circuitjson-toolkit 1.0.16 → 1.1.0

package/spec/library-scope.md

@@ -1,28 +1,35 @@
-# Library Scope
+# Library scope
 
-`circuitjson-toolkit` owns reusable browser and Node utilities for serialized
-CircuitJSON element arrays.
+`circuitjson-toolkit` owns browser- and Node-compatible common operations over
+immutable CircuitJSON.
 
 ## Included
 
-- CircuitJSON element-array validation
-- Standalone JSON text and byte parsing
-- Parser-style metadata attachment
-- Lookup indexes by element type and stable IDs
-- Source and PCB component lookup maps
-- Millimeter-to-mil conversion helpers
-- Local SPICE transient graph helpers that produce complete CircuitJSON
-  simulation experiment element sets
-- Deterministic SPICE graph summaries and non-fatal local syntax diagnostics
-- Small documentation and tests for toolkit behavior
+- Canonical parser and project result envelopes
+- CircuitJSON validation proofs and request-scoped prepared contexts
+- Element, relation, connectivity, and PCB spatial indexes
+- Deterministic PCB, schematic, and BOM rendering
+- PCB hit testing, picking, selection, snapping, layers, and diagnostics
+- Repeated component/net queries and connectivity traversal
+- Manufacturing inspection and explicit data exports
+- Simulation definition/export and explicitly injected engine execution
+- Data-only PCB 3D scene building and explicit asset preparation
+- Typed errors, diagnostics, progress, capabilities, and worker protocol
+- Packed downstream conformance fixtures and checks
+- Exactly 37 source-neutral compatibility extensions for previous CircuitJSON
+  APIs, classified as shared or derived across the toolkit family
+- Descriptor-safe asset measurement/preparation and project-wide payload limit
+  accounting
 
 ## Excluded
 
-- Three.js or browser DOM rendering
-- PCB 3D runtime behavior
-- ECAD source parser logic
-- Native ECAD source-format compatibility adapters
-- Network fetching or remote asset loading
+- Gerber, Altium, KiCad, or other native ECAD decoders
+- Source-format-specific fidelity predicates and native report generation
+- Three.js or other runtime scene rendering
+- Browser UI state, controls, downloads, or event orchestration
+- Implicit filesystem, process, network, or asset-store access
+- Customer/vendor fixtures or example-specific parsing behavior
 
-Renderer fixes belong in renderer packages. Source-format fixes belong in the
-source toolkit that parses that format.
+Native parser behavior belongs in its source toolkit. Runtime visualization
+belongs in `pcb-scene3d-viewer` or another host. Common behavior meaningful for
+CircuitJSON belongs here and is exposed consistently by every source toolkit.

package/src/capabilities.mjs

@@ -0,0 +1 @@
+export { ToolkitCapabilities } from './core/ToolkitCapabilities.mjs'

package/src/core/ArchiveEntryPath.mjs

