altium-toolkit 1.0.9 → 1.1.0

package/src/core/altium/ProjectBomPnpReconciliationBuilder.mjs

@@ -0,0 +1,237 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds deterministic BOM/PnP reconciliation metadata for a project bundle.
+ */
+export class ProjectBomPnpReconciliationBuilder {
+    static SCHEMA_ID = 'altium-toolkit.project.bom-pnp-reconciliation.a1'
+
+    /**
+     * Builds a reconciliation report from bundle and source document models.
+     * @param {{ bundle?: object, documentModels?: object[], effectiveVariant?: object }} options Report options.
+     * @returns {object}
+     */
+    static build(options = {}) {
+        const bundle = options.bundle || {}
+        const documentModels = Array.isArray(options.documentModels)
+            ? options.documentModels
+            : []
+        const schematicBomDesignators =
+            ProjectBomPnpReconciliationBuilder.#bomDesignators(
+                documentModels.filter((model) => model?.kind === 'schematic')
+            )
+        const pcbBomDesignators =
+            ProjectBomPnpReconciliationBuilder.#bomDesignators(
+                documentModels.filter((model) => model?.kind === 'pcb')
+            )
+        const pnpDesignators =
+            ProjectBomPnpReconciliationBuilder.#pnpDesignators(documentModels)
+        const effectiveBomDesignators =
+            ProjectBomPnpReconciliationBuilder.#effectiveBomDesignators(
+                bundle,
+                options.effectiveVariant
+            )
+        const noBomDesignators =
+            ProjectBomPnpReconciliationBuilder.#noBomDesignators(documentModels)
+        const issues = [
+            ...ProjectBomPnpReconciliationBuilder.#missingIssues(
+                schematicBomDesignators,
+                pcbBomDesignators,
+                'reconciliation.schematic-bom-without-pcb-bom',
+                'Schematic BOM designator was not present in the PCB-backed BOM.'
+            ),
+            ...ProjectBomPnpReconciliationBuilder.#missingIssues(
+                pcbBomDesignators,
+                schematicBomDesignators,
+                'reconciliation.pcb-bom-without-schematic-bom',
+                'PCB-backed BOM designator was not present in the schematic BOM.'
+            ),
+            ...ProjectBomPnpReconciliationBuilder.#missingIssues(
+                pcbBomDesignators,
+                pnpDesignators,
+                'reconciliation.bom-without-pnp',
+                'PCB-backed BOM designator did not have a PnP placement.'
+            ),
+            ...ProjectBomPnpReconciliationBuilder.#missingIssues(
+                pnpDesignators,
+                pcbBomDesignators,
+                'reconciliation.pnp-without-bom',
+                'PnP placement designator was not present in the PCB-backed BOM.'
+            ),
+            ...ProjectBomPnpReconciliationBuilder.#intersectionIssues(
+                noBomDesignators,
+                pcbBomDesignators,
+                'reconciliation.no-bom-component-in-pcb-bom',
+                'Component marked as no-BOM appeared in the PCB-backed BOM.'
+            )
+        ]
+
+        return {
+            schema: ProjectBomPnpReconciliationBuilder.SCHEMA_ID,
+            summary: {
+                schematicBomDesignatorCount: schematicBomDesignators.length,
+                pcbBomDesignatorCount: pcbBomDesignators.length,
+                pnpDesignatorCount: pnpDesignators.length,
+                effectiveBomDesignatorCount: effectiveBomDesignators.length,
+                noBomComponentCount: noBomDesignators.length,
+                issueCount: issues.length
+            },
+            schematicBomDesignators,
+            pcbBomDesignators,
+            pnpDesignators,
+            effectiveBomDesignators,
+            noBomDesignators,
+            issues
+        }
+    }
+
+    /**
+     * Extracts designators from BOM rows.
+     * @param {object[]} models Parsed document models.
+     * @returns {string[]}
+     */
+    static #bomDesignators(models) {
+        const designators = new Set()
+
+        for (const model of models) {
+            for (const row of model?.bom || []) {
+                for (const designator of row.designators || []) {
+                    ProjectBomPnpReconciliationBuilder.#addDesignator(
+                        designators,
+                        designator
+                    )
+                }
+                ProjectBomPnpReconciliationBuilder.#addDesignator(
+                    designators,
+                    row.designator
+                )
+            }
+        }
+
+        return ProjectBomPnpReconciliationBuilder.#sorted([...designators])
+    }
+
+    /**
+     * Extracts designators from pick-place entries.
+     * @param {object[]} models Parsed document models.
+     * @returns {string[]}
+     */
+    static #pnpDesignators(models) {
+        const designators = new Set()
+
+        for (const model of models.filter((item) => item?.kind === 'pcb')) {
+            const pnp = model.pnp || model.pcb?.pickPlace || {}
+            for (const entry of pnp.entries || []) {
+                ProjectBomPnpReconciliationBuilder.#addDesignator(
+                    designators,
+                    entry.designator
+                )
+            }
+        }
+
+        return ProjectBomPnpReconciliationBuilder.#sorted([...designators])
+    }
+
+    /**
+     * Extracts designators from the active effective variant or bundle BOM.
+     * @param {object} bundle Project design bundle.
+     * @param {object | undefined} effectiveVariant Effective variant view.
+     * @returns {string[]}
+     */
+    static #effectiveBomDesignators(bundle, effectiveVariant) {
+        if (effectiveVariant?.bom) {
+            return ProjectBomPnpReconciliationBuilder.#bomDesignators([
+                { bom: effectiveVariant.bom }
+            ])
+        }
+
+        return ProjectBomPnpReconciliationBuilder.#bomDesignators([
+            { bom: bundle.bom || [] }
+        ])
+    }
+
+    /**
+     * Extracts component designators explicitly excluded from BOMs.
+     * @param {object[]} models Parsed document models.
+     * @returns {string[]}
+     */
+    static #noBomDesignators(models) {
+        const designators = new Set()
+
+        for (const model of models.filter((item) => item?.kind === 'pcb')) {
+            for (const component of model.pcb?.components || []) {
+                if (component.componentKind?.includeInBom !== false) continue
+                ProjectBomPnpReconciliationBuilder.#addDesignator(
+                    designators,
+                    component.designator
+                )
+            }
+        }
+
+        return ProjectBomPnpReconciliationBuilder.#sorted([...designators])
+    }
+
+    /**
+     * Adds a normalized designator to a set.
+     * @param {Set<string>} designators Target set.
+     * @param {unknown} value Raw designator value.
+     * @returns {void}
+     */
+    static #addDesignator(designators, value) {
+        const designator = String(value || '').trim()
+        if (designator) designators.add(designator)
+    }
+
+    /**
+     * Builds missing-designator issue rows.
+     * @param {string[]} source Source designators.
+     * @param {string[]} target Target designators.
+     * @param {string} code Diagnostic code.
+     * @param {string} message Diagnostic message.
+     * @returns {object[]}
+     */
+    static #missingIssues(source, target, code, message) {
+        const targetSet = new Set(target)
+        return source
+            .filter((designator) => !targetSet.has(designator))
+            .map((designator) => ({
+                severity: 'warning',
+                code,
+                designator,
+                message
+            }))
+    }
+
+    /**
+     * Builds issue rows for designators present in both sets.
+     * @param {string[]} left Left designators.
+     * @param {string[]} right Right designators.
+     * @param {string} code Diagnostic code.
+     * @param {string} message Diagnostic message.
+     * @returns {object[]}
+     */
+    static #intersectionIssues(left, right, code, message) {
+        const rightSet = new Set(right)
+        return left
+            .filter((designator) => rightSet.has(designator))
+            .map((designator) => ({
+                severity: 'warning',
+                code,
+                designator,
+                message
+            }))
+    }
+
+    /**
+     * Sorts designators in a stable human-friendly order.
+     * @param {string[]} values Designator values.
+     * @returns {string[]}
+     */
+    static #sorted(values) {
+        return [...values].sort((left, right) =>
+            left.localeCompare(right, undefined, { numeric: true })
+        )
+    }
+}

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'
 
 /**
@@ -10,6 +11,19 @@ import { ProjectVariantViewBuilder } from './ProjectVariantViewBuilder.mjs'
  * bundle for multi-document consumers.
  */
 export class ProjectDesignBundleBuilder {
+    static #UNITS = {
+        coordinate: 'mil',
+        length: 'mil',
+        board: 'mil',
+        pnp: 'mil',
+        angle: 'deg'
+    }
+
+    static #PNP_UNITS = {
+        coordinate: 'mil',
+        angle: 'deg'
+    }
+
     /**
      * Builds a normalized project/design bundle from already parsed models.
      * @param {{ projectModel?: object, documentModels?: object[], annotationModels?: object[], variantName?: string }} options Bundle options.
@@ -78,6 +92,7 @@ export class ProjectDesignBundleBuilder {
                 }
             ],
             project,
+            units: ProjectDesignBundleBuilder.#UNITS,
             variants: project.variants || [],
             sheets,
             components,
@@ -100,6 +115,12 @@ export class ProjectDesignBundleBuilder {
             })
         }
 
+        bundle.reconciliation = ProjectBomPnpReconciliationBuilder.build({
+            bundle,
+            documentModels,
+            effectiveVariant: bundle.effectiveVariant
+        })
+
         return bundle
     }
 
@@ -215,6 +236,7 @@ export class ProjectDesignBundleBuilder {
         }
 
         return {
+            units: ProjectDesignBundleBuilder.#PNP_UNITS,
             positionMode,
             entries,
             modes: {}
@@ -294,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/ProjectDocumentGraphBuilder.mjs

@@ -0,0 +1,280 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds a read-only project document graph from parsed PrjPcb metadata.
+ */
+export class ProjectDocumentGraphBuilder {
+    static SCHEMA = 'altium-toolkit.project.document-graph.a1'
+
+    /**
+     * Builds a normalized document graph index.
+     * @param {object} projectModel Parsed project model or project payload.
+     * @param {{ availablePaths?: string[] | Set<string> }} options Graph options.
+     * @returns {object}
+     */
+    static build(projectModel = {}, options = {}) {
+        const project = projectModel?.project || projectModel || {}
+        const documents = ProjectDocumentGraphBuilder.#documentRows(
+            project.documents || [],
+            project.outputGroups || [],
+            options
+        )
+        const groups = ProjectDocumentGraphBuilder.#groups(
+            documents,
+            project.outputGroups || []
+        )
+        const indexes = ProjectDocumentGraphBuilder.#indexes(
+            documents,
+            project.outputGroups || []
+        )
+
+        return {
+            schema: ProjectDocumentGraphBuilder.SCHEMA,
+            summary: {
+                documentCount: documents.length,
+                sourceSheetCount: groups.sourceSheets.length,
+                pcbDocumentCount: groups.pcbs.length,
+                linkedLibraryCount: groups.linkedLibraries.length,
+                harnessFileCount: groups.harnessFiles.length,
+                outJobReferenceCount: groups.outJobs.length,
+                generatedOutputCount: groups.generatedOutputs.length,
+                missingPathCount: groups.missingPaths.length
+            },
+            documents,
+            groups,
+            indexes
+        }
+    }
+
+    /**
+     * Builds detailed document graph rows.
+     * @param {object[]} documents Project document rows.
+     * @param {object[]} outputGroups Project output groups.
+     * @param {{ availablePaths?: string[] | Set<string> }} options Graph options.
+     * @returns {object[]}
+     */
+    static #documentRows(documents, outputGroups, options) {
+        const availablePaths =
+            options.availablePaths == null
+                ? null
+                : new Set(
+                      [...options.availablePaths].map((path) =>
+                          ProjectDocumentGraphBuilder.#normalizePath(path)
+                      )
+                  )
+        const outputsByDocumentPath =
+            ProjectDocumentGraphBuilder.#outputsByDocumentPath(outputGroups)
+
+        return (documents || []).map((document, index) =>
+            ProjectDocumentGraphBuilder.#stripUndefined({
+                graphIndex: index,
+                documentIndex: document.index,
+                section: document.section,
+                path: document.path || '',
+                normalizedPath:
+                    document.normalizedPath ||
+                    ProjectDocumentGraphBuilder.#normalizePath(document.path),
+                fileName:
+                    document.fileName ||
+                    ProjectDocumentGraphBuilder.#basename(document.path),
+                extension: document.extension || '',
+                kind: document.kind || 'other',
+                uniqueId: document.uniqueId || '',
+                isStub: document.isStub === true ? true : undefined,
+                exists:
+                    availablePaths === null
+                        ? undefined
+                        : availablePaths.has(
+                              document.normalizedPath ||
+                                  ProjectDocumentGraphBuilder.#normalizePath(
+                                      document.path
+                                  )
+                          ),
+                linkedOutputs:
+                    outputsByDocumentPath[
+                        document.normalizedPath ||
+                            ProjectDocumentGraphBuilder.#normalizePath(
+                                document.path
+                            )
+                    ] || []
+            })
+        )
+    }
+
+    /**
+     * Groups document and generated-output paths by public role.
+     * @param {object[]} documents Document graph rows.
+     * @param {object[]} outputGroups Output groups.
+     * @returns {object}
+     */
+    static #groups(documents, outputGroups) {
+        const pathsForKind = (kind) =>
+            documents
+                .filter((document) => document.kind === kind)
+                .map((document) => document.normalizedPath)
+        const libraryKinds = new Set([
+            'schematic-library',
+            'pcb-library',
+            'integrated-library'
+        ])
+
+        return {
+            sourceSheets: pathsForKind('schematic'),
+            pcbs: pathsForKind('pcb'),
+            linkedLibraries: documents
+                .filter((document) => libraryKinds.has(document.kind))
+                .map((document) => document.normalizedPath),
+            schematicLibraries: pathsForKind('schematic-library'),
+            pcbLibraries: pathsForKind('pcb-library'),
+            integratedLibraries: pathsForKind('integrated-library'),
+            harnessFiles: pathsForKind('harness'),
+            outJobs: pathsForKind('output-job'),
+            generatedOutputs:
+                ProjectDocumentGraphBuilder.#generatedOutputPaths(outputGroups),
+            missingPaths: documents
+                .filter((document) => document.exists === false)
+                .map((document) => document.normalizedPath)
+        }
+    }
+
+    /**
+     * Builds graph lookup indexes.
+     * @param {object[]} documents Document graph rows.
+     * @param {object[]} outputGroups Output groups.
+     * @returns {object}
+     */
+    static #indexes(documents, outputGroups) {
+        const byPath = {}
+        const byKind = {}
+        for (const document of documents) {
+            byPath[document.normalizedPath] = document.graphIndex
+            byKind[document.kind] ||= []
+            byKind[document.kind].push(document.normalizedPath)
+        }
+
+        return {
+            byPath,
+            byKind,
+            outputsByDocumentPath:
+                ProjectDocumentGraphBuilder.#outputsByDocumentPath(
+                    outputGroups
+                ),
+            generatedOutputsByPath:
+                ProjectDocumentGraphBuilder.#generatedOutputsByPath(
+                    outputGroups
+                )
+        }
+    }
+
+    /**
+     * Builds generated-output descriptors keyed by source document path.
+     * @param {object[]} outputGroups Project output groups.
+     * @returns {Record<string, object[]>}
+     */
+    static #outputsByDocumentPath(outputGroups) {
+        const outputsByPath = {}
+        for (const outputGroup of outputGroups || []) {
+            for (const output of outputGroup.outputs || []) {
+                const documentPath = ProjectDocumentGraphBuilder.#normalizePath(
+                    output.normalizedDocumentPath || output.documentPath
+                )
+                if (!documentPath) {
+                    continue
+                }
+
+                outputsByPath[documentPath] ||= []
+                outputsByPath[documentPath].push(
+                    ProjectDocumentGraphBuilder.#stripUndefined({
+                        outputGroupName: outputGroup.name || '',
+                        outputGroupIndex: outputGroup.index,
+                        outputIndex: output.index,
+                        type: output.type || '',
+                        name: output.name || '',
+                        variantName: output.variantName || '',
+                        targetPath:
+                            ProjectDocumentGraphBuilder.#normalizePath(
+                                output.targetPath ||
+                                    output.normalizedTargetPath ||
+                                    ''
+                            ) || undefined,
+                        isDefault: output.isDefault === true ? true : undefined
+                    })
+                )
+            }
+        }
+
+        return outputsByPath
+    }
+
+    /**
+     * Lists generated output target paths.
+     * @param {object[]} outputGroups Project output groups.
+     * @returns {string[]}
+     */
+    static #generatedOutputPaths(outputGroups) {
+        const paths = []
+        for (const outputs of Object.values(
+            ProjectDocumentGraphBuilder.#outputsByDocumentPath(outputGroups)
+        )) {
+            for (const output of outputs) {
+                if (output.targetPath && !paths.includes(output.targetPath)) {
+                    paths.push(output.targetPath)
+                }
+            }
+        }
+        return paths
+    }
+
+    /**
+     * Builds generated-output descriptors keyed by target path.
+     * @param {object[]} outputGroups Project output groups.
+     * @returns {Record<string, object>}
+     */
+    static #generatedOutputsByPath(outputGroups) {
+        const byPath = {}
+        for (const [sourcePath, outputs] of Object.entries(
+            ProjectDocumentGraphBuilder.#outputsByDocumentPath(outputGroups)
+        )) {
+            for (const output of outputs) {
+                if (!output.targetPath) continue
+                byPath[output.targetPath] = {
+                    sourceDocumentPath: sourcePath,
+                    ...output
+                }
+            }
+        }
+        return byPath
+    }
+
+    /**
+     * Normalizes project-relative path separators.
+     * @param {string} path Project path.
+     * @returns {string}
+     */
+    static #normalizePath(path) {
+        return String(path || '').replace(/\\/g, '/')
+    }
+
+    /**
+     * Extracts a basename without resolving the path.
+     * @param {string} path Project path.
+     * @returns {string}
+     */
+    static #basename(path) {
+        const parts = String(path || '').split(/[\\/]/u)
+        return parts[parts.length - 1] || ''
+    }
+
+    /**
+     * Removes undefined object properties for stable JSON output.
+     * @param {Record<string, unknown>} value Candidate object.
+     * @returns {Record<string, unknown>}
+     */
+    static #stripUndefined(value) {
+        return Object.fromEntries(
+            Object.entries(value).filter(([, entry]) => entry !== undefined)
+        )
+    }
+}

package/src/core/altium/ProjectNetlistExporter.mjs

@@ -32,7 +32,7 @@ export class ProjectNetlistExporter {
     /**
      * Builds a deterministic JSON netlist contract.
      * @param {object} bundle Normalized design bundle or effective variant.
-     * @returns {{ schema: string, project: string, nets: object[] }}
+     * @returns {{ schema: string, project: string, units: object, nets: object[] }}
      */
     static buildNetlistJson(bundle) {
         const projectName =
@@ -61,6 +61,10 @@ export class ProjectNetlistExporter {
         return {
             schema: 'altium-toolkit.netlist.a1',
             project: projectName,
+            units: {
+                coordinate: 'mil',
+                length: 'mil'
+            },
             nets
         }
     }