altium-toolkit 1.0.8 → 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/PcbCustomPadShapeParser.mjs

@@ -0,0 +1,244 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbSidecarRecordParser } from './PcbSidecarRecordParser.mjs'
+
+/**
+ * Decodes custom pad shape sidecars and links pads to authored geometry.
+ */
+export class PcbCustomPadShapeParser {
+    static #SOURCE_STREAM = 'CustomShapes/Data'
+
+    /**
+     * Parses custom pad shape sidecar records.
+     * @param {Uint8Array | ArrayBuffer | undefined} dataBytes
+     * @param {string} [sourceStream]
+     * @returns {{ entries: object[], byPrimitiveIndex: Record<string, object[]> }}
+     */
+    static parse(
+        dataBytes,
+        sourceStream = PcbCustomPadShapeParser.#SOURCE_STREAM
+    ) {
+        const entries = PcbSidecarRecordParser.parseLengthPrefixedRecords(
+            dataBytes,
+            sourceStream
+        )
+            .map((record) => PcbCustomPadShapeParser.#normalizeRecord(record))
+            .filter(Boolean)
+        const byPrimitiveIndex = {}
+
+        for (const entry of entries) {
+            const key = String(entry.primitiveIndex)
+            byPrimitiveIndex[key] = byPrimitiveIndex[key] || []
+            byPrimitiveIndex[key].push(entry)
+        }
+
+        return {
+            entries,
+            byPrimitiveIndex
+        }
+    }
+
+    /**
+     * Links custom shape entries to pad records in place.
+     * @param {object[]} pads
+     * @param {{ byPrimitiveIndex?: Record<string, object[]> }} customShapes
+     * @param {{ regions?: object[], shapeBasedRegions?: object[], arcs?: object[], tracks?: object[], fills?: object[] }} geometry
+     */
+    static attachToPads(pads, customShapes, geometry = {}) {
+        if (!Array.isArray(pads) || !customShapes?.byPrimitiveIndex) {
+            return
+        }
+
+        for (let index = 0; index < pads.length; index += 1) {
+            const entries = customShapes.byPrimitiveIndex[String(index)] || []
+            if (!entries.length) {
+                continue
+            }
+
+            pads[index].customShape =
+                PcbCustomPadShapeParser.#buildPadCustomShape(
+                    index,
+                    entries,
+                    geometry
+                )
+        }
+    }
+
+    /**
+     * Normalizes one custom-shape sidecar record.
+     * @param {{ fields: Record<string, string>, sourceStream: string }} record
+     * @returns {object | null}
+     */
+    static #normalizeRecord(record) {
+        const primitiveIndex = PcbSidecarRecordParser.parseInteger(
+            PcbSidecarRecordParser.firstField(record.fields, [
+                'PRIMITIVEINDEX',
+                'PADINDEX',
+                'ANCHORINDEX'
+            ])
+        )
+
+        if (primitiveIndex === null) {
+            return null
+        }
+
+        return {
+            primitiveIndex,
+            layer: PcbSidecarRecordParser.firstField(record.fields, ['LAYER']),
+            layerId: PcbSidecarRecordParser.parseInteger(
+                PcbSidecarRecordParser.firstField(record.fields, [
+                    'LAYERID',
+                    'LAYERINDEX'
+                ])
+            ),
+            pasteMask: PcbSidecarRecordParser.parseBoolean(
+                PcbSidecarRecordParser.firstField(record.fields, [
+                    'PASTEMASK',
+                    'HASPASTEMASK'
+                ])
+            ),
+            solderMask: PcbSidecarRecordParser.parseBoolean(
+                PcbSidecarRecordParser.firstField(record.fields, [
+                    'SOLDERMASK',
+                    'HASSOLDERMASK'
+                ])
+            ),
+            regionIndexes: PcbCustomPadShapeParser.#parseIndexList(
+                record.fields,
+                ['REGIONINDEX', 'REGIONINDEXES']
+            ),
+            shapeRegionIndexes: PcbCustomPadShapeParser.#parseIndexList(
+                record.fields,
+                ['SHAPEREGIONINDEX', 'SHAPEREGIONINDEXES']
+            ),
+            arcIndexes: PcbCustomPadShapeParser.#parseIndexList(record.fields, [
+                'ARCINDEX',
+                'ARCINDEXES'
+            ]),
+            trackIndexes: PcbCustomPadShapeParser.#parseIndexList(
+                record.fields,
+                ['TRACKINDEX', 'TRACKINDEXES']
+            ),
+            fillIndexes: PcbCustomPadShapeParser.#parseIndexList(
+                record.fields,
+                ['FILLINDEX', 'FILLINDEXES']
+            ),
+            sourceStream: record.sourceStream,
+            fields: record.fields
+        }
+    }
+
+    /**
+     * Builds the custom-shape object attached to a pad.
+     * @param {number} primitiveIndex
+     * @param {object[]} entries
+     * @param {object} geometry
+     * @returns {object}
+     */
+    static #buildPadCustomShape(primitiveIndex, entries, geometry) {
+        return {
+            primitiveIndex,
+            sourceStream: entries[0]?.sourceStream || '',
+            layers: entries.map((entry) =>
+                PcbCustomPadShapeParser.#buildLayerShape(entry, geometry)
+            )
+        }
+    }
+
+    /**
+     * Resolves one layer-specific shape entry.
+     * @param {object} entry
+     * @param {object} geometry
+     * @returns {object}
+     */
+    static #buildLayerShape(entry, geometry) {
+        return {
+            layer: entry.layer,
+            layerId: entry.layerId,
+            pasteMask: entry.pasteMask,
+            solderMask: entry.solderMask,
+            regions: PcbCustomPadShapeParser.#lookupMany(
+                geometry.regions || [],
+                entry.regionIndexes
+            ),
+            arcs: PcbCustomPadShapeParser.#lookupMany(
+                geometry.arcs || [],
+                entry.arcIndexes
+            ),
+            tracks: PcbCustomPadShapeParser.#lookupMany(
+                geometry.tracks || [],
+                entry.trackIndexes
+            ),
+            fills: PcbCustomPadShapeParser.#lookupMany(
+                geometry.fills || [],
+                entry.fillIndexes
+            ),
+            ...(entry.shapeRegionIndexes.length
+                ? {
+                      shapeRegions: PcbCustomPadShapeParser.#lookupMany(
+                          geometry.shapeBasedRegions || [],
+                          entry.shapeRegionIndexes
+                      )
+                  }
+                : {})
+        }
+    }
+
+    /**
+     * Resolves several primitive indexes into object references.
+     * @param {object[]} collection
+     * @param {number[]} indexes
+     * @returns {object[]}
+     */
+    static #lookupMany(collection, indexes) {
+        return indexes
+            .map((index) => collection[index])
+            .filter((value) => value && typeof value === 'object')
+    }
+
+    /**
+     * Parses one or more integer indexes from scalar or numbered fields.
+     * @param {Record<string, string>} fields
+     * @param {string[]} baseKeys
+     * @returns {number[]}
+     */
+    static #parseIndexList(fields, baseKeys) {
+        const indexes = []
+
+        for (const baseKey of baseKeys) {
+            const directValue = fields[baseKey]
+            if (directValue) {
+                indexes.push(
+                    ...PcbCustomPadShapeParser.#splitIndexes(directValue)
+                )
+            }
+
+            for (const [key, value] of Object.entries(fields)) {
+                if (!key.startsWith(baseKey)) {
+                    continue
+                }
+                if (key === baseKey) {
+                    continue
+                }
+
+                indexes.push(...PcbCustomPadShapeParser.#splitIndexes(value))
+            }
+        }
+
+        return [...new Set(indexes)]
+    }
+
+    /**
+     * Parses a comma/semicolon-delimited index field.
+     * @param {string} value
+     * @returns {number[]}
+     */
+    static #splitIndexes(value) {
+        return String(value || '')
+            .split(/[;,\s]+/u)
+            .map((part) => PcbSidecarRecordParser.parseInteger(part))
+            .filter(Number.isInteger)
+    }
+}

