altium-toolkit 1.0.9 → 1.1.0

package/src/core/altium/PcbStatisticsBuilder.mjs

@@ -14,6 +14,15 @@ export class PcbStatisticsBuilder {
     static build(pcb) {
         return {
             schema: 'altium-toolkit.pcb.statistics.a1',
+            units: {
+                coordinate: 'mil',
+                length: 'mil',
+                board: 'mil',
+                drill: 'mil',
+                thickness: 'mil',
+                copperWeight: 'oz',
+                angle: 'deg'
+            },
             board: PcbStatisticsBuilder.#boardStats(pcb?.boardOutline || {}),
             drills: PcbStatisticsBuilder.#drillStats(
                 pcb?.pads || [],

package/src/core/altium/PrintableTextDecoder.mjs

@@ -12,6 +12,36 @@ export class PrintableTextDecoder {
         0x9c, 0x9e, 0x9f
     ])
 
+    static #WINDOWS_1252_CONTROL_CODE_POINTS = new Map([
+        [0x80, 0x20ac],
+        [0x82, 0x201a],
+        [0x83, 0x0192],
+        [0x84, 0x201e],
+        [0x85, 0x2026],
+        [0x86, 0x2020],
+        [0x87, 0x2021],
+        [0x88, 0x02c6],
+        [0x89, 0x2030],
+        [0x8a, 0x0160],
+        [0x8b, 0x2039],
+        [0x8c, 0x0152],
+        [0x8e, 0x017d],
+        [0x91, 0x2018],
+        [0x92, 0x2019],
+        [0x93, 0x201c],
+        [0x94, 0x201d],
+        [0x95, 0x2022],
+        [0x96, 0x2013],
+        [0x97, 0x2014],
+        [0x98, 0x02dc],
+        [0x99, 0x2122],
+        [0x9a, 0x0161],
+        [0x9b, 0x203a],
+        [0x9c, 0x0153],
+        [0x9e, 0x017e],
+        [0x9f, 0x0178]
+    ])
+
     /**
      * Returns printable ASCII-like runs from a binary buffer.
      * @param {ArrayBuffer} arrayBuffer
@@ -93,7 +123,7 @@ export class PrintableTextDecoder {
             preferredEncoding === 'cp1252'
         ) {
             return (
-                PrintableTextDecoder.#tryDecode(bytes, 'windows-1252') ||
+                PrintableTextDecoder.#tryDecodeWindows1252(bytes) ||
                 new TextDecoder('utf-8').decode(bytes)
             )
         }
@@ -104,10 +134,8 @@ export class PrintableTextDecoder {
         }
 
         if (PrintableTextDecoder.#hasWindows1252PreferredBytes(bytes)) {
-            const windows1252 = PrintableTextDecoder.#tryDecode(
-                bytes,
-                'windows-1252'
-            )
+            const windows1252 =
+                PrintableTextDecoder.#tryDecodeWindows1252(bytes)
             if (windows1252 !== null) {
                 return windows1252
             }
@@ -115,7 +143,7 @@ export class PrintableTextDecoder {
 
         return (
             PrintableTextDecoder.#tryDecode(bytes, 'gb18030') ||
-            PrintableTextDecoder.#tryDecode(bytes, 'windows-1252') ||
+            PrintableTextDecoder.#tryDecodeWindows1252(bytes) ||
             new TextDecoder('utf-8').decode(bytes)
         )
     }
@@ -203,4 +231,40 @@ export class PrintableTextDecoder {
             return null
         }
     }
+
+    /**
+     * Tries a Windows-1252 decode and normalizes runtimes that expose C1 bytes
+     * as control characters instead of punctuation.
+     * @param {Uint8Array} bytes
+     * @returns {string | null}
+     */
+    static #tryDecodeWindows1252(bytes) {
+        const decoded = PrintableTextDecoder.#tryDecode(bytes, 'windows-1252')
+        if (decoded === null) return null
+
+        return PrintableTextDecoder.#normalizeWindows1252Controls(decoded)
+    }
+
+    /**
+     * Maps Windows-1252 control-range punctuation to stable Unicode code
+     * points across Node/ICU builds.
+     * @param {string} text
+     * @returns {string}
+     */
+    static #normalizeWindows1252Controls(text) {
+        let normalized = ''
+
+        for (const character of text) {
+            const codePoint = character.codePointAt(0)
+            const windows1252CodePoint =
+                PrintableTextDecoder.#WINDOWS_1252_CONTROL_CODE_POINTS.get(
+                    codePoint
+                )
+            normalized += String.fromCodePoint(
+                windows1252CodePoint || codePoint
+            )
+        }
+
+        return normalized
+    }
 }

