Skip to content

timschmidt/hyperdrc

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

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

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.

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

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, acid traps, copper 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 and return-path coverage, RF via-fence review, gold fingers, ESD proximity, panelization clearance, mounting-hole grounding, plating, edge-clearance, distribution, spacing, copper-keepout review, panel-feature outline registration review, edge-plating intent, castellation pitch, component edge/hole clearance, dense-pad escape, 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, and impedance-control target/tolerance intent.
  • Assembly and test readiness: profile-driven component edge/hole/spacing clearance, connector rework spacing, fiducials and fiducial copper keepouts, tooling holes, mouse bites, testpoint coverage/accessibility including IPC-D-356 access-side, soldermask, and KiCad pad-side parity hints, testpoint copper clearance, pad-pair asymmetry, dense-pad escape, selective/wave solder keepouts, 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, 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, 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 system also 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": "sha256:0000"
    }
  ]
}
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