circuitjson-toolkit 1.0.16 → 1.1.0

package/src/core/CircuitJsonPcbPrimitiveIndex.mjs

@@ -1,4 +1,5 @@
 import { CircuitJsonIndexer } from './CircuitJsonIndexer.mjs'
+import { CircuitJsonLegacyNormalizer } from './context/CircuitJsonLegacyNormalizer.mjs'
 
 /**
  * Builds PCB primitive element indexes with a tolerant local fallback.
@@ -13,10 +14,25 @@ export class CircuitJsonPcbPrimitiveIndex {
         try {
             return CircuitJsonIndexer.index(elements)
         } catch (error) {
-            if (!CircuitJsonPcbPrimitiveIndex.#isUnknownTypeError(error)) {
+            const normalized = CircuitJsonLegacyNormalizer.normalize(elements)
+            if (normalized === elements) {
+                if (CircuitJsonPcbPrimitiveIndex.#isUnknownTypeError(error)) {
+                    return CircuitJsonPcbPrimitiveIndex.#localIndex(elements)
+                }
                 throw error
             }
-            return CircuitJsonPcbPrimitiveIndex.#localIndex(elements)
+            try {
+                return CircuitJsonIndexer.index(normalized)
+            } catch (normalizedError) {
+                if (
+                    CircuitJsonPcbPrimitiveIndex.#isUnknownTypeError(
+                        normalizedError
+                    )
+                ) {
+                    return CircuitJsonPcbPrimitiveIndex.#localIndex(normalized)
+                }
+                throw normalizedError
+            }
         }
     }
 

package/src/core/CircuitJsonPcbPrimitiveOverlays.mjs

@@ -355,9 +355,15 @@ export class CircuitJsonPcbPrimitiveOverlays {
                 pcb_trace_ids:
                     diagnostic?.pcbTraceIds || diagnostic?.pcb_trace_ids,
                 pcb_smtpad_id:
-                    diagnostic?.pcbSmtpadId || diagnostic?.pcb_smtpad_id,
+                    diagnostic?.pcbSmtpadId ||
+                    diagnostic?.pcb_smtpad_id ||
+                    diagnostic?.pcbPadId ||
+                    diagnostic?.pcb_pad_id,
                 pcb_smtpad_ids:
-                    diagnostic?.pcbSmtpadIds || diagnostic?.pcb_smtpad_ids,
+                    diagnostic?.pcbSmtpadIds ||
+                    diagnostic?.pcb_smtpad_ids ||
+                    diagnostic?.pcbPadIds ||
+                    diagnostic?.pcb_pad_ids,
                 pcb_via_id: diagnostic?.pcbViaId || diagnostic?.pcb_via_id,
                 pcb_via_ids: diagnostic?.pcbViaIds || diagnostic?.pcb_via_ids,
                 pcb_plated_hole_id:
@@ -646,7 +652,12 @@ export class CircuitJsonPcbPrimitiveOverlays {
             ['pcb_trace_id', [element?.pcb_trace_id, element?.pcb_trace_ids]],
             [
                 'pcb_smtpad_id',
-                [element?.pcb_smtpad_id, element?.pcb_smtpad_ids]
+                [
+                    element?.pcb_smtpad_id,
+                    element?.pcb_smtpad_ids,
+                    element?.pcb_pad_id,
+                    element?.pcb_pad_ids
+                ]
             ],
             ['pcb_via_id', [element?.pcb_via_id, element?.pcb_via_ids]],
             [
@@ -762,12 +773,18 @@ export class CircuitJsonPcbPrimitiveOverlays {
      * @returns {object | null}
      */
     static #mergeBounds(rows) {
