Skip to content

timschmidt/hyperdrc

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

28 Commits
benches
benches
 
 
docs
docs
 
 
examples
examples
 
 
proptest-regressions
proptest-regressions
 
 
src
src
 
 
.gitignore
.gitignore
 
 
Cargo.lock
Cargo.lock
 
 
Cargo.toml
Cargo.toml
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 

Repository files navigation

hyperdrc hyperdrc logo

hyperdrc is a Rust library and thin command line tool for PCB design-readiness checks over Gerber, KiCad, Excellon, and IPC-D-356 inputs. It uses the latest git version of csgrs for Gerber parsing, polygon offsets, and boolean geometry.

Current Status

hyperdrc is an active prototype with a broad regression suite for fabrication-readiness rules. It supports layer-level Gerber checks, net-aware KiCad checks, Excellon drill sidecars, IPC-D-356 electrical-test sidecars, JSON/JSON Lines/GeoJSON/SARIF/HTML/JUnit/text reports, GitHub Actions annotations, SVG review overlays, JSON waivers, JSON rule configuration, TransJLC conversion, Gerber-directory sidecar discovery, and structured input provenance with parser diagnostics.

The implemented checks are useful for CI and local design review, but they are not a replacement for a fabricator's final DFM/DRC pass. Some geometry and electrical intent remains conservative: KiCad oval and rectangular drill declarations are treated as circular keepouts using their larger dimension until exact routed-slot geometry is modeled, config-driven impedance checks verify declared stackup/reference intent rather than solving impedance, and IPC-D-356 parsing focuses on common test records and optional access-side/feature/soldermask hints rather than the full fixed-column dialect.

Workflow Overview

flowchart LR
    package["Release package"]
    gerber["Gerber layers"]
    kicad["KiCad board"]
    drill["Excellon drills"]
    ipc["IPC-D-356 net/test data"]
    sidecars["BOM, centroid, netlist, drawings, README"]
    config["JSON config and CLI overrides"]

    package --> gerber
    package --> kicad
    package --> drill
    package --> ipc
    package --> sidecars

    gerber --> load["Load and normalize inputs"]
    kicad --> load
    drill --> load
    ipc --> load
    sidecars --> load
    config --> rules["Resolve rule and package policies"]

    load --> checks["Run readiness checks"]
    rules --> checks
    checks --> report["Report model with stable finding IDs"]
    report --> outputs["Text, JSON, JSONL, GeoJSON, SARIF, HTML, JUnit"]
    report --> overlays["SVG review overlays"]
    report --> governance["Waivers, baselines, CI summaries"]
Loading

Library And CLI Split

The reusable API lives in src/lib.rs. It exposes parser modules, check modules, report types, rule policy modules, and the crate-root run entry point. run returns a RunOutcome containing the serializable Report instead of terminating the process, so Rust callers can embed hyperdrc in services, tests, or custom CI tooling.

The binary in src/main.rs is intentionally thin: it parses Cli with clap and calls hyperdrc::run_cli, which delegates to the library and then maps active findings to the traditional non-zero process exit status. Use --allow-findings for exploratory or report-only automation that should emit the full report and still return exit code 0 when findings remain.

Quick Start

Run all default checks against one or more Gerber layers:

cargo run -- path/to/top.gbr path/to/bottom.gbr

Load every Gerber-like file from a directory. The same directory is also scanned for common Excellon, IPC-D-356, BOM, centroid, netlist, README, fabrication drawing, assembly drawing, and rout/panel drawing sidecars:

cargo run -- --gerber-dir path/to/gerber-package

Include pre-production sidecars for manifest-driven readiness checks:

cargo run -- \
  --check file-manifest-readiness \
  --bom parts.csv \
  --centroid placement.txt \
  --netlist netlist.csv \
  --fab-drawing fab.dxf \
  --assembly-drawing assembly.dxf \
  --readme release-notes.md \
  --rout-drawing panel.dxf \
  --declared-copper-layer-count 4 \
  --kicad-pcb board.kicad_pcb \
  --excellon board.drl \
  top.gbr \
  bottom.gbr

Convert a Gerber package with TransJLC before loading the converted outputs:

cargo run -- \
  --convert-input path/to/source-gerbers \
  --conversion-output-dir build/hyperdrc-converted \
  --source-eda kicad \
  --transjlc-bin TransJLC \
  --conversion-arg --colorize \
  --conversion-arg --zip-name=upload

Run KiCad-aware checks against a .kicad_pcb file:

cargo run -- \
  --config examples/hyperdrc-config.json \
  --kicad-pcb board.kicad_pcb \
  --kicad-copper-layer F.Cu \
  --kicad-copper-layer B.Cu \
  --excellon panel-holes.drl \
  --ipc356 board.ipc \
  --format geojson

Generate a release report without failing the surrounding shell recipe on findings:

cargo run -- \
  --allow-findings \
  --kicad-pcb board.kicad_pcb \
  --format geojson

Run a specific check sequence:

