gerberdiff 0.29.0__tar.gz → 0.30.0__tar.gz

{gerberdiff-0.29.0 → gerberdiff-0.30.0}/.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: false
 contact_links:
   - name: Question / discussion
-    url: https://github.com/CameronBrooks11/gerberdiff/discussions
+    url: https://github.com/orgs/heibench/discussions
     about: Ask questions and discuss ideas in GitHub Discussions

{gerberdiff-0.29.0 → gerberdiff-0.30.0}/.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
     name: Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
@@ -32,7 +32,7 @@ jobs:
     name: Type check
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
@@ -51,7 +51,7 @@ jobs:
           - python-version: "3.11"
             os: windows-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true

gerberdiff-0.30.0/.github/workflows/docs.yml

@@ -0,0 +1,71 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "gerberdiff/**"
+      - "CHANGELOG.md"
+      - "CONTRIBUTING.md"
+      - ".github/workflows/docs.yml"
+      # The site is built with `uv sync --group docs`, so what ships is decided
+      # by the lock, not just by the sources above. Without these two paths a
+      # dependency fix lands on main and the deployed site keeps serving the old
+      # build -- which is how mkdocs-material 9.7.6 stayed live on the published
+      # docs after GHSA-xvg9-69gf-fjrf was already patched in the lock.
+      - "uv.lock"
+      - "pyproject.toml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "gerberdiff/**"
+      - "CHANGELOG.md"
+      - "CONTRIBUTING.md"
+      - ".github/workflows/docs.yml"
+      - "uv.lock"
+      - "pyproject.toml"
+  # Lets the site be rebuilt without inventing a commit -- there was previously
+  # no way to redeploy at all.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --group docs
+      - run: uv run mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v5
+        if: github.event_name == 'push'
+        with:
+          path: site/
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

{gerberdiff-0.29.0 → gerberdiff-0.30.0}/.github/workflows/release.yml

@@ -14,7 +14,7 @@ jobs:
     name: Build distribution
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
@@ -41,7 +41,7 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: actions/download-artifact@v8
         with:
           name: dist

{gerberdiff-0.29.0 → gerberdiff-0.30.0}/CHANGELOG.md

@@ -7,6 +7,91 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.30.0] - 2026-09-06
+
+### Changed
+
+- **BREAKING -- the exit-code contract now matches partspec and netspec**
+  ([A3]). `0` no differences, `1` differences (with `--fail-on-diff`), `2` the
+  comparison could not be completed, `4` an input could not be read or parsed,
+  `64` usage (`EX_USAGE`). Previously `2` meant a parse error and `1` doubled as
+  both "differences found" and "could not write the output file". A gate written
+  `[ $? -eq 0 ]` is unaffected; one that treated `2` as a parse failure must now
+  read `4`.
+- **Geometry report schema `version` 2 -> 3**, adding `summary.outcome`,
+  `summary.unrepresented` and a per-layer `unrepresented`. Additive: every v2
+  field keeps its meaning.
+
+### Added
+
+- **`geomdiff` has a third outcome, and says what it could not model** ([A3]) --
+  `identical` | `different` | `indeterminate`. A stroke drawn with a macro or
+  block aperture is not modelled by the geometry engine, and used to vanish: a
+  board with an added trace reported `0 changes` at exit `0`, with JSON
+  byte-identical to comparing a board against a copy of itself, while the raster
+  engine reported the change. The two engines answered the same question
+  differently and the geometry one gave the dangerous answer. Such operations are
+  now counted in `summary.unrepresented`, named on stderr, and make the outcome
+  `indeterminate` at exit `2` -- which does not wait for `--fail-on-diff`, since
+  that flag chooses whether a *difference* fails, not whether the tool could look.
+  `different` outranks `indeterminate`, so one unmodellable stroke cannot mask a
+  trace that moved.
+
+### Fixed
+
+- **Draw operations using an undefined aperture are no longer dropped in
+  silence** ([#17]) -- selecting a D-code that was never defined (or drawing
+  before any `Dnn` selection at all) left the flash or stroke carrying an
+  aperture index with no definition behind it.  Every consumer treated that
+  as nothing to draw: both geometry emit helpers returned early and the
+  raster renderer drew nothing, with no diagnostic at any severity.  `diff`
+  and `geomdiff` then reported `0 changes` at exit `0`, and the JSON report
+  was byte-identical to a comparison of two genuinely identical boards -- so
+  a real fabrication change could pass a `--fail-on-diff` gate invisibly.
+  The parser now emits an `Error` diagnostic at the offending draw
+  operation, which the existing promotion path turns into exit `2` for
+  `parse`, `render`, `diff` and `geomdiff` alike.  D02 moves and G36/G37
+  region contours consume no aperture and are unaffected.
+
+- **Degenerate region contours no longer leak line geometry** -- a G36/G37
+  contour whose points are collinear produced a zero-area `MultiLineString`
+  from `make_valid` that flowed into the geometry engine; region expansion
+  now keeps only polygonal parts.
+
+### Changed
+
+- Local coverage floor aligned with the CI gate (`fail_under` 85 -> 90;
+  actual coverage is ~94%).
+- Stale documentation corrected: the overlay-PNG colour table no longer
+  lists the removed "yellow" class; `SECURITY.md` supported versions
+  updated from 0.14.x to 0.29.x; `CONTRIBUTING.md` blesses
+  conventional-commit prefixes (matching recent history).
+- Package `__init__` modules for `parse`, `render`, `diff`, and `export`
+  gained one-line docstrings.
+
+### Added
+
+- **Documentation site** at <https://heibench.github.io/gerberdiff/>
+  -- MkDocs + Material with mkdocstrings API reference, MathJax for the
+  LaTeX notation already used in the docs, and Changelog/Contributing
+  included via snippets. Built strictly and deployed to GitHub Pages by
+  `.github/workflows/docs.yml` on every push to `main` that touches docs
+  or the package.
+
+- Edge-case test suite for the geometry engine's guard paths: block
+  nesting depth limit, invalid layer indices, zero-dimension apertures,
+  degenerate regions and strokes, macro flash dispatch, the
+  equal-geometry attribution guard, and driver diagnostic forwarding.
+
+## [0.29.1] - 2026-06-13
+
+### Changed
+
+- **Package metadata reflects both engines** -- the PyPI `description`
+  and the CLI group help text described only the raster engine; both now
+  cover the raster overlay and geometry diff pipelines. Added `geometry`
+  and `shapely` to the package keywords. No behaviour changes.
+
 ## [0.29.0] - 2026-06-12
 
 ### Added
@@ -77,6 +162,103 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Raster-engine tests skip cleanly when cairo is unavailable, which
   fixes the previously failing Windows CI job.
 
+- **Project renamed from `gerberdelta` to `gerberdiff`** (2026-04-25,
+  unreleased at the time). 0.29.0 is the first published release under
+  the new name; no release was ever made as `gerberdelta`. The rename
+  window also included: docs reorganised to lowercase-kebab filenames
+  with split CLI/API references, an ASCII-only character policy sweep,
+  LaTeX math notation for equations in docs, and strict mypy
+  annotations across the test suite.
+
+## [0.28.0] - 2026-04-25
+
+### Added
+
+- **Render/diff regression coverage** -- 411 lines of new tests across
+  the renderer, draw-ops, diff engine, and parser: incremental (G91)
+  coordinates, step-and-repeat tiling, layer transforms (LM/LR/LS),
+  clear-polarity compositing, region merge cascade, polygon aperture
+  rotation, macro `unit_scale`, `alignment_offset`, and pixel-level
+  render verification. No production code changes.
+
+## [0.27.0] - 2026-04-25
+
+### Changed
+
+- **`CompiledRender` cached per `BlockAperture`** -- repeated flashes of
+  the same block aperture no longer recompile its draw-op groups on
+  every flash. The cache is keyed by `id(block_ap)` and evicted by a
+  `weakref` finalizer when the aperture is garbage-collected, so stale
+  ids cannot produce false hits.
+
+## [0.26.0] - 2026-04-25
+
+### Fixed
+
+- **Rect/obround stroke width** -- D01 strokes with rectangle or obround
+  apertures are drawn with line width `max(width, height)` instead of
+  `min(width, height)`, so traces whose long axis aligns with the stroke
+  direction (the common case) are no longer under-stroked; documented as
+  an approximation pending geometry-aware rendering.
+- **Macro evaluation failures no longer abort the render** -- a macro
+  aperture whose primitive evaluation raises is skipped with a
+  `UserWarning` instead of crashing the whole render pass.
+
+## [0.25.0] - 2026-04-25
+
+### Fixed
+
+- **Parser correctness sweep** --
+  - arc bounding boxes account for axis-extrema crossings (0/90/180/270
+    degrees), not just the endpoints;
+  - step-and-repeat tiles expand the image bounding box and respect
+    layer polarity;
+  - block aperture (`%AB%`) parsing isolates state correctly (nested
+    apertures/layers no longer leak into the parent image);
+  - `_apply_format` no longer truncates coordinates with more integer
+    digits than the format statement declares;
+  - referencing an unknown macro in an aperture definition is an
+    `Error`-severity diagnostic (was silently tolerated).
+
+## [0.24.0] - 2026-04-25
+
+### Changed
+
+- **`DiffResult.has_changes` is a computed property** -- derived from the
+  layer results instead of stored at construction, so it cannot drift
+  from the data.
+- **Excellon parser refactored** -- the nonlocal-closure state pattern is
+  replaced with explicit local parser state; behaviour unchanged.
+
+## [0.23.0] - 2026-04-25
+
+### Added
+
+- **`compute_full_diff`** -- directory-vs-directory diff as a single
+  public API call (parse, match, diff, assemble `DiffResult`), with
+  `overlay_callback` and `on_diagnostic` hooks.
+- **All IR and result types exported** from the top-level package with
+  an `__all__` list; README gains API examples.
+
+### Changed
+
+- `diff_cmd` rewritten on top of `compute_full_diff` (the CLI no longer
+  duplicates the orchestration logic).
+
+## [0.22.0] - 2026-04-25
+
+### Added
+
+- **`docs/schema.md`** -- canonical JSON report schema documentation.
+- **CI hardening** -- coverage gate (`--cov-fail-under=90`), a Windows
+  test job in the matrix, and a non-ASCII character check.
+
+### Changed
+
+- **`EXCELLON_SUFFIXES` is public** -- renamed from `_EXCELLON_SUFFIXES`
+  in `diff/layer_matcher.py`; it is part of the de-facto API used by the
+  CLI and downstream callers.
+
 ## [0.21.0] - 2026-04-25
 
 ### Changed
@@ -242,6 +424,10 @@ saved_bbox, saved_layer_idx)` with a named `_BlockFrame` dataclass so that
 
 ### Changed
 
+- **License changed from AGPL-3.0 to Apache-2.0** so the tool can be
+  used commercially without copyleft obligations. (Landed immediately
+  before this version's other changes; recorded here for completeness.)
+
 - **Domain model rename** -- `Net` renamed to `DrawOp` and `NetState` renamed to `CoordState`
   throughout the codebase. The term "net" belongs to EDA net-list semantics; the IR types
   represent drawing primitives and coordinate-system snapshots, not electrical nets.
@@ -529,19 +715,37 @@ merge_tolerance) -> SingleLayerDiff`.
 - mypy `strict=true`, `warn_unused_ignores=true`, `cairocffi.*` override for missing stubs.
 - 2 smoke tests in `tests/test_scaffold.py`.
 
-[Unreleased]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.29.0...HEAD
-[0.29.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.21.0...v0.29.0
-[0.14.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.13.0...v0.14.0
-[0.13.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.12.0...v0.13.0
-[0.12.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.11.0...v0.12.0
-[0.11.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.10.0...v0.11.0
-[0.10.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.9.0...v0.10.0
-[0.9.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.8.0...v0.9.0
-[0.8.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.7.0...v0.8.0
-[0.7.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.6.0...v0.7.0
-[0.6.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.5.0...v0.6.0
-[0.5.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.4.0...v0.5.0
-[0.4.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.3.0...v0.4.0
-[0.3.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.2.0...v0.3.0
-[0.2.0]: https://github.com/CameronBrooks11/gerberdiff/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/CameronBrooks11/gerberdiff/releases/tag/v0.1.0
+[#17]: https://github.com/heibench/gerberdiff/issues/17
+[A3]: https://heibench.com/adjudications.html
+[Unreleased]: https://github.com/heibench/gerberdiff/compare/v0.30.0...HEAD
+[0.30.0]: https://github.com/heibench/gerberdiff/compare/v0.29.1...v0.30.0
+[0.29.1]: https://github.com/heibench/gerberdiff/compare/v0.29.0...v0.29.1
+[0.29.0]: https://github.com/heibench/gerberdiff/compare/9ffd4c8f...v0.29.0
+[0.28.0]: https://github.com/heibench/gerberdiff/compare/b6b6b98d...9ffd4c8f
+[0.27.0]: https://github.com/heibench/gerberdiff/compare/963eb957...b6b6b98d
+[0.26.0]: https://github.com/heibench/gerberdiff/compare/6162e435...963eb957
+[0.25.0]: https://github.com/heibench/gerberdiff/compare/e2519ec8...6162e435
+[0.24.0]: https://github.com/heibench/gerberdiff/compare/91c154d4...e2519ec8
+[0.23.0]: https://github.com/heibench/gerberdiff/compare/458734f9...91c154d4
+[0.22.0]: https://github.com/heibench/gerberdiff/compare/1c96a7b8...458734f9
+[0.21.0]: https://github.com/heibench/gerberdiff/compare/4d1201fe...1c96a7b8
+[0.20.0]: https://github.com/heibench/gerberdiff/compare/ba9a5015...4d1201fe
+[0.19.0]: https://github.com/heibench/gerberdiff/compare/c502171a...ba9a5015
+[0.18.0]: https://github.com/heibench/gerberdiff/compare/10f8f392...c502171a
+[0.17.0]: https://github.com/heibench/gerberdiff/compare/b04813ea...10f8f392
+[0.16.0]: https://github.com/heibench/gerberdiff/compare/3044033b...b04813ea
+[0.15.0]: https://github.com/heibench/gerberdiff/compare/9b4e3401...3044033b
+[0.14.0]: https://github.com/heibench/gerberdiff/compare/1a399ea2...9b4e3401
+[0.13.0]: https://github.com/heibench/gerberdiff/compare/c0672ea8...1a399ea2
+[0.12.0]: https://github.com/heibench/gerberdiff/compare/1bbfb235...c0672ea8
+[0.11.0]: https://github.com/heibench/gerberdiff/compare/2d1573ad...1bbfb235
+[0.10.0]: https://github.com/heibench/gerberdiff/compare/6691b195...2d1573ad
+[0.9.0]: https://github.com/heibench/gerberdiff/compare/2e944edc...6691b195
+[0.8.0]: https://github.com/heibench/gerberdiff/compare/46b463de...2e944edc
+[0.7.0]: https://github.com/heibench/gerberdiff/compare/5b9212fa...46b463de
+[0.6.0]: https://github.com/heibench/gerberdiff/compare/e12ff13f...5b9212fa
+[0.5.0]: https://github.com/heibench/gerberdiff/compare/6330d0cb...e12ff13f
+[0.4.0]: https://github.com/heibench/gerberdiff/compare/f63a51a3...6330d0cb
+[0.3.0]: https://github.com/heibench/gerberdiff/compare/3f1d1909...f63a51a3
+[0.2.0]: https://github.com/heibench/gerberdiff/compare/674251dd...3f1d1909
+[0.1.0]: https://github.com/heibench/gerberdiff/compare/2eeb692...674251dd

{gerberdiff-0.29.0 → gerberdiff-0.30.0}/CONTRIBUTING.md

@@ -7,7 +7,7 @@ Thank you for your interest in contributing to **gerberdiff**!
 Requires Python >= 3.11 and [uv](https://docs.astral.sh/uv/).
 
 ```sh
-git clone https://github.com/CameronBrooks11/gerberdiff.git
+git clone https://github.com/heibench/gerberdiff.git
 cd gerberdiff
 uv sync --dev
 ```
@@ -36,8 +36,11 @@ All three must pass with no errors before a PR will be merged. CI enforces this
 
 ## Commit messages
 
-- Single sentence, imperative mood, no trailing period
-- No phase or ticket prefix required (e.g. `Add viewport clamping for negative-Y boards`)
+- Single-sentence subject, imperative mood, no trailing period
+- [Conventional-commit](https://www.conventionalcommits.org/) type prefixes
+  (`feat:`, `fix:`, `docs:`, `test:`, `perf:`, `chore:`, `ci:`) are
+  encouraged and used throughout recent history
+  (e.g. `feat(geometry): add geometry diff engine core`)
 
 ## Pull request checklist
 
@@ -62,7 +65,7 @@ many fonts and meaningless to grep.
 **Banned characters and their ASCII replacements:**
 
 | Character         | Codepoint | Use instead |
-| ----------------- | --------- | ----------- | ------ |
+| ----------------- | --------- | ----------- |
 | em dash           | U+2014    | `--`        |
 | en dash           | U+2013    | `-`         |
 | ellipsis          | U+2026    | `...`       |
@@ -75,8 +78,8 @@ many fonts and meaningless to grep.
 | almost-equal      | U+2248    | `~=`        |
 | plus-minus        | U+00B1    | `+/-`       |
 | degree            | U+00B0    | `deg`       |
-| superscript 2     | U+00B2    | `^2`        |
-| box-drawing chars | U+2500+   | `-`, `      | `, `+` |
+| superscript 2     | U+00B2    | `^2`            |
+| box-drawing chars | U+2500+   | `-`, `\|`, `+`  |
 
 To check a branch before committing:
 
@@ -106,4 +109,5 @@ EOF
 ## License
 
 By contributing you agree that your contributions will be licensed under the
-[Apache-2.0](LICENSE) licence.
+[Apache-2.0](https://github.com/heibench/gerberdiff/blob/main/LICENSE)
+licence.

{gerberdiff-0.29.0 → gerberdiff-0.30.0}/PKG-INFO

@@ -1,15 +1,15 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: gerberdiff
-Version: 0.29.0
-Summary: Visual raster diff tool for Gerber/Excellon PCB design files
-Project-URL: Homepage, https://github.com/CameronBrooks11/gerberdiff
-Project-URL: Repository, https://github.com/CameronBrooks11/gerberdiff
-Project-URL: Changelog, https://github.com/CameronBrooks11/gerberdiff/blob/main/CHANGELOG.md
-Project-URL: Issues, https://github.com/CameronBrooks11/gerberdiff/issues
+Version: 0.30.0
+Summary: Diff tool for Gerber/Excellon PCB files: visual raster overlays and attributed vector-geometry change analysis
+Project-URL: Homepage, https://github.com/heibench/gerberdiff
+Project-URL: Repository, https://github.com/heibench/gerberdiff
+Project-URL: Changelog, https://github.com/heibench/gerberdiff/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/heibench/gerberdiff/issues
 Author-email: Cameron Brooks <cameronbrooks11@gmail.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
-Keywords: diff,eda,excellon,gerber,grbl,kicad,pcb
+Keywords: diff,eda,excellon,geometry,gerber,grbl,kicad,pcb,shapely
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Manufacturing
@@ -33,7 +33,8 @@ Description-Content-Type: text/markdown
 
 # gerberdiff
 
-[![CI](https://github.com/CameronBrooks11/gerberdiff/actions/workflows/ci.yml/badge.svg)](https://github.com/CameronBrooks11/gerberdiff/actions/workflows/ci.yml)
+[![CI](https://github.com/heibench/gerberdiff/actions/workflows/ci.yml/badge.svg)](https://github.com/heibench/gerberdiff/actions/workflows/ci.yml)
+[![Docs](https://github.com/heibench/gerberdiff/actions/workflows/docs.yml/badge.svg)](https://heibench.com/gerberdiff/)
 [![PyPI](https://img.shields.io/pypi/v/gerberdiff)](https://pypi.org/project/gerberdiff/)
 [![Python](https://img.shields.io/pypi/pyversions/gerberdiff)](https://pypi.org/project/gerberdiff/)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
@@ -82,6 +83,8 @@ for layer in result.layers:
 
 ## Docs
 
+Full documentation site: **<https://heibench.com/gerberdiff/>**
+
 | Topic                | File                                         |
 | -------------------- | -------------------------------------------- |
 | CLI reference        | [docs/cli.md](docs/cli.md)                   |

{gerberdiff-0.29.0 → gerberdiff-0.30.0}/README.md

@@ -1,6 +1,7 @@
 # gerberdiff
 
-[![CI](https://github.com/CameronBrooks11/gerberdiff/actions/workflows/ci.yml/badge.svg)](https://github.com/CameronBrooks11/gerberdiff/actions/workflows/ci.yml)
+[![CI](https://github.com/heibench/gerberdiff/actions/workflows/ci.yml/badge.svg)](https://github.com/heibench/gerberdiff/actions/workflows/ci.yml)
+[![Docs](https://github.com/heibench/gerberdiff/actions/workflows/docs.yml/badge.svg)](https://heibench.com/gerberdiff/)
 [![PyPI](https://img.shields.io/pypi/v/gerberdiff)](https://pypi.org/project/gerberdiff/)
 [![Python](https://img.shields.io/pypi/pyversions/gerberdiff)](https://pypi.org/project/gerberdiff/)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
@@ -49,6 +50,8 @@ for layer in result.layers:
 
 ## Docs
 
+Full documentation site: **<https://heibench.com/gerberdiff/>**
+
 | Topic                | File                                         |
 | -------------------- | -------------------------------------------- |
 | CLI reference        | [docs/cli.md](docs/cli.md)                   |

{gerberdiff-0.29.0 → gerberdiff-0.30.0}/SECURITY.md

@@ -2,17 +2,19 @@
 
 ## Supported versions
 
+Only the latest released minor version is supported.
+
 | Version | Supported |
 | ------- | --------- |
-| 0.14.x  | Yes       |
-| < 0.14  | No        |
+| 0.29.x  | Yes       |
+| < 0.29  | No        |
 
 ## Reporting a vulnerability
 
 **Do not open a public issue for security vulnerabilities.**
 
 Please report them via
-[GitHub private security advisories](https://github.com/CameronBrooks11/gerberdiff/security/advisories/new).
+[GitHub private security advisories](https://github.com/heibench/gerberdiff/security/advisories/new).
 
 Include:
 

gerberdiff-0.30.0/docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

{gerberdiff-0.29.0 → gerberdiff-0.30.0}/docs/cli.md

@@ -1,5 +1,22 @@
 # CLI reference
 
+
+## Exit codes
+
+Shared across the org's tools, so a script can branch on them the same way for
+`gerberdiff`, `partspec` and `netspec`.
+
+| code | meaning |
+| ---- | -------- |
+| `0`  | no differences, and everything was modelled |
+| `1`  | differences found (with `--fail-on-diff`) |
+| `2`  | part of the comparison could not be made -- **not** a statement about the boards |
+| `4`  | an input could not be read or parsed -- also not a statement about the boards |
+| `64` | usage (`EX_USAGE`): bad arguments, or an output file that exists without `--overwrite` |
+
+`2` does not wait for `--fail-on-diff`. That flag chooses whether a *difference* is a
+failure; it has no bearing on whether the tool could look.
+
 ## `parse` -- inspect a single file
 
 ```sh
@@ -49,7 +66,6 @@ gerberdiff diff before/ after/ --align-offset 0.5,0    # shift board B by 0.5 in
 | ------ | -------------------------------------------------- |
 | Red    | Geometry present in **before** only (removed)      |
 | Green  | Geometry present in **after** only (added)         |
-| Yellow | Geometry changed (both non-zero, different value)  |
 | Grey   | Unchanged geometry (only with `--png-show-common`) |
 
 ## `geomdiff` -- geometry-aware diff of two layer directories

gerberdiff-0.30.0/docs/contributing.md

@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"

{gerberdiff-0.29.0 → gerberdiff-0.30.0}/docs/geometry-diff.md

@@ -158,8 +158,14 @@ documented so the two engines' outputs are interpreted correctly:
 
 ## Known limitations
 
-- Strokes drawn with macro or block apertures are skipped (the raster
+- Strokes drawn with macro or block apertures are not modelled (the raster
   engine draws them as hairlines; neither engine models them properly).
+  **They are reported, not skipped in silence.** Each one is counted in
+  `summary.unrepresented`, makes the layer `indeterminate`, and gives the
+  comparison an `outcome` of `"indeterminate"` at exit `2`. This limitation was
+  documented here long before the output admitted to it: a board with such a
+  stroke reported `0 changes` at exit `0`, with JSON byte-identical to comparing
+  a board against a copy of itself, while the raster engine reported the change.
 - `rerouted` classification is deferred: a redrawn trace reports as
   removed + added segments (or `resized` when endpoints stay close).
 - Geometry changes are op-granular: a moved multi-op footprint reports

gerberdiff-0.30.0/docs/index.md

@@ -0,0 +1,78 @@
+# gerberdiff
+
+Diff tool for Gerber/Excellon PCB design files, with two complementary
+engines:
+
+- **Raster diff** (`diff`) -- renders both revisions with Cairo and XORs the
+  pixels; produces visual overlay PNGs of changed regions.
+- **Geometry diff** (`geomdiff`) -- computes resolution-independent,
+  **attributed** changes on the parsed vector geometry: every change is
+  classified as `added`, `removed`, `moved` (with dx/dy displacement, down
+  to micrometres), or `resized`, with net names propagated from `%TO.N%`
+  attributes.
+
+The raster engine answers "*where* did pixels change?"; the geometry engine
+answers "*what* changed, and by how much?". A $0.14\,\text{mm}$ component
+move that renders as an unreadable field of XOR crescents in a raster diff
+is reported by the geometry engine as "46 objects moved by
+$(-0.139, -0.054)\,\text{mm}$".
+
+## Install
+
+```sh
+pip install gerberdiff
+```
+
+Requires Python >= 3.11. The raster engine needs the system Cairo library
+(`libcairo2` on Debian/Ubuntu, `cairo` via Homebrew); the geometry engine
+and the parsers are Cairo-free and work everywhere.
+
+## Quick start
+
+```sh
+# Geometry diff: what moved, resized, was added or removed -- and by how much
+gerberdiff geomdiff before/ after/ --out-json report.json --out-svg overlays/
+
+# Raster diff: visual overlay PNGs
+gerberdiff diff before/ after/ --out-json report.json --out-png diffs/
+
+# Exit 1 if any changes detected (useful in CI)
+gerberdiff geomdiff before/ after/ --fail-on-diff
+```
+
+```python
+import gerberdiff
+from pathlib import Path
+
+result = gerberdiff.compute_geometry_diff(Path("before/"), Path("after/"))
+for layer in result.layers:
+    for change in layer.changes:
+        print(f"{layer.name}: {change.kind} {change.op_kind} "
+              f"dx={change.dx_mm} dy={change.dy_mm}")
+```
+
+## Where to go next
+
+| I want to... | Read |
+| --- | --- |
+| Use the command line | [CLI reference](cli.md) |
+| Call it from Python | [Python API](api.md) |
+| Parse the JSON reports | [JSON report schemas](schema.md) |
+| Understand how it works | [Architecture](architecture.md) |
+| Deep-dive the geometry engine | [Geometry diff engine](geometry-diff.md) |
+| Browse the API surface | [API reference](reference/package.md) |
+| Contribute | [Contributing](contributing.md) |
+
+## Known limitations
+
+- **Excellon rout mode:** only drill hits are processed; routing paths
+  produce a `Warning` diagnostic but no geometry.
+- **Deprecated RS-274X commands (`%MI%`, `%OF%`, `%SF%`, `%AS%`):** ignored
+  with an `Info` diagnostic.
+- **Rectangle/obround aperture strokes:** the raster engine strokes with
+  `max(width, height)`; the geometry engine computes the exact Minkowski sum
+  for linear strokes (see [Geometry diff engine](geometry-diff.md)).
+
+## License
+
+[Apache-2.0](https://github.com/heibench/gerberdiff/blob/main/LICENSE).