Codestin Search App

Walk the symbol-level call chain for one exported symbol: callers up (modules that import the symbol) and callees down (import-symbol edges plus intra-module call sites), bounded by --depth. trace is its own surface for following how a symbol connects through the codebase before you change it.

fallow trace src/api.ts:fetchUser --format json --quiet
fallow trace src/api.ts:fetchUser --callers --depth 2
fallow trace --path src/app.ts src/db.ts

--path answers a different question from the symbol target: which chain of imports carries one module to another. See Import path between two modules.

fallow trace is a standalone, best-effort symbol-level surface. It is not folded into the ranked review brief and is never an input to the focus map or its ranking. Use it when you want to see how a symbol connects, not when you want a prioritized review.

Target

fallow trace takes one positional argument in FILE:SYMBOL form:

fallow trace src/api.ts:fetchUser

FILE is a project-relative path and SYMBOL is the exported symbol name. Omit it when you pass --path, which takes two file paths instead.

Options

Flag	Description
`--callers`	Walk only the callers direction.
`--callees`	Walk only the callees direction.
`--depth <N>`	Bound the walk depth in each requested direction.
`--path <FROM> <TO>`	Find the shortest import path between two modules instead of walking a symbol. Mutually exclusive with the `FILE:SYMBOL` target, `--callers`, `--callees`, and `--depth`.

When neither --callers nor --callees is set, both directions are walked. trace also accepts the project, output, and performance global flags (--root, --config, --format with human or json, --quiet, --no-cache, --threads, --changed-since).

How it works

The walk is best-effort and syntactic. Resolved and unresolved callees are reported honestly: an unresolved callee (for example, a dynamic call fallow cannot statically resolve) is surfaced as unresolved rather than silently dropped, so the chain reflects what fallow could and could not follow. When the same export is referenced in both type and value space, JSON output adds direct_references_by_namespace with separate evidence for each lane. namespace and direct_references keep their existing winning-lane meaning for compatibility. The grouped field is omitted when only one lane has references, so consumers should treat its absence as the common single-namespace case.

Ambiguous star exports

When two export * sources contribute the requested name, the barrel exports nothing under that name. JSON output reports symbol_found: false and adds a star_export_ambiguity object:

{
  "symbol_found": false,
  "star_export_ambiguity": {
    "sources": ["src/models/admin.ts", "src/models/customer.ts"],
    "namespaces": ["type"]
  }
}

sources contains the sorted project-relative declaration origins. namespaces identifies whether the collision is in type space, value space, or both, with type before value. This field distinguishes a barrel collision from an unknown or misspelled symbol. Keep one origin, rename the others, or replace the star exports with explicit re-exports. The same best-effort call-chain data is available as opt-in evidence on fallow inspect --symbol-chain and the inspect_target MCP tool’s symbol_chain option.

Import path between two modules

fallow trace --path <FROM> <TO> reports the shortest chain of imports by which FROM reaches TO. Both are project-relative file paths. Use it when you want to know how a module ends up depending on another one, rather than how a symbol is called. Exact project-relative or absolute paths take priority over suffix matches. An abbreviation is accepted only when it identifies one module. A missing or ambiguous endpoint exits with code 2; use the full project-relative path to disambiguate.

$ fallow trace --path pages/report.tsx components/Box.tsx

Shortest import path (syntactic; OFF the ranked path)

  from: pages/report.tsx
  to:   components/Box.tsx
  hops: 3

  [1] pages/report.tsx:20 -> lib/related.transform.ts
  [2] lib/related.transform.ts:1 -> components/RelatedContent.tsx
  [3] components/RelatedContent.tsx:3 -> components/Box.tsx

JSON output carries the same walk under kind: "trace" with its own schema_version:

$ fallow trace --path pages/report.tsx components/Box.tsx --format json

{
  "kind": "trace",
  "schema_version": "1",
  "from": "pages/report.tsx",
  "to": "components/Box.tsx",
  "reachable": true,
  "hops": 3,
  "path": [
    {
      "from": "pages/report.tsx",
      "to": "lib/related.transform.ts",
      "type_only": false,
      "import_line": 20
    },
    {
      "from": "lib/related.transform.ts",
      "to": "components/RelatedContent.tsx",
      "type_only": false,
      "import_line": 1
    },
    {
      "from": "components/RelatedContent.tsx",
      "to": "components/Box.tsx",
      "type_only": false,
      "import_line": 3
    }
  ],
  "reason": "pages/report.tsx reaches components/Box.tsx in 3 hops"
}

Three behaviors are worth relying on. A type-only hop is reported with type_only: true rather than skipped, so a path that exists only in type space is visible instead of silently absent. An unreachable pair is a result, not an error: reachable is false, path is empty, hops is 0, and reason says no import path was found. The command still exits 0. And tracing a module to itself answers reachable: true with hops: 0, so branch on reachable rather than on the hop count, which is 0 in both cases.

Inspect a target

Compose one evidence bundle for a file or exported symbol, with opt-in --symbol-chain.

Audit and review brief

Changed-file verdict plus the graph-derived review brief and decision surface.

Resolve a stack trace

Map runtime stack-trace frames back to the definitions they name.

MCP integration

Use fallow tools from AI coding agents.

Commands

fallow trace

Target

Options

How it works

Ambiguous star exports

Import path between two modules

See also

Inspect a target

Audit and review brief

Resolve a stack trace

MCP integration

​Target

​Options

​How it works

​Ambiguous star exports

​Import path between two modules

​See also

Inspect a target

Audit and review brief

Resolve a stack trace

MCP integration

Target

Options

How it works

Ambiguous star exports

Import path between two modules

See also