scenario

Overview

Provides a set of commands for managing and importing data into various “named scenarios”. A named scenario is a modified snapshot of a provided code-base with user defined exclusions and additional manual dependencies. Scenarios can be used to generate reports of theoretical states of the codebase that are isolated from original data. This is useful for estimating the outcome of modifications on a codebase’s economic metrics.

To run a scenario-based report, use produce_reports with the --scenario option.

For more information about jobs see the job command.

Technical Health Improvement Plan

Scenarios may be used in conjunction with the Technical Health Improvement Plan (THIP) in order to estimate the outcome steps across one of more cores in the provided codebase. The recommended workflow is as follows:

Create an initial Technical Health Improvement Plan (THIP).
Use the THIP command-line interface (see system thip) to refine the plan by prioritizing and excluding steps.
Once done, import either all steps or a selected set of steps into a scenario using system scenario import --source thip. See the command reference below for more information about selectively importing steps.
At this point, you may open the scenario-specific user-defined architecture (UDA) file and add additional dependencies, or additional exclusions.
Run produce reports --scenario to produce scenario-specific reports. These reports will include the differences between the base system, and scenario.

Working with User-Defined Architecture (UDA)

User-defined architecture (UDA) is a flexible format for specifying codebase architecture such as components, custom file attributes, manual dependencies, and dependency exclusions. Scenarios use a subset of the User Defined Architecture to define file-level dependency additions and exclusions.

UDA files consist of 3 main sections:

properties: Where file attributes such as components, and custom properties are defined.
rules: Where system-level architectural rules are defined.
groups: Where additional dependencies and dependency exclusions are defined.

For the purpose of defining additional dependencies and exclusions, we will be working with the groups section.

Adding a dependency

In order to add a connection between one-or-more files, create a new group entry with the following format:

{
  "assignments": [
    {
      "subject": {"type": "file"},
      "group": [
        {"type": "inclusion",  "matchers": {"name": {"match": ["src/file_a.c"]}}}
      ]
    }
  ],
  "dependencies": [
    {
      "subject": {"type": "file"},
      "group": [
        {"type": "inclusion",  "matchers": {"name": {"match": ["src/file_b.c", "src/file_c.c"]}}}
      ]
    }
  ]
}

This will create connections from src/file_a.c to the files src/file_b.c and src/file_c.c.

Excluding Dependencies

To exclude dependencies from the network, the process is is similar to adding a dependency inclusion, except for the dependency_handling property. Dependency handling tells CodeMRI how to process the group, in this case, CodeMRI will exclude the group. Unlike additional dependencies, exclusions may contain wildcard expressions. Here is an example:

{
  "assignments": [
    {
      "subject": {"type": "file"},
      "group": [
        {"type": "inclusion",  "matchers": {"name": {"match": ["src/file_a.c"]}}}
      ]
    }
  ],
  "dependencies": [
    {
      "subject": {"type": "file"},
      "group": [
        {"type": "inclusion",  "matchers": {"name": {"match": ["src/include/internal_*.h"]}}}
      ],
      "dependency_handling": "exclusion"
    }
  ]
}

The above example will exclude all connections from src/file_a.c to src/include/internal_*.h.

In the case of conflicting exclusions and inclusions, exclusions will take precedence.

Sub-Commands

import