report

spanical report runs the whole pipeline and writes the result as a file you can read, share, or commit. It is the only command that accepts --format html.

bash

spanical report [flags]

Options

Option	Values	Notes
All global flags		See global flags
`--format`	`table` \| `json` \| `md` \| `html`	The only command accepting `html`
`--out`	path	Overrides the default artifact name; write failure prints `Failed to write <out>: <reason>` and exits 1

Behavior

The run covers extraction into the SQLite cache, monthly scc snapshots, ownership blame at HEAD, rework capture, and (when configured) the GitHub ticket sync. It then:

Prints a headline block to stdout
Writes an artifact named spanical-report-<start>_<end>.md in the current directory (spanical-report-2025-08_2026-08.md style), or .html, or your --out path

The headline shows the window label with granularity and zone, a two-column summary (net growth, total size, throughput churn, no-merge commits, active devs, busiest period), up to five hotspots, and a bus-factor warning count.

Artifact sections, in order: Activity by period; Timeline; Contributors; Tickets and Reviews (omitted when tickets are unconfigured, GITHUB_TOKEN is unset, or the window has no ticket or review activity); Hotspots; Ownership & bus-factor; Size & complexity; Migrations; then a per-repo appendix repeating everything per repository. Migrations always carry the note that they are tracked separately from main churn.

Format behavior

--format json and --format md change nothing: same terminal text, same Markdown artifact. Only html differs, turning the artifact into a self-contained dark-theme HTML dashboard (h1 "spanical dashboard") with six Chart.js charts: net growth, churn, contributor throughput share, size and complexity trend, language mix, hotspot scores. Chart.js is inlined; the file renders offline.

Examples

Default run against a small repo:

shell

$ spanical report
last 12m (2025-08 → 2026-08) · monthly · 1 repo · UTC

  Net growth        +104 LOC     Total now      93 LOC
  Throughput churn  204 lines    Commits        46 (no-merge)
  Active devs       3            Busiest month  2026-02

Top hotspots (refactor shortlist)
  repo-alpha/src/core/engine.ts  churn 3 · cx 0 · owners 3

Bus-factor warnings: 0 files owned > 80% by a single dev in 0 dirs

Full report -> .../repo-alpha/spanical-report-2025-08_2026-08.md

Narrow to the current month and choose the artifact path:

shell

$ spanical report --this month --out monthly.md
this month (2026-08 → 2026-08) · weekly · 1 repo · UTC
...
Full report -> /var/.../monthly.md

The Markdown artifact opens with the headline in a fenced block, then section tables:

shell

# Engineering report — last 12m (2025-08 → 2026-08)

```
  Net growth        +104 LOC     Total now      93 LOC
  Throughput churn  204 lines    Commits        46 (no-merge)
  Active devs       3            Busiest month  2026-02

Top hotspots (refactor shortlist)
  repo-alpha/src/core/engine.ts  churn 3 · cx 0 · owners 3

Bus-factor warnings: 0 files owned > 80% by a single dev in 0 dirs
```

## Activity by period

| Period | Commits | Added | Deleted | Net | Throughput | Migrations |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| 2026-01 | 7 | 10 | 2 | 8 | 12 | 0 |
| 2026-02 | 7 | 83 | 3 | 80 | 86 | 0 |
... truncated

Empty results

With no eligible files, the hotspot section prints the same empty-window message documented on hotspots. The 50 interpolates from config.hotspot.minFileLines. A repository with no commit at or before the window end is skipped with its own note rather than counted as zero activity.