altium-toolkit 1.0.10 → 1.1.0

package/src/core/altium/ProjectDesignBundleBuilder.mjs

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { NormalizedModelSchema } from './NormalizedModelSchema.mjs'
+import { ProjectBomPnpReconciliationBuilder } from './ProjectBomPnpReconciliationBuilder.mjs'
 import { ProjectVariantViewBuilder } from './ProjectVariantViewBuilder.mjs'
 
 /**
@@ -114,6 +115,12 @@ export class ProjectDesignBundleBuilder {
             })
         }
 
+        bundle.reconciliation = ProjectBomPnpReconciliationBuilder.build({
+            bundle,
+            documentModels,
+            effectiveVariant: bundle.effectiveVariant
+        })
+
         return bundle
     }
 
@@ -309,15 +316,67 @@ export class ProjectDesignBundleBuilder {
      * @returns {object[]}
      */
     static #buildBom(documentModels) {
+        const noBomDesignators =
+            ProjectDesignBundleBuilder.#noBomDesignators(documentModels)
         const pcbBom = documentModels
             .filter((model) => model?.kind === 'pcb')
             .flatMap((model) => model.bom || [])
 
         if (pcbBom.length) {
-            return pcbBom
+            return ProjectDesignBundleBuilder.#filterBomRows(
+                pcbBom,
+                noBomDesignators
+            )
+        }
+
+        return ProjectDesignBundleBuilder.#filterBomRows(
+            documentModels.flatMap((model) => model.bom || []),
+            noBomDesignators
+        )
+    }
+
+    /**
+     * Removes component-kind no-BOM designators from normalized BOM rows.
+     * @param {object[]} rows BOM rows.
+     * @param {Set<string>} noBomDesignators Designators excluded from BOMs.
+     * @returns {object[]}
+     */
+    static #filterBomRows(rows, noBomDesignators) {
+        if (!noBomDesignators.size) return rows
+
+        return (rows || [])
+            .map((row) => {
+                const designators = (row.designators || []).filter(
+                    (designator) => !noBomDesignators.has(designator)
+                )
+                return {
+                    ...row,
+                    designators,
+                    quantity: designators.length || row.quantity
+                }
+            })
+            .filter((row) => row.designators.length > 0)
+    }
+
+    /**
+     * Collects PCB components whose native kind excludes BOM output.
+     * @param {object[]} documentModels Parsed document models.
+     * @returns {Set<string>}
+     */
+    static #noBomDesignators(documentModels) {
+        const designators = new Set()
+
+        for (const model of documentModels.filter(
+            (item) => item?.kind === 'pcb'
+        )) {
+            for (const component of model.pcb?.components || []) {
+                if (component.componentKind?.includeInBom !== false) continue
+                const designator = String(component.designator || '').trim()
+                if (designator) designators.add(designator)
+            }
         }
 
