altium-toolkit 1.1.25 → 1.1.26

package/src/core/altium/LibraryQaReportBuilder.mjs

@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+import { LibraryCompatibilityReportBuilder } from './LibraryCompatibilityReportBuilder.mjs'
+
 /**
  * Builds deterministic QA reports across parsed schematic and PCB libraries.
  */
@@ -33,6 +35,10 @@ export class LibraryQaReportBuilder {
             schematicLibraries,
             pcbLibraries
         )
+        const compatibility = LibraryCompatibilityReportBuilder.build({
+            schematicLibraries,
+            pcbLibraries
+        })
         const mergePlan =
             LibraryQaReportBuilder.#schematicLibraryMergePlan(
                 schematicLibraries
@@ -74,7 +80,8 @@ export class LibraryQaReportBuilder {
                     diagnostic.symbolName
                 )
             ),
-            ...libraryLint.issues
+            ...libraryLint.issues,
+            ...(compatibility.issues || [])
         ]
         const issuesBySeverity =
             LibraryQaReportBuilder.#issueSeverityCounts(issues)
@@ -91,6 +98,7 @@ export class LibraryQaReportBuilder {
                 multipartMismatchCount: multipartMismatches.length,
                 mergePlanConflictCount: mergePlan.summary.conflictCount,
                 libraryLintIssueCount: libraryLint.summary.issueCount,
+                ...LibraryQaReportBuilder.#compatibilitySummary(compatibility),
                 issuesBySeverity,
                 issueCount: issues.length
             },
@@ -102,6 +110,7 @@ export class LibraryQaReportBuilder {
             missingModels,
             multipartMismatches,
             libraryLint,
+            compatibility,
             mergePlan,
             issues
         }
@@ -680,6 +689,25 @@ export class LibraryQaReportBuilder {
         return counts
     }
 
