altium-toolkit 1.1.1 → 1.1.3

package/src/core/altium/PcbReviewRouteHighlightProfileBuilder.mjs

@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+import { NaturalStringComparator } from './NaturalStringComparator.mjs'
+
 /**
  * Builds route-highlight profile rows for PCB review metadata.
  */
@@ -12,33 +14,45 @@ export class PcbReviewRouteHighlightProfileBuilder {
      * @returns {object[]}
      */
     static build(routeAnalysis = {}) {
+        const routeRowsByName =
+            PcbReviewRouteHighlightProfileBuilder.#routeRowsByName(
+                routeAnalysis
+            )
         return [
             ...PcbReviewRouteHighlightProfileBuilder.#differentialPairProfiles(
-                routeAnalysis
+                routeAnalysis,
+                routeRowsByName
             ),
             ...PcbReviewRouteHighlightProfileBuilder.#differentialPairClassProfiles(
-                routeAnalysis
+                routeAnalysis,
+                routeRowsByName
             ),
             ...PcbReviewRouteHighlightProfileBuilder.#netClassProfiles(
-                routeAnalysis
+                routeAnalysis,
+                routeRowsByName
             ),
-            ...PcbReviewRouteHighlightProfileBuilder.#netProfiles(routeAnalysis)
+            ...PcbReviewRouteHighlightProfileBuilder.#netProfiles(
+                routeAnalysis,
+                routeRowsByName
+            )
         ]
     }
 
     /**
      * Builds net-class highlight profiles.
      * @param {object} routeAnalysis Route analysis model.
+     * @param {Map<string, object[]>} routeRowsByName Route rows by net name.
      * @returns {object[]}
      */
-    static #netClassProfiles(routeAnalysis) {
+    static #netClassProfiles(routeAnalysis, routeRowsByName) {
         return (routeAnalysis.classes || []).map((classRow) =>
             PcbReviewRouteHighlightProfileBuilder.#highlightProfile({
                 selectorKind: 'net-class',
                 keyPrefix: 'highlight-net-class-',
                 name: classRow.name,
                 netNames: classRow.netNames || [],
-                routeAnalysis
+                routeAnalysis,
+                routeRowsByName
             })
         )
     }
@@ -46,9 +60,10 @@ export class PcbReviewRouteHighlightProfileBuilder {
     /**
      * Builds differential-pair highlight profiles.
      * @param {object} routeAnalysis Route analysis model.
+     * @param {Map<string, object[]>} routeRowsByName Route rows by net name.
      * @returns {object[]}
      */
-    static #differentialPairProfiles(routeAnalysis) {
+    static #differentialPairProfiles(routeAnalysis, routeRowsByName) {
         return (routeAnalysis.differentialPairs || []).map((pair) =>
             PcbReviewRouteHighlightProfileBuilder.#highlightProfile({
                 selectorKind: 'differential-pair',
@@ -57,7 +72,8 @@ export class PcbReviewRouteHighlightProfileBuilder {
                 netNames: [pair.positiveNetName, pair.negativeNetName].filter(
                     Boolean
                 ),
-                routeAnalysis
+                routeAnalysis,
+                routeRowsByName
             })
         )
     }
