altium-toolkit 1.0.9 → 1.0.10

package/src/core/altium/ParserCompatibilityFuzzer.mjs

@@ -0,0 +1,192 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { AltiumParser } from './AltiumParser.mjs'
+import { DraftsmanDigestParser } from './DraftsmanDigestParser.mjs'
+import { PcbModelParser } from './PcbModelParser.mjs'
+import { PrjPcbModelParser } from './PrjPcbModelParser.mjs'
+
+/**
+ * Runs deterministic synthetic compatibility cases against parser entrypoints.
+ */
+export class ParserCompatibilityFuzzer {
+    static SCHEMA = 'altium-toolkit.parser-compatibility-fuzz.a1'
+
+    /**
+     * Runs all built-in synthetic parser compatibility cases.
+     * @returns {object}
+     */
+    static run() {
+        const cases = ParserCompatibilityFuzzer.#cases().map((entry) =>
+            ParserCompatibilityFuzzer.#runCase(entry)
+        )
+
+        return {
+            schema: ParserCompatibilityFuzzer.SCHEMA,
+            summary: {
+                caseCount: cases.length,
+                failureCount: cases.filter((entry) => entry.status === 'fail')
+                    .length,
+                diagnosticCount: cases.reduce(
+                    (total, entry) =>
+                        total + Number(entry.diagnosticCount || 0),
+                    0
+                )
+            },
+            cases
+        }
+    }
+
+    /**
+     * Lists deterministic compatibility cases.
+     * @returns {{ key: string, parse: () => object }[]}
+     */
+    static #cases() {
+        return [
+            {
+                key: 'sch-record-ordering',
+                parse: () =>
+                    AltiumParser.parseArrayBufferToRendererModel(
+                        'fuzz-order.SchDoc',
+                        ParserCompatibilityFuzzer.#encodeText(
+                            '|RECORD=999|Text=Unknown First|' +
+                                '|HEADER=Schematic Document|' +
+                                '|RECORD=31|CustomX=120|CustomY=80|BorderOn=F|TitleBlockOn=F|' +
+                                '|RECORD=13|Location.X=10|Location.Y=10|Corner.X=80|Corner.Y=10|LineWidth=1|'
+                        )
+                    )
+            },
+            {
+                key: 'sch-odd-encoding',
+                parse: () =>
+                    AltiumParser.parseArrayBufferToRendererModel(
+                        'fuzz-encoding.SchDoc',
+                        ParserCompatibilityFuzzer.#windows1252Schematic()
+                    )
+            },
+            {
+                key: 'pcb-malformed-sidecars',
+                parse: () =>
+                    PcbModelParser.parse('fuzz-sidecar.PcbDoc', [
+                        {
+                            sourceStream: 'Pads6/Data',
+                            fields: {
+                                X: 'not-a-number',
+                                Y: '20mil',
+                                HOLESIZE: 'malformed',
+                                NET: 'NET_A'
+                            }
+                        },
+                        {
+                            sourceStream: 'ExtendedPrimitiveInformation/Data',
+                            fields: {
+                                PRIMITIVEINDEX: 'not-a-number',
+                                SolderMaskExpansionMode: 'Manual',
+                                SolderMaskExpansion: 'bad'
+                            }
+                        },
+                        {
+                            sourceStream: 'UnsupportedSidecar/Data',
+                            fields: { RECORD: '777', VALUE: 'preserve' }
+                        }
+                    ])
+            },
+            {
+                key: 'project-sparse-documents',
+                parse: () =>
+                    PrjPcbModelParser.parseText(
+                        'fuzz-project.PrjPcb',
+                        '[Design]\n\n[Document1]\nDocumentUniqueId=EMPTY\n'
+                    )
+            },
+            {
+                key: 'draftsman-unsupported-container',
+                parse: () =>
+                    DraftsmanDigestParser.parse(
+                        'fuzz.PCBDwf',
+                        new Uint8Array([0, 1, 2, 3]).buffer
+                    )
+            }
+        ]
+    }
+
+    /**
+     * Executes one compatibility case.
+     * @param {{ key: string, parse: () => object }} entry Case descriptor.
+     * @returns {object}
+     */
+    static #runCase(entry) {
+        try {
+            const model = entry.parse()
+            return {
+                key: entry.key,
+                status: 'pass',
+                kind: model?.kind || '',
+                fileType: model?.fileType || '',
+                diagnosticCount: (model?.diagnostics || []).length,
+                summary: ParserCompatibilityFuzzer.#stableSummary(
+                    model?.summary || {}
+                )
+            }
+        } catch (error) {
+            return {
+                key: entry.key,
+                status: 'fail',
+                diagnosticCount: 1,
+                error: {
+                    name: error?.name || 'Error',
+                    message: error?.message || String(error)
+                }
+            }
+        }
+    }
+
+    /**
+     * Builds a stable compact summary object.
+     * @param {object} summary Parser summary.
+     * @returns {object}
+     */
+    static #stableSummary(summary) {
+        return Object.fromEntries(
+            Object.entries(summary || {}).filter(([, value]) =>
+                ['number', 'string', 'boolean'].includes(typeof value)
+            )
+        )
+    }
+
+    /**
+     * Encodes text as UTF-8.
+     * @param {string} text Text payload.
+     * @returns {ArrayBuffer}
+     */
+    static #encodeText(text) {
+        const bytes = new TextEncoder().encode(text)
+        return bytes.buffer.slice(
+            bytes.byteOffset,
+            bytes.byteOffset + bytes.length
+        )
+    }
+
+    /**
+     * Builds a schematic payload with one Windows-1252 punctuation byte.
+     * @returns {ArrayBuffer}
+     */
+    static #windows1252Schematic() {
+        const prefix = new TextEncoder().encode(
+            '|HEADER=Schematic Document|' +
+                '|RECORD=31|CustomX=120|CustomY=80|BorderOn=F|TitleBlockOn=F|' +
+                '|RECORD=4|Location.X=20|Location.Y=20|TEXT=ESD'
+        )
+        const suffix = new TextEncoder().encode('TVS|')
+        const bytes = new Uint8Array(prefix.length + 1 + suffix.length)
+        bytes.set(prefix, 0)
+        bytes[prefix.length] = 0x96
+        bytes.set(suffix, prefix.length + 1)
+
+        return bytes.buffer.slice(
+            bytes.byteOffset,
+            bytes.byteOffset + bytes.length
+        )
+    }
+}

