altium-toolkit 1.0.8 → 1.0.10

package/src/core/altium/LibraryRenderManifestBuilder.mjs

@@ -0,0 +1,417 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds deterministic render/export manifests for read-only library models.
+ */
+export class LibraryRenderManifestBuilder {
+    static #SCHEMA = 'altium-toolkit.library.render-manifest.a1'
+
+    /**
+     * Builds a schematic-symbol library render manifest.
+     * @param {{ symbols?: object[] } | { schematicLibrary?: { symbols?: object[] } }} library Parsed schematic library.
+     * @returns {{ schema: string, libraryKind: string, outputs: object[], embeddedAssets: object[] }}
+     */
+    static buildSchematicLibraryManifest(library) {
+        const schematicLibrary = library?.schematicLibrary || library || {}
+        const symbols = Array.isArray(schematicLibrary.symbols)
+            ? schematicLibrary.symbols
+            : []
+        const outputs = symbols.flatMap((symbol, symbolIndex) =>
+            LibraryRenderManifestBuilder.#schematicSymbolOutputs(
+                symbol,
+                symbolIndex
+            )
+        )
+
+        return {
+            schema: LibraryRenderManifestBuilder.#SCHEMA,
+            libraryKind: 'schematic-symbols',
+            outputs,
+            embeddedAssets: LibraryRenderManifestBuilder.#dedupeEmbeddedAssets(
+                outputs.flatMap((output) => output.embeddedAssets || [])
+            )
+        }
+    }
+
+    /**
+     * Builds a PCB footprint-library render manifest.
+     * @param {{ footprints?: object[], embeddedAssets?: object[] } | { pcbLibrary?: { footprints?: object[], embeddedAssets?: object[] } }} library Parsed PCB library.
+     * @returns {{ schema: string, libraryKind: string, outputs: object[], embeddedAssets: object[] }}
+     */
+    static buildPcbLibraryManifest(library) {
+        const pcbLibrary = library?.pcbLibrary || library || {}
+        const footprints = Array.isArray(pcbLibrary.footprints)
+            ? pcbLibrary.footprints
+            : []
+        const outputs = footprints.map((footprint, footprintIndex) =>
+            LibraryRenderManifestBuilder.#pcbFootprintOutput(
+                footprint,
+                footprintIndex
+            )
+        )
+
+        return {
+            schema: LibraryRenderManifestBuilder.#SCHEMA,
+            libraryKind: 'pcb-footprints',
+            outputs,
+            embeddedAssets: LibraryRenderManifestBuilder.#dedupeEmbeddedAssets([
+                ...(pcbLibrary.embeddedAssets || []),
+                ...outputs.flatMap((output) => output.embeddedAssets || [])
+            ])
+        }
+    }
+
+    /**
+     * Builds a read-only manifest for symbols extractable from placed
+     * schematic components.
+     * @param {{ fileName?: string, schematic?: object } | { schematic?: object }} documentModel Parsed schematic document model.
+     * @returns {{ schema: string, sourceDocument: string, outputs: object[], embeddedAssets: object[] }}
+     */
+    static buildSchematicExtractionManifest(documentModel) {
+        const schematic = documentModel?.schematic || documentModel || {}
+        const components = Array.isArray(schematic.components)
+            ? schematic.components
+            : []
+        const outputs = components.map((component, componentIndex) =>
+            LibraryRenderManifestBuilder.#schematicExtractionOutput(
+                documentModel?.fileName || '',
+                schematic,
+                component,
+                componentIndex
+            )
+        )
+
+        return {
+            schema: 'altium-toolkit.schematic.extraction-manifest.a1',
+            sourceDocument: String(documentModel?.fileName || ''),
+            outputs,
+            embeddedAssets: LibraryRenderManifestBuilder.#dedupeEmbeddedAssets(
+                outputs.flatMap((output) => output.embeddedAssets || [])
+            )
+        }
+    }
+
+    /**
+     * Builds render outputs for one schematic symbol.
+     * @param {object} symbol Symbol record.
+     * @param {number} symbolIndex Symbol index.
+     * @returns {object[]}
+     */
+    static #schematicSymbolOutputs(symbol, symbolIndex) {
+        const symbolKey =
+            'symbol-' +
+            symbolIndex +
+            '-' +
+            LibraryRenderManifestBuilder.#slug(symbol?.name || symbolIndex)
+        const parts =
+            Array.isArray(symbol?.parts) && symbol.parts.length
+                ? symbol.parts
+                : [{ partId: 'default' }]
+        const embeddedAssets =
+            LibraryRenderManifestBuilder.#embeddedAssets(symbol)
+
+        return parts.map((part, partIndex) => {
+            const partId = String(part?.partId || part?.id || partIndex)
+            const partKey =
+                symbolKey +
+                '/part-' +
+                LibraryRenderManifestBuilder.#slug(partId)
+
+            return {
+                kind: 'symbol',
+                symbolKey,
+                name: String(symbol?.name || ''),
+                partKey,
+                partId,
+                outputSvgKey: 'schematic-library/' + partKey + '.svg',
+                embeddedAssets
+            }
+        })
+    }
+
+    /**
+     * Builds one PCB footprint output descriptor.
+     * @param {object} footprint Footprint record.
+     * @param {number} footprintIndex Footprint index.
+     * @returns {object}
+     */
+    static #pcbFootprintOutput(footprint, footprintIndex) {
+        const footprintKey =
+            'footprint-' +
+            footprintIndex +
+            '-' +
+            LibraryRenderManifestBuilder.#slug(
+                footprint?.name || footprintIndex
+            )
+        const layerSvgs = LibraryRenderManifestBuilder.#footprintLayers(
+            footprint
+        ).map((layer) => ({
+            layerKey: layer.layerKey,
+            layerId: layer.layerId,
+            displayName: layer.displayName,
+            outputSvgKey:
+                'pcb-library/' + footprintKey + '/' + layer.layerKey + '.svg'
+        }))
+
+        return {
+            kind: 'footprint',
+            footprintKey,
+            name: String(footprint?.name || ''),
+            sourceStorage: String(footprint?.sourceStorage || ''),
+            outputSvgKey: 'pcb-library/' + footprintKey + '.svg',
+            layerSvgs,
+            embeddedAssets:
+                LibraryRenderManifestBuilder.#embeddedAssets(footprint)
+        }
+    }
+
+    /**
+     * Builds one placed-component extraction output.
+     * @param {string} sourceDocument Source document name.
+     * @param {object} schematic Schematic model.
+     * @param {object} component Component row.
+     * @param {number} componentIndex Component index.
+     * @returns {object}
+     */
+    static #schematicExtractionOutput(
+        sourceDocument,
+        schematic,
+        component,
+        componentIndex
+    ) {
+        const symbolName =
+            component?.libReference || component?.designator || ''
+        const symbolKey =
+            'symbol-extract-' +
+            componentIndex +
+            '-' +
+            LibraryRenderManifestBuilder.#slug(symbolName || componentIndex)
+        const ownerIndex = String(component?.ownerIndex || '').trim()
+        const children = LibraryRenderManifestBuilder.#schematicOwnerChildren(
+            schematic,
+            ownerIndex
+        )
+        const embeddedAssets =
+            LibraryRenderManifestBuilder.#dedupeEmbeddedAssets(
+                children.images.map((image, index) =>
+                    LibraryRenderManifestBuilder.#imageAssetDescriptor(
+                        image,
+                        'symbol-image-' + index
+                    )
+                )
+            )
+
+        return {
+            kind: 'symbol-extraction',
+            symbolKey,
+            sourceComponent: LibraryRenderManifestBuilder.#stripUndefined({
+                designator: component?.designator,
+                libReference: component?.libReference,
+                uniqueId: component?.uniqueId,
+                ownerIndex
+            }),
+            outputLibraryKey: 'schematic-extract/' + symbolKey + '.SchLib',
+            renderManifestKey:
+                'schematic-extract/' + symbolKey + '.render.json',
+            partKeys: [symbolKey + '/part-default'],
+            childCounts: {
+                pins: children.pins.length,
+                graphics: children.graphics.length,
+                texts: children.texts.length,
+                images: children.images.length
+            },
+            embeddedAssets
+        }
+    }
+
+    /**
+     * Collects schematic primitives owned by one component owner index.
+     * @param {object} schematic Schematic model.
+     * @param {string} ownerIndex Owner index.
+     * @returns {{ pins: object[], graphics: object[], texts: object[], images: object[] }}
+     */
+    static #schematicOwnerChildren(schematic, ownerIndex) {
+        const ownerMatches = (item) =>
+            ownerIndex && String(item?.ownerIndex || '').trim() === ownerIndex
+        const graphics = [
+            ...(schematic?.lines || []),
+            ...(schematic?.polygons || []),
+            ...(schematic?.rectangles || []),
+            ...(schematic?.ellipses || []),
+            ...(schematic?.arcs || []),
+            ...(schematic?.beziers || []),
+            ...(schematic?.pies || []),
+            ...(schematic?.regions || [])
+        ].filter(ownerMatches)
+
+        return {
+            pins: (schematic?.pins || []).filter(ownerMatches),
+            graphics,
+            texts: (schematic?.texts || []).filter(ownerMatches),
+            images: (schematic?.images || []).filter(ownerMatches)
+        }
+    }
+
+    /**
+     * Collects layer descriptors touched by one footprint.
+     * @param {object} footprint Footprint record.
+     * @returns {{ layerKey: string, layerId?: number, displayName: string }[]}
+     */
+    static #footprintLayers(footprint) {
+        const layerMap = new Map()
+        const primitiveFamilies = [
+            'pads',
+            'tracks',
+            'arcs',
+            'vias',
+            'fills',
+            'texts',
+            'regions',
+            'shapeBasedRegions'
+        ]
+
+        for (const family of primitiveFamilies) {
+            for (const primitive of footprint?.[family] || []) {
+                const layer =
+                    LibraryRenderManifestBuilder.#layerDescriptor(primitive)
+                if (layer) {
+                    layerMap.set(layer.layerKey, layer)
+                }
+            }
+        }
+
+        return [...layerMap.values()].sort((left, right) =>
+            left.layerKey.localeCompare(right.layerKey)
+        )
+    }
+
+    /**
+     * Builds a normalized layer descriptor for one primitive.
+     * @param {object} primitive Primitive record.
+     * @returns {{ layerKey: string, layerId?: number, displayName: string } | null}
+     */
+    static #layerDescriptor(primitive) {
+        const layerId = Number.isInteger(primitive?.layerId)
+            ? primitive.layerId
+            : null
+        const layerName = String(
+            primitive?.layerName || primitive?.layer || ''
+        ).trim()
+
+        if (layerId === null && !layerName) {
+            return null
+        }
+
+        const layerKey =
+            layerId === null
+                ? 'layer-' + LibraryRenderManifestBuilder.#slug(layerName)
+                : 'L' + layerId
+
+        return {
+            layerKey,
+            ...(layerId === null ? {} : { layerId }),
+            displayName: layerName || layerKey
+        }
+    }
+
+    /**
+     * Collects embedded assets from a library item.
+     * @param {object} item Library item.
+     * @returns {object[]}
+     */
+    static #embeddedAssets(item) {
+        return [
+            ...(Array.isArray(item?.embeddedAssets) ? item.embeddedAssets : []),
+            ...(Array.isArray(item?.embeddedModels)
+                ? item.embeddedModels.map((model, index) => ({
+                      key: model.key || model.id || 'model-' + index,
+                      format: model.format,
+                      sourceStream: model.sourceStream,
+                      name: model.name
+                  }))
+                : []),
+            ...(Array.isArray(item?.embeddedFonts)
+                ? item.embeddedFonts.map((font, index) => ({
+                      key: font.key || font.name || 'font-' + index,
+                      format: 'font',
+                      sourceStream: font.sourceStream,
+                      name: font.name
+                  }))
+                : [])
+        ].map((asset) =>
+            LibraryRenderManifestBuilder.#stripUndefined(asset || {})
+        )
+    }
+
+    /**
+     * Builds an asset descriptor for a schematic image payload.
+     * @param {object} image Schematic image record.
+     * @param {string} fallbackKey Fallback asset key.
+     * @returns {object}
+     */
+    static #imageAssetDescriptor(image, fallbackKey) {
+        return LibraryRenderManifestBuilder.#stripUndefined({
+            key: image?.key || image?.id || fallbackKey,
+            format: image?.format,
+            nativeFormat: image?.nativeFormat,
+            wrapperType: image?.wrapperType,
+            byteSize: image?.byteSize,
+            checksum: image?.checksum,
+            sourceStream: image?.sourceStream,
+            name: image?.name,
+            diagnostics: image?.diagnostics
+        })
+    }
+
+    /**
+     * Deduplicates embedded asset descriptors.
+     * @param {object[]} assets Asset descriptors.
+     * @returns {object[]}
+     */
+    static #dedupeEmbeddedAssets(assets) {
+        const seen = new Set()
+        const deduped = []
+
+        for (const asset of assets || []) {
+            const key = JSON.stringify(asset)
+            if (seen.has(key)) {
+                continue
+            }
+
+            seen.add(key)
+            deduped.push(asset)
+        }
+
+        return deduped
+    }
+
+    /**
+     * Removes undefined values from one object.
+     * @param {object} value Source object.
+     * @returns {object}
+     */
+    static #stripUndefined(value) {
+        return Object.fromEntries(
+            Object.entries(value).filter(
+                ([, entryValue]) => entryValue !== undefined
+            )
+        )
+    }
+
+    /**
+     * Converts a display 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'
+        )
+    }
+}

package/src/core/altium/LibrarySearchIndex.mjs

@@ -0,0 +1,215 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Provides exact and lightweight fuzzy lookups over parsed library read models.
+ */
+export class LibrarySearchIndex {
+    /**
+     * Searches PCB footprint records.
+     * @param {{ footprints?: object[] } | { pcbLibrary?: { footprints?: object[] } }} library Parsed PCB library.
+     * @param {string} query Search query.
+     * @param {{ limit?: number }} options Search options.
+     * @returns {{ query: string, matches: object[] }}
+     */
+    static searchPcbFootprints(library, query, options = {}) {
+        const pcbLibrary = library?.pcbLibrary || library || {}
+        const footprints = Array.isArray(pcbLibrary.footprints)
+            ? pcbLibrary.footprints
+            : []
+
+        return LibrarySearchIndex.#searchCollection(
+            'footprint',
+            footprints,
+            query,
+            options
+        )
+    }
+
+    /**
+     * Searches schematic symbol records.
+     * @param {{ symbols?: object[] } | { schematicLibrary?: { symbols?: object[] } }} library Parsed schematic library.
+     * @param {string} query Search query.
+     * @param {{ limit?: number }} options Search options.
+     * @returns {{ query: string, matches: object[] }}
+     */
+    static searchSchematicSymbols(library, query, options = {}) {
+        const schematicLibrary = library?.schematicLibrary || library || {}
+        const symbols = Array.isArray(schematicLibrary.symbols)
+            ? schematicLibrary.symbols
+            : []
+
+        return LibrarySearchIndex.#searchCollection(
+            'symbol',
+            symbols,
+            query,
+            options
+        )
+    }
+
+    /**
+     * Searches one library collection.
+     * @param {string} kind Public item kind.
+     * @param {object[]} items Library items.
+     * @param {string} query Search query.
+     * @param {{ limit?: number }} options Search options.
+     * @returns {{ query: string, matches: object[] }}
+     */
+    static #searchCollection(kind, items, query, options) {
+        const normalizedQuery = LibrarySearchIndex.#normalize(query)
+        const limit = Math.max(Number(options.limit || 25), 1)
+        const matches = (items || [])
+            .map((item, index) =>
+                LibrarySearchIndex.#scoreItem(
+                    kind,
+                    item,
+                    index,
+                    normalizedQuery
+                )
+            )
+            .filter(Boolean)
+            .sort(
+                (left, right) =>
+                    left.score - right.score ||
+                    left.name.localeCompare(right.name)
+            )
+            .slice(0, limit)
+
+        return {
+            query: String(query || ''),
+            matches
+        }
+    }
+
+    /**
+     * Scores one candidate library item.
+     * @param {string} kind Public item kind.
+     * @param {object} item Library item.
+     * @param {number} index Source index.
+     * @param {string} normalizedQuery Normalized query.
+     * @returns {object | null}
+     */
+    static #scoreItem(kind, item, index, normalizedQuery) {
+        if (!normalizedQuery) {
+            return null
+        }
+
+        const name = String(item?.name || item?.libReference || '')
+        const normalizedName = LibrarySearchIndex.#normalize(name)
+        const keywords = LibrarySearchIndex.#keywords(item)
+        const match = LibrarySearchIndex.#match(
+            normalizedQuery,
+            normalizedName,
+            keywords
+        )
+
+        if (!match) {
+            return null
+        }
+
+        return {
+            kind,
+            name,
+            index,
+            score: match.score,
+            matchKind: match.matchKind,
+            keywords
+        }
+    }
+
+    /**
+     * Matches a normalized query against name and keywords.
+     * @param {string} query Normalized query.
+     * @param {string} name Normalized name.
+     * @param {string[]} keywords Keyword list.
+     * @returns {{ score: number, matchKind: string } | null}
+     */
+    static #match(query, name, keywords) {
+        const normalizedKeywords = keywords.map((keyword) =>
+            LibrarySearchIndex.#normalize(keyword)
+        )
+        const compactQuery = LibrarySearchIndex.#compact(query)
+        const compactName = LibrarySearchIndex.#compact(name)
+
+        if (name === query) {
+            return { score: 0, matchKind: 'exact' }
+        }
+        if (name.startsWith(query)) {
+            return { score: 10, matchKind: 'prefix' }
+        }
+        if (name.includes(query)) {
+            return { score: 20, matchKind: 'substring' }
+        }
+        if (normalizedKeywords.some((keyword) => keyword.includes(query))) {
+            return { score: 30, matchKind: 'keyword' }
+        }
+        if (
+            compactName.includes(compactQuery) ||
+            LibrarySearchIndex.#isOrderedSubsequence(compactQuery, compactName)
+        ) {
+            return { score: 40, matchKind: 'fuzzy' }
+        }
+
+        return null
+    }
+
+    /**
+     * Builds keywords from item metadata.
+     * @param {object} item Library item.
+     * @returns {string[]}
+     */
+    static #keywords(item) {
+        return [
+            item?.name,
+            item?.dataName,
+            item?.sourceStorage,
+            ...Object.values(item?.parameters || {}),
+            ...Object.values(item?.componentParams || {}),
+            ...Object.values(item?.componentParams?.properties || {})
+        ]
+            .map((value) => String(value || '').trim())
+            .filter(Boolean)
+    }
+
+    /**
+     * Returns true when all query chars appear in order in the candidate.
+     * @param {string} query Normalized compact query.
+     * @param {string} candidate Normalized compact candidate.
+     * @returns {boolean}
+     */
+    static #isOrderedSubsequence(query, candidate) {
+        let cursor = 0
+
+        for (const char of candidate) {
+            if (char === query[cursor]) {
+                cursor += 1
+            }
+            if (cursor === query.length) {
+                return true
+            }
+        }
+
+        return false
+    }
+
+    /**
+     * Normalizes text for case-insensitive lookup.
+     * @param {unknown} value Source value.
+     * @returns {string}
+     */
+    static #normalize(value) {
+        return String(value || '')
+            .trim()
+            .toLowerCase()
+    }
+
+    /**
+     * Removes separators for fuzzy package-name matching.
+     * @param {string} value Normalized value.
+     * @returns {string}
+     */
+    static #compact(value) {
+        return String(value || '').replace(/[^a-z0-9]+/gu, '')
+    }
+}

