health

Usage

kicad-cruncher health project.kicad_pro -o output/health
kicad-cruncher health project.kicad_pro --fail-on-issues

Arguments

file accepts a .kicad_pro project. If omitted, the command auto-detects exactly one .kicad_pro in the current directory.

-o selects the output directory. Without -o, artifacts are written under ./output/health/.

--fail-on-issues returns a nonzero exit code when missing model payloads, unresolved external models, or scan diagnostics are found. Without this flag the command writes the report and returns success so engineers can inspect diagnostics interactively.

The scan scope is the active project board/schematic pair plus local symbol and footprint libraries listed in the project sym-lib-table and fp-lib-table. It intentionally ignores unrelated recursive .pretty, .kicad_mod, and .kicad_sym files that are not listed in those tables.

Ownership

kicad-monkey owns asset and model-reference scanning. kicad-cruncher owns the health command, output layout, report summary, README writing, logging, and exit status.

The command is non-destructive. It does not extract libraries, edit source files, update library tables, relink schematic symbols, or relink PCB footprints.

Output

The selected output directory contains a health report bundle:

• project_health.json: kicad_cruncher.project_health.a0 report with asset inventory, model-reference classification, issue summary, and raw diagnostics.
• README.md: short human-readable summary for agents and reviewers.

Issues currently cover missing embedded model payloads, missing or unresolved external model files, placed PCB footprints with no model records, and parser/scanner diagnostics from the asset scan. Library extraction commands intentionally skip this scan by default.

Tests

L0 public CLI tests verify help and command registration. L3 public workflow tests run health against the sanitized 4-ch backplane corpus fixture and verify the report schema, summary counts, asset inventory, and command aliases. L99 signoff verifies public command docs and dedicated command-module ownership.