dg trace

Find every file that imports a given symbol and show exactly where it is used. Useful for understanding blast radius before making changes.

Usage

npx dg trace <symbol-name> [--scope <path>]

Examples

# Find all importers of a function
npx dg trace processPayment

# Find all importers in a subtree
npx dg trace processPayment --scope src/payments

# Find all importers of an enum
npx dg trace PaymentStatus

# Find all importers of a type/interface
npx dg trace UserConfig

How it works

The trace command runs the JIT Scanner — the same scanner used internally by the pipeline's call-site tracer. It performs a two-step process:

  1. git grep— fast initial scan to find candidate files that mention the symbol name. Scope filtering is applied immediately after grep and before any file classification. This is O(repo) but runs in milliseconds thanks to git's built-in index.
  2. AST confirmation — parses the import statements of each candidate file to confirm the symbol is actually imported (not just mentioned in a comment or string literal).

Barrel re-export resolution

The scanner handles barrel files (index.ts) automatically. If processPayment is exported from src/api/payments.tsand re-exported through src/api/index.ts, the scanner will follow the chain and find consumers that import from the barrel.

Re-export chains are followed up to 10 levels deep (configurable via maxBarrelDepth in dg.config.json).

Import types

The scanner identifies how each file imports the symbol:

TypeExample
staticimport { processPayment } from './api'
defaultimport processPayment from './api'
aliasedimport { processPayment as pay } from './api'
re-exportexport { processPayment } from './payments'

Example output

$ npx dg trace processPayment

  Diff-Guardian Trace: processPayment
  Scanning repo for importers...

  processPayment -- 3 importer(s) found

  src/checkout/handler.ts
    L4  processPayment  [static]
  src/invoices/gen.ts
    L2  processPayment  [static]
  tests/payments.test.ts
    L1  processPayment  [static]

  Total: 3 import(s) across 3 file(s)