circuitjson-toolkit 1.0.3 → 1.0.16

package/src/core/CircuitJsonManufacturingDownloadBuilder.mjs

@@ -0,0 +1,196 @@
+/**
+ * Builds downloadable manufacturing metadata artifacts from parsed documents.
+ */
+export class CircuitJsonManufacturingDownloadBuilder {
+    /**
+     * Returns true when a format is handled by this builder.
+     * @param {string} format Export format.
+     * @returns {boolean}
+     */
+    static supportsFormat(format) {
+        return [
+            'pick-place-csv',
+            'routing-dsn',
+            'fabrication-notes-json'
+        ].includes(String(format || ''))
+    }
+
+    /**
+     * Builds a manufacturing metadata download.
+     * @param {object} documentModel Parsed document model.
+     * @param {string} format Export format.
+     * @returns {{ fileName: string, bytes: Uint8Array, contentType: string }}
+     */
+    static build(documentModel, format) {
+        if (format === 'pick-place-csv') {
+            return CircuitJsonManufacturingDownloadBuilder.#pickPlaceCsv(
+                documentModel
+            )
+        }
+        if (format === 'routing-dsn') {
+            return CircuitJsonManufacturingDownloadBuilder.#routingDsn(
+                documentModel
+            )
+        }
+        if (format === 'fabrication-notes-json') {
+            return CircuitJsonManufacturingDownloadBuilder.#fabricationNotesJson(
+                documentModel
+            )
+        }
+        throw new Error('Unsupported manufacturing export format')
+    }
+
+    /**
+     * Builds a pick-and-place CSV download.
+     * @param {object} documentModel Parsed document model.
+     * @returns {{ fileName: string, bytes: Uint8Array, contentType: string }}
+     */
+    static #pickPlaceCsv(documentModel) {
+        const rows = Array.isArray(
+            documentModel?.manufacturing?.pickAndPlaceRows
+        )
+            ? documentModel.manufacturing.pickAndPlaceRows
+            : []
+        if (!rows.length) {
+            throw new Error('No placement metadata is available')
+        }
+
+        const headers = [
+            'Designator',
+            'Component ID',
+            'Source Component ID',
+            'X',
+            'Y',
+            'Rotation',
+            'Layer',
+            'Side',
+            'Value',
+            'Package',
+            'Manufacturer Part Number'
+        ]
+        const body = rows.map((row) => [
+            row.designator,
+            row.componentId,
+            row.sourceComponentId,
+            row.x,
+            row.y,
+            row.rotation,
+            row.layer,
+            row.side,
+            row.value,
+            row.package,
+            row.manufacturerPartNumber
+        ])
+        const csv = CircuitJsonManufacturingDownloadBuilder.#csv([
+            headers,
+            ...body
+        ])
+
+        return {
+            fileName:
+                CircuitJsonManufacturingDownloadBuilder.#fileBase(
+                    documentModel
+                ) + '-pick-place.csv',
+            bytes: new TextEncoder().encode(csv),
+            contentType: 'text/csv;charset=utf-8'
+        }
+    }
+
+    /**
+     * Builds a routing DSN download.
+     * @param {object} documentModel Parsed document model.
+     * @returns {{ fileName: string, bytes: Uint8Array, contentType: string }}
+     */
+    static #routingDsn(documentModel) {
+        const dsn = String(documentModel?.manufacturing?.routingDsn || '')
+        if (!dsn.trim()) {
+            throw new Error('No routing metadata is available')
+        }
+
+        return {
+            fileName:
+                CircuitJsonManufacturingDownloadBuilder.#fileBase(
+                    documentModel
+                ) + '-routing.dsn',
+            bytes: new TextEncoder().encode(dsn),
+            contentType: 'application/specctra-dsn'
+        }
+    }
+
+    /**
+     * Builds a fabrication notes JSON download.
+     * @param {object} documentModel Parsed document model.
+     * @returns {{ fileName: string, bytes: Uint8Array, contentType: string }}
+     */
+    static #fabricationNotesJson(documentModel) {
+        const notes = Array.isArray(
+            documentModel?.manufacturing?.fabricationNotes
+        )
+            ? documentModel.manufacturing.fabricationNotes
+            : []
+        if (!notes.length) {
+            throw new Error('No fabrication note metadata is available')
+        }
+
+        const payload = {
+            fileName: String(documentModel?.fileName || ''),
+            notes
+        }
+
+        return {
+            fileName:
+                CircuitJsonManufacturingDownloadBuilder.#fileBase(
+                    documentModel
+                ) + '-fabrication-notes.json',
+            bytes: new TextEncoder().encode(
+                JSON.stringify(payload, null, 2) + '\n'
+            ),
+            contentType: 'application/json;charset=utf-8'
+        }
+    }
+
+    /**
+     * Serializes CSV rows.
+     * @param {unknown[][]} rows CSV row values.
+     * @returns {string}
+     */
+    static #csv(rows) {
+        return (
+            rows
+                .map((row) =>
+                    row
+                        .map((value) =>
+                            CircuitJsonManufacturingDownloadBuilder.#csvCell(
+                                value
+                            )
+                        )
+                        .join(',')
+                )
+                .join('\n') + '\n'
+        )
+    }
+
+    /**
+     * Serializes one CSV cell.
+     * @param {unknown} value Cell value.
+     * @returns {string}
+     */
+    static #csvCell(value) {
+        const text = String(value ?? '')
+        if (!/[",\n\r]/u.test(text)) return text
+        return '"' + text.replaceAll('"', '""') + '"'
+    }
+
+    /**
+     * Builds a filesystem-safe base file name.
+     * @param {object} documentModel Parsed document model.
+     * @returns {string}
+     */
+    static #fileBase(documentModel) {
+        const raw = String(documentModel?.fileName || 'manufacturing')
+            .replace(/\.[^.]+$/u, '')
+            .trim()
+        const safe = raw.replace(/[^a-z0-9._-]+/giu, '-').replace(/^-|-$/gu, '')
+        return safe || 'manufacturing'
+    }
+}