-        return documentModels.flatMap((model) => model.bom || [])
+        return designators
     }
 
     /**

package/src/core/altium/ProjectOutJobDigestBuilder.mjs

@@ -14,7 +14,8 @@ export class ProjectOutJobDigestBuilder {
      * @returns {object}
      */
     static build(project) {
-        const documents = (project?.documents || [])
+        const projectDocuments = project?.documents || []
+        const documents = projectDocuments
             .filter((document) => document.kind === 'output-job')
             .map((document) => ({
                 documentIndex: document.index,
@@ -22,23 +23,39 @@ export class ProjectOutJobDigestBuilder {
                 normalizedPath: document.normalizedPath,
                 fileName: document.fileName
             }))
+        const context = {
+            defaultPcbDocumentPath:
+                projectDocuments.find((document) => document.kind === 'pcb')
+                    ?.path || ''
+        }
         const outputGroups = (project?.outputGroups || []).map((group) =>
-            ProjectOutJobDigestBuilder.#outputGroup(group)
+            ProjectOutJobDigestBuilder.#outputGroup(group, context)
         )
         const outputCount = outputGroups.reduce(
             (sum, group) => sum + group.outputCount,
             0
         )
+        const outputs = outputGroups.flatMap((group) => group.outputs)
+        const expectedArtifacts =
+            ProjectOutJobDigestBuilder.#expectedArtifacts(outputGroups)
 
         return {
             schema: ProjectOutJobDigestBuilder.SCHEMA_ID,
             summary: {
                 outJobDocumentCount: documents.length,
                 outputGroupCount: outputGroups.length,
-                outputCount
+                outputCount,
+                typedOutputCount: outputs.filter(
+                    (output) => output.normalizedType !== 'unsupported'
+                ).length,
+                unsupportedOutputCount: outputs.filter(
+                    (output) => output.normalizedType === 'unsupported'
+                ).length,
+                expectedArtifactCount: expectedArtifacts.manifest.outputs.length
             },
             documents,
             outputGroups,
+            expectedArtifacts,
             outputsByDocumentPath:
                 ProjectOutJobDigestBuilder.#outputsByDocumentPath(outputGroups)
         }
@@ -47,19 +64,12 @@ export class ProjectOutJobDigestBuilder {
     /**
      * Normalizes one output group.
      * @param {object} group Project output group.
+     * @param {{ defaultPcbDocumentPath: string }} context Project context.
      * @returns {object}
      */
-    static #outputGroup(group) {
+    static #outputGroup(group, context) {
         const outputs = (group.outputs || []).map((output) => ({
-            index: output.index,
-            type: output.type,
-            name: output.name,
-            documentPath: output.documentPath,
-            normalizedDocumentPath: ProjectOutJobDigestBuilder.#normalizePath(
-                output.documentPath
-            ),
-            variantName: output.variantName,
-            isDefault: output.isDefault
+            ...ProjectOutJobDigestBuilder.#typedOutput(output, group, context)
         }))
 
         return {
@@ -88,6 +98,7 @@ export class ProjectOutJobDigestBuilder {
                     outputGroupIndex: group.index,
                     outputIndex: output.index,
                     type: output.type,
+                    normalizedType: output.normalizedType,
                     name: output.name,
                     variantName: output.variantName,
                     isDefault: output.isDefault
@@ -106,4 +117,404 @@ export class ProjectOutJobDigestBuilder {
     static #normalizePath(path) {
         return String(path || '').replace(/\\/g, '/')
     }
+
+    /**
+     * Builds one typed output row.
+     * @param {object} output Raw output row.
+     * @param {object} group Owning output group.
+     * @param {{ defaultPcbDocumentPath: string }} context Project context.
+     * @returns {object}
+     */
+    static #typedOutput(output, group, context) {
+        const config = ProjectOutJobDigestBuilder.#mergedConfig(output)
+        const normalizedType = ProjectOutJobDigestBuilder.#normalizedType(
+            output.type
+        )
+        const category = ProjectOutJobDigestBuilder.#category(normalizedType)
+        const documentPath = ProjectOutJobDigestBuilder.#documentPath(
+            normalizedType,
+            output,
+            config,
+            context
+        )
+        const normalizedDocumentPath =
+            ProjectOutJobDigestBuilder.#normalizePath(documentPath)
+        const settings = ProjectOutJobDigestBuilder.#settings(
+            normalizedType,
+            output,
+            config,
+            documentPath
+        )
+        const base = {
+            index: output.index,
+            type: output.type,
+            normalizedType,
+            name: output.name,
+            documentPath: output.documentPath || '',
+            normalizedDocumentPath,
+            variantName: output.variantName || config.VariantName || '',
+            isDefault: output.isDefault,
+            category,
+            settings
+        }
+
+        return {
+            ...base,
+            expectedArtifact: ProjectOutJobDigestBuilder.#expectedArtifact(
+                base,
+                group
+            )
+        }
+    }
+
+    /**
+     * Resolves the source document path for one output row.
+     * @param {string} normalizedType Stable output type.
+     * @param {object} output Raw output row.
+     * @param {Record<string, string>} config Merged config fields.
+     * @param {{ defaultPcbDocumentPath: string }} context Project context.
+     * @returns {string}
+     */
+    static #documentPath(normalizedType, output, config, context) {
+        const explicit = output.documentPath || config.DocumentPath || ''
+        if (explicit) return explicit
+
+        if (
+            normalizedType === 'bom' &&
+            ProjectOutJobDigestBuilder.#boolean(config.IncludePcbData) === true
+        ) {
+            return context.defaultPcbDocumentPath || ''
+        }
+
+        return ''
+    }
+
+    /**
+     * Merges parsed configuration rows into one field lookup.
+     * @param {object} output Output row.
+     * @returns {Record<string, string>}
+     */
+    static #mergedConfig(output) {
+        const config = {}
+
+        for (const row of output.configRows || []) {
+            if (row.record && !config.Record) {
+                config.Record = row.record
+            }
+            Object.assign(config, row.fields || {})
+        }
+
+        return config
+    }
+
+    /**
+     * Resolves a stable output type token.
+     * @param {string} type Native output type.
+     * @returns {string}
+     */
+    static #normalizedType(type) {
+        const normalized = String(type || '')
+            .trim()
+            .toLowerCase()
+            .replace(/[\s_]+/gu, '-')
+
+        if (normalized.includes('gerber')) return 'gerber'
+        if (normalized.includes('ncdrill') || normalized.includes('nc-drill')) {
+            return 'nc-drill'
+        }
+        if (normalized.includes('odb')) return 'odb'
+        if (
+            normalized.includes('pickplace') ||
+            normalized.includes('pick-place')
+        ) {
+            return 'pick-place'
+        }
+        if (normalized.includes('wirelist')) return 'wirelist'
+        if (normalized.includes('bom')) return 'bom'
+        if (normalized.includes('step')) return 'step'
+        if (normalized.includes('schematicprint')) return 'schematic-print'
+        if (
+            normalized.includes('pcbdrawing') ||
+            normalized.includes('draftsman')
+        ) {
+            return 'pcb-drawing'
+        }
+
+        return 'unsupported'
+    }
+
+    /**
+     * Resolves an output category.
+     * @param {string} normalizedType Stable output type.
+     * @returns {string}
+     */
+    static #category(normalizedType) {
+        return (
+            {
+                gerber: 'fabrication',
+                'nc-drill': 'fabrication',
+                odb: 'fabrication',
+                'pick-place': 'assembly',
+                wirelist: 'netlist',
+                bom: 'report',
+                step: 'export',
+                'schematic-print': 'documentation',
+                'pcb-drawing': 'documentation'
+            }[normalizedType] || 'unsupported'
+        )
+    }
+
+    /**
+     * Builds typed settings for one output row.
+     * @param {string} normalizedType Stable output type.
+     * @param {object} output Output row.
+     * @param {Record<string, string>} config Merged config fields.
+     * @param {string} documentPath Resolved output document path.
+     * @returns {object}
+     */
+    static #settings(normalizedType, output, config, documentPath) {
+        const common = ProjectOutJobDigestBuilder.#stripEmpty({
+            record: config.Record || '',
+            documentPath
+        })
+
+        switch (normalizedType) {
+            case 'gerber':
+                return ProjectOutJobDigestBuilder.#stripEmpty({
+                    ...common,
+                    units: config.GerberUnit || config.Units || '',
+                    decimals: ProjectOutJobDigestBuilder.#number(
+                        config.NumberOfDecimals
+                    ),
+                    plotLayers: ProjectOutJobDigestBuilder.#plotLayers(
+                        config['Plot.Set']
+                    )
+                })
+            case 'nc-drill':
+                return ProjectOutJobDigestBuilder.#stripEmpty({
+                    ...common,
+                    units: config.Units || '',
+                    separatePlated:
+                        ProjectOutJobDigestBuilder.#boolean(
+                            config.SeparatePlated
+                        ) ??
+                        ProjectOutJobDigestBuilder.#boolean(
+                            config.GenerateSeparatePlatedNonPlatedFiles
+                        )
+                })
+            case 'pick-place':
+                return ProjectOutJobDigestBuilder.#stripEmpty({
+                    ...common,
+                    units: config.Units || '',
+                    generateCsv: ProjectOutJobDigestBuilder.#boolean(
+                        config.GenerateCSVFormat
+                    ),
+                    includeStandardNoBom: ProjectOutJobDigestBuilder.#boolean(
+                        config.IncludeStandardNoBOM
+                    )
+                })
+            case 'wirelist':
+                return ProjectOutJobDigestBuilder.#stripEmpty({
+                    ...common,
+                    units: config.Units || '',
+                    generateText: ProjectOutJobDigestBuilder.#boolean(
+                        config.GenerateTextFormat
+                    ),
+                    includeVariations: ProjectOutJobDigestBuilder.#boolean(
+                        config.IncludeVariations
+                    )
+                })
+            case 'bom':
+                return ProjectOutJobDigestBuilder.#stripEmpty({
+                    ...common,
+                    includePcbData: ProjectOutJobDigestBuilder.#boolean(
+                        config.IncludePcbData
+                    ),
+                    includeAlternatives: ProjectOutJobDigestBuilder.#boolean(
+                        config.IncludeAlternatives
+                    ),
+                    batchMode: ProjectOutJobDigestBuilder.#number(
+                        config.BatchMode
+                    ),
+                    viewType: ProjectOutJobDigestBuilder.#number(
+                        config.ViewType
+                    )
+                })
+            case 'step':
+                return ProjectOutJobDigestBuilder.#stripEmpty({
+                    ...common,
+                    exportModelsOption: ProjectOutJobDigestBuilder.#number(
+                        config.ExportModelsOption
+                    ),
+                    exportHolesOption: ProjectOutJobDigestBuilder.#number(
+                        config.ExportHolesOption
+                    )
+                })
+            case 'schematic-print':
+                return ProjectOutJobDigestBuilder.#stripEmpty({
+                    ...common,
+                    paperKind: config.PaperKind || '',
+                    printScale: ProjectOutJobDigestBuilder.#number(
+                        config.PrintScale
+                    )
+                })
+            case 'pcb-drawing':
+                return ProjectOutJobDigestBuilder.#stripEmpty({
+                    ...common,
+                    variantName: config.VariantName || ''
+                })
+            default:
+                return common
+        }
+    }
+
+    /**
+     * Builds expected artifact metadata for all output rows.
+     * @param {object[]} outputGroups Output groups.
+     * @returns {object}
+     */
+    static #expectedArtifacts(outputGroups) {
+        const outputs = outputGroups.flatMap((group) =>
+            group.outputs.map((output) => output.expectedArtifact)
+        )
+
+        return {
+            schema: 'altium-toolkit.project.expected-artifacts.a1',
+            summary: {
+                outputCount: outputs.length,
+                unsupportedOutputCount: outputs.filter(
+                    (output) => output.unsupported
+                ).length
+            },
+            manifest: {
+                outputs
+            }
+        }
+    }
+
+    /**
+     * Builds one expected artifact row.
+     * @param {object} output Typed output row.
+     * @param {object} group Owning group.
+     * @returns {object}
+     */
+    static #expectedArtifact(output, group) {
+        const artifact = ProjectOutJobDigestBuilder.#stripEmpty({
+            key:
+                ProjectOutJobDigestBuilder.#slug(group.name || 'outputs') +
+                '/' +
+                String(output.index).padStart(2, '0') +
+                '-' +
+                ProjectOutJobDigestBuilder.#slug(
+                    output.name || output.normalizedType
+                ),
+            outputGroupName: group.name || '',
+            outputName: output.name || '',
+            outputType: output.normalizedType,
+            category: output.category,
+            documentPath:
+                output.settings.documentPath || output.documentPath || '',
+            normalizedDocumentPath: output.normalizedDocumentPath,
+            variantName: output.variantName,
+            format: ProjectOutJobDigestBuilder.#format(output),
+            units: output.settings.units,
+            unsupported:
+                output.normalizedType === 'unsupported' ? true : undefined
+        })
+        artifact.variantName = output.variantName || ''
+        return artifact
+    }
+
+    /**
+     * Resolves the expected artifact format token.
+     * @param {object} output Typed output row.
+     * @returns {string}
+     */
+    static #format(output) {
+        if (output.normalizedType === 'pick-place') {
+            return output.settings.generateCsv === false
+                ? 'pick-place-text'
+                : 'pick-place-csv'
+        }
+
+        return (
+            {
+                gerber: 'gerber',
+                'nc-drill': 'nc-drill',
+                odb: 'odb',
+                wirelist: 'wirelist',
+                bom: 'bom',
+                step: 'step',
+                'schematic-print': 'pdf',
+                'pcb-drawing': 'pcbdwf'
+            }[output.normalizedType] || 'unknown'
+        )
+    }
+
+    /**
+     * Parses plot-layer tokens from Altium plot-layer state strings.
+     * @param {string | undefined} value Plot-layer state.
+     * @returns {string[] | undefined}
+     */
+    static #plotLayers(value) {
+        const layers = String(value || '')
+            .split(',')
+            .map((segment) => segment.trim().split('~')[0])
+            .filter(Boolean)
+
+        return layers.length ? layers : undefined
+    }
+
+    /**
+     * Parses one numeric field.
+     * @param {unknown} value Raw value.
+     * @returns {number | undefined}
+     */
+    static #number(value) {
+        const parsed = Number.parseFloat(String(value ?? '').trim())
+        return Number.isFinite(parsed) ? parsed : undefined
+    }
+
+    /**
+     * Parses one optional boolean field.
+     * @param {unknown} value Raw value.
+     * @returns {boolean | undefined}
+     */
+    static #boolean(value) {
+        const raw = String(value ?? '')
+            .trim()
+            .toLowerCase()
+        if (!raw) return undefined
+        return ['1', 't', 'true', 'yes'].includes(raw)
+    }
+
+    /**
+     * Removes empty values while preserving booleans and zeroes.
+     * @param {object} value Source object.
+     * @returns {object}
+     */
+    static #stripEmpty(value) {
+        return Object.fromEntries(
+            Object.entries(value || {}).filter(([, entryValue]) => {
+                if (Array.isArray(entryValue)) return entryValue.length > 0
+                if (typeof entryValue === 'string') return entryValue.length > 0
+                return entryValue !== null && entryValue !== undefined
+            })
+        )
+    }
+
+    /**
+     * Builds a stable slug for output manifest keys.
+     * @param {string} value Raw value.
+     * @returns {string}
+     */
+    static #slug(value) {
+        return (
+            String(value || '')
+                .trim()
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/gu, '-')
+                .replace(/^-|-$/gu, '') || 'output'
+        )
+    }
 }

