Show trace chain

Chain up to the top parents and down to evidence, with depth, gaps (also a requirement without a parent) and cycles; one page of nodes at a time, total counts all.

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

Input

Field	Type	Required	Description
ref	elementRef	yes	UUID, short ID or identifier (e.g. SR-036), any case; several matches give ref.ambiguous.
direction	one of "up", "down", "both"	no	Default: "both".
view	view	no	core, a variant ID, or absent for all. A variant’s view: the core requirements it neither excludes nor replaces, plus those valid for it; elements without validity property are in every view (SR-043).
maxDepth	integer	no
limit	integer	no	Nodes of the page; total counts all. The walk is always complete: depth, gaps, cycles and incomplete are those of the whole chain (spec-frage #290). Every page walks the whole chain again; to step through a chain, ask with maxDepth instead. Default: 200.
offset	integer	no	Nodes skipped before the page, in the order of nodes (the root, then the parents level by level, then the children level by level). Default: 0.

Output

Field	Type	Required	Description
root	uuid	yes	Element ID: random UUID version 4, lower case, never changes (D-017, SR-002).
nodes	array of object	yes	Every element of the chain once per direction, at its shortest depth (SR-022 AK1, AK2): the root first, then the parents level by level, then the children level by level. An element reached again (a diamond, a cycle) is not repeated; its edge is in edges (SR-022 AK4). In a view, only the elements the view holds (SR-040, SR-043: not a core requirement the variant excludes or replaces, nor what hangs only below it); the root always. An element is named by its UUID and repository (D-058); two files of one repository with the same UUID (SR-088) are two nodes, told apart only by file, and edges and gaps name both the same way. Only the page of limit nodes from offset (in this order) is listed; total counts every node. A chain can be large (in a workspace of 50,000 elements and 200,000 relations up to about 42,000 nodes): a client asks for the first page and further ones as needed (SR-082 AK4, spec-frage #290), or shows it step by step with maxDepth 1 and asks again below an element that is not expanded.
nodes[].id	uuid	yes	Element ID: random UUID version 4, lower case, never changes (D-017, SR-002).
nodes[].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).
nodes[].identifier	string	no	Its identifier (the value of its property with the meaning identifier, such as SR-036, #305), for display next to shortId; left out when it has none.
nodes[].type	string	yes
nodes[].title	string	yes
nodes[].status	string	no
nodes[].repository	string	yes
nodes[].file	string	yes	Path relative to the repository.
nodes[].depth	integer	yes	Steps from the root: 0 for the root, 1 for its parents or children, and so on.
nodes[].direction	one of "up", "down"	no	up for a parent (and its parents), down for a child (and its children); left out for the root.
nodes[].expanded	boolean	yes	Its parents or children were looked at; false only at maxDepth, where the chain was cut.
total	integer	yes	The number of all nodes of the chain; nodes holds the page of limit from offset.
edges	array of object	yes	Every derivation relation the chain followed, from the child that stores it (source) to its parent (target, ADR-0004): the upward ones, then the downward ones, in the order they were followed. Paged with the nodes: an edge is listed on the page of the node it leads to in its walk (upwards the parent, downwards the child), so every edge is on exactly one page.
edges[].source	uuid	yes	Element ID: random UUID version 4, lower case, never changes (D-017, SR-002).
edges[].sourceRepository	string	yes	Workspace name of the repository of source.
edges[].target	uuid	yes	Element ID: random UUID version 4, lower case, never changes (D-017, SR-002).
edges[].targetRepository	string	yes	Workspace name of the repository of target.
edges[].kind	key	yes	Key of the relation kind with the meaning derivation (SR-013).
edges[].direction	one of "up", "down"	yes
edges[].cyclic	boolean	yes	Both ends lie in one cycle of derivations (SR-022 AK4).
gaps	array of object	yes	The gaps of the chain, in the order of nodes (the no-parent gaps of the upward chain first, the root’s among them, then those of the downward chain), only those of the nodes of the page. Downward (SR-022 AK3), only for elements whose children were looked at (expanded): no-child for a need without a child, no-evidence for a requirement without a child and without evidence. Upward (SR-022 AK5), only for elements whose parents were looked at, so not with direction: down: no-parent for a requirement that names no parent through a relation kind with the meaning derivation, whatever the view and the state of the target (a parent in a repository that is not here is one); the metamodel says which kinds derive, so in the standard model a requirement based only on a decision (based-on) has the gap. workspace.check reports the same elements (trace.no-parent). no-evidence: the element has no verification record in view, in the core without view (as evidence.coverage and the filter condition verification; any version and result, spec question #527 Q3), so without view a requirement verified only for a variant shows its records in evidence and still has the gap (spec question #527 Q4). A test case that was only skipped does not close the gap.
gaps[].id	uuid	yes	Element ID: random UUID version 4, lower case, never changes (D-017, SR-002).
gaps[].repository	string	yes	Workspace name of the repository of the element with the gap.
gaps[].kind	one of "no-child", "no-evidence", "no-parent"	yes
evidence	array of object	yes	The evidence (Nachweise) of the downward chain (SR-022 AK1, SR-033 AK1 to AK3), in the order of nodes, only for the nodes of the page whose children were looked at (expanded), paged like gaps; one item per element that has any, none with direction up. Only verification records (D-007: the chain ends at the Nachweise; validation records are in evidence.list). With view only the records that hold in it (SR-047: the core the records without a variant, a variant those for it); without view every record, each with its variant, as evidence.list. A test case all of whose executions of the element hold in another view is left out; a test case that was only skipped shows in every view. The Beleg of a record is its evidence; a JUnit execution has none, its Beleg is its record file (repository, file, line; D-007: for automatic tests the record is the result file). Belege are text and never opened.
evidence[].id	uuid	yes	The element of the chain the evidence belongs to.
evidence[].repository	string	yes	Workspace name of the repository of that element.
evidence[].depth	integer	yes	The element’s depth plus one: the evidence is one level below it (SR-022 AK1).
evidence[].testCases	array of testCase	yes	The test cases that name the element (SR-033), by class name, then name, each with the element’s own executions newest first (elements names every element the test case names, SR-033 AK2); executed false for a test case that was only skipped (SR-033 AK3).
evidence[].records	array of evidenceRecord	yes	Unlike evidence.list records: only the element’s records without a test case (inspection, analysis, demonstration, manual records without test-case), newest first.
unresolved	array of object	yes	Derivation relations the chain could not follow (SR-006 AK1, SR-088, SR-089): upwards a parent that is not available, downwards a child whose relation points at a UUID several files of the repository share. The other end is shown by its short ID only when it is not available (prefix UNKNOWN when its repository is not on this machine). A parent whose id is no UUID is not listed (the value-kind check reports it, SR-085); in a repository that is not here it still makes the chain incomplete. Only those of the nodes of the page (from).
unresolved[].direction	one of "up", "down"	yes
unresolved[].from	uuid	yes	The element of the chain whose parents or children were looked at.
unresolved[].fromRepository	string	yes	Workspace name of the repository of from.
unresolved[].kind	key	yes	Fixed metamodel key of a type, property, relation kind or status value. Readable English, lower case, dashes (D-043, SR-010 AK2).
unresolved[].id	uuid	yes	The other end: the parent the relation names (up), the child that stores it (down).
unresolved[].shortId	shortId	no	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).
unresolved[].identifier	string	no	Identifier of the other end (#305), when it is available and has one.
unresolved[].title	string	no
unresolved[].targetState	one of "inaccessible", "missing", "ambiguous", "unknown-repository"	yes	As in data-export.schema.json#/$defs/relation; downwards always ambiguous (the element the child points at).
incomplete	incomplete	yes	True when a part of the chain lies in a repository that is not on this machine (SR-006 AK2), in the view of a variant while a repository of the workspace is not on this machine (it may hold a replacement or an exclusion), or, when the chain goes down, an evidence location does: evidence there is not seen.
problems	array of problem	yes	Hints: trace.cycle once per cycle of derivations in the chain, naming its elements (SR-022 AK4); metamodel.meaning-unassigned when no type has the meaning need or requirement, so those gaps cannot be found (SR-013 AK3; upward only requirement). The hints are those of the whole chain, on every page.

App

In the command prompt (Ctrl+Shift+P, macOS ⌘⇧P): the command Show trace chain.

CLI

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

Usage: reqseq trace chain <ref> [options]

Chain up to the top parents and down to evidence, with depth, gaps (also a
requirement without a parent) and cycles; one page of nodes at a time, total
counts all.

Options:
  --ref <value>           instead of the argument <ref>
  --direction <value>     one of: up, down, both; default: "both"
  --view <value>
  --max-depth <number>
  --limit <number>        Nodes of the page; total counts all. The walk is
                          always complete: depth, gaps, cycles and incomplete
                          are those of the whole chain (spec-frage #290). Every
                          page walks the whole chain again; to step through a
                          chain, ask with `maxDepth` instead. default: 200
  --offset <number>       Nodes skipped before the page, in the order of `nodes`
                          (the root, then the parents level by level, then the
                          children level by level). 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

API

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

MCP

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