altium-toolkit 1.1.22 → 1.1.23

package/src/core/altium/LibraryCatalogArtifactBuilder.mjs

@@ -0,0 +1,296 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { LibraryQaReportBuilder } from './LibraryQaReportBuilder.mjs'
+import { LibraryRenderManifestBuilder } from './LibraryRenderManifestBuilder.mjs'
+
+/**
+ * Builds deterministic static catalog artifacts for parsed libraries.
+ */
+export class LibraryCatalogArtifactBuilder {
+    static SCHEMA_ID = 'altium-toolkit.library.catalog.a1'
+
+    /**
+     * Builds catalog entries, search metadata, and static HTML.
+     * @param {{ schematicLibraries?: object[], pcbLibraries?: object[], qaReport?: object }} [options] Catalog options.
+     * @returns {object}
+     */
+    static build(options = {}) {
+        const schematicLibraries = options.schematicLibraries || []
+        const pcbLibraries = options.pcbLibraries || []
+        const qaReport =
+            options.qaReport ||
+            LibraryQaReportBuilder.build({ schematicLibraries, pcbLibraries })
+        const issuesByTarget =
+            LibraryCatalogArtifactBuilder.#issuesByTarget(qaReport)
+        const entries = [
+            ...LibraryCatalogArtifactBuilder.#symbolEntries(
+                schematicLibraries,
+                issuesByTarget
+            ),
+            ...LibraryCatalogArtifactBuilder.#footprintEntries(
+                pcbLibraries,
+                issuesByTarget
+            )
+        ].sort(
+            (left, right) =>
+                left.kind.localeCompare(right.kind) ||
+                left.name.localeCompare(right.name) ||
+                left.libraryFileName.localeCompare(right.libraryFileName)
+        )
+        const searchIndex = {
+            schema: 'altium-toolkit.library.catalog-search.a1',
+            entries: entries.map((entry) => ({
+                key: entry.key,
+                kind: entry.kind,
+                name: entry.name,
+                libraryFileName: entry.libraryFileName,
+                text: entry.searchText
+            }))
+        }
+
+        return {
+            schema: LibraryCatalogArtifactBuilder.SCHEMA_ID,
+            summary: {
+                schematicLibraryCount: schematicLibraries.length,
+                pcbLibraryCount: pcbLibraries.length,
+                entryCount: entries.length,
+                symbolCount: entries.filter((entry) => entry.kind === 'symbol')
+                    .length,
+                footprintCount: entries.filter(
+                    (entry) => entry.kind === 'footprint'
+                ).length,
+                issueCount: entries.reduce(
+                    (count, entry) => count + entry.issueCodes.length,
+                    0
+                )
+            },
+            entries,
+            searchIndex,
+            html: LibraryCatalogArtifactBuilder.#html(entries)
+        }
+    }
+
+    /**
+     * Builds catalog entries for schematic symbols.
+     * @param {object[]} schematicLibraries Schematic libraries.
+     * @param {Map<string, object[]>} issuesByTarget Issues by target.
+     * @returns {object[]}
+     */
+    static #symbolEntries(schematicLibraries, issuesByTarget) {
+        return (schematicLibraries || []).flatMap((library) => {
+            const schematicLibrary = library.schematicLibrary || library || {}
+            const manifest =
+                LibraryRenderManifestBuilder.buildSchematicLibraryManifest(
+                    schematicLibrary
+                )
+
+            return (schematicLibrary.symbols || []).map(
+                (symbol, symbolIndex) => {
+                    const name = String(symbol.name || '').trim()
+                    const output = manifest.outputs.find(
+                        (entry) => entry.name === name
+                    )
+                    const issues =
+                        issuesByTarget.get('symbol:' + name) ||
+                        issuesByTarget.get(name) ||
+                        []
+
+                    return LibraryCatalogArtifactBuilder.#stripUndefined({
+                        key: 'symbol:' + (library.fileName || '') + ':' + name,
+                        kind: 'symbol',
+                        name,
+                        libraryFileName: library.fileName || '',
+                        index: symbolIndex,
+                        pinCount: (symbol.pins || []).length,
+                        partCount: (symbol.parts || []).length,
+                        outputSvgKey: output?.outputSvgKey,
+                        issueCodes: issues.map((issue) => issue.code),
+                        issues,
+                        searchText: [
+                            name,
+                            library.fileName || '',
+                            'symbol',
+                            symbol.parameters?.Description || '',
+                            'pins:' + (symbol.pins || []).length
+                        ]
+                            .filter(Boolean)
+                            .join(' ')
+                    })
+                }
+            )
+        })
+    }
+
+    /**
+     * Builds catalog entries for PCB footprints.
+     * @param {object[]} pcbLibraries PCB footprint libraries.
+     * @param {Map<string, object[]>} issuesByTarget Issues by target.
+     * @returns {object[]}
+     */
+    static #footprintEntries(pcbLibraries, issuesByTarget) {
+        return (pcbLibraries || []).flatMap((library) => {
+            const pcbLibrary = library.pcbLibrary || library || {}
+            const manifest =
+                LibraryRenderManifestBuilder.buildPcbLibraryManifest(pcbLibrary)
+
+            return (pcbLibrary.footprints || []).map(
+                (footprint, footprintIndex) => {
+                    const name = String(footprint.name || '').trim()
+                    const output = manifest.outputs.find(
+                        (entry) => entry.name === name
+                    )
+                    const issues =
+                        issuesByTarget.get('footprint:' + name) ||
+                        issuesByTarget.get(name) ||
+                        []
+
+                    return LibraryCatalogArtifactBuilder.#stripUndefined({
+                        key:
+                            'footprint:' +
+                            (library.fileName || '') +
+                            ':' +
+                            name,
+                        kind: 'footprint',
+                        name,
+                        libraryFileName: library.fileName || '',
+                        index: footprintIndex,
+                        primitiveCount:
+                            (footprint.pads || []).length +
+                            (footprint.tracks || []).length +
+                            (footprint.arcs || []).length +
+                            (footprint.vias || []).length +
+                            (footprint.fills || []).length +
+                            (footprint.regions || []).length,
+                        rawRecordCount: (footprint.rawRecords || []).length,
+                        outputSvgKey: output?.outputSvgKey,
+                        issueCodes: issues.map((issue) => issue.code),
+                        issues,
+                        searchText: [
+                            name,
+                            library.fileName || '',
+                            'footprint',
+                            'pads:' + (footprint.pads || []).length
+                        ]
+                            .filter(Boolean)
+                            .join(' ')
+                    })
+                }
+            )
+        })
+    }
+
+    /**
+     * Builds a target-key lookup for QA issues.
+     * @param {object} qaReport QA report.
+     * @returns {Map<string, object[]>}
+     */
+    static #issuesByTarget(qaReport) {
+        const byTarget = new Map()
+        const issues = [
+            ...(qaReport?.libraryLint?.issues || []),
+            ...(qaReport?.issues || [])
+        ]
+
+        for (const issue of issues) {
+            const keys = new Set([
+                issue.target,
+                issue.symbolName ? 'symbol:' + issue.symbolName : '',
+                issue.footprintName ? 'footprint:' + issue.footprintName : ''
+            ])
+
+            for (const key of keys) {
+                if (!key) continue
+                byTarget.set(key, [...(byTarget.get(key) || []), issue])
+            }
+        }
+
+        return byTarget
+    }
+
+    /**
+     * Builds a self-contained static HTML catalog.
+     * @param {object[]} entries Catalog entries.
+     * @returns {string}
+     */
+    static #html(entries) {
+        const items = entries
+            .map((entry) => {
+                const badges = entry.issueCodes
+                    .map(
+                        (code) =>
+                            '<span class="badge">' +
+                            LibraryCatalogArtifactBuilder.#escapeHtml(code) +
+                            '</span>'
+                    )
+                    .join('')
+
+                return (
+                    '<article data-catalog-entry="' +
+                    LibraryCatalogArtifactBuilder.#escapeHtml(entry.kind) +
+                    '">' +
+                    '<h2>' +
+                    LibraryCatalogArtifactBuilder.#escapeHtml(entry.name) +
+                    '</h2>' +
+                    '<p>' +
+                    LibraryCatalogArtifactBuilder.#escapeHtml(
+                        entry.libraryFileName
+                    ) +
+                    '</p>' +
+                    '<p data-preview-key="' +
+                    LibraryCatalogArtifactBuilder.#escapeHtml(
+                        entry.outputSvgKey || ''
+                    ) +
+                    '">' +
+                    LibraryCatalogArtifactBuilder.#escapeHtml(
+                        entry.outputSvgKey || ''
+                    ) +
+                    '</p>' +
+                    '<div class="badges">' +
+                    badges +
+                    '</div>' +
+                    '</article>'
+                )
+            })
+            .join('')
+
+        return (
+            '<!doctype html><html><head><meta charset="utf-8">' +
+            '<title>Library Catalog</title>' +
+            '<style>body{font-family:sans-serif;margin:24px}' +
+            'main{display:grid;gap:12px}' +
+            'article{border:1px solid #d0d7de;border-radius:6px;padding:12px}' +
+            '.badge{display:inline-block;margin:4px 4px 0 0;padding:2px 6px;' +
+            'border:1px solid #d0d7de;border-radius:999px;font-size:12px}' +
+            '</style></head><body><main data-library-catalog>' +
+            items +
+            '</main></body></html>'
+        )
+    }
+
+    /**
+     * Escapes text for HTML output.
+     * @param {unknown} value Source value.
+     * @returns {string}
+     */
+    static #escapeHtml(value) {
+        return String(value ?? '')
+            .replace(/&/gu, '&amp;')
+            .replace(/</gu, '&lt;')
+            .replace(/>/gu, '&gt;')
+            .replace(/"/gu, '&quot;')
+            .replace(/'/gu, '&#39;')
+    }
+
+    /**
+     * Removes undefined fields.
+     * @param {object} row Source row.
+     * @returns {object}
+     */
+    static #stripUndefined(row) {
+        return Object.fromEntries(
+            Object.entries(row).filter(([, value]) => value !== undefined)
+        )
+    }
+}

