Show neighbourhood

The surroundings of one element over every relation kind and inline reference, up and down to a depth; each edge says whether it repeats an element and whether it is outdated. One page of nodes at a time.

Command trace.neighbourhood. 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).
`direction`	one of `"up"`, `"down"`, `"both"`	no	`up`: along the links the element’s file stores (its parents, the targets of its other relations and relation properties, its inline references). `down`: along the links that point at it (its children and every element whose file has a relation or an inline reference to it). The source of a link is placed below its target (ADR-0004). Default: `"both"`.
`maxDepth`	`integer`	no	The deepest depth in each direction; 0: the root only. Omitted: 1 (the direct neighbours), unless `allLevels` is true.
`allLevels`	`boolean`	no	Walk as far as the links go (the whole chain); 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	Nodes of the page; total counts all. Default: `200`.
`offset`	`integer`	no	Nodes skipped before the page, in the order of `nodes` (the root, the up walk level by level, the down walk 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 reached once per walk, at its shortest depth: the root, then the up walk, then the down walk, each level by level. In a view only the elements the view holds (SR-040, SR-043: not a core requirement the variant excludes or replaces); the root always. Only the page of `limit` nodes from `offset` is listed; `total` counts all.
`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 in its walk: 0 for the root.
`nodes[].direction`	one of `"up"`, `"down"`	no	`up` for an element reached along the links its file stores, `down` for one reached along the links that point at it; left out for the root.
`nodes[].expanded`	`boolean`	yes	Its links were looked at; false only at `maxDepth`, where the walk was cut.
`total`	`integer`	yes	The number of all nodes; `nodes` holds the page.
`edges`	array of `object`	yes	Every link the walks followed, up edges first, then down edges, in walk order; an edge is on the page of the node it leads to in its walk. A hub (a package with many members) can put many edges on one page: leave out `packages` with `kinds` or `meanings`. 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), whatever the walk direction.
`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[].direction`	one of `"up"`, `"down"`	yes	The walk it belongs to.
`edges[].cyclic`	`boolean`	yes	Both ends lie in one cycle of the walk.
`edges[].repeated`	`boolean`	yes	The edge leads, in its walk, to an element that this walk first reached through another edge, or to the root: a repetition (SR-107 AK3). It holds within one call (asking again from a child loses it; to open a tree level by level ask from the same root with a larger `maxDepth`) and within the followed kinds (the tree of derivations comes from `meanings: ["derivation"]`). First means first reached breadth first (spec question #421).
`edges[].outdated`	`boolean`	yes	The link stores a version of normal form 1, its target is available and has a current version, and the two differ (SR-025).
`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).

App

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

CLI

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

Usage: reqseq trace neighbourhood <ref> [options]

The surroundings of one element over every relation kind and inline reference,
up and down to a depth; each edge says whether it repeats an element and whether
it is outdated. One page of nodes at a time.

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).
  --direction <value>     `up`: along the links the element's file stores (its
                          parents, the targets of its other relations and
                          relation properties, its inline references). `down`:
                          along the links that point at it (its children and
                          every element whose file has a relation or an inline
                          reference to it). The source of a link is placed below
                          its target (ADR-0004). one of: up, down, both;
                          default: "both"
  --max-depth <number>    The deepest depth in each direction; 0: the root only.
                          Omitted: 1 (the direct neighbours), unless `allLevels`
                          is true.
  --all-levels            Walk as far as the links go (the whole chain); 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>        Nodes of the page; total counts all. default: 200
  --offset <number>       Nodes skipped before the page, in the order of `nodes`
                          (the root, the up walk level by level, the down walk
                          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.neighbourhood on the local API (reqseq serve api), with the input as the JSON body; the answer is the output.

MCP

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