altium-toolkit 1.0.7 → 1.0.9

package/src/core/altium/SchematicRecordTypeRegistry.mjs

@@ -0,0 +1,137 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Provides stable schematic record type descriptors for parser consumers.
+ */
+export class SchematicRecordTypeRegistry {
+    static #RECORD_TYPES = new Map([
+        [0, ['file-header', 'metadata', true]],
+        [1, ['component', 'component', true]],
+        [2, ['pin', 'component', true]],
+        [3, ['ieee-symbol', 'symbol', true]],
+        [4, ['label', 'annotation', true]],
+        [5, ['bezier', 'graphic', true]],
+        [6, ['polyline', 'graphic', true]],
+        [7, ['polygon', 'graphic', true]],
+        [8, ['ellipse', 'graphic', true]],
+        [9, ['pie-chart', 'graphic', true]],
+        [10, ['rounded-rectangle', 'graphic', true]],
+        [11, ['elliptical-arc', 'graphic', true]],
+        [12, ['arc', 'graphic', true]],
+        [13, ['line', 'graphic', true]],
+        [14, ['rectangle', 'graphic', true]],
+        [15, ['sheet-symbol', 'sheet', true]],
+        [16, ['sheet-entry', 'sheet', true]],
+        [17, ['power-port', 'connectivity', true]],
+        [18, ['port', 'connectivity', true]],
+        [22, ['no-erc', 'directive', true]],
+        [25, ['net-label', 'connectivity', true]],
+        [26, ['bus', 'connectivity', true]],
+        [27, ['wire', 'connectivity', true]],
+        [28, ['text-frame', 'annotation', true]],
+        [29, ['junction', 'connectivity', true]],
+        [30, ['image', 'graphic', true]],
+        [31, ['sheet', 'sheet', true]],
+        [32, ['sheet-name', 'sheet', true]],
+        [33, ['file-name', 'sheet', true]],
+        [34, ['designator', 'component', true]],
+        [37, ['bus-entry', 'connectivity', true]],
+        [39, ['template', 'metadata', true]],
+        [41, ['parameter', 'component', true]],
+        [43, ['parameter-set', 'directive', true]],
+        [44, ['implementation-list', 'implementation', true]],
+        [45, ['implementation', 'implementation', true]],
+        [46, ['map-definer-list', 'implementation', true]],
+        [47, ['map-definer', 'implementation', true]],
+        [48, ['implementation-parameters', 'implementation', true]],
+        [209, ['note', 'annotation', true]],
+        [211, ['compile-mask', 'directive', true]],
+        [215, ['harness-connector', 'harness', true]],
+        [216, ['harness-entry', 'harness', true]],
+        [217, ['harness-type', 'harness', true]],
+        [218, ['signal-harness', 'harness', true]],
+        [225, ['blanket', 'directive', true]],
+        [226, ['hyperlink', 'annotation', false]]
+    ])
+
+    /**
+     * Lists every known schematic record descriptor.
+     * @returns {{ recordType: number, name: string, family: string, supported: boolean }[]}
+     */
+    static list() {
+        return [...SchematicRecordTypeRegistry.#RECORD_TYPES.keys()]
+            .sort((left, right) => left - right)
+            .map((recordType) => SchematicRecordTypeRegistry.get(recordType))
+    }
+
+    /**
+     * Returns the descriptor for one record type.
+     * @param {number | string} recordType
+     * @returns {{ recordType: number, name: string, family: string, supported: boolean }}
+     */
+    static get(recordType) {
+        const normalizedRecordType =
+            SchematicRecordTypeRegistry.#normalizeRecordType(recordType)
+        const descriptor =
+            SchematicRecordTypeRegistry.#RECORD_TYPES.get(normalizedRecordType)
+
+        if (!descriptor) {
+            return {
+                recordType: normalizedRecordType,
+                name: 'unknown-' + normalizedRecordType,
+                family: 'unknown',
+                supported: false
+            }
+        }
+
+        return {
+            recordType: normalizedRecordType,
+            name: descriptor[0],
+            family: descriptor[1],
+            supported: descriptor[2]
+        }
+    }
+
+    /**
+     * Summarizes record counts by known type descriptor.
+     * @param {{ fields?: Record<string, string | string[]> }[]} records
+     * @returns {{ recordType: number, name: string, family: string, supported: boolean, count: number }[]}
+     */
+    static summarize(records) {
+        const counts = new Map()
+
+        for (const record of records || []) {
+            const recordType = SchematicRecordTypeRegistry.#normalizeRecordType(
+                record?.fields?.RECORD
+            )
+            if (recordType < 0) {
+                continue
+            }
+
+            counts.set(recordType, (counts.get(recordType) || 0) + 1)
+        }
+
+        return [...counts.entries()]
+            .sort(([left], [right]) => left - right)
+            .map(([recordType, count]) => ({
+                ...SchematicRecordTypeRegistry.get(recordType),
+                count
+            }))
+    }
+
+    /**
+     * Normalizes one record type field value.
+     * @param {number | string | undefined | string[]} recordType
+     * @returns {number}
+     */
+    static #normalizeRecordType(recordType) {
+        const rawValue = Array.isArray(recordType) ? recordType[0] : recordType
+        const normalizedRecordType = Number(rawValue)
+
+        return Number.isInteger(normalizedRecordType)
+            ? normalizedRecordType
+            : -1
+    }
+}