@@ -0,0 +1,93 @@
+import { ToolkitError } from './contracts/ToolkitError.mjs'
+
+const DRIVE_PATH = /^[A-Za-z]:/u
+
+/**
+ * Normalizes untrusted archive entry names without touching the host filesystem.
+ */
+export class ArchiveEntryPath {
+    /**
+     * Normalizes one entry name to a safe relative POSIX path.
+     * @param {unknown} name Archive entry name.
+     * @returns {string} Safe normalized entry name.
+     */
+    static normalize(name) {
+        if (typeof name !== 'string' || !name || name.includes('\0')) {
+            throw ArchiveEntryPath.#pathError(name)
+        }
+
+        const candidate = name.replaceAll('\\', '/')
+        if (candidate.startsWith('/') || DRIVE_PATH.test(candidate)) {
+            throw ArchiveEntryPath.#pathError(name)
+        }
+
+        const segments = []
+        for (const segment of candidate.split('/')) {
+            if (!segment || segment === '.') continue
+            if (segment === '..') {
+                if (!segments.length) {
+                    throw ArchiveEntryPath.#pathError(name)
+                }
+                segments.pop()
+                continue
+            }
+            segments.push(segment)
+        }
+
+        if (!segments.length) throw ArchiveEntryPath.#pathError(name)
+        return segments.join('/')
+    }
+
+    /**
+     * Normalizes entry names and rejects collisions after normalization.
+     * @param {unknown} names Archive entry names.
+     * @returns {string[]} Normalized names in caller order.
+     */
+    static unique(names) {
+        if (!Array.isArray(names)) {
+            throw new ToolkitError('Archive entry names must be an array.', {
+                code: 'ERR_ARCHIVE_PATH',
+                category: 'validation',
+                format: 'archive'
+            })
+        }
+
+        const normalized = []
+        const seen = new Set()
+        for (const name of names) {
+            const entryName = ArchiveEntryPath.normalize(name)
+            if (seen.has(entryName)) {
+                throw new ToolkitError(
+                    `Duplicate normalized archive entry: ${entryName}.`,
+                    {
+                        code: 'ERR_ARCHIVE_DUPLICATE_ENTRY',
+                        category: 'validation',
+                        format: 'archive',
+                        source: entryName,
+                        details: { entryName }
+                    }
+                )
+            }
+            seen.add(entryName)
+            normalized.push(entryName)
+        }
+        return normalized
+    }
+
+    /**
+     * Creates one unsafe-entry error without reflecting NUL data into messages.
+     * @param {unknown} name Rejected entry name.
+     * @returns {ToolkitError} Typed path error.
+     */
+    static #pathError(name) {
+        const source =
+            typeof name === 'string' && !name.includes('\0') ? name : ''
+        return new ToolkitError('Archive entry path is unsafe.', {
+            code: 'ERR_ARCHIVE_PATH',
+            category: 'validation',
+            format: 'archive',
+            source,
+            details: { reason: 'unsafe-relative-path' }
+        })
+    }
+}

package/src/core/ArchiveLimits.mjs

@@ -0,0 +1,31 @@
+import { ArchiveLimitsValidator } from './ArchiveLimitsValidator.mjs'
+
+const DEFAULTS = Object.freeze({
+    maxEntries: 4096,
+    maxEntryBytes: 536870912,
+    maxTotalBytes: 2147483648,
+    maxCompressionRatio: 1000,
+    maxArchiveDepth: 1
+})
+
+/**
+ * Publishes the shared non-disableable archive safety ceilings.
+ */
+export class ArchiveLimits {
+    /**
+     * Returns the immutable default ceilings.
+     * @returns {Readonly<Record<string, number>>} Default archive limits.
+     */
+    static get defaults() {
+        return DEFAULTS
+    }
+
+    /**
+     * Applies caller overrides that may only tighten the hard ceilings.
+     * @param {unknown} [overrides] Caller limit overrides.
+     * @returns {Readonly<Record<string, number>>} Normalized archive limits.
+     */
+    static normalize(overrides = {}) {
+        return ArchiveLimitsValidator.normalize(overrides, DEFAULTS)
+    }
+}

package/src/core/ArchiveLimitsValidator.mjs

