altium-toolkit 1.0.8 → 1.0.10

package/src/core/altium/SchematicTextParser.mjs

@@ -57,6 +57,39 @@ export class SchematicTextParser {
         return fonts
     }
 
+    /**
+     * Extracts deterministic render diagnostics for schematic sheet fonts.
+     * @param {Record<string, string | string[]> | undefined} fields
+     * @returns {{ schema: string, fontFallbacks: object[] }}
+     */
+    static extractSchematicFontDiagnostics(fields) {
+        const count = ParserUtils.parseNumericField(fields, 'FontIdCount') || 0
+        const fontFallbacks = []
+
+        for (let index = 1; index <= count; index += 1) {
+            const rawFamily = ParserUtils.getField(fields, 'FontName' + index)
+            if (!SchematicTextParser.#needsFontFamilyFallback(rawFamily)) {
+                continue
+            }
+
+            fontFallbacks.push({
+                code: 'schematic.font.family-fallback',
+                severity: 'warning',
+                fontId: String(index),
+                sourceFamily: rawFamily,
+                resolvedFamily:
+                    SchematicTextParser.#sanitizeFontFamily(rawFamily),
+                message:
+                    'Schematic font family was missing or malformed and was replaced for deterministic SVG rendering.'
+            })
+        }
+
+        return {
+            schema: 'altium-toolkit.schematic.render-diagnostics.a1',
+            fontFallbacks
+        }
+    }
+
     /**
      * Normalizes one schematic text record into a drawable text node.
      * @param {Record<string, string | string[]>} fields
@@ -119,6 +152,8 @@ export class SchematicTextParser {
             ownerIndex: ParserUtils.getField(fields, 'OwnerIndex') || undefined,
             recordType,
             style: ParserUtils.parseNumericField(fields, 'Style') || 0,
+            renderOrder:
+                ParserUtils.parseNumericField(fields, 'IndexInSheet') ?? 0,
             fontSize: SchematicTextParser.#toSvgFontSize(font.size),
             fontFamily: font.family,
             fontWeight: font.bold ? 700 : 400,
@@ -152,6 +187,19 @@ export class SchematicTextParser {
         return textRecord
     }
 
+    /**
+     * Builds a normalized text-frame read model from visible text records.
+     * @param {object[]} texts Normalized schematic text records.
+     * @returns {object[]}
+     */
+    static extractSchematicTextFrames(texts) {
+        return (texts || [])
+            .filter((text) => text?.recordType === '28')
+            .map((text) =>
+                SchematicTextParser.#normalizeTextFrameContract(text)
+            )
+    }
+
     /**
      * Extracts footer metadata used for the synthesized title block.
      * @param {{ fields: Record<string, string | string[]> }[]} records
@@ -623,6 +671,17 @@ export class SchematicTextParser {
         return normalized
     }
 
+    /**
+     * Returns true when the font family must be replaced for SVG output.
+     * @param {string} family Raw font family value.
+     * @returns {boolean}
+     */
+    static #needsFontFamilyFallback(family) {
+        const normalized = String(family || '').trim()
+
+        return !normalized || /["|]/.test(normalized)
+    }
+
     /**
      * Returns the default schematic font when no sheet font entry exists.
      * @returns {{ size: number, family: string, bold: boolean, italic: boolean, rotation: number }}
@@ -697,6 +756,8 @@ export class SchematicTextParser {
                 fields.Color || fields.TextColor,
                 '#7b7753'
             ),
+            lineWidth:
+                ParserUtils.parseNumericField(fields, 'LineWidth') ?? undefined,
             isSolid: ParserUtils.parseBoolean(fields.IsSolid),
             showBorder: ParserUtils.parseBoolean(fields.ShowBorder),
             textMargin:
@@ -705,6 +766,68 @@ export class SchematicTextParser {
         }
     }
 
+    /**
+     * Converts one rendered text-frame record into an explicit read model.
+     * @param {object} text Normalized text-frame text record.
+     * @returns {object}
+     */
+    static #normalizeTextFrameContract(text) {
+        const left = Math.min(Number(text.x || 0), Number(text.cornerX || 0))
+        const right = Math.max(Number(text.x || 0), Number(text.cornerX || 0))
+        const top = Math.max(Number(text.y || 0), Number(text.cornerY || 0))
+        const bottom = Math.min(Number(text.y || 0), Number(text.cornerY || 0))
+
+        return SchematicTextParser.#stripUndefined({
+            x: text.x,
+            y: text.y,
+            cornerX: text.cornerX,
+            cornerY: text.cornerY,
+            width: right - left,
+            height: top - bottom,
+            text: text.text,
+            alignment: SchematicTextParser.#alignmentFromAnchor(text.anchor),
+            borderWidth: text.lineWidth || 1,
+            color: text.color,
+            borderColor: text.borderColor,
+            fill: text.fill,
+            isSolid: text.isSolid,
+            showBorder: text.showBorder,
+            font: {
+                size: text.fontSize,
+                family: text.fontFamily,
+                weight: text.fontWeight,
+                ...(text.fontStyle ? { style: text.fontStyle } : {})
+            },
+            textMargin: text.textMargin,
+            renderOrder: text.renderOrder,
+            ownerIndex: text.ownerIndex
+        })
+    }
+
+    /**
+     * Converts SVG text-anchor naming to a read-model alignment label.
+     * @param {string | undefined} anchor Text anchor.
+     * @returns {'left' | 'center' | 'right'}
+     */
+    static #alignmentFromAnchor(anchor) {
+        if (anchor === 'middle') return 'center'
+        if (anchor === 'end') return 'right'
+        return 'left'
+    }
+
+    /**
+     * 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
+            )
+        )
+    }
+
     /**
      * Decodes Altium note control codes into visible text rows.
      * @param {string} text

package/src/core/altium/SvgModelCrossLinkValidator.mjs

@@ -0,0 +1,402 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Validates that semantic SVG links point back to normalized model entries.
+ */
+export class SvgModelCrossLinkValidator {
+    static SCHEMA = 'altium-toolkit.svg-model-cross-link.a1'
+
+    /**
+     * Validates semantic SVG data attributes against a normalized model.
+     * @param {object} documentModel Normalized schematic or PCB model.
+     * @param {string} svgMarkup SVG markup.
+     * @returns {object}
+     */
+    static validate(documentModel, svgMarkup) {
+        const documentKind =
+            SvgModelCrossLinkValidator.#documentKind(documentModel)
+        const expectedElements =
+            SvgModelCrossLinkValidator.#expectedElements(documentModel)
+        const expectedByKey = new Map(
+            expectedElements.map((element) => [element.elementKey, element])
+        )
+        const svgElements = SvgModelCrossLinkValidator.#svgElements(svgMarkup)
+        const renderedKeys = new Set(
+            svgElements.map((element) => element.elementKey).filter(Boolean)
+        )
+        const orphanElements = SvgModelCrossLinkValidator.#orphanElements(
+            svgElements,
+            expectedByKey,
+            documentKind
+        )
+        const missingElements = SvgModelCrossLinkValidator.#missingElements(
+            expectedElements,
+            renderedKeys,
+            documentModel.diagnostics || []
+        )
+        const unresolvedReferences =
+            SvgModelCrossLinkValidator.#unresolvedReferences(
+                documentModel,
+                svgElements
+            )
+        const metadata = SvgModelCrossLinkValidator.#metadata(svgMarkup)
+
+        return {
+            schema: SvgModelCrossLinkValidator.SCHEMA,
+            documentKind,
+            summary: {
+                expectedElementCount: expectedElements.length,
+                renderedElementCount: renderedKeys.size,
+                linkedElementCount:
+                    expectedElements.length - missingElements.length,
+                missingElementCount: missingElements.length,
+                orphanElementCount: orphanElements.length,
+                unresolvedReferenceCount: unresolvedReferences.length,
+                metadataElementCount: metadata.elements.length
+            },
+            missingElements,
+            orphanElements,
+            unresolvedReferences,
+            metadata
+        }
+    }
+
+    /**
+     * Determines the model kind for report output.
+     * @param {object} documentModel Normalized document model.
+     * @returns {'schematic' | 'pcb' | 'unknown'}
+     */
+    static #documentKind(documentModel) {
+        if (documentModel?.schematic) return 'schematic'
+        if (documentModel?.pcb) return 'pcb'
+        return 'unknown'
+    }
+
+    /**
+     * Builds expected semantic element keys from a normalized model.
+     * @param {object} documentModel Normalized document model.
+     * @returns {object[]}
+     */
+    static #expectedElements(documentModel) {
+        if (documentModel?.schematic) {
+            return SvgModelCrossLinkValidator.#schematicExpectedElements(
+                documentModel.schematic
+            )
+        }
+        if (documentModel?.pcb) {
+            return SvgModelCrossLinkValidator.#pcbExpectedElements(
+                documentModel.pcb
+            )
+        }
+        return []
+    }
+
+    /**
+     * Builds expected schematic element descriptors.
+     * @param {object} schematic Normalized schematic payload.
+     * @returns {object[]}
+     */
+    static #schematicExpectedElements(schematic) {
+        return SvgModelCrossLinkValidator.#collectionElements('schematic', [
+            ['lines', 'line', schematic?.lines || []],
+            ['polygons', 'polygon', schematic?.polygons || []],
+            ['rectangles', 'rectangle', schematic?.rectangles || []],
+            [
+                'roundedRectangles',
+                'rounded-rectangle',
+                schematic?.roundedRectangles || []
+            ],
+            ['ellipses', 'ellipse', schematic?.ellipses || []],
+            ['arcs', 'arc', schematic?.arcs || []],
+            ['beziers', 'bezier', schematic?.beziers || []],
+            ['pies', 'pie', schematic?.pies || []],
+            ['ieeeSymbols', 'ieee-symbol', schematic?.ieeeSymbols || []],
+            ['texts', 'text', schematic?.texts || []],
+            ['pins', 'pin', schematic?.pins || []],
+            ['ports', 'port', schematic?.ports || []],
+            ['directives', 'directive', schematic?.directives || []]
+        ])
+    }
+
+    /**
+     * Builds expected PCB element descriptors.
+     * @param {object} pcb Normalized PCB payload.
+     * @returns {object[]}
+     */
+    static #pcbExpectedElements(pcb) {
+        return SvgModelCrossLinkValidator.#collectionElements('pcb', [
+            ['polygons', 'polygon', pcb?.polygons || []],
+            ['fills', 'fill', pcb?.fills || []],
+            ['tracks', 'track', pcb?.tracks || []],
+            ['arcs', 'arc', pcb?.arcs || []],
+            ['vias', 'via', pcb?.vias || []],
+            ['pads', 'pad', pcb?.pads || []],
+            ['texts', 'text', pcb?.texts || []],
+            ['components', 'component', pcb?.components || []]
+        ])
+    }
+
+    /**
+     * Builds descriptors for primitive collections.
+     * @param {'schematic' | 'pcb'} prefix SVG element prefix.
+     * @param {[string, string, object[]][]} collections Collections to inspect.
+     * @returns {object[]}
+     */
+    static #collectionElements(prefix, collections) {
+        const elements = []
+        for (const [collectionKey, primitiveKind, records] of collections) {
+            for (const [index, record] of (records || []).entries()) {
+                elements.push({
+                    elementKey: prefix + '-' + primitiveKind + '-' + index,
+                    collectionKey,
+                    primitiveKind,
+                    recordId:
+                        record?.recordId ??
+                        record?.sourceRecordId ??
+                        record?.sourceRecordIndex ??
+                        ''
+                })
+            }
+        }
+        return elements
+    }
+
+    /**
+     * Extracts SVG elements that carry semantic data attributes.
+     * @param {string} svgMarkup SVG markup.
+     * @returns {object[]}
+     */
+    static #svgElements(svgMarkup) {
+        const elements = []
+        const tagPattern = /<[^>]+data-element-key="[^"]+"[^>]*>/gu
+        let match = tagPattern.exec(String(svgMarkup || ''))
+        while (match) {
+            const attrs = SvgModelCrossLinkValidator.#dataAttributes(match[0])
+            elements.push({
+                elementKey: attrs.elementKey || '',
+                primitive: attrs.primitive || '',
+                component: attrs.component || '',
+                net: attrs.net || '',
+                pin: attrs.pin || '',
+                attrs
+            })
+            match = tagPattern.exec(String(svgMarkup || ''))
+        }
+        return elements
+    }
+
+    /**
+     * Extracts data attributes from one SVG tag.
+     * @param {string} tag SVG tag markup.
+     * @returns {Record<string, string>}
+     */
+    static #dataAttributes(tag) {
+        const attrs = {}
+        const attrPattern = /data-([a-z0-9-]+)="([^"]*)"/giu
+        let match = attrPattern.exec(tag || '')
+        while (match) {
+            attrs[SvgModelCrossLinkValidator.#camelCase(match[1])] =
+                SvgModelCrossLinkValidator.#decodeEntities(match[2])
+            match = attrPattern.exec(tag || '')
+        }
+        return attrs
+    }
+
+    /**
+     * Finds rendered elements not represented by the normalized model.
+     * @param {object[]} svgElements Rendered semantic SVG rows.
+     * @param {Map<string, object>} expectedByKey Expected element map.
+     * @param {'schematic' | 'pcb' | 'unknown'} documentKind Document kind.
+     * @returns {object[]}
+     */
+    static #orphanElements(svgElements, expectedByKey, documentKind) {
+        return svgElements
+            .filter(
+                (element) =>
+                    !expectedByKey.has(element.elementKey) &&
+                    !SvgModelCrossLinkValidator.#isRendererOwnedElement(
+                        element.elementKey,
+                        documentKind
+                    )
+            )
+            .map((element) => ({
+                elementKey: element.elementKey,
+                primitive: element.primitive || ''
+            }))
+    }
+
+    /**
+     * Finds normalized elements that are not represented in SVG output.
+     * @param {object[]} expectedElements Expected model element rows.
+     * @param {Set<string>} renderedKeys Rendered SVG element keys.
+     * @param {object[]} diagnostics Model diagnostics.
+     * @returns {object[]}
+     */
+    static #missingElements(expectedElements, renderedKeys, diagnostics) {
+        return expectedElements
+            .filter(
+                (element) =>
+                    !renderedKeys.has(element.elementKey) &&
+                    !SvgModelCrossLinkValidator.#hasDiagnostic(
+                        element,
+                        diagnostics
+                    )
+            )
+            .map((element) => ({
+                elementKey: element.elementKey,
+                collectionKey: element.collectionKey,
+                primitiveKind: element.primitiveKind,
+                recordId: element.recordId || undefined
+            }))
+    }
+
+    /**
+     * Checks whether a missing element has an explicit diagnostic.
+     * @param {object} element Expected element row.
+     * @param {object[]} diagnostics Model diagnostics.
+     * @returns {boolean}
+     */
+    static #hasDiagnostic(element, diagnostics) {
+        return (diagnostics || []).some((diagnostic) => {
+            const message = String(diagnostic?.message || '')
+            return (
+                diagnostic?.elementKey === element.elementKey ||
+                (element.recordId &&
+                    diagnostic?.recordId === element.recordId) ||
+                message.includes(element.elementKey)
+            )
+        })
+    }
+
+    /**
+     * Finds component/net references that cannot be resolved in the model.
+     * @param {object} documentModel Normalized document model.
+     * @param {object[]} svgElements Rendered semantic SVG rows.
+     * @returns {object[]}
+     */
+    static #unresolvedReferences(documentModel, svgElements) {
+        const components =
+            SvgModelCrossLinkValidator.#componentNames(documentModel)
+        const nets = SvgModelCrossLinkValidator.#netNames(documentModel)
+        const unresolved = []
+
+        for (const element of svgElements) {
+            if (element.component && !components.has(element.component)) {
+                unresolved.push({
+                    elementKey: element.elementKey,
+                    referenceKind: 'component',
+                    value: element.component
+                })
+            }
+            if (element.net && !nets.has(element.net)) {
+                unresolved.push({
+                    elementKey: element.elementKey,
+                    referenceKind: 'net',
+                    value: element.net
+                })
+            }
+        }
+
+        return unresolved
+    }
+
+    /**
+     * Collects normalized component designators.
+     * @param {object} documentModel Normalized document model.
+     * @returns {Set<string>}
+     */
+    static #componentNames(documentModel) {
+        const components =
+            documentModel?.schematic?.components ||
+            documentModel?.pcb?.components ||
+            []
+        return new Set(
+            components
+                .map((component) => String(component?.designator || ''))
+                .filter(Boolean)
+        )
+    }
+
+    /**
+     * Collects normalized net names.
+     * @param {object} documentModel Normalized document model.
+     * @returns {Set<string>}
+     */
+    static #netNames(documentModel) {
+        const nets =
+            documentModel?.schematic?.nets || documentModel?.pcb?.nets || []
+        return new Set(
+            nets.map((net) => String(net?.name || '')).filter(Boolean)
+        )
+    }
+
+    /**
+     * Returns true for renderer-owned semantic helpers.
+     * @param {string} elementKey SVG element key.
+     * @param {'schematic' | 'pcb' | 'unknown'} documentKind Document kind.
+     * @returns {boolean}
+     */
+    static #isRendererOwnedElement(elementKey, documentKind) {
+        if (documentKind !== 'pcb') return false
+        return (
+            elementKey === 'pcb-board-outline' ||
+            elementKey === 'pcb-board-outline-stroke' ||
+            /^pcb-board-cutout-\d+$/u.test(elementKey) ||
+            /^pcb-(via|pad)-hole-\d+$/u.test(elementKey)
+        )
+    }
+
+    /**
+     * Extracts the semantic metadata JSON sidecar when present.
+     * @param {string} svgMarkup SVG markup.
+     * @returns {{ schema: string, elements: object[] }}
+     */
+    static #metadata(svgMarkup) {
+        const match = String(svgMarkup || '').match(
+            /<metadata id="(?:schematic|pcb)-semantic-metadata"[^>]*>([^<]*)<\/metadata>/u
+        )
+        if (!match) {
+            return { schema: '', elements: [] }
+        }
+        try {
+            const metadata = JSON.parse(
+                SvgModelCrossLinkValidator.#decodeEntities(match[1])
+            )
+            return {
+                schema: metadata.schema || '',
+                elements: Array.isArray(metadata.elements)
+                    ? metadata.elements
+                    : []
+            }
+        } catch {
+            return { schema: '', elements: [] }
+        }
+    }
+
+    /**
+     * Converts a data attribute token to a camelCase object key.
+     * @param {string} value Attribute token.
+     * @returns {string}
+     */
+    static #camelCase(value) {
+        return String(value || '').replace(/-([a-z0-9])/giu, (_match, char) =>
+            String(char).toUpperCase()
+        )
+    }
+
+    /**
+     * Decodes basic XML entities.
+     * @param {string} value Encoded value.
+     * @returns {string}
+     */
+    static #decodeEntities(value) {
+        return String(value || '')
+            .replace(/&quot;/gu, '"')
+            .replace(/&apos;/gu, "'")
+            .replace(/&lt;/gu, '<')
+            .replace(/&gt;/gu, '>')
+            .replace(/&amp;/gu, '&')
+    }
+}