cargo run -- \
  --check mask-island-keepout \
  --check copper-overlap \
  --keepout 0.2 \
  --pair 0:1 \
  --format json \
  path/to/mask.gbr path/to/copper.gbr

Layer roles are explicit zero-based indexes into the Gerber input list:

cargo run -- \
  --board-outline 2 \
  --copper-layer 0 \
  --copper-layer 1 \
  --paste-pair 3:0 \
  --mask-pair 0:4 \
  --silk-layer 5 \
  --silk-pair 5:4 \
  top.gbr bottom.gbr edge.gbr paste.gbr mask.gbr silk.gbr

Output formats are text, json, jsonl, geojson, sarif, github-annotations, html, and junit. JSON reports include stable violation IDs, severity, layers, polygon coordinates, point locations where applicable, short messages, structured parser diagnostics, and a structured input manifest. During a run, hyperdrc writes start/end status lines for runtime phases and per-check execution to stderr with elapsed time; each completed check also reports its new finding count. Expensive checks such as minimum copper neck, mask sliver, aperture/opening spacing, drill-to-copper clearance, and net spacing also emit intra-check progress lines so long-running layer or board work can be monitored. This leaves stdout safe for the selected report format. JSON Lines emits one run/input/diagnostic/violation object per line for streaming analytics. SARIF output preserves stable hyperdrc finding IDs and PCB geometry in result properties for CI/code-review systems. GitHub annotation output emits workflow commands that surface findings in Actions logs. HTML output embeds the SVG overlay with summary, parser diagnostic, input, and finding tables for review packets. JUnit XML output maps active findings into testcase failures for CI systems with JUnit publishers. SVG review overlays can be written with --svg-overlay violations.svg. Active-finding waiver stubs and baselines can be written with --waiver-stubs waiver-stubs.json and --baseline-file baseline.json. A current run can also be compared to a saved baseline with --baseline-reference previous.json and --baseline-diff-file baseline-diff.json, producing new, resolved, and unchanged finding buckets for release review.

Rule thresholds can be placed in a JSON config file and loaded with --config. CLI flags override config values. See examples/hyperdrc-config.json. The config also tunes package policy. package_profile accepts full-production, fabrication-only, assembly-only, or electrical-test; that profile sets default manifest expectations, and required_artifacts plus required_layers can override individual deliverables. Generated-output freshness is controlled with generated_date_stale_days. Assembly thresholds can be selected with assembly_profile (prototype, production-smt, double-sided-smt, test-fixture, hand-assembly, selective-solder, wave-solder, press-fit, or conformal-coating) and tuned field-by-field in assembly. Stackup readiness accepts process metadata plus built-in or custom fabrication_capability thresholds for finished thickness, copper layer count, copper weight, dielectric thickness, laminate Dk/Df, and Tg.

Readiness Coverage

The default suite covers the main hyperdrc readiness surfaces:

  • Layer geometry: copper overlap, edge clearance, mask and paste alignment, silkscreen clearance, minimum feature width, independently selectable polygon and trace-junction acid traps, whole-layer copper balance, first-class local copper-density balance, and board-outline sanity.
  • Drill and fabrication context: annular ring, drill spacing, drill-to-copper clearance, routed-slot readiness, castellation intent, aspect ratio, and cross-source drill-table consistency.
  • KiCad board context: net intent, high-speed and high-current heuristics, reference-plane, split-plane, and return-proximity coverage, RF keepout, antenna copper-free region, and via-fence review, gold fingers, ESD proximity and TVS clamp return-path proximity, bucketed voltage/protective-earth spacing, bucketed ESD protection/return, surge-protection keepouts, panelization clearance, mounting-hole grounding, plating, edge-clearance, distribution, spacing, copper-keepout review, same-net drill-break continuity review, different-net short isolation review, differential pair width, neck-down, skew, via proximity/return, and pair-to-pair spacing review, high-current pad-entry and via-return support review, switch-node and inductor copper keepouts, panel-feature outline registration review, edge-plating intent, castellation pitch, component edge/hole clearance, dense-pad escape, pad/via spacing, mask-bridge review, bucketed thermal copper-area/spacing/keepout review, thermal-via count/distribution, and config-driven stackup/net-class constraints for material, surface finish, laminate Dk/Df/Tg, soldermask process/color, IPC/fabricator class, fabrication capability thresholds, width, clearance, current, voltage, reference-plane, layer-count, via-count, approximate length/skew, differential-pair spacing, differential-pair return/guard proximity, mixed-signal partitioning, and impedance-control target/tolerance intent. Companion checks for thermal-via distribution, bucketed thermal copper-area/spacing/keepout review, bucketed RF/antenna keepout, RF via-fence, TVS/ESD return path, bucketed switch-node and inductor copper keepout, bucketed sensitive-net/mixed-signal partitioning, and dense-pad via/mask review are also first-class CLI checks rather than only hidden side effects of broader review groups.
  • Assembly and test readiness: profile-driven component edge and bucketed hole/spacing clearance, bucketed connector rework spacing, fiducials and fiducial copper keepouts with nearby-blocker bucketing, tooling holes, mouse bites, testpoint coverage/accessibility including IPC-D-356 access-side, soldermask, KiCad pad-side parity hints, bucketed component/probe spacing review, testpoint copper clearance, bucketed pad-pair asymmetry, dense-pad escape, bucketed selective/wave solder and press-fit keepouts, conformal-coating keepouts, and IPC-D-356 coverage.
  • Production package readiness: Gerber package completeness, sidecar discovery, BOM/centroid/netlist structure, README release notes, fabrication and assembly drawings, rout drawings, order-parameter consistency, generated-date freshness, duplicate layer/island-geometry detection, tiny and skinny layer-fragment detection, side-role filename conflict detection, paste/mask companion checks, configurable required artifacts/layers, centroid unit/origin/rotation convention handoff, BOM compliance/traceability/source-control evidence for sensitive rows, package-level polarity/MSL handoffs, polarized same-package centroid orientation review, dense-package reflow-profile handoff, tall-component height/keepout handoff, thermal-validation handoff for heat-dissipating rows, low-standoff cleanliness handoff, press-fit and wire-bond process/drawing handoff, fabrication marking-zone handoff, and surface-finish handoff notes.