package/src/core/altium/PrjPcbModelParser.mjs

@@ -4,6 +4,7 @@
 
 import { NormalizedModelSchema } from './NormalizedModelSchema.mjs'
 import { ProjectOutJobDigestBuilder } from './ProjectOutJobDigestBuilder.mjs'
+import { ProjectDocumentGraphBuilder } from './ProjectDocumentGraphBuilder.mjs'
 
 /**
  * Parses Altium PrjPcb INI-style project files into a normalized project
@@ -58,6 +59,11 @@ export class PrjPcbModelParser {
             documents,
             outputGroups
         })
+        const documentGraph = ProjectDocumentGraphBuilder.build({
+            documents,
+            documentGroups,
+            outputGroups
+        })
         const summary = PrjPcbModelParser.#buildSummary(
             fileName,
             documents,
@@ -87,6 +93,7 @@ export class PrjPcbModelParser {
                 configurations,
                 outputGroups,
                 outJobDigest,
+                documentGraph,
                 classGeneration,
                 sections: PrjPcbModelParser.#serializeSections(sections)
             },
@@ -229,6 +236,9 @@ export class PrjPcbModelParser {
             integratedLibraries: documents.filter(
                 (document) => document.kind === 'integrated-library'
             ),
+            harnessFiles: documents.filter(
+                (document) => document.kind === 'harness'
+            ),
             outJobs: documents.filter(
                 (document) => document.kind === 'output-job'
             ),
@@ -699,7 +709,18 @@ export class PrjPcbModelParser {
                 PrjPcbModelParser.#stringField(fields, 'OutputType' + index) ||
                 ''
             if (!type) continue
-            rows.push({
+            const targetPath =
+                PrjPcbModelParser.#stringField(
+                    fields,
+                    'OutputTargetPath' + index
+                ) ||
+                PrjPcbModelParser.#stringField(fields, 'OutputPath' + index) ||
+                ''
+            const configRows = PrjPcbModelParser.#extractOutputConfigRows(
+                fields,
+                index
+            )
+            const row = {
                 index,
                 type,
                 name:
@@ -721,7 +742,50 @@ export class PrjPcbModelParser {
                     fields,
                     'OutputDefault' + index
                 )
-            })
+            }
+            if (targetPath) row.targetPath = targetPath
+            if (configRows.length) row.configRows = configRows
+            rows.push(row)
+        }
+
+        return rows
+    }
+
+    /**
+     * Extracts output configuration rows associated with one output index.
+     * @param {Record<string, string | string[]>} fields Output group fields.
+     * @param {number} outputIndex Output row index.
+     * @returns {{ key: string, record: string, fields: Record<string, string> }[]}
+     */
+    static #extractOutputConfigRows(fields, outputIndex) {
+        const rows = []
+        const patterns = [
+            new RegExp('^Configuration' + outputIndex + '_Item\\d+$', 'i'),
+            new RegExp(
+                '^OutputConfiguration(?:Parameter)?' +
+                    outputIndex +
+                    '(?:_Item\\d+)?$',
+                'i'
+            )
+        ]
+
+        for (const key of Object.keys(fields || {}).sort((left, right) =>
+            left.localeCompare(right, undefined, { numeric: true })
+        )) {
+            if (!patterns.some((pattern) => pattern.test(key))) continue
+            const values = Array.isArray(fields[key])
+                ? fields[key]
+                : [fields[key]]
+            for (const value of values) {
+                const parsed = PrjPcbModelParser.#parsePipeFields(value)
+                const record = parsed.Record || ''
+                delete parsed.Record
+                rows.push({
+                    key,
+                    record,
+                    fields: parsed
+                })
+            }
         }
 
         return rows