-        const validRows = rows.filter(Boolean)
-        if (!validRows.length) return null
-        const minX = Math.min(...validRows.map((bounds) => bounds.minX))
-        const minY = Math.min(...validRows.map((bounds) => bounds.minY))
-        const maxX = Math.max(...validRows.map((bounds) => bounds.maxX))
-        const maxY = Math.max(...validRows.map((bounds) => bounds.maxY))
+        let minX = Infinity
+        let minY = Infinity
+        let maxX = -Infinity
+        let maxY = -Infinity
+        for (const bounds of rows) {
+            if (!bounds) continue
+            minX = Math.min(minX, bounds.minX)
+            minY = Math.min(minY, bounds.minY)
+            maxX = Math.max(maxX, bounds.maxX)
+            maxY = Math.max(maxY, bounds.maxY)
+        }
+        if (!Number.isFinite(minX)) return null
         return {
             minX: CircuitJsonPcbPrimitiveOverlays.#round(minX),
             minY: CircuitJsonPcbPrimitiveOverlays.#round(minY),

package/src/core/CircuitJsonPcbZonePrimitiveBuilder.mjs

@@ -325,12 +325,13 @@ export class CircuitJsonPcbZonePrimitiveBuilder {
      * @returns {object[]}
      */
     static #brepShapes(element) {
-        return [
-            ...(Array.isArray(element?.brep_shapes) ? element.brep_shapes : []),
-            ...(Array.isArray(element?.brepShapes) ? element.brepShapes : []),
-            element?.brep_shape,
-            element?.brepShape
-        ].filter(Boolean)
+        if (Array.isArray(element?.brep_shapes) && element.brep_shapes.length) {
+            return element.brep_shapes
+        }
+        if (Array.isArray(element?.brepShapes) && element.brepShapes.length) {
+            return element.brepShapes
+        }
+        return [element?.brep_shape, element?.brepShape].filter(Boolean)
     }
 
     /**

package/src/core/CircuitJsonSerializedInputAudit.mjs

@@ -0,0 +1,87 @@
+import { CIRCUIT_JSON_UPSTREAM_DEFAULT_ID_FIELDS } from './CircuitJsonUpstreamSchema.mjs'
+
+/**
+ * Reports upstream defaults intentionally left unmaterialized by raw parsing.
+ */
+export class CircuitJsonSerializedInputAudit {
+    /**
+     * Audits missing random upstream identity defaults without mutating input.
+     * @param {unknown} model Serialized CircuitJSON model candidate.
+     * @param {string} [source] Source identity for diagnostics.
+     * @returns {{ diagnostics: object[], statistics: Record<string, number> }} Audit rows.
+     */
+    static inspect(model, source = '') {
+        if (!Array.isArray(model)) {
+            return { diagnostics: [], statistics: {} }
+        }
+        let length
+        try {
+            length = Object.getOwnPropertyDescriptor(model, 'length')?.value
+        } catch {
+            return { diagnostics: [], statistics: {} }
+        }
+        if (!Number.isSafeInteger(length) || length < 0) {
+            return { diagnostics: [], statistics: {} }
+        }
+        const diagnostics = []
+        for (let index = 0; index < length; index += 1) {
+            const element = CircuitJsonSerializedInputAudit.#dataField(
+                model,
+                String(index)
+            )
+            const type = CircuitJsonSerializedInputAudit.#dataField(
+                element,
+                'type'
+            )
+            if (typeof type !== 'string') continue
+            const idField = CIRCUIT_JSON_UPSTREAM_DEFAULT_ID_FIELDS[type]
+            if (!idField) continue
+            const identity = CircuitJsonSerializedInputAudit.#dataField(
+                element,
+                idField
+            )
+            if (identity !== undefined) continue
+            diagnostics.push({
+                code: 'CIRCUITJSON_UPSTREAM_DEFAULT_ID_OMITTED',
+                severity: 'warning',
+                message:
+                    `Serialized CircuitJSON omitted ${idField}; ` +
+                    'the random upstream default was not materialized.',
+                source,
+                location: { elementIndex: index },
+                details: {
+                    elementType: type,
+                    idField,
+                    materialized: false
+                }
+            })
+        }
+        return {
+            diagnostics,
+            statistics: diagnostics.length
+                ? { upstreamDefaultIdentityOmissions: diagnostics.length }
+                : {}
+        }
+    }
+
+    /**
+     * Reads one own data field without invoking caller accessors.
+     * @param {unknown} owner Field owner.
+     * @param {string} key Field name.
+     * @returns {unknown} Data value or undefined.
+     */
+    static #dataField(owner, key) {
+        if (!owner || typeof owner !== 'object') return undefined
+        try {
+            const descriptor = Object.getOwnPropertyDescriptor(owner, key)
+            return descriptor && Object.hasOwn(descriptor, 'value')
+                ? descriptor.value
+                : undefined
+        } catch {
+            return undefined
+        }
+    }
+}
+
+Object.freeze(CircuitJsonSerializedInputAudit.prototype)
+Object.freeze(CircuitJsonSerializedInputAudit)

