altium-toolkit 1.0.9 → 1.1.0

package/src/core/altium/PcbReviewMetadataBuilder.mjs

@@ -0,0 +1,373 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbReviewDrillMetadataBuilder } from './PcbReviewDrillMetadataBuilder.mjs'
+import { PcbReviewPolygonRealizationBuilder } from './PcbReviewPolygonRealizationBuilder.mjs'
+import { PcbReviewRouteHighlightProfileBuilder } from './PcbReviewRouteHighlightProfileBuilder.mjs'
+
+/**
+ * Builds PCB review metadata for routed-class and board-assembly workflows.
+ */
+export class PcbReviewMetadataBuilder {
+    static SCHEMA = 'altium-toolkit.pcb.review-metadata.a1'
+
+    /**
+     * Builds a normalized review-metadata sidecar.
+     * @param {{ routeAnalysis?: object, embeddedModels?: object[], componentBodies?: object[], layers?: object[], primitiveLayers?: object[], polygons?: object[], tracks?: object[], arcs?: object[], fills?: object[], vias?: object[], pads?: object[], regions?: object[], shapeBasedRegions?: object[] }} pcb Review context.
+     * @returns {object}
+     */
+    static build(pcb = {}) {
+        const routeGroups = PcbReviewMetadataBuilder.#routeGroups(
+            pcb.routeAnalysis || {}
+        )
+        const routeHighlightProfiles =
+            PcbReviewRouteHighlightProfileBuilder.build(pcb.routeAnalysis || {})
+        const polygonRealizations =
+            PcbReviewPolygonRealizationBuilder.build(pcb)
+        const drillReview = PcbReviewDrillMetadataBuilder.build(pcb)
+        const boardAssemblyViews = PcbReviewMetadataBuilder.#boardAssemblyViews(
+            pcb.embeddedModels || [],
+            pcb.componentBodies || []
+        )
+
+        return {
+            schema: PcbReviewMetadataBuilder.SCHEMA,
+            summary: {
+                routeGroupCount: routeGroups.length,
+                boardAssemblyViewCount: boardAssemblyViews.length,
+                polygonRealizationCount: polygonRealizations.length,
+                routeHighlightProfileCount: routeHighlightProfiles.length,
+                drillOverlayCount: drillReview.overlays.length
+            },
+            routeGroups,
+            routeHighlightProfiles,
+            polygonRealizations,
+            drillReview,
+            boardAssemblyViews,
+            indexes: PcbReviewMetadataBuilder.#indexes(
+                routeGroups,
+                routeHighlightProfiles,
+                polygonRealizations,
+                drillReview,
+                boardAssemblyViews,
+                pcb.routeAnalysis || {}
+            )
+        }
+    }
+
+    /**
+     * Builds route highlight groups from route analysis.
+     * @param {object} routeAnalysis Route analysis model.
+     * @returns {object[]}
+     */
+    static #routeGroups(routeAnalysis) {
+        return [
+            ...PcbReviewMetadataBuilder.#classGroups(routeAnalysis),
+            ...PcbReviewMetadataBuilder.#differentialPairGroups(routeAnalysis)
+        ]
+    }
+
+    /**
+     * Builds net-class route groups.
+     * @param {object} routeAnalysis Route analysis model.
+     * @returns {object[]}
+     */
+    static #classGroups(routeAnalysis) {
+        return (routeAnalysis.classes || []).map((classRow) =>
+            PcbReviewMetadataBuilder.#stripEmpty({
+                key:
+                    'route-class-' +
+                    PcbReviewMetadataBuilder.#slug(classRow.name),
+                kind: 'net-class',
+                name: classRow.name,
+                netNames: classRow.netNames || [],
+                layerKeys: PcbReviewMetadataBuilder.#layerKeysForNets(
+                    routeAnalysis,
+                    classRow.netNames || []
+                ),
+                primitiveKeys: PcbReviewMetadataBuilder.#primitiveKeysForNets(
+                    routeAnalysis,
+                    classRow.netNames || []
+                ),
+                totalLengthMil: classRow.totalLengthMil
+            })
+        )
+    }
+
+    /**
+     * Builds differential-pair route groups.
+     * @param {object} routeAnalysis Route analysis model.
+     * @returns {object[]}
+     */
+    static #differentialPairGroups(routeAnalysis) {
+        return (routeAnalysis.differentialPairs || []).map((pair) => {
+            const netNames = [
+                pair.positiveNetName,
+                pair.negativeNetName
+            ].filter(Boolean)
+
+            return PcbReviewMetadataBuilder.#stripEmpty({
+                key:
+                    'route-diff-pair-' +
+                    PcbReviewMetadataBuilder.#slug(pair.name),
+                kind: 'differential-pair',
+                name: pair.name,
+                netNames,
+                layerKeys: PcbReviewMetadataBuilder.#layerKeysForNets(
+                    routeAnalysis,
+                    netNames
+                ),
+                primitiveKeys: PcbReviewMetadataBuilder.#primitiveKeysForNets(
+                    routeAnalysis,
+                    netNames
+                ),
+                totalLengthMil: PcbReviewMetadataBuilder.#round(
+                    Number(pair.positiveLengthMil || 0) +
+                        Number(pair.negativeLengthMil || 0)
+                ),
+                skewLengthMil: pair.skewLengthMil,
+                classes: pair.classes || []
+            })
+        })
+    }
+
+    /**
+     * Builds board assembly view candidates from unreferenced model payloads.
+     * @param {object[]} embeddedModels Embedded model payload rows.
+     * @param {object[]} componentBodies Component body rows.
+     * @returns {object[]}
+     */
+    static #boardAssemblyViews(embeddedModels, componentBodies) {
+        const referencedModelKeys =
+            PcbReviewMetadataBuilder.#referencedModelKeys(componentBodies)
+
+        return (embeddedModels || [])
+            .filter((model) => {
+                const keys = PcbReviewMetadataBuilder.#modelKeys(model)
+                return !keys.some((key) => referencedModelKeys.has(key))
+            })
+            .map((model, index) =>
+                PcbReviewMetadataBuilder.#stripEmpty({
+                    key:
+                        'board-assembly-' +
+                        index +
+                        '-' +
+                        PcbReviewMetadataBuilder.#slug(model.name || index),
+                    name: model.name,
+                    format: model.format,
+                    sourceStream: model.sourceStream,
+                    modelId: model.id,
+                    reason: 'embedded model is not referenced by component bodies'
+                })
+            )
+    }
+
+    /**
+     * Builds review lookup indexes.
+     * @param {object[]} routeGroups Route review groups.
+     * @param {object[]} routeHighlightProfiles Route-highlight profiles.
+     * @param {object[]} polygonRealizations Polygon realization rows.
+     * @param {{ overlays: object[] }} drillReview Drill review rows.
+     * @param {object[]} boardAssemblyViews Assembly-view candidates.
+     * @param {object} routeAnalysis Route analysis model.
+     * @returns {object}
+     */
+    static #indexes(
+        routeGroups,
+        routeHighlightProfiles,
+        polygonRealizations,
+        drillReview,
+        boardAssemblyViews,
+        routeAnalysis
+    ) {
+        const routeGroupsByName = {}
+        const routeHighlightProfilesByName = {}
+        const polygonRealizationsByKey = {}
+        const drillOverlaysByOwnerKey = {}
+        const boardAssemblyViewsByName = {}
+
+        routeGroups.forEach((group, index) => {
+            if (group.name) routeGroupsByName[group.name] = index
+        })
+        routeHighlightProfiles.forEach((profile, index) => {
+            if (profile.name) routeHighlightProfilesByName[profile.name] = index
+        })
+        polygonRealizations.forEach((realization, index) => {
+            polygonRealizationsByKey[realization.key] = index
+        })
+        for (const [index, overlay] of (drillReview.overlays || []).entries()) {
+            drillOverlaysByOwnerKey[overlay.ownerKey] = index
+        }
+        boardAssemblyViews.forEach((view, index) => {
+            if (view.name) boardAssemblyViewsByName[view.name] = index
+        })
+
+        return {
+            routeGroupsByName,
+            routeHighlightProfilesByName,
+            primitiveKeysByNet:
+                PcbReviewMetadataBuilder.#primitiveKeysByNet(routeAnalysis),
+            polygonRealizationsByKey,
+            drillOverlaysByOwnerKey,
+            boardAssemblyViewsByName
+        }
+    }
+
+    /**
+     * Builds primitive-key lookups by net.
+     * @param {object} routeAnalysis Route analysis model.
+     * @returns {Record<string, string[]>}
+     */
+    static #primitiveKeysByNet(routeAnalysis) {
+        const entries = {}
+        for (const net of routeAnalysis.byNet || []) {
+            entries[net.netName] = PcbReviewMetadataBuilder.#primitiveKeys(net)
+        }
+        return Object.fromEntries(
+            Object.entries(entries).sort(([left], [right]) =>
+                left.localeCompare(right, undefined, { numeric: true })
+            )
+        )
+    }
+
+    /**
+     * Returns layer keys participating in a list of nets.
+     * @param {object} routeAnalysis Route analysis model.
+     * @param {string[]} netNames Net names.
+     * @returns {string[]}
+     */
+    static #layerKeysForNets(routeAnalysis, netNames) {
+        const nets = PcbReviewMetadataBuilder.#netsByName(
+            routeAnalysis,
+            netNames
+        )
+        return PcbReviewMetadataBuilder.#sortedStrings(
+            nets.flatMap((net) => net.layers || [])
+        )
+    }
+
+    /**
+     * Returns primitive keys participating in a list of nets.
+     * @param {object} routeAnalysis Route analysis model.
+     * @param {string[]} netNames Net names.
+     * @returns {string[]}
+     */
+    static #primitiveKeysForNets(routeAnalysis, netNames) {
+        const nets = PcbReviewMetadataBuilder.#netsByName(
+            routeAnalysis,
+            netNames
+        )
+        return PcbReviewMetadataBuilder.#sortedStrings(
+            nets.flatMap((net) => PcbReviewMetadataBuilder.#primitiveKeys(net))
+        )
+    }
+
+    /**
+     * Resolves net route rows by name.
+     * @param {object} routeAnalysis Route analysis model.
+     * @param {string[]} netNames Net names.
+     * @returns {object[]}
+     */
+    static #netsByName(routeAnalysis, netNames) {
+        const wanted = new Set(netNames || [])
+        return (routeAnalysis.byNet || []).filter((net) =>
+            wanted.has(net.netName)
+        )
+    }
+
+    /**
+     * Collects primitive keys from one net route row.
+     * @param {object} net Net route row.
+     * @returns {string[]}
+     */
+    static #primitiveKeys(net) {
+        return PcbReviewMetadataBuilder.#sortedStrings(
+            (net.connectedRouteGroups || []).flatMap(
+                (group) => group.primitiveKeys || []
+            )
+        )
+    }
+
+    /**
+     * Collects model reference keys from component bodies.
+     * @param {object[]} componentBodies Component body rows.
+     * @returns {Set<string>}
+     */
+    static #referencedModelKeys(componentBodies) {
+        const keys = new Set()
+        for (const componentBody of componentBodies || []) {
+            for (const key of PcbReviewMetadataBuilder.#modelKeys(
+                componentBody
+            )) {
+                keys.add(key)
+            }
+        }
+        return keys
+    }
+
+    /**
+     * Builds comparable model identity keys.
+     * @param {object} value Model or body row.
+     * @returns {string[]}
+     */
+    static #modelKeys(value) {
+        return [value?.id, value?.modelId, value?.checksum, value?.name]
+            .map((entry) => String(entry ?? '').trim())
+            .filter(Boolean)
+    }
+
+    /**
+     * Sorts and deduplicates strings naturally.
+     * @param {string[]} values Source values.
+     * @returns {string[]}
+     */
+    static #sortedStrings(values) {
+        return [...new Set((values || []).filter(Boolean))].sort(
+            (left, right) =>
+                left.localeCompare(right, undefined, { numeric: true })
+        )
+    }
+
+    /**
+     * Converts a value to a deterministic lowercase key segment.
+     * @param {unknown} value Source value.
+     * @returns {string}
+     */
+    static #slug(value) {
+        return (
+            String(value || '')
+                .trim()
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/gu, '-')
+                .replace(/^-+|-+$/gu, '') || 'item'
+        )
+    }
+
+    /**
+     * Rounds numeric values for stable JSON.
+     * @param {number} value Candidate number.
+     * @returns {number}
+     */
+    static #round(value) {
+        return Number.isFinite(value) ? Math.round(value * 1000) / 1000 : 0
+    }
+
+    /**
+     * Removes empty fields while preserving zeros and false.
+     * @param {Record<string, unknown>} value Candidate object.
+     * @returns {Record<string, unknown>}
+     */
+    static #stripEmpty(value) {
+        return Object.fromEntries(
+            Object.entries(value || {}).filter(([, entryValue]) => {
+                if (Array.isArray(entryValue)) return entryValue.length > 0
+                return (
+                    entryValue !== null &&
+                    entryValue !== undefined &&
+                    entryValue !== ''
+                )
+            })
+        )
+    }
+}

