altium-toolkit 1.1.22 → 1.1.24

package/src/core/altium/ParameterRecordInventoryBuilder.mjs

@@ -0,0 +1,274 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds read-only inventories for pipe/backtick parameter record strings.
+ */
+export class ParameterRecordInventoryBuilder {
+    static SCHEMA = 'altium-toolkit.parameter-record-inventory.a1'
+
+    /**
+     * Builds a parameter record inventory report.
+     * @param {{ records?: (object | string)[] } | (object | string)[]} [input]
+     * @returns {object}
+     */
+    static build(input = {}) {
+        const sourceRecords = Array.isArray(input) ? input : input.records || []
+        const records = sourceRecords.map((record, index) =>
+            ParameterRecordInventoryBuilder.scanRecord(
+                ParameterRecordInventoryBuilder.#raw(record),
+                {
+                    sourceStream:
+                        typeof record === 'object' ? record.sourceStream : '',
+                    recordIndex:
+                        typeof record === 'object'
+                            ? (record.recordIndex ?? index)
+                            : index
+                }
+            )
+        )
+
+        return {
+            schema: ParameterRecordInventoryBuilder.SCHEMA,
+            summary: ParameterRecordInventoryBuilder.#summary(records),
+            records
+        }
+    }
+
+    /**
+     * Scans one raw record string.
+     * @param {string} raw Raw parameter record text.
+     * @param {{ sourceStream?: string, recordIndex?: number }} [metadata]
+     * @returns {object}
+     */
+    static scanRecord(raw, metadata = {}) {
+        const fields = []
+        const keyCounts = new Map()
+        let emptyEntryCount = 0
+
+        for (const segment of ParameterRecordInventoryBuilder.#segments(raw)) {
+            const text = segment.text.trim()
+            if (!text) {
+                emptyEntryCount += 1
+                continue
+            }
+
+            const separatorIndex = text.indexOf('=')
+            if (separatorIndex <= 0) {
+                continue
+            }
+
+            const rawKey = text.slice(0, separatorIndex).trim()
+            const isUtf8 = rawKey.startsWith('%UTF8%')
+            const key = rawKey.replace(/^%UTF8%/u, '')
+            if (!key) continue
+
+            const value = text.slice(separatorIndex + 1).trim()
+            const occurrence = (keyCounts.get(key) || 0) + 1
+            keyCounts.set(key, occurrence)
+            fields.push({
+                rawKey,
+                key,
+                value,
+                delimiter: segment.delimiter,
+                level: segment.level,
+                occurrence,
+                isUtf8,
+                typedValue: ParameterRecordInventoryBuilder.#typedValue(value)
+            })
+        }
+
+        const duplicateFields =
+            ParameterRecordInventoryBuilder.#duplicateFields(fields)
+
+        return ParameterRecordInventoryBuilder.#stripUndefined({
+            sourceStream: metadata.sourceStream || undefined,
+            recordIndex: metadata.recordIndex,
+            fieldCount: fields.length,
+            emptyEntryCount,
+            duplicateFields,
+            fields
+        })
+    }
+
+    /**
+     * Extracts raw record text from supported inputs.
+     * @param {object | string} record Source record.
+     * @returns {string}
+     */
+    static #raw(record) {
+        if (typeof record === 'string') return record
+        return String(record?.raw || record?.text || '')
+    }
+
+    /**
+     * Splits a parameter string into delimiter-aware segments.
+     * @param {string} raw Raw parameter text.
+     * @returns {{ delimiter: string, level: number, text: string }[]}
+     */
+    static #segments(raw) {
+        const value = String(raw || '')
+        const segments = []
+        let delimiter = ''
+        let text = ''
+
+        for (const character of value) {
+            if (character === '|' || character === '`') {
+                if (delimiter || text) {
+                    segments.push({
+                        delimiter,
+                        level: delimiter === '`' ? 1 : 0,
+                        text
+                    })
+                }
+                delimiter = character
+                text = ''
+                continue
+            }
+
+            text += character
+        }
+
+        if (delimiter || text) {
+            segments.push({
+                delimiter,
+                level: delimiter === '`' ? 1 : 0,
+                text
+            })
+        }
+
+        return segments
+    }
+
+    /**
+     * Infers a typed value for common parameter scalar encodings.
+     * @param {string} value Field value.
+     * @returns {{ kind: 'boolean' | 'integer' | 'number', value: boolean | number } | null}
+     */
+    static #typedValue(value) {
+        const text = String(value || '').trim()
+        if (/^(T|TRUE)$/iu.test(text)) {
+            return { kind: 'boolean', value: true }
+        }
+        if (/^(F|FALSE)$/iu.test(text)) {
+            return { kind: 'boolean', value: false }
+        }
+        if (/^[+-]?\d+$/u.test(text)) {
+            return { kind: 'integer', value: Number(text) }
+        }
+        if (/^[+-]?(?:\d+\.\d*|\.\d+|\d+E[+-]?\d+)$/iu.test(text)) {
+            const parsed = Number(text)
+            return Number.isFinite(parsed)
+                ? { kind: 'number', value: parsed }
+                : null
+        }
+
+        return null
+    }
+
+    /**
+     * Builds duplicate field rows.
+     * @param {object[]} fields Scanned fields.
+     * @returns {object[]}
+     */
+    static #duplicateFields(fields) {
+        const byKey = new Map()
+
+        for (const field of fields) {
+            byKey.set(field.key, [...(byKey.get(field.key) || []), field])
+        }
+
+        return [...byKey.entries()]
+            .filter(([, rows]) => rows.length > 1)
+            .map(([key, rows]) => ({
+                key,
+                count: rows.length,
+                firstValue: rows[0].value,
+                lastValue: rows.at(-1).value
+            }))
+            .sort((left, right) => left.key.localeCompare(right.key))
+    }
+
+    /**
+     * Summarizes scanned records.
+     * @param {object[]} records Scanned records.
+     * @returns {object}
+     */
+    static #summary(records) {
+        const duplicateFieldCount = records.reduce(
+            (total, record) => total + record.duplicateFields.length,
+            0
+        )
+
+        return {
+            recordCount: records.length,
+            fieldCount: ParameterRecordInventoryBuilder.#sum(
+                records,
+                'fieldCount'
+            ),
+            duplicateFieldCount,
+            duplicateOccurrenceCount: records.reduce(
+                (total, record) =>
+                    total +
+                    record.duplicateFields.reduce(
+                        (count, field) => count + field.count - 1,
+                        0
+                    ),
+                0
+            ),
+            utf8FieldCount: ParameterRecordInventoryBuilder.#fieldCount(
+                records,
+                (field) => field.isUtf8
+            ),
+            nestedFieldCount: ParameterRecordInventoryBuilder.#fieldCount(
+                records,
+                (field) => field.level > 0
+            ),
+            emptyEntryCount: ParameterRecordInventoryBuilder.#sum(
+                records,
+                'emptyEntryCount'
+            ),
+            typedFieldCount: ParameterRecordInventoryBuilder.#fieldCount(
+                records,
+                (field) => field.typedValue
+            )
+        }
+    }
+
+    /**
+     * Sums one numeric record field.
+     * @param {object[]} records Scanned records.
+     * @param {string} key Numeric key.
+     * @returns {number}
+     */
+    static #sum(records, key) {
+        return records.reduce((total, record) => total + Number(record[key]), 0)
+    }
+
+    /**
+     * Counts fields matching a predicate.
+     * @param {object[]} records Scanned records.
+     * @param {(field: object) => boolean} predicate Match predicate.
+     * @returns {number}
+     */
+    static #fieldCount(records, predicate) {
+        return records.reduce(
+            (total, record) =>
+                total +
+                record.fields.filter((field) => predicate(field)).length,
+            0
+        )
+    }
+
+    /**
+     * 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/ParserCompatibilityFuzzer.mjs

@@ -28,6 +28,9 @@ export class ParserCompatibilityFuzzer {
                 caseCount: cases.length,
                 failureCount: cases.filter((entry) => entry.status === 'fail')
                     .length,
+                handledErrorCount: cases.filter(
+                    (entry) => entry.status === 'handled-error'
+                ).length,
                 diagnosticCount: cases.reduce(
                     (total, entry) =>
                         total + Number(entry.diagnosticCount || 0),
@@ -40,7 +43,7 @@ export class ParserCompatibilityFuzzer {
 
     /**
      * Lists deterministic compatibility cases.
-     * @returns {{ key: string, parse: () => object }[]}
+     * @returns {{ key: string, parse: () => object, expectedError?: boolean }[]}
      */
     static #cases() {
         return [
@@ -107,18 +110,93 @@ export class ParserCompatibilityFuzzer {
                         'fuzz.PCBDwf',
                         new Uint8Array([0, 1, 2, 3]).buffer
                     )
+            },
+            {
+                key: 'empty-schdoc',
+                parse: () =>
+                    AltiumParser.parseArrayBufferToRendererModel(
+                        'empty.SchDoc',
+                        new ArrayBuffer(0)
+                    )
+            },
+            {
+                key: 'random-pcbdoc',
+                parse: () =>
+                    AltiumParser.parseArrayBufferToRendererModel(
+                        'random.PcbDoc',
+                        ParserCompatibilityFuzzer.#byteBuffer([
+                            0, 17, 65, 127, 128, 255, 42, 3
+                        ])
+                    )
+            },
+            {
+                key: 'random-pcblib',
+                parse: () =>
+                    AltiumParser.parseArrayBufferToRendererModel(
+                        'random.PcbLib',
+                        ParserCompatibilityFuzzer.#byteBuffer([
+                            9, 8, 7, 6, 5, 4, 3, 2
+                        ])
+                    )
+            },
+            {
+                key: 'random-intlib',
+                expectedError: true,
+                parse: () =>
+                    AltiumParser.parseArrayBufferToRendererModel(
+                        'random.IntLib',
+                        ParserCompatibilityFuzzer.#byteBuffer([
+                            1, 35, 69, 103, 137, 171, 205, 239
+                        ])
+                    )
+            },
+            {
+                key: 'wrong-reader-schdoc-as-intlib',
+                expectedError: true,
+                parse: () =>
+                    AltiumParser.parseArrayBufferToRendererModel(
+                        'wrong-reader.IntLib',
+                        ParserCompatibilityFuzzer.#encodeText(
+                            '|HEADER=Schematic Document|' +
+                                '|RECORD=31|CustomX=120|CustomY=80|'
+                        )
+                    )
+            },
+            {
+                key: 'unknown-extension-fallback',
+                parse: () =>
+                    AltiumParser.parseArrayBufferToRendererModel(
+                        'unknown.bin',
+                        ParserCompatibilityFuzzer.#encodeText(
+                            '|RECORD=1|NET=FALLBACK|'
+                        )
+                    )
             }
         ]
     }
 
     /**
      * Executes one compatibility case.
-     * @param {{ key: string, parse: () => object }} entry Case descriptor.
+     * @param {{ key: string, parse: () => object, expectedError?: boolean }} entry Case descriptor.
      * @returns {object}
      */
     static #runCase(entry) {
         try {
             const model = entry.parse()
+            if (entry.expectedError) {
+                return {
+                    key: entry.key,
+                    status: 'fail',
+                    expectedError: true,
+                    diagnosticCount: 1,
+                    error: {
+                        name: 'ExpectedError',
+                        message:
+                            'Parser case was expected to fail in a controlled way.'
+                    }
+                }
+            }
+
             return {
                 key: entry.key,
                 status: 'pass',
@@ -130,6 +208,19 @@ export class ParserCompatibilityFuzzer {
                 )
             }
         } catch (error) {
+            if (entry.expectedError) {
+                return {
+                    key: entry.key,
+                    status: 'handled-error',
+                    expectedError: true,
+                    diagnosticCount: 1,
+                    error: {
+                        name: error?.name || 'Error',
+                        message: error?.message || String(error)
+                    }
+                }
+            }
+
             return {
                 key: entry.key,
                 status: 'fail',
@@ -168,6 +259,19 @@ export class ParserCompatibilityFuzzer {
         )
     }
 
+    /**
+     * Builds an ArrayBuffer from stable synthetic bytes.
+     * @param {number[]} values Byte values.
+     * @returns {ArrayBuffer}
+     */
+    static #byteBuffer(values) {
+        const bytes = new Uint8Array(values)
+        return bytes.buffer.slice(
+            bytes.byteOffset,
+            bytes.byteOffset + bytes.length
+        )
+    }
+
     /**
      * Builds a schematic payload with one Windows-1252 punctuation byte.
      * @returns {ArrayBuffer}

package/src/core/altium/ParserDiagnosticNormalizer.mjs

@@ -0,0 +1,213 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+const DIAGNOSTIC_METADATA_KEYS = Object.freeze([
+    'source',
+    'sourceStorage',
+    'sourceStream',
+    'fileName',
+    'recordIndex',
+    'recordType',
+    'fieldName',
+    'contextKey',
+    'errorKind'
+])
+
+/**
+ * Normalizes parser diagnostics into one reusable, machine-readable envelope.
+ */
+export class ParserDiagnosticNormalizer {
+    static SCHEMA = 'altium-toolkit.parser-diagnostics.a1'
+
+    /**
+     * Normalizes one diagnostic entry.
+     * @param {object | string | Error} diagnostic Diagnostic entry.
+     * @param {object} [defaults] Default metadata applied when absent.
+     * @returns {object}
+     */
+    static normalize(diagnostic, defaults = {}) {
+        const source = ParserDiagnosticNormalizer.#diagnosticObject(diagnostic)
+        const message = ParserDiagnosticNormalizer.#message(source, defaults)
+        const normalized = {
+            code: ParserDiagnosticNormalizer.#code(source, defaults, message),
+            severity: ParserDiagnosticNormalizer.#severity(source, defaults),
+            message
+        }
+
+        for (const key of DIAGNOSTIC_METADATA_KEYS) {
+            const value =
+                source[key] === undefined ? defaults[key] : source[key]
+            if (value === undefined || value === null || value === '') {
+                continue
+            }
+
+            normalized[key] =
+                key === 'recordIndex'
+                    ? ParserDiagnosticNormalizer.#recordIndex(value)
+                    : value
+        }
+
+        for (const [key, value] of Object.entries(source)) {
+            if (
+                key === 'code' ||
+                key === 'severity' ||
+                key === 'message' ||
+                DIAGNOSTIC_METADATA_KEYS.includes(key) ||
+                value === undefined
+            ) {
+                continue
+            }
+
+            normalized[key] = value
+        }
+
+        return normalized
+    }
+
+    /**
+     * Normalizes a diagnostic list.
+     * @param {(object | string | Error)[]} diagnostics Diagnostic entries.
+     * @param {object} [defaults] Default metadata applied when absent.
+     * @returns {object[]}
+     */
+    static normalizeMany(diagnostics, defaults = {}) {
+        return (diagnostics || []).map((diagnostic) =>
+            ParserDiagnosticNormalizer.normalize(diagnostic, defaults)
+        )
+    }
+
+    /**
+     * Builds a structured diagnostic report.
+     * @param {{ diagnostics?: (object | string | Error)[], defaults?: object } | (object | string | Error)[]} [input]
+     * @returns {object}
+     */
+    static buildReport(input = {}) {
+        const diagnostics = Array.isArray(input)
+            ? input
+            : input.diagnostics || []
+        const defaults = Array.isArray(input) ? {} : input.defaults || {}
+        const normalized = ParserDiagnosticNormalizer.normalizeMany(
+            diagnostics,
+            defaults
+        )
+
+        return {
+            schema: ParserDiagnosticNormalizer.SCHEMA,
+            summary: ParserDiagnosticNormalizer.summarize(normalized),
+            diagnostics: normalized
+        }
+    }
+
+    /**
+     * Summarizes normalized diagnostics by severity.
+     * @param {object[]} diagnostics Normalized diagnostics.
+     * @returns {{ diagnosticCount: number, infoCount: number, warningCount: number, errorCount: number }}
+     */
+    static summarize(diagnostics) {
+        const rows = diagnostics || []
+
+        return {
+            diagnosticCount: rows.length,
+            infoCount: rows.filter(
+                (diagnostic) => diagnostic.severity === 'info'
+            ).length,
+            warningCount: rows.filter(
+                (diagnostic) => diagnostic.severity === 'warning'
+            ).length,
+            errorCount: rows.filter(
+                (diagnostic) => diagnostic.severity === 'error'
+            ).length
+        }
+    }
+
+    /**
+     * Converts supported diagnostic inputs into plain objects.
+     * @param {object | string | Error} diagnostic Diagnostic entry.
+     * @returns {object}
+     */
+    static #diagnosticObject(diagnostic) {
+        if (diagnostic instanceof Error) {
+            const source = {
+                severity: 'error',
+                message: diagnostic.message
+            }
+
+            for (const [key, value] of Object.entries(diagnostic)) {
+                if (key === 'name' || key === 'stack' || key === 'cause') {
+                    continue
+                }
+
+                source[key] = value
+            }
+
+            return source
+        }
+
+        if (typeof diagnostic === 'string') {
+            return { message: diagnostic }
+        }
+
+        return diagnostic && typeof diagnostic === 'object' ? diagnostic : {}
+    }
+
+    /**
+     * Resolves one diagnostic message.
+     * @param {object} diagnostic Diagnostic object.
+     * @param {object} defaults Default metadata.
+     * @returns {string}
+     */
+    static #message(diagnostic, defaults) {
+        return String(
+            diagnostic.message || defaults.message || 'Parser diagnostic'
+        )
+    }
+
+    /**
+     * Resolves one stable diagnostic code.
+     * @param {object} diagnostic Diagnostic object.
+     * @param {object} defaults Default metadata.
+     * @param {string} message Normalized message.
+     * @returns {string}
+     */
+    static #code(diagnostic, defaults, message) {
+        const explicitCode = String(
+            diagnostic.code || defaults.code || ''
+        ).trim()
+        if (explicitCode) return explicitCode
+
+        const slug = message
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/gu, '.')
+            .replace(/^\.+|\.+$/gu, '')
+            .slice(0, 80)
+
+        return 'parser.' + (slug || 'diagnostic')
+    }
+
+    /**
+     * Resolves one normalized severity.
+     * @param {object} diagnostic Diagnostic object.
+     * @param {object} defaults Default metadata.
+     * @returns {'info' | 'warning' | 'error'}
+     */
+    static #severity(diagnostic, defaults) {
+        const value = String(diagnostic.severity || defaults.severity || 'info')
+            .trim()
+            .toLowerCase()
+
+        if (value === 'warn' || value === 'warning') return 'warning'
+        if (value === 'error' || value === 'fatal') return 'error'
+        return 'info'
+    }
+
+    /**
+     * Normalizes a record index while preserving nonnumeric identifiers.
+     * @param {unknown} value Record index value.
+     * @returns {number | unknown}
+     */
+    static #recordIndex(value) {
+        const numeric = Number(value)
+        return Number.isInteger(numeric) ? numeric : value
+    }
+}