Show traceability matrix

Traceability matrix of a selection: one row per element in list order, one column per relation kind and direction that occurs, each cell the elements at the other end with outdated and missing marks; per column how many rows have a link. One page of rows at a time. With evidence locations also each requirement’s test cases and verification status, and the degree.

Command trace.matrix. Reads the workspace and changes no file.

Input

Field	Type	Required	Description
`selection`	`selection`	no	The rows: every element the selection selects, as `element.list` selects them (every part given must hold, SR-101 AK2). In a variant view (`selection.view`, or the view of the saved filter) a link whose other end the view does not hold (SR-040, SR-043: also a core requirement the variant excludes or replaces) is left out of the cells and the counts, as `trace.neighbourhood` leaves it out of its walk.
`sort`	array of `sortKey`	no	As in `element.list`: the rows are in the order `element.list` gives for the same `selection` and `sort` (SR-125 AK1). Without `sort`, the sort of the saved filter in `selection.filter`. `hierarchy` first makes the rows the derivation tree and gives each row its `depth`.
`kinds`	array of `key`	no	Keys of the relation kinds or of properties of kind `relation` (such as `packages`) to make columns of. An unknown key is `input.invalid`. Without `kinds`, the columns are the relation kinds of the metamodel (Beziehungsarten, D-043, D-037): relation properties such as the package and the validity are their own built-in meanings (D-012) and form a column only when named here; inline references are no relation kind and never form a column.
`limit`	`integer`	no	Rows of the page; `total` counts all. Default: `200`.
`offset`	`integer`	no	Rows skipped before the page, in the order of the list. Default: `0`.

Output