@@ -65,9 +81,10 @@ export class PcbReviewRouteHighlightProfileBuilder {
     /**
      * Builds differential-pair class highlight profiles.
      * @param {object} routeAnalysis Route analysis model.
+     * @param {Map<string, object[]>} routeRowsByName Route rows by net name.
      * @returns {object[]}
      */
-    static #differentialPairClassProfiles(routeAnalysis) {
+    static #differentialPairClassProfiles(routeAnalysis, routeRowsByName) {
         const classNames = new Map()
         for (const pair of routeAnalysis.differentialPairs || []) {
             for (const className of pair.classes || []) {
@@ -88,7 +105,7 @@ export class PcbReviewRouteHighlightProfileBuilder {
 
         return [...classNames.entries()]
             .sort(([left], [right]) =>
-                left.localeCompare(right, undefined, { numeric: true })
+                NaturalStringComparator.compare(left, right)
             )
             .map(([className, netNames]) =>
                 PcbReviewRouteHighlightProfileBuilder.#highlightProfile({
@@ -96,7 +113,8 @@ export class PcbReviewRouteHighlightProfileBuilder {
                     keyPrefix: 'highlight-diff-pair-class-',
                     name: className,
                     netNames: [...netNames],
-                    routeAnalysis
+                    routeAnalysis,
+                    routeRowsByName
                 })
             )
     }
@@ -104,23 +122,25 @@ export class PcbReviewRouteHighlightProfileBuilder {
     /**
      * Builds scalar net highlight profiles.
      * @param {object} routeAnalysis Route analysis model.
+     * @param {Map<string, object[]>} routeRowsByName Route rows by net name.
      * @returns {object[]}
      */
-    static #netProfiles(routeAnalysis) {
+    static #netProfiles(routeAnalysis, routeRowsByName) {
         return (routeAnalysis.byNet || []).map((net) =>
             PcbReviewRouteHighlightProfileBuilder.#highlightProfile({
                 selectorKind: 'net',
                 keyPrefix: 'highlight-net-',
                 name: net.netName,
                 netNames: [net.netName],
-                routeAnalysis
+                routeAnalysis,
+                routeRowsByName
             })
         )
     }
 
     /**
      * Builds one route-highlight profile.
-     * @param {{ selectorKind: string, keyPrefix: string, name: string, netNames: string[], routeAnalysis: object }} options Profile options.
+     * @param {{ selectorKind: string, keyPrefix: string, name: string, netNames: string[], routeAnalysis: object, routeRowsByName: Map<string, object[]> }} options Profile options.
      * @returns {object}
      */
     static #highlightProfile(options) {
@@ -129,7 +149,8 @@ export class PcbReviewRouteHighlightProfileBuilder {
         )
         const layerGroups = PcbReviewRouteHighlightProfileBuilder.#layerGroups(
             options.routeAnalysis,
-            netNames
+            netNames,
+            options.routeRowsByName
         )
 
         return PcbReviewRouteHighlightProfileBuilder.#stripEmpty({
@@ -158,12 +179,13 @@ export class PcbReviewRouteHighlightProfileBuilder {
      * Builds per-layer route-highlight groups.
      * @param {object} routeAnalysis Route analysis model.
      * @param {string[]} netNames Net names.
+     * @param {Map<string, object[]>} routeRowsByName Route rows by net name.
      * @returns {object[]}
      */
-    static #layerGroups(routeAnalysis, netNames) {
+    static #layerGroups(routeAnalysis, netNames, routeRowsByName) {
         const groupsByLayer = new Map()
         for (const net of PcbReviewRouteHighlightProfileBuilder.#netsByName(
-            routeAnalysis,
+            routeRowsByName,
             netNames
         )) {
             for (const participation of net.layerParticipation || []) {
@@ -205,22 +227,37 @@ export class PcbReviewRouteHighlightProfileBuilder {
                 )
             }))
             .sort((left, right) =>
-                left.layerKey.localeCompare(right.layerKey, undefined, {
-                    numeric: true
-                })
+                NaturalStringComparator.compare(left.layerKey, right.layerKey)
             )
     }
 
     /**
-     * Resolves net route rows by name.
+     * Builds route rows indexed by net name.
      * @param {object} routeAnalysis Route analysis model.
+     * @returns {Map<string, object[]>}
+     */
+    static #routeRowsByName(routeAnalysis) {
+        const rowsByName = new Map()
+        for (const net of routeAnalysis.byNet || []) {
+            const netName = String(net?.netName || '')
+            if (!netName) continue
+            if (!rowsByName.has(netName)) {
+                rowsByName.set(netName, [])
+            }
+            rowsByName.get(netName).push(net)
+        }
+        return rowsByName
+    }
+
+    /**
+     * Resolves net route rows by name.
+     * @param {Map<string, object[]>} routeRowsByName Route rows by net name.
      * @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)
+    static #netsByName(routeRowsByName, netNames) {
+        return (netNames || []).flatMap(
+            (netName) => routeRowsByName.get(netName) || []
         )
     }
 
@@ -248,10 +285,10 @@ export class PcbReviewRouteHighlightProfileBuilder {
      * @returns {string[]}
      */
     static #sortedStrings(values) {