package/src/core/altium/PcbModelParser.mjs

@@ -16,6 +16,7 @@ import { PcbMaskPasteResolver } from './PcbMaskPasteResolver.mjs'
 import { PcbOutlineRecovery } from './PcbOutlineRecovery.mjs'
 import { PcbOwnershipGraphBuilder } from './PcbOwnershipGraphBuilder.mjs'
 import { PcbPickPlacePositionResolver } from './PcbPickPlacePositionResolver.mjs'
+import { PcbRouteAnalysisBuilder } from './PcbRouteAnalysisBuilder.mjs'
 import { PcbRuleParser } from './PcbRuleParser.mjs'
 import { PcbSpecialStringResolver } from './PcbSpecialStringResolver.mjs'
 import { PcbStatisticsBuilder } from './PcbStatisticsBuilder.mjs'
@@ -281,6 +282,16 @@ export class PcbModelParser {
             componentPrimitiveGroups,
             { sourceComponents: componentRecords }
         )
+        const routeAnalysis = PcbRouteAnalysisBuilder.build({
+            ...normalizedPcb,
+            layers,
+            primitiveLayers,
+            nets,
+            classes,
+            differentialPairs: differentialPairData.differentialPairs,
+            differentialPairClasses:
+                differentialPairData.differentialPairClasses
+        })
         const statistics = PcbStatisticsBuilder.build({
             ...normalizedPcb,
             layers,
@@ -556,6 +567,8 @@ export class PcbModelParser {
                 customPadShapeCount: customPadShapes.entries?.length || 0,
                 userUnionCount: unions.userUnions?.length || 0,
                 smartUnionCount: unions.smartUnions?.length || 0,
+                routedNetCount: routeAnalysis.summary.routedNetCount,
+                routedLengthMil: routeAnalysis.summary.totalLengthMil,
                 boardRegionCount: boardRegionSummary.boardRegionCount,
                 flexRegionCount: boardRegionSummary.flexRegionCount,
                 bendingLineCount: boardRegionSummary.bendingLineCount,
@@ -588,6 +601,7 @@ export class PcbModelParser {
                 dimensions,
                 components: normalizedPcb.components,
                 pickPlace: pnp,
+                routeAnalysis,
                 polygons: normalizedPcb.polygons,
                 fills: normalizedPcb.fills,
                 tracks: normalizedPcb.tracks,
@@ -1193,25 +1207,36 @@ export class PcbModelParser {
                 key === 'MEMBERCOUNT' ||
                 key === 'ENABLED' ||
                 key === 'UNIQUEID' ||
-                /^M\d+$/.test(key)
+                /^(?:M|MEMBER)\d+$/.test(key)
         )
     }
 
     /**
-     * Extracts ordered class members from M0, M1, ... fields.
+     * Extracts ordered class members from M0/MEMBER0-style fields.
      * @param {Record<string, string | string[]>} fields
      * @returns {string[]}
      */
     static #parseClassMembers(fields) {
         return Object.keys(fields || {})
-            .filter((key) => /^M\d+$/.test(key))
+            .filter((key) => /^(?:M|MEMBER)\d+$/.test(key))
             .sort(
-                (left, right) => Number(left.slice(1)) - Number(right.slice(1))
+                (left, right) =>
+                    PcbModelParser.#classMemberIndex(left) -
+                    PcbModelParser.#classMemberIndex(right)
             )
             .map((key) => getField(fields, key))
             .filter(Boolean)
     }
 
+    /**
+     * Extracts the numeric index from a class member field name.
+     * @param {string} key Field key.
+     * @returns {number}
+     */
+    static #classMemberIndex(key) {
+        return Number(String(key).replace(/^(?:M|MEMBER)/u, ''))
+    }
+
     /**
      * Returns a stable display name for one native PCB class kind.
      * @param {number} kind

package/src/core/altium/PcbPadStackParser.mjs

@@ -81,6 +81,10 @@ export class PcbPadStackParser {
         const flags = PcbPadStackParser.#parseFlags(mainRecord)
         const mainRecordTail =
             PcbPadStackParser.#parseMainRecordTail(mainRecord)
+        const extension = PcbPadStackParser.#parseExtensionRecord(
+            extensionRecord,
+            padContext
+        )
 
         return {
             ...flags,
@@ -90,8 +94,10 @@ export class PcbPadStackParser {
                 mainRecordTail,
                 padContext
             ),
-            ...PcbPadStackParser.#parseExtensionRecord(
-                extensionRecord,
+            ...extension,
+            ...PcbPadStackParser.#buildLocalStack(
+                mainRecordTail,
+                extension,
                 padContext
             )
         }
@@ -722,6 +728,169 @@ export class PcbPadStackParser {
         }
     }
 
+    /**
+     * Builds a normalized local-stack geometry read model.
+     * @param {Record<string, boolean | number>} mainRecordTail Main tail fields.
+     * @param {Record<string, unknown>} extension Extension fields.
+     * @param {Record<string, unknown>} padContext Parsed pad fields.
+     * @returns {{ localStack?: object }}
+     */
+    static #buildLocalStack(mainRecordTail, extension, padContext) {
+        const mode = Number(mainRecordTail.padMode)
+        if (mode === 1) {
+            return {
+                localStack: {
+                    schema: 'altium-toolkit.pcb.pad-local-stack.a1',
+                    mode,
+                    modeName: String(mainRecordTail.padModeName || ''),
+                    source: 'main-record',
+                    layers: [
+                        PcbPadStackParser.#localStackLayer(
+                            'top',
+                            1,
+                            'L1',
+                            padContext,
+                            extension
+                        ),
+                        PcbPadStackParser.#localStackLayer(
+                            'middle',
+                            null,
+                            'INNER',
+                            padContext,
+                            extension
+                        ),
+                        PcbPadStackParser.#localStackLayer(
+                            'bottom',
+                            32,
+                            'L32',
+                            padContext,
+                            extension
+                        )
+                    ],
+                    hole: PcbPadStackParser.#localStackHole(
+                        padContext,
+                        extension
+                    )
+                }
+            }
+        }
+
+        if (
+            mode === 2 &&
+            Array.isArray(extension.fullStackLayerEntries) &&
+            extension.fullStackLayerEntries.length
+        ) {
+            return {
+                localStack: {
+                    schema: 'altium-toolkit.pcb.pad-local-stack.a1',
+                    mode,
+                    modeName: String(mainRecordTail.padModeName || ''),
+                    source: 'extension-record',
+                    layers: extension.fullStackLayerEntries.map((entry) => ({
+                        role: 'layer',
+                        layerId: Number(entry.layerCode),
+                        layerKey: 'L' + Number(entry.layerCode),
+                        enabled: entry.enabled,
+                        width: entry.sizeX,
+                        height: entry.sizeY,
+                        cornerRadius: entry.cornerRadius,
+                        modeFlags: entry.modeFlags
+                    })),
+                    hole: PcbPadStackParser.#localStackHole(
+                        padContext,
+                        extension
+                    )
+                }
+            }
+        }
+
+        return {}
+    }
+
+    /**
+     * Builds one top/middle/bottom local-stack layer entry.
+     * @param {'top' | 'middle' | 'bottom'} role Layer role.
+     * @param {number | null} layerId Layer id.
+     * @param {string} layerKey Stable layer key.
+     * @param {Record<string, unknown>} padContext Parsed pad fields.
+     * @param {Record<string, unknown>} extension Extension fields.
+     * @returns {object}
+     */
+    static #localStackLayer(role, layerId, layerKey, padContext, extension) {
+        const suffix =
+            role === 'top' ? 'Top' : role === 'bottom' ? 'Bottom' : 'Mid'
+        const offset = PcbPadStackParser.#layerOffset(role, extension)
+
+        return {
+            role,
+            layerId,
+            layerKey,
+            width: Number(padContext['size' + suffix + 'X'] || 0),
+            height: Number(padContext['size' + suffix + 'Y'] || 0),
+            shape: PcbPadStackParser.#numericOrNull(
+                padContext['shape' + suffix]
+            ),
+            shapeName: PcbPadShapeCodec.padShapeName(
+                padContext['shape' + suffix]
+            ),
+            offsetX: offset.x,
+            offsetY: offset.y
+        }
+    }
+
+    /**
+     * Resolves layer offsets from extension data when present.
+     * @param {'top' | 'middle' | 'bottom'} role Layer role.
+     * @param {Record<string, unknown>} extension Extension fields.
+     * @returns {{ x: number, y: number }}
+     */
+    static #layerOffset(role, extension) {
+        const layerNumber = role === 'top' ? 1 : role === 'bottom' ? 32 : null
+        const offset = Array.isArray(extension.layerOffsets)
+            ? extension.layerOffsets.find(
+                  (entry) => entry.layerNumber === layerNumber
+              )
+            : null
+
+        return {
+            x: Number(offset?.x || 0),
+            y: Number(offset?.y || 0)
+        }
+    }
+
+    /**
+     * Builds local-stack hole geometry.
+     * @param {Record<string, unknown>} padContext Parsed pad fields.
+     * @param {Record<string, unknown>} extension Extension fields.
+     * @returns {object}
+     */
+    static #localStackHole(padContext, extension) {
+        const shape = PcbPadStackParser.#numericOrNull(extension.holeShape)
+
+        return {
+            diameter: Number(padContext.holeDiameter || 0),
+            shape,
+            shapeName:
+                shape === null ? null : PcbPadShapeCodec.holeShapeName(shape),
+            slotLength: extension.holeSlotLength ?? null,
+            rotation: extension.holeRotation ?? null
+        }
+    }
+
+    /**
+     * Converts finite numeric values and nullish values into stable output.
+     * @param {unknown} value Candidate value.
+     * @returns {number | null}
+     */
+    static #numericOrNull(value) {
+        if (value === null || value === undefined || value === '') {
+            return null
+        }
+
+        const number = Number(value)
+        return Number.isFinite(number) ? number : null
+    }
+
     /**
      * Decodes non-empty inner-layer pad sizes.
      * @param {DataView} extensionRecord

package/src/core/altium/PcbPickPlacePositionResolver.mjs

@@ -15,10 +15,16 @@ export class PcbPickPlacePositionResolver {
      * @param {{ componentIndex: number, designator: string, pattern: string, layer: string, rotation: number, x: number, y: number }[]} components
      * @param {{ componentIndex: number, pads?: { x?: number, y?: number }[] }[]} componentPrimitiveGroups
      * @param {{ sourceComponents?: { componentIndex: number, rotation?: number }[] }} [options] Resolver options.
-     * @returns {{ positionMode: string, entries: object[], modes: { componentOrigin: { positionMode: string, entries: object[] } } }}
+     * @returns {{ units: object, positionMode: string, entries: object[], modes: { componentOrigin: { units: object, positionMode: string, entries: object[] } } }}
      */
     static buildModel(components, componentPrimitiveGroups, options = {}) {
+        const units = {
+            coordinate: 'mil',
+            angle: 'deg'
+        }
+
         return {
+            units,
             positionMode: DEFAULT_POSITION_MODE,
             entries: PcbPickPlacePositionResolver.buildEntries(
                 components,
@@ -28,6 +34,7 @@ export class PcbPickPlacePositionResolver {
             ),
             modes: {
                 componentOrigin: {
+                    units,
                     positionMode: COMPONENT_ORIGIN_MODE,
                     entries: PcbPickPlacePositionResolver.buildEntries(
                         components,

package/src/core/altium/PcbRegionPrimitiveParser.mjs

@@ -165,17 +165,26 @@ export class PcbRegionPrimitiveParser {
                 net: 3,
                 polygon: 5
             })
+        const kind = PcbRegionPrimitiveParser.#numericKind(properties.KIND)
+        const legacyCutout =
+            PcbRegionPrimitiveParser.#legacyCutoutClassification(
+                properties,
+                kind
+            )
 
         return {
             region: {
                 layerId,
                 layerCode: layerId,
                 ...ownershipIndexes,
-                kind: Number(properties.KIND || 0),
+                kind,
+                ...legacyCutout.fields,
                 isKeepout: flags2 === 2,
                 isBoardCutout:
+                    legacyCutout.isBoardCutout ||
                     String(properties.ISBOARDCUTOUT || '').toUpperCase() ===
-                    'TRUE',
+                        'TRUE',
+                ...legacyCutout.cutoutFlags,
                 isShapeBased:
                     shapeBased ||
                     String(properties.ISSHAPEBASED || '').toUpperCase() ===
@@ -188,6 +197,66 @@ export class PcbRegionPrimitiveParser {
         }
     }
 
+    /**
+     * Parses a region kind while avoiding NaN for legacy symbolic labels.
+     * @param {string | undefined} rawKind Raw KIND value.
+     * @returns {number | null}
+     */
+    static #numericKind(rawKind) {
+        if (rawKind === undefined || rawKind === null || rawKind === '') {
+            return 0
+        }
+
+        const kind = Number(rawKind)
+        return Number.isFinite(kind) ? kind : null
+    }
+
+    /**
+     * Builds cutout fields from legacy string KIND labels.
+     * @param {Record<string, string>} properties Native property map.
+     * @param {number | null} numericKind Parsed numeric kind.
+     * @returns {{ isBoardCutout: boolean, fields: object, cutoutFlags: object }}
+     */
+    static #legacyCutoutClassification(properties, numericKind) {
+        const rawKind = String(properties.KIND || '').trim()
+        if (numericKind !== null || !rawKind) {
+            return {
+                isBoardCutout: false,
+                fields: {},
+                cutoutFlags: {}
+            }
+        }
+
+        const normalized = rawKind.replace(/[^a-z0-9]/giu, '').toLowerCase()
+        const isBoardCutout = normalized === 'boardcutout'
+        const isPolygonPourCutout =
+            normalized === 'polygonpourcutout' ||
+            normalized === 'polygoncutout' ||
+            normalized === 'pourcutout'
+        const classification =
+            isBoardCutout || isPolygonPourCutout
+                ? {
+                      isBoardCutout,
+                      isPolygonPourCutout,
+                      source: 'legacy-kind',
+                      rawKind
+                  }
+                : null
+
+        return {
+            isBoardCutout,
+            fields: {
+                rawKind
+            },
+            cutoutFlags: classification
+                ? {
+                      isPolygonPourCutout,
+                      cutoutClassification: classification
+                  }
+                : {}
+        }
+    }
+
     /**
      * Reads one simple double-coordinate region vertex list.
      * @param {DataView} view