Show graph

The graph of one element: what its links lead to above it and what links to it below, to a depth, over the chosen kinds. Each element is one node with its level and marks, and each link between two nodes is one edge. At most limit nodes, nearest levels first.

Command trace.graph. 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.
`repository`	`string`	no	The workspace name of the repository of the element ref names, as in element.get (#255).
`maxDepth`	`integer`	no	The deepest level in each direction; 0: the element only. Omitted: 1 (the direct neighbours), unless `allLevels` is true.
`allLevels`	`boolean`	no	Go as far as the links go (the whole chain), within `limit`; not together with `maxDepth`. For the chain alone ask with `meanings: ["derivation"]`. Default: `false`.
`kinds`	array of `key`	no	Keys of relation kinds or of properties of kind `relation` (such as `packages`) to follow. An unknown key is `input.invalid`. See `meanings` for the filter rule.
`meanings`	array of one of `"derivation"`, `"replacement"`, `"succession"`, `"exclusion"`, `"reference"`	no	Relation kinds with these meanings are followed; `reference` stands for inline references. Without `kinds` and `meanings` every relation and reference is followed. Otherwise a link is followed when its key is in `kinds` or its meaning is in `meanings`; an empty list follows nothing.
`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).
`limit`	`integer`	no	The most nodes, the element included; the nearest levels first (`truncated` says when more exist). Default: `500`.

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 graph once: the element first, then level by level from the nearest (for each distance the elements above, then those below, each in the order the links were followed). An element reached both ways is one node at its smaller distance, above on a tie. In a view only the elements the view holds (SR-040, SR-043: not a core requirement the variant excludes or replaces); the element always. At most `limit` nodes.
`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[].expanded`	`boolean`	yes	Its links in the direction of its level (both for the element) were looked at and every element they lead to is a node. False at `maxDepth`, where `limit` stopped the walk, and when `limit` left out an element they lead to.
`nodes[].level`	`integer`	yes	0 for the element; -d for an element reached d steps up along the links the files store (its parents, the targets of its other relations and relation properties, its inline references), +d for one reached d steps down along links that point at it. The source of a link is placed below its target (ADR-0004).
`nodes[].marks`	array of one of `"outdated"`, `"superseded"`, `"no-evidence"`	yes	In this order, only those that hold (SR-111 AK4): `outdated`, the element stores an outdated relation, relation property or inline reference (SR-025, the `relation.outdated` and `variant.core-changed` hints of element.get), whatever kinds are followed; `superseded`, its status is one the metamodel marks invalid (D-044); `no-evidence`, the gap rule of trace.chain (SR-022 AK3): a requirement without a derivation child that applies in the view and without evidence, whatever depth is shown. Evidence records come in stage 4: until then every requirement without a child is `no-evidence`. Empty when none holds.
`edges`	array of `object`	yes	Every followed link from one node to another, also one the walks did not take (a link between two parents, or from a child to a parent): by source in the order of `nodes`, then in the order its file stores them (relations and relation properties in frontmatter order, then inline references). A link from an element to itself is no edge. Not listed: unresolved links (`element.get` and `workspace.check` report them).
`edges[].source`	`uuid`	yes	The element whose file stores the link.
`edges[].sourceRepository`	`string`	yes	Workspace name of the repository of `source`.
`edges[].target`	`uuid`	yes	The element the link points at (ADR-0004).
`edges[].targetRepository`	`string`	yes	Workspace name of the repository of `target`.
`edges[].link`	one of `"relation"`, `"reference"`	yes	A relation in the frontmatter or an inline reference in the text or in a property marked `markdown`.
`edges[].kind`	`key`	no	The frontmatter key, only for `link: relation`.
`edges[].property`	`true`	no	The key is a property of kind `relation` (such as `packages`), not a relation kind.
`edges[].meaning`	one of `"derivation"`, `"replacement"`, `"succession"`, `"exclusion"`, `"reference"`	no	The meaning of the relation kind, `reference` for an inline reference; left out for a kind without a meaning and for a property.
`edges[].outdated`	`boolean`	yes	The link stores a version of normal form 1, its target has a current version, and the two differ (SR-025).
`truncated`	`boolean`	yes	More elements are reachable than shown: `limit` stopped a walk or left out a node. The nodes kept are the nearest ones.
`incomplete`	`incomplete`	yes	True when a result is incomplete because targets are in repositories that are not available locally (SR-006 AK2, SR-036 AK3).
`problems`	array of `problem`	yes	Hints: `metamodel.meaning-unassigned` when no relation kind has the meaning `derivation` or no type the meaning `requirement`, so `no-evidence` cannot be found (SR-013 AK3).

App

In the command prompt (Ctrl+Shift+P, macOS ⌘⇧P): the action Show graph. Key: Ctrl+Shift+G (macOS ⌘⇧G).

CLI

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

Usage: reqseq trace graph <ref> [options]

The graph of one element: what its links lead to above it and what links to it
below, to a depth, over the chosen kinds. Each element is one node with its
level and marks, and each link between two nodes is one edge. At most `limit`
nodes, nearest levels first.

Options:
  --ref <value>           instead of the argument <ref>
  --repository <value>    The workspace name of the repository of the element
                          ref names, as in element.get (#255).
  --max-depth <number>    The deepest level in each direction; 0: the element
                          only. Omitted: 1 (the direct neighbours), unless
                          `allLevels` is true.
  --all-levels            Go as far as the links go (the whole chain), within
                          `limit`; not together with `maxDepth`. For the chain
                          alone ask with `meanings: ["derivation"]`. default:
                          false
  --no-all-levels         set all-levels to false
  --kinds <value>         Keys of relation kinds or of properties of kind
                          `relation` (such as `packages`) to follow. An unknown
                          key is `input.invalid`. See `meanings` for the filter
                          rule. repeatable
  --meanings <value>      Relation kinds with these meanings are followed;
                          `reference` stands for inline references. Without
                          `kinds` and `meanings` every relation and reference is
                          followed. Otherwise a link is followed when its key is
                          in `kinds` or its meaning is in `meanings`; an empty
                          list follows nothing. repeatable
  --view <value>
  --limit <number>        The most nodes, the element included; the nearest
                          levels first (`truncated` says when more exist).
                          default: 500
  --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.graph on the local API (reqseq serve api), with the input as the JSON body; the answer is the output.

MCP

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