altium-toolkit 1.1.25 → 1.1.26

package/README.md

@@ -43,9 +43,9 @@ browser or Node-based tools.
 - Build deterministic parser field-coverage matrix, raw-data preservation,
   parameter-record inventory, parser value-verification, normalized
   diagnostics, geometry-bounds, fixture-coverage, embedded-asset,
-  library-diff, library-QA lint, project-hierarchy, and static
-  library-catalog reports, classify PCB layer ids, and convert common Altium
-  length units for downstream QA tooling
+  library-diff, library-compatibility, library-QA lint, project-hierarchy, and
+  static library-catalog reports, classify PCB layer ids, and convert common
+  Altium length units for downstream QA tooling
 - Emit Circuit JSON arrays from parser roots, with non-serialized
   renderer-compatibility fields for existing consumers
 - Render semantically annotated schematic SVG, semantically annotated PCB SVG,
@@ -114,8 +114,10 @@ import 'altium-toolkit/styles/altium-renderers.css'
 - [Geometry Bounds Schema](docs/schemas/altium_toolkit/geometry_bounds_a1.schema.json)
 - [Fixture Coverage Matrix Schema](docs/schemas/altium_toolkit/fixture_coverage_matrix_a1.schema.json)
 - [Unsupported Features Schema](docs/schemas/altium_toolkit/unsupported_features_a1.schema.json)
+- [Library Compatibility Schema](docs/schemas/altium_toolkit/library_compatibility_a1.schema.json)
 - [Testing](docs/testing.md)
 - [Scope](spec/library-scope.md)
+- [Library Compatibility Reports](spec/library-compatibility.md)
 
 ## Examples
 

package/docs/api.md

@@ -73,8 +73,8 @@ Specialized parser helpers are exported for lower-level integrations, including
 `ParserFieldCoverageReportBuilder`, `ParserValueVerificationReportBuilder`,
 `ParserCompatibilityFuzzer`, `NativeStreamInventoryBuilder`,
 `RawDataPreservationReportBuilder`, `UnsupportedFeatureReportBuilder`,
-`EmbeddedAssetReportBuilder`, `LibraryDiffReportBuilder`,
-`LibraryInspectionReportBuilder`,
+`EmbeddedAssetReportBuilder`, `LibraryCompatibilityReportBuilder`,
+`LibraryDiffReportBuilder`, `LibraryInspectionReportBuilder`,
 `PcbBoardRegionSemanticsParser`, `PcbComponentPrimitiveIndexer`,
 `PcbCustomPadShapeParser`, `PcbDimensionParser`,
 `PcbDimensionReportBuilder`, `PcbEmbeddedFontExtractor`,
@@ -192,8 +192,13 @@ opaque-frame preservation for lower-level extractors.
 `ParserCompatibilityFuzzer` runs deterministic malformed,
 wrong-reader, and sparse-input cases against parser entrypoints for parser QA.
 `EmbeddedAssetReportBuilder` emits unified embedded-asset inventories across
-parser roots, and `LibraryDiffReportBuilder` compares parsed symbol and
-footprint libraries by name, counts, and parameters.
+parser roots. `LibraryCompatibilityReportBuilder` emits source-neutral
+schematic-library pin compatibility rows, symbol bounds, field-placement risk
+rows, footprint bounds, pad diagnostics, custom pad outline diagnostics, and
+package-key suggestions with pin-one rotation hints for footprints without
+embedded or body-level model references. `LibraryDiffReportBuilder` compares
+parsed symbol and footprint
+libraries by name, counts, and parameters.
 `LibraryInspectionReportBuilder` composes library inventory and QA findings
 into one stable artifact. `SchLibStreamExtractor` and `SchLibModelParser`
 expose native schematic-symbol library recovery, including section keys,

package/docs/model-format.md

@@ -154,9 +154,17 @@ known/unknown classification, and consumed status.
 `EmbeddedAssetReportBuilder.build()` emits
 `altium-toolkit.embedded-assets.a1` reports that normalize schematic images,
 embedded file inventories, PCB font/model payloads, and integrated-library
-source entries into one stable asset table. `LibraryDiffReportBuilder.build()`
-emits `altium-toolkit.library.diff.a1` reports comparing parsed symbol and
-footprint libraries by item name, counts, and parameter values.
+source entries into one stable asset table.
+`LibraryCompatibilityReportBuilder.build()` emits
+`altium-toolkit.library.compatibility.a1` reports for schematic-library pin
+roles and edge markers, hidden-pin hints, symbol bounds, field-placement risk
+rows, footprint bounds, pad diagnostics, custom pad outline diagnostics, and
+package-key suggestions with pin-one rotation hints for missing model
+references. The report is read-only and is also composed into library QA when
+it emits issues.
+`LibraryDiffReportBuilder.build()` emits `altium-toolkit.library.diff.a1`
+reports comparing parsed symbol and footprint libraries by item name, counts,
+and parameter values.
 `LibraryInspectionReportBuilder.build()` emits
 `altium-toolkit.library.inspection.a1` reports that combine library inventory
 rows with duplicate, stale-link, missing-model, lint, and merge-plan QA
@@ -478,7 +486,10 @@ preserves raw mixed-format primitive records with the same registry metadata
 shape used by PcbDoc raw records. Library-level `embeddedFonts` uses the same
 payload and metric shape as PCB documents. Library-level `embeddedModels` and
 `componentBodies` preserve embedded 3D payloads and body references when
