altium-toolkit 1.1.24 → 1.1.26

package/src/core/altium/PcbLayerStackReadModelBuilder.mjs

@@ -25,10 +25,17 @@ export class PcbLayerStackReadModelBuilder {
         const fields = PcbLayerStackReadModelBuilder.#mergeFields(
             input.boardRecords || []
         )
+        const nativeLayerOrder = (input.layers || []).length
+            ? null
+            : PcbLayerStackReadModelBuilder.#nativeLayerOrder(
+                  fields,
+                  input.primitiveLayers || []
+              )
         const layers = PcbLayerStackReadModelBuilder.#layers(
             input.layers || [],
             input.primitiveLayers || [],
-            fields
+            fields,
+            nativeLayerOrder
         )
         const layerById = new Map(
             layers
@@ -85,6 +92,9 @@ export class PcbLayerStackReadModelBuilder {
             cavityRegionCount: cavityReport.cavityRegionCount,
             stiffenerLayerCount: cavityReport.stiffenerLayerCount,
             adhesiveLayerCount: cavityReport.adhesiveLayerCount,
+            ...(nativeLayerOrder
+                ? { nativeLayerOrderCount: nativeLayerOrder.layerIds.length }
+                : {}),
             diagnosticCount: diagnostics.length
         }
 
@@ -101,6 +111,7 @@ export class PcbLayerStackReadModelBuilder {
                 topLevelBendLines,
                 cavityReport
             ),
+            ...(nativeLayerOrder ? { nativeLayerOrder } : {}),
             layers,
             substacks,
             branches,
@@ -160,9 +171,10 @@ export class PcbLayerStackReadModelBuilder {
      * @param {object[]} layers Parsed physical layers.
      * @param {object[]} primitiveLayers Primitive layer map.
      * @param {Record<string, string | string[]>} fields Source fields.
+     * @param {{ layerIds: number[] } | null} nativeLayerOrder Native order.
      * @returns {object[]}
      */
-    static #layers(layers, primitiveLayers, fields) {
+    static #layers(layers, primitiveLayers, fields, nativeLayerOrder) {
         if (layers.length) {
             return layers.map((layer) =>
                 PcbLayerStackReadModelBuilder.#stripUndefined({
@@ -187,7 +199,19 @@ export class PcbLayerStackReadModelBuilder {
             )
         }
 
-        return (primitiveLayers || []).map((layer, index) =>
+        const nativeOrderByLayerId = new Map(
+            (nativeLayerOrder?.layerIds || []).map((layerId, index) => [
+                layerId,
+                index + 1
+            ])
+        )
+        const orderedPrimitiveLayers =
+            PcbLayerStackReadModelBuilder.#orderPrimitiveLayers(
+                primitiveLayers || [],
+                nativeLayerOrder
+            )
+
+        return orderedPrimitiveLayers.map((layer, index) =>
             PcbLayerStackReadModelBuilder.#stripUndefined({
                 index: index + 1,
                 layerId: layer.layerId,
@@ -196,6 +220,7 @@ export class PcbLayerStackReadModelBuilder {
                     : undefined,
                 name: layer.name,
                 kind: layer.kind || layer.role,
+                nativeOrderIndex: nativeOrderByLayerId.get(layer.layerId),
                 ...PcbLayerStackSourceMetadataParser.layerSourceFields(
                     fields,
                     index + 1
@@ -204,6 +229,116 @@ export class PcbLayerStackReadModelBuilder {
         )
     }
 
+    /**
+     * Parses the native layer linked-list order stored in Board6 records.
+     * @param {Record<string, string | string[]>} fields Board fields.
+     * @param {object[]} primitiveLayers Primitive layer fallbacks.
+     * @returns {{ source: string, layerIds: number[], complete: boolean } | null}
+     */
+    static #nativeLayerOrder(fields, primitiveLayers) {
+        const layerIds = new Set(
+            (primitiveLayers || [])
+                .map((layer) => Number(layer.layerId))
+                .filter(Number.isFinite)
+        )
+        if (!layerIds.size) return null
+
+        const links = PcbLayerStackReadModelBuilder.#nativeLayerLinks(fields)
+        const firstLayerId = [...links.entries()].find(
+            ([, link]) => link.prev === 0 && link.next !== 0
+        )?.[0]
+        if (!firstLayerId) return null
+
+        const orderedLayerIds = []
+        const visited = new Set()
+        let currentLayerId = firstLayerId
+
+        while (
+            Number.isFinite(currentLayerId) &&
+            currentLayerId !== 0 &&
+            !visited.has(currentLayerId)
+        ) {
+            visited.add(currentLayerId)
+
+            if (layerIds.has(currentLayerId)) {
+                orderedLayerIds.push(currentLayerId)
+            }
+
+            const nextLayerId = links.get(currentLayerId)?.next || 0
+            currentLayerId = Number(nextLayerId)
+        }
+
+        if (!orderedLayerIds.length) return null
+
+        return {
+            source: 'Board6/Data',
+            layerIds: orderedLayerIds,
+            complete: orderedLayerIds.length === layerIds.size
+        }
+    }
+
+    /**
+     * Builds native layer link rows from Board6 LAYERnNEXT/PREV fields.
+     * @param {Record<string, string | string[]>} fields Board fields.
+     * @returns {Map<number, { next: number, prev: number }>}
+     */
+    static #nativeLayerLinks(fields) {
+        const layerIndexes = PcbLayerStackReadModelBuilder.#indexedRows(
+            fields,
+            [/^LAYER(\d+)NEXT$/iu, /^LAYER(\d+)PREV$/iu]
+        )
+        const links = new Map()
+
+        for (const layerIndex of layerIndexes) {
+            const next = Number(
+                PcbLayerStackReadModelBuilder.#field(
+                    fields,
+                    'LAYER' + layerIndex + 'NEXT'
+                ) || 0
+            )
+            const prev = Number(
+                PcbLayerStackReadModelBuilder.#field(
+                    fields,
+                    'LAYER' + layerIndex + 'PREV'
+                ) || 0
+            )
+
+            if (Number.isFinite(next) || Number.isFinite(prev)) {
+                links.set(layerIndex, {
+                    next: Number.isFinite(next) ? next : 0,
+                    prev: Number.isFinite(prev) ? prev : 0
+                })
+            }
+        }
+
+        return links
+    }
+
+    /**
+     * Orders primitive fallback layers with native linked-list evidence first.
+     * @param {object[]} primitiveLayers Primitive layer rows.
+     * @param {{ layerIds: number[] } | null} nativeLayerOrder Native order.
+     * @returns {object[]}
+     */
+    static #orderPrimitiveLayers(primitiveLayers, nativeLayerOrder) {
+        if (!nativeLayerOrder?.layerIds?.length) return primitiveLayers
+
+        const layerById = new Map(
+            primitiveLayers
+                .filter((layer) => Number.isFinite(Number(layer.layerId)))
+                .map((layer) => [Number(layer.layerId), layer])
+        )
+        const orderedLayers = nativeLayerOrder.layerIds
+            .map((layerId) => layerById.get(layerId))
+            .filter(Boolean)
+        const orderedIds = new Set(nativeLayerOrder.layerIds)
+        const remainingLayers = primitiveLayers.filter(
+            (layer) => !orderedIds.has(Number(layer.layerId))
+        )
+
+        return [...orderedLayers, ...remainingLayers]
+    }
+
     /**
      * Normalizes substacks and links them to board-region rows.
      * @param {object[]} layerSubstacks Parsed substacks.

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