altium-toolkit 1.0.9 → 1.1.0

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/PcbBomProfileBuilder.mjs

@@ -0,0 +1,263 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds PCB-only BOM grouping and parameter-normalization profiles.
+ */
+export class PcbBomProfileBuilder {
+    static SCHEMA_ID = 'altium-toolkit.pcb.bom-profile.a1'
+
+    /**
+     * Builds a deterministic BOM profile from PCB component rows.
+     * @param {object[]} components Normalized PCB component rows.
+     * @param {{ source?: string }} options Build options.
+     * @returns {object}
+     */
+    static build(components, options = {}) {
+        const normalizedComponents = (components || []).map((component) =>
+            PcbBomProfileBuilder.#component(component)
+        )
+        const included = normalizedComponents.filter(
+            (component) => component.includeInBom
+        )
+        const groups = PcbBomProfileBuilder.#groups(included)
+        const exclusions = normalizedComponents
+            .filter((component) => !component.includeInBom)
+            .map((component) => ({
+                designator: component.designator,
+                reason: 'component-kind:no-bom'
+            }))
+
+        return {
+            schema: PcbBomProfileBuilder.SCHEMA_ID,
+            source: String(options.source || 'pcb-document'),
+            summary: {
+                componentCount: normalizedComponents.length,
+                includedComponentCount: included.length,
+                excludedComponentCount: exclusions.length,
+                groupCount: groups.length,
+                normalizedParameterCount:
+                    PcbBomProfileBuilder.#normalizedParameterCount(included)
+            },
+            groups,
+            components: normalizedComponents,
+            exclusions
+        }
+    }
+
+    /**
+     * Normalizes one component into a BOM profile row.
+     * @param {object} component Source component.
+     * @returns {object}
+     */
+    static #component(component) {
+        const normalizedParameters = PcbBomProfileBuilder.#normalizedParameters(
+            component?.parameters || {}
+        )
+        const sourceParameterNames = Object.keys(component?.parameters || {})
+        const includeInBom =
+            component?.componentKind?.includeInBom === false ? false : true
+        const value =
+            normalizedParameters.comment ||
+            component?.description ||
+            component?.value ||
+            component?.pattern ||
+            ''
+
+        return {
+            designator: String(component?.designator || ''),
+            includeInBom,
+            componentKind: component?.componentKind?.name || 'standard',
+            pattern: String(component?.pattern || ''),
+            source: String(component?.source || ''),
+            value,
+            normalizedParameters,
+            sourceParameterNames
+        }
+    }
+
+    /**
+     * Builds grouped BOM rows from included components.
+     * @param {object[]} components Included normalized components.
+     * @returns {object[]}
+     */
+    static #groups(components) {
+        const byKey = new Map()
+
+        for (const component of components || []) {
+            const key = PcbBomProfileBuilder.#groupKey(component)
+            if (!byKey.has(key)) {
+                byKey.set(key, {
+                    key,
+                    quantity: 0,
+                    designators: [],
+                    pattern: component.pattern,
+                    source: component.source,
+                    value: component.value,
+                    normalizedParameters: {}
+                })
+            }
+            const group = byKey.get(key)
+            group.quantity += 1
+            group.designators.push(component.designator)
+            group.normalizedParameters = PcbBomProfileBuilder.#mergeParameters(
+                group.normalizedParameters,
+                component.normalizedParameters
+            )
+        }
+
+        return [...byKey.values()].map((group) => ({
+            ...group,
+            designators: PcbBomProfileBuilder.#sortDesignators(
+                group.designators
+            ),
+            normalizedParameters:
+                PcbBomProfileBuilder.#stripGroupingOnlyParameters(
+                    group.normalizedParameters
+                )
+        }))
+    }
+
+    /**
+     * Builds the stable grouping key for one included component.
+     * @param {object} component Normalized component row.
+     * @returns {string}
+     */
+    static #groupKey(component) {
+        const parameters = component.normalizedParameters || {}
+        return [
+            parameters.manufacturer || '',
+            parameters.manufacturerPartNumber || '',
+            parameters.supplierPartNumber || '',
+            component.pattern || '',
+            component.value || ''
+        ].join('|')
+    }
+
+    /**
+     * Converts source parameters into normalized BOM aliases.
+     * @param {Record<string, string>} parameters Source parameters.
+     * @returns {Record<string, string>}
+     */
+    static #normalizedParameters(parameters) {
+        const normalized = {}
+
+        for (const [name, value] of Object.entries(parameters || {})) {
+            const text = String(value || '').trim()
+            if (!text) continue
+
+            const alias = PcbBomProfileBuilder.#aliasForName(name)
+            if (alias && !normalized[alias]) {
+                normalized[alias] = text
+            }
+            if (
+                alias === 'supplierPartNumber' &&
+                /jlcpcb/iu.test(String(name || '')) &&
+                !normalized.supplier
+            ) {
+                normalized.supplier = 'JLCPCB'
+            }
+        }
+
+        return normalized
+    }
+
+    /**
+     * Resolves a normalized alias for a source parameter name.
+     * @param {string} name Source parameter name.
+     * @returns {string}
+     */
+    static #aliasForName(name) {
+        const key = String(name || '')
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/gu, '')
+
+        if (['manufacturer', 'mfr', 'mfg'].includes(key)) {
+            return 'manufacturer'
+        }
+        if (
+            [
+                'manufacturerpartnumber',
+                'manufacturerpn',
+                'mfrpartnumber',
+                'mfgpartnumber',
+                'mpn'
+            ].includes(key)
+        ) {
+            return 'manufacturerPartNumber'
+        }
+        if (
+            [
+                'supplierpartnumber',
+                'supplierpn',
+                'supplierpart',
+                'jlcpcbpart',
+                'jlcpcbpartnumber',
+                'jlcpcbpartno'
+            ].includes(key)
+        ) {
+            return 'supplierPartNumber'
+        }
+        if (key === 'category') return 'category'
+        if (key === 'comment' || key === 'value') return 'comment'
+
+        return ''
+    }
+
+    /**
+     * Merges normalized parameters while preserving the first non-empty value.
+     * @param {object} existing Existing values.
+     * @param {object} incoming Candidate values.
+     * @returns {object}
+     */
+    static #mergeParameters(existing, incoming) {
+        const merged = { ...(existing || {}) }
+
+        for (const [key, value] of Object.entries(incoming || {})) {
+            if (merged[key] || value === undefined || value === '') continue
+            merged[key] = value
+        }
+
+        return merged
+    }
+
+    /**
+     * Removes fields that are component-specific rather than group identity.
+     * @param {object} parameters Normalized parameters.
+     * @returns {object}
+     */
+    static #stripGroupingOnlyParameters(parameters) {
+        const { comment: _comment, ...rest } = parameters || {}
+        return rest
+    }
+
+    /**
+     * Counts normalized source aliases used for group identity.
+     * @param {object[]} components Included component rows.
+     * @returns {number}
+     */
+    static #normalizedParameterCount(components) {
+        return (components || []).reduce(
+            (count, component) =>
+                count +
+                Object.keys(component.normalizedParameters || {}).filter(
+                    (key) => !['comment', 'supplier'].includes(key)
+                ).length,
+            0
+        )
+    }
+
+    /**
+     * Sorts designators in a stable natural-ish order.
+     * @param {string[]} designators Designator list.
+     * @returns {string[]}
+     */
+    static #sortDesignators(designators) {
+        return (designators || []).slice().sort((left, right) =>
+            String(left).localeCompare(String(right), undefined, {
+                numeric: true
+            })
+        )
+    }
+}

