altium-toolkit 1.0.7 → 1.0.9

package/src/core/altium/ProjectVariantViewBuilder.mjs

@@ -0,0 +1,334 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds consumer-facing effective views for project variants.
+ */
+export class ProjectVariantViewBuilder {
+    /**
+     * Applies one project variant to bundle-level BOM, PnP, component, and net
+     * collections.
+     * @param {object} bundle Project design bundle.
+     * @param {{ variantName?: string }} options Variant selection options.
+     * @returns {object}
+     */
+    static build(bundle, options = {}) {
+        const variant = ProjectVariantViewBuilder.#findVariant(
+            bundle,
+            options.variantName
+        )
+        const dnp = new Set(variant?.dnp || [])
+        const parameterOverrides = variant?.parameterOverrides || {}
+        const alternateFitted = variant?.alternateFitted || {}
+        const annotations = bundle?.annotations?.bySourceDesignator || {}
+        const includeVariantDetails =
+            ProjectVariantViewBuilder.#hasKeys(alternateFitted) ||
+            ProjectVariantViewBuilder.#hasKeys(annotations)
+
+        return {
+            name: variant?.description || options.variantName || '',
+            uniqueId: variant?.uniqueId || '',
+            dnp: [...dnp],
+            parameterOverrides,
+            ...(includeVariantDetails ? { alternateFitted } : {}),
+            bom: ProjectVariantViewBuilder.#applyBomVariant(
+                bundle?.bom || [],
+                dnp,
+                parameterOverrides,
+                alternateFitted,
+                annotations,
+                includeVariantDetails
+            ),
+            pnp: {
+                ...(bundle?.pnp || {}),
+                entries: (bundle?.pnp?.entries || [])
+                    .filter((entry) => !dnp.has(entry.designator))
+                    .map((entry) =>
+                        ProjectVariantViewBuilder.#applyDesignatorAnnotation(
+                            entry,
+                            annotations
+                        )
+                    )
+            },
+            nets: ProjectVariantViewBuilder.#applyNetVariant(
+                bundle?.nets || [],
+                dnp,
+                annotations
+            ),
+            components: (bundle?.components || []).map((component) =>
+                ProjectVariantViewBuilder.#applyComponentVariant(
+                    component,
+                    dnp,
+                    parameterOverrides,
+                    alternateFitted,
+                    annotations,
+                    includeVariantDetails
+                )
+            )
+        }
+    }
+
+    /**
+     * Finds the requested variant or the current project variant.
+     * @param {object} bundle Project design bundle.
+     * @param {string | undefined} variantName Requested variant name.
+     * @returns {object | null}
+     */
+    static #findVariant(bundle, variantName) {
+        const variants = bundle?.variants || bundle?.project?.variants || []
+        const requested =
+            variantName || bundle?.project?.design?.CurrentVariant || ''
+        if (!requested) {
+            return variants.find((variant) => variant.isCurrent) || null
+        }
+
+        const lookup = requested.toLowerCase()
+        return (
+            variants.find(
+                (variant) =>
+                    String(variant.description || '').toLowerCase() ===
+                        lookup ||
+                    String(variant.uniqueId || '').toLowerCase() === lookup
+            ) ||
+            variants.find((variant) => variant.isCurrent) ||
+            null
+        )
+    }
+
+    /**
+     * Applies DNP and parameter overrides to BOM rows.
+     * @param {object[]} bom BOM rows.
+     * @param {Set<string>} dnp DNP designators.
+     * @param {Record<string, Record<string, string>>} parameterOverrides Overrides by designator.
+     * @param {Record<string, object>} alternateFitted Alternate fitted rows by designator.
+     * @param {Record<string, object>} annotations Annotation rows by source designator.
+     * @param {boolean} includeVariantDetails Whether to expose alternate metadata.
+     * @returns {object[]}
+     */
+    static #applyBomVariant(
+        bom,
+        dnp,
+        parameterOverrides,
+        alternateFitted,
+        annotations,
+        includeVariantDetails
+    ) {
+        return (bom || [])
+            .flatMap((row) =>
+                (row.designators || []).map((designator) =>
+                    ProjectVariantViewBuilder.#applyBomDesignatorVariant(
+                        row,
+                        designator,
+                        parameterOverrides,
+                        alternateFitted,
+                        annotations,
+                        includeVariantDetails
+                    )
+                )
+            )
+            .filter(
+                (row) => !dnp.has(row.sourceDesignator || row.designators[0])
+            )
+    }
+
+    /**
+     * Applies one designator's parameter overrides to a BOM row.
+     * @param {object} row Source BOM row.
+     * @param {string} designator Designator.
+     * @param {Record<string, Record<string, string>>} parameterOverrides Overrides by designator.
+     * @param {Record<string, object>} alternateFitted Alternate fitted rows by designator.
+     * @param {Record<string, object>} annotations Annotation rows by source designator.
+     * @param {boolean} includeVariantDetails Whether to expose alternate metadata.
+     * @returns {object}
+     */
+    static #applyBomDesignatorVariant(
+        row,
+        designator,
+        parameterOverrides,
+        alternateFitted,
+        annotations,
+        includeVariantDetails
+    ) {
+        const parameters = parameterOverrides[designator] || {}
+        const alternate = alternateFitted[designator] || null
+        const value =
+            parameters.Comment ||
+            parameters.Value ||
+            alternate?.comment ||
+            alternate?.description ||
+            row.value
+
+        return {
+            ...row,
+            designators: [
+                ProjectVariantViewBuilder.#compiledDesignator(
+                    designator,
+                    annotations
+                )
+            ],
+            ...(includeVariantDetails ? { sourceDesignator: designator } : {}),
+            quantity: 1,
+            value,
+            source: alternate?.libReference || row.source,
+            pattern: alternate?.footprint || row.pattern,
+            parameters,
+            ...(includeVariantDetails
+                ? { alternateFitted: alternate || null }
+                : {})
+        }
+    }
+
+    /**
+     * Applies DNP filtering metadata to normalized nets.
+     * @param {object[]} nets Bundle nets.
+     * @param {Set<string>} dnp DNP designators.
+     * @param {Record<string, object>} annotations Annotation rows by source designator.
+     * @returns {object[]}
+     */
+    static #applyNetVariant(nets, dnp, annotations) {
+        return (nets || []).map((net) => {
+            const excludedDesignators = []
+            const pins = (net.pins || [])
+                .filter((pin) => {
+                    const designator =
+                        pin.componentDesignator || pin.ownerIndex || ''
+                    if (dnp.has(designator)) {
+                        excludedDesignators.push(designator)
+                        return false
+                    }
+                    return true
+                })
+                .map((pin) =>
+                    ProjectVariantViewBuilder.#applyPinAnnotation(
+                        pin,
+                        annotations
+                    )
+                )
+
+            return {
+                ...net,
+                pins,
+                excludedDesignators:
+                    ProjectVariantViewBuilder.#dedupe(excludedDesignators)
+            }
+        })
+    }
+
+    /**
+     * Applies DNP and parameter metadata to one component entry.
+     * @param {object} component Bundle component.
+     * @param {Set<string>} dnp DNP designators.
+     * @param {Record<string, Record<string, string>>} parameterOverrides Overrides by designator.
+     * @param {Record<string, object>} alternateFitted Alternate fitted rows by designator.
+     * @param {Record<string, object>} annotations Annotation rows by source designator.
+     * @param {boolean} includeVariantDetails Whether to expose alternate metadata.
+     * @returns {object}
+     */
+    static #applyComponentVariant(
+        component,
+        dnp,
+        parameterOverrides,
+        alternateFitted,
+        annotations,
+        includeVariantDetails
+    ) {
+        const alternate = alternateFitted[component.designator] || null
+        return {
+            designator: ProjectVariantViewBuilder.#compiledDesignator(
+                component.designator,
+                annotations
+            ),
+            ...(includeVariantDetails
+                ? { sourceDesignator: component.designator }
+                : {}),
+            schematic: component.schematic,
+            pcb: component.pcb,
+            dnp: dnp.has(component.designator),
+            parameters: parameterOverrides[component.designator] || {},
+            ...(includeVariantDetails
+                ? { alternateFitted: alternate || null }
+                : {})
+        }
+    }
+
+    /**
+     * Applies an annotation row to one designator-bearing object.
+     * @param {object} entry Source entry.
+     * @param {Record<string, object>} annotations Annotation rows by source designator.
+     * @returns {object}
+     */
+    static #applyDesignatorAnnotation(entry, annotations) {
+        const compiledDesignator =
+            ProjectVariantViewBuilder.#compiledDesignator(
+                entry.designator,
+                annotations
+            )
+        return compiledDesignator === entry.designator
+            ? entry
+            : {
+                  ...entry,
+                  sourceDesignator: entry.designator,
+                  designator: compiledDesignator
+              }
+    }
+
+    /**
+     * Applies annotation mapping to one net pin.
+     * @param {object} pin Net pin.
+     * @param {Record<string, object>} annotations Annotation rows by source designator.
+     * @returns {object}
+     */
+    static #applyPinAnnotation(pin, annotations) {
+        const ownerIndex = String(pin?.ownerIndex || '')
+        const componentDesignator = String(pin?.componentDesignator || '')
+        const sourceDesignator = componentDesignator || ownerIndex
+        const compiledDesignator =
+            ProjectVariantViewBuilder.#compiledDesignator(
+                sourceDesignator,
+                annotations
+            )
+
+        if (compiledDesignator === sourceDesignator) {
+            return pin
+        }
+
+        return {
+            ...pin,
+            sourceDesignator,
+            ...(ownerIndex ? { ownerIndex: compiledDesignator } : {}),
+            ...(componentDesignator
+                ? { componentDesignator: compiledDesignator }
+                : {})
+        }
+    }
+
+    /**
+     * Resolves a compiled designator for a source designator.
+     * @param {string} designator Source designator.
+     * @param {Record<string, object>} annotations Annotation rows by source designator.
+     * @returns {string}
+     */
+    static #compiledDesignator(designator, annotations) {
+        const key = String(designator || '').trim()
+        return String(annotations?.[key]?.compiledDesignator || key)
+    }
+
+    /**
+     * Checks whether an object has enumerable keys.
+     * @param {object | undefined} value Candidate object.
+     * @returns {boolean}
+     */
+    static #hasKeys(value) {
+        return Object.keys(value || {}).length > 0
+    }
+
+    /**
+     * Deduplicates values while preserving order.
+     * @param {unknown[]} values Candidate values.
+     * @returns {unknown[]}
+     */
+    static #dedupe(values) {
+        return [...new Set((values || []).filter(Boolean))]
+    }
+}

