altium-toolkit 1.1.22 → 1.1.23

package/src/core/altium/AltiumUnits.mjs

@@ -0,0 +1,205 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Provides deterministic conversions for common Altium length units.
+ */
+export class AltiumUnits {
+    static RAW_UNITS_PER_MIL = 10000
+
+    static MM_PER_MIL = 0.0254
+
+    static MIL_PER_INCH = 1000
+
+    /**
+     * Converts millimeters to mils.
+     * @param {number} value Length in millimeters.
+     * @returns {number}
+     */
+    static mmToMil(value) {
+        return AltiumUnits.#round(Number(value) / AltiumUnits.MM_PER_MIL)
+    }
+
+    /**
+     * Converts mils to millimeters.
+     * @param {number} value Length in mils.
+     * @returns {number}
+     */
+    static milToMm(value) {
+        return AltiumUnits.#round(Number(value) * AltiumUnits.MM_PER_MIL)
+    }
+
+    /**
+     * Converts inches to mils.
+     * @param {number} value Length in inches.
+     * @returns {number}
+     */
+    static inchToMil(value) {
+        return AltiumUnits.#round(Number(value) * AltiumUnits.MIL_PER_INCH)
+    }
+
+    /**
+     * Converts mils to inches.
+     * @param {number} value Length in mils.
+     * @returns {number}
+     */
+    static milToInch(value) {
+        return AltiumUnits.#round(Number(value) / AltiumUnits.MIL_PER_INCH)
+    }
+
+    /**
+     * Converts raw Altium coordinate units to mils.
+     * @param {number} value Raw coordinate units.
+     * @returns {number}
+     */
+    static rawToMil(value) {
+        return AltiumUnits.#round(Number(value) / AltiumUnits.RAW_UNITS_PER_MIL)
+    }
+
+    /**
+     * Converts mils to raw Altium coordinate units.
+     * @param {number} value Length in mils.
+     * @returns {number}
+     */
+    static milToRaw(value) {
+        return AltiumUnits.#round(Number(value) * AltiumUnits.RAW_UNITS_PER_MIL)
+    }
+
+    /**
+     * Parses one numeric or textual length into a deterministic unit bundle.
+     * @param {unknown} value Length value.
+     * @param {{ defaultUnit?: 'mil' | 'mm' | 'in' | 'raw' }} [options]
+     * @returns {{ value: number, unit: string, mil: number, mm: number, inch: number, raw: number } | null}
+     */
+    static parseLength(value, options = {}) {
+        const parsed = AltiumUnits.#parseNumericAndUnit(value, options)
+        if (!parsed) return null
+
+        const mil = AltiumUnits.#toMil(parsed.value, parsed.unit)
+        if (!Number.isFinite(mil)) return null
+
+        return {
+            value: AltiumUnits.#round(parsed.value),
+            unit: parsed.unit,
+            mil: AltiumUnits.#round(mil),
+            mm: AltiumUnits.milToMm(mil),
+            inch: AltiumUnits.milToInch(mil),
+            raw: AltiumUnits.milToRaw(mil)
+        }
+    }
+
+    /**
+     * Formats a mil value in the requested target unit.
+     * @param {number} value Length in mils.
+     * @param {'mil' | 'mm' | 'in' | 'raw'} [unit]
+     * @returns {string}
+     */
+    static formatMil(value, unit = 'mil') {
+        const mil = Number(value)
+        if (!Number.isFinite(mil)) return ''
+
+        const normalizedUnit = AltiumUnits.#normalizeUnit(unit)
+        if (normalizedUnit === 'mm') {
+            return AltiumUnits.#formatNumber(AltiumUnits.milToMm(mil)) + 'mm'
+        }
+        if (normalizedUnit === 'in') {
+            return AltiumUnits.#formatNumber(AltiumUnits.milToInch(mil)) + 'in'
+        }
+        if (normalizedUnit === 'raw') {
+            return AltiumUnits.#formatNumber(AltiumUnits.milToRaw(mil)) + 'raw'
+        }
+        return AltiumUnits.#formatNumber(mil) + 'mil'
+    }
+
+    /**
+     * Parses an input value into a number and normalized unit token.
+     * @param {unknown} value Length input.
+     * @param {{ defaultUnit?: string }} options Parse options.
+     * @returns {{ value: number, unit: 'mil' | 'mm' | 'in' | 'raw' } | null}
+     */
+    static #parseNumericAndUnit(value, options) {
+        const defaultUnit = AltiumUnits.#normalizeUnit(
+            options?.defaultUnit || 'mil'
+        )
+
+        if (typeof value === 'number') {
+            return Number.isFinite(value) ? { value, unit: defaultUnit } : null
+        }
+
+        const text = String(value ?? '').trim()
+        const match = text.match(
+            /^([-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[-+]?\d+)?)\s*([A-Za-z]*)$/u
+        )
+        if (!match) return null
+
+        const numericValue = Number(match[1])
+        if (!Number.isFinite(numericValue)) return null
+
+        return {
+            value: numericValue,
+            unit: AltiumUnits.#normalizeUnit(match[2] || defaultUnit)
+        }
+    }
+
+    /**
+     * Converts one normalized length value to mils.
+     * @param {number} value Numeric length.
+     * @param {'mil' | 'mm' | 'in' | 'raw'} unit Length unit.
+     * @returns {number}
+     */
+    static #toMil(value, unit) {
+        if (unit === 'mm') return AltiumUnits.mmToMil(value)
+        if (unit === 'in') return AltiumUnits.inchToMil(value)
+        if (unit === 'raw') return AltiumUnits.rawToMil(value)
+        return Number(value)
+    }
+
+    /**
+     * Normalizes one unit label.
+     * @param {unknown} unit Unit label.
+     * @returns {'mil' | 'mm' | 'in' | 'raw'}
+     */
+    static #normalizeUnit(unit) {
+        const normalized = String(unit || '')
+            .trim()
+            .toLowerCase()
+        if (
+            normalized === 'mm' ||
+            normalized === 'millimeter' ||
+            normalized === 'millimeters'
+        ) {
+            return 'mm'
+        }
+        if (
+            normalized === 'in' ||
+            normalized === 'inch' ||
+            normalized === 'inches'
+        ) {
+            return 'in'
+        }
+        if (normalized === 'raw') {
+            return 'raw'
+        }
+        return 'mil'
+    }
+
+    /**
+     * Formats a number without unstable floating-point tails.
+     * @param {number} value Numeric value.
+     * @returns {string}
+     */
+    static #formatNumber(value) {
+        return String(AltiumUnits.#round(value))
+    }
+
+    /**
+     * Rounds a numeric value to stable JSON/report precision.
+     * @param {number} value Numeric value.
+     * @returns {number}
+     */
+    static #round(value) {
+        const numeric = Number(value)
+        return Number.isFinite(numeric) ? Number(numeric.toFixed(9)) : numeric
+    }
+}

