design

Usage

altium-cruncher design project.PrjPcb -o output/design_review
altium-cruncher design-review project.PrjPcb
altium-cruncher dr schematic.SchDoc

Arguments

file accepts .SchDoc or .PrjPcb. When omitted, the command attempts project auto-detection in the current directory. -o selects the output directory. --no-indexes omits optional lookup indexes from the design JSON. design-review and dr are aliases for the same command and output contract.

Output

The command defaults to output/design_review and writes design_review_manifest.json with additive schema altium_cruncher.design_review_manifest.b1. The frozen B0 schema remains published for archived bundles. Other artifacts include README.md, design/<input>_design.json from AltiumDesign.to_json(), notes/<input>_notes.jsonc, serialized SchDoc/PcbDoc JSON under json/schdoc/ and json/pcbdoc/, schematic SVGs under sch/, and PCB copper-layer review SVGs under pcb/layers/ for project inputs with boards.

Every newly produced pcb_svgs[] entry contains a design_rules_and_classes path to pcb/<board>__design-rules-and-classes.json. Its other per-board paths are manifest for pcb/<board>__views.json and layer_outputs[].file for pcb/layers/<board>__<layer>.svg. Consumers use the exact manifest paths rather than guessing filenames. The altium_cruncher.pcb_routing_context.a0 sidecar is a compact projection of authored net classes, differential-pair definitions/classes, reverse net memberships, and typed design rules. The direct filename describes the artifact contents while the manifest remains the discovery authority. The manifest field remains optional in the B1 schema so B1 is additive, while workflow tests enforce the new producer guarantee.

Design b0 is the primary schematic semantic model: its required compiled_schematic_graph owns realized pages, hierarchy, components, local nets, terminals, bindings, and scoped drawing links; physical_page_metadata carries only Altium channel/room presentation facts. SchDoc and PrjPcb schematic manifest and SVG roots record page_occurrence_ref plus artifact_key="sch.dwg_scene"; source groups join through element_id. Compiled SVG metadata uses the Cruncher-owned breaking altium_cruncher.schematic.svg.enrichment.b0 contract and schematic-enrichment-b0 metadata id. The SVG metadata does not duplicate the graph.

Each PCB review SVG follows the default pcb-svg layer-output contract but limits physical layers to copper layers, including inner copper layers when present; board outline, board cutouts, drills, and slots are included. Layer classification is V7-aware: copper detection is layer-family based, including StackUpX-backed extended signal layers and via layer_start/layer_end spans. Primitives on Mechanical17+ layers retain their real layer identity. Composed PCB views and assembly/HLR virtual layers are intentionally omitted from dr; use pcb-svg when those heavier views are needed. The command logs each generated SVG and JSON artifact as it is written. The notes artifact uses the default review filter and suppresses title-block/sheet-template owned text.

PCB routing evidence boundary

The routing context records authored intent, not evaluated compliance. Its required evidence object states that Cruncher did not evaluate Altium rule scopes, did not run DRC during this export, and includes no DRC violation result. This says nothing about whether a user previously ran Altium DRC. Actual pass/fail claims require a provenance-bearing native DRC execution or report.

The mixed PcbDoc class table is filtered: PcbNetClassKind.NET rows become net classes and PcbNetClassKind.DIFF_PAIR rows become differential-pair classes. Stored members and uniquely resolved joins remain separate; empty classes are never expanded because their name resembles All Nets or All Differential Pairs. A net may belong to multiple classes.

_P and _N are common naming conventions, never polarity evidence. Pair membership and positive/negative polarity come from the authored differential-pair record and also work for unconventional net names. Exact scope expressions, priorities, nullable common fields, typed constraints, and unmodeled rule fields are preserved. A conservative lexical scanner records literal InNetClass and InDifferentialPairClass calls from both expressions and resolves them against the corresponding exported class table. Resolution proves only that a literal class name has one matching exported row; it does not evaluate the complete Altium query or establish applicability. Unsupported query functions remain in the exact expression without inferred semantics. Missing and ambiguous supported references produce warnings. Cruncher does not choose an effective rule. Differential-pair routing gap and width settings must not be mistaken for a complete clearance result; applicable Clearance rules remain separate evidence.

Join a sidecar net to routed SVG primitives using exact data-net or data-net-uid. data-net-class and data-net-classes can corroborate the relationship when present. The sidecar resolves source references case-insensitively, while the pinned SVG renderer's class lookup is exact-case, so an absent SVG class attribute does not override a proven sidecar join.

Review identity and compiler evidence

DR explicitly requests include_compile_metadata=True, preserving the released Design b0 compile and diagnostics sections even with --no-indexes. Compiler diagnostics and graph terminal resolution diagnostics describe compiler health and evidence limits; they are not automatically electrical-design defects. Unresolved evidence does not prove an open circuit, and absence of diagnostics does not certify the circuit. Warnings alone do not fail bundle generation. The full beta raw compiler model is not exported.

Component labels are not identities. SVG enrichment uses the physical IR's physical_page.page_occurrence_ref and physical_page.id to bind a canonical graph page to the raw physical document. Within that document, graph component source_identity["sch.source_key.source_uuid"] matches a unique Design row's source_unique_id and physical_sheet_id. Duplicate or missing candidates retain graph identity and labels without borrowed value or variant attributes. Some multipart bodies have no matching aggregate source UID in Design b0; their missing enrichment does not imply missing value or not-fitted state. Opaque IDs are not parsed, and raw compiler IDs are not equated to graph IDs.

The generated README explains that classification.pin_count is the combined compiled schematic count for the complete component. Do not multiply by part count, divide it to infer body counts, or use it as proof of physical package-pad completeness. Per-body inspection must respect the source body's selected part, display mode, and pin visibility. Power-tree review follows scoped graph connectivity; optional indexes and non-unique aliases only aid navigation. These instructions target the pinned Monkey 2026.9.22 contracts without anticipating future fields.

PCB routing context compactness

On the committed RT Super C1 fixture, the A0 sidecar is 65,099 bytes versus 24,640,889 bytes for the formatted raw PcbDoc JSON (0.264%). Seven in-memory projections had a median builder time of 0.953 ms on the qualification machine. This measures the projection from an already parsed PcbDoc, matching DR's reuse boundary; it does not include board parsing or SVG rendering.

Tests

L0 verifies help and aliases. Unit workflow tests synthesize SchDoc and PcbDoc inputs, then verify the dr alias writes design JSON, notes JSONC, document JSON, schematic SVG, copper-only PCB review SVGs, routing context, manifest, and README artifacts while omitting composed assembly views. Routing-context tests cover mixed class kinds, class/pair/net joins, unconventional polarity names, duplicate references, nullable rules, exact compound scopes, conservative scope-reference extraction, missing and ambiguous scope references, future fields, non-JSON diagnostics, empty boards, deterministic output, SVG metadata joins, collision-safe paths, stale-output exclusion, B1 output, and frozen B0 validation. RT Super exercises a real six-member SDIO class and matched-length rule; PiMX8 exercises multiple class calls in a compound expression and a differential-pair-class reference. Identity regressions in tests/test_design_review_identity.py cover duplicate labels, repeated-source page scope, multipart bodies, and missing or ambiguous evidence. L3 continues to verify real project output through the same command.