altium-toolkit 1.0.10 → 1.1.0

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 !== ''
+                )
+            })
+        )
+    }
+}

package/src/core/altium/PcbReviewRouteHighlightProfileBuilder.mjs

@@ -0,0 +1,298 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds route-highlight profile rows for PCB review metadata.
+ */
+export class PcbReviewRouteHighlightProfileBuilder {
+    /**
+     * Builds route-highlight profiles for classes, pairs, pair classes, and nets.
+     * @param {object} routeAnalysis Route analysis model.
+     * @returns {object[]}
+     */
+    static build(routeAnalysis = {}) {
+        return [
+            ...PcbReviewRouteHighlightProfileBuilder.#differentialPairProfiles(
+                routeAnalysis
+            ),
+            ...PcbReviewRouteHighlightProfileBuilder.#differentialPairClassProfiles(
+                routeAnalysis
+            ),
+            ...PcbReviewRouteHighlightProfileBuilder.#netClassProfiles(
+                routeAnalysis
+            ),
+            ...PcbReviewRouteHighlightProfileBuilder.#netProfiles(routeAnalysis)
+        ]
+    }
+
+    /**
+     * Builds net-class highlight profiles.
+     * @param {object} routeAnalysis Route analysis model.
+     * @returns {object[]}
+     */
+    static #netClassProfiles(routeAnalysis) {
+        return (routeAnalysis.classes || []).map((classRow) =>
+            PcbReviewRouteHighlightProfileBuilder.#highlightProfile({
+                selectorKind: 'net-class',
+                keyPrefix: 'highlight-net-class-',
+                name: classRow.name,
+                netNames: classRow.netNames || [],
+                routeAnalysis
+            })
+        )
+    }
+
+    /**
+     * Builds differential-pair highlight profiles.
+     * @param {object} routeAnalysis Route analysis model.
+     * @returns {object[]}
+     */
+    static #differentialPairProfiles(routeAnalysis) {
+        return (routeAnalysis.differentialPairs || []).map((pair) =>
+            PcbReviewRouteHighlightProfileBuilder.#highlightProfile({
+                selectorKind: 'differential-pair',
+                keyPrefix: 'highlight-diff-pair-',
+                name: pair.name,
+                netNames: [pair.positiveNetName, pair.negativeNetName].filter(
+                    Boolean
+                ),
+                routeAnalysis
+            })
+        )
+    }
+
+    /**
+     * Builds differential-pair class highlight profiles.
+     * @param {object} routeAnalysis Route analysis model.
+     * @returns {object[]}
+     */
+    static #differentialPairClassProfiles(routeAnalysis) {
+        const classNames = new Map()
+        for (const pair of routeAnalysis.differentialPairs || []) {
+            for (const className of pair.classes || []) {
+                if (!classNames.has(className)) {
+                    classNames.set(className, new Set())
+                }
+                const netNames = classNames.get(className)
+                for (const netName of [
+                    pair.positiveNetName,
+                    pair.negativeNetName
+                ]) {
+                    if (netName) {
+                        netNames.add(netName)
+                    }
+                }
+            }
+        }
+
+        return [...classNames.entries()]
+            .sort(([left], [right]) =>
+                left.localeCompare(right, undefined, { numeric: true })
+            )
+            .map(([className, netNames]) =>
+                PcbReviewRouteHighlightProfileBuilder.#highlightProfile({
+                    selectorKind: 'differential-pair-class',
+                    keyPrefix: 'highlight-diff-pair-class-',
+                    name: className,
+                    netNames: [...netNames],
+                    routeAnalysis
+                })
+            )
+    }
+
+    /**
+     * Builds scalar net highlight profiles.
+     * @param {object} routeAnalysis Route analysis model.
+     * @returns {object[]}
+     */
+    static #netProfiles(routeAnalysis) {
+        return (routeAnalysis.byNet || []).map((net) =>
+            PcbReviewRouteHighlightProfileBuilder.#highlightProfile({
+                selectorKind: 'net',
+                keyPrefix: 'highlight-net-',
+                name: net.netName,
+                netNames: [net.netName],
+                routeAnalysis
+            })
+        )
+    }
+
+    /**
+     * Builds one route-highlight profile.
+     * @param {{ selectorKind: string, keyPrefix: string, name: string, netNames: string[], routeAnalysis: object }} options Profile options.
+     * @returns {object}
+     */
+    static #highlightProfile(options) {
+        const netNames = PcbReviewRouteHighlightProfileBuilder.#sortedStrings(
+            options.netNames || []
+        )
+        const layerGroups = PcbReviewRouteHighlightProfileBuilder.#layerGroups(
+            options.routeAnalysis,
+            netNames
+        )
+
+        return PcbReviewRouteHighlightProfileBuilder.#stripEmpty({
+            key:
+                options.keyPrefix +
+                PcbReviewRouteHighlightProfileBuilder.#slug(options.name),
+            selectorKind: options.selectorKind,
+            name: options.name,
+            netNames,
+            minRoutedLengthMil:
+                layerGroups.length > 0
+                    ? Math.min(
+                          ...layerGroups.map((group) =>
+                              Number(group.routedLengthMil || 0)
+                          )
+                      )
+                    : 0,
+            layerGroups,
+            style: PcbReviewRouteHighlightProfileBuilder.#highlightStyle(
+                options.selectorKind
+            )
+        })
+    }
+
+    /**
+     * Builds per-layer route-highlight groups.
+     * @param {object} routeAnalysis Route analysis model.
+     * @param {string[]} netNames Net names.
+     * @returns {object[]}
+     */
+    static #layerGroups(routeAnalysis, netNames) {
+        const groupsByLayer = new Map()
+        for (const net of PcbReviewRouteHighlightProfileBuilder.#netsByName(
+            routeAnalysis,
+            netNames
+        )) {
+            for (const participation of net.layerParticipation || []) {
+                const layerKey = participation.layerKey || ''
+                if (!layerKey) {
+                    continue
+                }
+                if (!groupsByLayer.has(layerKey)) {
+                    groupsByLayer.set(layerKey, {
+                        layerKey,
+                        primitiveKeys: new Set(),
+                        routedLengthMil: 0
+                    })
+                }
+                const group = groupsByLayer.get(layerKey)
+                group.routedLengthMil += Number(
+                    participation.totalLengthMil || 0
+                )
+                for (const routeGroup of net.connectedRouteGroups || []) {
+                    if (!(routeGroup.layerKeys || []).includes(layerKey)) {
+                        continue
+                    }
+                    for (const primitiveKey of routeGroup.primitiveKeys || []) {
+                        group.primitiveKeys.add(primitiveKey)
+                    }
+                }
+            }
+        }
+
+        return [...groupsByLayer.values()]
+            .map((group) => ({
+                layerKey: group.layerKey,
+                primitiveKeys:
+                    PcbReviewRouteHighlightProfileBuilder.#sortedStrings([
+                        ...group.primitiveKeys
+                    ]),
+                routedLengthMil: PcbReviewRouteHighlightProfileBuilder.#round(
+                    group.routedLengthMil
+                )
+            }))
+            .sort((left, right) =>
+                left.layerKey.localeCompare(right.layerKey, undefined, {
+                    numeric: true
+                })
+            )
+    }
+
+    /**
+     * 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)
+        )
+    }
+
+    /**
+     * Returns deterministic highlight style metadata.
+     * @param {string} selectorKind Selector kind.
+     * @returns {{ highlightColor: string, contextColor: string }}
+     */
+    static #highlightStyle(selectorKind) {
+        if (selectorKind === 'differential-pair') {
+            return { highlightColor: '#dc2626', contextColor: '#475569' }
+        }
+        if (selectorKind === 'differential-pair-class') {
+            return { highlightColor: '#7c3aed', contextColor: '#475569' }
+        }
+        if (selectorKind === 'net-class') {
+            return { highlightColor: '#d97706', contextColor: '#475569' }
+        }
+        return { highlightColor: '#2563eb', contextColor: '#475569' }
+    }
+
+    /**
+     * 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 !== ''
+                )
+            })
+        )
+    }
+}