code-inventory

Reference

Look up command options, file selection rules, and the evidence behind each result.

CLI options

node dist/cli.js [directory] [options]

The directory defaults to the current working directory. Quote globs so the scanner receives the pattern directly.

--project config
Select a config relative to the scan root and follow its transitive project references. Repeat to select multiple configs.
--exclude glob
Omit matching files from the inventory, including imported files. Repeat to combine patterns.
--test glob, --tooling glob, --production glob
Override scope by slash-separated path relative to the root. Each is repeatable. Test takes precedence over tooling, then production, then the default path conventions.
--symbol name-or-id
Query one declaration by exact unique name or snapshot ID. Supports summary and JSON.
--entry source-file
Trace paths from an analyzed file relative to the scan root. Repeat for multiple entries. Use a separate query for --symbol.
--format summary|json|markdown
Choose terminal text (default), machine-readable JSON, or a Markdown report.
--output new-file
Write the result to a new file. An existing path produces an error.
--strict
Write the report and exit with code 2 for a partial scan. A successful scan otherwise exits with 0. Invalid arguments and filesystem errors exit with 1.
-h, --help
Print usage and exit.

Project selection

node dist/cli.js . --project tsconfig.build.json --exclude '**/generated/**' --test 'qa/**'

The scanner discovers TS, TSX, JS, JSX, MTS, CTS, MJS, and CJS files. By default it reads the root tsconfig.json, falling back to jsconfig.json, then to discovered source. Configs supply compiler options, root file selection, and path aliases. A solution config with an empty files list can select a reference graph. Imported source may enter a program even when excluded from the config’s root list.

Each file is counted once. If multiple configs explicitly include a file, the one with the shortest relative path to it owns the file. Config path order breaks ties. An imported file outside every root list belongs to the first importing project in config path order. The file record identifies its owner. Scan projects separately when a shared file has different alias resolutions.

Discovery skips symlinks, declaration files as inventory inputs, and the contents of node_modules, .git, dist, build, coverage, .next, .nuxt, and .output. The compiler can still read declarations for resolution. Discovered files excluded from the inventory carry a reason.

Paths containing test, tests, __tests__, __mocks__, or fixtures as directory names, and .test or .spec files, receive test scope. The scanner labels scripts, tools, and *.config.* as tooling. Other files default to production. The equivalent library options are scan(root, { projects, exclude, scopes }), where each scope maps to an array of globs.

Counts and findings

usages() groups resolved occurrences into calls, construction, reads, type references, imports, re-exports, and JSX. An import or re-export alias contributes one reference even if no code uses the binding. A call inside a loop contributes one direct call site. An explicit constructor and its class each receive a relationship for the same construction site. Distinct callers count the containing declarations of call and construction sites, grouping top-level sites by module.

findings() separates local declarations without meaningful usage from exports without local usage. Imports and re-exports alone do not count as meaningful usage. Export visibility includes exports anywhere in the analyzed source. Review the package’s entry points to determine which exports it exposes.

JSON snapshot

schemaVersion, analyzer, snapshotId
Record the format version, analyzer and compiler versions, and report identity. A symbol ID is tied to its declaration location within the snapshot.
config, files
Record selected configs, project paths and config input hashes, plus file hashes, status, exclusion reasons and project ownership. Resolution-only inputs such as installed declarations and package metadata fall outside the fingerprint.
symbols, references, modules, exports
Describe declarations and their locations, resolved occurrences, module edges, and exported names. Source bodies and the absolute root path are omitted. Locations use one-based lines and columns and zero-based UTF-16 offsets with an exclusive end.
completeness, diagnostics, limitations
A partial result includes diagnostics. A complete result means the supported analysis emitted none. Read the limits when interpreting either result.

A symbol query returns a usage object with its symbol, counts, and references alongside schema version, snapshot ID, diagnostics, and completeness. An entry query returns the selected entries, reached nodes with shortest-path predecessors, and declarations labeled reachable or no-known-path, along with snapshot ID, completeness, diagnostics, and limitations.

Analysis limits

Scanning reads source and configuration without executing modules, tests, or configuration scripts. Parse errors, unresolved imports or calls, computed module paths, accessors, and mutable function bindings can produce diagnostics. Implicit getter and setter dispatch, reflection, and framework conventions can hide usages. The adapter uses Microsoft’s TypeScript 6 compatibility package with compiler engine 6.0.3.

Reachability follows direct calls, construction, static imports and re-exports, and literal dynamic imports or requires in their containing scope. It skips explicit type-only module edges. Emitted JavaScript may omit other imports too. Conditional branches can contribute paths. Recursion within an isolated group creates references without making it reachable from an entry. Runtime behavior, test coverage, and safe removal require additional evidence.