package/src/core/altium/AsciiRecordParser.mjs

@@ -63,6 +63,15 @@ export class AsciiRecordParser {
         return records
     }
 
+    /**
+     * Parses one pipe-delimited record string into a field object.
+     * @param {string} raw Raw record text.
+     * @returns {{ raw: string, fields: Record<string, string | string[]> }}
+     */
+    static parseRecord(raw) {
+        return AsciiRecordParser.#parseRecord(raw)
+    }
+
     /**
      * Returns true when a printable run looks like an Altium record block.
      * @param {string} candidate

package/src/core/altium/EmbeddedAssetReportBuilder.mjs

@@ -0,0 +1,383 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds deterministic inventories of embedded assets across parser roots.
+ */
+export class EmbeddedAssetReportBuilder {
+    static SCHEMA = 'altium-toolkit.embedded-assets.a1'
+
+    /**
+     * Builds an embedded-asset report.
+     * @param {{ models?: object[] } | object[]} input Parser-root models.
+     * @returns {object}
+     */
+    static build(input = {}) {
+        const models = EmbeddedAssetReportBuilder.#models(input)
+        const assets = EmbeddedAssetReportBuilder.#dedupeAssets(
+            models.flatMap((model) =>
+                EmbeddedAssetReportBuilder.#assetsForModel(model)
+            )
+        ).sort(EmbeddedAssetReportBuilder.#compareAssets)
+
+        return {
+            schema: EmbeddedAssetReportBuilder.SCHEMA,
+            summary: {
+                modelCount: models.length,
+                assetCount: assets.length,
+                totalByteCount: assets.reduce(
+                    (count, asset) => count + asset.byteLength,
+                    0
+                ),
+                byKind: EmbeddedAssetReportBuilder.#byKind(assets)
+            },
+            assets
+        }
+    }
+
+    /**
+     * Normalizes builder input to a model array.
+     * @param {{ models?: object[] } | object[]} input Builder input.
+     * @returns {object[]}
+     */
+    static #models(input) {
+        if (Array.isArray(input)) return input
+        return Array.isArray(input?.models) ? input.models : []
+    }
+
+    /**
+     * Collects embedded asset rows from one parser-root model.
+     * @param {object} model Parser-root model.
+     * @returns {object[]}
+     */
+    static #assetsForModel(model) {
+        const base = {
+            modelFileName: String(model?.fileName || ''),
+            modelKind: String(model?.kind || '')
+        }
+
+        return [
+            ...EmbeddedAssetReportBuilder.#schematicAssets(base, model),
+            ...EmbeddedAssetReportBuilder.#schematicLibraryAssets(base, model),
+            ...EmbeddedAssetReportBuilder.#pcbAssets(base, model),
+            ...EmbeddedAssetReportBuilder.#pcbLibraryAssets(base, model),
+            ...EmbeddedAssetReportBuilder.#integratedLibraryAssets(base, model)
+        ].filter(Boolean)
+    }
+
+    /**
+     * Collects schematic-document assets.
+     * @param {object} base Shared row fields.
+     * @param {object} model Parser-root model.
+     * @returns {object[]}
+     */
+    static #schematicAssets(base, model) {
+        const schematic = model?.schematic || {}
+
+        return [
+            ...EmbeddedAssetReportBuilder.#collectionAssets(
+                base,
+                'embedded-file',
+                schematic.embeddedFiles?.files || []
+            ),
+            ...EmbeddedAssetReportBuilder.#collectionAssets(
+                base,
+                'schematic-image',
+                schematic.images || [],
+                { fallbackName: 'image' }
+            ),
+            ...EmbeddedAssetReportBuilder.#collectionAssets(
+                base,
+                'schematic-thumbnail',
+                schematic.thumbnails || [],
+                { fallbackName: 'thumbnail' }
+            )
+        ]
+    }
+
+    /**
+     * Collects schematic-library assets.
+     * @param {object} base Shared row fields.
+     * @param {object} model Parser-root model.
+     * @returns {object[]}
+     */
+    static #schematicLibraryAssets(base, model) {
+        const schematicLibrary = model?.schematicLibrary || {}
+        const embeddedFiles = schematicLibrary.embeddedFiles?.files || []
+        const symbolAssets = (schematicLibrary.symbols || []).flatMap(
+            (symbol) =>
+                (symbol.embeddedAssets || []).map((asset) => ({
+                    ...asset,
+                    symbolName: symbol.name
+                }))
+        )
+
+        return EmbeddedAssetReportBuilder.#collectionAssets(
+            base,
+            'embedded-file',
+            embeddedFiles.length ? embeddedFiles : symbolAssets
+        )
+    }
+
+    /**
+     * Collects PCB-document assets.
+     * @param {object} base Shared row fields.
+     * @param {object} model Parser-root model.
+     * @returns {object[]}
+     */
+    static #pcbAssets(base, model) {
+        const pcb = model?.pcb || {}
+
+        return [
+            ...EmbeddedAssetReportBuilder.#collectionAssets(
+                base,
+                'pcb-font',
+                pcb.embeddedFonts || []
+            ),
+            ...EmbeddedAssetReportBuilder.#collectionAssets(
+                base,
+                'pcb-model',
+                pcb.embeddedModels || []
+            )
+        ]
+    }
+
+    /**
+     * Collects PCB-library assets.
+     * @param {object} base Shared row fields.
+     * @param {object} model Parser-root model.
+     * @returns {object[]}
+     */
+    static #pcbLibraryAssets(base, model) {
+        const pcbLibrary = model?.pcbLibrary || {}
+        const footprintModels = (pcbLibrary.footprints || []).flatMap(
+            (footprint) =>
+                (footprint.embeddedModels || []).map((asset) => ({
+                    ...asset,
+                    footprintName: footprint.name
+                }))
+        )
+
+        return [
+            ...EmbeddedAssetReportBuilder.#collectionAssets(
+                base,
+                'pcb-font',
+                pcbLibrary.embeddedFonts || []
+            ),
+            ...EmbeddedAssetReportBuilder.#collectionAssets(
+                base,
+                'pcb-model',
+                pcbLibrary.embeddedModels || []
+            ),
+            ...EmbeddedAssetReportBuilder.#collectionAssets(
+                base,
+                'pcb-model',
+                footprintModels
+            )
+        ]
+    }
+
+    /**
+     * Collects integrated-library source assets.
+     * @param {object} base Shared row fields.
+     * @param {object} model Parser-root model.
+     * @returns {object[]}
+     */
+    static #integratedLibraryAssets(base, model) {
+        return EmbeddedAssetReportBuilder.#collectionAssets(
+            base,
+            'integrated-library-source',
+            model?.integratedLibrary?.sources || []
+        )
+    }
+
+    /**
+     * Normalizes one asset collection.
+     * @param {object} base Shared row fields.
+     * @param {string} kind Asset kind.
+     * @param {object[]} assets Source assets.
+     * @param {{ fallbackName?: string }} options Collection options.
+     * @returns {object[]}
+     */
+    static #collectionAssets(base, kind, assets, options = {}) {
+        return (Array.isArray(assets) ? assets : []).map((asset, index) =>
+            EmbeddedAssetReportBuilder.#assetRow(base, kind, asset, index, {
+                fallbackName: options.fallbackName || kind
+            })
+        )
+    }
+
+    /**
+     * Normalizes one asset row.
+     * @param {object} base Shared row fields.
+     * @param {string} kind Asset kind.
+     * @param {object} asset Source asset.
+     * @param {number} index Collection index.
+     * @param {{ fallbackName: string }} options Row options.
+     * @returns {object}
+     */
+    static #assetRow(base, kind, asset, index, options) {
+        return EmbeddedAssetReportBuilder.#stripUndefined({
+            ...base,
+            kind,
+            name: EmbeddedAssetReportBuilder.#assetName(
+                asset,
+                index,
+                options.fallbackName
+            ),
+            format: EmbeddedAssetReportBuilder.#format(asset),
+            sourceStream: EmbeddedAssetReportBuilder.#sourceStream(asset),
+            byteLength: EmbeddedAssetReportBuilder.#byteLength(asset),
+            symbolName: asset?.symbolName,
+            footprintName: asset?.footprintName
+        })
+    }
+
+    /**
+     * Resolves a stable asset name.
+     * @param {object} asset Source asset.
+     * @param {number} index Collection index.
+     * @param {string} fallbackName Fallback prefix.
+     * @returns {string}
+     */
+    static #assetName(asset, index, fallbackName) {
+        return String(
+            asset?.name ||
+                asset?.family ||
+                asset?.fileName ||
+                asset?.key ||
+                asset?.id ||
+                EmbeddedAssetReportBuilder.#basename(
+                    EmbeddedAssetReportBuilder.#sourceStream(asset)
+                ) ||
+                fallbackName + '-' + index
+        )
+    }
+
+    /**
+     * Resolves a source stream or source path.
+     * @param {object} asset Source asset.
+     * @returns {string}
+     */
+    static #sourceStream(asset) {
+        return String(asset?.sourceStream || asset?.path || asset?.stream || '')
+    }
+
+    /**
+     * Resolves asset byte length.
+     * @param {object} asset Source asset.
+     * @returns {number}
+     */
+    static #byteLength(asset) {
+        const value =
+            asset?.byteLength ??
+            asset?.byteCount ??
+            asset?.payloadByteLength ??
+            asset?.size ??
+            0
+        const numeric = Number(value)
+        return Number.isFinite(numeric) ? numeric : 0
+    }
+
+    /**
+     * Resolves a compact asset format.
+     * @param {object} asset Source asset.
+     * @returns {string}
+     */
+    static #format(asset) {
+        const explicit =
+            asset?.format || asset?.fileType || asset?.type || asset?.mimeType
+        const normalized = String(explicit || '').trim()
+
+        if (!normalized) return 'unknown'
+        if (normalized.includes('/')) {
+            return normalized.split('/').pop()
+        }
+
+        return normalized
+    }
+
+    /**
+     * Builds a sorted count map by asset kind.
+     * @param {object[]} assets Asset rows.
+     * @returns {Record<string, number>}
+     */
+    static #byKind(assets) {
+        const counts = new Map()
+
+        for (const asset of assets) {
+            counts.set(asset.kind, (counts.get(asset.kind) || 0) + 1)
+        }
+
+        return Object.fromEntries(
+            [...counts.entries()].sort(([left], [right]) =>
+                left.localeCompare(right)
+            )
+        )
+    }
+
+    /**
+     * Dedupe exact asset references.
+     * @param {object[]} assets Asset rows.
+     * @returns {object[]}
+     */
+    static #dedupeAssets(assets) {
+        const byKey = new Map()
+
+        for (const asset of assets) {
+            const key = [
+                asset.modelFileName,
+                asset.modelKind,
+                asset.kind,
+                asset.sourceStream,
+                asset.name
+            ].join('\0')
+            if (!byKey.has(key)) {
+                byKey.set(key, asset)
+            }
+        }
+
+        return [...byKey.values()]
+    }
+
+    /**
+     * Sorts report rows deterministically.
+     * @param {object} left Left row.
+     * @param {object} right Right row.
+     * @returns {number}
+     */
+    static #compareAssets(left, right) {
+        return (
+            left.modelFileName.localeCompare(right.modelFileName) ||
+            left.kind.localeCompare(right.kind) ||
+            left.name.localeCompare(right.name) ||
+            left.sourceStream.localeCompare(right.sourceStream)
+        )
+    }
+
+    /**
+     * Resolves a path basename.
+     * @param {string} value Path-like value.
+     * @returns {string}
+     */
+    static #basename(value) {
+        return (
+            String(value || '')
+                .split('/')
+                .filter(Boolean)
+                .pop() || ''
+        )
+    }
+
+    /**
+     * Removes undefined values from a row.
+     * @param {object} row Row to normalize.
+     * @returns {object}
+     */
+    static #stripUndefined(row) {
+        return Object.fromEntries(
+            Object.entries(row).filter(([, value]) => value !== undefined)
+        )
+    }
+}