query

Perform searches on system metadata objects and their relationships.

Usage: <system> query <table> [filters...]

required arguments:

table

The type of object/relationship to query, must be one of components, component-relationships, files, file-relationships, entities, or entity-relationships.

optional arguments:

filters...

One or more filters to filter the results by. See Basic Filters and Filter and Field Reference by Table below for more information.

Basic Filters

Filters are a comma separated list of literal values or wildcard expressions matched against fields of the same name. Filter values are combined using or semantics, whereas multiple filters are combined using and semantics.

For example, the query:

> system query component-relationships --from-component a,b --to-component c,d

would match the component relationships “from a to c”, “from b to c”, “from a to d”, and “from b to d”.

Query Chaining

Multiple queries may be chained together by feeding fields from previous results into filters of a given query. This allows for advanced queries that traverse different types of objects or relationships in the system. For example, a query to retrieve file relationships that are involved in violations at the component level would be:

> system query component-relationships --severity error
> system query file-relationships --from-component @from_component --to-component @to_component

The @<field-name> operator specifies that the unique values from a given field in the previous query are to be used in the current query as a series of literal match filters. When multiple chained filters are combined, matches are performed row-by-row. This means that a given object or relationship will only be returned if it matches all chained fields in a given row. For example, if the above query for component relationships returned two relationships:

From A to B
From B to C

Then, in the query on file-relationships, only file relationships from components A to B, and B to C would be returned.

Filters containing chained fields and filters containing values are combined with and semantics. For example, to reduce the results of the above file-relationships query by erroneous file relationships:

> system query component-relationships --severity error
> system query file-relationships --from-component @from_component --to-component @to_component --severity error

Chained fields cannot be combined with values in the same filter. For example, a filter of --from-component @from_component,a is invalid.

The CLI will interpret any values starting with @ as chained fields. To specify a filter value starting with a literal @, escape the @ at the beginning of the value with a backslash (\):

> system query files --name \@sources.js

Filter and Field Reference by Table

components

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

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

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.

Please note that this command 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.

file-relationships

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

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

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.

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.