package/src/core/altium/SchematicBindingProvenanceParser.mjs

@@ -0,0 +1,223 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+const { getField, parseNumericField } = ParserUtils
+
+/**
+ * Builds a read-only schematic component library/model binding layer.
+ */
+export class SchematicBindingProvenanceParser {
+    static SCHEMA_ID = 'altium-toolkit.schematic.bindings.a1'
+
+    /**
+     * Parses component binding status from component and implementation rows.
+     * @param {object[]} records Schematic records.
+     * @param {object | null} implementations Implementation read model.
+     * @returns {object | null}
+     */
+    static parse(records, implementations) {
+        const componentRows =
+            SchematicBindingProvenanceParser.#componentRows(records)
+
+        if (!componentRows.length) {
+            return null
+        }
+
+        const implementationsByComponent =
+            SchematicBindingProvenanceParser.#implementationsByComponent(
+                implementations
+            )
+        const components = componentRows.map((component) =>
+            SchematicBindingProvenanceParser.#componentBinding(
+                component,
+                implementationsByComponent.get(component.componentKey) || []
+            )
+        )
+
+        return {
+            schema: SchematicBindingProvenanceParser.SCHEMA_ID,
+            summary: SchematicBindingProvenanceParser.#summary(components),
+            components
+        }
+    }
+
+    /**
+     * Builds normalized component identity rows.
+     * @param {object[]} records Schematic records.
+     * @returns {object[]}
+     */
+    static #componentRows(records) {
+        return (records || [])
+            .filter((record) => getField(record.fields, 'RECORD') === '1')
+            .map((record) => {
+                const indexInSheet = parseNumericField(
+                    record.fields,
+                    'IndexInSheet'
+                )
+                return {
+                    componentKey:
+                        'schematic-component-' +
+                        String(indexInSheet ?? record.recordIndex ?? 0),
+                    recordKey:
+                        'schematic-record-' + String(record.recordIndex ?? 0),
+                    uniqueId: getField(record.fields, 'UniqueID'),
+                    libReference:
+                        getField(record.fields, 'LibReference') ||
+                        getField(record.fields, 'DesignItemId')
+                }
+            })
+    }
+
+    /**
+     * Groups implementation rows by owner component key.
+     * @param {object | null} implementations Implementation read model.
+     * @returns {Map<string, object[]>}
+     */
+    static #implementationsByComponent(implementations) {
+        const grouped = new Map()
+
+        for (const implementation of implementations?.implementations || []) {
+            const key = implementation.ownerComponentKey || ''
+            if (!key) continue
+            if (!grouped.has(key)) grouped.set(key, [])
+            grouped.get(key).push(implementation)
+        }
+
+        return grouped
+    }
+
+    /**
+     * Builds one component binding row.
+     * @param {object} component Component row.
+     * @param {object[]} linkedImplementations Linked implementation rows.
+     * @returns {object}
+     */
+    static #componentBinding(component, linkedImplementations) {
+        const status = SchematicBindingProvenanceParser.#status(
+            component,
+            linkedImplementations
+        )
+        const reasons = SchematicBindingProvenanceParser.#reasons(
+            status,
+            component,
+            linkedImplementations
+        )
+
+        return {
+            componentKey: component.componentKey,
+            recordKey: component.recordKey,
+            uniqueId: component.uniqueId,
+            libReference: component.libReference,
+            status,
+            implementationKeys: linkedImplementations.map(
+                (implementation) => implementation.key
+            ),
+            targetLibraries: SchematicBindingProvenanceParser.#targetLibraries(
+                linkedImplementations
+            ),
+            reasons
+        }
+    }
+
+    /**
+     * Classifies component binding status.
+     * @param {object} component Component row.
+     * @param {object[]} linkedImplementations Linked implementation rows.
+     * @returns {'resolved' | 'unresolved' | 'stale' | 'external'}
+     */
+    static #status(component, linkedImplementations) {
+        if (linkedImplementations.length) {
+            const current =
+                linkedImplementations.find(
+                    (implementation) => implementation.isCurrent
+                ) || linkedImplementations[0]
+            return current.modelName &&
+                (current.targetLibraries || []).length > 0
+                ? 'resolved'
+                : 'stale'
+        }
+
+        return component.libReference ? 'external' : 'unresolved'
+    }
+
+    /**
+     * Explains non-resolved status values.
+     * @param {string} status Binding status.
+     * @param {object} component Component row.
+     * @param {object[]} linkedImplementations Linked implementation rows.
+     * @returns {string[]}
+     */
+    static #reasons(status, component, linkedImplementations) {
+        if (status === 'resolved') return []
+        if (status === 'external') {
+            return ['component has a library reference but no local model link']
+        }
+        if (status === 'unresolved') {
+            return ['component has no local library reference or model link']
+        }
+
+        const reasons = []
+        const current =
+            linkedImplementations.find(
+                (implementation) => implementation.isCurrent
+            ) || linkedImplementations[0]
+        if (!current?.modelName) reasons.push('current model name is missing')
+        if (!(current?.targetLibraries || []).length) {
+            reasons.push('current model target library is missing')
+        }
+        if (!component.libReference) {
+            reasons.push('component library reference is missing')
+        }
+        return reasons
+    }
+
+    /**
+     * Flattens target-library rows without implementation-local indexes.
+     * @param {object[]} linkedImplementations Linked implementation rows.
+     * @returns {object[]}
+     */
+    static #targetLibraries(linkedImplementations) {
+        const libraries = []
+        const seen = new Set()
+
+        for (const implementation of linkedImplementations) {
+            for (const library of implementation.targetLibraries || []) {
+                const publicLibrary = {
+                    entity: library.entity || '',
+                    kind: library.kind || '',
+                    fileName: library.fileName || ''
+                }
+                const key = JSON.stringify(publicLibrary)
+                if (seen.has(key)) continue
+                seen.add(key)
+                libraries.push(publicLibrary)
+            }
+        }
+
+        return libraries
+    }
+
+    /**
+     * Builds status counters.
+     * @param {object[]} components Binding rows.
+     * @returns {object}
+     */
+    static #summary(components) {
+        const summary = {
+            componentCount: components.length,
+            resolvedCount: 0,
+            unresolvedCount: 0,
+            staleCount: 0,
+            externalCount: 0
+        }
+
+        for (const component of components) {
+            summary[component.status + 'Count'] += 1
+        }
+
+        return summary
+    }
+}