@@ -0,0 +1,107 @@
+import { ToolkitError } from './contracts/ToolkitError.mjs'
+
+const INTEGER_LIMITS = new Set([
+    'maxEntries',
+    'maxEntryBytes',
+    'maxTotalBytes',
+    'maxArchiveDepth'
+])
+
+/**
+ * Validates caller-controlled archive safety limits against hard maxima.
+ */
+export class ArchiveLimitsValidator {
+    /**
+     * Normalizes bounded own overrides into a new immutable record.
+     * @param {unknown} overrides Limit overrides.
+     * @param {Record<string, number>} defaults Hard maximum values.
+     * @returns {Readonly<Record<string, number>>} Normalized limits.
+     */
+    static normalize(overrides = {}, defaults = {}) {
+        if (!ArchiveLimitsValidator.#isPlainRecord(overrides)) {
+            throw ArchiveLimitsValidator.#error(
+                '',
+                'Archive limits must be a plain object.'
+            )
+        }
+
+        const descriptors = Object.getOwnPropertyDescriptors(overrides)
+        const allowed = new Set(Object.keys(defaults))
+        for (const key of Reflect.ownKeys(descriptors)) {
+            if (
+                typeof key !== 'string' ||
+                !allowed.has(key) ||
+                descriptors[key].enumerable !== true ||
+                descriptors[key].get ||
+                descriptors[key].set
+            ) {
+                throw ArchiveLimitsValidator.#error(
+                    typeof key === 'string' ? key : '',
+                    'Archive limits contain an unknown or accessor-backed key.'
+                )
+            }
+        }
+
+        const normalized = {}
+        for (const [key, maximum] of Object.entries(defaults)) {
+            const descriptor = descriptors[key]
+            const value = descriptor ? descriptor.value : maximum
+            ArchiveLimitsValidator.#assertValue(key, value, maximum)
+            normalized[key] = value
+        }
+        return Object.freeze(normalized)
+    }
+
+    /**
+     * Checks whether a value is an ordinary own-property record.
+     * @param {unknown} value Candidate record.
+     * @returns {boolean} Whether the record is safe to inspect.
+     */
+    static #isPlainRecord(value) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            return false
+        }
+        const prototype = Object.getPrototypeOf(value)
+        return prototype === Object.prototype || prototype === null
+    }
+
+    /**
+     * Validates one numeric override.
+     * @param {string} key Limit name.
+     * @param {unknown} value Limit value.
+     * @param {number} maximum Hard maximum.
+     * @returns {void}
+     */
+    static #assertValue(key, value, maximum) {
+        const number = typeof value === 'number' ? value : Number.NaN
+        const minimum = key === 'maxArchiveDepth' ? 0 : Number.MIN_VALUE
+        const invalidInteger =
+            INTEGER_LIMITS.has(key) && !Number.isSafeInteger(number)
+        if (
+            !Number.isFinite(number) ||
+            invalidInteger ||
+            number < minimum ||
+            number > maximum
+        ) {
+            throw ArchiveLimitsValidator.#error(
+                key,
+                `Archive limit ${key} is outside its safe range.`
+            )
+        }
+    }
+
+    /**
+     * Creates a stable invalid-limit error.
+     * @param {string} key Rejected key.
+     * @param {string} message Failure message.
+     * @returns {ToolkitError} Typed validation error.
+     */
+    static #error(key, message) {
+        return new ToolkitError(message, {
+            code: 'ERR_ARCHIVE_LIMIT_INVALID',
+            category: 'validation',
+            format: 'archive',
+            details: key ? { key } : {}
+        })
+    }
+}

package/src/core/AsyncInputOwnership.mjs

@@ -0,0 +1,56 @@
+const OWNED_PARSER_INPUTS = new WeakSet()
+const OWNED_PROJECT_ENTRIES = new WeakSet()
+
+/**
+ * Marks structured-cloned worker inputs that already belong to the receiver.
+ */
+export class AsyncInputOwnership {
+    /**
+     * Marks one worker-received parser input as receiver-owned.
+     * @param {object} input Parser input.
+     * @returns {object} The same input.
+     */
+    static markParser(input) {
+        if (input && typeof input === 'object') OWNED_PARSER_INPUTS.add(input)
+        return input
+    }
+
+    /**
+     * Returns whether one parser input already belongs to this process.
+     * @param {unknown} input Parser input candidate.
+     * @returns {boolean} Whether the input is receiver-owned.
+     */
+    static ownsParser(input) {
+        return Boolean(
+            input && typeof input === 'object' && OWNED_PARSER_INPUTS.has(input)
+        )
+    }
+
+    /**
+     * Marks one worker-received project entry array as receiver-owned.
+     * @param {object[]} entries Project entries.
+     * @returns {object[]} The same entries.
+     */
+    static markProject(entries) {
+        if (entries && typeof entries === 'object') {
+            OWNED_PROJECT_ENTRIES.add(entries)
+        }
+        return entries
+    }
+
+    /**
+     * Returns whether project entries already belong to this process.
+     * @param {unknown} entries Project entry candidate.
+     * @returns {boolean} Whether the entries are receiver-owned.
+     */
+    static ownsProject(entries) {
+        return Boolean(
+            entries &&
+            typeof entries === 'object' &&
+            OWNED_PROJECT_ENTRIES.has(entries)
+        )
+    }
+}
+
+Object.freeze(AsyncInputOwnership.prototype)
+Object.freeze(AsyncInputOwnership)

package/src/core/AttachedValueLimits.mjs

