altium-toolkit 1.1.3 → 1.1.23

package/src/core/altium/SchematicNetlistBuilder.mjs

@@ -9,8 +9,8 @@
 export class SchematicNetlistBuilder {
     /**
      * Builds normalized nets and connectivity diagnostics.
-     * @param {{ lines: { x1: number, y1: number, x2: number, y2: number, ownerIndex?: string, isBus?: boolean }[], texts: { x: number, y: number, text: string, recordType?: string }[], pins?: { x: number, y: number, length: number, orientation: 'left' | 'right' | 'top' | 'bottom', name: string, designator: string }[], ports?: { x: number, y: number, width: number, direction?: 'left' | 'right' | 'up' | 'down', name: string }[], crossSheetConnectors?: { key: string, x: number, y: number, name: string, style?: string }[], junctions?: { x: number, y: number, color: string }[], busEntries?: { x1: number, y1: number, x2: number, y2: number }[], sheetEntries?: { x: number, y: number, name: string }[] }} schematic
-     * @returns {{ nets: { name: string, segments: { x1: number, y1: number, x2: number, y2: number, ownerIndex?: string, isBus?: boolean }[], labels: { x: number, y: number, text: string, recordType?: string }[], powerPorts: { x: number, y: number, text: string, recordType?: string }[], crossSheetConnectors: { key: string, name: string, x: number, y: number, style?: string }[], pins: { x: number, y: number, length: number, orientation: 'left' | 'right' | 'top' | 'bottom', name: string, designator: string }[], ports: { x: number, y: number, width: number, direction?: 'left' | 'right' | 'up' | 'down', name: string }[], junctions: { x: number, y: number, color: string }[], busEntries: { x1: number, y1: number, x2: number, y2: number }[], sheetEntries: { x: number, y: number, name: string }[] }[], diagnostics: { severity: 'warning', message: string }[] }}
+     * @param {{ lines: { x1: number, y1: number, x2: number, y2: number, ownerIndex?: string, isBus?: boolean }[], texts: { x: number, y: number, text: string, recordType?: string }[], pins?: { x: number, y: number, length: number, orientation: 'left' | 'right' | 'top' | 'bottom', name: string, designator: string, ownerIndex?: string, componentDesignator?: string }[], ports?: { x: number, y: number, width: number, direction?: 'left' | 'right' | 'up' | 'down', name: string }[], crossSheetConnectors?: { key: string, x: number, y: number, name: string, style?: string }[], junctions?: { x: number, y: number, color: string }[], busEntries?: { x1: number, y1: number, x2: number, y2: number }[], sheetEntries?: { x: number, y: number, name: string }[], componentDesignatorsByOwnerIndex?: Map<string, string> | Record<string, string> }} schematic
+     * @returns {{ nets: { name: string, autoName?: string, autoNameSource?: string, aliasCandidates?: string[], segments: { x1: number, y1: number, x2: number, y2: number, ownerIndex?: string, isBus?: boolean }[], labels: { x: number, y: number, text: string, recordType?: string }[], powerPorts: { x: number, y: number, text: string, recordType?: string }[], crossSheetConnectors: { key: string, name: string, x: number, y: number, style?: string }[], pins: { x: number, y: number, length: number, orientation: 'left' | 'right' | 'top' | 'bottom', name: string, designator: string, ownerIndex?: string, componentDesignator?: string }[], ports: { x: number, y: number, width: number, direction?: 'left' | 'right' | 'up' | 'down', name: string }[], junctions: { x: number, y: number, color: string }[], busEntries: { x1: number, y1: number, x2: number, y2: number }[], sheetEntries: { x: number, y: number, name: string }[] }[], diagnostics: { severity: 'warning', message: string }[] }}
      */
     static build(schematic) {
         const diagnostics = []
@@ -43,12 +43,19 @@ export class SchematicNetlistBuilder {
             ).filter((connector) =>
                 SchematicNetlistBuilder.#groupContainsPoint(group, connector)
             )
-            const pins = (schematic.pins || []).filter((pin) =>
-                SchematicNetlistBuilder.#groupContainsPoint(
-                    group,
-                    SchematicNetlistBuilder.#resolvePinConnectionPoint(pin)
+            const pins = (schematic.pins || [])
+                .filter((pin) =>
+                    SchematicNetlistBuilder.#groupContainsPoint(
+                        group,
+                        SchematicNetlistBuilder.#resolvePinConnectionPoint(pin)
+                    )
+                )
+                .map((pin) =>
+                    SchematicNetlistBuilder.#annotatePinComponentDesignator(
+                        pin,
+                        schematic.componentDesignatorsByOwnerIndex
+                    )
                 )
-            )
             const ports = (schematic.ports || []).filter((port) =>
                 SchematicNetlistBuilder.#groupContainsPoint(
                     group,
@@ -89,6 +96,11 @@ export class SchematicNetlistBuilder {
             ]
             const name =
                 explicitNames[0] || 'UnknownNet' + String(unknownNetIndex++)
+            const implicitNaming =
+                SchematicNetlistBuilder.#deriveImplicitNetNaming({
+                    explicitNames,
+                    pins
+                })
 
             if (explicitNames.length > 1) {
                 diagnostics.push({
@@ -102,6 +114,7 @@ export class SchematicNetlistBuilder {
 
             return {
                 name,
+                ...implicitNaming,
                 segments: group,
                 labels,
                 powerPorts,
@@ -120,7 +133,257 @@ export class SchematicNetlistBuilder {
             }
         })
 
-        return { nets, diagnostics }
+        return {
+            nets: SchematicNetlistBuilder.#mergeMatchingPowerPortNets(nets),
+            diagnostics
+        }
+    }
+
+    /**
+     * Adds a component designator to a net pin when owner metadata resolves it.
+     * @param {object} pin Net pin.
+     * @param {Map<string, string> | Record<string, string> | undefined} componentDesignatorsByOwnerIndex Component designators by native owner id.
+     * @returns {object}
+     */
+    static #annotatePinComponentDesignator(
+        pin,
+        componentDesignatorsByOwnerIndex
+    ) {
+        const componentDesignator =
+            pin?.componentDesignator ||
+            SchematicNetlistBuilder.#lookupComponentDesignator(
+                componentDesignatorsByOwnerIndex,
+                pin?.ownerIndex
+            )
+
+        if (!componentDesignator) {
+            return pin
+        }
+
+        return {
+            ...pin,
+            componentDesignator
+        }
+    }
+
+    /**
+     * Derives non-breaking names for unnamed nets from attached pins.
+     * @param {{ explicitNames: string[], pins: object[] }} options Naming inputs.
+     * @returns {{ autoName?: string, autoNameSource?: string, aliasCandidates?: string[] }}
+     */
+    static #deriveImplicitNetNaming(options) {
+        if ((options.explicitNames || []).length) {
+            return {}
+        }
+
+        const candidates = SchematicNetlistBuilder.#pinAliasCandidates(
+            options.pins || []
+        )
+
+        if (!candidates.length) {
+            return {}
+        }
+
+        return {
+            autoName: candidates[0].name,
+            autoNameSource: candidates[0].source,
+            aliasCandidates: candidates.map((candidate) => candidate.name)
+        }
+    }
+
+    /**
+     * Builds deterministic alias candidates from connected pins.
+     * @param {object[]} pins Connected pins.
+     * @returns {{ name: string, source: string }[]}
+     */
+    static #pinAliasCandidates(pins) {
+        const candidates = []
+
+        for (const pin of pins || []) {
+            const componentDesignator = String(
+                pin?.componentDesignator || ''
+            ).trim()
+            const ownerIndex = String(pin?.ownerIndex || '').trim()
+            const pinDesignator = String(pin?.designator || '').trim()
+            const pinName = String(pin?.name || '').trim()
+
+            if (componentDesignator) {
+                SchematicNetlistBuilder.#pushPinAliasCandidate(
+                    candidates,
+                    componentDesignator,
+                    pinDesignator,
+                    'component-pin'
+                )
+                SchematicNetlistBuilder.#pushPinAliasCandidate(
+                    candidates,
+                    componentDesignator,
+                    pinName,
+                    'component-pin-name'
+                )
+                continue
+            }
+
+            if (ownerIndex) {
+                SchematicNetlistBuilder.#pushPinAliasCandidate(
+                    candidates,
+                    'owner-' + ownerIndex,
+                    pinDesignator,
+                    'owner-pin'
+                )
+                SchematicNetlistBuilder.#pushPinAliasCandidate(
+                    candidates,
+                    'owner-' + ownerIndex,
+                    pinName,
+                    'owner-pin-name'
+                )
+                continue
+            }
+
+            if (pinName) {
+                candidates.push({
+                    name: 'pin.' + pinName,
+                    source: 'pin-name'
+                })
+            }
+        }
+
+        return SchematicNetlistBuilder.#dedupeAliasCandidates(candidates)
+    }
+
+    /**
+     * Adds one scoped pin alias candidate.
+     * @param {{ name: string, source: string }[]} candidates Alias candidates.
+     * @param {string} scope Alias scope.
+     * @param {string} pinLabel Pin designator or name.
+     * @param {string} source Alias source label.
+     * @returns {void}
+     */
+    static #pushPinAliasCandidate(candidates, scope, pinLabel, source) {
+        const trimmedScope = String(scope || '').trim()
+        const trimmedPinLabel = String(pinLabel || '').trim()
+
+        if (!trimmedScope || !trimmedPinLabel) {
+            return
+        }
+
+        candidates.push({
+            name: trimmedScope + '.' + trimmedPinLabel,
+            source
+        })
+    }
+
+    /**
+     * Deduplicates alias candidates by visible alias name.
+     * @param {{ name: string, source: string }[]} candidates Alias candidates.
+     * @returns {{ name: string, source: string }[]}
+     */
+    static #dedupeAliasCandidates(candidates) {
+        const seen = new Set()
+        const uniqueCandidates = []
+
+        for (const candidate of candidates || []) {
+            if (!candidate.name || seen.has(candidate.name)) {
+                continue
+            }
+
+            seen.add(candidate.name)
+            uniqueCandidates.push(candidate)
+        }
+
+        return uniqueCandidates
+    }
+
+    /**
+     * Looks up a component designator by native owner id.
+     * @param {Map<string, string> | Record<string, string> | undefined} componentDesignatorsByOwnerIndex Component designators by native owner id.
+     * @param {string | undefined} ownerIndex Native owner id.
+     * @returns {string}
+     */
+    static #lookupComponentDesignator(
+        componentDesignatorsByOwnerIndex,
+        ownerIndex
+    ) {
+        const key = String(ownerIndex || '').trim()
+        if (!key || !componentDesignatorsByOwnerIndex) {
+            return ''
+        }
+
+        if (componentDesignatorsByOwnerIndex instanceof Map) {
+            return String(componentDesignatorsByOwnerIndex.get(key) || '')
+        }
+
+        return String(componentDesignatorsByOwnerIndex[key] || '')
+    }
+
+    /**
+     * Merges physically separate net groups that share one power-port label.
+     * @param {{ name: string, powerPorts: { text?: string }[] }[]} nets Source nets.
+     * @returns {object[]}
+     */
+    static #mergeMatchingPowerPortNets(nets) {
+        const mergedNets = []
+        const netsByPowerName = new Map()
+
+        for (const net of nets) {
+            const powerName =
+                SchematicNetlistBuilder.#singlePowerPortNetName(net)
+
+            if (!powerName) {
+                mergedNets.push(net)
+                continue
+            }
+
+            const existingNet = netsByPowerName.get(powerName)
+            if (!existingNet) {
+                netsByPowerName.set(powerName, net)
+                mergedNets.push(net)
+                continue
+            }
+
+            SchematicNetlistBuilder.#appendNet(existingNet, net)
+        }
+
+        return mergedNets
+    }
+
+    /**
+     * Returns one normalized power-port name when every port agrees.
+     * @param {{ powerPorts?: { text?: string }[] }} net Source net.
+     * @returns {string}
+     */
+    static #singlePowerPortNetName(net) {
+        const names = [
+            ...new Set(
+                (net.powerPorts || [])
+                    .map((powerPort) => String(powerPort.text || '').trim())
+                    .filter(Boolean)
+                    .map((name) => name.toUpperCase())
+            )
+        ]
+
+        return names.length === 1 ? names[0] : ''
+    }
+
+    /**
+     * Appends one net's observable members to an existing logical net.
+     * @param {object} target Existing logical net.
+     * @param {object} source Source net to append.
+     * @returns {void}
+     */
+    static #appendNet(target, source) {
+        for (const key of [
+            'segments',
+            'labels',
+            'powerPorts',
+            'crossSheetConnectors',
+            'pins',
+            'ports',
+            'junctions',
+            'busEntries',
+            'sheetEntries'
+        ]) {
+            target[key].push(...(source[key] || []))
+        }
     }
 
     /**

package/src/core/altium/SchematicNoErcSymbolResolver.mjs

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Resolves Altium No ERC marker symbol identifiers into stable names.
+ */
+export class SchematicNoErcSymbolResolver {
+    /**
+     * Converts common No ERC symbol ids and names into public labels.
+     * @param {number | string | null | undefined} symbol Symbol id or source name.
+     * @returns {string}
+     */
+    static resolveSymbolName(symbol) {
+        const text = String(symbol ?? '')
+            .trim()
+            .toLowerCase()
+
+        if (text) {
+            if (/check\s*box/.test(text)) return 'checkbox'
+            if (/cross/.test(text)) return 'cross'
+            if (/triangle/.test(text)) return 'triangle'
+            if (/box/.test(text)) return 'box'
+            if (/generic/.test(text)) return 'generic'
+        }
+
+        return (
+            {
+                0: 'generic',
+                1: 'box',
+                2: 'cross',
+                3: 'triangle'
+            }[Number(symbol)] || 'unknown'
+        )
+    }
+}

