altium-toolkit 1.0.7 → 1.0.9

package/src/core/altium/SchematicProjectParameterResolver.mjs

@@ -0,0 +1,361 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Resolves schematic-visible project parameters and special strings.
+ */
+export class SchematicProjectParameterResolver {
+    static #TITLE_BLOCK_FIELDS = [
+        'title',
+        'revision',
+        'documentNumber',
+        'sheetNumber',
+        'sheetTotal',
+        'date',
+        'drawnBy'
+    ]
+
+    /**
+     * Resolves one schematic text expression against project parameters.
+     * @param {string} text Raw schematic text.
+     * @param {Record<string, string | number | boolean | null | undefined>} parameters Project parameters.
+     * @returns {{ rawText: string, resolvedText: string, parameterNames: string[], expressionParts: object[] } | null}
+     */
+    static resolveText(text, parameters = {}) {
+        const rawText = String(text ?? '')
+        const lookup =
+            SchematicProjectParameterResolver.#buildParameterLookup(parameters)
+        const expressionParts =
+            SchematicProjectParameterResolver.#parseExpressionParts(
+                rawText,
+                lookup
+            )
+
+        if (
+            !expressionParts.some((part) => part.kind === 'parameter') ||
+            !expressionParts.length
+        ) {
+            return null
+        }
+
+        const parameterNames = [
+            ...new Set(
+                expressionParts
+                    .filter((part) => part.kind === 'parameter')
+                    .map((part) => part.name)
+            )
+        ]
+
+        return {
+            rawText,
+            resolvedText: expressionParts
+                .map((part) => String(part.value ?? ''))
+                .join(''),
+            parameterNames,
+            expressionParts
+        }
+    }
+
+    /**
+     * Returns a schematic copy with project-parameter annotations.
+     * @param {object} schematic Normalized schematic model.
+     * @param {Record<string, string | number | boolean | null | undefined>} parameters Project parameters.
+     * @param {{ replaceText?: boolean }} options Resolver options.
+     * @returns {object}
+     */
+    static applyToSchematic(schematic, parameters = {}, options = {}) {
+        const resolvedTexts = Array.isArray(schematic?.texts)
+            ? schematic.texts.map((text) =>
+                  SchematicProjectParameterResolver.#annotateText(
+                      text,
+                      parameters,
+                      options
+                  )
+              )
+            : []
+        const sheet = schematic?.sheet
+            ? {
+                  ...schematic.sheet,
+                  titleBlock:
+                      SchematicProjectParameterResolver.#annotateTitleBlock(
+                          schematic.sheet.titleBlock,
+                          parameters,
+                          options
+                      )
+              }
+            : schematic?.sheet
+
+        return {
+            ...(schematic || {}),
+            ...(sheet ? { sheet } : {}),
+            texts: resolvedTexts
+        }
+    }
+
+    /**
+     * Returns a document-model copy with project-parameter annotations.
+     * @param {object} documentModel Normalized document model.
+     * @param {Record<string, string | number | boolean | null | undefined>} parameters Project parameters.
+     * @param {{ replaceText?: boolean }} options Resolver options.
+     * @returns {object}
+     */
+    static applyToDocumentModel(documentModel, parameters = {}, options = {}) {
+        if (!documentModel?.schematic) {
+            return documentModel
+        }
+
+        return {
+            ...documentModel,
+            schematic: SchematicProjectParameterResolver.applyToSchematic(
+                documentModel.schematic,
+                parameters,
+                options
+            )
+        }
+    }
+
+    /**
+     * Builds a case-insensitive project-parameter lookup.
+     * @param {Record<string, string | number | boolean | null | undefined>} parameters Project parameters.
+     * @returns {Map<string, { name: string, value: string }>}
+     */
+    static #buildParameterLookup(parameters) {
+        return new Map(
+            Object.entries(parameters || {}).map(([name, value]) => [
+                name.trim().toLowerCase(),
+                {
+                    name,
+                    value:
+                        value === null || value === undefined
+                            ? ''
+                            : String(value)
+                }
+            ])
+        )
+    }
+
+    /**
+     * Parses one parameter expression into renderable parts.
+     * @param {string} text Raw text.
+     * @param {Map<string, { name: string, value: string }>} lookup Parameter lookup.
+     * @returns {object[]}
+     */
+    static #parseExpressionParts(text, lookup) {
+        const tokens =
+            SchematicProjectParameterResolver.#splitConcatenation(text)
+
+        if (tokens.length > 1) {
+            return tokens.flatMap((token) =>
+                SchematicProjectParameterResolver.#parseToken(token, lookup)
+            )
+        }
+
+        return SchematicProjectParameterResolver.#parseInlineText(text, lookup)
+    }
+
+    /**
+     * Parses one concatenation token.
+     * @param {string} token Expression token.
+     * @param {Map<string, { name: string, value: string }>} lookup Parameter lookup.
+     * @returns {object[]}
+     */
+    static #parseToken(token, lookup) {
+        const trimmed = token.trim()
+        const quoted = trimmed.match(/^"((?:[^"\\]|\\.)*)"$/u)
+
+        if (quoted) {
+            return [
+                {
+                    kind: 'literal',
+                    value: SchematicProjectParameterResolver.#unescapeQuoted(
+                        quoted[1]
+                    )
+                }
+            ]
+        }
+
+        const directParameter = trimmed.match(/^[.=]([A-Za-z_][\w.-]*)$/u)
+        if (directParameter) {
+            return [
+                SchematicProjectParameterResolver.#parameterPart(
+                    directParameter[1],
+                    trimmed[0],
+                    lookup
+                )
+            ]
+        }
+
+        return SchematicProjectParameterResolver.#parseInlineText(token, lookup)
+    }
+
+    /**
+     * Parses inline text and parameter references.
+     * @param {string} text Raw text.
+     * @param {Map<string, { name: string, value: string }>} lookup Parameter lookup.
+     * @returns {object[]}
+     */
+    static #parseInlineText(text, lookup) {
+        const parts = []
+        const pattern = /([.=])([A-Za-z_][\w.-]*)/gu
+        let lastIndex = 0
+        let match = pattern.exec(text)
+
+        while (match) {
+            if (match.index > lastIndex) {
+                parts.push({
+                    kind: 'literal',
+                    value: text.slice(lastIndex, match.index)
+                })
+            }
+
+            parts.push(
+                SchematicProjectParameterResolver.#parameterPart(
+                    match[2],
+                    match[1],
+                    lookup
+                )
+            )
+            lastIndex = pattern.lastIndex
+            match = pattern.exec(text)
+        }
+
+        if (lastIndex < text.length) {
+            parts.push({ kind: 'literal', value: text.slice(lastIndex) })
+        }
+
+        return parts
+    }
+
+    /**
+     * Builds one parameter expression part.
+     * @param {string} name Parameter name.
+     * @param {string} prefix Source prefix.
+     * @param {Map<string, { name: string, value: string }>} lookup Parameter lookup.
+     * @returns {object}
+     */
+    static #parameterPart(name, prefix, lookup) {
+        const resolved = lookup.get(String(name || '').toLowerCase())
+
+        return {
+            kind: 'parameter',
+            name: resolved?.name || name,
+            value: resolved?.value ?? prefix + name
+        }
+    }
+
+    /**
+     * Annotates one schematic text object.
+     * @param {object} text Text primitive.
+     * @param {Record<string, string | number | boolean | null | undefined>} parameters Project parameters.
+     * @param {{ replaceText?: boolean }} options Resolver options.
+     * @returns {object}
+     */
+    static #annotateText(text, parameters, options) {
+        const resolved = SchematicProjectParameterResolver.resolveText(
+            text?.text,
+            parameters
+        )
+
+        if (!resolved) {
+            return { ...(text || {}) }
+        }
+
+        return {
+            ...(text || {}),
+            rawText: resolved.rawText,
+            resolvedText: resolved.resolvedText,
+            specialString: resolved,
+            ...(options.replaceText ? { text: resolved.resolvedText } : {})
+        }
+    }
+
+    /**
+     * Annotates title-block fields with project-parameter resolution details.
+     * @param {object | undefined} titleBlock Title-block object.
+     * @param {Record<string, string | number | boolean | null | undefined>} parameters Project parameters.
+     * @param {{ replaceText?: boolean }} options Resolver options.
+     * @returns {object | undefined}
+     */
+    static #annotateTitleBlock(titleBlock, parameters, options) {
+        if (!titleBlock) {
+            return titleBlock
+        }
+
+        const annotated = { ...titleBlock }
+        const specialStrings = { ...(titleBlock.specialStrings || {}) }
+
+        for (const fieldName of SchematicProjectParameterResolver
+            .#TITLE_BLOCK_FIELDS) {
+            const resolved = SchematicProjectParameterResolver.resolveText(
+                titleBlock[fieldName],
+                parameters
+            )
+            if (!resolved) {
+                continue
+            }
+
+            specialStrings[fieldName] = resolved
+            if (options.replaceText) {
+                annotated[fieldName] = resolved.resolvedText
+            }
+        }
+
+        return Object.keys(specialStrings).length
+            ? { ...annotated, specialStrings }
+            : annotated
+    }
+
+    /**
+     * Splits one string by top-level concatenation operators.
+     * @param {string} text Raw expression.
+     * @returns {string[]}
+     */
+    static #splitConcatenation(text) {
+        const tokens = []
+        let token = ''
+        let inQuote = false
+        let escaped = false
+
+        for (const char of String(text || '')) {
+            if (escaped) {
+                token += char
+                escaped = false
+                continue
+            }
+
+            if (char === '\\') {
+                token += char
+                escaped = true
+                continue
+            }
+
+            if (char === '"') {
+                inQuote = !inQuote
+                token += char
+                continue
+            }
+
+            if (char === '+' && !inQuote) {
+                tokens.push(token)
+                token = ''
+                continue
+            }
+
+            token += char
+        }
+
+        tokens.push(token)
+
+        return tokens
+    }
+
+    /**
+     * Unescapes the subset of quoted string escapes used by parameter fields.
+     * @param {string} text Quoted string body.
+     * @returns {string}
+     */
+    static #unescapeQuoted(text) {
+        return String(text || '').replace(/\\(["\\])/gu, '$1')
+    }
+}

package/src/core/altium/SchematicQaReportBuilder.mjs

@@ -0,0 +1,284 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+const { getDisplayText, getField, parseBoolean, parseNumericField, toColor } =
+    ParserUtils
+
+/**
+ * Builds deterministic read-only QA summaries for schematic documents.
+ */
+export class SchematicQaReportBuilder {
+    static SCHEMA_ID = 'altium-toolkit.schematic.qa.a1'
+
+    /**
+     * Builds a schematic QA report from parsed records and geometry.
+     * @param {{ records: object[], sheet?: object, lines?: object[], texts?: object[] }} input QA input.
+     * @returns {object}
+     */
+    static build(input) {
+        const records = input?.records || []
+        const fonts = SchematicQaReportBuilder.#fonts(input?.sheet)
+        const colors = SchematicQaReportBuilder.#colors(records)
+        const lineWidths = SchematicQaReportBuilder.#lineWidths(records)
+        const unresolvedParameters =
+            SchematicQaReportBuilder.#unresolvedParameters(records)
+        const findings = [
+            ...SchematicQaReportBuilder.#fontFindings(fonts),
+            ...SchematicQaReportBuilder.#unresolvedFindings(
+                unresolvedParameters
+            ),
+            ...SchematicQaReportBuilder.#titleBlockFindings(records)
+        ]
+
+        return {
+            schema: SchematicQaReportBuilder.SCHEMA_ID,
+            summary: {
+                recordCount: records.length,
+                fontFamilyCount: fonts.families.length,
+                colorCount: colors.values.length,
+                lineWidthCount: lineWidths.values.length,
+                unresolvedParameterCount: unresolvedParameters.length,
+                findingCount: findings.length
+            },
+            fonts,
+            colors,
+            lineWidths,
+            unresolvedParameters,
+            titleBlockResidue:
+                SchematicQaReportBuilder.#titleBlockResidue(records),
+            geometryFallbacks: SchematicQaReportBuilder.#geometryFallbacks(
+                input?.texts
+            ),
+            findings
+        }
+    }
+
+    /**
+     * Summarizes sheet fonts.
+     * @param {object | undefined} sheet Parsed sheet model.
+     * @returns {{ families: string[], entries: object[] }}
+     */
+    static #fonts(sheet) {
+        const entries = Object.entries(sheet?.fonts || {})
+            .map(([fontId, font]) => ({
+                fontId,
+                family: String(font?.family || '').trim(),
+                size: Number(font?.size || 0),
+                bold: font?.bold === true,
+                italic: font?.italic === true
+            }))
+            .filter((font) => font.family)
+            .sort(
+                (left, right) =>
+                    left.family.localeCompare(right.family) ||
+                    String(left.fontId).localeCompare(String(right.fontId))
+            )
+
+        return {
+            families: [...new Set(entries.map((font) => font.family))],
+            entries
+        }
+    }
+
+    /**
+     * Summarizes schematic colors.
+     * @param {object[]} records Schematic records.
+     * @returns {{ values: string[], records: object[] }}
+     */
+    static #colors(records) {
+        const rows = []
+
+        for (const record of records || []) {
+            for (const key of ['Color', 'TextColor', 'AreaColor']) {
+                if (!(key in (record.fields || {}))) {
+                    continue
+                }
+
+                rows.push({
+                    recordKey: SchematicQaReportBuilder.#recordKey(record),
+                    field: key,
+                    color: toColor(record.fields[key], '#000000')
+                })
+            }
+        }
+
+        return {
+            values: [...new Set(rows.map((row) => row.color))].sort(),
+            records: rows
+        }
+    }
+
+    /**
+     * Summarizes authored line widths.
+     * @param {object[]} records Schematic records.
+     * @returns {{ values: number[], records: object[] }}
+     */
+    static #lineWidths(records) {
+        const rows = (records || [])
+            .map((record) => ({
+                recordKey: SchematicQaReportBuilder.#recordKey(record),
+                width: parseNumericField(record.fields, 'LineWidth')
+            }))
+            .filter((row) => row.width !== null)
+
+        return {
+            values: [...new Set(rows.map((row) => row.width))].sort(
+                (left, right) => left - right
+            ),
+            records: rows
+        }
+    }
+
+    /**
+     * Collects unresolved `=Parameter` placeholders.
+     * @param {object[]} records Schematic records.
+     * @returns {string[]}
+     */
+    static #unresolvedParameters(records) {
+        const metadata = new Set(
+            (records || [])
+                .filter((record) => getField(record.fields, 'RECORD') === '41')
+                .map((record) => getField(record.fields, 'Name'))
+                .filter(Boolean)
+        )
+        const unresolved = []
+
+        for (const record of records || []) {
+            const text = getDisplayText(record.fields)
+            const match = text.match(/^=([A-Za-z_][\w.]*)$/)
+            if (!match) {
+                continue
+            }
+            if (
+                !metadata.has(match[1]) ||
+                text === getDisplayText(record.fields)
+            ) {
+                unresolved.push(match[1])
+            }
+        }
+
+        return [...new Set(unresolved)].sort()
+    }
+
+    /**
+     * Builds nonstandard-font findings.
+     * @param {{ families: string[] }} fonts Font summary.
+     * @returns {object[]}
+     */
+    static #fontFindings(fonts) {
+        const preferred = new Set(['Arial', 'Times New Roman'])
+
+        return (fonts.families || [])
+            .filter((family) => !preferred.has(family))
+            .map((family) => ({
+                code: 'schematic.font.nonstandard-family',
+                severity: 'info',
+                family,
+                message:
+                    'Schematic uses a font family outside the default parser baseline.'
+            }))
+    }
+
+    /**
+     * Builds unresolved-parameter findings.
+     * @param {string[]} parameters Unresolved parameters.
+     * @returns {object[]}
+     */
+    static #unresolvedFindings(parameters) {
+        return (parameters || []).map((parameter) => ({
+            code: 'schematic.text.unresolved-parameter',
+            severity: 'warning',
+            parameter,
+            message:
+                'Schematic text contains an unresolved project or document parameter.'
+        }))
+    }
+
+    /**
+     * Builds title-block findings.
+     * @param {object[]} records Schematic records.
+     * @returns {object[]}
+     */
+    static #titleBlockFindings(records) {
+        const sheet = (records || []).find(
+            (record) => getField(record.fields, 'RECORD') === '31'
+        )
+        if (!sheet || parseBoolean(sheet.fields.TitleBlockOn)) {
+            return []
+        }
+
+        const residue = SchematicQaReportBuilder.#titleBlockResidue(records)
+        return residue.length
+            ? [
+                  {
+                      code: 'schematic.title-block.hidden-residue',
+                      severity: 'info',
+                      count: residue.length,
+                      message:
+                          'Hidden title-block parameter records remain while the title block is disabled.'
+                  }
+              ]
+            : []
+    }
+
+    /**
+     * Collects hidden title-block-like parameter rows.
+     * @param {object[]} records Schematic records.
+     * @returns {object[]}
+     */
+    static #titleBlockResidue(records) {
+        const titleBlockNames = new Set([
+            'title',
+            'revision',
+            'documentnumber',
+            'sheetnumber',
+            'sheettotal',
+            'date',
+            'drawnby'
+        ])
+
+        return (records || [])
+            .filter(
+                (record) =>
+                    getField(record.fields, 'RECORD') === '41' &&
+                    parseBoolean(record.fields.IsHidden) &&
+                    titleBlockNames.has(
+                        getField(record.fields, 'Name')
+                            .replace(/\s+/g, '')
+                            .toLowerCase()
+                    )
+            )
+            .map((record) => ({
+                recordKey: SchematicQaReportBuilder.#recordKey(record),
+                name: getField(record.fields, 'Name'),
+                value: getDisplayText(record.fields)
+            }))
+    }
+
+    /**
+     * Collects text geometry fallback diagnostics already attached by parsers.
+     * @param {object[] | undefined} texts Parsed text rows.
+     * @returns {object[]}
+     */
+    static #geometryFallbacks(texts) {
+        return (texts || [])
+            .filter((text) => text?.diagnosticState)
+            .map((text, index) => ({
+                key: 'schematic-text-' + index,
+                state: text.diagnosticState,
+                text: text.text || ''
+            }))
+    }
+
+    /**
+     * Builds a stable schematic record key.
+     * @param {object} record Schematic record.
+     * @returns {string}
+     */
+    static #recordKey(record) {
+        return 'schematic-record-' + String(record?.recordIndex ?? 0)
+    }
+}