-        return [...new Set((values || []).filter(Boolean))].sort(
-            (left, right) =>
-                left.localeCompare(right, undefined, { numeric: true })
-        )
+        const sortedValues = [...new Set((values || []).filter(Boolean))]
+        return sortedValues.length < 2
+            ? sortedValues
+            : sortedValues.sort(NaturalStringComparator.compare)
     }
 
     /**

package/src/core/altium/PcbRouteAnalysisBuilder.mjs

@@ -183,23 +183,30 @@ export class PcbRouteAnalysisBuilder {
      * @returns {object[]}
      */
     static #netRows(pcb, routePrimitives, viaRows) {
+        const primitivesByNet =
+            PcbRouteAnalysisBuilder.#rowsByNet(routePrimitives)
+        const viasByNet = PcbRouteAnalysisBuilder.#rowsByNet(viaRows)
         const netNames = new Set([
             ...(pcb?.nets || []).map((net) => net.name).filter(Boolean),
-            ...routePrimitives.map((primitive) => primitive.netName),
-            ...viaRows.map((via) => via.netName)
+            ...primitivesByNet.keys(),
+            ...viasByNet.keys()
         ])
 
         return [...netNames]
-            .map((netName) =>
-                PcbRouteAnalysisBuilder.#netRow(
+            .map((netName) => {
+                const primitives = primitivesByNet.get(netName) || []
+                const vias = viasByNet.get(netName) || []
+                if (!primitives.length && !vias.length) {
+                    return null
+                }
+
+                return PcbRouteAnalysisBuilder.#netRow(
                     netName,
-                    routePrimitives.filter(
-                        (primitive) => primitive.netName === netName
-                    ),
-                    viaRows.filter((via) => via.netName === netName)
+                    primitives,
+                    vias
                 )
-            )
-            .filter((net) => net.totalLengthMil > 0 || net.viaCount > 0)
+            })
+            .filter(Boolean)
             .sort((left, right) =>
                 left.netName.localeCompare(right.netName, undefined, {
                     numeric: true
@@ -215,12 +222,16 @@ export class PcbRouteAnalysisBuilder {
      * @returns {object}
      */
     static #netRow(netName, primitives, vias) {
-        const trackRows = primitives.filter(
-            (primitive) => primitive.kind === 'track'
-        )
-        const arcRows = primitives.filter(
-            (primitive) => primitive.kind === 'arc'
-        )
+        const trackRows = []
+        const arcRows = []
+
+        for (const primitive of primitives || []) {
+            if (primitive.kind === 'track') {
+                trackRows.push(primitive)
+            } else if (primitive.kind === 'arc') {
+                arcRows.push(primitive)
+            }
+        }
 
         return {
             netName,
@@ -240,6 +251,29 @@ export class PcbRouteAnalysisBuilder {
         }
     }
 
+    /**
+     * Groups route rows by net name.
+     * @param {object[]} rows Route or via rows.
+     * @returns {Map<string, object[]>}
+     */
+    static #rowsByNet(rows) {
+        const rowsByNet = new Map()
+
+        for (const row of rows || []) {
+            const netName = String(row?.netName || '').trim()
+            if (!netName) {
+                continue
+            }
+
+            if (!rowsByNet.has(netName)) {
+                rowsByNet.set(netName, [])
+            }
+            rowsByNet.get(netName).push(row)
+        }
+
+        return rowsByNet
+    }
+
     /**
      * Builds per-net-class length summaries.
      * @param {object} pcb Normalized PCB model.

package/src/core/altium/PrintableTextDecoder.mjs

@@ -6,6 +6,9 @@
  * Extracts long printable runs from binary Altium documents.
  */
 export class PrintableTextDecoder {
+    static #decoderCache = new Map()
+    static #decoderConstructor = null
+
     static #WINDOWS_1252_PRINTABLE_CONTROL_BYTES = new Set([
         0x80, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8a, 0x8b, 0x8c,
         0x8e, 0x91, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9a, 0x9b,
@@ -115,7 +118,7 @@ export class PrintableTextDecoder {
         if (preferredEncoding === 'utf-8') {
             return (
                 PrintableTextDecoder.#tryDecode(bytes, 'utf-8') ||
-                new TextDecoder('utf-8').decode(bytes)
+                PrintableTextDecoder.#decode(bytes, 'utf-8')
             )
         }
         if (
@@ -124,7 +127,7 @@ export class PrintableTextDecoder {
         ) {
             return (
                 PrintableTextDecoder.#tryDecodeWindows1252(bytes) ||
-                new TextDecoder('utf-8').decode(bytes)
+                PrintableTextDecoder.#decode(bytes, 'utf-8')
             )
         }
 
@@ -144,7 +147,7 @@ export class PrintableTextDecoder {
         return (
             PrintableTextDecoder.#tryDecode(bytes, 'gb18030') ||
             PrintableTextDecoder.#tryDecodeWindows1252(bytes) ||
-            new TextDecoder('utf-8').decode(bytes)
+            PrintableTextDecoder.#decode(bytes, 'utf-8')
         )
     }
 
@@ -157,18 +160,25 @@ export class PrintableTextDecoder {
      * @param {number} minLength
      */
     static #pushRunBytes(runs, bytes, start, end, minLength) {
-        const length = end - start
-        if (length < minLength) return
-
-        const slice = bytes.slice(start, end)
-        const normalized = PrintableTextDecoder.#normalizeRun(
-            PrintableTextDecoder.decodeBytes(slice)
+        const bounds = PrintableTextDecoder.#trimAsciiByteRange(
+            bytes,
+            start,
+            end
         )
+        const length = bounds.end - bounds.start
+        if (length < minLength) return
 
-        if (normalized.length < minLength) return
-        if (!normalized.includes('|') || !normalized.includes('=')) return
+        if (
+            !PrintableTextDecoder.#containsRecordDelimiterBytes(
+                bytes,
+                bounds.start,
+                bounds.end
+            )
+        ) {
+            return
+        }
 
-        runs.push(slice)
+        runs.push(bytes.slice(start, end))
     }
 
     /**
@@ -218,6 +228,72 @@ export class PrintableTextDecoder {
         return false
     }
 
+    /**
+     * Trims ASCII whitespace from one byte range.
+     * @param {Uint8Array} bytes
+     * @param {number} start
+     * @param {number} end
+     * @returns {{ start: number, end: number }}
+     */
+    static #trimAsciiByteRange(bytes, start, end) {
+        let trimmedStart = start
+        let trimmedEnd = end
+
+        while (
+            trimmedStart < trimmedEnd &&
+            PrintableTextDecoder.#isAsciiWhitespaceByte(bytes[trimmedStart])
+        ) {
+            trimmedStart += 1
+        }
+
+        while (
+            trimmedEnd > trimmedStart &&
+            PrintableTextDecoder.#isAsciiWhitespaceByte(bytes[trimmedEnd - 1])
+        ) {
+            trimmedEnd -= 1
+        }
+
+        return {
+            start: trimmedStart,
+            end: trimmedEnd
+        }
+    }
+
+    /**
+     * Returns true when one byte range contains Altium record delimiters.
+     * @param {Uint8Array} bytes
+     * @param {number} start
+     * @param {number} end
+     * @returns {boolean}
+     */
+    static #containsRecordDelimiterBytes(bytes, start, end) {
+        let hasPipe = false
+        let hasEquals = false
+
+        for (let index = start; index < end; index += 1) {
+            if (bytes[index] === 0x7c) {
+                hasPipe = true
+            } else if (bytes[index] === 0x3d) {
+                hasEquals = true
+            }
+
+            if (hasPipe && hasEquals) {
+                return true
+            }
+        }
+
+        return false
+    }
+
+    /**
+     * Returns true when a byte is ASCII whitespace normalized around runs.
+     * @param {number} byte
+     * @returns {boolean}
+     */
+    static #isAsciiWhitespaceByte(byte) {
+        return byte === 9 || byte === 10 || byte === 13 || byte === 32
+    }
+
     /**
      * Tries one strict decode and returns null when bytes are invalid for it.
      * @param {Uint8Array} bytes
@@ -226,12 +302,56 @@ export class PrintableTextDecoder {
      */
     static #tryDecode(bytes, encoding) {
         try {
-            return new TextDecoder(encoding, { fatal: true }).decode(bytes)
+            return PrintableTextDecoder.#decode(bytes, encoding, {
+                fatal: true
+            })
         } catch {
             return null
         }
     }
 
