Skip to content

Latest commit

 

History

History

code-graph

README.md

@demlik/code-graph

Scan TypeScript to find refactor targets, trace calls, and check architecture rules. The default scan measures functions and reports possible maintenance problems. Optional reports cover reachability, storage access, duplicate logic, comments, and git hotspots.

Invocation

Requires Node.js 20 or later. Install it in the project you want to analyze:

pnpm add -D @demlik/code-graph
pnpm exec code-graph src
pnpm exec code-graph src --plan

The path must be a directory. Paths are relative to where you run the command.

Choose the report you need; these examples use code-graph as shorthand for pnpm exec code-graph:

Goal Command
Rank refactor targets code-graph src --plan
Browse files and functions code-graph src --tree
Inspect one feature's Ports & Adapters code-graph src/orders --hexagon
See who owns a table and who reaches into it code-graph . --owners --boundary-rules boundary-rules.json
Inspect one function's callers code-graph src --blast example.ts:calculate
Look up a name: where it is declared, whether it is exported, who uses it code-graph src --find Order
Save a call graph code-graph src --graph --edges --out graph.json
Browse an HTML report code-graph src --html --out report.html
Find unreachable functions code-graph src --unreachable
Check architecture boundaries code-graph . --boundaries
Find churn and complexity hotspots code-graph src --hotspots
Find repeated expressions and argument groups code-graph src --clones --clumps

The default scan uses oxc and needs no tsconfig. Call-graph reports use tsgo and require an accessible tsconfig.json. The path controls which files are scanned; --deep changes where the tsconfig is found, without adding files to the scan.

Use --json for machine-readable reports and --out <file> to save them. --clones and --clumps need no tsconfig and never gate. They report syntax matches for review, including every matching site in JSON. --clumps also ranks repeated call shapes whose reference names differ: positional rows list the varying argument slots (including options keys), site count and distinct-tuple count beside the existing exact-name groups. See duplication reports for normalization, size floors and limits. The CLI reference lists every flag, scope rule, and exit code.

Documentation

Start with the documentation index, or go directly to:

Working in this checkout

From the monorepo root:

pnpm --filter @demlik/code-graph build
node packages/code-graph/dist/index.js packages/code-graph/src --plan
node packages/code-graph/dist/index.js packages/code-graph --graph --edges --out graph.json
node packages/code-graph/dist/index.js packages/code-graph --html --out report.html

This repository has package tsconfigs and no root tsconfig. Run call-graph reports on a package directory. See scope rules for other repository layouts.

To run the source directly, without building:

pnpm --filter @demlik/code-graph exec node --import tsx src/index.ts src --plan

That command runs inside the package, so its paths are package-relative.

Run the package checks:

pnpm --filter @demlik/code-graph typecheck
pnpm --filter @demlik/code-graph lint
pnpm --filter @demlik/code-graph test
pnpm --filter @demlik/code-graph build
pnpm --filter @demlik/code-graph verify:exports

Benchmark findings record the engine measurements and reproduction commands.