altium-toolkit 1.1.3 → 1.1.23

package/docs/schemas/altium_toolkit/unsupported_features_a1.schema.json

@@ -0,0 +1,212 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "altium-toolkit.unsupported-features.a1",
+    "title": "Altium Toolkit Unsupported Features A1",
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+        "schema",
+        "summary",
+        "recordTypes",
+        "rawRecords",
+        "opaqueRecords",
+        "diagnostics"
+    ],
+    "properties": {
+        "schema": {
+            "const": "altium-toolkit.unsupported-features.a1"
+        },
+        "summary": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": [
+                "modelCount",
+                "unsupportedRecordTypeCount",
+                "rawRecordCount",
+                "opaqueRecordCount",
+                "diagnosticCount",
+                "itemCount",
+                "status"
+            ],
+            "properties": {
+                "modelCount": {
+                    "type": "number"
+                },
+                "unsupportedRecordTypeCount": {
+                    "type": "number"
+                },
+                "rawRecordCount": {
+                    "type": "number"
+                },
+                "opaqueRecordCount": {
+                    "type": "number"
+                },
+                "diagnosticCount": {
+                    "type": "number"
+                },
+                "itemCount": {
+                    "type": "number"
+                },
+                "status": {
+                    "enum": ["supported", "unsupported"]
+                }
+            }
+        },
+        "recordTypes": {
+            "type": "array",
+            "items": {
+                "$ref": "#/$defs/recordType"
+            }
+        },
+        "rawRecords": {
+            "type": "array",
+            "items": {
+                "$ref": "#/$defs/rawRecord"
+            }
+        },
+        "opaqueRecords": {
+            "type": "array",
+            "items": {
+                "$ref": "#/$defs/opaqueRecord"
+            }
+        },
+        "diagnostics": {
+            "type": "array",
+            "items": {
+                "$ref": "#/$defs/diagnostic"
+            }
+        }
+    },
+    "$defs": {
+        "recordType": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["domain", "recordType", "name", "family", "count"],
+            "properties": {
+                "fileName": {
+                    "type": "string"
+                },
+                "domain": {
+                    "type": "string"
+                },
+                "recordType": {
+                    "type": "number"
+                },
+                "name": {
+                    "type": "string"
+                },
+                "family": {
+                    "type": "string"
+                },
+                "count": {
+                    "type": "number"
+                }
+            }
+        },
+        "rawRecord": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["domain"],
+            "properties": {
+                "fileName": {
+                    "type": "string"
+                },
+                "domain": {
+                    "type": "string"
+                },
+                "sourceStream": {
+                    "type": "string"
+                },
+                "sourceStorage": {
+                    "type": "string"
+                },
+                "recordIndex": {
+                    "type": "number"
+                },
+                "family": {
+                    "type": "string"
+                },
+                "type": {
+                    "type": "string"
+                },
+                "typeId": {
+                    "type": "number"
+                },
+                "byteLength": {
+                    "type": "number"
+                },
+                "supported": {
+                    "type": "boolean"
+                },
+                "parsed": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "opaqueRecord": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["domain"],
+            "properties": {
+                "fileName": {
+                    "type": "string"
+                },
+                "domain": {
+                    "type": "string"
+                },
+                "sourceStream": {
+                    "type": "string"
+                },
+                "sourceStorage": {
+                    "type": "string"
+                },
+                "frameType": {
+                    "type": "number"
+                },
+                "recordIndex": {
+                    "type": "number"
+                },
+                "byteLength": {
+                    "type": "number"
+                }
+            }
+        },
+        "diagnostic": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["code", "severity", "message"],
+            "properties": {
+                "fileName": {
+                    "type": "string"
+                },
+                "code": {
+                    "type": "string"
+                },
+                "severity": {
+                    "enum": ["info", "warning", "error"]
+                },
+                "message": {
+                    "type": "string"
+                },
+                "source": {
+                    "type": "string"
+                },
+                "sourceStream": {
+                    "type": "string"
+                },
+                "sourceStorage": {
+                    "type": "string"
+                },
+                "recordIndex": {
+                    "type": "number"
+                },
+                "recordType": {
+                    "type": "number"
+                },
+                "errorKind": {
+                    "type": "string"
+                }
+            }
+        }
+    }
+}

package/docs/testing.md

@@ -6,6 +6,11 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 # Testing
 