package/src/core/altium/NormalizedModelSchema.mjs

@@ -22,7 +22,43 @@ export class NormalizedModelSchema {
             ...model
         }
         normalizedModel.schema = NormalizedModelSchema.CURRENT_SCHEMA_ID
+        if (Array.isArray(normalizedModel.diagnostics)) {
+            normalizedModel.diagnostics =
+                NormalizedModelSchema.#normalizeDiagnostics(
+                    normalizedModel.diagnostics
+                )
+        }
 
         return normalizedModel
     }
+
+    /**
+     * Adds machine-readable codes to parser diagnostics.
+     * @param {object[]} diagnostics Parser diagnostics.
+     * @returns {object[]}
+     */
+    static #normalizeDiagnostics(diagnostics) {
+        return diagnostics.map((diagnostic) => ({
+            code:
+                typeof diagnostic?.code === 'string' && diagnostic.code
+                    ? diagnostic.code
+                    : NormalizedModelSchema.#deriveDiagnosticCode(diagnostic),
+            ...diagnostic
+        }))
+    }
+
+    /**
+     * Derives a stable fallback code from one diagnostic message.
+     * @param {object} diagnostic Parser diagnostic.
+     * @returns {string}
+     */
+    static #deriveDiagnosticCode(diagnostic) {
+        const slug = String(diagnostic?.message || 'diagnostic')
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/gu, '.')
+            .replace(/^\.+|\.+$/gu, '')
+            .slice(0, 80)
+
+        return 'parser.' + (slug || 'diagnostic')
+    }
 }