API

Version

Rationale

Date-based releases need a typed view over the package version string so CLI, tests, and release automation can agree on the encoded calendar date.

Purpose

Version carries the parsed major, minor, patch, optional build, original string, and derived release date for kicad-cruncher.

Test Requirements

L99 verifies that pyproject metadata, package API, CLI output, changelog, and dated release notes all match the same date-version contract.

Working Definition

The interface is working when kicad_cruncher.version() parses the installed distribution version or source fallback into a valid date-version object.

DesignReviewBundle

Rationale

Design-review generation is reused by the standalone design command and by Megamaid, so callers need one typed bundle describing every written artifact and count.

Purpose

DesignReviewBundle carries the output directory, design JSON, netlist JSON, KiCad S-expression netlist, manifest, README, manifest payload, component/net counts, schematic SVG records, and PCB SVG records for one review bundle.

Test Requirements

L3 exercises the public design command and verifies emitted JSON, netlists, manifest fields, README, schematic SVGs, PCB SVGs, component counts, and net counts. Megamaid L3 tests also verify nested design-review bundle creation.

Working Definition

The interface is working when all generated design-review paths and counts can be passed to downstream commands without reopening or rediscovering the output directory.

PcbLayerStepConfig

Rationale

The layer STEP command needs a durable config object that preserves the fixture-alignment shape while resolving KiCad layer selectors and per-output overrides.

Purpose

PcbLayerStepConfig carries one parsed root config or one parsed output config, including board selection, layer selection, feature switches, feature colors, step_body_name values, pad highlight rules, thickness-bias policy, scoped drill policy, fusion policy, and nested output definitions.

Test Requirements

L3 loads the generated default JSONC template through the command path and verifies that yoshi and taillight produce the expected test-point body, board outline body, drill behavior, and manifests. L99 verifies generated JSONC comments for enum options.

Working Definition

The interface is working when defaults merge into each output consistently and command-line overrides can convert the parsed config into a valid PcbLayerStepOptions object for export.

PcbLayerStepOptions

Rationale

The exporter needs a normalized, per-output option contract so geometry collection, drill strategy, color grouping, and Geometer body creation do not depend on raw JSON shape.

Purpose

PcbLayerStepOptions carries the resolved KiCad layer, Z/thickness settings, copper and outline colors, feature switches, scoped drill policy, pad highlight rules, feature-specific step_body_name values, and thickness-bias options used for one STEP output.

Test Requirements

L3 exercises the default options through real yoshi and taillight boards and checks the resulting Geometer request body IDs, colors, drill overlay counts, and selected B.Cu layer manifest data.

Working Definition

The interface is working when one options instance fully determines a repeatable geometry.planar_step.request.a0 request for a selected PCB layer.

PcbLayerStepResult

Rationale

The command needs a compact result summary after Geometer writes the STEP file so logging and tests can verify emitted artifacts without reopening the whole request.

Purpose

PcbLayerStepResult carries the STEP path, manifest path, board name, selected layer, body counts, drill count, and source input path for one generated output.

Test Requirements

L3 verifies that the command writes both files, that the manifest records the expected board/layer/counts, and that the Geometer request matches the result-level artifact naming.

Working Definition

The interface is working when successful exports return paths and counts matching the files and manifest written beside the STEP artifact.

KiCadModelPose

Rationale

Assembly SVG projection needs one KiCad-facing model pose that can be passed unchanged to Geometer HLR and model-bounds calls.

Purpose

KiCadModelPose carries the resolved model-to-KiCad-3D-world matrix, footprint side, board thickness, and a rounded cache signature for one footprint model.

Test Requirements

L3 verifies the dedicated HLR fixture against KiCad STEP-exporter transform order, including model offset, rotations, board thickness, and world-to-SVG coordinate conversion.

Working Definition

The interface is working when the same pose matrix aligns HLR detail, HLR outline, transformed model bounds, and copper fallback bounds for the signoff fixture and broader PCB SVG outputs.

PcbSvgComposition

Rationale

The PCB SVG command composes physical KiCad layers with derived virtual layers, so callers need both rendered SVG text and the physical layer dependencies used to build it.

Purpose

PcbSvgComposition is the internal return contract for A0 PCB SVG composition: it carries complete SVG text and the normalized physical layers represented in that output.

Test Requirements

L3 exercises explicit config rendering, layer outputs, virtual outputs, manifests, configured views, and enriched metadata that depends on the composition contract.

Working Definition

The interface is working when layer and view outputs render from the same compositor path and their manifests accurately report the physical layers behind each SVG artifact.

PcbSvgCompositionRenderCache

Rationale

PCB SVG generation can render several configured views from the same board, so repeated root SVG, board-origin, hole-fragment, physical-fragment, and board-region work must be cached within one command run.

Purpose

PcbSvgCompositionRenderCache owns command-scoped compositor caches for one KiCadPcb, including the parsed board IR, root SVG text by layer set, physical fragments, hole fragments, classified board regions, and root origin.

Test Requirements

L3 exercises default view rendering through the public pcb-svg command and verifies that multiple view outputs are emitted from the same configured command path. Repeated model projection tests cover the companion HLR/bounds reuse path.

Working Definition

The interface is working when one PCB SVG command run can render multiple physical and virtual outputs while reusing cached board-derived SVG fragments without changing artifact content.

FieldAliasConfig

Rationale