Field	Type	Required	Description
`columns`	array of `object`	yes	One column per relation kind and direction that occurs in the whole selection (SR-125 AK2), not only on the page: a kind or direction no row has makes no column. Order: relation kinds in the order of the metamodel, then properties of kind `relation` in property order; per key `out` before `in`. `type` says what a column holds and so the shape of its cells; every column is `relation`. The evidence columns (SR-126) are no column type: their header is `evidence` and their cells are `rows[].testCases` and `rows[].verification`, so a reader of `columns` and `cells` needs no other shape.
`columns[].type`	one of `"relation"`	yes	The column holds relations: its cell in each row is an array of relations (`data-export#/$defs/relation`) of `kind` and `direction`. The evidence columns of SR-126 are `evidence`, `rows[].testCases` and `rows[].verification`, not a column type.
`columns[].kind`	`key`	yes	Key of the relation kind, or of the property of kind `relation`.
`columns[].property`	`true`	no	`kind` is the key of a property of kind `relation`, not of a relation kind.
`columns[].meaning`	one of `"derivation"`, `"replacement"`, `"succession"`, `"exclusion"`	no	The meaning of the relation kind; left out for a kind without a meaning and for a property.
`columns[].direction`	one of `"out"`, `"in"`	yes	`out`: the relations the row element’s file stores. `in`: the relations of other elements that point at it.
`columns[].name`	`string`	yes	For `out`, the `name` of the kind (e.g. Derives from); for `in`, its `inverse-name` (e.g. Derived by), the `name` when it has none. A name can be the same for both directions (Distinct from): `direction` tells them apart.
`columns[].count`	`integer`	yes	How many rows of the whole selection have at least one relation in this column (SR-125 AK3), whatever state its other end is in; a relation to a missing target counts. With a view, the relations the cells show.
`columns[].share`	`number`	yes	`count` divided by `total`: the share of the rows of the whole selection.
`rows`	array of `object`	yes	The page: one row per element of the list, in its order (SR-125 AK1).
`rows[].id`	`uuid`	yes	Element ID: random UUID version 4, lower case, never changes (D-017, SR-002).
`rows[].repository`	`string`	yes	Workspace name of the repository of the element.
`rows[].shortId`	`shortId`	yes	Display ID: type prefix, dash, the trailing hex characters of the UUID with dashes removed, at least 6, more until unique in the workspace (D-017, SR-002 AK3). The file name uses 12 (D-056).
`rows[].identifier`	`string`	no	Its identifier (the value of its property with the meaning `identifier`, such as SR-036), for display next to `shortId`; left out when it has none.
`rows[].type`	`string`	yes
`rows[].status`	`string`	no
`rows[].title`	`string`	yes
`rows[].file`	`string`	yes	Path relative to the repository.
`rows[].depth`	`integer`	no	Only when `sort` starts with `hierarchy`: the depth of the element in the derivation tree, as `element.list` gives it in `tree`.
`rows[].testCases`	array of `object`	no	SR-126 AK1, AK2: only with `evidence`, on a row whose type has the meaning `requirement` and that applies in its view. The test cases that name the requirement, with their verification executions that hold in the view of `evidence` (`trace.chain` shows the same test cases in the same view), by class name then name; an empty array when it has none: a gap (AK2). Records without a test case (inspection, analysis, a manual record without `test-case`) are not here; they count for `verification` only (spec question #528 Q3). The chain and `evidence.list` give every execution.
`rows[].testCases[].name`	`string`	yes	The JUnit `name`, or the `test-case` of the Markdown records.
`rows[].testCases[].className`	`string`	no	The JUnit `classname`; left out for a test case of Markdown records.
`rows[].testCases[].executed`	`boolean`	yes	The test case has at least one execution of this requirement in the view (SR-033 AK3).
`rows[].testCases[].last`	`evidenceRecord`	no	The last execution (letzte Durchführung): the newest execution of this requirement in the view, of any version, with result, date, item and version; its record file (`repository`, `file`, `line`) is the Beleg of a JUnit execution. Left out when `executed` is false.
`rows[].testCases[].mark`	one of `"not-executed"`, `"outdated"`, `"failed"`	no	How the cell is marked (AK2; spec questions #528 Q1, Q2 and #593 Q2), the first that holds: `not-executed` when `executed` is false; `outdated` when `last` is of another version than the requirement’s current one, or its current version is not known; `failed` when `last` failed. Left out when the last execution passed for the current version.
`rows[].verification`	array of `verificationEntry`	no	SR-126 AK1, AK3: only with `evidence`, on a row whose type has the meaning `requirement` and that applies in its view. Its verification status in the view of `evidence`, one entry, the same as `element.get` and `evidence.status` give for that view: `indirect` when it is verified through its children (AK3).
`rows[].cells`	array of array of `relation`	yes	One cell per entry of `columns`, in the same order; a cell takes its shape from the type of its column. For `relation`, an array of the relations of the row element in the column’s `kind` and `direction`, each with `shortId` and `title` of the other end when it is available (SR-125 AK2), and an empty array when it has none: a gap (AK3). Outgoing relations come in the order of the file, incoming ones in the order of the incoming index (store order). A relation to an older version of its target is `outdated`, one to a target that is not there has `targetState: "missing"` (SR-125 AK4); for an incoming relation, `outdated` means its source stores an older version of the row element and `currentVersion` is the row element’s.
`total`	`integer`	yes	The number of rows of the whole selection.
`incomplete`	`incomplete`	yes	The selection is incomplete (SR-006 AK2), or the workspace file lists a repository that is not on this machine: relations of elements there that point at a row cannot be seen, and its elements may belong to the selection. With `evidence`, also when an evidence location lies in such a repository: its records are not seen (SR-006 AK2).
`evidence`	`object`	no	The header of the evidence columns (SR-126): given when the workspace file names an evidence location, the metamodel is valid and the selection holds an element whose type has the meaning `requirement` (spec question #593 Q1); then every requirement row of the page that applies in `view` has `testCases` and `verification`. Other rows have neither (a requirement valid only in variants, without a view): not applicable, no gap. Left out otherwise, and the output is the one of SR-125.
`evidence.view`	`viewId`	yes	The one view of the test cases, the status and the degree: the selection’s view, else its saved filter’s, else the core (as `evidence.degree`; spec questions #593, #592 Q1). `element.get` and `evidence.status` give every view.
`evidence.degree`	`verificationDegree`	yes	SR-126 AK4: the verification degree of the whole selection in `view`, with the count per status, not of the page only; the same as `evidence.degree` gives for the same selection (SR-037).
`names`	array of `elementName`	no	The elements that `evidence` and the rows’ `verification` name by UUID only, each once in the order first named: the variant of the view and the missing children (`missingChildren`), so a reader names them by short ID, identifier and title (#588). Left out when they name none.

App

In the command prompt (Ctrl+Shift+P, macOS ⌘⇧P): the action Show traceability matrix. Key: Ctrl+T (macOS ⌘T).

CLI

reqseq trace matrix, with --json for the output as JSON. Its help:

Usage: reqseq trace matrix [options]

Traceability matrix of a selection: one row per element in list order, one
column per relation kind and direction that occurs, each cell the elements at
the other end with outdated and missing marks; per column how many rows have a
link. One page of rows at a time. With evidence locations also each
requirement's test cases and verification status, and the degree.

Options:
  --kinds <value>         Keys of the relation kinds or of properties of kind
                          `relation` (such as `packages`) to make columns of. An
                          unknown key is `input.invalid`. Without `kinds`, the
                          columns are the relation kinds of the metamodel
                          (Beziehungsarten, D-043, D-037): relation properties
                          such as the package and the validity are their own
                          built-in meanings (D-012) and form a column only when
                          named here; inline references are no relation kind and
                          never form a column. repeatable
  --limit <number>        Rows of the page; `total` counts all. default: 200
  --offset <number>       Rows skipped before the page, in the order of the
                          list. default: 0
  --input <json|@file|->  command input as JSON: inline, from a file, or from
                          standard input
  --workspace <path>      workspace root (default: nearest folder upwards with
                          reqseq-workspace.yaml)
  --json                  print exactly the command output as JSON
  --yaml                  print the whole command output as YAML, problems one
                          per line
  -h, --help              show help

Only via --input: selection, sort

API

POST /v1/commands/trace.matrix on the local API (reqseq serve api), with the input as the JSON body; the answer is the output.

MCP

Tool trace_matrix of the MCP server (reqseq mcp), with the input as its arguments.