@@ -0,0 +1,67 @@
+import { ToolkitError } from './contracts/ToolkitError.mjs'
+
+const MAX_ATTACHED_VALUES = 100_000
+
+/**
+ * Enforces the request-global ceiling for caller-attached asset values.
+ */
+export class AttachedValueLimits {
+    /**
+     * Returns the hard attached-value ceiling shared by every execution path.
+     * @returns {number} Maximum attached values per request.
+     */
+    static get maximum() {
+        return MAX_ATTACHED_VALUES
+    }
+
+    /**
+     * Adds one attached-value array length without visiting its elements.
+     * @param {unknown} values Attached-value array candidate.
+     * @param {number} [current] Values already counted in this request.
+     * @returns {number} Updated request-global count.
+     */
+    static add(values, current = 0) {
+        if (!Array.isArray(values)) {
+            throw new TypeError('Attached values must be an array.')
+        }
+        let prototype
+        let lengthDescriptor
+        try {
+            prototype = Object.getPrototypeOf(values)
+            lengthDescriptor = Object.getOwnPropertyDescriptor(values, 'length')
+        } catch {
+            throw new TypeError(
+                'Attached values could not be inspected safely.'
+            )
+        }
+        const length = lengthDescriptor?.value
+        if (
+            prototype !== Array.prototype ||
+            !lengthDescriptor ||
+            !Object.hasOwn(lengthDescriptor, 'value') ||
+            !Number.isSafeInteger(length) ||
+            length < 0
+        ) {
+            throw new TypeError('Attached values must be a plain array.')
+        }
+        const total = current + length
+        if (!Number.isSafeInteger(total) || total > MAX_ATTACHED_VALUES) {
+            throw new ToolkitError(
+                `Attached values exceed the ${MAX_ATTACHED_VALUES} item limit.`,
+                {
+                    code: 'ERR_ATTACHED_VALUE_LIMIT_EXCEEDED',
+                    category: 'validation',
+                    format: 'circuitjson',
+                    details: {
+                        attachedValues: total,
+                        maxAttachedValues: MAX_ATTACHED_VALUES
+                    }
+                }
+            )
+        }
+        return total
+    }
+}
+
+Object.freeze(AttachedValueLimits.prototype)
+Object.freeze(AttachedValueLimits)

package/src/core/CircuitJsonDiagnosticIndexer.mjs

