circuitjson-toolkit 1.0.3 → 1.0.10

package/src/core/CircuitJsonSupportMatrixBuilder.mjs

@@ -0,0 +1,259 @@
+import { CircuitJsonElementValidator } from './CircuitJsonElementValidator.mjs'
+
+const PCB_RENDERED_TYPES = new Set([
+    'pcb_board',
+    'pcb_breakout_point',
+    'pcb_component',
+    'pcb_copper_pour',
+    'pcb_copper_text',
+    'pcb_courtyard',
+    'pcb_courtyard_circle',
+    'pcb_courtyard_outline',
+    'pcb_courtyard_pill',
+    'pcb_courtyard_polygon',
+    'pcb_courtyard_rect',
+    'pcb_cutout',
+    'pcb_fabrication_note_dimension',
+    'pcb_fabrication_note_path',
+    'pcb_fabrication_note_rect',
+    'pcb_fabrication_note_text',
+    'pcb_ground_plane',
+    'pcb_ground_plane_region',
+    'pcb_group',
+    'pcb_hole',
+    'pcb_keepout',
+    'pcb_note_dimension',
+    'pcb_note_line',
+    'pcb_note_path',
+    'pcb_note_rect',
+    'pcb_note_text',
+    'pcb_panel',
+    'pcb_plated_hole',
+    'pcb_port',
+    'pcb_silkscreen_circle',
+    'pcb_silkscreen_graphic',
+    'pcb_silkscreen_line',
+    'pcb_silkscreen_oval',
+    'pcb_silkscreen_path',
+    'pcb_silkscreen_pill',
+    'pcb_silkscreen_rect',
+    'pcb_silkscreen_text',
+    'pcb_smtpad',
+    'pcb_solder_paste',
+    'pcb_text',
+    'pcb_thermal_spoke',
+    'pcb_trace',
+    'pcb_trace_hint',
+    'pcb_via'
+])
+
+const SCHEMATIC_RENDERED_TYPES = new Set([
+    'schematic_arc',
+    'schematic_box',
+    'schematic_circle',
+    'schematic_component',
+    'schematic_debug_object',
+    'schematic_group',
+    'schematic_line',
+    'schematic_net_label',
+    'schematic_path',
+    'schematic_port',
+    'schematic_rect',
+    'schematic_sheet',
+    'schematic_symbol',
+    'schematic_table',
+    'schematic_table_cell',
+    'schematic_text',
+    'schematic_trace',
+    'schematic_voltage_probe'
+])
+
+const ROUTING_DSN_TYPES = new Set([
+    'pcb_board',
+    'pcb_component',
+    'pcb_smtpad',
+    'pcb_trace',
+    'pcb_via',
+    'pcb_plated_hole',
+    'source_net'
+])
+
+/**
+ * Builds document-level support coverage reports from known element metadata.
+ */
+export class CircuitJsonSupportMatrixBuilder {
+    /**
+     * Builds a support matrix for the known schema snapshot and present rows.
+     * @param {object[]} [circuitJson] Parsed element array.
+     * @returns {{ sourceFormat: string, totals: object, rows: object[], gaps: object[] }}
+     */
+    static build(circuitJson = []) {
+        const elements = Array.isArray(circuitJson) ? circuitJson : []
+        const presentTypes = new Set(
+            elements
+                .map((element) => String(element?.type || ''))
+                .filter(Boolean)
+        )
+        const rows = CircuitJsonElementValidator.knownElementTypes().map(
+            (type) =>
+                CircuitJsonSupportMatrixBuilder.#row(
+                    type,
+                    presentTypes.has(type)
+                )
+        )
+
+        return {
+            sourceFormat: 'circuitjson',
+            totals: CircuitJsonSupportMatrixBuilder.#totals(rows, presentTypes),
+            rows,
+            gaps: rows.flatMap((row) =>
+                CircuitJsonSupportMatrixBuilder.#gaps(row)
+            )
+        }
+    }
+
+    /**
+     * Builds one matrix row.
+     * @param {string} type Element type.
+     * @param {boolean} present Whether the current document contains the type.
+     * @returns {object}
+     */
+    static #row(type, present) {
+        const capabilities = CircuitJsonSupportMatrixBuilder.#capabilities(type)
+        return {
+            type,
+            family: CircuitJsonSupportMatrixBuilder.#family(type),
+            present,
+            status: CircuitJsonSupportMatrixBuilder.#status(capabilities),
+            capabilities
+        }
+    }
+
+    /**
+     * Resolves capability labels for one type.
+     * @param {string} type Element type.
+     * @returns {Record<string, string>}
+     */
+    static #capabilities(type) {
+        const capabilities = {
+            validation: 'known',
+            parser: 'preserved',
+            indexer: 'indexed',
+            diagnostics: CircuitJsonSupportMatrixBuilder.#diagnostics(type),
+            schematic: SCHEMATIC_RENDERED_TYPES.has(type) ? 'rendered' : 'none',
+            pcb: PCB_RENDERED_TYPES.has(type) ? 'rendered' : 'none',
+            bom: type === 'source_component' ? 'grouped' : 'none',
+            manufacturing: CircuitJsonSupportMatrixBuilder.#manufacturing(type),
+            simulation: type.startsWith('simulation_') ? 'preserved' : 'none'
+        }
+
+        if (type === 'pcb_component') {
+            capabilities.manufacturing = 'pick-and-place'
+        }
+
+        return capabilities
+    }
+
+    /**
+     * Resolves diagnostic support for one type.
+     * @param {string} type Element type.
+     * @returns {string}
+     */
+    static #diagnostics(type) {
+        return /(?:error|warning)/u.test(type) ? 'normalized' : 'none'
+    }
+
+    /**
+     * Resolves manufacturing support for one type.
+     * @param {string} type Element type.
+     * @returns {string}
+     */
+    static #manufacturing(type) {
+        if (ROUTING_DSN_TYPES.has(type)) return 'routing-dsn'
+        return 'none'
+    }
+
+    /**
+     * Resolves an overall support status.
+     * @param {Record<string, string>} capabilities Capability labels.
+     * @returns {'full' | 'partial' | 'metadata'}
+     */
+    static #status(capabilities) {
+        if (
+            capabilities.pcb === 'rendered' ||
+            capabilities.schematic === 'rendered' ||
+            capabilities.diagnostics === 'normalized'
+        ) {
+            return capabilities.manufacturing === 'routing-dsn'
+                ? 'partial'
+                : 'full'
+        }
+
+        return 'metadata'
+    }
+
+    /**
+     * Builds gap rows for present partially supported capabilities.
+     * @param {object} row Matrix row.
+     * @returns {object[]}
+     */
+    static #gaps(row) {
+        if (!row.present) return []
+        if (row.capabilities.manufacturing === 'routing-dsn') {
+            return [
+                {
+                    type: row.type,
+                    capability: 'manufacturing',
+                    status: 'partial',
+                    detail: 'Routing exchange metadata is generated without full fabrication packaging.'
+                }
+            ]
+        }
+        if (row.status === 'metadata') {
+            return [
+                {
+                    type: row.type,
+                    capability: 'rendering',
+                    status: 'metadata',
+                    detail: 'The element is preserved for downstream consumers.'
+                }
+            ]
+        }
+        return []
+    }
+
+    /**
+     * Builds aggregate matrix counts.
+     * @param {object[]} rows Matrix rows.
+     * @param {Set<string>} presentTypes Present element types.
+     * @returns {object}
+     */
+    static #totals(rows, presentTypes) {
+        return {
+            knownElementTypes: rows.length,
+            presentElementTypes: rows.filter((row) => row.present).length,
+            renderedElementTypes: rows.filter(
+                (row) =>
+                    row.present &&
+                    (row.capabilities.pcb === 'rendered' ||
+                        row.capabilities.schematic === 'rendered')
+            ).length,
+            diagnosticElementTypes: rows.filter(
+                (row) =>
+                    row.present && row.capabilities.diagnostics === 'normalized'
+            ).length,
+            unknownPresentElementTypes: [...presentTypes].filter(
+                (type) => !rows.some((row) => row.type === type)
+            ).length
+        }
+    }
+
+    /**
+     * Resolves the top-level element family.
+     * @param {string} type Element type.
+     * @returns {string}
+     */
+    static #family(type) {
+        return String(type || '').split('_')[0] || 'unknown'
+    }
+}