package/src/core/CircuitJsonSourceMetadata.mjs

@@ -185,7 +185,11 @@ export class CircuitJsonSourceMetadata {
      */
     static #supplierPartNumbers(component) {
         const numbers = {}
-        for (const field of ['supplier_part_numbers', 'supplierPartNumbers']) {
+        for (const field of [
+            'supplier_part_numbers',
+            'supplierPartNumbers',
+            'legacy_supplier_part_numbers'
+        ]) {
             const value = component?.[field]
             if (!value || typeof value !== 'object' || Array.isArray(value)) {
                 continue

package/src/core/CircuitJsonSupportMatrixBuilder.mjs

@@ -56,12 +56,14 @@ const SCHEMATIC_RENDERED_TYPES = new Set([
     'schematic_component',
     'schematic_debug_object',
     'schematic_group',
+    'schematic_image',
     'schematic_line',
     'schematic_net_label',
     'schematic_path',
     'schematic_port',
     'schematic_rect',
     'schematic_sheet',
+    'schematic_sheet_symbol',
     'schematic_symbol',
     'schematic_table',
     'schematic_table_cell',
@@ -171,7 +173,7 @@ export class CircuitJsonSupportMatrixBuilder {
                 .map((element) => String(element?.type || ''))
                 .filter(Boolean)
         )
-        const rows = CircuitJsonElementValidator.knownElementTypes().map(
+        const rows = CircuitJsonElementValidator.canonicalElementTypes().map(
             (type) =>
                 CircuitJsonSupportMatrixBuilder.#row(
                     type,

package/src/core/CircuitJsonToolkitElementSchema.mjs

@@ -0,0 +1,218 @@
+const TOOLKIT_ELEMENT_TYPES = new Set([
+    'schematic_image',
+    'schematic_sheet_symbol'
+])
+
+/**
+ * Validates canonical toolkit element types that are newer than the pinned
+ * upstream CircuitJSON union.
+ */
+export class CircuitJsonToolkitElementSchema {
+    /**
+     * Returns the toolkit-owned canonical element types.
+     * @returns {string[]} Stable element type names.
+     */
+    static elementTypes() {
+        return [...TOOLKIT_ELEMENT_TYPES]
+    }
+
+    /**
+     * Returns whether a type is owned by the canonical toolkit overlay.
+     * @param {unknown} type Element type.
+     * @returns {boolean} Whether the type is recognized.
+     */
+    static has(type) {
+        return typeof type === 'string' && TOOLKIT_ELEMENT_TYPES.has(type)
+    }
+
+    /**
+     * Validates one toolkit-owned canonical element.
+     * @param {Record<string, any>} value Element value.
+     * @param {string} type Element type.
+     * @param {string} [location] Human-readable location suffix.
+     * @returns {string[]} Empty on success or one validation error.
+     */
+    static validate(value, type, location = '') {
+        const valid =
+            (type === 'schematic_image' &&
+                CircuitJsonToolkitElementSchema.#schematicImage(value)) ||
+            (type === 'schematic_sheet_symbol' &&
+                CircuitJsonToolkitElementSchema.#schematicSheetSymbol(value))
+        return valid
+            ? []
+            : [
+                  `CircuitJSON element ${type}${location} does not match the canonical toolkit schema.`
+              ]
+    }
+
+    /**
+     * Validates an asset-backed schematic image.
+     * @param {Record<string, any>} value Image element.
+     * @returns {boolean} Whether the complete image contract matches.
+     */
+    static #schematicImage(value) {
+        if (
+            value.type !== 'schematic_image' ||
+            !CircuitJsonToolkitElementSchema.#requiredString(
+                value.schematic_image_id
+            ) ||
+            !CircuitJsonToolkitElementSchema.#requiredString(value.asset_id) ||
+            !CircuitJsonToolkitElementSchema.#point(value.center) ||
+            !CircuitJsonToolkitElementSchema.#size(value.size)
+        ) {
+            return false
+        }
+        for (const field of [
+            'schematic_sheet_id',
+            'schematic_component_id',
+            'subcircuit_id',
+            'source_path',
+            'source_name'
+        ]) {
+            if (
+                value[field] !== undefined &&
+                typeof value[field] !== 'string'
+            ) {
+                return false
+            }
+        }
+        if (
+            value.rotation !== undefined &&
+            !CircuitJsonToolkitElementSchema.#number(value.rotation)
+        ) {
+            return false
+        }
+        if (
+            value.opacity !== undefined &&
+            (!CircuitJsonToolkitElementSchema.#number(value.opacity) ||
+                value.opacity < 0 ||
+                value.opacity > 1)
+        ) {
+            return false
+        }
+        if (
+            value.preserve_aspect_ratio !== undefined &&
+            typeof value.preserve_aspect_ratio !== 'boolean'
+        ) {
+            return false
+        }
+        return (
+            value.render_order === undefined ||
+            Number.isSafeInteger(value.render_order)
+        )
+    }
+
+    /**
+     * Validates one hierarchical child-sheet symbol.
+     * @param {Record<string, any>} value Sheet-symbol element.
+     * @returns {boolean} Whether the complete symbol contract matches.
+     */
+    static #schematicSheetSymbol(value) {
+        if (
+            value.type !== 'schematic_sheet_symbol' ||
+            !CircuitJsonToolkitElementSchema.#requiredString(
+                value.schematic_sheet_symbol_id
+            ) ||
+            typeof value.name !== 'string' ||
+            !CircuitJsonToolkitElementSchema.#point(value.center) ||
+            !CircuitJsonToolkitElementSchema.#positive(value.width) ||
+            !CircuitJsonToolkitElementSchema.#positive(value.height)
+        ) {
+            return false
+        }
+        for (const field of [
+            'schematic_sheet_id',
+            'schematic_group_id',
+            'subcircuit_id',
+            'source_file_name',
+            'color',
+            'fill_color'
+        ]) {
+            if (
+                value[field] !== undefined &&
+                typeof value[field] !== 'string'
+            ) {
+                return false
+            }
+        }
+        for (const field of ['is_dashed', 'is_filled']) {
+            if (
+                value[field] !== undefined &&
+                typeof value[field] !== 'boolean'
+            ) {
+                return false
+            }
+        }
+        if (
+            value.stroke_width !== undefined &&
+            (!CircuitJsonToolkitElementSchema.#number(value.stroke_width) ||
+                value.stroke_width < 0)
+        ) {
+            return false
+        }
+        return (
+            value.render_order === undefined ||
+            Number.isSafeInteger(value.render_order)
+        )
+    }
+
+    /**
+     * Validates a required non-empty string.
+     * @param {unknown} value Candidate.
+     * @returns {boolean} Whether the value is valid.
+     */
+    static #requiredString(value) {
+        return typeof value === 'string' && value.length > 0
+    }
+
+    /**
+     * Validates a finite number.
+     * @param {unknown} value Candidate.
+     * @returns {boolean} Whether the value is valid.
+     */
+    static #number(value) {
+        return typeof value === 'number' && Number.isFinite(value)
+    }
+
+    /**
+     * Validates a positive finite number.
+     * @param {unknown} value Candidate.
+     * @returns {boolean} Whether the value is valid.
+     */
+    static #positive(value) {
+        return CircuitJsonToolkitElementSchema.#number(value) && value > 0
+    }
+
+    /**
+     * Validates one finite point.
+     * @param {unknown} value Candidate.
+     * @returns {boolean} Whether the point is valid.
+     */
+    static #point(value) {
+        return Boolean(
+            value &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            CircuitJsonToolkitElementSchema.#number(value.x) &&
+            CircuitJsonToolkitElementSchema.#number(value.y)
+        )
+    }
+
+    /**
+     * Validates one positive image size.
+     * @param {unknown} value Candidate.
+     * @returns {boolean} Whether the size is valid.
+     */
+    static #size(value) {
+        return Boolean(
+            value &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            CircuitJsonToolkitElementSchema.#positive(value.width) &&
+            CircuitJsonToolkitElementSchema.#positive(value.height)
+        )
+    }
+}
+
+Object.freeze(CircuitJsonToolkitElementSchema.prototype)
+Object.freeze(CircuitJsonToolkitElementSchema)

package/src/core/CircuitJsonUnitParsers.mjs

@@ -0,0 +1,101 @@
+const LENGTH_FACTORS_TO_MM = new Map([
+    ['mm', 1],
+    ['millimeter', 1],
+    ['millimeters', 1],
+    ['cm', 10],
+    ['centimeter', 10],
+    ['centimeters', 10],
+    ['m', 1000],
+    ['meter', 1000],
+    ['meters', 1000],
+    ['in', 25.4],
+    ['inch', 25.4],
+    ['inches', 25.4],
+    ['mil', 0.0254],
+    ['mils', 0.0254],
+    ['um', 0.001],
+    ['micrometer', 0.001],
+    ['micrometers', 0.001]
+])
+const ANGLE_FACTORS_TO_DEG = new Map([
+    ['deg', 1],
+    ['degree', 1],
+    ['degrees', 1],
+    ['rad', 180 / Math.PI],
+    ['radian', 180 / Math.PI],
+    ['radians', 180 / Math.PI]
+])
+
+/**
+ * Rounds unit conversions to stable precision.
+ * @param {number} value Numeric value.
+ * @returns {number} Rounded value.
+ */
+export function round(value) {
+    return Math.round(value * 1_000_000) / 1_000_000
+}
+
+/**
+ * Parses one numeric value with an optional unit suffix.
+ * @param {unknown} value Value candidate.
+ * @param {Map<string, number>} unitFactors Unit factor lookup.
+ * @returns {number | null} Parsed value or null.
+ */
+function parseUnitValue(value, unitFactors) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? round(value) : null
+    }
+
+    const text = String(value ?? '').trim()
+    if (!text) return null
+    const match = text.match(
+        /^([+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?)\s*([a-z]+)?$/iu
+    )
+    if (!match) return null
+
+    const number = Number(match[1])
+    if (!Number.isFinite(number)) return null
+    const unit = String(match[2] || '').toLowerCase()
+    const factor = unit ? unitFactors.get(unit) : 1
+    return Number.isFinite(factor) ? round(number * factor) : null
+}
+
+/**
+ * Parses an optional millimeter length.
+ * @param {unknown} value Length candidate.
+ * @returns {number | null} Parsed length or null.
+ */
+export function optionalLength(value) {
+    return parseUnitValue(value, LENGTH_FACTORS_TO_MM)
+}
+
+/**
+ * Parses an optional degree angle.
+ * @param {unknown} value Angle candidate.
+ * @returns {number | null} Parsed angle or null.
+ */
+export function optionalAngle(value) {
+    return parseUnitValue(value, ANGLE_FACTORS_TO_DEG)
+}
+
+/**
+ * Parses an optional point.
+ * @param {{ x?: unknown, y?: unknown } | null | undefined} point Point.
+ * @returns {{ x: number, y: number } | null} Parsed point or null.
+ */
+export function optionalPoint(point) {
+    const x = optionalLength(point?.x)
+    const y = optionalLength(point?.y)
+    return x === null || y === null ? null : { x, y }
+}
+
+/**
+ * Parses an optional size.
+ * @param {{ width?: unknown, height?: unknown } | null | undefined} size Size.
+ * @returns {{ width: number, height: number } | null} Parsed size or null.
+ */
+export function optionalSize(size) {
+    const width = optionalLength(size?.width)
+    const height = optionalLength(size?.height)
+    return width === null || height === null ? null : { width, height }
+}