+    /**
+     * Builds optional compatibility counters for non-empty reports.
+     * @param {object} compatibility Compatibility report.
+     * @returns {object}
+     */
+    static #compatibilitySummary(compatibility) {
+        const summary = compatibility?.summary || {}
+        const issueCount = Number(summary.issueCount || 0)
+
+        if (!issueCount) return {}
+
+        return {
+            compatibilityIssueCount: issueCount,
+            hiddenPinCount: Number(summary.hiddenPinCount || 0),
+            padDiagnosticCount: Number(summary.padDiagnosticCount || 0),
+            modelSuggestionCount: Number(summary.modelSuggestionCount || 0)
+        }
+    }
+
     /**
      * Builds duplicate-symbol merge-plan rows.
      * @param {object[]} schematicLibraries Schematic libraries.

package/src/core/altium/PcbLibModelParser.mjs

@@ -20,7 +20,7 @@ export class PcbLibModelParser {
     /**
      * Parses one extracted PcbLib into a normalized read-only model.
      * @param {string} fileName
-     * @param {{ libraryHeader?: Record<string, string>, componentParamsToc?: Record<string, object>, sectionKeys?: Record<string, string>, footprints?: object[], embeddedFonts?: { fonts?: object[] }, nativeStreams?: object, streamNames?: string[], diagnostics?: Record<string, number> } | null} extraction
+     * @param {{ libraryHeader?: Record<string, string>, componentParamsToc?: Record<string, object>, sectionKeys?: Record<string, string>, footprints?: object[], embeddedFonts?: { fonts?: object[] }, nativeStreams?: object, streamNames?: string[], diagnostics?: Record<string, number | object[]> } | null} extraction
      * @returns {{ schema: string, kind: 'pcb-library', fileType: 'PcbLib', fileName: string, summary: Record<string, number | string>, diagnostics: { severity: 'info' | 'warning', message: string }[], pcbLibrary: { libraryHeader: Record<string, string>, componentParamsToc: Record<string, object>, sectionKeys: Record<string, string>, footprints: object[], embeddedFonts: object[] }, bom: [] }}
      */
     static parse(fileName, extraction) {
@@ -72,6 +72,7 @@ export class PcbLibModelParser {
             embeddedFonts,
             embeddedModels,
             componentBodies,
+            ...PcbLibModelParser.#storageDiagnostics(safeExtraction),
             ...(safeExtraction.nativeStreams
                 ? { nativeStreams: safeExtraction.nativeStreams }
                 : {}),
@@ -141,7 +142,7 @@ export class PcbLibModelParser {
      * @param {object[]} footprints
      * @param {object[]} embeddedFonts
      * @param {object[]} embeddedModels
-     * @param {{ streamNames?: string[], diagnostics?: Record<string, number> }} extraction
+     * @param {{ streamNames?: string[], diagnostics?: Record<string, number | object[]> }} extraction
      * @returns {{ severity: 'info' | 'warning', message: string }[]}
      */
     static #buildDiagnostics(
@@ -203,6 +204,27 @@ export class PcbLibModelParser {
         return diagnostics
     }
 
+    /**
+     * Builds storage-level diagnostics for the public PCB library model.
+     * @param {{ diagnostics?: Record<string, number | object[]> }} extraction Extracted PcbLib data.
+     * @returns {{ storageDiagnostics?: object }}
+     */
+    static #storageDiagnostics(extraction) {
+        const missingFootprints = Array.isArray(
+            extraction?.diagnostics?.missingFootprints
+        )
+            ? extraction.diagnostics.missingFootprints
+            : []
+
+        return missingFootprints.length
+            ? {
+                  storageDiagnostics: {
+                      missingFootprints
+                  }
+              }
+            : {}
+    }
+
     /**
      * Normalizes one extracted footprint object with stable primitive arrays.
      * @param {object} footprint

package/src/core/altium/PcbLibStorageNameResolver.mjs

@@ -0,0 +1,171 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Resolves declared PcbLib footprint names to compound-document storage names.
+ */
+export class PcbLibStorageNameResolver {
+    /**
+     * Resolves all declared footprint storage names.
+     * @param {Map<string, Uint8Array>} streams PcbLib compound streams.
+     * @param {string[]} footprintNames Declared footprint names.
+     * @param {Record<string, string>} sectionKeys Section-key mapping.
+     * @returns {{ resolvedFootprints: { name: string, storageName: string }[], missingFootprints: object[] }}
+     */
+    static resolveFootprints(streams, footprintNames, sectionKeys) {
+        const resolvedFootprints = []
+        const missingFootprints = []
+
+        for (const name of footprintNames || []) {
+            const candidates = PcbLibStorageNameResolver.#storageCandidates(
+                name,
+                sectionKeys
+            )
+            const storageName = PcbLibStorageNameResolver.#resolveStorageName(
+                streams,
+                candidates
+            )
+
+            if (!storageName) {
+                missingFootprints.push({
+                    footprintName: name,
+                    candidates,
+                    reason: 'no matching footprint Data stream'
+                })
+                continue
+            }
+
+            resolvedFootprints.push({ name, storageName })
+        }
+
+        return { resolvedFootprints, missingFootprints }
+    }
+
+    /**
+     * Parses an optional SectionKeys stream that maps full footprint names to
+     * shortened OLE storage names.
+     * @param {Uint8Array | undefined} bytes SectionKeys stream bytes.
+     * @returns {Record<string, string>}
+     */
+    static parseSectionKeys(bytes) {
+        if (!bytes || bytes.byteLength < 4) {
+            return {}
+        }
+
+        const count = PcbLibStorageNameResolver.#readUint32(bytes, 0)
+        const entries = {}
+        let offset = 4
+
+        for (let index = 0; index < count; index += 1) {
+            const fullName = PcbLibStorageNameResolver.#readStringBlockAt(
+                bytes,
+                offset
+            )
+            if (!fullName) break
+            offset = fullName.nextOffset
+
+            const storageName = PcbLibStorageNameResolver.#readStringBlockAt(
+                bytes,
+                offset
+            )
+            if (!storageName) break
+            offset = storageName.nextOffset
+            entries[fullName.text] = storageName.text
+        }
+
+        return entries
+    }
+
+    /**
+     * Builds candidate OLE storage names for one declared footprint.
+     * @param {string} footprintName Declared footprint name.
+     * @param {Record<string, string>} sectionKeys Section-key mapping.
+     * @returns {string[]}
+     */
+    static #storageCandidates(footprintName, sectionKeys) {
+        return [
+            footprintName,
+            PcbLibStorageNameResolver.#sanitizeStorageName(footprintName),
+            sectionKeys[footprintName],
+            PcbLibStorageNameResolver.#sanitizeStorageName(
+                footprintName.slice(0, 31)
+            )
+        ]
+            .filter(Boolean)
+            .filter(
+                (candidate, index, candidates) =>
+                    candidates.indexOf(candidate) === index
+            )
+    }
+
+    /**
+     * Resolves the first candidate with a matching Data stream.
+     * @param {Map<string, Uint8Array>} streams PcbLib compound streams.
+     * @param {string[]} candidates Candidate storage names.
+     * @returns {string}
+     */
+    static #resolveStorageName(streams, candidates) {
+        return (
+            candidates.find((candidate) => streams.has(candidate + '/Data')) ||
+            ''
+        )
+    }
+
+    /**
+     * Sanitizes one footprint name for legacy OLE storage lookup.
+     * @param {string} name Footprint name.
+     * @returns {string}
+     */
+    static #sanitizeStorageName(name) {
+        return String(name || '')
+            .replace(/[<>:"/\\|?*\x00-\x1f]/gu, '_')
+            .slice(0, 31)
+    }
+
+    /**
+     * Reads a little-endian unsigned 32-bit value from one byte array.
+     * @param {Uint8Array} bytes Source bytes.
+     * @param {number} offset Byte offset.
+     * @returns {number}
+     */
+    static #readUint32(bytes, offset) {
+        if (!bytes || offset + 4 > bytes.byteLength) return 0
+
+        return new DataView(
+            bytes.buffer,
+            bytes.byteOffset,
+            bytes.byteLength
+        ).getUint32(offset, true)
+    }
+
+    /**
+     * Reads one Pascal-style PCB string block from an offset.
+     * @param {Uint8Array} bytes Source bytes.
+     * @param {number} offset Byte offset.
+     * @returns {{ text: string, nextOffset: number } | null}
+     */
+    static #readStringBlockAt(bytes, offset) {
+        if (!bytes || offset + 5 > bytes.byteLength) return null
+
+        const byteLength = PcbLibStorageNameResolver.#readUint32(bytes, offset)
+        const stringLength = bytes[offset + 4]
+        const textOffset = offset + 5
+        const nextOffset = offset + 4 + byteLength
+
+        if (
+            byteLength < 1 ||
+            textOffset + stringLength > bytes.byteLength ||
+            nextOffset > bytes.byteLength
+        ) {
+            return null
+        }
+
+        return {
+            text: new TextDecoder('utf-8').decode(
+                bytes.subarray(textOffset, textOffset + stringLength)
+            ),
+            nextOffset
+        }
+    }
+}