package/src/core/altium/SchematicRepeatedChannelParser.mjs

@@ -0,0 +1,229 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+const { getField, parseNumericField } = ParserUtils
+
+/**
+ * Parses schematic repeated-channel declarations and derived net aliases.
+ */
+export class SchematicRepeatedChannelParser {
+    static SCHEMA_ID = 'altium-toolkit.schematic.repeated-channels.a1'
+
+    /**
+     * Parses repeated-channel rooms and sheet-entry aliases.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }[]} records Schematic records.
+     * @returns {object | null}
+     */
+    static parse(records) {
+        const sheetSymbols = (records || []).filter(
+            (record) => getField(record.fields, 'RECORD') === '15'
+        )
+        const sheetEntries = (records || []).filter(
+            (record) => getField(record.fields, 'RECORD') === '16'
+        )
+        const rooms = sheetSymbols
+            .map((record) => SchematicRepeatedChannelParser.#room(record))
+            .filter(Boolean)
+        const netAliases = rooms.flatMap((room) =>
+            SchematicRepeatedChannelParser.#netAliases(
+                room,
+                sheetEntries.filter(
+                    (entry) =>
+                        getField(entry.fields, 'OwnerIndex') === room.ownerIndex
+                )
+            )
+        )
+
+        if (!rooms.length && !netAliases.length) {
+            return null
+        }
+
+        return {
+            schema: SchematicRepeatedChannelParser.SCHEMA_ID,
+            rooms: rooms.map(({ ownerIndex, ...room }) => room),
+            netAliases
+        }
+    }
+
+    /**
+     * Parses one repeated sheet-symbol declaration.
+     * @param {object} record Sheet-symbol record.
+     * @returns {object | null}
+     */
+    static #room(record) {
+        const repeat = SchematicRepeatedChannelParser.#parseRepeatRange(
+            getField(record.fields, 'Name') ||
+                getField(record.fields, 'SheetName') ||
+                getField(record.fields, 'Designator')
+        )
+        if (!repeat) {
+            return null
+        }
+
+        const indexInSheet =
+            parseNumericField(record.fields, 'IndexInSheet') ??
+            record.recordIndex ??
+            0
+        const designatorTemplate =
+            getField(record.fields, 'Designator') ||
+            '$ChannelPrefix$ChannelIndex'
+        const instances = []
+
+        for (
+            let index = repeat.startIndex;
+            index <= repeat.endIndex;
+            index += 1
+        ) {
+            const alpha = SchematicRepeatedChannelParser.#alpha(index)
+            const channelPrefix = repeat.channelName
+            const designator = SchematicRepeatedChannelParser.#formatDesignator(
+                designatorTemplate,
+                {
+                    channelPrefix,
+                    channelIndex: index,
+                    channelAlpha: alpha
+                }
+            )
+
+            instances.push({
+                index,
+                alpha,
+                channelPrefix,
+                designator,
+                hierarchyPath: designator
+            })
+        }
+
+        return {
+            key: 'repeated-channel-' + String(indexInSheet),
+            sheetSymbolKey: SchematicRepeatedChannelParser.#recordKey(record),
+            ownerIndex: String(indexInSheet),
+            channelName: repeat.channelName,
+            startIndex: repeat.startIndex,
+            endIndex: repeat.endIndex,
+            designatorTemplate,
+            instances
+        }
+    }
+
+    /**
+     * Builds aliases for repeated sheet entries.
+     * @param {object} room Repeated-channel room.
+     * @param {object[]} sheetEntries Child sheet-entry records.
+     * @returns {object[]}
+     */
+    static #netAliases(room, sheetEntries) {
+        return (sheetEntries || [])
+            .map((entry) => {
+                const repeatEntry =
+                    SchematicRepeatedChannelParser.#parseRepeatEntryName(
+                        getField(entry.fields, 'Name')
+                    )
+                if (!repeatEntry) {
+                    return null
+                }
+
+                return {
+                    key:
+                        'repeated-channel-net-' +
+                        String(entry.recordIndex ?? 0),
+                    sheetEntryKey:
+                        SchematicRepeatedChannelParser.#recordKey(entry),
+                    sheetSymbolKey: room.sheetSymbolKey,
+                    baseName: repeatEntry,
+                    aliases: room.instances.map(
+                        (instance) => instance.hierarchyPath + '/' + repeatEntry
+                    ),
+                    hierarchyPaths: room.instances.map(
+                        (instance) => instance.hierarchyPath
+                    )
+                }
+            })
+            .filter(Boolean)
+    }
+
+    /**
+     * Parses `REPEAT(name, start, end)`.
+     * @param {string} value Raw repeat string.
+     * @returns {{ channelName: string, startIndex: number, endIndex: number } | null}
+     */
+    static #parseRepeatRange(value) {
+        const match = String(value || '').match(
+            /^REPEAT\s*\(\s*([^,]+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*\)$/i
+        )
+        if (!match) {
+            return null
+        }
+
+        const startIndex = Number.parseInt(match[2], 10)
+        const endIndex = Number.parseInt(match[3], 10)
+        if (
+            !Number.isInteger(startIndex) ||
+            !Number.isInteger(endIndex) ||
+            endIndex < startIndex
+        ) {
+            return null
+        }
+
+        return {
+            channelName: match[1].trim(),
+            startIndex,
+            endIndex
+        }
+    }
+
+    /**
+     * Parses `REPEAT(name)` sheet-entry aliases.
+     * @param {string} value Raw sheet-entry name.
+     * @returns {string}
+     */
+    static #parseRepeatEntryName(value) {
+        const match = String(value || '').match(
+            /^REPEAT\s*\(\s*([^)]+?)\s*\)$/i
+        )
+        return match ? match[1].trim() : ''
+    }
+
+    /**
+     * Resolves a channel designator template.
+     * @param {string} template Designator template.
+     * @param {{ channelPrefix: string, channelIndex: number, channelAlpha: string }} tokens Channel tokens.
+     * @returns {string}
+     */
+    static #formatDesignator(template, tokens) {
+        return String(template || '')
+            .replaceAll('$ChannelPrefix', tokens.channelPrefix)
+            .replaceAll('$ChannelIndex', String(tokens.channelIndex))
+            .replaceAll('$ChannelAlpha', tokens.channelAlpha)
+    }
+
+    /**
+     * Converts one-based channel indexes into spreadsheet-style letters.
+     * @param {number} index One-based index.
+     * @returns {string}
+     */
+    static #alpha(index) {
+        let value = Math.max(Number(index) || 1, 1)
+        let output = ''
+
+        while (value > 0) {
+            value -= 1
+            output = String.fromCharCode(65 + (value % 26)) + output
+            value = Math.floor(value / 26)
+        }
+
+        return output
+    }
+
+    /**
+     * Builds a stable schematic record key.
+     * @param {object} record Schematic record.
+     * @returns {string}
+     */
+    static #recordKey(record) {
+        return 'schematic-record-' + String(record?.recordIndex ?? 0)
+    }
+}

