circuitjson-toolkit 1.0.3 → 1.0.16

package/src/core/SelectedPartCircuitJsonExportAdapter.mjs

@@ -0,0 +1,335 @@
+import { CircuitJsonDocument } from './CircuitJsonDocument.mjs'
+
+/**
+ * Builds standards-shaped CircuitJSON for selected-part ZIP exports.
+ */
+export class SelectedPartCircuitJsonExportAdapter {
+    /**
+     * Builds a CircuitJSON element array for one selected part.
+     * @param {{ designator?: string, symbol?: object, footprint?: object }} selectedPart Selected part data.
+     * @param {object} documentModel Active document model.
+     * @param {string} partName Export artifact name.
+     * @returns {object[]}
+     */
+    static build(selectedPart, documentModel, partName) {
+        const designator = selectedPart.designator || 'selected-part'
+        const idToken =
+            SelectedPartCircuitJsonExportAdapter.#safeIdentifier(designator)
+        const sourceComponentId = 'source_component_' + idToken
+        const pcbComponentId = 'pcb_component_' + idToken
+        const circuitJson = [
+            {
+                type: 'source_project_metadata',
+                name: documentModel?.fileName || 'Selected part export',
+                software_used_string:
+                    documentModel?.sourceFormat || documentModel?.fileType || ''
+            },
+            {
+                type: 'source_component',
+                source_component_id: sourceComponentId,
+                name: partName,
+                ftype: 'simple_chip',
+                manufacturer_part_number: selectedPart.symbol?.value || '',
+                supplier_part_numbers: {}
+            },
+            {
+                type: 'schematic_component',
+                schematic_component_id: 'schematic_component_' + idToken,
+                source_component_id: sourceComponentId,
+                center: { x: 0, y: 0 },
+                size: SelectedPartCircuitJsonExportAdapter.#schematicSize(
+                    selectedPart
+                ),
+                rotation: 0
+            },
+            {
+                type: 'pcb_component',
+                pcb_component_id: pcbComponentId,
+                source_component_id: sourceComponentId,
+                center: SelectedPartCircuitJsonExportAdapter.#footprintCenter(
+                    selectedPart
+                ),
+                layer: 'top',
+                rotation: 0,
+                width: SelectedPartCircuitJsonExportAdapter.#footprintSize(
+                    selectedPart
+                ).width,
+                height: SelectedPartCircuitJsonExportAdapter.#footprintSize(
+                    selectedPart
+                ).height
+            },
+            ...SelectedPartCircuitJsonExportAdapter.#sourcePorts(
+                selectedPart,
+                sourceComponentId
+            ),
+            ...SelectedPartCircuitJsonExportAdapter.#pcbPads(
+                selectedPart,
+                pcbComponentId
+            )
+        ]
+
+        CircuitJsonDocument.assertModel(circuitJson)
+        return circuitJson
+    }
+
+    /**
+     * Builds source port entries.
+     * @param {{ symbol?: { pins?: object[] } }} selectedPart Selected part data.
+     * @param {string} sourceComponentId Source component id.
+     * @returns {object[]}
+     */
+    static #sourcePorts(selectedPart, sourceComponentId) {
+        return SelectedPartCircuitJsonExportAdapter.#array(
+            selectedPart.symbol?.pins
+        ).map((pin, index) => {
+            const pinName = String(pin.name || index + 1)
+            const pinNumber = String(pin.number || index + 1)
+            const entry = {
+                type: 'source_port',
+                source_port_id:
+                    sourceComponentId +
+                    '_port_' +
+                    SelectedPartCircuitJsonExportAdapter.#safeIdentifier(
+                        pinNumber
+                    ),
+                source_component_id: sourceComponentId,
+                name: pinName,
+                port_hints: [pinNumber]
+            }
+            const numericPinNumber =
+                SelectedPartCircuitJsonExportAdapter.#numericPinNumber(
+                    pinNumber
+                )
+            if (numericPinNumber !== null) entry.pin_number = numericPinNumber
+            return entry
+        })
+    }
+
+    /**
+     * Builds PCB SMT pad entries.
+     * @param {{ footprint?: { pads?: object[] } }} selectedPart Selected part data.
+     * @param {string} pcbComponentId PCB component id.
+     * @returns {object[]}
+     */
+    static #pcbPads(selectedPart, pcbComponentId) {
+        return SelectedPartCircuitJsonExportAdapter.#array(
+            selectedPart.footprint?.pads
+        ).map((pad, index) =>
+            SelectedPartCircuitJsonExportAdapter.#pcbPad(
+                pad,
+                index,
+                pcbComponentId
+            )
+        )
+    }
+
+    /**
+     * Builds one PCB SMT pad entry.
+     * @param {object} pad Pad data.
+     * @param {number} index Pad index.
+     * @param {string} pcbComponentId PCB component id.
+     * @returns {object}
+     */
+    static #pcbPad(pad, index, pcbComponentId) {
+        const padNumber = String(pad.number || index + 1)
+        const width = SelectedPartCircuitJsonExportAdapter.#number(pad.width, 1)
+        const height = SelectedPartCircuitJsonExportAdapter.#number(
+            pad.height,
+            1
+        )
+        const rotation = SelectedPartCircuitJsonExportAdapter.#number(
+            pad.ccw_rotation ?? pad.rotation,
+            0
+        )
+        const shape =
+            rotation !== 0
+                ? 'rotated_rect'
+                : SelectedPartCircuitJsonExportAdapter.#padShape(
+                      pad,
+                      width,
+                      height
+                  )
+        const entry = {
+            type: 'pcb_smtpad',
+            shape,
+            pcb_smtpad_id:
+                pcbComponentId +
+                '_pad_' +
+                SelectedPartCircuitJsonExportAdapter.#safeIdentifier(padNumber),
+            pcb_component_id: pcbComponentId,
+            port_hints: [padNumber],
+            x: SelectedPartCircuitJsonExportAdapter.#number(pad.x, 0),
+            y: SelectedPartCircuitJsonExportAdapter.#number(pad.y, 0),
+            layer: SelectedPartCircuitJsonExportAdapter.#padLayer(pad)
+        }
+
+        if (shape === 'circle') {
+            entry.radius = Math.max(width, height) / 2
+        } else {
+            entry.width = width
+            entry.height = height
+        }
+
+        if (shape === 'rotated_rect') entry.ccw_rotation = rotation
+        return entry
+    }
+
+    /**
+     * Resolves the schematic component size.
+     * @param {{ symbol?: { pins?: object[] } }} selectedPart Selected part data.
+     * @returns {{ width: number, height: number }}
+     */
+    static #schematicSize(selectedPart) {
+        const pinCount = SelectedPartCircuitJsonExportAdapter.#array(
+            selectedPart.symbol?.pins
+        ).length
+        const edge = Math.max(2.54, Math.ceil(Math.sqrt(pinCount || 1)) * 2.54)
+        return { width: edge, height: edge }
+    }
+
+    /**
+     * Resolves footprint size from owned pads.
+     * @param {{ footprint?: { pads?: object[] } }} selectedPart Selected part data.
+     * @returns {{ width: number, height: number }}
+     */
+    static #footprintSize(selectedPart) {
+        const bounds =
+            SelectedPartCircuitJsonExportAdapter.#footprintBounds(selectedPart)
+        return {
+            width: Math.max(bounds.maxX - bounds.minX, 1),
+            height: Math.max(bounds.maxY - bounds.minY, 1)
+        }
+    }
+
+    /**
+     * Resolves footprint center from owned pads.
+     * @param {{ footprint?: { pads?: object[] } }} selectedPart Selected part data.
+     * @returns {{ x: number, y: number }}
+     */
+    static #footprintCenter(selectedPart) {
+        const bounds =
+            SelectedPartCircuitJsonExportAdapter.#footprintBounds(selectedPart)
+        return {
+            x: (bounds.minX + bounds.maxX) / 2,
+            y: (bounds.minY + bounds.maxY) / 2
+        }
+    }
+
+    /**
+     * Resolves footprint pad bounds.
+     * @param {{ footprint?: { pads?: object[] } }} selectedPart Selected part data.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number }}
+     */
+    static #footprintBounds(selectedPart) {
+        const pads = SelectedPartCircuitJsonExportAdapter.#array(
+            selectedPart.footprint?.pads
+        )
+        if (!pads.length)
+            return { minX: -0.5, minY: -0.5, maxX: 0.5, maxY: 0.5 }
+
+        return pads.reduce(
+            (bounds, pad) => {
+                const x = SelectedPartCircuitJsonExportAdapter.#number(pad.x, 0)
+                const y = SelectedPartCircuitJsonExportAdapter.#number(pad.y, 0)
+                const halfWidth =
+                    SelectedPartCircuitJsonExportAdapter.#number(pad.width, 1) /
+                    2
+                const halfHeight =
+                    SelectedPartCircuitJsonExportAdapter.#number(
+                        pad.height,
+                        1
+                    ) / 2
+                return {
+                    minX: Math.min(bounds.minX, x - halfWidth),
+                    minY: Math.min(bounds.minY, y - halfHeight),
+                    maxX: Math.max(bounds.maxX, x + halfWidth),
+                    maxY: Math.max(bounds.maxY, y + halfHeight)
+                }
+            },
+            {
+                minX: Infinity,
+                minY: Infinity,
+                maxX: -Infinity,
+                maxY: -Infinity
+            }
+        )
+    }
+
+    /**
+     * Resolves an SMT pad shape.
+     * @param {object} pad Pad data.
+     * @param {number} width Pad width.
+     * @param {number} height Pad height.
+     * @returns {string}
+     */
+    static #padShape(pad, width, height) {
+        const rawShape = String(
+            pad.shape || pad.shapeTopName || pad.shapeName || ''
+        ).toLowerCase()
+        if (
+            rawShape.includes('circle') ||
+            rawShape.includes('round') ||
+            rawShape.includes('oval')
+        ) {
+            return width === height ? 'circle' : 'rect'
+        }
+        return 'rect'
+    }
+
+    /**
+     * Resolves an SMT pad layer.
+     * @param {object} pad Pad data.
+     * @returns {string}
+     */
+    static #padLayer(pad) {
+        const layer = String(pad.layer || pad.layerName || '').toLowerCase()
+        if (
+            layer.includes('bottom') ||
+            layer === 'bottom' ||
+            pad.layerId === 32
+        ) {
+            return 'bottom'
+        }
+        return 'top'
+    }
+
+    /**
+     * Returns a number pin when a pin token is numeric.
+     * @param {unknown} value Candidate pin number.
+     * @returns {number | null}
+     */
+    static #numericPinNumber(value) {
+        const text = String(value || '').trim()
+        const parsed = Number(text)
+        return text && Number.isFinite(parsed) ? parsed : null
+    }
+
+    /**
+     * Creates a safe CircuitJSON id token.
+     * @param {unknown} value Raw value.
+     * @returns {string}
+     */
+    static #safeIdentifier(value) {
+        return String(value || 'selected_part').replace(/[^a-z0-9_]/giu, '_')
+    }
+
+    /**
+     * Normalizes a possible array.
+     * @param {unknown} value Candidate array.
+     * @returns {object[]}
+     */
+    static #array(value) {
+        return Array.isArray(value) ? value : []
+    }
+
+    /**
+     * Reads a finite number with fallback.
+     * @param {unknown} value Candidate number.
+     * @param {number} fallback Fallback number.
+     * @returns {number}
+     */
+    static #number(value, fallback) {
+        const parsed = Number(value)
+        return Number.isFinite(parsed) ? parsed : fallback
+    }
+}

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)
+            )
+        )
+    }
+}