+    /**
+     * Decodes one byte slice with a cached runtime decoder.
+     * @param {Uint8Array} bytes
+     * @param {string} encoding
+     * @param {{ fatal?: boolean }} [options]
+     * @returns {string}
+     */
+    static #decode(bytes, encoding, options = {}) {
+        return PrintableTextDecoder.#getTextDecoder(encoding, options).decode(
+            bytes
+        )
+    }
+
+    /**
+     * Resolves a cached TextDecoder for one encoding and fatal mode.
+     * @param {string} encoding
+     * @param {{ fatal?: boolean }} options
+     * @returns {TextDecoder}
+     */
+    static #getTextDecoder(encoding, options) {
+        const Decoder = globalThis.TextDecoder
+        if (PrintableTextDecoder.#decoderConstructor !== Decoder) {
+            PrintableTextDecoder.#decoderCache = new Map()
+            PrintableTextDecoder.#decoderConstructor = Decoder
+        }
+
+        const normalizedEncoding = String(encoding || 'utf-8').toLowerCase()
+        const fatal = Boolean(options?.fatal)
+        const cacheKey = `${normalizedEncoding}:${fatal ? 'fatal' : 'replace'}`
+        const cached = PrintableTextDecoder.#decoderCache.get(cacheKey)
+        if (cached) {
+            return cached
+        }
+
+        const decoder = new Decoder(
+            normalizedEncoding,
+            fatal ? { fatal: true } : {}
+        )
+        PrintableTextDecoder.#decoderCache.set(cacheKey, decoder)
+        return decoder
+    }
+
     /**
      * Tries a Windows-1252 decode and normalizes runtimes that expose C1 bytes
      * as control characters instead of punctuation.

package/src/core/altium/SchematicComponentOwnerTextResolver.mjs

@@ -66,6 +66,19 @@ export class SchematicComponentOwnerTextResolver {
         )
     }
 
+    /**
+     * Resolves candidate owner indexes for one schematic component record.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }} componentRecord Component placement record.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }[]} records Indexed schematic records.
+     * @returns {string[]}
+     */
+    static resolveOwnerIndexes(componentRecord, records) {
+        return SchematicComponentOwnerTextResolver.#resolveOwnerIndexes(
+            componentRecord,
+            records
+        )
+    }
+
     /**
      * Resolves candidate owner indexes for one schematic component record.
      * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }} componentRecord Component placement record.

package/src/core/altium/SchematicComponentTextResolver.mjs

@@ -56,7 +56,7 @@ export class SchematicComponentTextResolver {
      */
     static resolveValue(ownerTexts, texts, component) {
         const ownerValue =
-            SchematicComponentTextResolver.#findFirstRelatedTextRecord(
+            SchematicComponentTextResolver.#findFirstUsableRelatedTextRecord(
                 ownerTexts,
                 ['Comment', 'VALUE']
             )
