circuitjson-toolkit 1.0.10 → 1.0.17

package/src/core/CircuitJsonSourceMetadata.mjs

@@ -0,0 +1,233 @@
+const COMPONENT_ICON_BY_TYPE = {
+    battery: 'battery',
+    capacitor: 'capacitor',
+    chip: 'chip',
+    connector: 'connector',
+    crystal: 'crystal',
+    current_source: 'source',
+    diode: 'diode',
+    fiducial: 'fiducial',
+    fuse: 'fuse',
+    ground: 'ground',
+    inductor: 'inductor',
+    interconnect: 'connector',
+    led: 'led',
+    mosfet: 'transistor',
+    op_amp: 'op-amp',
+    pin_header: 'connector',
+    potentiometer: 'potentiometer',
+    push_button: 'switch',
+    resistor: 'resistor',
+    resonator: 'crystal',
+    switch: 'switch',
+    test_point: 'test-point',
+    transistor: 'transistor',
+    voltage_probe: 'probe',
+    voltage_source: 'source'
+}
+
+/**
+ * Normalizes generic source-level CircuitJSON metadata for stable consumers.
+ */
+export class CircuitJsonSourceMetadata {
+    /**
+     * Builds a safe source net name from display-oriented text.
+     * @param {unknown} value Source net label.
+     * @param {{ fallback?: string, usedNames?: Set<string> }} [options]
+     * @returns {string}
+     */
+    static normalizeSourceNetName(value, options = {}) {
+        const fallback = String(options.fallback || 'net').trim() || 'net'
+        let name = String(value || '').trim() || fallback
+        name = name
+            .replaceAll('+', '_P')
+            .replaceAll('-', '_')
+            .replace(/[^A-Za-z0-9_]+/gu, '_')
+            .replace(/_+/gu, '_')
+            .replace(/_+$/u, '')
+        if (!name) {
+            name = fallback.replace(/[^A-Za-z0-9_]+/gu, '_') || 'net'
+        }
+        if (/^[0-9]/u.test(name)) {
+            name = 'net_' + name
+        }
+        return CircuitJsonSourceMetadata.#dedupeName(name, options.usedNames)
+    }
+
+    /**
+     * Builds a stable source port name from a pad or pin label.
+     * @param {unknown} value Source port label.
+     * @param {{ fallback?: string, usedNames?: Set<string> }} [options]
+     * @returns {string}
+     */
+    static normalizeSourcePortName(value, options = {}) {
+        const text = String(value ?? '').trim()
+        const fallback = String(options.fallback || 'pin').trim() || 'pin'
+        const name = /^[0-9]+$/u.test(text) ? 'pin' + Number(text) : text
+        return CircuitJsonSourceMetadata.#dedupeName(
+            name || fallback,
+            options.usedNames
+        )
+    }
+
+    /**
+     * Builds stable semantic metadata for one source component.
+     * @param {object} component Source component row.
+     * @returns {{ sourceFtype: string, componentType: string, componentIcon: string, supplierPartNumber: string, supplierPartNumbers: Record<string, string> }}
+     */
+    static normalizeSourceComponent(component) {
+        const sourceFtype =
+            CircuitJsonSourceMetadata.#sourceFtype(component) ||
+            CircuitJsonSourceMetadata.#inferSourceFtype(component)
+        const componentType = sourceFtype
+            .replace(/^simple_/u, '')
+            .replaceAll('_', '-')
+        const supplierPartNumbers =
+            CircuitJsonSourceMetadata.#supplierPartNumbers(component)
+        return {
+            sourceFtype,
+            componentType,
+            componentIcon:
+                COMPONENT_ICON_BY_TYPE[componentType.replaceAll('-', '_')] ||
+                componentType ||
+                'component',
+            supplierPartNumber: String(
+                Object.values(supplierPartNumbers).find(Boolean) || ''
+            ).trim(),
+            supplierPartNumbers
+        }
+    }
+
+    /**
+     * Returns a unique name against an optional used-name set.
+     * @param {string} name Base name.
+     * @param {Set<string> | undefined} usedNames Existing names.
+     * @returns {string}
+     */
+    static #dedupeName(name, usedNames) {
+        if (!(usedNames instanceof Set) || !usedNames.has(name)) return name
+        let index = 2
+        let candidate = name + '_' + index
+        while (usedNames.has(candidate)) {
+            index += 1
+            candidate = name + '_' + index
+        }
+        return candidate
+    }
+
+    /**
+     * Resolves an explicit source component function type.
+     * @param {object} component Source component row.
+     * @returns {string}
+     */
+    static #sourceFtype(component) {
+        return String(component?.ftype || component?.sourceFtype || '').trim()
+    }
+
+    /**
+     * Infers a source component function type from generic fields.
+     * @param {object} component Source component row.
+     * @returns {string}
+     */
+    static #inferSourceFtype(component) {
+        const reference = String(
+            component?.name ||
+                component?.reference ||
+                component?.designator ||
+                ''
+        ).trim()
+        const text = [
+            reference,
+            component?.footprint,
+            component?.package,
+            component?.package_name,
+            component?.value,
+            component?.description
+        ]
+            .map((value) => String(value || '').toLowerCase())
+            .filter(Boolean)
+            .join(' ')
+
+        if (text.includes('led')) return 'simple_led'
+        if (/^tp[0-9A-Z_-]*/iu.test(reference) || text.includes('test point')) {
+            return 'simple_test_point'
+        }
+        if (/^fid[0-9A-Z_-]*/iu.test(reference) || text.includes('fiducial')) {
+            return 'simple_fiducial'
+        }
+        if (/^sw[0-9A-Z_-]*/iu.test(reference) || text.includes('switch')) {
+            return 'simple_switch'
+        }
+        if (/^r[0-9A-Z_-]*/iu.test(reference) || component?.resistance) {
+            return 'simple_resistor'
+        }
+        if (/^c[0-9A-Z_-]*/iu.test(reference) || component?.capacitance) {
+            return 'simple_capacitor'
+        }
+        if (/^l[0-9A-Z_-]*/iu.test(reference) || component?.inductance) {
+            return 'simple_inductor'
+        }
+        if (text.includes('mosfet')) return 'simple_mosfet'
+        if (/^q[0-9A-Z_-]*/iu.test(reference) || text.includes('transistor')) {
+            return 'simple_transistor'
+        }
+        if (/^d[0-9A-Z_-]*/iu.test(reference)) return 'simple_diode'
+        if (/^(u|ic)[0-9A-Z_-]*/iu.test(reference) || text.includes('chip')) {
+            return 'simple_chip'
+        }
+        return ''
+    }
+
+    /**
+     * Normalizes supplier part fields into a stable keyed object.
+     * @param {object} component Source component row.
+     * @returns {Record<string, string>}
+     */
+    static #supplierPartNumbers(component) {
+        const numbers = {}
+        for (const field of ['supplier_part_numbers', 'supplierPartNumbers']) {
+            const value = component?.[field]
+            if (!value || typeof value !== 'object' || Array.isArray(value)) {
+                continue
+            }
+            for (const [key, entry] of Object.entries(value)) {
+                const normalized = String(entry || '').trim()
+                if (normalized) numbers[String(key || 'supplier')] = normalized
+            }
+        }
+        CircuitJsonSourceMetadata.#addSupplierNumber(
+            numbers,
+            'supplier',
+            component?.supplier_part_number ?? component?.supplierPartNumber
+        )
+        CircuitJsonSourceMetadata.#addSupplierNumber(
+            numbers,
+            'distributor',
+            component?.distributor_part_number ??
+                component?.distributorPartNumber
+        )
+        CircuitJsonSourceMetadata.#addSupplierNumber(
+            numbers,
+            'assembly',
+            component?.assembly_part_number ?? component?.assemblyPartNumber
+        )
+        CircuitJsonSourceMetadata.#addSupplierNumber(
+            numbers,
+            'catalog',
+            component?.catalog_part_number ?? component?.catalogPartNumber
+        )
+        return numbers
+    }
+
+    /**
+     * Adds one supplier part number when present.
+     * @param {Record<string, string>} numbers Supplier number map.
+     * @param {string} key Supplier key.
+     * @param {unknown} value Supplier part value.
+     * @returns {void}
+     */
+    static #addSupplierNumber(numbers, key, value) {
+        const normalized = String(value || '').trim()
+        if (normalized && !numbers[key]) numbers[key] = normalized
+    }
+}

