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>

Examples

# Find all importers of a function
npx dg trace processPayment

# 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. 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)