altium-toolkit 1.0.10 → 1.1.0

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
+    }
+}

package/src/core/altium/PcbLayerStackFidelityReportBuilder.mjs

@@ -0,0 +1,141 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Classifies layer-stack source evidence and regeneration limits.
+ */
+export class PcbLayerStackFidelityReportBuilder {
+    static SCHEMA_ID = 'altium-toolkit.pcb.layer-stack-fidelity.a1'
+
+    /**
+     * Builds a source-fidelity report for a layer-stack read model.
+     * @param {object} readModel Layer-stack read model.
+     * @returns {object}
+     */
+    static build(readModel) {
+        const semanticSections =
+            PcbLayerStackFidelityReportBuilder.#semanticSections(readModel)
+        const nativeCacheSections =
+            PcbLayerStackFidelityReportBuilder.#nativeCacheSections(readModel)
+        const interchangeOnlySections =
+            PcbLayerStackFidelityReportBuilder.#interchangeOnlySections(
+                readModel
+            )
+        const diagnostics = readModel?.diagnostics || []
+        const unsupportedRegeneration =
+            PcbLayerStackFidelityReportBuilder.#unsupportedRegeneration(
+                nativeCacheSections,
+                diagnostics
+            )
+
+        return {
+            schema: PcbLayerStackFidelityReportBuilder.SCHEMA_ID,
+            sourceDocument: String(readModel?.source?.fileName || ''),
+            summary: {
+                semanticLayerCount: (readModel?.layers || []).length,
+                nativeCacheFeatureCount: nativeCacheSections.length,
+                interchangeOnlyFeatureCount: interchangeOnlySections.length,
+                unsupportedRegenerationCount: unsupportedRegeneration.length,
+                diagnosticCount: diagnostics.length
+            },
+            capabilities: {
+                semanticRead: semanticSections.length > 0,
+                nativeCacheRead: nativeCacheSections.length > 0,
+                interchangeRead: interchangeOnlySections.length > 0,
+                deterministicReport: true,
+                nativeRegeneration: false
+            },
+            semanticSections,
+            nativeCacheSections,
+            interchangeOnlySections,
+            unsupportedRegeneration,
+            diagnostics
+        }
+    }
+
+    /**
+     * Lists semantic layer-stack sections in the model.
+     * @param {object} readModel Layer-stack read model.
+     * @returns {string[]}
+     */
+    static #semanticSections(readModel) {
+        return [
+            ['layers', readModel?.layers],
+            ['substacks', readModel?.substacks],
+            ['branches', readModel?.branches],
+            ['impedanceProfiles', readModel?.impedanceProfiles]
+        ]
+            .filter(([, values]) => (values || []).length > 0)
+            .map(([section]) => section)
+    }
+
+    /**
+     * Lists native-cache-only sections represented in the model.
+     * @param {object} readModel Layer-stack read model.
+     * @returns {string[]}
+     */
+    static #nativeCacheSections(readModel) {
+        const sections = []
+        const sourceMap = readModel?.sourceMap || {}
+
+        if (sourceMap.registryEntryCount > 0) sections.push('source.registry')
+        if (sourceMap.sourceKeyCount > 0) sections.push('source.keys')
+        if ((readModel?.topLevelBendLines || []).length > 0) {
+            sections.push('bendLines')
+        }
+        if (sourceMap.cavityRegionCount > 0) sections.push('cavities')
+        if (sourceMap.surfaceFinishCount > 0) sections.push('surfaceFinish')
+
+        return sections
+    }
+
+    /**
+     * Lists fields that are preserved as interchange-specific metadata.
+     * @param {object} readModel Layer-stack read model.
+     * @returns {string[]}
+     */
+    static #interchangeOnlySections(readModel) {
+        const layers = readModel?.layers || []
+        const sections = []
+
+        if (layers.some((layer) => layer.stackupxShared !== undefined)) {
+            sections.push('layers.stackupxShared')
+        }
+        if (
+            layers.some(
+                (layer) =>
+                    Object.keys(layer.stackupxProperties || {}).length > 0
+            )
+        ) {
+            sections.push('layers.stackupxProperties')
+        }
+
+        return sections
+    }
+
+    /**
+     * Describes why native stack regeneration is intentionally unsupported.
+     * @param {string[]} nativeCacheSections Native cache sections.
+     * @param {object[]} diagnostics Read-model diagnostics.
+     * @returns {object[]}
+     */
+    static #unsupportedRegeneration(nativeCacheSections, diagnostics) {
+        const issues = []
+
+        if (nativeCacheSections.length > 0) {
+            issues.push({
+                section: 'native-cache',
+                reason: 'Native cache metadata is preserved for review but not regenerated.'
+            })
+        }
+        if ((diagnostics || []).length > 0) {
+            issues.push({
+                section: 'diagnostics',
+                reason: 'Unresolved references prevent equivalent native regeneration.'
+            })
+        }
+
+        return issues
+    }
+}