extracting-code-structure

Extracting code structure

ts-pack process <file> runs the code-intelligence pipeline over a source file and prints JSON. Use it when the user wants structured metadata — "list the functions", "what does this file import", "find the exported symbols", "pull the docstrings" — rather than a raw syntax tree.

Quick recipe

# Default features: structure + imports + exports
ts-pack process src/app.ts

# Pick features explicitly (only what you ask for is computed)
ts-pack process src/app.ts --structure --imports --symbols --docstrings

# Everything
ts-pack process src/app.ts --all

When no feature flags are given, process defaults to --structure --imports --exports. Passing any single extraction flag (--structure --imports --exports --comments --docstrings --symbols --diagnostics) turns off that default set, so list every feature you want. --chunk-size and --language are modifiers, not extraction flags: they do not disable the defaults (e.g. --chunk-size 500 alone still emits structure+imports+exports and adds chunks).

Feature flags

Flag	Extracts
--structure	Functions, classes, methods, modules (spans, nesting, visibility).
--imports	Import statements and their sources.
--exports	Exported symbols and their kinds.
--comments	Inline and block comments.
--docstrings	Docstrings attached to definitions.
--symbols	All identifiers (for search/indexing).
--diagnostics	Syntax errors and error nodes with positions.
--all	Enable every feature above.
--chunk-size <bytes>	Syntax-aware chunks — see chunking-for-llms.
--language <name> (-l)	Override language (auto-detected from extension otherwise).

Result shape

process always prints JSON. Top-level keys:

{
  "language": "python",
  "metrics": { "total_lines": 0, "code_lines": 0, "comment_lines": 0, "blank_lines": 0, "total_bytes": 0, "node_count": 0, "error_count": 0, "max_depth": 0 },
  "structure": [],
  "imports": [],
  "exports": [],
  "comments": [],
  "docstrings": [],
  "symbols": [],
  "diagnostics": [],
  "chunks": []
}