+Exporter tests use only synthetic component responses and generated OLE
+streams. Do not add native customer files or provider-derived raw fixtures.
+When exercising source lookup, inject a fake fetcher/client and assert emitted
+entries, progress events, checkpoints, diagnostics, and OLE round trips.
+
 Run the complete suite:
 
 ```bash
@@ -34,3 +39,5 @@ areas and must keep `assetPolicy` set to `repo-owned-synthetic-only`. Each
 fixture entry records `source: inline-synthetic-records` plus expected parser,
 SVG, schema, and diagnostic contracts so tests can catch drift between fake
 fixtures and public read-model coverage.
+`FixtureCoverageMatrixBuilder` can turn the manifest into a machine-readable
+required-coverage report without adding native fixture files.

package/examples/README.md

@@ -6,6 +6,27 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 # Examples
 
+## Read-only utility scripts
+
+The repository includes small Node.js examples for common non-interactive
+workflows. They read the requested input file, write deterministic output to
+stdout, and do not modify source documents:
+
+- `node examples/inspect-board.mjs <file> [--json]`
+- `node examples/inspect-schematic.mjs <file> [--json] [--view <view>]`
+- `node examples/extract-bom.mjs <file> [--json]`
+- `node examples/generate-pnp.mjs <file> [--json]`
+- `node examples/net-report.mjs <file> [--json]`
+- `node examples/library-catalog.mjs <file> [--json]`
+- `node examples/library-catalog.mjs <file> --html`
+- `node examples/validate-library.mjs <file> [--json]`
+- `node examples/corpus-smoke.mjs <directory> [--json] [--coverage]`
+
+Run any script with `--help` to see its output mode. The schematic inspection
+views are `summary`, `flat`, `hierarchy`, `parts`, `nets`, and `all`. Corpus
+coverage reports include aggregate record-type counters and field-gap counters
+for caller-owned local sample directories.
+
 ## Arduino Uno
 
 The `arduino-uno` example is a browser page for loading `.SchDoc` and

package/examples/cli-utils.mjs

@@ -0,0 +1,148 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { readFile } from 'node:fs/promises'
+import { basename } from 'node:path'
+
+import { AltiumParser } from '../src/index.mjs'
+
+/**
+ * Returns true when help was requested.
+ * @param {string[]} args CLI arguments.
+ * @returns {boolean}
+ */
+export function hasHelpFlag(args) {
+    return args.includes('--help') || args.includes('-h')
+}
+
+/**
+ * Prints a read-only script help message.
+ * @param {string} scriptName Script name.
+ * @param {string} summary Script summary.
+ * @param {string[]} lines Additional help lines.
+ * @returns {void}
+ */
+export function printHelp(scriptName, summary, lines = []) {
+    console.log(
+        [
+            'Usage: ' + scriptName + ' <file> [--json]',
+            '',
+            summary,
+            '',
+            'This is a read-only example. It reads the input file and writes report output to stdout.',
+            ...lines
+        ].join('\n')
+    )
+}
+
+/**
+ * Resolves the first non-option argument as an input path.
+ * @param {string[]} args CLI arguments.
+ * @returns {string}
+ */
+export function inputPathFromArgs(args) {
+    return args.find((arg) => !arg.startsWith('-')) || ''
+}
+
+/**
+ * Returns true when JSON output was requested.
+ * @param {string[]} args CLI arguments.
+ * @returns {boolean}
+ */
+export function wantsJson(args) {
+    return args.includes('--json')
+}
+
+/**
+ * Parses an Altium file from disk using the library parser.
+ * @param {string} filePath Input path.
+ * @returns {Promise<object>}
+ */
+export async function parseModelFromPath(filePath) {
+    const bytes = await readFile(filePath)
+    const arrayBuffer = bytes.buffer.slice(
+        bytes.byteOffset,
+        bytes.byteOffset + bytes.byteLength
+    )
+    return AltiumParser.parseArrayBuffer(basename(filePath), arrayBuffer)
+}
+
+/**
+ * Prints a JSON value with deterministic indentation.
+ * @param {unknown} value JSON-compatible value.
+ * @returns {void}
+ */
+export function printJson(value) {
+    console.log(JSON.stringify(value, null, 4))
+}
+
+/**
+ * Prints an error and marks the process as failed.
+ * @param {string} scriptName Script name.
+ * @returns {void}
+ */
+export function printMissingPath(scriptName) {
+    console.error('Usage: ' + scriptName + ' <file> [--json]')
+    console.error('Run `' + scriptName + ' --help` for details.')
+    process.exitCode = 1
+}
+
+/**
+ * Escapes one CSV field.
+ * @param {unknown} value Field value.
+ * @returns {string}
+ */
+export function csvField(value) {
+    const text = String(value ?? '')
+    return /[",\n\r]/u.test(text) ? '"' + text.replace(/"/gu, '""') + '"' : text
+}
+
+/**
+ * Prints CSV rows.
+ * @param {string[]} headers CSV headers.
+ * @param {object[]} rows Data rows.
+ * @returns {void}
+ */
+export function printCsv(headers, rows) {
+    console.log(headers.map(csvField).join(','))
+    for (const row of rows) {
+        console.log(headers.map((header) => csvField(row[header])).join(','))
+    }
+}
+
+/**
+ * Returns a compact parser identity for report output.
+ * @param {object} model Parsed model.
+ * @returns {object}
+ */
+export function modelIdentity(model) {
+    return {
+        fileName: model.fileName,
+        fileType: model.fileType,
+        kind: model.kind,
+        title: model.summary?.title || model.fileName
+    }
+}
+
+/**
+ * Runs a read-only CLI script.
+ * @param {{ scriptName: string, summary: string, helpLines?: string[], run: (model: object, args: string[]) => void | Promise<void> }} options Script options.
+ * @returns {Promise<void>}
+ */
+export async function runReadOnlyScript(options) {
+    const args = process.argv.slice(2)
+    if (hasHelpFlag(args)) {
+        printHelp(options.scriptName, options.summary, options.helpLines || [])
+        return
+    }
+
+    const filePath = inputPathFromArgs(args)
+    if (!filePath) {
+        printMissingPath(options.scriptName)
+        return
+    }
+
+    const model = await parseModelFromPath(filePath)
+    await options.run(model, args)
+}