altium-toolkit 1.1.41 → 1.2.0

package/src/convergence/Parser.mjs

@@ -0,0 +1,285 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import {
+    ToolkitDiagnostic,
+    ToolkitError,
+    ToolkitProgress
+} from 'circuitjson-toolkit/parser'
+
+import { AltiumDocumentBuilder } from './AltiumDocumentBuilder.mjs'
+import { AltiumWorkerClient } from './AltiumWorkerClient.mjs'
+import { ParserInput } from './ParserInput.mjs'
+
+const ABORTED_GETTER = Object.getOwnPropertyDescriptor(
+    AbortSignal.prototype,
+    'aborted'
+)?.get
+const PROGRESS_MESSAGES = {
+    detect: 'Detecting Altium input.',
+    decode: 'Decoding native Altium data.',
+    validate: 'Validating canonical CircuitJSON.',
+    complete: 'Altium parsing complete.'
+}
+const SUPPORTED_EXTENSION_IDS = new Set([
+    'altium.native-model',
+    'altium.project-context'
+])
+
+/**
+ * Parses native Altium inputs into canonical CircuitJSON document envelopes.
+ */
+export class Parser {
+    /**
+     * Parses one input synchronously.
+     * @param {Record<string, any>} input Common parser input.
+     * @param {Record<string, any>} [options] Common parser options.
+     * @returns {Record<string, any>} Canonical document.
+     */
+    static parse(input, options = {}) {
+        try {
+            const normalized = ParserInput.normalize(input, options)
+            if (normalized.options.worker === true) {
+                throw Parser.#error(
+                    'Synchronous Altium parsing cannot use a worker.',
+                    'ERR_WORKER_SYNC_UNAVAILABLE',
+                    'unsupported',
+                    normalized.input.fileName
+                )
+            }
+            Parser.#assertSupported(normalized.input)
+            Parser.#assertExtensions(normalized)
+            Parser.#assertReports(normalized)
+            return AltiumDocumentBuilder.build(normalized)
+        } catch (error) {
+            throw Parser.#parseError(error, input)
+        }
+    }
+
+    /**
+     * Returns a discriminated parse result without throwing public failures.
+     * @param {Record<string, any>} input Common parser input.
+     * @param {Record<string, any>} [options] Common parser options.
+     * @returns {{ ok: true, value: Record<string, any> } | { ok: false, error: ToolkitError, diagnostics: object[] }} Parse result.
+     */
+    static tryParse(input, options = {}) {
+        try {
+            return { ok: true, value: Parser.parse(input, options) }
+        } catch (error) {
+            const normalized = Parser.#parseError(error, input)
+            return {
+                ok: false,
+                error: normalized,
+                diagnostics: [
+                    ToolkitDiagnostic.create({
+                        code: normalized.code,
+                        severity: 'error',
+                        message: normalized.message,
+                        source: normalized.source
+                    })
+                ]
+            }
+        }
+    }
+
+    /**
+     * Parses one input asynchronously with progress, cancellation, and workers.
+     * @param {Record<string, any>} input Common parser input.
+     * @param {Record<string, any>} [options] Common parser options.
+     * @returns {Promise<Record<string, any>>} Canonical document.
+     */
+    static async parseAsync(input, options = {}) {
+        let normalized
+        try {
+            normalized = ParserInput.normalize(input, options)
+            Parser.#assertSupported(normalized.input)
+            Parser.#assertExtensions(normalized)
+            Parser.#assertReports(normalized)
+            Parser.#assertNotCancelled(normalized)
+        } catch (error) {
+            throw Parser.#parseError(error, input)
+        }
+        const useWorker =
+            normalized.options.worker === true ||
+            (normalized.options.worker === 'auto' &&
+                normalized.options.retainSource !== 'reference' &&
+                AltiumWorkerClient.isAvailable())
+        if (useWorker) {
+            const attempt = await AltiumWorkerClient.parseAttempt(
+                normalized.input,
+                normalized.options
+            )
+            if (attempt.ok) return attempt.value
+            if (normalized.options.worker !== 'auto' || !attempt.unavailable) {
+                throw Parser.#parseError(attempt.error, input)
+            }
+            AltiumWorkerClient.dispose()
+        }
+        let progress = Parser.#progress(normalized, 'detect')
+        Parser.#assertNotCancelled(normalized)
+        progress = Parser.#progress(normalized, 'decode', progress)
+        await Promise.resolve()
+        Parser.#assertNotCancelled(normalized)
+        let decoded
+        try {
+            decoded = AltiumDocumentBuilder.decode(normalized)
+        } catch (error) {
+            throw Parser.#parseError(error, input)
+        }
+        Parser.#assertNotCancelled(normalized)
+        progress = Parser.#progress(normalized, 'validate', progress)
+        Parser.#assertNotCancelled(normalized)
+        let document
+        try {
+            document = AltiumDocumentBuilder.build(normalized, decoded)
+        } catch (error) {
+            throw Parser.#parseError(error, input)
+        }
+        Parser.#assertNotCancelled(normalized)
+        Parser.#progress(normalized, 'complete', progress)
+        Parser.#assertNotCancelled(normalized)
+        return document
+    }
+
+    /**
+     * Performs bounded Altium format detection.
+     * @param {unknown} input Parser input candidate.
+     * @returns {boolean} Whether the input is supported.
+     */
+    static supports(input) {
+        return ParserInput.supports(input)
+    }
+
+    /**
+     * Rejects unsupported report requests explicitly.
+     * @param {{ input: { fileName: string }, options: { reports: string[] } }} normalized Normalized request.
+     * @returns {void}
+     */
+    static #assertReports(normalized) {
+        if (!normalized.options.reports.length) return
+        throw Parser.#error(
+            `Altium parser report is unavailable: ${normalized.options.reports[0]}.`,
+            'ERR_CAPABILITY_UNAVAILABLE',
+            'unsupported',
+            normalized.input.fileName,
+            { reports: normalized.options.reports }
+        )
+    }
+
+    /**
+     * Rejects unknown explicitly selected extension feature ids.
+     * @param {{ input: { fileName: string }, options: { extensions: string | string[] } }} normalized Normalized request.
+     * @returns {void}
+     */
+    static #assertExtensions(normalized) {
+        if (!Array.isArray(normalized.options.extensions)) return
+        const unknown = normalized.options.extensions.find(
+            (id) => !SUPPORTED_EXTENSION_IDS.has(id)
+        )
+        if (!unknown) return
+        throw Parser.#error(
+            `Altium parser extension is unavailable: ${unknown}.`,
+            'ERR_CAPABILITY_UNAVAILABLE',
+            'unsupported',
+            normalized.input.fileName,
+            { extensions: normalized.options.extensions }
+        )
+    }
+
+    /**
+     * Rejects unsupported source names.
+     * @param {Record<string, any>} input Normalized input.
+     * @returns {void}
+     */
+    static #assertSupported(input) {
+        if (ParserInput.supports(input)) return
+        throw Parser.#error(
+            `Unsupported Altium input: ${input.fileName || '(unnamed)'}.`,
+            'ERR_FORMAT_UNSUPPORTED',
+            'unsupported',
+            input.fileName
+        )
+    }
+
+    /**
+     * Emits one ordered direct-parser progress row.
+     * @param {{ options: { onProgress?: Function } }} normalized Request.
+     * @param {'detect' | 'decode' | 'validate' | 'complete'} stage Stage.
+     * @param {Record<string, any> | null} [previous] Previous row.
+     * @returns {Record<string, any> | null} Emitted or previous row.
+     */
+    static #progress(normalized, stage, previous = null) {
+        if (!normalized.options.onProgress) return previous
+        const row = ToolkitProgress.create(
+            { stage, message: PROGRESS_MESSAGES[stage] },
+            previous
+        )
+        normalized.options.onProgress(row)
+        return row
+    }
+
+    /**
+     * Rejects an aborted direct request.
+     * @param {{ input: { fileName: string }, options: { signal?: unknown } }} normalized Request.
+     * @returns {void}
+     */
+    static #assertNotCancelled(normalized) {
+        const { signal } = normalized.options
+        if (signal === undefined || signal === null) return
+        if (!ABORTED_GETTER) {
+            throw new TypeError('AbortSignal state is unavailable.')
+        }
+        let aborted = false
+        try {
+            aborted = Boolean(Reflect.apply(ABORTED_GETTER, signal, []))
+        } catch {
+            throw new TypeError('Altium signal must be an AbortSignal.')
+        }
+        if (aborted) {
+            throw Parser.#error(
+                'Altium parsing was cancelled.',
+                'ERR_CANCELLED',
+                'cancelled',
+                normalized.input.fileName
+            )
+        }
+    }
+
+    /**
+     * Normalizes one parser failure.
+     * @param {unknown} error Failure candidate.
+     * @param {unknown} input Original input.
+     * @returns {ToolkitError} Typed failure.
+     */
+    static #parseError(error, input) {
+        if (ToolkitError.trustedRecord(error)) return error
+        return ToolkitError.from(error, {
+            code: 'ERR_ALTIUM_PARSE',
+            category: 'parse',
+            format: 'altium',
+            source: ParserInput.fileName(input)
+        })
+    }
+
+    /**
+     * Creates one typed Altium failure.
+     * @param {string} message Message.
+     * @param {string} code Stable code.
+     * @param {string} category Error category.
+     * @param {string} source Source name.
+     * @param {Record<string, any>} [details] Clone-safe details.
+     * @returns {ToolkitError} Typed failure.
+     */
+    static #error(message, code, category, source, details = {}) {
+        return new ToolkitError(message, {
+            code,
+            category,
+            format: 'altium',
+            source,
+            details
+        })
+    }
+}
+
+Object.freeze(Parser.prototype)
+Object.freeze(Parser)

package/src/convergence/ParserInput.mjs

@@ -0,0 +1,282 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+const ASSET_MODES = new Set(['none', 'metadata', 'full'])
+const EXTENSION_MODES = new Set(['none', 'metadata', 'canonical', 'full'])
+const RETAIN_SOURCE_MODES = new Set(['none', 'reference'])
+const WORKER_MODES = new Set(['auto', true, false])
+const SUPPORTED_SUFFIXES = new Set([
+    'intlib',
+    'pcbdoc',
+    'pcbdwf',
+    'pcblib',
+    'prjpcb',
+    'prjscr',
+    'schdoc',
+    'schlib'
+])
+
+/**
+ * Normalizes source-neutral parser requests for the Altium adapter.
+ */
+export class ParserInput {
+    /**
+     * Normalizes one parser input and common option record.
+     * @param {unknown} input Parser input candidate.
+     * @param {unknown} [options] Common options candidate.
+     * @returns {{ input: { fileName: string, data: string | ArrayBuffer | Uint8Array, assets: object[] }, sourceReference: object, options: Record<string, any> }} Normalized request.
+     */
+    static normalize(input, options = {}) {
+        const inputFields = ParserInput.#plainFields(
+            input,
+            'Altium parser input must be a plain object.'
+        )
+        const optionFields = ParserInput.#plainFields(
+            options,
+            'Altium parser options must be a plain object.'
+        )
+        if (!ParserInput.#isData(inputFields.data)) {
+            throw new TypeError(
+                'Altium parser data must be a string, ArrayBuffer, or Uint8Array.'
+            )
+        }
+        if (
+            inputFields.assets !== undefined &&
+            !Array.isArray(inputFields.assets)
+        ) {
+            throw new TypeError('Altium parser assets must be an array.')
+        }
+        const decodeAssets = ParserInput.#enum(
+            optionFields.decodeAssets,
+            'metadata',
+            ASSET_MODES,
+            'asset decode mode'
+        )
+        const extensions = ParserInput.#extensions(optionFields.extensions)
+        const retainSource = ParserInput.#enum(
+            optionFields.retainSource,
+            'none',
+            RETAIN_SOURCE_MODES,
+            'source retention mode'
+        )
+        const worker =
+            optionFields.worker === undefined ? 'auto' : optionFields.worker
+        if (!WORKER_MODES.has(worker)) {
+            throw new TypeError('Altium worker must be auto, true, or false.')
+        }
+        if (
+            optionFields.onProgress !== undefined &&
+            typeof optionFields.onProgress !== 'function'
+        ) {
+            throw new TypeError('Altium onProgress must be a function.')
+        }
+        return {
+            input: {
+                fileName: ParserInput.fileName(inputFields.fileName),
+                data: inputFields.data,
+                assets: inputFields.assets || []
+            },
+            sourceReference: input,
+            options: {
+                preserveRaw: optionFields.preserveRaw === true,
+                decodeAssets,
+                extensions,
+                reports: ParserInput.#stringList(optionFields.reports),
+                retainSource,
+                worker,
+                transferInput: optionFields.transferInput === true,
+                signal: optionFields.signal,
+                onProgress: optionFields.onProgress
+            }
+        }
+    }
+
+    /**
+     * Performs bounded format detection without parsing native contents.
+     * @param {unknown} input Parser input candidate.
+     * @returns {boolean} Whether the file name and payload are supported.
+     */
+    static supports(input) {
+        try {
+            const fields = ParserInput.#plainFields(
+                input,
+                'Altium parser input must be a plain object.'
+            )
+            return (
+                ParserInput.#isData(fields.data) &&
+                ParserInput.supportsFileType(
+                    ParserInput.suffix(fields.fileName)
+                )
+            )
+        } catch {
+            return false
+        }
+    }
+
+    /**
+     * Checks one already normalized lowercase file type.
+     * @param {unknown} fileType File suffix without a period.
+     * @returns {boolean} Whether the Altium parser supports the file type.
+     */
+    static supportsFileType(fileType) {
+        return SUPPORTED_SUFFIXES.has(String(fileType))
+    }
+
+    /**
+     * Returns a normalized source file name.
+     * @param {unknown} input Parser input or name.
+     * @returns {string} Normalized name.
+     */
+    static fileName(input) {
+        let value = input
+        if (input && typeof input === 'object') {
+            try {
+                value = ParserInput.#plainFields(
+                    input,
+                    'Altium parser input must be a plain object.'
+                ).fileName
+            } catch {
+                value = ''
+            }
+        }
+        return String(value || '')
+            .replaceAll('\\', '/')
+            .replace(/^\.\//u, '')
+    }
+
+    /**
+     * Returns the lowercase file suffix.
+     * @param {unknown} fileName File name candidate.
+     * @returns {string} Lowercase suffix without a period.
+     */
+    static suffix(fileName) {
+        const name = ParserInput.fileName(fileName)
+        const suffix = name.split('.').pop()
+        return suffix && suffix !== name ? suffix.toLowerCase() : ''
+    }
+
+    /**
+     * Copies the exact input byte range for the native parser.
+     * @param {string | ArrayBuffer | Uint8Array} data Parser payload.
+     * @returns {ArrayBuffer} Owned native parser buffer.
+     */
+    static arrayBuffer(data) {
+        if (typeof data === 'string')
+            return new TextEncoder().encode(data).buffer
+        if (data instanceof ArrayBuffer) return data
+        if (data instanceof Uint8Array) {
+            if (
+                data.byteOffset === 0 &&
+                data.byteLength === data.buffer.byteLength
+            ) {
+                return data.buffer
+            }
+            return data.buffer.slice(
+                data.byteOffset,
+                data.byteOffset + data.byteLength
+            )
+        }
+        throw new TypeError(
+            'Altium parser data must be a string, ArrayBuffer, or Uint8Array.'
+        )
+    }
+
+    /**
+     * Normalizes one optional enum.
+     * @param {unknown} value Candidate value.
+     * @param {string} fallback Default value.
+     * @param {Set<string>} allowed Allowed values.
+     * @param {string} label Error label.
+     * @returns {string} Normalized value.
+     */
+    static #enum(value, fallback, allowed, label) {
+        const normalized = String(value === undefined ? fallback : value)
+        if (!allowed.has(normalized)) {
+            throw new TypeError(`Unsupported Altium ${label}: ${normalized}.`)
+        }
+        return normalized
+    }
+
+    /**
+     * Normalizes the extension selection contract.
+     * @param {unknown} value Candidate value.
+     * @returns {string | string[]} Normalized extension selection.
+     */
+    static #extensions(value) {
+        if (Array.isArray(value)) return ParserInput.#stringList(value)
+        return ParserInput.#enum(
+            value,
+            'canonical',
+            EXTENSION_MODES,
+            'extension mode'
+        )
+    }
+
+    /**
+     * Normalizes one unique nonempty string list.
+     * @param {unknown} value List candidate.
+     * @returns {string[]} Normalized values.
+     */
+    static #stringList(value) {
+        if (value === undefined) return []
+        if (!Array.isArray(value)) {
+            throw new TypeError('Altium option list must be an array.')
+        }
+        const values = []
+        const seen = new Set()
+        for (let index = 0; index < value.length; index += 1) {
+            const normalized = String(value[index]).trim()
+            if (!normalized) {
+                throw new TypeError('Altium option ids must not be empty.')
+            }
+            if (!seen.has(normalized)) {
+                seen.add(normalized)
+                values.push(normalized)
+            }
+        }
+        return values
+    }
+
+    /**
+     * Returns whether a payload uses one common binary/text input type.
+     * @param {unknown} value Payload candidate.
+     * @returns {boolean} True for supported payload values.
+     */
+    static #isData(value) {
+        return (
+            typeof value === 'string' ||
+            value instanceof ArrayBuffer ||
+            value instanceof Uint8Array
+        )
+    }
+
+    /**
+     * Reads one accessor-free plain record.
+     * @param {unknown} value Record candidate.
+     * @param {string} message Failure message.
+     * @returns {Record<string, any>} Own field values.
+     */
+    static #plainFields(value, message) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new TypeError(message)
+        }
+        const prototype = Object.getPrototypeOf(value)
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(message)
+        }
+        const descriptors = Object.getOwnPropertyDescriptors(value)
+        const fields = Object.create(null)
+        for (const [name, descriptor] of Object.entries(descriptors)) {
+            if (!Object.hasOwn(descriptor, 'value')) {
+                throw new TypeError(
+                    'Accessor-backed parser fields are invalid.'
+                )
+            }
+            fields[name] = descriptor.value
+        }
+        return fields
+    }
+}
+
+Object.freeze(ParserInput.prototype)
+Object.freeze(ParserInput)