package/src/core/altium/SchematicOwnershipGraphParser.mjs

@@ -15,7 +15,7 @@ export class SchematicOwnershipGraphParser {
     /**
      * Parses record parent/child links from raw schematic records.
      * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }[]} records Schematic records.
-     * @returns {{ schema: string, records: object[], recordsByIndexInSheet: Record<string, object>, childrenByParentKey: Record<string, object[]>, parentsByChildKey: Record<string, object> }}
+     * @returns {{ schema: string, records: object[], hierarchy: object[], recordsByRecordIndex: Record<string, object>, recordsByIndexInSheet: Record<string, object>, childrenByParentKey: Record<string, object[]>, parentsByChildKey: Record<string, object> }}
      */
     static parse(records) {
         const entries = (records || []).map((record, fallbackIndex) =>
@@ -54,6 +54,12 @@ export class SchematicOwnershipGraphParser {
             records: entries.map((entry) =>
                 SchematicOwnershipGraphParser.#publicRecord(entry)
             ),
+            hierarchy: SchematicOwnershipGraphParser.#hierarchy(
+                entries,
+                parentsByChildKey
+            ),
+            recordsByRecordIndex:
+                SchematicOwnershipGraphParser.#recordsByRecordIndex(entries),
             recordsByIndexInSheet:
                 SchematicOwnershipGraphParser.#recordsByIndexInSheet(entries),
             childrenByParentKey,
@@ -61,6 +67,63 @@ export class SchematicOwnershipGraphParser {
         }
     }
 
+    /**
+     * Builds a nested public hierarchy from resolved parent links.
+     * @param {object[]} entries Record sidecar rows.
+     * @param {Record<string, { parentKey: string }>} parentsByChildKey Resolved parent links.
+     * @returns {object[]}
+     */
+    static #hierarchy(entries, parentsByChildKey) {
+        const entriesByKey = new Map(entries.map((entry) => [entry.key, entry]))
+        const childrenByParentKey = new Map()
+        const childKeys = new Set()
+
+        for (const [childKey, parentLink] of Object.entries(
+            parentsByChildKey
+        )) {
+            const child = entriesByKey.get(childKey)
+            const parent = entriesByKey.get(parentLink.parentKey)
+
+            if (!child || !parent) {
+                continue
+            }
+
+            childKeys.add(childKey)
+            if (!childrenByParentKey.has(parent.key)) {
+                childrenByParentKey.set(parent.key, [])
+            }
+
+            childrenByParentKey.get(parent.key).push(child)
+        }
+
+        return entries
+            .filter((entry) => !childKeys.has(entry.key))
+            .map((entry) =>
+                SchematicOwnershipGraphParser.#hierarchyNode(
+                    entry,
+                    childrenByParentKey
+                )
+            )
+    }
+
+    /**
+     * Builds one nested hierarchy node.
+     * @param {object} entry Record sidecar row.
+     * @param {Map<string, object[]>} childrenByParentKey Child rows by parent key.
+     * @returns {object}
+     */
+    static #hierarchyNode(entry, childrenByParentKey) {
+        return {
+            ...SchematicOwnershipGraphParser.#publicRecord(entry),
+            children: (childrenByParentKey.get(entry.key) || []).map((child) =>
+                SchematicOwnershipGraphParser.#hierarchyNode(
+                    child,
+                    childrenByParentKey
+                )
+            )
+        }
+    }
+
     /**
      * Normalizes one raw schematic record into a sidecar row.
      * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }} record Source record.
@@ -83,7 +146,8 @@ export class SchematicOwnershipGraphParser {
                 getField(record?.fields, 'UniqueID') ||
                 getField(record?.fields, 'UniqueId'),
             name: getField(record?.fields, 'Name'),
-            text: getField(record?.fields, 'Text')
+            text: getField(record?.fields, 'Text'),
+            fields: SchematicOwnershipGraphParser.#publicFields(record?.fields)
         }
     }
 
@@ -139,7 +203,8 @@ export class SchematicOwnershipGraphParser {
             ownerIndex: entry.ownerIndex,
             uniqueId: entry.uniqueId,
             name: entry.name,
-            text: entry.text
+            text: entry.text,
+            fields: entry.fields
         })
     }
 
@@ -159,6 +224,22 @@ export class SchematicOwnershipGraphParser {
         })
     }
 
+    /**
+     * Indexes records by parser record index.
+     * @param {object[]} entries Record sidecar rows.
+     * @returns {Record<string, object>}
+     */
+    static #recordsByRecordIndex(entries) {
+        const index = {}
+
+        for (const entry of entries) {
+            index[String(entry.recordIndex)] =
+                SchematicOwnershipGraphParser.#publicRecord(entry)
+        }
+
+        return index
+    }
+
     /**
      * Indexes records by native IndexInSheet values.
      * @param {object[]} entries Record sidecar rows.
@@ -177,6 +258,24 @@ export class SchematicOwnershipGraphParser {
         return index
     }
 
+    /**
+     * Copies source fields into a stable plain object for read-only consumers.
+     * @param {Record<string, string | string[]> | undefined} fields Source fields.
+     * @returns {Record<string, string | string[]>}
+     */
+    static #publicFields(fields) {
+        if (!fields || typeof fields !== 'object') {
+            return {}
+        }
+
+        return Object.fromEntries(
+            Object.entries(fields).map(([key, value]) => [
+                key,
+                Array.isArray(value) ? [...value] : value
+            ])
+        )
+    }
+
     /**
      * Drops empty object fields while preserving numeric zero.
      * @param {Record<string, unknown>} value Candidate object.