-present. Shape-based component bodies may include `staticGeometry` for
+present. When declared footprint names cannot be resolved to storage names,
+`pcbLibrary.storageDiagnostics.missingFootprints` lists the declared name,
+attempted storage candidates, and reason. Shape-based component bodies may
+include `staticGeometry` for
 extruded-polygon, cone, cylinder, and sphere bodies, with dimensions and
 vertices expressed in mils when native evidence is available.
 `pcbLibrary.indexes.footprintsByName` provides read-only footprint lookup and

package/docs/schemas/altium_toolkit/library_compatibility_a1.schema.json

@@ -0,0 +1,116 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "altium-toolkit.library.compatibility.a1",
+    "title": "Altium Toolkit Library Compatibility A1",
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+        "schema",
+        "summary",
+        "symbolPins",
+        "hiddenPins",
+        "symbolBounds",
+        "fieldPlacementRisks",
+        "footprintBounds",
+        "padDiagnostics",
+        "modelSuggestions",
+        "issues"
+    ],
+    "properties": {
+        "schema": {
+            "const": "altium-toolkit.library.compatibility.a1"
+        },
+        "summary": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+                "schematicLibraryCount": {
+                    "type": "number"
+                },
+                "pcbLibraryCount": {
+                    "type": "number"
+                },
+                "symbolPinCount": {
+                    "type": "number"
+                },
+                "hiddenPinCount": {
+                    "type": "number"
+                },
+                "symbolBoundsCount": {
+                    "type": "number"
+                },
+                "fieldPlacementRiskCount": {
+                    "type": "number"
+                },
+                "footprintBoundsCount": {
+                    "type": "number"
+                },
+                "padDiagnosticCount": {
+                    "type": "number"
+                },
+                "modelSuggestionCount": {
+                    "type": "number"
+                },
+                "issueCount": {
+                    "type": "number"
+                }
+            }
+        },
+        "symbolPins": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true
+            }
+        },
+        "hiddenPins": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true
+            }
+        },
+        "symbolBounds": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true
+            }
+        },
+        "fieldPlacementRisks": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true
+            }
+        },
+        "footprintBounds": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true
+            }
+        },
+        "padDiagnostics": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true
+            }
+        },
+        "modelSuggestions": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true
+            }
+        },
+        "issues": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true
+            }
+        }
+    }
+}

package/docs/schemas/altium_toolkit/library_qa_a1.schema.json

@@ -63,6 +63,9 @@
             "type": "object",
             "additionalProperties": true
         },
+        "compatibility": {
+            "$ref": "library_compatibility_a1.schema.json"
+        },
         "issues": {
             "type": "array",
             "items": {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "altium-toolkit",
-    "version": "1.1.25",
+    "version": "1.1.26",
     "description": "Altium document parsing and non-interactive rendering utilities",
     "keywords": [
         "altium",

package/spec/library-compatibility.md

@@ -0,0 +1,65 @@
+<!--
+SPDX-FileCopyrightText: 2026 André Fiedler
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Library Compatibility Reports
+
+Library compatibility reports provide deterministic, source-neutral QA over
+parsed schematic symbol libraries and PCB footprint libraries. The report is
+read-only: it never rewrites symbols, footprints, model references, or rendered
+output.
+
+## Scope
+
+The report focuses on compatibility signals that are useful across importer,
+renderer, catalog, and review workflows:
+
+- schematic pin electrical roles, decorative edge markers, hidden state, and
+  hidden-pin placement hints
+- schematic symbol bounds, pin/body bounds, deterministic field anchor hints,
+  and visible field-placement risk rows
+- PCB footprint bounds and padded courtyard-like bounds derived from recovered
+  pad and primitive geometry
+- PCB pad diagnostics for top/bottom size mismatches, explicit zero-size pads,
+  unknown pad shapes, unresolved pad layers, and custom pad outline geometry
+- package-name keys and pin-one rotation hints that can help downstream tools
+  suggest model matches when a footprint has no embedded or body-level model
+  reference
+
+The report does not perform format conversion, file writing, model download,
+interactive model binding, or application UI work.
+
+## Contract
+
+`LibraryCompatibilityReportBuilder.build()` emits
+`altium-toolkit.library.compatibility.a1` with these top-level arrays:
+
+- `symbolPins`: normalized schematic-library pin compatibility rows
+- `hiddenPins`: hidden pins with placement hints and source location metadata
+- `symbolBounds`: per-symbol bounds, body bounds, pin bounds, source counts,
+  and deterministic field anchor hints
+- `fieldPlacementRisks`: warning rows for visible designator/comment/value
+  fields placed inside symbol bounds
+- `footprintBounds`: footprint-level bounds, courtyard bounds, and primitive
+  source counts
+- `padDiagnostics`: warning rows for pad geometry and mapping problems
+- `modelSuggestions`: package-key and rotation-hint rows for model matching by
+  host tools
+- `issues`: flattened warning/info rows suitable for library QA summaries
+
+PcbLib extraction also exposes `diagnostics.missingFootprints` rows when a
+declared footprint name cannot be resolved to a compound-document storage. Each
+row lists the declared name, attempted storage candidates, and reason. Parsed
+PcbLib models surface the same rows at
+`pcbLibrary.storageDiagnostics.missingFootprints`.
+
+`LibraryQaReportBuilder.build()` composes compatibility issues into its
+top-level `issues` array when the compatibility report finds non-empty issue
+rows. Clean inputs keep the existing QA summary shape.
+
+## Testing Policy
+
+Tests for this report use synthetic library objects only. They must not rely on
+native library files or real project, customer, vendor, or product identifiers.