package/src/core/CircuitJsonParser.mjs

@@ -1,4 +1,8 @@
 import { CircuitJsonDocument } from './CircuitJsonDocument.mjs'
+import { CircuitJsonBomBuilder } from './CircuitJsonBomBuilder.mjs'
+import { CircuitJsonIndexer } from './CircuitJsonIndexer.mjs'
+import { CircuitJsonManufacturingBuilder } from './CircuitJsonManufacturingBuilder.mjs'
+import { CircuitJsonSupportMatrixBuilder } from './CircuitJsonSupportMatrixBuilder.mjs'
 
 /**
  * Parses standalone CircuitJSON files.
@@ -22,10 +26,15 @@ export class CircuitJsonParser {
         }
 
         CircuitJsonDocument.assertModel(parsed)
+        const index = CircuitJsonIndexer.index(parsed)
         return CircuitJsonDocument.attachMetadata(parsed, {
             fileName: options.fileName || '',
             fileType: 'circuitjson',
-            kind: CircuitJsonParser.#resolveKind(parsed)
+            kind: CircuitJsonParser.#resolveKind(index),
+            diagnostics: index.diagnostics,
+            bom: CircuitJsonBomBuilder.build(parsed),
+            supportMatrix: CircuitJsonSupportMatrixBuilder.build(parsed),
+            manufacturing: CircuitJsonManufacturingBuilder.build(parsed, index)
         })
     }
 
@@ -44,12 +53,19 @@ export class CircuitJsonParser {
 
     /**
      * Resolves a broad document kind from available elements.
-     * @param {object[]} model CircuitJSON model.
+     * @param {{ elementsByType?: Map<string, object[]> }} index Model index.
      * @returns {string}
      */
-    static #resolveKind(model) {
-        return model.some((element) => String(element?.type) === 'pcb_board')
-            ? 'pcb'
-            : 'circuitjson'
+    static #resolveKind(index) {
+        if (index.elementsByType?.has('pcb_board')) return 'pcb'
+        if (
+            [...(index.elementsByType?.keys() || [])].some((type) =>
+                String(type).startsWith('schematic_')
+            )
+        ) {
+            return 'schematic'
+        }
+
+        return 'circuitjson'
     }
 }

package/src/core/CircuitJsonPcbClearanceDiagnostics.mjs

