Skip to Content
Command Referencereport

report

Generate a CODEBASE_BRIEF — one shareable snapshot of the whole graph: structure, impact, runtime, and the system boundary, in a single document. Where the query commands answer one question at a time, report rolls the most useful rankings into a page you can read top to bottom or hand to someone else. It is the natural closing step of a session (and of the project0N tour scripts ).

Source: src/commands/report_command.ts · renderer: GraphReport in src/report/graph_report.ts · data: ReportData in src/report/report_data.ts

Synopsis

npx codespine report [options]

Arguments

None. The command summarises the whole loaded graph.

Options

OptionDefaultDescription
-o, --output-folder <dir>./.codespineOutput folder; the Kùzu database is read from <dir>/graph.kuzu.
--format <format>markdownOutput format: markdown, json, or pdf.
--output <file><output-folder>/CODEBASE_BRIEF.<ext>Destination file. The extension follows the format (.md / .json / .pdf).
--limit <n>10Maximum rows per ranking (hubs, hotspots, communities…). Clamped to 1–100.
--stdoutfalseWrite to stdout instead of a file. markdown / json only.

What it does

  1. Checks the database exists. If <output-folder>/graph.kuzu is missing it prints database not found … — run extract then load first, sets exit code 1, and returns.
  2. Gathers the report data by running the same query surface the CLI exposes — hotspots (by callers, by blast radius, and by self-time), cost, deadExports, the strong-cycle finder, and the community/boundary scans — into one format-agnostic GraphReportData.
  3. Renders the chosen format. markdown and json come straight from the pure renderer; pdf renders the visual HTML layout and converts it through an optional engine (see PDF).
  4. Writes the file (or stdout). The default path is <output-folder>/CODEBASE_BRIEF.<ext>.

The brief

The markdown brief is organised as a single readable page. Runtime sections are populated only when the graph has been enriched; on a static graph they state that plainly rather than inventing numbers.

SectionWhat it shows
SnapshotA one-line verdict and the totals: symbols, files, relationships, communities, dead exports, cycles.
CompositionThe node-kind and edge-kind breakdown — the shape of the graph.
Load-bearing codeThe structural hubs: highest fan-in (hotspots --by callers) and largest blast radius.
CommunitiesThe modules cluster found, with CPM quality.
Runtime(enriched only) hotspots by measured self-time and where inclusive cost concentrates.
Structure vs. runtime(enriched only) orchestrators (carry cost, spend little), hidden hotspots (hot, few callers), and the aligned core.
CyclesStrongly-connected call cycles — refactoring friction.
System boundaryWhere the code meets the outside world: Endpoints handled, ConfigFlags read, ExternalAPIs called.
Cleanup candidatesThe dead-exports list.
Where to go nextSuggested follow-up commands, pre-filled with this --output-folder.

PDF output

--format pdf renders the visual HTML layout and converts it with an optional engine. When no engine is installed it does not fail: it writes the HTML next to the requested path (CODEBASE_BRIEF.html) and tells you to open it and print to PDF, or install the engine for direct output. --stdout is not supported for pdf.

Output

✓ wrote ./.codespine/CODEBASE_BRIEF.md

json (--format json) emits the full GraphReportData — the same numbers the markdown renders, for feeding into another tool.

Examples

# write the default markdown brief to ./.codespine/CODEBASE_BRIEF.md
npx codespine report
 
# print the brief to the terminal
npx codespine report --stdout
 
# machine-readable, to a custom path
npx codespine report --format json --output brief.json
 
# a PDF (or an HTML fallback if no PDF engine is installed)
npx codespine report --format pdf

Notes and caveats

  • Enrich first for the runtime sections. Without enrich the Runtime and Structure-vs-runtime sections are empty by design — the graph carries no measured cost to report.
  • A snapshot, not a live view. The brief reflects the graph at the moment you ran it. Re-extract, reload, and re-run after code changes.
  • --limit trims every ranking uniformly; raise it (up to 100) for a fuller brief, lower it for a one-screen summary.

See also

Last updated on
webviewinstall