package/src/core/altium/PcbComponentKindPolicy.mjs

@@ -0,0 +1,146 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+const { getField, parseNumericField } = ParserUtils
+
+const KIND_BY_VALUE = {
+    0: {
+        name: 'standard',
+        displayName: 'Standard',
+        includeInBom: true,
+        includeInNetlist: true,
+        includeInPnp: true
+    },
+    1: {
+        name: 'mechanical',
+        displayName: 'Mechanical',
+        includeInBom: true,
+        includeInNetlist: true,
+        includeInPnp: true
+    },
+    2: {
+        name: 'graphical',
+        displayName: 'Graphical',
+        includeInBom: false,
+        includeInNetlist: false,
+        includeInPnp: false
+    },
+    3: {
+        name: 'net-tie-bom',
+        displayName: 'Net Tie BOM',
+        includeInBom: true,
+        includeInNetlist: true,
+        includeInPnp: true
+    },
+    4: {
+        name: 'net-tie-no-bom',
+        displayName: 'Net Tie No BOM',
+        includeInBom: false,
+        includeInNetlist: true,
+        includeInPnp: true
+    },
+    5: {
+        name: 'standard-no-bom',
+        displayName: 'Standard No BOM',
+        includeInBom: false,
+        includeInNetlist: true,
+        includeInPnp: true
+    },
+    6: {
+        name: 'jumper',
+        displayName: 'Jumper',
+        includeInBom: true,
+        includeInNetlist: true,
+        includeInPnp: true
+    }
+}
+
+/**
+ * Normalizes native PCB component kind fields and participation policy.
+ */
+export class PcbComponentKindPolicy {
+    /**
+     * Parses native versioned component-kind fields.
+     * @param {Record<string, string | string[]>} fields Native component row.
+     * @returns {{ value: number, name: string, displayName: string, includeInBom: boolean, includeInNetlist: boolean, includeInPnp: boolean } | undefined}
+     */
+    static parse(fields) {
+        if (!PcbComponentKindPolicy.#hasKindField(fields)) return undefined
+
+        const value = PcbComponentKindPolicy.#kindValue(fields)
+        const policy = KIND_BY_VALUE[value] || {
+            name: 'unknown',
+            displayName: 'Unknown',
+            includeInBom: true,
+            includeInNetlist: true,
+            includeInPnp: true
+        }
+
+        return {
+            value,
+            ...policy
+        }
+    }
+
+    /**
+     * Returns true when a component row carries any native kind field.
+     * @param {Record<string, string | string[]>} fields Native component row.
+     * @returns {boolean}
+     */
+    static #hasKindField(fields) {
+        return [
+            'COMPONENTKIND',
+            'ComponentKind',
+            'COMPONENTKINDVERSION2',
+            'ComponentKindVersion2',
+            'COMPONENTKINDVERSION3',
+            'ComponentKindVersion3'
+        ].some((key) => Object.hasOwn(fields || {}, key))
+    }
+
+    /**
+     * Resolves the effective native component kind from versioned fields.
+     * @param {Record<string, string | string[]>} fields Native component row.
+     * @returns {number}
+     */
+    static #kindValue(fields) {
+        const v1 = PcbComponentKindPolicy.#numericField(fields, [
+            'COMPONENTKIND',
+            'ComponentKind'
+        ])
+        const v2 = PcbComponentKindPolicy.#numericField(fields, [
+            'COMPONENTKINDVERSION2',
+            'ComponentKindVersion2'
+        ])
+        const v3 = PcbComponentKindPolicy.#numericField(fields, [
+            'COMPONENTKINDVERSION3',
+            'ComponentKindVersion3'
+        ])
+
+        if (v3 === 6) return v3
+        if (v2 !== null && v2 >= 5) return v2
+        return v1 ?? 0
+    }
+
+    /**
+     * Returns the first finite numeric value from possible field names.
+     * @param {Record<string, string | string[]>} fields Native fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {number | null}
+     */
+    static #numericField(fields, keys) {
+        for (const key of keys) {
+            const value = parseNumericField(fields, key)
+            if (Number.isFinite(value)) return value
+
+            const raw = getField(fields, key)
+            const parsed = Number.parseInt(String(raw ?? '').trim(), 10)
+            if (Number.isFinite(parsed)) return parsed
+        }
+
+        return null
+    }
+}