package/src/core/altium/PcbReviewPolygonRealizationBuilder.mjs

@@ -0,0 +1,269 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds polygon-pour realization rows for PCB review metadata.
+ */
+export class PcbReviewPolygonRealizationBuilder {
+    /**
+     * Builds polygon-pour realization sidecars.
+     * @param {object} pcb Normalized PCB model.
+     * @returns {object[]}
+     */
+    static build(pcb = {}) {
+        const layerNameToKey =
+            PcbReviewPolygonRealizationBuilder.#layerNameToKey(pcb)
+        const rows = [
+            ...PcbReviewPolygonRealizationBuilder.#realizationRows(
+                'polygon',
+                pcb.polygons || [],
+                layerNameToKey
+            ),
+            ...PcbReviewPolygonRealizationBuilder.#realizationRows(
+                'track',
+                pcb.tracks || [],
+                layerNameToKey
+            ),
+            ...PcbReviewPolygonRealizationBuilder.#realizationRows(
+                'arc',
+                pcb.arcs || [],
+                layerNameToKey
+            ),
+            ...PcbReviewPolygonRealizationBuilder.#realizationRows(
+                'fill',
+                pcb.fills || [],
+                layerNameToKey
+            ),
+            ...PcbReviewPolygonRealizationBuilder.#realizationRows(
+                'region',
+                pcb.regions || [],
+                layerNameToKey
+            ),
+            ...PcbReviewPolygonRealizationBuilder.#realizationRows(
+                'shape-based-region',
+                pcb.shapeBasedRegions || [],
+                layerNameToKey
+            )
+        ]
+        const groups = new Map()
+
+        for (const row of rows) {
+            if (!Number.isFinite(row.polygonIndex)) {
+                continue
+            }
+            const key =
+                row.polygonIndex +
+                ':' +
+                (row.subpolygonIndex ?? '') +
+                ':' +
+                (row.unionIndex ?? '')
+            if (!groups.has(key)) {
+                groups.set(key, {
+                    polygonIndex: row.polygonIndex,
+                    subpolygonIndex: row.subpolygonIndex,
+                    unionIndex: row.unionIndex,
+                    isCutout: false,
+                    layerKeys: new Set(),
+                    primitiveKeys: new Set(),
+                    realizedPrimitiveKinds: new Set()
+                })
+            }
+            const group = groups.get(key)
+            group.isCutout = group.isCutout || row.isCutout === true
+            if (row.layerKey) group.layerKeys.add(row.layerKey)
+            group.primitiveKeys.add(row.primitiveKey)
+            group.realizedPrimitiveKinds.add(row.kind)
+        }
+
+        return [...groups.values()]
+            .map((group) =>
+                PcbReviewPolygonRealizationBuilder.#stripEmpty({
+                    key:
+                        'polygon-realization-' +
+                        group.polygonIndex +
+                        '-' +
+                        (group.subpolygonIndex ?? 'main') +
+                        '-' +
+                        (group.unionIndex ?? 'none'),
+                    polygonIndex: group.polygonIndex,
+                    subpolygonIndex: group.subpolygonIndex,
+                    unionIndex: group.unionIndex,
+                    classification: group.isCutout ? 'cutout' : 'copper-pour',
+                    layerKeys:
+                        PcbReviewPolygonRealizationBuilder.#sortedStrings([
+                            ...group.layerKeys
+                        ]),
+                    primitiveKeys:
+                        PcbReviewPolygonRealizationBuilder.#sortedStrings([
+                            ...group.primitiveKeys
+                        ]),
+                    realizedPrimitiveKinds:
+                        PcbReviewPolygonRealizationBuilder.#sortedStrings([
+                            ...group.realizedPrimitiveKinds
+                        ])
+                })
+            )
+            .sort((left, right) =>
+                left.key.localeCompare(right.key, undefined, { numeric: true })
+            )
+    }
+
+    /**
+     * Builds realization rows for one primitive collection.
+     * @param {string} kind Primitive kind.
+     * @param {object[]} primitives Primitive rows.
+     * @param {Map<string, string>} layerNameToKey Layer-name lookup.
+     * @returns {object[]}
+     */
+    static #realizationRows(kind, primitives, layerNameToKey) {
+        return (primitives || []).map((primitive, index) => ({
+            kind,
+            primitiveKey: kind + '-' + index,
+            polygonIndex: PcbReviewPolygonRealizationBuilder.#optionalNumber(
+                primitive?.polygonIndex
+            ),
+            subpolygonIndex: PcbReviewPolygonRealizationBuilder.#optionalNumber(
+                primitive?.subpolygonIndex ?? primitive?.subpolyIndex
+            ),
+            unionIndex: PcbReviewPolygonRealizationBuilder.#optionalNumber(
+                primitive?.unionIndex
+            ),
+            isCutout:
+                primitive?.isCutout === true ||
+                primitive?.classification === 'cutout',
+            layerKey: PcbReviewPolygonRealizationBuilder.#layerKey(
+                primitive,
+                layerNameToKey
+            )
+        }))
+    }
+
+    /**
+     * Builds a layer-name to layer-key lookup.
+     * @param {object} pcb PCB model.
+     * @returns {Map<string, string>}
+     */
+    static #layerNameToKey(pcb) {
+        const lookup = new Map()
+        for (const layer of [
+            ...(pcb.layers || []),
+            ...(pcb.primitiveLayers || [])
+        ]) {
+            const layerId = PcbReviewPolygonRealizationBuilder.#layerId(layer)
+            const name = String(layer?.displayName || layer?.name || '').trim()
+            if (Number.isInteger(layerId) && name) {
+                lookup.set(
+                    PcbReviewPolygonRealizationBuilder.#lookupName(name),
+                    'L' + layerId
+                )
+            }
+        }
+        return lookup
+    }
+
+    /**
+     * Resolves a layer key from a primitive or layer descriptor.
+     * @param {object} value Primitive or layer descriptor.
+     * @param {Map<string, string>} [layerNameToKey] Optional layer-name lookup.
+     * @returns {string}
+     */
+    static #layerKey(value, layerNameToKey = new Map()) {
+        const layerId = PcbReviewPolygonRealizationBuilder.#layerId(value)
+        if (Number.isInteger(layerId)) {
+            return 'L' + layerId
+        }
+
+        const layer = String(value?.layer || value?.layerName || '').trim()
+        const lookupKey = PcbReviewPolygonRealizationBuilder.#lookupName(layer)
+        if (layerNameToKey.has(lookupKey)) {
+            return layerNameToKey.get(lookupKey)
+        }
+        return layer
+            ? 'L-' + PcbReviewPolygonRealizationBuilder.#slug(layer)
+            : ''
+    }
+
+    /**
+     * Resolves a numeric layer id.
+     * @param {object} value Primitive or layer descriptor.
+     * @returns {number | undefined}
+     */
+    static #layerId(value) {
+        for (const key of ['layerId', 'layerCode', 'id', 'index']) {
+            const layerId = Number(value?.[key])
+            if (Number.isInteger(layerId)) {
+                return layerId
+            }
+        }
+
+        return undefined
+    }
+
+    /**
+     * Returns a finite number or undefined.
+     * @param {unknown} value Candidate value.
+     * @returns {number | undefined}
+     */
+    static #optionalNumber(value) {
+        const number = Number(value)
+        return Number.isFinite(number) ? number : undefined
+    }
+
+    /**
+     * Sorts and deduplicates strings naturally.
+     * @param {string[]} values Source values.
+     * @returns {string[]}
+     */
+    static #sortedStrings(values) {
+        return [...new Set((values || []).filter(Boolean))].sort(
+            (left, right) =>
+                left.localeCompare(right, undefined, { numeric: true })
+        )
+    }
+
+    /**
+     * Converts a value to a deterministic lowercase key segment.
+     * @param {unknown} value Source value.
+     * @returns {string}
+     */
+    static #slug(value) {
+        return (
+            String(value || '')
+                .trim()
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/gu, '-')
+                .replace(/^-+|-+$/gu, '') || 'item'
+        )
+    }
+
+    /**
+     * Normalizes a layer or semantic lookup name.
+     * @param {unknown} value Source value.
+     * @returns {string}
+     */
+    static #lookupName(value) {
+        return String(value || '')
+            .trim()
+            .toLowerCase()
+            .replace(/\s+/gu, ' ')
+    }
+
+    /**
+     * Removes empty fields while preserving zeros and false.
+     * @param {Record<string, unknown>} value Candidate object.
+     * @returns {Record<string, unknown>}
+     */
+    static #stripEmpty(value) {
+        return Object.fromEntries(
+            Object.entries(value || {}).filter(([, entryValue]) => {
+                if (Array.isArray(entryValue)) return entryValue.length > 0
+                return (
+                    entryValue !== null &&
+                    entryValue !== undefined &&
+                    entryValue !== ''
+                )
+            })
+        )
+    }
+}