package/src/core/altium/SchematicStreamExtractor.mjs

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { AsciiRecordParser } from './AsciiRecordParser.mjs'
+import { EmbeddedFileInventoryBuilder } from './EmbeddedFileInventoryBuilder.mjs'
 import { OleCompoundDocument } from '../ole/OleCompoundDocument.mjs'
 import { OleConstants } from '../ole/OleConstants.mjs'
 
@@ -75,7 +76,15 @@ export class SchematicStreamExtractor {
 
         return {
             records,
-            streamNames: compoundDocument.listStreams()
+            streamNames: compoundDocument.listStreams(),
+            embeddedFiles: EmbeddedFileInventoryBuilder.buildFromStreams(
+                new Map(
+                    compoundDocument
+                        .listStreams()
+                        .map((name) => [name, compoundDocument.getStream(name)])
+                ),
+                { skipStreamNames: ['FileHeader'] }
+            )
         }
     }
 

package/src/core/altium/SchematicTemplateParser.mjs

@@ -0,0 +1,256 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+const { getDisplayText, getField, parseBoolean, parseNumericField } =
+    ParserUtils
+
+/**
+ * Builds a read-only sidecar for schematic template metadata.
+ */
+export class SchematicTemplateParser {
+    static SCHEMA_ID = 'altium-toolkit.schematic.template.a1'
+
+    /**
+     * Parses template identity and owned schematic records.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }[]} records Schematic records.
+     * @param {{ fields?: Record<string, string | string[]> } | undefined} sheetRecord Sheet record.
+     * @param {{ fonts?: object, titleBlock?: object }} sheet Normalized sheet.
+     * @returns {object | null}
+     */
+    static parse(records, sheetRecord, sheet) {
+        const templateRecord =
+            (records || []).find(
+                (record) => getField(record.fields, 'RECORD') === '39'
+            ) || null
+        const identity = SchematicTemplateParser.#identity(
+            sheetRecord?.fields,
+            templateRecord
+        )
+        const ownedRecords = templateRecord
+            ? SchematicTemplateParser.#ownedRecords(records, templateRecord)
+            : []
+
+        if (
+            !identity.fileName &&
+            !identity.recordId &&
+            ownedRecords.length === 0
+        ) {
+            return null
+        }
+
+        return {
+            schema: SchematicTemplateParser.SCHEMA_ID,
+            identity,
+            ownedRecordKeys: ownedRecords.map((record) =>
+                SchematicTemplateParser.#recordKey(record)
+            ),
+            ownedGraphics: SchematicTemplateParser.#ownedGraphics(ownedRecords),
+            fonts: sheet?.fonts || {},
+            missingParameters:
+                SchematicTemplateParser.#missingParameters(records),
+            titleBlock: sheet?.titleBlock || {}
+        }
+    }
+
+    /**
+     * Builds template identity fields from sheet and template records.
+     * @param {Record<string, string | string[]> | undefined} fields Sheet fields.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex?: number } | null} templateRecord Template record.
+     * @returns {object}
+     */
+    static #identity(fields, templateRecord) {
+        return SchematicTemplateParser.#stripEmpty({
+            showGraphics: parseBoolean(fields?.ShowTemplateGraphics),
+            fileName: getField(fields, 'TemplateFileName'),
+            vaultGuid: getField(fields, 'TemplateVaultGUID'),
+            itemGuid: getField(fields, 'TemplateItemGUID'),
+            revisionGuid: getField(fields, 'TemplateRevisionGUID'),
+            vaultHrid: getField(fields, 'TemplateVaultHRID'),
+            revisionHrid: getField(fields, 'TemplateRevisionHRID'),
+            recordId: templateRecord
+                ? SchematicTemplateParser.#semanticRecordId(templateRecord)
+                : '',
+            name: getField(templateRecord?.fields, 'Name'),
+            uniqueId:
+                getField(templateRecord?.fields, 'UniqueID') ||
+                getField(templateRecord?.fields, 'UniqueId')
+        })
+    }
+
+    /**
+     * Returns records owned by the template record.
+     * @param {object[]} records Schematic records.
+     * @param {object} templateRecord Template owner record.
+     * @returns {object[]}
+     */
+    static #ownedRecords(records, templateRecord) {
+        const ownerKeys = new Set(
+            SchematicTemplateParser.#ownerKeys(templateRecord)
+        )
+
+        return (records || []).filter(
+            (record) =>
+                record !== templateRecord &&
+                ownerKeys.has(getField(record.fields, 'OwnerIndex'))
+        )
+    }
+
+    /**
+     * Builds grouped owned record keys by primitive family.
+     * @param {object[]} ownedRecords Template-owned records.
+     * @returns {object}
+     */
+    static #ownedGraphics(ownedRecords) {
+        const groups = {
+            lines: [],
+            polygons: [],
+            rectangles: [],
+            ellipses: [],
+            arcs: [],
+            texts: [],
+            images: []
+        }
+
+        for (const record of ownedRecords) {
+            const key = SchematicTemplateParser.#recordKey(record)
+            switch (getField(record.fields, 'RECORD')) {
+                case '4':
+                case '28':
+                case '41':
+                    groups.texts.push(key)
+                    break
+                case '7':
+                    groups.polygons.push(key)
+                    break
+                case '8':
+                    groups.ellipses.push(key)
+                    break
+                case '11':
+                case '12':
+                    groups.arcs.push(key)
+                    break
+                case '14':
+                case '225':
+                    groups.rectangles.push(key)
+                    break
+                case '30':
+                    groups.images.push(key)
+                    break
+                default:
+                    groups.lines.push(key)
+                    break
+            }
+        }
+
+        return groups
+    }
+
+    /**
+     * Collects unresolved equals-prefixed placeholders.
+     * @param {object[]} records Schematic records.
+     * @returns {string[]}
+     */
+    static #missingParameters(records) {
+        const metadata = SchematicTemplateParser.#metadata(records)
+        const missing = []
+
+        for (const record of records || []) {
+            const text = getDisplayText(record.fields).trim()
+            const match = text.match(/^=([A-Za-z0-9_.-]+)$/u)
+            if (!match) {
+                continue
+            }
+            const parameterName = match[1]
+            if (!metadata.has(parameterName.toLowerCase())) {
+                missing.push(parameterName)
+            }
+        }
+
+        return [...new Set(missing)].sort((left, right) =>
+            left.localeCompare(right)
+        )
+    }
+
+    /**
+     * Builds a lowercase metadata-name set.
+     * @param {object[]} records Schematic records.
+     * @returns {Set<string>}
+     */
+    static #metadata(records) {
+        const metadata = new Set()
+
+        for (const record of records || []) {
+            const name = getField(record.fields, 'Name').trim()
+            const value = getDisplayText(record.fields).trim()
+            if (name && value && value !== '*') {
+                metadata.add(name.toLowerCase())
+            }
+        }
+
+        return metadata
+    }
+
+    /**
+     * Builds owner lookup keys for one record.
+     * @param {object} record Schematic record.
+     * @returns {string[]}
+     */
+    static #ownerKeys(record) {
+        const recordIndex = Number(record?.recordIndex)
+        const indexInSheet = parseNumericField(record?.fields, 'IndexInSheet')
+        const keys = new Set()
+
+        if (Number.isInteger(recordIndex)) {
+            keys.add(String(recordIndex))
+            keys.add(String(recordIndex + 1))
+        }
+        if (Number.isInteger(indexInSheet)) {
+            keys.add(String(indexInSheet))
+            keys.add(String(indexInSheet + 1))
+        }
+
+        return [...keys]
+    }
+
+    /**
+     * Builds the public semantic record id.
+     * @param {object} record Schematic record.
+     * @returns {string}
+     */
+    static #semanticRecordId(record) {
+        const indexInSheet = parseNumericField(record?.fields, 'IndexInSheet')
+        return 'record-' + String(indexInSheet ?? record?.recordIndex ?? 0)
+    }
+
+    /**
+     * Builds a stable internal record key.
+     * @param {object} record Schematic record.
+     * @returns {string}
+     */
+    static #recordKey(record) {
+        return 'schematic-record-' + String(record?.recordIndex ?? 0)
+    }
+
+    /**
+     * Removes empty fields while preserving false and zero.
+     * @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 !== ''
+                )
+            })
+        )
+    }
+}