altium-toolkit 1.1.22 → 1.1.23

package/src/core/altium/ParserValueVerificationReportBuilder.mjs

@@ -0,0 +1,323 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds fixture-oriented parser value verification reports from path maps.
+ */
+export class ParserValueVerificationReportBuilder {
+    static SCHEMA = 'altium-toolkit.parser-value-verification.a1'
+
+    /**
+     * Builds a value verification report.
+     * @param {{ cases?: object[] }} [input] Report input.
+     * @returns {object}
+     */
+    static build(input = {}) {
+        const cases = (input.cases || []).map((entry, index) =>
+            ParserValueVerificationReportBuilder.#caseReport(entry, index)
+        )
+        const failures = cases.flatMap((entry) =>
+            entry.failures.map((failure) => ({
+                caseKey: entry.key,
+                ...(entry.source ? { source: entry.source } : {}),
+                ...failure
+            }))
+        )
+        const passedCount = cases.reduce(
+            (total, entry) => total + entry.passedCount,
+            0
+        )
+        const failedCount = cases.reduce(
+            (total, entry) => total + entry.failedCount,
+            0
+        )
+
+        return {
+            schema: ParserValueVerificationReportBuilder.SCHEMA,
+            summary: {
+                caseCount: cases.length,
+                assertionCount: cases.reduce(
+                    (total, entry) => total + entry.assertionCount,
+                    0
+                ),
+                passedCount,
+                failedCount,
+                mismatchCount: failures.filter(
+                    (failure) => failure.status === 'mismatch'
+                ).length,
+                missingCount: failures.filter(
+                    (failure) => failure.status === 'missing'
+                ).length,
+                status: failedCount ? 'failed' : 'passed'
+            },
+            cases,
+            failures
+        }
+    }
+
+    /**
+     * Builds one case report.
+     * @param {object} entry Case input.
+     * @param {number} index Case index.
+     * @returns {object}
+     */
+    static #caseReport(entry, index) {
+        const key = String(entry.key || 'case-' + index)
+        const actual = entry.actual || entry.model || entry.documentModel || {}
+        const assertionInput =
+            entry.expectedValues || entry.expected || entry.assertions || []
+        const assertions =
+            ParserValueVerificationReportBuilder.#assertions(assertionInput)
+        const failures = []
+        const passedAssertions = []
+
+        for (const assertion of assertions) {
+            const actualValue = ParserValueVerificationReportBuilder.#pathValue(
+                actual,
+                assertion.path
+            )
+
+            if (!actualValue.present) {
+                failures.push(
+                    ParserValueVerificationReportBuilder.#failure(
+                        assertion,
+                        actualValue,
+                        'missing'
+                    )
+                )
+                continue
+            }
+
+            if (
+                !ParserValueVerificationReportBuilder.#equal(
+                    actualValue.value,
+                    assertion.expected
+                )
+            ) {
+                failures.push(
+                    ParserValueVerificationReportBuilder.#failure(
+                        assertion,
+                        actualValue,
+                        'mismatch'
+                    )
+                )
+                continue
+            }
+
+            passedAssertions.push({
+                path: assertion.path,
+                expected: assertion.expected,
+                ...(assertion.label ? { label: assertion.label } : {})
+            })
+        }
+
+        return ParserValueVerificationReportBuilder.#stripUndefined({
+            key,
+            source: entry.source,
+            status: failures.length ? 'failed' : 'passed',
+            assertionCount: assertions.length,
+            passedCount: assertions.length - failures.length,
+            failedCount: failures.length,
+            failures,
+            assertions:
+                ParserValueVerificationReportBuilder.#shouldIncludeAssertions(
+                    assertionInput
+                )
+                    ? passedAssertions
+                    : undefined
+        })
+    }
+
+    /**
+     * Converts path-map or assertion-list input into assertion rows.
+     * @param {Record<string, unknown> | object[]} input Assertion input.
+     * @returns {{ path: string, expected: unknown, label?: string }[]}
+     */
+    static #assertions(input) {
+        if (Array.isArray(input)) {
+            return input
+                .filter((entry) => entry?.path)
+                .map((entry) => ({
+                    path: String(entry.path),
+                    expected: entry.expected,
+                    label: entry.label
+                }))
+        }
+
+        return Object.entries(input || {}).map(([path, expected]) => ({
+            path,
+            expected
+        }))
+    }
+
+    /**
+     * Returns true when passing assertion detail should be emitted.
+     * @param {Record<string, unknown> | object[]} input Assertion input.
+     * @returns {boolean}
+     */
+    static #shouldIncludeAssertions(input) {
+        return Array.isArray(input)
+    }
+
+    /**
+     * Builds one failure row.
+     * @param {{ path: string, expected: unknown }} assertion Expected assertion.
+     * @param {{ present: boolean, value: unknown }} actualValue Actual path lookup.
+     * @param {'missing' | 'mismatch'} status Failure status.
+     * @returns {object}
+     */
+    static #failure(assertion, actualValue, status) {
+        const actual = actualValue.present
+            ? ParserValueVerificationReportBuilder.#jsonValue(actualValue.value)
+            : null
+        const expected = ParserValueVerificationReportBuilder.#jsonValue(
+            assertion.expected
+        )
+
+        return {
+            path: assertion.path,
+            status,
+            expected,
+            actual,
+            message:
+                status === 'missing'
+                    ? 'Expected ' +
+                      assertion.path +
+                      ' to equal ' +
+                      ParserValueVerificationReportBuilder.#formatValue(
+                          expected
+                      ) +
+                      ' but the path was missing.'
+                    : 'Expected ' +
+                      assertion.path +
+                      ' to equal ' +
+                      ParserValueVerificationReportBuilder.#formatValue(
+                          expected
+                      ) +
+                      ' but received ' +
+                      ParserValueVerificationReportBuilder.#formatValue(
+                          actual
+                      ) +
+                      '.'
+        }
+    }
+
+    /**
+     * Resolves one dot/bracket path from an object.
+     * @param {object} source Source object.
+     * @param {string} path Path expression.
+     * @returns {{ present: boolean, value: unknown }}
+     */
+    static #pathValue(source, path) {
+        const parts = String(path || '')
+            .replace(/\[(\d+)\]/gu, '.$1')
+            .split('.')
+            .filter(Boolean)
+        let current = source
+
+        for (const part of parts) {
+            if (Array.isArray(current)) {
+                const index = Number(part)
+                if (
+                    !Number.isInteger(index) ||
+                    index < 0 ||
+                    index >= current.length
+                ) {
+                    return { present: false, value: undefined }
+                }
+                current = current[index]
+                continue
+            }
+
+            if (!current || typeof current !== 'object' || !(part in current)) {
+                return { present: false, value: undefined }
+            }
+
+            current = current[part]
+        }
+
+        return { present: true, value: current }
+    }
+
+    /**
+     * Compares two values by stable JSON representation.
+     * @param {unknown} left First value.
+     * @param {unknown} right Second value.
+     * @returns {boolean}
+     */
+    static #equal(left, right) {
+        return (
+            ParserValueVerificationReportBuilder.#stableJson(left) ===
+            ParserValueVerificationReportBuilder.#stableJson(right)
+        )
+    }
+
+    /**
+     * Converts values into JSON-safe report payloads.
+     * @param {unknown} value Source value.
+     * @returns {unknown}
+     */
+    static #jsonValue(value) {
+        return value === undefined ? null : value
+    }
+
+    /**
+     * Formats a value for a concise diagnostic message.
+     * @param {unknown} value Report value.
+     * @returns {string}
+     */
+    static #formatValue(value) {
+        return JSON.stringify(value)
+    }
+
+    /**
+     * Produces a stable JSON representation for comparison.
+     * @param {unknown} value Source value.
+     * @returns {string}
+     */
+    static #stableJson(value) {
+        if (!value || typeof value !== 'object') {
+            return JSON.stringify(value)
+        }
+
+        if (Array.isArray(value)) {
+            return (
+                '[' +
+                value
+                    .map((entry) =>
+                        ParserValueVerificationReportBuilder.#stableJson(entry)
+                    )
+                    .join(',') +
+                ']'
+            )
+        }
+
+        return (
+            '{' +
+            Object.keys(value)
+                .sort()
+                .map(
+                    (key) =>
+                        JSON.stringify(key) +
+                        ':' +
+                        ParserValueVerificationReportBuilder.#stableJson(
+                            value[key]
+                        )
+                )
+                .join(',') +
+            '}'
+        )
+    }
+
+    /**
+     * Removes undefined properties from one row.
+     * @param {object} row Source row.
+     * @returns {object}
+     */
+    static #stripUndefined(row) {
+        return Object.fromEntries(
+            Object.entries(row).filter(([, value]) => value !== undefined)
+        )
+    }
+}

