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.

PcbLayerStepConfig

Rationale

The layer STEP command needs a durable config object that preserves the v2 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, colors, 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 overlays, and manifests.

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, drill policy, pad color rules, and body-splitting 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 simple, 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.

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.v1.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.

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.