package/src/core/spice/SpiceDirectiveParser.mjs

@@ -0,0 +1,231 @@
+const NUMBER_SUFFIX_MULTIPLIERS = {
+    t: 1e12,
+    g: 1e9,
+    meg: 1e6,
+    k: 1e3,
+    m: 1e-3,
+    ms: 1e-3,
+    u: 1e-6,
+    us: 1e-6,
+    n: 1e-9,
+    ns: 1e-9,
+    p: 1e-12,
+    ps: 1e-12,
+    f: 1e-15,
+    fs: 1e-15,
+    s: 1
+}
+const VOLTAGE_PROBE_COMMENT_PATTERN =
+    /^\s*\*\s*(?:ecadforge_voltage_probe|circuitjson_voltage_probe|simulation_voltage_probe)\s+(.+)\s*$/
+const CURRENT_PROBE_COMMENT_PATTERN =
+    /^\s*\*\s*(?:ecadforge_current_probe|circuitjson_current_probe|simulation_current_probe)\s+(.+)\s*$/
+
+/**
+ * Parses SPICE directives and metadata comments used by simulation helpers.
+ */
+export class SpiceDirectiveParser {
+    /**
+     * Parses transient directive timing parameters.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {{ tstep?: number, tstop?: number, tstart?: number, tmax?: number, uic?: boolean } | null}
+     */
+    static parseTransient(spiceString) {
+        for (const rawLine of String(spiceString || '').split(/\r?\n/)) {
+            const line = rawLine.trim()
+            if (!line || line.startsWith('*')) continue
+            if (!line.toLowerCase().startsWith('.tran')) continue
+
+            const [withoutComment = ''] = line.split(';')
+            const tokens = withoutComment.split(/\s+/).filter(Boolean)
+            const values = []
+            let uic = false
+
+            for (const token of tokens.slice(1)) {
+                if (token.toLowerCase() === 'uic') {
+                    uic = true
+                    continue
+                }
+
+                const value = SpiceDirectiveParser.parseNumber(token)
+                if (value !== undefined) values.push(value)
+            }
+
+            return {
+                ...(values[0] !== undefined ? { tstep: values[0] } : {}),
+                ...(values[1] !== undefined ? { tstop: values[1] } : {}),
+                ...(values[2] !== undefined ? { tstart: values[2] } : {}),
+                ...(values[3] !== undefined ? { tmax: values[3] } : {}),
+                ...(uic ? { uic: true } : {})
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Parses requested transient plot tokens from the first PRINT directive.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {Map<string, string> | null}
+     */
+    static parseRequestedPlots(spiceString) {
+        const match = String(spiceString || '').match(/\.print\s+tran\s+(.*)/i)
+        if (!match?.[1]) return null
+
+        const tokens = match[1].match(/[VI]\s*\([^)]+\)/gi)
+        if (!tokens) return null
+
+        const plots = new Map()
+        for (const token of tokens) {
+            const normalizedToken = SpiceDirectiveParser.normalizeVector(token)
+            if (!plots.has(normalizedToken)) {
+                plots.set(normalizedToken, token)
+            }
+        }
+
+        return plots
+    }
+
+    /**
+     * Extracts voltage probe metadata comments from a netlist.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {Map<string, object>}
+     */
+    static extractVoltageProbeMetadata(spiceString) {
+        return SpiceDirectiveParser.#extractProbeMetadata(
+            spiceString,
+            VOLTAGE_PROBE_COMMENT_PATTERN,
+            (parsed) => {
+                if (
+                    typeof parsed.simulation_voltage_probe_id !== 'string' ||
+                    typeof parsed.spice_vector !== 'string' ||
+                    typeof parsed.source_node_name !== 'string'
+                ) {
+                    return null
+                }
+
+                return {
+                    simulation_voltage_probe_id:
+                        parsed.simulation_voltage_probe_id,
+                    name:
+                        typeof parsed.name === 'string'
+                            ? parsed.name
+                            : undefined,
+                    spice_vector: parsed.spice_vector,
+                    source_node_name: parsed.source_node_name,
+                    reference_node_name:
+                        typeof parsed.reference_node_name === 'string'
+                            ? parsed.reference_node_name
+                            : undefined
+                }
+            }
+        )
+    }
+
+    /**
+     * Extracts current probe metadata comments from a netlist.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {Map<string, object>}
+     */
+    static extractCurrentProbeMetadata(spiceString) {
+        return SpiceDirectiveParser.#extractProbeMetadata(
+            spiceString,
+            CURRENT_PROBE_COMMENT_PATTERN,
+            (parsed) => {
+                if (
+                    typeof parsed.simulation_current_probe_id !== 'string' ||
+                    typeof parsed.spice_vector !== 'string'
+                ) {
+                    return null
+                }
+
+                return {
+                    simulation_current_probe_id:
+                        parsed.simulation_current_probe_id,
+                    name:
+                        typeof parsed.name === 'string'
+                            ? parsed.name
+                            : undefined,
+                    spice_vector: parsed.spice_vector,
+                    source_component_id:
+                        typeof parsed.source_component_id === 'string'
+                            ? parsed.source_component_id
+                            : undefined,
+                    source_trace_id:
+                        typeof parsed.source_trace_id === 'string'
+                            ? parsed.source_trace_id
+                            : undefined
+                }
+            }
+        )
+    }
+
+    /**
+     * Normalizes a simulator vector token for map lookups.
+     * @param {string} value Raw vector token.
+     * @returns {string}
+     */
+    static normalizeVector(value) {
+        return String(value || '')
+            .toLowerCase()
+            .replace(/\s/g, '')
+    }
+
+    /**
+     * Parses a SPICE numeric token with common suffix multipliers.
+     * @param {string} token Numeric token.
+     * @returns {number | undefined}
+     */
+    static parseNumber(token) {
+        const normalized = String(token || '')
+            .replace(/[,]/g, '')
+            .toLowerCase()
+        const match = normalized.match(
+            /^([+-]?\d*\.?\d+(?:e[+-]?\d+)?)([a-z]+)?$/i
+        )
+
+        if (!match) return undefined
+
+        const base = Number.parseFloat(match[1] || '')
+        if (!Number.isFinite(base)) return undefined
+
+        const suffix = match[2] || ''
+        if (!suffix) return base
+
+        const multiplier =
+            NUMBER_SUFFIX_MULTIPLIERS[suffix] ??
+            NUMBER_SUFFIX_MULTIPLIERS[suffix.replace(/s$/, '')] ??
+            1
+
+        return base * multiplier
+    }
+
+    /**
+     * Extracts JSON probe metadata comments with a validator callback.
+     * @param {string} spiceString SPICE netlist text.
+     * @param {RegExp} pattern Comment matcher.
+     * @param {(parsed: object) => object | null} shapeMetadata Metadata shaper.
+     * @returns {Map<string, object>}
+     */
+    static #extractProbeMetadata(spiceString, pattern, shapeMetadata) {
+        const metadata = new Map()
+
+        for (const line of String(spiceString || '').split(/\r?\n/)) {
+            const match = line.match(pattern)
+            if (!match?.[1]) continue
+
+            try {
+                const shapedMetadata = shapeMetadata(JSON.parse(match[1]))
+                if (!shapedMetadata) continue
+
+                metadata.set(
+                    SpiceDirectiveParser.normalizeVector(
+                        shapedMetadata.spice_vector
+                    ),
+                    shapedMetadata
+                )
+            } catch {}
+        }
+
+        return metadata
+    }
+}