package/src/core/altium/PcbLibStreamExtractor.mjs

@@ -7,6 +7,7 @@ import { PcbCustomPadShapeParser } from './PcbCustomPadShapeParser.mjs'
 import { PcbEmbeddedFontExtractor } from './PcbEmbeddedFontExtractor.mjs'
 import { PcbEmbeddedModelExtractor } from './PcbEmbeddedModelExtractor.mjs'
 import { PcbExtendedPrimitiveInformationParser } from './PcbExtendedPrimitiveInformationParser.mjs'
+import { PcbLibStorageNameResolver } from './PcbLibStorageNameResolver.mjs'
 import { NativeStreamInventoryBuilder } from './NativeStreamInventoryBuilder.mjs'
 import { PcbRawRecordRegistry } from './PcbRawRecordRegistry.mjs'
 import { OleCompoundDocument } from '../ole/OleCompoundDocument.mjs'
@@ -119,7 +120,7 @@ export class PcbLibStreamExtractor {
     /**
      * Extracts all declared footprints from one PcbLib stream map.
      * @param {Map<string, Uint8Array>} streams
-     * @returns {{ libraryHeader: Record<string, string>, componentParamsToc: Record<string, object>, sectionKeys: Record<string, string>, footprints: object[], streamNames: string[], diagnostics: Record<string, number> }}
+     * @returns {{ libraryHeader: Record<string, string>, componentParamsToc: Record<string, object>, sectionKeys: Record<string, string>, footprints: object[], streamNames: string[], diagnostics: Record<string, number | object[]> }}
      */
     static extractFromStreams(streams) {
         const libraryData = streams.get('Library/Data') || new Uint8Array()
@@ -129,30 +130,24 @@ export class PcbLibStreamExtractor {
             PcbLibStreamExtractor.#parseComponentParamsToc(
                 streams.get('Library/ComponentParamsTOC/Data')
             )
-        const sectionKeys = PcbLibStreamExtractor.#parseSectionKeys(
+        const sectionKeys = PcbLibStorageNameResolver.parseSectionKeys(
             streams.get('SectionKeys')
         )
-        const footprints = parsedLibraryData.footprintNames.flatMap((name) => {
-            const resolvedStorage =
-                PcbLibStreamExtractor.#resolveFootprintStorageName(
-                    streams,
-                    name,
-                    sectionKeys
-                )
-
-            if (!resolvedStorage) {
-                return []
-            }
-
-            return [
+        const storageResolution = PcbLibStorageNameResolver.resolveFootprints(
+            streams,
+            parsedLibraryData.footprintNames,
+            sectionKeys
+        )
+        const footprints = storageResolution.resolvedFootprints.map(
+            ({ name, storageName }) =>
                 PcbLibStreamExtractor.#extractFootprint(
                     streams,
                     name,
-                    resolvedStorage,
+                    storageName,
                     componentParamsToc[name] || {}
                 )
-            ]
-        })
+        )
+        const missingFootprints = storageResolution.missingFootprints
         const primitiveCount = footprints.reduce(
             (sum, footprint) => sum + footprint.primitiveCount,
             0
@@ -198,8 +193,8 @@ export class PcbLibStreamExtractor {
                 embeddedFontCount: embeddedFonts.fonts.length,
                 embeddedModelCount: embeddedModels.models.length,
                 componentBodyCount: embeddedModels.componentBodies.length,
-                missingFootprintCount:
-                    parsedLibraryData.footprintNames.length - footprints.length
+                missingFootprintCount: missingFootprints.length,
+                ...(missingFootprints.length ? { missingFootprints } : {})
             }
         }
     }
