CodeMRI - Cheat Sheet

Owned by Dan Sturtevant
Last updated: Aug 19, 2023
8 min read

Basic Setup and Administration

CodeMRI maintains separate directories for installation and data.

The installation directory is defined during setup and contains files related to the execution of CodeMRI.

The data directory is called a “vault”. This is the main workspace where CodeMRI stores data on the codebases being analyzed and configuration information related to those codebases.

Understanding CodeMRI Command Execution

CodeMRI executes through a series of statements issued in a Command Line Interface (CLI), such as DOS or Bash. Commands are in the following format:

cmri <command> --vault </path/to/vault> -or- cd <path/to/vault/myvault> cmri <command>

 

Alternatively, CodeMRI commands can be issued via the CodeMRI Shell which can be activated as follows:

cmri shell --vault <path/to/vault> -or- cd <path/to/vault> cmri shell

Once the shell is active, commands are in the following format:

<command>

The shell recognizes that all commands are CodeMRI commands, and recognizes the users vault location. The “cmri” keyword is no longer necessary, and the “-vault </path/to/vault>” parameter is no longer necessary. Commands execute quicker in the shell as the CLI overhead is reduced.

For more information on the CLI and the Shell, see https://silverthread.atlassian.net/wiki/spaces/CKB/pages/2534244356

Understanding CodeMRI data structures (vaults, projects, systems)

CodeMRI uses multiple layers of virtual containers to store data (configuration, metadata, analysis) about codebases being scanned. These layers can best be visualized as boxes that contain other boxes.

The outer-most box is a vault.

  • A vault is the main CodeMRI workspace.

  • A user can create multiple vaults.

Inside of a vault are “project” boxes.

  • There can be 1-n projects in a vault.

Inside of a project box are “system” boxes.

  • There can be 1-n systems in a project.

  • A system points to a directory location that contains a codebase.

  • A system maintains the current snapshot of data.

  • Each system may represent a snapshot in time of scan data. To do this, you may set a “revision_date” property for each system in the project.

  • Note: revision_date is currently only used in the Web Platform Trending displays and in KPI output. All other output references the current snapshot that is maintained at the “system box” level.

Create a vault

Use a vault - being in the vault directory

Use a vault - with a command line flag

Use a vault - by setting environment variables

Set the CMRI_VAULT environment variable to point to your vault.

