code-inventory

Your first scan

Build the CLI from a checkout, then use the included TypeScript fixture to investigate a declaration and trace its callers.

Build from source

Clone the code-inventory repository and open its root directory. The examples use the compiled files in your checkout. Use Node.js 26 or newer. CI pins 26.13.1.

npm ci --ignore-scripts --no-audit
npm run build

Scan the fixture

The basic fixture has a function named normalize, a module that re-exports it as clean, and two files that use it. Scan the directory to see the totals across all declarations.

node dist/cli.js test/fixtures/basic
Code inventory: 4 analyzed files, 10 symbols
16 references, 7 direct call sites
2 symbols with no references found
2 exports without local usage
Analysis: complete; 0 diagnostics
Static evidence only; no-reference findings are not proof of dead code.

To review individual records or share a report, select an output format. Each output path must be new. The CLI writes to standard output when you omit --output.

node dist/cli.js test/fixtures/basic --format json --output inventory.json
node dist/cli.js test/fixtures/basic --format markdown --output inventory.md

Inspect a symbol

node dist/cli.js test/fixtures/basic --symbol normalize

The report starts with the declaration ID and counts. Each subsequent reference names its file, line, column, kind, and scope.

normalize (definitions.ts:0:function)
9 references; 4 direct call sites; 3 distinct callers

In app.ts, clean(' first ') on line 6 and alias(' second ') on line 8 both resolve to normalize. Passing clean to .map() on line 9 contributes a read. The scanner cannot infer how often the callback runs. When several declarations share a name, use an exact ID from the snapshot or ambiguity error.

Trace an entry point

node dist/cli.js test/fixtures/basic --entry app.ts --format markdown

The scan finds four reachable declarations and five with no known path from app.ts. The production entry calls main(), which calls normalize through its alias. The separate test function also references normalize, but has no incoming path from the selected entry. Repeat --entry to combine roots.

In JSON, start at a reached node and follow via.from until you reach an entry. Each step gives the edge kind and its location. Consider other entry points, callbacks, framework dispatch, and external consumers before removing a declaration.

Read a partial scan

After building from source, scan the CLI itself from the repository root.

node dist/cli.js . --project tsconfig.build.json --entry src/cli.ts --format markdown
42 reachable declarations, 63 with no known path
Analysis: partial; 3 diagnostics

In the paths section, follow the call from the entry module to main() at src/cli.ts:71, then from main() to scan() at src/cli.ts:36. The line numbers point to the calls that establish each step.

Run the same query with --format json to inspect diagnostics. The three unresolved-call entries point to two calls through rules.excluded and one through addCompilerDiagnostic. The scanner could not tie those calls to concrete project declarations. Adding --strict still emits the report and sets exit code 2.

The callback passed to .map() at src/report.ts:49 appears under declarations with no known path. That status describes the path the scanner could establish from this entry. The scanner does not model the runtime call that .map() makes to the callback.

Use the library

From the repository root, run the same queries against one in-memory snapshot. All calls are synchronous.

Save this example as inspect.mjs in the repository root and run node inspect.mjs.

import { scan, usages, reachability, findings, markdown } from './dist/index.js';

const inventory = scan('test/fixtures/basic');
console.log(usages(inventory, 'normalize').counts);
console.log(reachability(inventory, ['app.ts']).declarations);
console.log(findings(inventory));
console.log(markdown(inventory));

See the project selection rules before scanning a workspace with several TypeScript configs.