@@ -280,68 +275,6 @@ export class PcbLibStreamExtractor {
         return entries
     }
 
-    /**
-     * Parses an optional SectionKeys stream that maps full footprint names to
-     * shortened OLE storage names.
-     * @param {Uint8Array | undefined} bytes
-     * @returns {Record<string, string>}
-     */
-    static #parseSectionKeys(bytes) {
-        if (!bytes || bytes.byteLength < 4) {
-            return {}
-        }
-
-        const count = PcbLibStreamExtractor.#readUint32(bytes, 0)
-        const entries = {}
-        let offset = 4
-
-        for (let index = 0; index < count; index += 1) {
-            const fullName = PcbLibStreamExtractor.#readStringBlockAt(
-                bytes,
-                offset
-            )
-            if (!fullName) {
-                break
-            }
-            offset = fullName.nextOffset
-
-            const storageName = PcbLibStreamExtractor.#readStringBlockAt(
-                bytes,
-                offset
-            )
-            if (!storageName) {
-                break
-            }
-            offset = storageName.nextOffset
-            entries[fullName.text] = storageName.text
-        }
-
-        return entries
-    }
-
-    /**
-     * Resolves the OLE storage name for one declared footprint.
-     * @param {Map<string, Uint8Array>} streams
-     * @param {string} footprintName
-     * @param {Record<string, string>} sectionKeys
-     * @returns {string}
-     */
-    static #resolveFootprintStorageName(streams, footprintName, sectionKeys) {
-        const candidates = [
-            footprintName,
-            PcbLibStreamExtractor.#sanitizeStorageName(footprintName),
-            sectionKeys[footprintName],
-            PcbLibStreamExtractor.#sanitizeStorageName(
-                footprintName.slice(0, 31)
-            )
-        ].filter(Boolean)
-
-        return (
-            candidates.find((candidate) => streams.has(candidate + '/Data')) ||
-            ''
-        )
-    }
-
     /**
      * Extracts one footprint storage into normalized primitive lists.
      * @param {Map<string, Uint8Array>} streams
@@ -1042,17 +975,6 @@ export class PcbLibStreamExtractor {
         })
     }
 
-    /**
-     * Sanitizes one footprint name for legacy OLE storage lookup.
-     * @param {string} name
-     * @returns {string}
-     */
-    static #sanitizeStorageName(name) {
-        return String(name || '')
-            .replace(/[/:\\]/gu, '_')
-            .slice(0, 31)
-    }
-
     /**
      * Reads a little-endian unsigned 32-bit value from one byte array.
      * @param {Uint8Array} bytes

package/src/parser.mjs

@@ -41,6 +41,7 @@ export { DraftsmanBoardViewMetadataBuilder } from './core/altium/DraftsmanBoardV
 export { DraftsmanDigestParser } from './core/altium/DraftsmanDigestParser.mjs'
 export { LibraryRenderManifestBuilder } from './core/altium/LibraryRenderManifestBuilder.mjs'
 export { LibraryCatalogArtifactBuilder } from './core/altium/LibraryCatalogArtifactBuilder.mjs'
+export { LibraryCompatibilityReportBuilder } from './core/altium/LibraryCompatibilityReportBuilder.mjs'
 export { LibraryDiffReportBuilder } from './core/altium/LibraryDiffReportBuilder.mjs'
 export { LibraryInspectionReportBuilder } from './core/altium/LibraryInspectionReportBuilder.mjs'
 export { LibraryQaReportBuilder } from './core/altium/LibraryQaReportBuilder.mjs'