CodeMRI Query Interface Tutorial

Owned by Brandon Smith, created
Last updated: Jul 14, 2023
11 min read

Table of Contents

Preface

If you haven’t already, please reference the installation guide. Depending on your OS, either use the Installing CodeMRI on Windows or Installing CodeMRI on Linux.

Defining Components and Component Relationships

The next critical step before beginning to query is to define both components and their relationships. For guidance on how to define these, reference the Defining Codebase Architecture section of the CLI Cheat Sheet.

The granularity of components is up to your discretion, as you have the best knowledge of your codebase. As a general rule, components should be defined as directories or files that have contained logic and functionality. For example, a util directory that contains widely used utility functions would be a good choice for a defined component. An API directory that contains all of your APIs may be better served being split at the file level if the APIs are unrelated. An API with logic for managing user info may be in the same directory as an API for running database queries, but they will likely not share much logic. In that case, separate components for a UserAPI and DatabaseAPI will give a better system picture.

Component Relationships are also defined at your discretion. Think of them as an “ideal” view of your architecture. CodeMRI will run its own analysis of the connections and relationships between your components, and show you any discrepancies between what it finds and what you have defined.

Generate Query Data

Once the components are defined, you are almost ready to begin querying. If you attempt to query at this point you will see a message that reads:

The query failed due to an error. Run `generate_query_data`, then retry your query. If the query continues to fail, contact Silverthread for support.

Use job run generate_query_data, and you’re ready to start.

Querying

In order to query components, component relationships, files, or file relationships, you will need the names of components or files. Component names are user-defined, while file and entity names are collected by CodeMRI.

Components

List components Additional command info

The NAME column should be used for querying