The check implementations and exact ownership are documented in src/checks. The roadmap and remaining gaps are tracked in docs/design-readiness-plan.md.

Important tunables include --keepout, --clearance, --min-width, --min-mask-width, --acid-trap-angle, --annular-ring, --drill-clearance, --board-thickness, --max-drill-aspect-ratio, --min-paste-area-ratio, --max-paste-area-ratio, --stencil-thickness, --min-stencil-area-ratio, --max-copper-imbalance-ratio, --net-clearance, --registration-tolerance, --panel-clearance, --ipc356-tolerance, --min-area, --max-layer-area, and --generated-date-stale-days.

Waivers And CI

Waiver files are JSON and can suppress findings by id, check, layers, and message text. The default suite includes waiver-governance, and it can also be selected explicitly; it emits readiness warnings for incomplete waiver metadata so production waivers remain auditable: reason, owner, review_date, source, and geometry_hash are expected. review_date must be an ISO YYYY-MM-DD date and is warned when it has expired, so standing exceptions stay visible in pre-production review. A compact CI summary can be written with --summary-file. Proposed waiver stubs and active-finding baselines can be generated without suppressing anything. Baseline comparison is an audit artifact: it classifies drift in the active finding set, but waivers remain the mechanism for intentionally suppressing accepted findings.

{
  "waivers": [
    {
      "check": "acid-trap-candidate",
      "layers": ["F.Cu"],
      "message_contains": "below 30",
      "reason": "accepted connector footprint geometry",
      "owner": "DRC reviewer",
      "review_date": "2027-05-01",
      "source": "https://jira.example/issues/123",
      "geometry_hash": "hyperdrc-geometry-v1:0123456789abcdef"
    }
  ]
}
cargo run -- \
  --kicad-pcb board.kicad_pcb \
  --waiver waivers.json \
  --summary-file summary.json \
  --svg-overlay violations.svg \
  --waiver-stubs waiver-stubs.json \
  --baseline-file baseline.json \
  --baseline-reference previous-baseline.json \
  --baseline-diff-file baseline-diff.json

Repository Map

Each folder has its own local README with the hyperdrc-specific ownership details for that part of the tree:

  • src: Rust crate structure, runtime pipeline, parsers, reports, configuration, and submodule map.
  • src/checks: all design-readiness checks grouped by layer, drill, board, mechanical, stencil, assembly, manifest, artifact, surface-finish, and helper responsibilities.
  • src/geometry: polygon construction, sketch conversion, shape extraction, and geometry-test expectations.
  • src/kicad: KiCad board model, S-expression parsing, graphics parsing, and current parser scope.
  • docs: roadmap, design-readiness backlog, and visual assets.
  • docs/testing.md: test-suite guide explaining what the current tests look for and how they exercise hyperdrc.
  • examples: runnable configuration examples.
  • benches: benchmark and smoke-performance entry points.
  • proptest-regressions: persisted fuzz and property-test regression seeds.

Known Gaps

Not yet modeled: exact routed slot shapes, plated-slot/edge-plating electrical semantics, KiCad silkscreen text side/mirroring, per-pad paste or mask attributes, fabricator-specific rule-deck libraries, true impedance solving, routed differential-pair length/skew matching, semantic XLS/XLSX spreadsheet parsing, richer parser diagnostics for all input formats, and ODB++/IPC-2581 input.

See docs/design-readiness-plan.md for the long-form design-readiness roadmap.

References

hyperdrc comments and readiness heuristics cite these design and manufacturing references where the code implements related checks. Entries are kept in MLA style so they can be copied into engineering review notes.

About

PCB design-readiness checks using csgrs

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages