circuitjson-toolkit 1.0.16 → 1.1.0

package/src/core/ManufacturingService.mjs

@@ -0,0 +1,323 @@
+import { CircuitJsonManufacturingBuilder } from './CircuitJsonManufacturingBuilder.mjs'
+import { CircuitJsonManufacturingDownloadBuilder } from './CircuitJsonManufacturingDownloadBuilder.mjs'
+import { CircuitJsonDocumentContext } from './context/CircuitJsonDocumentContext.mjs'
+import { ToolkitError } from './contracts/ToolkitError.mjs'
+
+const EXPORTS = [
+    {
+        id: 'fabrication-notes-json',
+        format: 'json',
+        mediaType: 'application/json;charset=utf-8',
+        fileExtension: '.json'
+    },
+    {
+        id: 'pick-place-csv',
+        format: 'csv',
+        mediaType: 'text/csv;charset=utf-8',
+        fileExtension: '.csv'
+    },
+    {
+        id: 'routing-dsn',
+        format: 'specctra-dsn',
+        mediaType: 'application/specctra-dsn',
+        fileExtension: '.dsn'
+    }
+]
+const ROUTING_TYPES = [
+    'pcb_board',
+    'pcb_component',
+    'pcb_smtpad',
+    'pcb_trace',
+    'pcb_via',
+    'pcb_plated_hole',
+    'pcb_trace_hint',
+    'pcb_breakout_point',
+    'source_net'
+]
+
+/**
+ * Exposes lazy CircuitJSON manufacturing inspection and export services.
+ */
+export class ManufacturingService {
+    /**
+     * Inspects canonical placement and fabrication metadata.
+     * @param {unknown} document DocumentInput or prepared context.
+     * @param {Record<string, any>} [options] Reserved service options.
+     * @returns {{ schema: string, placements: object[], fabricationNotes: object[], exports: object[], diagnostics: object[], statistics: object }} Manufacturing inspection.
+     */
+    static inspect(document, options = {}) {
+        const context = ManufacturingService.#context(document, options)
+        const manufacturing = ManufacturingService.#build(context)
+        return {
+            schema: 'ecad-toolkit.manufacturing.v1',
+            placements: structuredClone(manufacturing.pickAndPlaceRows),
+            fabricationNotes: structuredClone(manufacturing.fabricationNotes),
+            exports: ManufacturingService.#exports(manufacturing, context),
+            diagnostics: [],
+            statistics: ManufacturingService.#statistics(context)
+        }
+    }
+
+    /**
+     * Lists every canonical manufacturing export and its availability.
+     * @param {unknown} document DocumentInput or prepared context.
+     * @param {Record<string, any>} [options] Reserved service options.
+     * @returns {object[]} Detached export capability rows.
+     */
+    static listExports(document, options = {}) {
+        const context = ManufacturingService.#context(document, options)
+        const manufacturing = ManufacturingService.#build(context)
+        return ManufacturingService.#exports(manufacturing, context)
+    }
+
+    /**
+     * Builds one available canonical manufacturing file.
+     * @param {unknown} document DocumentInput or prepared context.
+     * @param {Record<string, any>} request Export request.
+     * @param {Record<string, any>} [options] Reserved service options.
+     * @returns {{ fileName: string, mediaType: string, data: Uint8Array, diagnostics: object[] }} File result.
+     */
+    static export(document, request, options = {}) {
+        const normalized = ManufacturingService.#request(request)
+        const context = ManufacturingService.#context(document, options)
+        const manufacturing = ManufacturingService.#build(context)
+        const capability = ManufacturingService.#exports(
+            manufacturing,
+            context
+        ).find((entry) => entry.id === normalized.id)
+        if (!capability || capability.status !== 'available') {
+            throw ManufacturingService.#unavailable(capability?.reason)
+        }
+        try {
+            const built = CircuitJsonManufacturingDownloadBuilder.build(
+                {
+                    fileName: context.source.fileName,
+                    manufacturing
+                },
+                normalized.id,
+                normalized.options
+            )
+            return {
+                fileName: built.fileName,
+                mediaType: built.contentType,
+                data: new Uint8Array(built.bytes),
+                diagnostics: []
+            }
+        } catch (error) {
+            throw ToolkitError.from(error, {
+                code: 'ERR_MANUFACTURING_EXPORT',
+                category: 'runtime',
+                format: 'circuitjson'
+            })
+        }
+    }
+
+    /**
+     * Prepares one shared context and its element index.
+     * @param {unknown} document Document input.
+     * @param {unknown} options Service options.
+     * @returns {CircuitJsonDocumentContext} Prepared context.
+     */
+    static #context(document, options) {
+        ManufacturingService.#record(options, new Set())
+        try {
+            return CircuitJsonDocumentContext.prepare(document, {
+                indexes: ['elements']
+            })
+        } catch (error) {
+            throw ToolkitError.from(error, {
+                code: 'ERR_MANUFACTURING_DOCUMENT',
+                category: 'validation',
+                format: 'circuitjson'
+            })
+        }
+    }
+
+    /**
+     * Returns the one request-scoped manufacturing model.
+     * @param {CircuitJsonDocumentContext} context Prepared context.
+     * @returns {Record<string, any>} Internal manufacturing model.
+     */
+    static #build(context) {
+        return context.getOrCreateDerived(
+            'manufacturing',
+            'inspection-v1',
+            () =>
+                CircuitJsonManufacturingBuilder.build(
+                    context.model,
+                    context.getIndex('elements')
+                )
+        )
+    }
+
+    /**
+     * Computes stable format availability rows.
+     * @param {Record<string, any>} manufacturing Internal manufacturing model.
+     * @param {CircuitJsonDocumentContext} context Prepared context.
+     * @returns {object[]} Detached export capability rows.
+     */
+    static #exports(manufacturing, context) {
+        return EXPORTS.map((entry) => {
+            const reason = ManufacturingService.#reason(
+                entry.id,
+                manufacturing,
+                context
+            )
+            return {
+                ...entry,
+                status: reason ? 'unavailable' : 'available',
+                reason
+            }
+        })
+    }
+
+    /**
+     * Explains why one core export lacks source data.
+     * @param {string} id Export id.
+     * @param {Record<string, any>} manufacturing Internal manufacturing model.
+     * @param {CircuitJsonDocumentContext} context Prepared context.
+     * @returns {string} Empty string when available.
+     */
+    static #reason(id, manufacturing, context) {
+        if (id === 'pick-place-csv' && !manufacturing.pickAndPlaceRows.length) {
+            return 'No placement metadata is available.'
+        }
+        if (
+            id === 'fabrication-notes-json' &&
+            !manufacturing.fabricationNotes.length
+        ) {
+            return 'No fabrication note metadata is available.'
+        }
+        if (
+            id === 'routing-dsn' &&
+            (!manufacturing.routingDsn.trim() ||
+                !ManufacturingService.#hasRoutingData(context))
+        ) {
+            return 'No routing metadata is available.'
+        }
+        return ''
+    }
+
+    /**
+     * Returns whether the canonical model contains data represented by DSN.
+     * @param {CircuitJsonDocumentContext} context Prepared context.
+     * @returns {boolean} Whether a routing export is meaningful.
+     */
+    static #hasRoutingData(context) {
+        const byType = context.getIndex('elements').elementsByType
+        return ROUTING_TYPES.some((type) => (byType.get(type) || []).length)
+    }
+
+    /**
+     * Normalizes one safe manufacturing export request.
+     * @param {unknown} request Request candidate.
+     * @returns {{ id: string, options: Record<string, any> }} Request.
+     */
+    static #request(request) {
+        const normalized = ManufacturingService.#record(
+            request,
+            new Set(['id', 'options'])
+        )
+        const id = normalized.id
+        if (typeof id !== 'string' || !id.trim() || id.length > 256) {
+            throw ManufacturingService.#requestError(
+                'Manufacturing export id must be a bounded string.'
+            )
+        }
+        const options = ManufacturingService.#record(
+            normalized.options ?? {},
+            new Set()
+        )
+        return { id: id.trim(), options }
+    }
+
+    /**
+     * Reads a plain accessor-free request record.
+     * @param {unknown} value Record candidate.
+     * @param {Set<string>} allowed Allowed own keys.
+     * @returns {Record<string, any>} Safe shallow copy.
+     */
+    static #record(value, allowed) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw ManufacturingService.#requestError(
+                'Manufacturing options must be a plain object.'
+            )
+        }
+        let prototype
+        let descriptors
+        try {
+            prototype = Object.getPrototypeOf(value)
+            descriptors = Object.getOwnPropertyDescriptors(value)
+        } catch {
+            throw ManufacturingService.#requestError(
+                'Manufacturing options could not be inspected safely.'
+            )
+        }
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw ManufacturingService.#requestError(
+                'Manufacturing options must be a plain object.'
+            )
+        }
+        const result = {}
+        for (const key of Reflect.ownKeys(descriptors)) {
+            const descriptor = descriptors[key]
+            if (
+                typeof key !== 'string' ||
+                !allowed.has(key) ||
+                descriptor.enumerable !== true ||
+                descriptor.get ||
+                descriptor.set
+            ) {
+                throw ManufacturingService.#requestError(
+                    'Manufacturing options contain an unsupported field.'
+                )
+            }
+            result[key] = descriptor.value
+        }
+        return result
+    }
+
+    /**
+     * Returns stable context work statistics.
+     * @param {CircuitJsonDocumentContext} context Prepared context.
+     * @returns {Record<string, number>} Statistics.
+     */
+    static #statistics(context) {
+        const statistics = context.statistics
+        return {
+            validationPasses: statistics.validationPasses,
+            elementIndexBuilds: statistics.indexBuilds.elements || 0,
+            manufacturingBuilds:
+                statistics.derivedBuilds['manufacturing:inspection-v1'] || 0
+        }
+    }
+
+    /**
+     * Creates a typed request validation failure.
+     * @param {string} message Failure message.
+     * @returns {ToolkitError} Typed error.
+     */
+    static #requestError(message) {
+        return new ToolkitError(message, {
+            code: 'ERR_MANUFACTURING_REQUEST',
+            category: 'validation',
+            format: 'circuitjson'
+        })
+    }
+
+    /**
+     * Creates a typed unavailable-capability failure.
+     * @param {string} [reason] Capability reason.
+     * @returns {ToolkitError} Typed error.
+     */
+    static #unavailable(reason = '') {
+        return new ToolkitError(
+            reason || 'Manufacturing export is unavailable.',
+            {
+                code: 'ERR_CAPABILITY_UNAVAILABLE',
+                category: 'unsupported',
+                format: 'circuitjson'
+            }
+        )
+    }
+}

package/src/core/Parser.mjs

@@ -0,0 +1,343 @@
+import { DocumentResult } from './contracts/DocumentResult.mjs'
+import { ToolkitDiagnostic } from './contracts/ToolkitDiagnostic.mjs'
+import { ToolkitError } from './contracts/ToolkitError.mjs'
+import { ToolkitProgress } from './contracts/ToolkitProgress.mjs'
+import { AsyncInputOwnership } from './AsyncInputOwnership.mjs'
+import { BinaryDataSnapshot } from './context/BinaryDataSnapshot.mjs'
+import { ParserOptions } from './ParserOptions.mjs'
+import { CircuitJsonLegacyNormalizer } from './context/CircuitJsonLegacyNormalizer.mjs'
+import { ParserWorkerClient } from './worker/ParserWorkerClient.mjs'
+
+const PROGRESS_MESSAGES = {
+    detect: 'Detecting CircuitJSON input.',
+    decode: 'Decoding CircuitJSON.',
+    validate: 'Validating CircuitJSON.',
+    complete: 'CircuitJSON parsing complete.'
+}
+
+/**
+ * Parses standalone CircuitJSON inputs into canonical document envelopes.
+ */
+export class Parser {
+    /**
+     * Parses one CircuitJSON input synchronously.
+     * @param {{ fileName: string, data: string | ArrayBuffer | Uint8Array, assets?: object[] }} input Parser input.
+     * @param {Record<string, any>} [options] Common parser options.
+     * @returns {Record<string, any>} Canonical document result.
+     */
+    static parse(input, options = {}) {
+        try {
+            const normalized = ParserOptions.normalize(input, options)
+            if (normalized.options.worker === true) {
+                throw Parser.#workerSyncError(normalized.input.fileName)
+            }
+            return Parser.#parseNormalized(normalized)
+        } catch (error) {
+            throw Parser.#parseError(error, input)
+        }
+    }
+
+    /**
+     * Parses one CircuitJSON input without throwing public parse failures.
+     * @param {{ fileName: string, data: string | ArrayBuffer | Uint8Array, assets?: object[] }} input Parser input.
+     * @param {Record<string, any>} [options] Common parser options.
+     * @returns {{ ok: true, value: Record<string, any> } | { ok: false, error: ToolkitError, diagnostics: object[] }} Discriminated 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 CircuitJSON input through the currently available direct path.
+     * @param {{ fileName: string, data: string | ArrayBuffer | Uint8Array, assets?: object[] }} input Parser input.
+     * @param {Record<string, any>} [options] Common parser options.
+     * @returns {Promise<Record<string, any>>} Canonical document result.
+     */
+    static async parseAsync(input, options = {}) {
+        let normalized
+        const inputOwned = AsyncInputOwnership.ownsParser(input)
+        try {
+            normalized = ParserOptions.normalize(input, options)
+            if (Parser.#isAborted(normalized.options.signal)) {
+                throw Parser.#cancelledError(normalized.input.fileName)
+            }
+            Parser.#assertReports(
+                normalized.options.reports,
+                normalized.input.fileName
+            )
+        } catch (error) {
+            throw Parser.#parseError(error, input)
+        }
+
+        const useWorker =
+            normalized.options.worker === true ||
+            (normalized.options.worker === 'auto' &&
+                normalized.options.retainSource !== 'reference' &&
+                ParserWorkerClient.isDefaultAvailable())
+        if (useWorker) {
+            const attempt = await ParserWorkerClient.parseDefault(
+                normalized.input,
+                normalized.options
+            )
+            if (attempt.ok) return attempt.value
+            if (normalized.options.worker !== 'auto' || !attempt.unavailable) {
+                throw attempt.error
+            }
+            ParserWorkerClient.disposeDefault()
+        }
+
+        try {
+            if (!inputOwned) {
+                normalized = Parser.#ownAsyncInput(normalized)
+            }
+        } catch (error) {
+            throw Parser.#parseError(error, input)
+        }
+
+        let progress = Parser.#progress(normalized, 'detect')
+        Parser.#assertNotCancelled(normalized)
+        progress = Parser.#progress(normalized, 'decode', progress)
+        Parser.#assertNotCancelled(normalized)
+        let model
+        try {
+            model = Parser.#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 = Parser.#document(normalized, model)
+        } catch (error) {
+            throw Parser.#parseError(error, input)
+        }
+        Parser.#assertNotCancelled(normalized)
+        Parser.#progress(normalized, 'complete', progress)
+        Parser.#assertNotCancelled(normalized)
+        return document
+    }
+
+    /**
+     * Performs bounded detection for canonical CircuitJSON array inputs.
+     * @param {unknown} input Parser input candidate.
+     * @returns {boolean} Whether the input is supported.
+     */
+    static supports(input) {
+        return ParserOptions.supports(input)
+    }
+
+    /**
+     * Decodes and validates one normalized request exactly once.
+     * @param {{ input: { fileName: string, data: string | ArrayBuffer | Uint8Array, assets: object[] }, options: Record<string, any> }} normalized Normalized request.
+     * @returns {Record<string, any>} Canonical document result.
+     */
+    static #parseNormalized(normalized) {
+        Parser.#assertReports(
+            normalized.options.reports,
+            normalized.input.fileName
+        )
+        const model = Parser.#decode(normalized)
+        return Parser.#document(normalized, model)
+    }
+
+    /**
+     * Captures parser bytes and selected assets before the first host callback.
+     * @param {{ input: { fileName: string, data: string | ArrayBuffer | Uint8Array, assets: object[] }, options: { decodeAssets: string } }} normalized Normalized request.
+     * @returns {Record<string, any>} Request with one owned input boundary.
+     */
+    static #ownAsyncInput(normalized) {
+        const data = normalized.input.data
+        return {
+            ...normalized,
+            input: {
+                ...normalized.input,
+                data:
+                    typeof data === 'string'
+                        ? data
+                        : BinaryDataSnapshot.clone(data),
+                assets: ParserOptions.assets(
+                    normalized.input.assets,
+                    normalized.options.decodeAssets
+                )
+            }
+        }
+    }
+
+    /**
+     * Decodes one normalized payload and enforces the model-array boundary.
+     * @param {{ input: { data: string | ArrayBuffer | Uint8Array } }} normalized Normalized request.
+     * @returns {object[]} Decoded CircuitJSON model.
+     */
+    static #decode(normalized) {
+        let model = JSON.parse(ParserOptions.text(normalized.input.data))
+        if (!Array.isArray(model)) {
+            throw new TypeError('Expected a CircuitJSON element array.')
+        }
+        if (normalized.options.extensions === 'full') {
+            model = CircuitJsonLegacyNormalizer.normalize(model, {
+                owned: true
+            })
+        }
+        return model
+    }
+
+    /**
+     * Validates one model and creates its canonical document envelope.
+     * @param {{ input: { fileName: string, assets: object[] }, sourceReference: object, options: { decodeAssets: string, retainSource: string } }} normalized Normalized request.
+     * @param {object[]} model Decoded CircuitJSON model.
+     * @returns {Record<string, any>} Canonical document result.
+     */
+    static #document(normalized, model) {
+        const runtime =
+            normalized.options.retainSource === 'reference'
+                ? { sourceReference: normalized.sourceReference }
+                : {}
+        return DocumentResult.createValidated(
+            {
+                fileName: normalized.input.fileName,
+                fileType: 'circuitjson',
+                format: 'circuitjson',
+                model,
+                extensions: {},
+                assets: ParserOptions.assets(
+                    normalized.input.assets,
+                    normalized.options.decodeAssets
+                )
+            },
+            runtime
+        )
+    }
+
+    /**
+     * Emits one ordered direct-parser progress row when requested.
+     * @param {{ options: { onProgress?: Function } }} normalized Normalized request.
+     * @param {'detect' | 'decode' | 'validate' | 'complete'} stage Common progress stage.
+     * @param {Record<string, any> | null} [previous] Previous progress row.
+     * @returns {Record<string, any> | null} Emitted row or the prior state.
+     */
+    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 report ids because CircuitJSON exposes no eager parser reports.
+     * @param {string[]} reports Requested report ids.
+     * @param {string} source Source file name.
+     * @returns {void}
+     */
+    static #assertReports(reports, source) {
+        if (!reports.length) return
+        throw new ToolkitError(
+            `CircuitJSON parser report is unavailable: ${reports[0]}.`,
+            {
+                code: 'ERR_CAPABILITY_UNAVAILABLE',
+                category: 'unsupported',
+                format: 'circuitjson',
+                source,
+                details: { reports }
+            }
+        )
+    }
+
+    /**
+     * Normalizes public parse failures while preserving typed option failures.
+     * @param {unknown} error Failure candidate.
+     * @param {unknown} input Original parser input.
+     * @returns {ToolkitError} Typed parser failure.
+     */
+    static #parseError(error, input) {
+        return ToolkitError.from(error, {
+            code: 'ERR_CIRCUITJSON_PARSE',
+            category: 'parse',
+            format: 'circuitjson',
+            source: ParserOptions.fileName(input)
+        })
+    }
+
+    /**
+     * Creates the synchronous worker-mode error.
+     * @param {string} source Source file name.
+     * @returns {ToolkitError} Typed unsupported error.
+     */
+    static #workerSyncError(source) {
+        return new ToolkitError(
+            'Synchronous CircuitJSON parsing cannot use a worker.',
+            {
+                code: 'ERR_WORKER_SYNC_UNAVAILABLE',
+                category: 'unsupported',
+                format: 'circuitjson',
+                source
+            }
+        )
+    }
+
+    /**
+     * Creates a pre-start cancellation error.
+     * @param {string} source Source file name.
+     * @returns {ToolkitError} Typed cancellation error.
+     */
+    static #cancelledError(source) {
+        return new ToolkitError('CircuitJSON parsing was cancelled.', {
+            code: 'ERR_CANCELLED',
+            category: 'cancelled',
+            format: 'circuitjson',
+            source
+        })
+    }
+
+    /**
+     * Rejects an aborted direct request between parser phases.
+     * @param {{ input: { fileName: string }, options: { signal?: unknown } }} normalized Normalized request.
+     * @returns {void}
+     */
+    static #assertNotCancelled(normalized) {
+        if (!Parser.#isAborted(normalized.options.signal)) return
+        throw Parser.#cancelledError(normalized.input.fileName)
+    }
+
+    /**
+     * Reads a genuine optional AbortSignal through its platform getter.
+     * @param {unknown} signal Signal candidate.
+     * @returns {boolean} Whether the signal is aborted.
+     */
+    static #isAborted(signal) {
+        if (signal === undefined || signal === null) return false
+        const descriptor = Object.getOwnPropertyDescriptor(
+            AbortSignal.prototype,
+            'aborted'
+        )
+        if (typeof descriptor?.get !== 'function') {
+            throw new TypeError('AbortSignal state is unavailable.')
+        }
+        try {
+            return Boolean(descriptor.get.call(signal))
+        } catch {
+            throw new TypeError('CircuitJSON signal must be an AbortSignal.')
+        }
+    }
+}