BOM and PnP outputs need one alias table so KiCad fields such as manufacturer, part number, and LCSC code normalize into stable grouped and JLC upload columns.

Purpose

FieldAliasConfig carries canonical field aliases for the shared manufacturing model and keeps source field traceability attached to normalized records.

Test Requirements

L3 exercises the alias-aware command path through BOM, PnP, and JLC generation from the Yoshi project and verifies that configured output artifacts are written.

Working Definition

The interface is working when raw KiCad symbol and footprint fields can be normalized without changing the public BOM/PnP config schema.

BomPnpConfig

Rationale

The KiCad BOM, PnP, and JLC commands share one manufacturing config shape so workspace automation can use one naming, variant, grouping, and output policy.

Purpose

BomPnpConfig carries variant selection, BOM source and output kinds, grouping fields, DNP policy, PnP output fields, KiCad component-center placement mode, JLC CPL policy, and output path templates. The generated editable template is JSONC with one top block-comment documentation header, while used-config snapshots remain plain JSON.

Test Requirements

L3 verifies command execution through the public CLI, while L99 verifies the linked bom_pnp_config.a0.schema.json config contract for the public commands.

Working Definition

The interface is working when the same parsed config can drive BOM-only, PnP-only, and paired JLC outputs for a KiCad project with variants.

NormalizedBomComponent

Rationale

Grouped BOM and JLC BOM generation need canonical component records independent of whether the raw source came from schematic fields or PCB placement data.

Purpose

NormalizedBomComponent carries designator, value, footprint, description, sheet, DNP state, canonical fields, and field-source provenance for one BOM component.

Test Requirements

L3 generates raw and grouped BOM/JLC artifacts from Yoshi and verifies the ADXL355 variant flips the U2/U3 DNP state before output normalization.

Working Definition

The interface is working when configured BOM outputs can sort, group, split DNP lines, and emit JLC rows from normalized component records.

GroupedBomLine

Rationale

Review BOMs and JLC BOMs need deterministic grouped line items while preserving the list of designators and whether a line is fitted or DNP.

Purpose

GroupedBomLine carries quantity, sorted designators, representative canonical fields, DNP state, and the components that contributed to one grouped line.

Test Requirements

L3 runs JLC generation for the Yoshi ADXL355 variant and verifies a valid JLC BOM workbook is produced from grouped component data.

Working Definition

The interface is working when grouped CSV/XLSX and JLC BOM outputs can be emitted with stable quantities, designator ordering, and DNP handling.

NormalizedPlacement

Rationale

PnP and JLC CPL outputs need canonical placement records with units, layer naming, rotations, and alias-normalized fields independent of raw KiCad footprint objects.

Purpose

NormalizedPlacement carries designator, comment, side, footprint, center coordinates, rotation, units, description, parameters, canonical fields, and field-source provenance.

Test Requirements

L3 generates ADXL355 PnP JSON and JLC CPL XLSX outputs and verifies U2 is placed while U3 is omitted for that variant.

Working Definition

The interface is working when PnP JSON/CSV/XLSX and JLC CPL outputs sort and format the same normalized placement stream consistently.

KiCadPnpEntry

Rationale

The KiCad adapter needs a small raw placement carrier that matches the shared manufacturing normalizer without exposing KiCad parser objects to command code.

Purpose

KiCadPnpEntry carries one footprint placement, including designator, value/comment, side, footprint, KiCad component-center coordinates relative to the aux axis/drill-place file origin, rotation, description, and merged parameters.

Test Requirements

L3 validates that the Yoshi ADXL355 and IIM42352 variants produce mutually exclusive U2/U3 placement entries through the adapter.

Working Definition

The interface is working when variant-resolved KiCad assembly components convert into raw placements accepted by the shared PnP normalizer.

KiCadManufacturingDesign

Rationale

The public manufacturing commands need a KiCad-specific design adapter that offers the same high-level BOM, PnP, variant, and project-parameter surface used by the shared command logic.

Purpose

KiCadManufacturingDesign loads a KiCad project, schematic, or PCB, discovers variants, assembles schematic/PCB effective component state, and emits raw BOM or PnP records. KiCad PnP coordinates use the footprint placement point, matching KiCad's position-file exporter. They also match appz bom_cruncher: X is shifted by the aux axis origin, also called the drill/place file origin, and Y is shifted and inverted into the shared placement frame.

Test Requirements

L3 exercises Yoshi variants directly through the adapter and then through the public BOM, PnP, and JLC CLI commands.

Working Definition

The interface is working when KiCad variant overrides, DNP state, BOM eligibility, placement eligibility, aux-axis/drill-place-origin-relative placement coordinates, and project text variables reach the manufacturing output layer consistently.

KiCadProcess

Rationale

The KiCad workstation helper command needs one normalized process record so Windows and POSIX process discovery can feed the same CLI, JSON, and stop-planning paths.

Purpose

KiCadProcess carries the process ID, executable name, resolved executable path, command line, and inferred KiCad version for one running KiCad-family process.

Test Requirements

L0 verifies Windows process JSON parsing and version inference, and command-level tests verify dry-run stop output uses the normalized process record without terminating anything.

Working Definition

The interface is working when kicad running and kicad stop can report KiCad, pcbnew, eeschema, and kicad-cli processes with stable JSON fields across supported platforms.

Policy

When another public dataclass or major interface is added, it must be listed here with machine-readable test ownership before L99 signoff can pass.