package/src/core/altium/PcbClassReportBuilder.mjs

@@ -0,0 +1,366 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds deterministic summaries for normalized PCB class records.
+ */
+export class PcbClassReportBuilder {
+    static SCHEMA = 'altium-toolkit.pcb.class-report.a1'
+
+    /**
+     * Builds a PCB class report.
+     * @param {object} pcb Normalized PCB model.
+     * @returns {object}
+     */
+    static build(pcb = {}) {
+        const indexes = PcbClassReportBuilder.#memberIndexes(pcb)
+        const classes = (Array.isArray(pcb?.classes) ? pcb.classes : []).map(
+            (classRecord, index) =>
+                PcbClassReportBuilder.#classRow(classRecord, index, indexes)
+        )
+        const issues = PcbClassReportBuilder.#issues(classes)
+
+        return {
+            schema: PcbClassReportBuilder.SCHEMA,
+            summary: PcbClassReportBuilder.#summary(classes, issues),
+            byKind: PcbClassReportBuilder.#byKind(classes),
+            classes,
+            issues
+        }
+    }
+
+    /**
+     * Builds lookup sets used to resolve class members.
+     * @param {object} pcb Normalized PCB model.
+     * @returns {Record<string, Set<string>>}
+     */
+    static #memberIndexes(pcb) {
+        return {
+            net: PcbClassReportBuilder.#namedSet(pcb?.nets, ['name']),
+            component: PcbClassReportBuilder.#namedSet(pcb?.components, [
+                'designator',
+                'name'
+            ]),
+            pad: PcbClassReportBuilder.#namedSet(pcb?.pads, [
+                'designator',
+                'padNumber',
+                'pinName',
+                'name'
+            ]),
+            layer: PcbClassReportBuilder.#namedSet(
+                [
+                    ...PcbClassReportBuilder.#array(pcb?.layers),
+                    ...PcbClassReportBuilder.#array(pcb?.primitiveLayers)
+                ],
+                ['name', 'displayName', 'id', 'layerId']
+            ),
+            polygon: PcbClassReportBuilder.#namedSet(pcb?.polygons, [
+                'name',
+                'netName'
+            ]),
+            'diff-pair': PcbClassReportBuilder.#namedSet(
+                pcb?.differentialPairs,
+                ['name']
+            )
+        }
+    }
+
+    /**
+     * Returns an array value or an empty array for non-array input.
+     * @param {unknown} value Candidate array value.
+     * @returns {unknown[]}
+     */
+    static #array(value) {
+        return Array.isArray(value) ? value : []
+    }
+
+    /**
+     * Builds a set of names from candidate row fields.
+     * @param {object[] | undefined} rows Candidate rows.
+     * @param {string[]} keys Candidate field names.
+     * @returns {Set<string>}
+     */
+    static #namedSet(rows, keys) {
+        const values = new Set()
+
+        for (const row of Array.isArray(rows) ? rows : []) {
+            for (const key of keys) {
+                const value = String(row?.[key] ?? '').trim()
+                if (value) {
+                    values.add(value)
+                }
+            }
+        }
+
+        return values
+    }
+
+    /**
+     * Builds one class summary row.
+     * @param {object} classRecord Normalized class record.
+     * @param {number} index Class index.
+     * @param {Record<string, Set<string>>} indexes Member lookup sets.
+     * @returns {object}
+     */
+    static #classRow(classRecord, index, indexes) {
+        const kindName = PcbClassReportBuilder.#kindName(classRecord)
+        const members = (
+            Array.isArray(classRecord?.members) ? classRecord.members : []
+        )
+            .map((member) => String(member || '').trim())
+            .filter(Boolean)
+        const resolvedMembers = []
+        const unresolvedMembers = []
+
+        for (const member of members) {
+            const resolved = PcbClassReportBuilder.#resolveMember(
+                member,
+                kindName,
+                indexes
+            )
+            if (resolved) {
+                resolvedMembers.push(resolved)
+            } else {
+                unresolvedMembers.push(member)
+            }
+        }
+
+        return PcbClassReportBuilder.#stripEmpty({
+            classIndex: Number.isInteger(classRecord?.classIndex)
+                ? classRecord.classIndex
+                : index,
+            name: String(classRecord?.name || '').trim(),
+            kind: Number.isFinite(Number(classRecord?.kind))
+                ? Number(classRecord.kind)
+                : undefined,
+            kindName,
+            enabled: classRecord?.enabled !== false,
+            memberCount: members.length,
+            resolvedMemberCount: resolvedMembers.length,
+            unresolvedMemberCount: unresolvedMembers.length,
+            members,
+            resolvedMembers,
+            unresolvedMembers,
+            references: PcbClassReportBuilder.#references(resolvedMembers),
+            uniqueId: String(classRecord?.uniqueId || '').trim()
+        })
+    }
+
+    /**
+     * Resolves the normalized class kind name.
+     * @param {object} classRecord Normalized class record.
+     * @returns {string}
+     */
+    static #kindName(classRecord) {
+        const kindName = String(classRecord?.kindName || '').trim()
+        if (kindName) {
+            return kindName
+        }
+
+        return (
+            {
+                0: 'net',
+                1: 'component',
+                2: 'from-to',
+                3: 'pad',
+                4: 'layer',
+                6: 'diff-pair',
+                7: 'polygon'
+            }[Number(classRecord?.kind)] || 'unknown'
+        )
+    }
+
+    /**
+     * Resolves one class member against the expected or known object indexes.
+     * @param {string} member Member name.
+     * @param {string} kindName Class kind name.
+     * @param {Record<string, Set<string>>} indexes Member lookup sets.
+     * @returns {{ name: string, kind: string } | null}
+     */
+    static #resolveMember(member, kindName, indexes) {
+        const expectedKind = kindName === 'diff-pair' ? 'diff-pair' : kindName
+        const expectedIndex = indexes[expectedKind]
+        if (expectedIndex?.has(member)) {
+            return { name: member, kind: expectedKind }
+        }
+
+        if (kindName !== 'unknown') {
+            return null
+        }
+
+        for (const [kind, values] of Object.entries(indexes)) {
+            if (values.has(member)) {
+                return { name: member, kind }
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Builds grouped reference lists from resolved members.
+     * @param {{ name: string, kind: string }[]} resolvedMembers Resolved member rows.
+     * @returns {object}
+     */
+    static #references(resolvedMembers) {
+        const references = {
+            netNames: [],
+            componentDesignators: [],
+            padDesignators: [],
+            layerNames: [],
+            polygonNames: [],
+            differentialPairNames: []
+        }
+
+        for (const member of resolvedMembers) {
+            if (member.kind === 'net') references.netNames.push(member.name)
+            if (member.kind === 'component') {
+                references.componentDesignators.push(member.name)
+            }
+            if (member.kind === 'pad')
+                references.padDesignators.push(member.name)
+            if (member.kind === 'layer') references.layerNames.push(member.name)
+            if (member.kind === 'polygon') {
+                references.polygonNames.push(member.name)
+            }
+            if (member.kind === 'diff-pair') {
+                references.differentialPairNames.push(member.name)
+            }
+        }
+
+        return Object.fromEntries(
+            Object.entries(references)
+                .map(([key, values]) => [
+                    key,
+                    [...values].sort(PcbClassReportBuilder.#naturalCompare)
+                ])
+                .filter(([, values]) => values.length > 0)
+        )
+    }
+
+    /**
+     * Builds deterministic class issues.
+     * @param {object[]} classes Class rows.
+     * @returns {object[]}
+     */
+    static #issues(classes) {
+        const issues = []
+
+        for (const classRow of classes) {
+            for (const member of classRow.unresolvedMembers || []) {
+                issues.push({
+                    code: 'pcb.class.unresolved-member',
+                    severity: 'warning',
+                    className: classRow.name,
+                    kindName: classRow.kindName,
+                    memberName: member
+                })
+            }
+
+            if (classRow.memberCount === 0) {
+                issues.push({
+                    code: 'pcb.class.empty',
+                    severity: 'info',
+                    className: classRow.name,
+                    kindName: classRow.kindName
+                })
+            }
+        }
+
+        return issues
+    }
+
+    /**
+     * Builds top-level class summary counters.
+     * @param {object[]} classes Class rows.
+     * @param {object[]} issues Issue rows.
+     * @returns {object}
+     */
+    static #summary(classes, issues) {
+        return {
+            classCount: classes.length,
+            enabledClassCount: classes.filter((row) => row.enabled !== false)
+                .length,
+            disabledClassCount: classes.filter((row) => row.enabled === false)
+                .length,
+            netClassCount: PcbClassReportBuilder.#kindCount(classes, 'net'),
+            componentClassCount: PcbClassReportBuilder.#kindCount(
+                classes,
+                'component'
+            ),
+            padClassCount: PcbClassReportBuilder.#kindCount(classes, 'pad'),
+            differentialPairClassCount: PcbClassReportBuilder.#kindCount(
+                classes,
+                'diff-pair'
+            ),
+            emptyClassCount: classes.filter((row) => row.memberCount === 0)
+                .length,
+            unresolvedMemberCount: classes.reduce(
+                (total, row) => total + Number(row.unresolvedMemberCount || 0),
+                0
+            ),
+            issueCount: issues.length
+        }
+    }
+
+    /**
+     * Counts classes by kind.
+     * @param {object[]} classes Class rows.
+     * @param {string} kindName Class kind name.
+     * @returns {number}
+     */
+    static #kindCount(classes, kindName) {
+        return classes.filter((row) => row.kindName === kindName).length
+    }
+
+    /**
+     * Builds sorted class counts by kind.
+     * @param {object[]} classes Class rows.
+     * @returns {{ kindName: string, count: number }[]}
+     */
+    static #byKind(classes) {
+        const counts = new Map()
+
+        for (const classRow of classes) {
+            counts.set(
+                classRow.kindName,
+                Number(counts.get(classRow.kindName) || 0) + 1
+            )
+        }
+
+        return [...counts.entries()]
+            .map(([kindName, count]) => ({ kindName, count }))
+            .sort((left, right) =>
+                PcbClassReportBuilder.#naturalCompare(
+                    left.kindName,
+                    right.kindName
+                )
+            )
+    }
+
+    /**
+     * Sorts strings with numeric chunks in human order.
+     * @param {string} left Left value.
+     * @param {string} right Right value.
+     * @returns {number}
+     */
+    static #naturalCompare(left, right) {
+        return String(left).localeCompare(String(right), undefined, {
+            numeric: true
+        })
+    }
+
+    /**
+     * Removes undefined and blank-string values from a shallow object.
+     * @param {Record<string, unknown>} row Input row.
+     * @returns {Record<string, unknown>}
+     */
+    static #stripEmpty(row) {
+        return Object.fromEntries(
+            Object.entries(row).filter(
+                ([, value]) => value !== undefined && value !== ''
+            )
+        )
+    }
+}