package/src/core/CircuitJsonSupportMatrixBuilder.mjs

@@ -8,7 +8,9 @@ const PCB_RENDERED_TYPES = new Set([
     'pcb_copper_text',
     'pcb_courtyard',
     'pcb_courtyard_circle',
+    'pcb_courtyard_line',
     'pcb_courtyard_outline',
+    'pcb_courtyard_path',
     'pcb_courtyard_pill',
     'pcb_courtyard_polygon',
     'pcb_courtyard_rect',
@@ -78,6 +80,81 @@ const ROUTING_DSN_TYPES = new Set([
     'source_net'
 ])
 
+const VARIANT_ROWS_BY_SET = {
+    sourceComponentFtypes: {
+        type: 'source_component',
+        group: 'ftype',
+        capability: 'bom',
+        status: 'grouped'
+    },
+    pcbBoardShapes: {
+        type: 'pcb_board',
+        group: 'shape',
+        capability: 'pcb',
+        status: 'rendered'
+    },
+    pcbSmtPadShapes: {
+        type: 'pcb_smtpad',
+        group: 'shape',
+        capability: 'pcb',
+        status: 'rendered'
+    },
+    pcbHoleShapes: {
+        type: 'pcb_hole',
+        group: 'hole_shape',
+        capability: 'pcb',
+        status: 'rendered'
+    },
+    pcbPlatedHoleShapes: {
+        type: 'pcb_plated_hole',
+        group: 'shape',
+        capability: 'pcb',
+        status: 'rendered'
+    },
+    pcbPlatedHoleHoleShapes: {
+        type: 'pcb_plated_hole',
+        group: 'hole_shape',
+        capability: 'pcb',
+        status: 'rendered'
+    },
+    pcbSolderPasteShapes: {
+        type: 'pcb_solder_paste',
+        group: 'shape',
+        capability: 'pcb',
+        status: 'rendered'
+    },
+    pcbCutoutShapes: {
+        type: 'pcb_cutout',
+        group: 'shape',
+        capability: 'pcb',
+        status: 'rendered'
+    },
+    pcbCopperPourShapes: {
+        type: 'pcb_copper_pour',
+        group: 'shape',
+        capability: 'pcb',
+        status: 'rendered'
+    },
+    simulationSourceKinds: {
+        type: 'simulation_voltage_source',
+        group: 'kind',
+        capability: 'simulation',
+        status: 'summarized'
+    },
+    simulationWaveShapes: {
+        type: 'simulation_voltage_source',
+        group: 'wave_shape',
+        capability: 'simulation',
+        status: 'summarized'
+    },
+    simulationExperimentMethods: {
+        type: 'simulation_experiment',
+        group: 'spice_options.method',
+        capability: 'simulation',
+        status: 'summarized'
+    }
+}
+
 /**
  * Builds document-level support coverage reports from known element metadata.
  */
@@ -85,7 +162,7 @@ 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[] }}
+     * @returns {{ sourceFormat: string, totals: object, rows: object[], variantRows: object[], gaps: object[] }}
      */
     static build(circuitJson = []) {
         const elements = Array.isArray(circuitJson) ? circuitJson : []
@@ -101,11 +178,18 @@ export class CircuitJsonSupportMatrixBuilder {
                     presentTypes.has(type)
                 )
         )