package/src/core/CircuitJsonUnits.mjs

@@ -1,9 +1,114 @@
 const MILS_PER_MM = 39.37007874015748
+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]
+])
 
 /**
  * Unit helpers for CircuitJSON's millimeter-based PCB dimensions.
  */
 export class CircuitJsonUnits {
+    /**
+     * Converts a length value to millimeters.
+     * @param {unknown} value Length candidate.
+     * @param {number} [fallback] Fallback millimeter value.
+     * @returns {number}
+     */
+    static length(value, fallback = 0) {
+        return (
+            CircuitJsonUnits.optionalLength(value) ??
+            CircuitJsonUnits.#round(fallback)
+        )
+    }
+
+    /**
+     * Converts a length value to millimeters, or null when invalid.
+     * @param {unknown} value Length candidate.
+     * @returns {number | null}
+     */
+    static optionalLength(value) {
+        return CircuitJsonUnits.#parseUnitValue(value, LENGTH_FACTORS_TO_MM)
+    }
+
+    /**
+     * Converts an angle value to degrees.
+     * @param {unknown} value Angle candidate.
+     * @param {number} [fallback] Fallback degree value.
+     * @returns {number}
+     */
+    static angle(value, fallback = 0) {
+        return (
+            CircuitJsonUnits.optionalAngle(value) ??
+            CircuitJsonUnits.#round(fallback)
+        )
+    }
+
+    /**
+     * Converts an angle value to degrees, or null when invalid.
+     * @param {unknown} value Angle candidate.
+     * @returns {number | null}
+     */
+    static optionalAngle(value) {
+        return CircuitJsonUnits.#parseUnitValue(value, ANGLE_FACTORS_TO_DEG)
+    }
+
+    /**
+     * Converts a point to normalized millimeter coordinates.
+     * @param {{ x?: unknown, y?: unknown } | null | undefined} point Point.
+     * @returns {{ x: number, y: number }}
+     */
+    static point(point) {
+        return {
+            x: CircuitJsonUnits.length(point?.x, 0),
+            y: CircuitJsonUnits.length(point?.y, 0)
+        }
+    }
+
+    /**
+     * Converts a point to normalized millimeter coordinates when valid.
+     * @param {{ x?: unknown, y?: unknown } | null | undefined} point Point.
+     * @returns {{ x: number, y: number } | null}
+     */
+    static optionalPoint(point) {
+        const x = CircuitJsonUnits.optionalLength(point?.x)
+        const y = CircuitJsonUnits.optionalLength(point?.y)
+        return x === null || y === null ? null : { x, y }
+    }
+
+    /**
+     * Converts a size to normalized millimeter dimensions.
+     * @param {{ width?: unknown, height?: unknown } | null | undefined} size Size.
+     * @returns {{ width: number, height: number } | null}
+     */
+    static optionalSize(size) {
+        const width = CircuitJsonUnits.optionalLength(size?.width)
+        const height = CircuitJsonUnits.optionalLength(size?.height)
+        return width === null || height === null ? null : { width, height }
+    }
+
     /**
      * Converts millimeters to mils.
      * @param {unknown} value Millimeter value.
@@ -12,7 +117,7 @@ export class CircuitJsonUnits {
      */
     static mmToMil(value, fallback = 0) {
         return CircuitJsonUnits.#round(
-            CircuitJsonUnits.#number(value, fallback) * MILS_PER_MM
+            CircuitJsonUnits.length(value, fallback) * MILS_PER_MM
         )
     }
 