@@ -0,0 +1,329 @@
+import { CircuitJsonUnits } from './CircuitJsonUnits.mjs'
+import { CircuitJsonPcbCopperGeometry } from './CircuitJsonPcbCopperGeometry.mjs'
+
+/**
+ * Builds copper clearance diagnostics for CircuitJSON PCB primitives.
+ */
+export class CircuitJsonPcbClearanceDiagnostics {
+    /**
+     * Builds generic copper clearance diagnostics when board rules are present.
+     * @param {{ elementsByType: Map<string, object[]> }} index Element index.
+     * @param {object[]} primitives Primitive rows.
+     * @returns {object[]}
+     */
+    static build(index, primitives) {
+        const minimum = this.#minimumClearance(index)
+        if (minimum === null || minimum <= 0) return []
+
+        const copper = primitives.filter((primitive) =>
+            this.#isCopperPrimitive(primitive)
+        )
+        const keepouts = primitives.filter((primitive) =>
+            this.#isKeepoutPrimitive(primitive)
+        )
+        const diagnostics = []
+        for (let leftIndex = 0; leftIndex < copper.length; leftIndex += 1) {
+            for (
+                let rightIndex = leftIndex + 1;
+                rightIndex < copper.length;
+                rightIndex += 1
+            ) {
+                const left = copper[leftIndex]
+                const right = copper[rightIndex]
+                if (left.netName === right.netName) continue
+                if (!this.#sameClearanceLayer(left, right)) continue
+                const actual =
+                    CircuitJsonPcbCopperGeometry.clearance(left, right) ??
+                    this.#boundsClearance(left.bounds, right.bounds)
+                if (actual >= minimum) continue
+                diagnostics.push(
+                    this.#clearanceDiagnostic(
+                        left,
+                        right,
+                        minimum,
+                        actual,
+                        diagnostics.length
+                    )
+                )
+            }
+        }
+        for (const copperPrimitive of copper) {
+            for (const keepout of keepouts) {
+                if (!this.#keepoutAppliesToCopper(copperPrimitive, keepout)) {
+                    continue
+                }
+                const actual =
+                    CircuitJsonPcbCopperGeometry.clearance(
+                        copperPrimitive,
+                        keepout
+                    ) ??
+                    this.#boundsClearance(
+                        copperPrimitive.bounds,
+                        keepout.bounds
+                    )
+                if (actual >= minimum) continue
+                diagnostics.push(
+                    this.#keepoutDiagnostic(
+                        copperPrimitive,
+                        keepout,
+                        minimum,
+                        actual,
+                        diagnostics.length
+                    )
+                )
+            }
+        }
+        return diagnostics
+    }
+
+    /**
+     * Resolves the configured minimum copper clearance.
+     * @param {{ elementsByType: Map<string, object[]> }} index Element index.
+     * @returns {number | null}
+     */
+    static #minimumClearance(index) {
+        for (const board of index.elementsByType.get('pcb_board') || []) {
+            const value = CircuitJsonUnits.optionalLength(
+                board.min_trace_clearance ??
+                    board.minimum_trace_clearance ??
+                    board.minimum_copper_clearance ??
+                    board.minimumCopperClearance ??
+                    board.minCopperClearance
+            )
+            if (value !== null) return value
+        }
+        return null
+    }
+
+    /**
+     * Returns true when a primitive participates in copper spacing checks.
+     * @param {object} primitive Primitive row.
+     * @returns {boolean}
+     */
+    static #isCopperPrimitive(primitive) {
+        return (
+            ['pad', 'track', 'via', 'zone'].includes(primitive.kind) &&
+            String(primitive.netName || '').trim() &&
+            primitive.bounds
+        )
+    }
+
+    /**
+     * Returns true when a primitive represents a keepout region.
+     * @param {object} primitive Primitive row.
+     * @returns {boolean}
+     */
+    static #isKeepoutPrimitive(primitive) {
+        return primitive.kind === 'keepout' && Boolean(primitive.bounds)
+    }
+
+    /**
+     * Returns true when two copper primitives should share clearance checks.
+     * @param {object} left First primitive.
+     * @param {object} right Second primitive.
+     * @returns {boolean}
+     */
+    static #sameClearanceLayer(left, right) {
+        if (left.kind === 'via' || right.kind === 'via') return true
+        const leftLayer = String(left.layer || '').trim()
+        const rightLayer = String(right.layer || '').trim()
+        return !leftLayer || !rightLayer || leftLayer === rightLayer
+    }
+
+    /**
+     * Returns true when a keepout applies to the copper primitive layer.
+     * @param {object} copper Copper primitive.
+     * @param {object} keepout Keepout primitive.
+     * @returns {boolean}
+     */
+    static #keepoutAppliesToCopper(copper, keepout) {
+        if (copper.kind === 'via') return true
+        const keepoutSides = this.#keepoutSides(keepout)
+        if (!keepoutSides.length) return true
+        const copperSide = this.#surfaceSide(copper.layer || copper.side)
+        return !copperSide || keepoutSides.includes(copperSide)
+    }
+
+    /**
+     * Resolves the positive distance between two axis-aligned bounds.
+     * @param {object} left First bounds.
+     * @param {object} right Second bounds.
+     * @returns {number}
+     */
+    static #boundsClearance(left, right) {
+        const gapX = Math.max(left.minX - right.maxX, right.minX - left.maxX, 0)
+        const gapY = Math.max(left.minY - right.maxY, right.minY - left.maxY, 0)
+        return Math.hypot(gapX, gapY)
+    }
+
+    /**
+     * Builds one copper clearance diagnostic.
+     * @param {object} left First primitive.
+     * @param {object} right Second primitive.
+     * @param {number} minimum Minimum clearance.
+     * @param {number} actual Actual clearance.
+     * @param {number} index Diagnostic index.
+     * @returns {object}
+     */
+    static #clearanceDiagnostic(left, right, minimum, actual, index) {
+        const leftCenter = this.#boundsCenter(left.bounds)
+        const rightCenter = this.#boundsCenter(right.bounds)
+        const netName = [left.netName, right.netName].sort().join(' / ')
+
+        return {
+            id: 'clearance:' + index,
+            kind: 'error',
+            severity: 'error',
+            category: 'clearance',
+            code: 'pcb_copper_clearance',
+            message:
+                'Copper clearance is below the configured minimum for ' +
+                netName +
+                '.',
+            point: {
+                x: (leftCenter.x + rightCenter.x) / 2,
+                y: (leftCenter.y + rightCenter.y) / 2
+            },
+            bounds: this.#mergeBounds([left.bounds, right.bounds]),
+            relatedPrimitiveIds: [left.id, right.id].filter(Boolean).sort(),
+            componentKey: '',
+            netName,
+            clearance: {
+                minimum,
+                actual: Number(actual.toFixed(6))
+            }
+        }
+    }
+
+    /**
+     * Builds one keepout clearance diagnostic.
+     * @param {object} copper Copper primitive.
+     * @param {object} keepout Keepout primitive.
+     * @param {number} minimum Minimum clearance.
+     * @param {number} actual Actual clearance.
+     * @param {number} index Diagnostic index.
+     * @returns {object}
+     */
+    static #keepoutDiagnostic(copper, keepout, minimum, actual, index) {
+        const copperCenter = this.#boundsCenter(copper.bounds)
+        const keepoutCenter = this.#boundsCenter(keepout.bounds)
+        const keepoutId = String(keepout.id || '')
+
+        return {
+            id: 'keepout-clearance:' + index,
+            kind: 'error',
+            severity: 'error',
+            category: 'clearance',
+            code: 'pcb_keepout_clearance',
+            message:
+                'Copper clearance is below the configured minimum around keepout ' +
+                keepoutId +
+                '.',
+            point: {
+                x: (copperCenter.x + keepoutCenter.x) / 2,
+                y: (copperCenter.y + keepoutCenter.y) / 2
+            },
+            bounds: this.#mergeBounds([copper.bounds, keepout.bounds]),
+            relatedPrimitiveIds: [copper.id, keepout.id].filter(Boolean).sort(),
+            componentKey: String(copper.componentKey || ''),
+            netName: String(copper.netName || ''),
+            keepoutId,
+            clearance: {
+                minimum,
+                actual: Number(actual.toFixed(6))
+            }
+        }
+    }
+
+    /**
+     * Resolves the center point of bounds.
+     * @param {object} bounds Bounds record.
+     * @returns {{ x: number, y: number }}
+     */
+    static #boundsCenter(bounds) {
+        return {
+            x: bounds.minX + bounds.width / 2,
+            y: bounds.minY + bounds.height / 2
+        }
+    }
+
+    /**
+     * Merges bounds rows.
+     * @param {object[]} rows Bounds rows.
+     * @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))
+        return {
+            minX: this.#round(minX),
+            minY: this.#round(minY),
+            maxX: this.#round(maxX),
+            maxY: this.#round(maxY),
+            width: this.#round(maxX - minX),
+            height: this.#round(maxY - minY)
+        }
+    }
+
+    /**
+     * Resolves keepout surface sides from source layer fields.
+     * @param {object} keepout Keepout primitive.
+     * @returns {string[]}
+     */
+    static #keepoutSides(keepout) {
+        const source = keepout.source || {}
+        const layers = [
+            ...(Array.isArray(source.layers) ? source.layers : []),
+            source.layer,
+            source.side
+        ]
+        return [
+            ...new Set(
+                layers.map((layer) => this.#surfaceSide(layer)).filter(Boolean)
+            )
+        ]
+    }
+
+    /**
+     * Resolves top or bottom from common layer values.
+     * @param {unknown} layer Layer value.
+     * @returns {'top' | 'bottom' | ''}
+     */
+    static #surfaceSide(layer) {
+        const value =
+            typeof layer === 'object' && layer !== null ? layer.name : layer
+        const normalized = String(value || '')
+            .trim()
+            .toLowerCase()
+        if (
+            normalized === 'top' ||
+            normalized === 'front' ||
+            normalized === 'f.cu' ||
+            normalized === '1'
+        ) {
+            return 'top'
+        }
+        if (
+            normalized === 'bottom' ||
+            normalized === 'back' ||
+            normalized === 'b.cu' ||
+            normalized === '32'
+        ) {
+            return 'bottom'
+        }
+        return ''
+    }
+
+    /**
+     * Rounds one computed geometry value.
+     * @param {number} value Numeric value.
+     * @returns {number}
+     */
+    static #round(value) {
+        return Number(Number(value).toFixed(6))
+    }
+}