> ## Documentation Index
> Fetch the complete documentation index at: https://xspec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# xspec query: JSON Graph Access for Scripts

> Reference for all xspec query subcommands: node, nodes, edges, subtree, ancestors, and reachable — JSON-native graph access for scripts and automation.

`query` is the JSON-native interface to the xspec requirement graph. Every subcommand emits JSON unconditionally — no `--json` flag is needed. Use `query` when you are writing scripts, CI tools, or editor integrations that need structured graph data.

## Node vs graph-node

Two argument types appear across `query` subcommands:

* **`<node>`** — a workspace-relative spec reference: `path#id` for a named node, or a bare `path` for the file root node. Only spec nodes are valid here.
* **`<graph-node>`** — a superset of `<node>` that also accepts code locations: `path` for a file root, `path#unit` for a named code unit, or `path#unit@N` for a specific occurrence within a unit.

## Subcommands

### query node

Return the complete record for a single spec node.

```sh theme={null}
xspec query node <node>
```

**Returns:** identity, source range, own text, subtree text, all four hashes (`ownHash`, `subtreeHash`, `effectiveHash`, `metadataHash`), tags, coverage attribute, and all incoming and outgoing edges grouped by kind.

***

### query nodes

Return one row per node in the workspace, with optional filters.

```sh theme={null}
xspec query nodes [--group <g>] [--file <glob>] [--tag <t>] [--coverage required|none]
```

<ParamField path="--group" type="string">
  Restrict to nodes belonging to the named spec group. Accepts a spec group name only — not a file path.
</ParamField>

<ParamField path="--file" type="glob">
  Restrict to nodes defined in files matching the given workspace-relative glob.
</ParamField>

<ParamField path="--tag" type="string">
  Restrict to nodes carrying the given tag.
</ParamField>

<ParamField path="--coverage" type="string">
  Restrict by coverage attribute. Accepted values: `required`, `none`.
</ParamField>

All filters combine conjunctively — a node must satisfy every provided filter to appear in the results.

**Returns:** one object per matching node with identity, source range, tags, and coverage attribute.

***

### query edges

Return all edges in the graph, with optional filters.

```sh theme={null}
xspec query edges [--from <graph-node>] [--to <graph-node>] [--kinds <kinds>]
```

<ParamField path="--from" type="graph-node">
  Restrict to edges originating from this graph node.
</ParamField>

<ParamField path="--to" type="graph-node">
  Restrict to edges terminating at this graph node.
</ParamField>

<ParamField path="--kinds" type="string">
  Comma-separated list of edge kinds to include. Valid values: `contains`, `depends`, `embeds`, `references`.
</ParamField>

**Returns:** one object per matching edge with `from`, `to`, and `kind` fields.

***

### query subtree

Return the node and all of its descendants in document order.

```sh theme={null}
xspec query subtree <node>
```

**Returns:** one object per node (the root plus all descendants) with identity, source range, tags, and coverage attribute.

***

### query ancestors

Return the proper ancestors of a node, nearest-first.

```sh theme={null}
xspec query ancestors <node>
```

**Returns:** one object per ancestor node (not including the node itself) with identity, source range, tags, and coverage attribute. The immediate parent is first; the file root is last.

***

### query reachable

Determine whether one graph node can reach another through the edge graph, and return the shortest path if so.

```sh theme={null}
xspec query reachable --from <graph-node> --to <graph-node> [--kinds <kinds>]
```

<ParamField path="--from" type="graph-node" required>
  The starting node for the reachability search.
</ParamField>

<ParamField path="--to" type="graph-node" required>
  The target node.
</ParamField>

<ParamField path="--kinds" type="string">
  Comma-separated edge kinds to traverse. Accepts only the three dependency kinds: `depends`, `embeds`, `references`. `contains` edges are not traversable here.
</ParamField>

**Returns:** a `path` array with the identity strings along the shortest path, and a `reachable` boolean. If `reachable` is `false`, the `path` array is empty.

```sh theme={null}
$ xspec query reachable --from "test/auth.test.ts#testValidLogin" \
    --to "specs/AUTH.mdx#auth.login.valid"
{
  "path": [
    "test/auth.test.ts#testValidLogin",
    "specs/AUTH.mdx#auth.login.valid"
  ],
  "reachable": true
}
```

When multiple shortest paths exist, xspec selects the one that sorts first byte-lexicographically.

## Always-JSON behavior

Unlike other xspec commands, `query` never produces human-readable output. All subcommands emit JSON unconditionally — passing `--json` is valid but has no additional effect. Pipe the output directly into `jq` or any JSON-aware tool.

```sh theme={null}
# Find all nodes tagged "security" in the specs/ directory
xspec query nodes --file "specs/**" --tag security | jq '.[].identity'
```