@@ -0,0 +1,184 @@
+/**
+ * Normalizes CircuitJSON warning and error elements for shared indexes.
+ */
+export class CircuitJsonDiagnosticIndexer {
+    /**
+     * Returns true when an element is a warning or error row.
+     * @param {object} element Element.
+     * @returns {boolean}
+     */
+    static isElement(element) {
+        return (
+            CircuitJsonDiagnosticIndexer.isType(String(element?.type || '')) ||
+            Boolean(element?.error_type || element?.warning_type)
+        )
+    }
+
+    /**
+     * Returns true for upstream warning and error discriminants.
+     * @param {string} type Element type.
+     * @returns {boolean}
+     */
+    static isType(type) {
+        return (
+            type.includes('error') ||
+            type.endsWith('_warning') ||
+            type === 'source_ambiguous_port_reference'
+        )
+    }
+
+    /**
+     * Builds one normalized diagnostic.
+     * @param {object} element Diagnostic element.
+     * @param {string} elementId Stable element id.
+     * @returns {object}
+     */
+    static fromElement(element, elementId) {
+        const type = String(
+            element?.error_type || element?.warning_type || element?.type || ''
+        )
+        return {
+            severity: element?.warning_type ? 'warning' : 'error',
+            sourceFormat: 'circuitjson',
+            type,
+            category: CircuitJsonDiagnosticIndexer.#category(type),
+            message: String(element?.message || type || 'CircuitJSON issue'),
+            elementId,
+            ...CircuitJsonDiagnosticIndexer.#relations(element)
+        }
+    }
+
+    /**
+     * Extracts optional relation ids from one diagnostic element.
+     * @param {object} element Diagnostic element.
+     * @returns {object}
+     */
+    static #relations(element) {
+        const scalar = Object.fromEntries(
+            [
+                ['sourceComponentId', element?.source_component_id],
+                ['sourcePortId', element?.source_port_id],
+                ['sourceNetId', element?.source_net_id],
+                ['sourceTraceId', element?.source_trace_id],
+                ['pcbComponentId', element?.pcb_component_id],
+                ['pcbPortId', element?.pcb_port_id],
+                ['pcbTraceId', element?.pcb_trace_id],
+                ['pcbSmtpadId', element?.pcb_smtpad_id],
+                ['pcbViaId', element?.pcb_via_id],
+                ['pcbPlatedHoleId', element?.pcb_plated_hole_id],
+                ['pcbHoleId', element?.pcb_hole_id],
+                ['schematicComponentId', element?.schematic_component_id],
+                ['schematicSymbolId', element?.schematic_symbol_id],
+                ['schematicPortId', element?.schematic_port_id]
+            ]
+                .map(([key, value]) => [key, String(value || '').trim()])
+                .filter(([_key, value]) => value)
+        )
+        const plural = Object.fromEntries(
+            [
+                [
+                    'sourceComponentIds',
+                    element?.source_component_ids,
+                    element?.source_component_id
+                ],
+                [
+                    'sourcePortIds',
+                    element?.source_port_ids,
+                    element?.source_port_id
+                ],
+                [
+                    'sourceNetIds',
+                    element?.source_net_ids,
+                    element?.source_net_id
+                ],
+                [
+                    'sourceTraceIds',
+                    element?.source_trace_ids,
+                    element?.source_trace_id
+                ],
+                [
+                    'pcbComponentIds',
+                    element?.pcb_component_ids,
+                    element?.pcb_component_id
+                ],
+                ['pcbPortIds', element?.pcb_port_ids, element?.pcb_port_id],
+                ['pcbTraceIds', element?.pcb_trace_ids, element?.pcb_trace_id],
+                [
+                    'pcbPadIds',
+                    element?.pcb_pad_ids ?? element?.pcb_smtpad_ids,
+                    element?.pcb_pad_id ?? element?.pcb_smtpad_id
+                ],
+                ['pcbViaIds', element?.pcb_via_ids, element?.pcb_via_id],
+                [
+                    'pcbPlatedHoleIds',
+                    element?.pcb_plated_hole_ids,
+                    element?.pcb_plated_hole_id
+                ],
+                ['pcbHoleIds', element?.pcb_hole_ids, element?.pcb_hole_id]
+            ]
+                .map(([key, values, singular]) => {
+                    const ids = Array.isArray(values)
+                        ? [...new Set(values.map(String).filter(Boolean))]
+                        : []
+                    const singularId = String(singular || '').trim()
+                    return [
+                        key,
+                        ids.length === 1 && ids[0] === singularId ? [] : ids
+                    ]
+                })
+                .filter(([_key, values]) => values.length)
+        )
+        return { ...scalar, ...plural }
+    }
+
+    /**
+     * Resolves a broad diagnostic category.
+     * @param {string} type Diagnostic type or code.
+     * @returns {string}
+     */
+    static #category(type) {
+        const text = String(type || '').toLowerCase()
+        if (text.includes('clearance')) return 'clearance'
+        if (text.includes('autorouting') || text.includes('trace_error')) {
+            return 'routing'
+        }
+        if (text.includes('placement') || text.includes('outside_board')) {
+            return 'placement'
+        }
+        if (
+            text.includes('trace_missing') ||
+            text.includes('not_connected') ||
+            text.includes('missing_trace') ||
+            text.includes('pin_missing_trace') ||
+            text.includes('pin_must_be_connected')
+        ) {
+            return 'connectivity'
+        }
+        if (text.includes('layout')) return 'layout'
+        if (text.includes('simulation')) return 'simulation'
+        if (text.includes('footprint')) return 'footprint'
+        if (
+            text.includes('pin_defined') ||
+            text.includes('pins_underspecified') ||
+            text.includes('ground_pin') ||
+            text.includes('power_pin')
+        ) {
+            return 'pin-definition'
+        }
+        if (
+            text.includes('manufacturer_part') ||
+            text.includes('missing_property') ||
+            text.includes('property_ignored')
+        ) {
+            return 'metadata'
+        }
+        if (text.includes('manual_edit_conflict')) return 'edit-conflict'
+        if (text.includes('property') || text.includes('misconfigured')) {
+            return 'configuration'
+        }
+        return 'general'
+    }
+}
+
+Object.freeze(CircuitJsonDiagnosticIndexer.prototype)
+Object.freeze(CircuitJsonDiagnosticIndexer)