package/src/core/altium/SvgModelCrossLinkValidator.mjs

@@ -15,6 +15,18 @@ export class SvgModelCrossLinkValidator {
      * @returns {object}
      */
     static validate(documentModel, svgMarkup) {
+        return SvgModelCrossLinkValidator.validateSet(documentModel, [
+            svgMarkup
+        ])
+    }
+
+    /**
+     * Validates a set of semantic SVG fragments against one normalized model.
+     * @param {object} documentModel Normalized schematic or PCB model.
+     * @param {string[]} svgMarkups SVG markup strings.
+     * @returns {object}
+     */
+    static validateSet(documentModel, svgMarkups) {
         const documentKind =
             SvgModelCrossLinkValidator.#documentKind(documentModel)
         const expectedElements =
@@ -22,7 +34,9 @@ export class SvgModelCrossLinkValidator {
         const expectedByKey = new Map(
             expectedElements.map((element) => [element.elementKey, element])
         )
-        const svgElements = SvgModelCrossLinkValidator.#svgElements(svgMarkup)
+        const svgElements = (svgMarkups || []).flatMap((svgMarkup) =>
+            SvgModelCrossLinkValidator.#svgElements(svgMarkup)
+        )
         const renderedKeys = new Set(
             svgElements.map((element) => element.elementKey).filter(Boolean)
         )
@@ -41,12 +55,13 @@ export class SvgModelCrossLinkValidator {
                 documentModel,
                 svgElements
             )
-        const metadata = SvgModelCrossLinkValidator.#metadata(svgMarkup)
+        const metadata = SvgModelCrossLinkValidator.#metadataSet(svgMarkups)
 
         return {
             schema: SvgModelCrossLinkValidator.SCHEMA,
             documentKind,
             summary: {
+                svgCount: (svgMarkups || []).length,
                 expectedElementCount: expectedElements.length,
                 renderedElementCount: renderedKeys.size,
                 linkedElementCount:
@@ -375,6 +390,24 @@ export class SvgModelCrossLinkValidator {
         }
     }
 
+    /**
+     * Extracts semantic metadata from a set of SVG fragments.
+     * @param {string[]} svgMarkups SVG markup strings.
+     * @returns {{ schema: string, elements: object[] }}
+     */
+    static #metadataSet(svgMarkups) {
+        const metadataRows = (svgMarkups || []).map((svgMarkup) =>
+            SvgModelCrossLinkValidator.#metadata(svgMarkup)
+        )
+        const schema =
+            metadataRows.find((metadata) => metadata.schema)?.schema || ''
+
+        return {
+            schema,
+            elements: metadataRows.flatMap((metadata) => metadata.elements)
+        }
+    }
+
     /**
      * Converts a data attribute token to a camelCase object key.
      * @param {string} value Attribute token.