@@ -29,14 +134,34 @@ export class CircuitJsonUnits {
     }
 
     /**
-     * Converts a value to a finite number.
-     * @param {unknown} value Candidate number.
-     * @param {number} fallback Fallback number.
-     * @returns {number}
+     * 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}
      */
-    static #number(value, fallback) {
-        const numeric = Number(value)
-        return Number.isFinite(numeric) ? numeric : fallback
+    static #parseUnitValue(value, unitFactors) {
+        if (typeof value === 'number') {
+            return Number.isFinite(value)
+                ? CircuitJsonUnits.#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
+        if (!Number.isFinite(factor)) return null
+
+        return CircuitJsonUnits.#round(number * factor)
     }
 
     /**

package/src/core/spice/SpiceCompatibilityPreprocessor.mjs

@@ -0,0 +1,139 @@
+const PSPICE_NUMBER_TOKEN = String.raw`([+-]?(?:(?:\d+(?:\.\d*)?)|(?:\.\d+))(?:[eE][+-]?\d+)?)`
+const PSPICE_COMPARISON_OPERATOR = '(?:<=|>=|==|!=|(?<![!<>=])=(?!=)|<|>)'
+const PSPICE_COMPARISON_OPERAND = String.raw`(?:V\s*\([^)]*\)|\{[^}\r\n]+\}|${PSPICE_NUMBER_TOKEN}(?:[a-zA-Z]+)?|[A-Za-z_][\w.$]*)`
+const PSPICE_COMPARISON_EXPRESSION = String.raw`${PSPICE_COMPARISON_OPERAND}\s*${PSPICE_COMPARISON_OPERATOR}\s*${PSPICE_COMPARISON_OPERAND}`
+const PSPICE_COMPARISON_BEFORE_CARET_PATTERN = new RegExp(
+    String.raw`${PSPICE_COMPARISON_EXPRESSION}\s*$`,
+    'i'
+)
+const PSPICE_COMPARISON_AFTER_CARET_PATTERN = new RegExp(
+    String.raw`^\s*\+?\s*${PSPICE_COMPARISON_EXPRESSION}`,
+    'i'
+)
+
+/**
+ * Rewrites narrow, well-understood SPICE compatibility syntax.
+ */
+export class SpiceCompatibilityPreprocessor {
+    /**
+     * Returns a netlist with supported compatibility syntax rewritten.
+     * @param {string} spiceString Raw SPICE netlist text.
+     * @returns {string}
+     */
+    static rewrite(spiceString) {
+        return SpiceCompatibilityPreprocessor.#rewriteValueBooleanCarets(
+            SpiceCompatibilityPreprocessor.#rewriteResistorTemperaturePairs(
+                spiceString
+            )
+        )
+    }
+
+    /**
+     * Rewrites resistor TC pairs to separate TC1 and TC2 assignments.
+     * @param {string} spiceString Raw SPICE netlist text.
+     * @returns {string}
+     */
+    static #rewriteResistorTemperaturePairs(spiceString) {
+        return String(spiceString || '')
+            .split(/\r?\n/)
+            .map((line) => {
+                if (!/^\s*r/i.test(line)) return line
+
+                return line.replace(
+                    new RegExp(
+                        String.raw`\bTC\s*=\s*${PSPICE_NUMBER_TOKEN}\s*,\s*${PSPICE_NUMBER_TOKEN}\b`,
+                        'gi'
+                    ),
+                    'TC1=$1 TC2=$2'
+                )
+            })
+            .join('\n')
+    }
+
+    /**
+     * Rewrites boolean caret operators inside VALUE expression blocks.
+     * @param {string} spiceString Raw SPICE netlist text.
+     * @returns {string}
+     */
+    static #rewriteValueBooleanCarets(spiceString) {
+        let result = ''
+        let cursor = 0
+        const valueStartPattern = /\bVALUE\s*\{/gi
+
+        for (;;) {
+            valueStartPattern.lastIndex = cursor
+            const match = valueStartPattern.exec(spiceString)
+            if (!match) break
+
+            const blockStart = match.index
+            const firstBraceIndex = spiceString.indexOf('{', blockStart)
+            const blockEnd =
+                SpiceCompatibilityPreprocessor.#findBalancedBlockEnd(
+                    spiceString,
+                    firstBraceIndex
+                )
+
+            if (blockEnd === -1) break
+
+            result += spiceString.slice(cursor, blockStart)
+            const block = spiceString.slice(blockStart, blockEnd)
+            result += block.replace(/\s+\^\s+/g, (operator, offset, full) => {
+                if (
+                    SpiceCompatibilityPreprocessor.#isValueBooleanCaret(
+                        full,
+                        offset,
+                        operator.length
+                    )
+                ) {
+                    return operator.replace('^', '!=')
+                }
+
+                return operator
+            })
+            cursor = blockEnd
+        }
+
+        return result + spiceString.slice(cursor)
+    }
+
+    /**
+     * Finds the exclusive end offset of a balanced brace block.
+     * @param {string} text Source text.
+     * @param {number} firstBraceIndex Offset of the opening brace.
+     * @returns {number}
+     */
+    static #findBalancedBlockEnd(text, firstBraceIndex) {
+        if (firstBraceIndex < 0) return -1
+
+        let depth = 0
+        for (let index = firstBraceIndex; index < text.length; index += 1) {
+            const character = text[index]
+            if (character === '{') {
+                depth += 1
+            } else if (character === '}') {
+                depth -= 1
+                if (depth === 0) return index + 1
+            }
+        }
+
+        return -1
+    }
+
+    /**
+     * Returns true when a caret separates two comparison expressions.
+     * @param {string} block VALUE block text.
+     * @param {number} caretOffset Caret operator offset.
+     * @param {number} operatorLength Operator token length.
+     * @returns {boolean}
+     */
+    static #isValueBooleanCaret(block, caretOffset, operatorLength) {
+        return (
+            PSPICE_COMPARISON_BEFORE_CARET_PATTERN.test(
+                block.slice(0, caretOffset)
+            ) &&
+            PSPICE_COMPARISON_AFTER_CARET_PATTERN.test(
+                block.slice(caretOffset + operatorLength)
+            )
+        )
+    }
+}