@@ -986,6 +1050,9 @@ export class PrjPcbModelParser {
                 return 'pcb-library'
             case '.intlib':
                 return 'integrated-library'
+            case '.harness':
+            case '.harnessdoc':
+                return 'harness'
             case '.outjob':
                 return 'output-job'
             default:

package/src/core/altium/PrjScrModelParser.mjs

@@ -0,0 +1,386 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { NormalizedModelSchema } from './NormalizedModelSchema.mjs'
+import { ParserUtils } from './ParserUtils.mjs'
+
+/**
+ * Parses Altium script-project files into a read-only project-script digest.
+ */
+export class PrjScrModelParser {
+    /**
+     * Parses one script-project ArrayBuffer.
+     * @param {string} fileName Source file name.
+     * @param {ArrayBuffer} arrayBuffer Source bytes.
+     * @param {{ existingPaths?: string[] }} options Parser options.
+     * @returns {object}
+     */
+    static parse(fileName, arrayBuffer, options = {}) {
+        return PrjScrModelParser.parseText(
+            fileName,
+            PrjScrModelParser.#decodeText(arrayBuffer),
+            options
+        )
+    }
+
+    /**
+     * Parses one script-project text payload.
+     * @param {string} fileName Source file name.
+     * @param {string} text Source text.
+     * @param {{ existingPaths?: string[] }} options Parser options.
+     * @returns {object}
+     */
+    static parseText(fileName, text, options = {}) {
+        const sections = PrjScrModelParser.#parseIniSections(text)
+        const design = PrjScrModelParser.#sectionFields(
+            PrjScrModelParser.#findSection(sections, 'Design')
+        )
+        const existingPaths = new Set(
+            (options.existingPaths || []).map((path) =>
+                PrjScrModelParser.#normalizePath(path)
+            )
+        )
+        const documents = PrjScrModelParser.#extractDocuments(
+            sections,
+            existingPaths,
+            options
+        )
+        const scripts = documents
+            .filter((document) => document.kind === 'script')
+            .map((document) => PrjScrModelParser.#publicScript(document))
+        const diagnostics = PrjScrModelParser.#diagnostics(documents)
+
+        return NormalizedModelSchema.attach({
+            kind: 'project-script',
+            fileType: 'PrjScr',
+            fileName,
+            summary: {
+                title: ParserUtils.stripExtension(fileName),
+                documentCount: documents.length,
+                scriptCount: scripts.length,
+                missingPathCount: scripts.filter(
+                    (script) => script.exists === false
+                ).length,
+                diagnosticCount: diagnostics.length
+            },
+            diagnostics,
+            projectScript: {
+                name: ParserUtils.stripExtension(fileName),
+                design,
+                documents,
+                scripts,
+                sections: PrjScrModelParser.#serializeSections(sections)
+            },
+            bom: []
+        })
+    }
+
+    /**
+     * Decodes text with common project-file encodings.
+     * @param {ArrayBuffer} arrayBuffer Source bytes.
+     * @returns {string}
+     */
+    static #decodeText(arrayBuffer) {
+        const bytes = new Uint8Array(arrayBuffer || new ArrayBuffer(0))
+        for (const encoding of ['utf-8', 'windows-1252']) {
+            try {
+                return new TextDecoder(encoding, { fatal: true })
+                    .decode(bytes)
+                    .replace(/^\uFEFF/u, '')
+            } catch {
+                // Try the next legacy-compatible project encoding.
+            }
+        }
+
+        return new TextDecoder('windows-1252')
+            .decode(bytes)
+            .replace(/^\uFEFF/u, '')
+    }
+
+    /**
+     * Parses INI sections while preserving option order.
+     * @param {string} text Source text.
+     * @returns {{ name: string, index: number, entries: object[] }[]}
+     */
+    static #parseIniSections(text) {
+        const sections = []
+        let current = null
+        const lines = String(text || '')
+            .replace(/\r\n?/gu, '\n')
+            .split('\n')
+
+        for (const [lineIndex, rawLine] of lines.entries()) {
+            const trimmed = rawLine.trim()
+            if (
+                !trimmed ||
+                trimmed.startsWith(';') ||
+                trimmed.startsWith('#')
+            ) {
+                continue
+            }
+
+            const sectionMatch = /^\[([^\]]+)\]$/u.exec(trimmed)
+            if (sectionMatch) {
+                current = {
+                    name: sectionMatch[1].trim(),
+                    index: sections.length,
+                    entries: []
+                }
+                sections.push(current)
+                continue
+            }
+
+            if (!current) continue
+            const separatorIndex = rawLine.indexOf('=')
+            if (separatorIndex < 0) continue
+
+            current.entries.push({
+                key: rawLine.slice(0, separatorIndex).trim(),
+                value: rawLine.slice(separatorIndex + 1).trim(),
+                line: lineIndex + 1
+            })
+        }
+
+        return sections
+    }
+
+    /**
+     * Extracts numbered document entries.
+     * @param {object[]} sections Parsed sections.
+     * @param {Set<string>} existingPaths Normalized existing paths.
+     * @param {{ existingPaths?: string[] }} options Parser options.
+     * @returns {object[]}
+     */
+    static #extractDocuments(sections, existingPaths, options) {
+        return PrjScrModelParser.#numberedSections(sections, 'Document').map(
+            ({ section, number }) => {
+                const fields = PrjScrModelParser.#sectionFields(section)
+                const path = String(fields.DocumentPath || '')
+                const normalizedPath = PrjScrModelParser.#normalizePath(path)
+                const base = {
+                    index: number,
+                    section: section.name,
+                    path,
+                    normalizedPath,
+                    fileName: PrjScrModelParser.#basename(path),
+                    extension: PrjScrModelParser.#extension(path),
+                    kind:
+                        PrjScrModelParser.#extension(path).toLowerCase() ===
+                        '.pas'
+                            ? 'script'
+                            : 'unsupported',
+                    ...(options.existingPaths
+                        ? { exists: existingPaths.has(normalizedPath) }
+                        : {}),
+                    annotationEnabled: PrjScrModelParser.#optionalBoolean(
+                        fields.AnnotationEnabled
+                    ),
+                    classGeneration: PrjScrModelParser.#classGeneration(fields),
+                    updatePolicies: PrjScrModelParser.#updatePolicies(fields),
+                    options: fields
+                }
+
+                return PrjScrModelParser.#stripEmpty(base)
+            }
+        )
+    }
+
+    /**
+     * Builds class-generation option metadata.
+     * @param {Record<string, string>} fields Document fields.
+     * @returns {object | undefined}
+     */
+    static #classGeneration(fields) {
+        return PrjScrModelParser.#stripEmpty({
+            classGenCcAutoEnabled: PrjScrModelParser.#optionalBoolean(
+                fields.ClassGenCCAutoEnabled
+            ),
+            classGenCcAutoRoomEnabled: PrjScrModelParser.#optionalBoolean(
+                fields.ClassGenCCAutoRoomEnabled
+            ),
+            classGenNcAutoScope: fields.ClassGenNCAutoScope
+        })
+    }
+
+    /**
+     * Builds update-policy metadata.
+     * @param {Record<string, string>} fields Document fields.
+     * @returns {object | undefined}
+     */
+    static #updatePolicies(fields) {
+        return PrjScrModelParser.#stripEmpty({
+            doLibraryUpdate: PrjScrModelParser.#optionalBoolean(
+                fields.DoLibraryUpdate
+            ),
+            doDatabaseUpdate: PrjScrModelParser.#optionalBoolean(
+                fields.DoDatabaseUpdate
+            )
+        })
+    }
+
+    /**
+     * Builds structured parser diagnostics.
+     * @param {object[]} documents Parsed documents.
+     * @returns {object[]}
+     */
+    static #diagnostics(documents) {
+        return [
+            ...documents
+                .filter(
+                    (document) =>
+                        document.kind === 'script' && document.exists === false
+                )
+                .map((document) => ({
+                    code: 'project-script.missing-document-path',
+                    severity: 'warning',
+                    message: 'Script project document path was not found.',
+                    path: document.path,
+                    normalizedPath: document.normalizedPath
+                })),
+            ...documents
+                .filter((document) => document.kind === 'unsupported')
+                .map((document) => ({
+                    code: 'project-script.unsupported-document-kind',
+                    severity: 'warning',
+                    message:
+                        'Script project document is not a supported script file.',
+                    path: document.path,
+                    normalizedPath: document.normalizedPath
+                }))
+        ]
+    }
+
+    /**
+     * Builds the public script convenience row.
+     * @param {object} document Parsed document row.
+     * @returns {object}
+     */
+    static #publicScript(document) {
+        const { kind: _kind, ...script } = document
+        return script
+    }
+
+    /**
+     * Finds numbered sections with a common prefix.
+     * @param {object[]} sections Parsed sections.
+     * @param {string} prefix Section prefix.
+     * @returns {{ section: object, number: number }[]}
+     */
+    static #numberedSections(sections, prefix) {
+        const pattern = new RegExp('^' + prefix + '(\\d+)$', 'iu')
+
+        return (sections || [])
+            .map((section) => ({
+                section,
+                match: pattern.exec(section.name)
+            }))
+            .filter(({ match }) => match)
+            .map(({ section, match }) => ({
+                section,
+                number: Number.parseInt(match[1], 10)
+            }))
+            .sort((left, right) => left.number - right.number)
+    }
+
+    /**
+     * Finds one section by case-insensitive name.
+     * @param {object[]} sections Parsed sections.
+     * @param {string} name Section name.
+     * @returns {object | undefined}
+     */
+    static #findSection(sections, name) {
+        const normalized = String(name || '').toLowerCase()
+        return (sections || []).find(
+            (section) => section.name.toLowerCase() === normalized
+        )
+    }
+
+    /**
+     * Converts one section to a key-value map.
+     * @param {{ entries?: { key: string, value: string }[] } | undefined} section Parsed section.
+     * @returns {Record<string, string>}
+     */
+    static #sectionFields(section) {
+        return Object.fromEntries(
+            (section?.entries || []).map((entry) => [entry.key, entry.value])
+        )
+    }
+
+    /**
+     * Serializes preserved sections.
+     * @param {object[]} sections Parsed sections.
+     * @returns {object[]}
+     */
+    static #serializeSections(sections) {
+        return (sections || []).map((section) => ({
+            name: section.name,
+            entries: (section.entries || []).map((entry) => ({
+                key: entry.key,
+                value: entry.value
+            }))
+        }))
+    }
+
+    /**
+     * Parses optional boolean option values.
+     * @param {string | undefined} value Raw value.
+     * @returns {boolean | undefined}
+     */
+    static #optionalBoolean(value) {
+        const normalized = String(value ?? '')
+            .trim()
+            .toLowerCase()
+        if (!normalized) return undefined
+        return ['1', 'true', 't', 'yes'].includes(normalized)
+    }
+
+    /**
+     * Normalizes project-relative paths.
+     * @param {string} path Source path.
+     * @returns {string}
+     */
+    static #normalizePath(path) {
+        return String(path || '').replace(/\\/gu, '/')
+    }
+
+    /**
+     * Returns a basename from a project path.
+     * @param {string} path Source path.
+     * @returns {string}
+     */
+    static #basename(path) {
+        return PrjScrModelParser.#normalizePath(path).split('/').pop() || ''
+    }
+
+    /**
+     * Returns a lower-level extension token.
+     * @param {string} path Source path.
+     * @returns {string}
+     */
+    static #extension(path) {
+        const name = PrjScrModelParser.#basename(path)
+        const dotIndex = name.lastIndexOf('.')
+        return dotIndex >= 0 ? name.slice(dotIndex) : ''
+    }
+
+    /**
+     * Removes undefined and empty object fields.
+     * @param {Record<string, unknown>} value Source object.
+     * @returns {object}
+     */
+    static #stripEmpty(value) {
+        return Object.fromEntries(
+            Object.entries(value || {}).filter(([, entryValue]) => {
+                if (
+                    entryValue &&
+                    typeof entryValue === 'object' &&
+                    !Array.isArray(entryValue)
+                ) {
+                    return Object.keys(entryValue).length > 0
+                }
+                return entryValue !== undefined && entryValue !== ''
+            })
+        )
+    }
+}