Dependency Queries

Commands

The query command traces dependency paths between two selectors without changing analysis results or editing files. It uses the same parsed import, export, resolver, alias, dynamic import, and glob edges as normal analysis.

npx codescythe query somepath \
  src/main.ts \
  src/module.ts

npx codescythe query somepath \
  src/main.ts \
  src/features/

npx codescythe query allpaths \
  src/main.ts \
  src/runtime.ts:initRuntime

Selectors

Selectors can point at files, directories, or exported symbols. Relative selectors are resolved from the analysis root selected by -C or --config.

• src/main.ts selects a project file.
• src/features/ selects every project file under a directory.
• src/module.ts:used selects one exported symbol from a file.

Output Formats

Text output is optimized for terminal inspection. JSON is the stable machine-readable surface. Mermaid and SVG render the same query graph as a diagram.

npx codescythe query allpaths \
  --output text \
  src/main.ts \
  src/runtime.ts:initRuntime

npx codescythe query allpaths \
  --json \
  src/main.ts \
  src/runtime.ts:initRuntime

npx codescythe query allpaths \
  --output mermaid \
  src/main.ts \
  src/runtime.ts:initRuntime

npx codescythe query allpaths \
  --output svg \
  src/main.ts \
  src/runtime.ts:initRuntime > graph.svg

--json is a shortcut for --output json. SVG output is rendered from the Mermaid graph with mermaid-rs-renderer.

Fixture Examples

These examples are generated from checked-in repository fixtures. The Mermaid snippets below are exact CLI output from --output mermaid.

test-file-usage: somepath to one export

A file-to-export query shows a named import edge directly to the exported symbol.

codescythe query somepath \
  -C tests/fixtures/test-file-usage \
  --output mermaid \
  src/main.ts \
  src/module.ts:used

flowchart LR
  n0["src/module.ts:used"]
  n1["src/main.ts"]
  n1 -->|"named import ./module:used"| n0

oxc-resolution: somepath to a folder

A file-to-directory query returns one shortest path for each reachable matched target file.

codescythe query somepath \
  -C tests/fixtures/oxc-resolution \
  --output mermaid \
  app/index.ts \
  app/

flowchart LR
  n0["app/aliased.ts:aliased"]
  n1["app/extension.ts:extension"]
  n2["app/internal.ts:internal"]
  n3["app/aliased.ts"]
  n4["app/extension.ts"]
  n5["app/index.ts"]
  n6["app/internal.ts"]
  n0 -->|"defined in file aliased"| n3
  n1 -->|"defined in file extension"| n4
  n2 -->|"defined in file internal"| n6
  n5 -->|"named import @/aliased:aliased"| n0
  n5 -->|"named import ./extension.js:extension"| n1
  n5 -->|"named import #internal:internal"| n2

knip-export-basics: allpaths through namespace use

An allpaths query keeps every node and edge that can carry the source file to the target export.

codescythe query allpaths \
  -C tests/fixtures/knip-export-basics \
  --output mermaid \
  index.ts \
  my-namespace.ts:y

flowchart LR
  n0["index.ts"]
  n1["my-module.ts"]
  n2["my-module.ts:myExport"]
  n3["my-namespace.ts:y"]
  n2 -->|"defined in file myExport"| n1
  n0 -->|"named import ./my-module.js:myExport"| n2
  n1 -->|"namespace member ./my-namespace.js:y"| n3

runfiles-fixture: somepath through an alias

Alias resolution is represented in the edge label, while the target still resolves to the project file export.

codescythe query somepath \
  -C tests/fixtures/runfiles-fixture \
  --output mermaid \
  workspace/frontend/apps/client/platform/platformRuntime.ts \
  protobuf/generated/client.ts:client

flowchart LR
  n0["protobuf/generated/client.ts:client"]
  n1["workspace/frontend/apps/client/platform/platformRuntime.ts"]
  n1 -->|"named import #bazel_generated/client:client"| n0

Cycles

Dependency cycles are finite in query output. somepath runs breadth-first search with visited nodes and parent edges, so it returns shortest acyclic paths. allpaths does not enumerate paths; it intersects forward reachability from the source with reverse reachability from the target, then returns the induced path subgraph.