@@ -128,6 +128,45 @@ export class SchematicComponentTextResolver {
         return { found: false, text: '' }
     }
 
+    /**
+     * Finds the first owner text that is resolved or explicitly empty, while
+     * allowing unresolved templates to fall through to later owner parameters.
+     * @param {{ fields: Record<string, string | string[]> }[]} records
+     * @param {string[]} logicalNames Logical text names.
+     * @returns {{ found: boolean, text: string }}
+     */
+    static #findFirstUsableRelatedTextRecord(records, logicalNames) {
+        let unresolvedMatch = { found: false, text: '' }
+
+        for (const logicalName of logicalNames) {
+            const match = SchematicComponentTextResolver.#findRelatedTextRecord(
+                records,
+                logicalName
+            )
+
+            if (!match.found) {
+                continue
+            }
+
+            if (
+                SchematicComponentTextResolver.#isExplicitEmptyText(
+                    match.text
+                ) ||
+                SchematicComponentTextResolver.#isResolvedComponentText(
+                    match.text
+                )
+            ) {
+                return match
+            }
+
+            if (!unresolvedMatch.found) {
+                unresolvedMatch = match
+            }
+        }
+
+        return unresolvedMatch
+    }
+
     /**
      * Finds the closest nearby designator text for one component.
      * @param {{ x: number, y: number, text: string, name: string }[]} texts

package/src/core/altium/SchematicDisplayModeCatalogParser.mjs

@@ -18,12 +18,14 @@ export class SchematicDisplayModeCatalogParser {
      * @returns {object | null}
      */
     static parse(records) {
+        const childrenByOwner =
+            SchematicDisplayModeCatalogParser.#ownerChildrenByOwner(records)
         const components = (records || [])
             .filter((record) => getField(record.fields, 'RECORD') === '1')
             .map((record) =>
                 SchematicDisplayModeCatalogParser.#componentCatalog(
                     record,
-                    records
+                    childrenByOwner
                 )
             )
             .filter(Boolean)