+        const variantRows =
+            CircuitJsonSupportMatrixBuilder.#variantRows(elements)
 
         return {
             sourceFormat: 'circuitjson',
-            totals: CircuitJsonSupportMatrixBuilder.#totals(rows, presentTypes),
+            totals: CircuitJsonSupportMatrixBuilder.#totals(
+                rows,
+                presentTypes,
+                variantRows
+            ),
             rows,
+            variantRows,
             gaps: rows.flatMap((row) =>
                 CircuitJsonSupportMatrixBuilder.#gaps(row)
             )
@@ -142,6 +226,7 @@ export class CircuitJsonSupportMatrixBuilder {
             diagnostics: CircuitJsonSupportMatrixBuilder.#diagnostics(type),
             schematic: SCHEMATIC_RENDERED_TYPES.has(type) ? 'rendered' : 'none',
             pcb: PCB_RENDERED_TYPES.has(type) ? 'rendered' : 'none',
+            scene3d: type === 'cad_component' ? 'external-model' : 'none',
             bom: type === 'source_component' ? 'grouped' : 'none',
             manufacturing: CircuitJsonSupportMatrixBuilder.#manufacturing(type),
             simulation: type.startsWith('simulation_') ? 'preserved' : 'none'
@@ -182,6 +267,7 @@ export class CircuitJsonSupportMatrixBuilder {
         if (
             capabilities.pcb === 'rendered' ||
             capabilities.schematic === 'rendered' ||
+            capabilities.scene3d === 'external-model' ||
             capabilities.diagnostics === 'normalized'
         ) {
             return capabilities.manufacturing === 'routing-dsn'
@@ -222,13 +308,145 @@ export class CircuitJsonSupportMatrixBuilder {
         return []
     }
 
+    /**
+     * Builds variant coverage rows from active schema metadata.
+     * @param {object[]} elements Parsed element rows.
+     * @returns {object[]}
+     */
+    static #variantRows(elements) {
+        const schema = CircuitJsonElementValidator.variantSets()
+        const present =
+            CircuitJsonSupportMatrixBuilder.#presentVariants(elements)
+        return Object.entries(schema).flatMap(([setName, values]) => {
+            const definition = VARIANT_ROWS_BY_SET[setName]
+            if (!definition) return []
+            return values.map((value) =>
+                CircuitJsonSupportMatrixBuilder.#variantRow(
+                    setName,
+                    definition,
+                    value,
+                    present
+                )
+            )
+        })
+    }
+
+    /**
+     * Builds one variant coverage row.
+     * @param {string} setName Variant set name.
+     * @param {object} definition Row definition.
+     * @param {string} value Variant value.
+     * @param {Map<string, Set<string>>} present Present variant values.
+     * @returns {object}
+     */
+    static #variantRow(setName, definition, value, present) {
+        const isPresent = Boolean(present.get(setName)?.has(value))
+        return {
+            set: setName,
+            type: definition.type,
+            group: definition.group,
+            value,
+            present: isPresent,
+            capability: definition.capability,
+            status: definition.status,
+            note: CircuitJsonSupportMatrixBuilder.#variantNote(
+                definition,
+                value,
+                isPresent
+            )
+        }
+    }
+
+    /**
+     * Builds a short human-readable variant support note.
+     * @param {object} definition Variant row definition.
+     * @param {string} value Variant value.
+     * @param {boolean} present Whether the variant is present.
+     * @returns {string}
+     */
+    static #variantNote(definition, value, present) {
+        const label =
+            definition.type + '.' + definition.group + ' ' + value + ' is '
+        if (!present) return label + 'known but not present.'
+        if (definition.status === 'rendered') return label + 'rendered.'
+        if (definition.status === 'grouped') {
+            return label + 'used for BOM grouping.'
+        }
+        if (definition.status === 'summarized') {
+            return label + 'summarized in simulation setup.'
+        }
+        return label + 'preserved as metadata.'
+    }
+
+    /**
+     * Extracts variant values present in the current document.
+     * @param {object[]} elements Parsed element rows.
+     * @returns {Map<string, Set<string>>}
+     */
+    static #presentVariants(elements) {
+        const present = new Map()
+        const add = (setName, value) => {
+            const text = String(value || '').trim()
+            if (!text) return
+            if (!present.has(setName)) present.set(setName, new Set())
+            present.get(setName).add(text)
+        }
+
+        for (const element of elements) {
+            if (element?.type === 'source_component') {
+                add('sourceComponentFtypes', element.ftype)
+            }
+            if (element?.type === 'pcb_board') {
+                add('pcbBoardShapes', element.shape || 'rect')
+            }
+            if (element?.type === 'pcb_smtpad') {
+                add('pcbSmtPadShapes', element.shape)
+            }
+            if (element?.type === 'pcb_hole') {
+                add('pcbHoleShapes', element.hole_shape || element.shape)
+            }
+            if (element?.type === 'pcb_plated_hole') {
+                add('pcbPlatedHoleShapes', element.shape || 'circle')
+                add('pcbPlatedHoleHoleShapes', element.hole_shape)
+            }
+            if (element?.type === 'pcb_solder_paste') {
+                add('pcbSolderPasteShapes', element.shape)
+            }
+            if (element?.type === 'pcb_cutout') {
+                add('pcbCutoutShapes', element.shape || 'rect')
+            }
+            if (element?.type === 'pcb_copper_pour') {
+                add('pcbCopperPourShapes', element.shape || 'polygon')
+            }
+            if (
+                element?.type === 'simulation_voltage_source' ||
+                element?.type === 'simulation_current_source'
+            ) {
+                add(
+                    'simulationSourceKinds',
+                    element.source_type || element.sourceType || element.kind
+                )
+                add('simulationWaveShapes', element.wave_shape)
+            }
+            if (element?.type === 'simulation_experiment') {
+                add(
+                    'simulationExperimentMethods',
+                    element.spice_options?.method
+                )
+            }
+        }
+
+        return present
+    }
+
     /**
      * Builds aggregate matrix counts.
      * @param {object[]} rows Matrix rows.
      * @param {Set<string>} presentTypes Present element types.
+     * @param {object[]} variantRows Variant coverage rows.
      * @returns {object}
      */
-    static #totals(rows, presentTypes) {
+    static #totals(rows, presentTypes, variantRows) {
         return {
             knownElementTypes: rows.length,
             presentElementTypes: rows.filter((row) => row.present).length,
@@ -236,7 +454,8 @@ export class CircuitJsonSupportMatrixBuilder {
                 (row) =>
                     row.present &&
                     (row.capabilities.pcb === 'rendered' ||
-                        row.capabilities.schematic === 'rendered')
+                        row.capabilities.schematic === 'rendered' ||
+                        row.capabilities.scene3d === 'external-model')
             ).length,
             diagnosticElementTypes: rows.filter(
                 (row) =>
@@ -244,7 +463,10 @@ export class CircuitJsonSupportMatrixBuilder {
             ).length,
             unknownPresentElementTypes: [...presentTypes].filter(
                 (type) => !rows.some((row) => row.type === type)
-            ).length
+            ).length,
+            knownVariantValues: variantRows.length,
+            presentVariantValues: variantRows.filter((row) => row.present)
+                .length
         }
     }