We also recommend you automate this to increase the efficiency of your workflow

  • Linux: Add this to your BASH/ZSH/*.SH profile

  • Windows: We recommend setting the user environment variables

Help Commands

See command listing and invocation help

This will show all of the commands available to you, as well as provide information about scripting.

See a summary of all jobs available at the CLI.

Note that jobs are still subject to licensing.

Call up more detailed help for a particular job.

Licensing

Acquire and Install License (Online mode - Typical)

Silverthread will create an account for http://codemri.com. Your login will be your email address. Set your password.

If you are on a LINUX command line prompt:

If you are on a WINDOWS command line prompt:

If you are in the CMRI INTERACTIVE SHELL

Result:

NOTE: must be logged in to account in order to generate CodeMRI reports.

Acquire and Install License (Offline mode - Classified Systems)

  • Forward the ID file that gets generated to Silverthread

  • receive a license file back

  • Store file in C:\Program Files\Silverthread

Define Projects and Systems

Create a project

Delete a project

Create a system

Delete a system

View vault content

Select Projects and Systems

Select projects and systems for operations and jobs.

See select --help for more information about selection.

Deselect projects and systems for operations and jobs.

View vault selection state

Produce Reports

NOTE: must be logged in to account in order to generate CodeMRI reports.

Generate diagnostic reports

Create CodeMRI® Health Diagnostic reports for selected systems

Generate portfolio reports

Create a CodeMRI® Portfolio report for selected systems

Generate Technical Health Improvement Plan (THIP) reports

Generate THIP report

Create a CodeMRI® Technical Health Improvement Plan (THIP) report for selected systems

NOTE: THIP only considers file cores above the 150-file threshold by default.

To set the threshold higher or lower, add the optional parameter:

List all the THIP cores in a specific language

List all the THIP steps for a specific core

  • THIP NOTE: This lists steps for the provided language/core combination along with the following base metrics about the provided steps

  • STEP: The step number used ito reference the step in operations

  • FROM FILE: The file originiating the relationships to cut

  • TO FILE: The file containing referenced entities in the relationships to cut

  • ENTITIES MODIFIED: The number of entity relationships to cut

  • CORE SIZE: The core size after the provided step and all previous steps are completed

  • PRIORITY: True if the step is prioritized, otherwise false

  • EXCLUDED: True if the step will be removed next time produce_thip is run, otherwise false

Prioritize THIP Steps

Exclude THIP Steps

Define File Attributes

 

NOTE: When setting the following customizable file attributes:

  • Select the system that owns the file whose attribute is being set

  • Using the “system file-property add” command, the “-e” parameter is a relative path (the file path is listed in relation to the system path)

    • For example:

      • if a system path = /home/my_user/my_project/my_system

      • and a file path = /home/my_user/my_project/my_system/src/my_file.java

      • then the relative file path (relative to the system path) = src/my_file.java

Flag a system directory as test code

Flag a system directory as third party

Flag a system directory as generated code

Flag a system directory as excluded

Define Codebase Architecture (Components and Blueprints)

IMPORTANT: Ensure that the relative paths used for the --expressions flag match the relative paths in the CodeMRI reports. If unsure, run job run produce_reports and open any one of the reports to find the File List containing relative paths.

Create a component

Remove a component

NOTE: Expressions are relative paths (relative to the system path) that must include standard * wildcard expressions. See https://silverthread.atlassian.net/wiki/spaces/CKB/pages/2377384003 for more information defining and controlling the architecture.

Component Usage

The Create Component command can be repeated multiple times for the same component with different paths to build the component.

 

The Create Component and Remove Component commands can be used together to extract components from within other components.

 

Declare component relationships

  • creates A-->B, A-->C, A-->... relationships

  • IMPORTANT: no space after commas

Verify component definition

View a listing of component names, expressions, and file counts for each component.

List all of the declared component relationships in a tabular format

Regenerate the Silverthread Database containing the updated component information.

View information about files within a given component.

Produce reports with component data

Produce diagrams with component data

NOTE: CodeMRI detects relationships between file, and hence detects relationships between components. API diagrams will show defined and undefined relationships between components. This is a useful feature to help discover the design in an undocumented (or partially documented) architecture.

Produce diagrams with selected component data

CodeMRI is capable of generating API diagrams comprised of selected components.

CodeMRI will accept a list of components in the command line:

CodeMRI will also accept a file that contains the selected components:

See https://silverthread.atlassian.net/wiki/spaces/CKB/pages/2595323915 for more details!

 

Generate Key Performance Indicator (KPI) Data

KPI Ability

CodeMRI can generate a KPI data report based on KPI input data and a codebase(s) to derive KPI’s from.

KPI Input

CodeMRI accepts a file in YAML format that specifies (1-n) KPI definitions and/or metrics.

To see all available values for “MetricName”:

 

KPI CLI Commands

Once a YAML file has been created with the desired KPIs and/or Metrics, KPI reports can be generated with the following steps:

 

KPI Output Report

As a result of running the create_kpi_worksheet job, CodeMRI will generate a KPI report in Excel (.xlsx) format. The KPI Report spreadsheet will be exported to the root directory of your vault. The report contains multiple tabbed sheets displaying complete overview data and detailed percentage/detailed quantity data presentations for both KPIs and Metrics (as some data is collected as a percentage and some is collected as a “count”, percentage and quantity data has been separated for the purposes of displaying data as a chart)

Detailed sheets contain pivot tables of grouped data, along with charts and slicers to better visualize and customize the presentation.

 

Export data for use on another computer

Generate Metadata

Generate Anonymized Metadata

Anonymize data to mask sensitive information (if desired). You must run produce_silverthread_database first. If you want to generate un-anonymized reports, run produce_reports prior to anonymization. Anonymization is reversible via job clean anonymize_database.