@@ -41,17 +43,17 @@ export class SchematicDisplayModeCatalogParser {
     /**
      * Builds one component display-mode catalog row.
      * @param {object} componentRecord Component record.
-     * @param {object[]} records All schematic records.
+     * @param {Map<string, object[]>} childrenByOwner Child records by owner index.
      * @returns {object}
      */
-    static #componentCatalog(componentRecord, records) {
+    static #componentCatalog(componentRecord, childrenByOwner) {
         const indexInSheet = parseNumericField(
             componentRecord.fields,
             'IndexInSheet'
         )
         const ownerIndex = String(indexInSheet ?? componentRecord.recordIndex)
         const children = SchematicDisplayModeCatalogParser.#ownerChildren(
-            records,
+            childrenByOwner,
             ownerIndex
         )
         const declaredPartCount =
@@ -95,16 +97,39 @@ export class SchematicDisplayModeCatalogParser {
 
     /**
      * Returns child records with owner part/display metadata.
-     * @param {object[]} records All schematic records.
+     * @param {Map<string, object[]>} childrenByOwner Child records by owner index.
      * @param {string} ownerIndex Component owner index.
      * @returns {object[]}
      */
-    static #ownerChildren(records, ownerIndex) {
-        return (records || []).filter(
-            (record) =>
-                getField(record.fields, 'OwnerIndex') === ownerIndex &&
-                parseNumericField(record.fields, 'OwnerPartID') !== null
-        )
+    static #ownerChildren(childrenByOwner, ownerIndex) {
+        return childrenByOwner.get(ownerIndex) || []
+    }
+
+    /**
+     * Indexes schematic owner child records once for display-mode cataloguing.
+     * @param {object[]} records Schematic records.
+     * @returns {Map<string, object[]>}
+     */
+    static #ownerChildrenByOwner(records) {
+        const childrenByOwner = new Map()
+
+        for (const record of records || []) {
+            if (parseNumericField(record.fields, 'OwnerPartID') === null) {
+                continue
+            }
+
+            const ownerIndex = getField(record.fields, 'OwnerIndex')
+            if (!ownerIndex) {
+                continue
+            }
+
+            if (!childrenByOwner.has(ownerIndex)) {
+                childrenByOwner.set(ownerIndex, [])
+            }
+            childrenByOwner.get(ownerIndex).push(record)
+        }
+
+        return childrenByOwner
     }
 
     /**