system component list SYSTEM NAME EXPRESSIONS FILE COUNT linux/linux-1.0 boot linux/boot/* 2 linux/linux-1.0 fs linux/fs/* 19 ...

Query components

system query components --name kernel ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- name kernel file_count 13 fan_in 5 fan_out 5 files_in_cyclic_group 10

Filters:

--name

The name of the component. May include wildcard expressions.

Fields:

name

The name of the component.

file_count

The number of files inside the component.

fan_in

How many components directly depend on the component.

fan_out

How many components are directly depended on by the component.

files_in_cyclic_group

The number of files within the component that are members of a cyclic group. A cyclic group is a group of files that are, either directly or indirectly, circularly dependent upon each other.

Component Relationships

List component relationships Additional command info

Query component relationships

system query component-relationship requires --from-component and --to-component flags:

Filters:

--from-component

The component that uses the to_component. May include wildcard expressions.

--to-component

The component used by the from_component. May include wildcard expressions.

--relationship-type

The type of relationship between the components. Must be one or more of: actual_dependency, declared_dependency.

--relationship-state

The state of the relationship between the components. Must be one or more of: ok, circular, undeclared, missing.

--severity

A coarse indicator of the level of attention to pay to a given relationship. Must be one or more of: info, warning, error.

Fields:

from_component

The component that uses the to_component.

to_component

The component used by the from_component.

relationship_type

The type of relationship between the components. See Component Relationship Types for more information.

relationship_state

The state of the relationship as determined by CodeMRI. See Relationship States for more information.

severity

A coarse indicator of the level of attention to pay to a given relationship. See query#Severities for more information.

file_relationships

The number of files involved in the given component relationship. Will be nan or null for declared dependencies.

entity_relationships

The number of entities involved in the given component relationship. Will have a value of nan or null for declared dependencies.

Files

Querying may display files not present in the reports. CodeMRI removes files deemed “isolates” from reports. A file is an “isolate” if:

  • it does not depend on any other files.

  • no other files depend on it.

List files Additional command info

Query files

system query files drops the appended linux/ in the --name flag. For example:

Filters:

--name

The relative path of the file. May include wildcard expressions.

--component

The component in which the file resides. May include wildcard expressions.

--property-<property name>

Restrict the search to files assigned to the given list of files tagged with the provided list of file property / value combinations. At time of writing, the only recognized value for file properties is true. All values other than true will be treated as false.

--language

The programming language of the file, as detected by static analysis. May include wildcard expressions.

--complexity-class

 

 

The McCabe complexity class of the file. Must be one of the following:

  • NA: Complexity is either not available or 0.

  • Low: Complexity is between the Low and Medium thresholds.

  • Medium: Complexity is between the Medium and High thresholds.

  • High: Complexity is between the High and Very High thresholds.

  • Very High: Complexity is above the Very High threshold, the file is considered too complex to reasonably test or maintain. This value must be quoted as it contains a space.

--connected-to-file

Restrict search to files indirectly dependent upon a given file or set of files matching the given expression.

Fields:

name

The relative path of the file.

component

The component the file resides in. nan if the file is not assigned to a component.

language

The programming language of this file detected by static analysis.

entity_count

The number of entities contained in this file.

fan_in

The number of files that directly depend on this file.

fan_out

The number of files this file directly depends on.

in_cyclic_group

True if the file is part of a group of circularly dependent files, else False.

cyclic_group_id

The ID of the cyclic group this file is part of. 0 if the file is not part of a cyclic group.

cyclic_group_size

The size, in files, of the cyclic group this file belongs to.

complexity_class

A simplified representation of the complexity of this file.

max_cyclomatic_modified

The cyclomatic complexity of this file.

count_line_code

The number of source lines within the file.

ratio_comment_to_code

The ratio of comment lines to source lines within this file.

property.*

Property values assigned to the given file.

File Relationships

File relationships are _____________

List file relationships

Query file relationships

system query file_relationship uses --from-file and --to-file flags

Filters:

--from-file

The name of file that uses the to_file. May include wildcard expressions.

--to-file

The name of the file used by the from_file. May include wildcard expressions.

--from-component

The component containing the file that uses the to_file. May include wildcard expressions.

--to-component

The component containing the file used by the from_file. May include wildcard expressions.

-from-property-<property>

Files tagged with the file property matching the given property/value combination. At time of writing the only supported value is true, all other values will be treated as false.

-to-property-<property>

Files tagged with the file property matching the given property/value combination. At time of writing the only supported value is true, all other values will be treated as false.

--relationship-state

The state of the relationship between the files. Must be one or more of: ok, circular, constraint_violation.

--severity

A coarse indicator of the level of attention to pay to a given relationship. Must be one of: info, warning, error.

--connected-to-file

Restrict search to files indirectly dependent upon a given file or set of files matching the given expression.

--from-cyclic-group-id

The cyclic group ID of the file that uses the to_file.

--to-cyclic-group-id

The cyclic group ID of the file used by the from_file.

Fields:

from_file

The file that uses the to_file.

to_file

The file used by the from_file.

from_component

The component that uses the to_component.

to_component

The component used by the from_component.

from_property.*

Property values assigned to the file on the from side of the relationship.

to_property.*

Property values assigned to the file on the to side of the relationship.

relationship_state

The state of the relationship. See Relationship States for more information.

severity

A coarse indicator of the level of attention to pay to a given relationship. See query#Severities for more information.

entity_relationships

The number of entities involved in the given file relationship.

Entities

Entities are __

List entities

Query entities

Filters:

--name

The name of the entity. May include wildcard expressions.

--type

The type of the entity. May include wildcard expressions.

--file

The file the entity is contained in. May include wildcard expressions.

--component

The component the entity is contained in. May include wildcard expressions.

--language

The language of the file the entity is contained in. May include wildcard expressions.

--complexity-class

The McCabe complexity class of the file. Must be one of the following:

  • NA: Complexity is either not available or 0.

  • Low: Complexity is between the Low and Medium thresholds.

  • Medium: Complexity is between the Medium and High thresholds.

  • High: Complexity is between the High and Very High thresholds.

  • Very High: Complexity is above the Very High threshold, the file is considered too complex to reasonably test or maintain. This value must be quoted as it contains a space.

Fields:

name

The name of the entity.

type

The type of the entity. Please note that these types are not standardized across static analysis engines.

file

The relative path of the file that owns the entity.

component

The component that owns the entity. If the entity is not part of any component, this field will be blank.

in_cyclic_group

Whether the entity is in a group of entities that are circularly dependent on each other.

cyclic_group_id

The ID of the cyclic group the entity belongs to. Will be 0 if in_cyclic_group is False.

cyclic_group_size

The number of files in the cyclic group the entity belongs to. Will be 0 if in_cyclic_group is False.

language

The programming language the owning file was written in, as detected by the static analysis engine.

max_cyclomatic_modified

The McCabe complexity of the entity, as determined by static analysis. May not be valid for all entity types, will be -1 if not available for a given entity.

complexity_class

The McCabe complexity class of the entity, as determined by CodeMRI. May not be valid for all entity types, will be nan if not available for a given entity.

count_line_code

The number of lines of code (LOC) in the entity. May not be valid for all entity types, will be nan if not available for a given entity.

ratio_comment_to_code

The ratio of comment lines to source lines in the entity. May not be valid for all entity types, will be nan if not available for a given entity.

Entity Relationships

Entity relationships are ________________

List entity relationships

Query entity relationships

Filters:

--from-entity

The name of the entity that uses to_entity. May include wildcard expressions.

--to-entity

The name of the entity used by the from_entity. May include wildcard expressions.

--from-file

The file that owns the from_entity. May include wildcard expressions.

--to-file

The file that owns the to_entity. May include wildcard expressions.

--from-component

The name of the component that owns the from_file. May include wildcard expressions.

--to-component

The name of the component that owns the to_file. May include wildcard expressions.

--relationship-state

The state of the relationship between the from_file and to_file. Must be one of ok, circular, illegal, missing, or undeclared.

--severity

The weight of the relationship state. Can be overridden by the user. Must be one of info, warning, or error.

Fields:

from_entity

The name of the entity that depends directly on the to_entity.

to_entity

The name of the entity that the from_entity depends directly on.

from_file

The file that owns the from_entity.

to_file

The file that owns the to_entity.

ref_line

The line number in the from_file the to_entity was referenced from.

ref_col

The column in the ref_line the to_entity was reference from.

from_component

The name of the component that owns the from_file.

to_component

The name of the component that owns the to_file.

relationship_type

The type of the relationship between the from_entity and to_entity.

relationship_state

The state of the relationship between the from_entity and to_entity.

severity

A coarse indicator of the level of attention to pay to a given relationship. See query#Severities for more information.

Indexing

job run generate_query_data will automatically create indices to enhance the performance of your queries. This must be rebuilt following database updates to take effect.

Relationship States

Within a system, a given relationship may be in one or more “states”. Silverthread determines relationship states by looking at both user-supplied rules as well as the network of relationships within the codebase. At the time of writing, the possbile relationship states are:

ok

The relationship is not introducing cyclicality or violating any user-defined rules, if this is a component relationship, the relationship has been explicitly declared in user-defined architecture and is present within the codebase.

circular

This relationship forms part of a cycle, either directly or indirectly.

undeclared

This relationship is present in the codebase, but not in the user-defined architecture. Undeclared relationships may indicate signs of divergence from agreed upon architecture or gaps in documentation of codebase architecture.

illegal

This relationship is in direct violation of a user-defined rule.

missing

This relationship has been declared inside of the user-defined architecture, but is not present in the codebase.

constraint_violation

The relationship is in direct violation of one or more user-defined constraints. For more information about constraints see the system architecture command.

Component Relationship Types

Component relationships have multiple types:

actual_dependencies

component relationships that reside in the actual codebase.

declared_dependencies

component relationships provided by the user in user-defined architecture.

Severities

Severities provide a simple abstraction over relationship states for the purpose of checking a codebase for problems. Severities are initially computed by Silverthread, but may be overridden explicitly by applying user-defined rules. The levels of severity recognized by Silverthread are in the table below:

info

The state of the relationship is either ok, or if an error, it is something the user has elected to ignore.

warning

The relationship is problematic, but is not an immediate issue. Undeclared and missing component dependencies fall under this category. This also may be a circular or illegal relationship that the user has elected to ignore until a later time. It is common to mark pre-existing issues as warnings.

error

The relationship is an issue that deserves immediate attention. Circular and illegal dependencies fall under this category.