package/src/core/altium/LibraryDiffReportBuilder.mjs

@@ -0,0 +1,260 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds deterministic read-only diffs between parsed library models.
+ */
+export class LibraryDiffReportBuilder {
+    static SCHEMA = 'altium-toolkit.library.diff.a1'
+
+    /**
+     * Builds a library diff report.
+     * @param {{ left?: object[] | object, right?: object[] | object }} input Diff input.
+     * @returns {object}
+     */
+    static build(input = {}) {
+        const leftLibraries = LibraryDiffReportBuilder.#libraries(input.left)
+        const rightLibraries = LibraryDiffReportBuilder.#libraries(input.right)
+        const symbols = LibraryDiffReportBuilder.#diffCollection(
+            LibraryDiffReportBuilder.#symbolRows(leftLibraries),
+            LibraryDiffReportBuilder.#symbolRows(rightLibraries),
+            'symbol'
+        )
+        const footprints = LibraryDiffReportBuilder.#diffCollection(
+            LibraryDiffReportBuilder.#footprintRows(leftLibraries),
+            LibraryDiffReportBuilder.#footprintRows(rightLibraries),
+            'footprint'
+        )
+
+        return {
+            schema: LibraryDiffReportBuilder.SCHEMA,
+            summary: {
+                leftLibraryCount: leftLibraries.length,
+                rightLibraryCount: rightLibraries.length,
+                addedSymbolCount: symbols.added.length,
+                removedSymbolCount: symbols.removed.length,
+                changedSymbolCount: symbols.changed.length,
+                addedFootprintCount: footprints.added.length,
+                removedFootprintCount: footprints.removed.length,
+                changedFootprintCount: footprints.changed.length,
+                differenceCount:
+                    symbols.added.length +
+                    symbols.removed.length +
+                    symbols.changed.length +
+                    footprints.added.length +
+                    footprints.removed.length +
+                    footprints.changed.length
+            },
+            symbols,
+            footprints
+        }
+    }
+
+    /**
+     * Normalizes library input to an array.
+     * @param {object[] | object | undefined} value Input value.
+     * @returns {object[]}
+     */
+    static #libraries(value) {
+        if (!value) return []
+        return Array.isArray(value) ? value : [value]
+    }
+
+    /**
+     * Collects schematic symbol comparison rows.
+     * @param {object[]} libraries Library models.
+     * @returns {object[]}
+     */
+    static #symbolRows(libraries) {
+        return (libraries || []).flatMap((library) =>
+            (library.schematicLibrary?.symbols || []).map((symbol, index) => ({
+                name: String(symbol.name || ''),
+                libraryFileName: library.fileName || '',
+                index,
+                pinCount: (symbol.pins || []).length,
+                partCount: (symbol.parts || []).length,
+                parameters: symbol.parameters || {}
+            }))
+        )
+    }
+
+    /**
+     * Collects PCB footprint comparison rows.
+     * @param {object[]} libraries Library models.
+     * @returns {object[]}
+     */
+    static #footprintRows(libraries) {
+        return (libraries || []).flatMap((library) =>
+            (library.pcbLibrary?.footprints || []).map((footprint, index) => ({
+                name: String(footprint.name || ''),
+                libraryFileName: library.fileName || '',
+                index,
+                padCount: (footprint.pads || []).length,
+                textCount: (footprint.texts || []).length,
+                parameters: footprint.parameters || {}
+            }))
+        )
+    }
+
+    /**
+     * Diffs one named library item collection.
+     * @param {object[]} leftRows Left rows.
+     * @param {object[]} rightRows Right rows.
+     * @param {'symbol' | 'footprint'} kind Collection kind.
+     * @returns {{ added: object[], removed: object[], changed: object[] }}
+     */
+    static #diffCollection(leftRows, rightRows, kind) {
+        const leftByName = LibraryDiffReportBuilder.#byName(leftRows)
+        const rightByName = LibraryDiffReportBuilder.#byName(rightRows)
+        const names = [
+            ...new Set([...leftByName.keys(), ...rightByName.keys()])
+        ]
+            .filter(Boolean)
+            .sort((left, right) => left.localeCompare(right))
+        const added = []
+        const removed = []
+        const changed = []
+
+        for (const name of names) {
+            const left = leftByName.get(name)
+            const right = rightByName.get(name)
+
+            if (!left && right) {
+                added.push(
+                    LibraryDiffReportBuilder.#publicRow(right, kind, {
+                        includeName: true
+                    })
+                )
+                continue
+            }
+
+            if (left && !right) {
+                removed.push(
+                    LibraryDiffReportBuilder.#publicRow(left, kind, {
+                        includeName: true
+                    })
+                )
+                continue
+            }
+
+            const differences = LibraryDiffReportBuilder.#differences(
+                left,
+                right,
+                kind
+            )
+            if (Object.keys(differences).length) {
+                changed.push({
+                    name,
+                    left: LibraryDiffReportBuilder.#publicRow(left, kind),
+                    right: LibraryDiffReportBuilder.#publicRow(right, kind),
+                    differences
+                })
+            }
+        }
+
+        return { added, removed, changed }
+    }
+
+    /**
+     * Indexes rows by name.
+     * @param {object[]} rows Rows.
+     * @returns {Map<string, object>}
+     */
+    static #byName(rows) {
+        return new Map(
+            (rows || []).filter((row) => row.name).map((row) => [row.name, row])
+        )
+    }
+
+    /**
+     * Builds public row shape without private comparison-only data.
+     * @param {object} row Source row.
+     * @param {'symbol' | 'footprint'} kind Collection kind.
+     * @param {{ includeName?: boolean }} options Row options.
+     * @returns {object}
+     */
+    static #publicRow(row, kind, options = {}) {
+        const base = {
+            libraryFileName: row.libraryFileName,
+            index: row.index
+        }
+        if (options.includeName) {
+            base.name = row.name
+        }
+
+        if (kind === 'symbol') {
+            return {
+                ...base,
+                pinCount: row.pinCount,
+                partCount: row.partCount
+            }
+        }
+
+        return {
+            ...base,
+            padCount: row.padCount,
+            textCount: row.textCount
+        }
+    }
+
+    /**
+     * Builds differences between two matching rows.
+     * @param {object} left Left row.
+     * @param {object} right Right row.
+     * @param {'symbol' | 'footprint'} kind Collection kind.
+     * @returns {object}
+     */
+    static #differences(left, right, kind) {
+        const differences = {}
+
+        for (const key of kind === 'symbol'
+            ? ['pinCount', 'partCount']
+            : ['padCount', 'textCount']) {
+            if (left[key] !== right[key]) {
+                differences[key] = { left: left[key], right: right[key] }
+            }
+        }
+
+        const parameterDifferences =
+            LibraryDiffReportBuilder.#parameterDifferences(
+                left.parameters,
+                right.parameters
+            )
+        if (Object.keys(parameterDifferences).length) {
+            differences.parameters = parameterDifferences
+        }
+
+        return differences
+    }
+
+    /**
+     * Builds per-parameter value differences.
+     * @param {Record<string, string>} left Left parameters.
+     * @param {Record<string, string>} right Right parameters.
+     * @returns {object}
+     */
+    static #parameterDifferences(left, right) {
+        const differences = {}
+        const keys = [
+            ...new Set([
+                ...Object.keys(left || {}),
+                ...Object.keys(right || {})
+            ])
+        ].sort((leftKey, rightKey) => leftKey.localeCompare(rightKey))
+
+        for (const key of keys) {
+            const leftValue = String(left?.[key] ?? '')
+            const rightValue = String(right?.[key] ?? '')
+
+            if (leftValue !== rightValue) {
+                differences[key] = {
+                    left: leftValue,
+                    right: rightValue
+                }
+            }
+        }
+
+        return differences
+    }
+}