package/src/core/altium/PcbDefaultsParser.mjs

@@ -0,0 +1,171 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+const { getField, parseNumericField, toColor } = ParserUtils
+
+/**
+ * Builds read-only PCB and footprint-library default metadata.
+ */
+export class PcbDefaultsParser {
+    static SCHEMA_ID = 'altium-toolkit.pcb.defaults.a1'
+
+    /**
+     * Parses a defaults read model from one field bag.
+     * @param {Record<string, string | string[]> | undefined} fields Source fields.
+     * @param {string} source Defaults source label.
+     * @returns {object | null}
+     */
+    static parse(fields, source) {
+        const board = PcbDefaultsParser.#stripEmpty({
+            defaultFontName: PcbDefaultsParser.#firstField(fields, [
+                'DEFAULTFONTNAME',
+                'FONTNAME',
+                'TEXTFONTNAME'
+            ]),
+            units: PcbDefaultsParser.#firstField(fields, [
+                'UNITS',
+                'BOARDUNITS',
+                'MEASUREMENTUNITS'
+            ])
+        })
+        const primitiveStyles = PcbDefaultsParser.#stripEmpty({
+            trackWidthMil: PcbDefaultsParser.#firstNumber(fields, [
+                'TRACKWIDTH',
+                'DEFAULTTRACKWIDTH',
+                'ROUTINGWIDTH'
+            ]),
+            viaHoleSizeMil: PcbDefaultsParser.#firstNumber(fields, [
+                'VIAHOLESIZE',
+                'VIAHOLE',
+                'DEFAULTVIAHOLESIZE'
+            ]),
+            viaDiameterMil: PcbDefaultsParser.#firstNumber(fields, [
+                'VIADIAMETER',
+                'VIASIZE',
+                'DEFAULTVIADIAMETER'
+            ])
+        })
+        const maskPaste = PcbDefaultsParser.#stripEmpty({
+            solder: PcbDefaultsParser.#stripEmpty({
+                expansionMil: PcbDefaultsParser.#firstNumber(fields, [
+                    'SOLDERMASKEXPANSION',
+                    'SOLDERMASKEXPANSION_DEFAULT',
+                    'MASKEXPANSION'
+                ])
+            }),
+            paste: PcbDefaultsParser.#stripEmpty({
+                expansionMil: PcbDefaultsParser.#firstNumber(fields, [
+                    'PASTEMASKEXPANSION',
+                    'PASTEMASKEXPANSION_DEFAULT',
+                    'PASTEEXPANSION'
+                ])
+            })
+        })
+        const clearances = PcbDefaultsParser.#stripEmpty({
+            defaultClearanceMil: PcbDefaultsParser.#firstNumber(fields, [
+                'CLEARANCE',
+                'DEFAULTCLEARANCE',
+                'MINCLEARANCE'
+            ])
+        })
+        const colors = PcbDefaultsParser.#stripEmpty({
+            defaultColor: PcbDefaultsParser.#firstColor(fields, [
+                'DEFAULTCOLOR',
+                'COLOR'
+            ]),
+            solderMaskTopColor: PcbDefaultsParser.#firstColor(fields, [
+                'SOLDERMASKTOPCOLOR',
+                'TOPSOLDERMASKCOLOR',
+                'CFG3D.TOPSOLDERMASKCOLOR'
+            ]),
+            solderMaskBottomColor: PcbDefaultsParser.#firstColor(fields, [
+                'SOLDERMASKBOTTOMCOLOR',
+                'BOTTOMSOLDERMASKCOLOR',
+                'CFG3D.BOTTOMSOLDERMASKCOLOR'
+            ])
+        })
+        const defaults = PcbDefaultsParser.#stripEmpty({
+            schema: PcbDefaultsParser.SCHEMA_ID,
+            source,
+            board,
+            primitiveStyles,
+            maskPaste,
+            clearances,
+            colors
+        })
+
+        return Object.keys(defaults).length > 2 ? defaults : null
+    }
+
+    /**
+     * Returns the first populated field value.
+     * @param {Record<string, string | string[]> | undefined} fields Source fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {string}
+     */
+    static #firstField(fields, keys) {
+        for (const key of keys) {
+            const value = getField(fields, key)
+            if (value) return value
+        }
+
+        return ''
+    }
+
+    /**
+     * Returns the first parsed numeric field.
+     * @param {Record<string, string | string[]> | undefined} fields Source fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {number | undefined}
+     */
+    static #firstNumber(fields, keys) {
+        for (const key of keys) {
+            const value = parseNumericField(fields, key)
+            if (value !== null) return value
+        }
+
+        return undefined
+    }
+
+    /**
+     * Returns the first parsed color field.
+     * @param {Record<string, string | string[]> | undefined} fields Source fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {string}
+     */
+    static #firstColor(fields, keys) {
+        for (const key of keys) {
+            if (getField(fields, key)) return toColor(fields[key], '')
+        }
+
+        return ''
+    }
+
+    /**
+     * Removes empty properties from one object.
+     * @param {Record<string, unknown>} object Source object.
+     * @returns {Record<string, unknown>}
+     */
+    static #stripEmpty(object) {
+        const result = {}
+
+        for (const [key, value] of Object.entries(object || {})) {
+            if (value === undefined || value === null || value === '') {
+                continue
+            }
+            if (
+                typeof value === 'object' &&
+                !Array.isArray(value) &&
+                Object.keys(value).length === 0
+            ) {
+                continue
+            }
+            result[key] = value
+        }
+
+        return result
+    }
+}