@schemd/core 0.3.1 → 0.3.2

package/dist/parser.d.ts

@@ -12,7 +12,7 @@ import { type SchematicColor, type SchematicDocument, type SchematicFence } from
 /**
  * Assert that a document originated from {@link parseSchematic} in this module.
  *
- * @param document - Candidate AST supplied to the renderer.
+ * @param document - Candidate AST supplied to a parsed-document consumer.
  * @throws {TypeError} When the object was forged, cloned, or parsed by another
  *   loaded copy of the package rather than this module instance.
  * @internal

package/dist/parser.js

@@ -1,15 +1,16 @@
 import { ADDER_TYPES, AMPLIFIER_TYPES, ANALOG_KINDS, BUFFER_TYPES, BUS_TYPES, CLASSICAL_GATE_KINDS, COMPONENT_KINDS, DIGITAL_COMPONENT_KINDS, DIODE_TYPES, ELECTRICAL_COMPONENT_KINDS, FLIPFLOP_TYPES, GROUND_STYLES, LOAD_TYPES, LOGIC_STATES, METER_TYPES, MUX_TYPES, NAMED_QUANTUM_GATE_KINDS, PASSIVE_KINDS, POWER_TYPES, PROTECTION_TYPES, QUANTUM_GATE_KINDS, QUANTUM_SPECIAL_KINDS, RESONATOR_TYPES, SCHEMATIC_ORIENTATIONS, SCHEMATIC_SIGNAL_KINDS, SEMANTIC_COLORS, SCHEMATIC_SIGNAL_MARKERS, SOURCE_TYPES, SWITCH_TYPES, TRANSISTOR_TYPES, UML_COMPONENT_KINDS, UML_RELATION_KINDS, SchematicSyntaxError } from './types.js';
-import { validateDocumentGeometry } from './layout.js';
+import { isClassicalGate, isDigitalComponent, isQuantumSpecial, validateDocumentGeometry } from './layout.js';
 import { mathLabelTextWidth } from './math-label.js';
 import { cacheParsedSchematicRoutes } from './route-cache.js';
 import { MAX_SCHEMATIC_COMPONENTS, MAX_SCHEMATIC_CONNECTIONS, MAX_SCHEMATIC_SOURCE_CHARACTERS } from './limits.js';
 const COMPONENT_PATTERN = /^([A-Za-z][A-Za-z0-9_-]*):([A-Za-z][A-Za-z0-9_-]*)\s+"([^"]+)"\s+at\s+\((-?\d+(?:\.\d+)?),\s*(-?\d+(?:\.\d+)?)\)\s+(.+)$/;
 const CONNECTION_PATTERN = /^([A-Za-z][A-Za-z0-9_-]*)\.([A-Za-z][A-Za-z0-9_+-]*)\s*->\s*([A-Za-z][A-Za-z0-9_-]*)\.([A-Za-z][A-Za-z0-9_+-]*)\s+(.+)$/;
-const SCHEMD_FENCE_PATTERN = /^schemd\s+bounds="(\d+)x(\d+)"(?:\s+title="([^"]+)")?\s*$/i;
+const SCHEMD_FENCE_PATTERN = /^(?:schemd|schematic)\s+bounds="(\d+)x(\d+)"(?:\s+title="([^"]+)")?\s*$/i;
 const NUMBER_PATTERN = /^[+-]?(?:\d+\.?\d*|\.\d+)$/;
 const ANGLE_PATTERN = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:deg|grad|rad|turn)?$/i;
 const ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,63}$/i;
 const PIN_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+const NET_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 const RESERVED_IC_PIN_NAMES = new Set(['in', 'out']);
 const MAX_IC_PINS_PER_SIDE = 64;
 const IC_MINIMUM_WIDTH = 88;
@@ -58,7 +59,7 @@ function freezeParsedDocument(document) {
 }
 export function assertParsedSchematicDocument(document) {
     if (!parsedDocuments.has(document)) {
-        throw new TypeError('renderSchematic requires an immutable document returned by parseSchematic.');
+        throw new TypeError('This operation requires an immutable document returned by parseSchematic.');
     }
 }
 function includesValue(values, value) {
@@ -750,9 +751,10 @@ function parseConnectionOptions(raw, line) {
     let label;
     let dashed = false;
     let signalKind;
+    let net;
     let width;
     if (raw === undefined || raw.trim() === '') {
-        return { curve, markerStart, markerEnd, relation, label, dashed, signalKind, width };
+        return { curve, markerStart, markerEnd, relation, label, dashed, signalKind, net, width };
     }
     const seen = new Set();
     for (const token of connectionOptionTokens(raw.trim(), line)) {
@@ -796,9 +798,9 @@ function parseConnectionOptions(raw, line) {
             seen.add('marker-end');
             continue;
         }
-        const match = token.match(/^(marker-start|marker-end|relation|label|signal|width)=(.*)$/);
+        const match = token.match(/^(marker-start|marker-end|relation|label|signal|net|width)=(.*)$/);
         if (!match) {
-            throw new SchematicSyntaxError('Unsupported connection routing, marker, relation, label, or stroke option.', line);
+            throw new SchematicSyntaxError('Unsupported connection routing, topology, marker, relation, label, or stroke option.', line);
         }
         const option = match[1];
         if (seen.has(option)) {
@@ -829,6 +831,12 @@ function parseConnectionOptions(raw, line) {
             }
             signalKind = optionValue;
         }
+        else if (option === 'net') {
+            if (!NET_NAME_PATTERN.test(optionValue)) {
+                throw new SchematicSyntaxError('net must begin with a letter and contain at most 64 letters, digits, underscores, or hyphens.', line);
+            }
+            net = optionValue;
+        }
         else if (option === 'width') {
             width = parseWidth(optionValue, 1, line);
         }
@@ -870,7 +878,7 @@ function parseConnectionOptions(raw, line) {
     if (label === undefined && (relation === 'include' || relation === 'extend')) {
         label = `«${relation}»`;
     }
-    return { curve, markerStart, markerEnd, relation, label, dashed, signalKind, width };
+    return { curve, markerStart, markerEnd, relation, label, dashed, signalKind, net, width };
 }
 function parseConnection(match, line) {
     const tail = splitDeclarationTail(match[5], line);
@@ -890,6 +898,8 @@ function parseConnection(match, line) {
         connection.label = options.label;
     if (options.signalKind !== undefined)
         connection.signalKind = options.signalKind;
+    if (options.net !== undefined)
+        connection.net = options.net;
     if (options.width !== undefined)
         connection.width = options.width;
     return connection;
@@ -913,15 +923,6 @@ function validGatePort(component, port) {
         ? index <= component.inputs && index >= 1
         : index <= component.outputs && index >= 1;
 }
-function isClassicalGate(component) {
-    return CLASSICAL_GATE_KINDS.includes(component.kind);
-}
-function isDigitalComponent(component) {
-    return DIGITAL_COMPONENT_KINDS.includes(component.kind);
-}
-function isQuantumSpecial(component) {
-    return QUANTUM_SPECIAL_KINDS.includes(component.kind);
-}
 function validIndexedPort(port, inputs, outputs) {
     if (port === 'in')
         return inputs > 0;
@@ -1119,8 +1120,119 @@ function validateConnectionWidth(connection, components) {
         throw new SchematicSyntaxError(`Connection width ${width} is incompatible with ${sourceWidth}-bit source and ${targetWidth}-bit target ports.`, connection.line);
     }
 }
+function assignConnectionNetIds(connections) {
+    const parent = connections.map((_, index) => index);
+    const find = (index) => {
+        let root = index;
+        while (parent[root] !== root)
+            root = parent[root];
+        while (parent[index] !== index) {
+            const next = parent[index];
+            parent[index] = root;
+            index = next;
+        }
+        return root;
+    };
+    const union = (left, right) => {
+        const leftRoot = find(left);
+        const rightRoot = find(right);
+        if (leftRoot !== rightRoot)
+            parent[rightRoot] = leftRoot;
+    };
+    const terminalOwner = new Map();
+    const namedOwner = new Map();
+    for (const [index, connection] of connections.entries()) {
+        if (connection.relation !== 'signal') {
+            if (connection.net !== undefined) {
+                throw new SchematicSyntaxError('Only signal connections may declare a net.', connection.line);
+            }
+            continue;
+        }
+        for (const endpoint of [connection.from, connection.to]) {
+            const key = `${endpoint.componentId}.${endpoint.port}`;
+            const owner = terminalOwner.get(key);
+            if (owner === undefined)
+                terminalOwner.set(key, index);
+            else
+                union(index, owner);
+        }
+        if (connection.net !== undefined) {
+            const owner = namedOwner.get(connection.net);
+            if (owner === undefined)
+                namedOwner.set(connection.net, index);
+            else
+                union(index, owner);
+        }
+    }
+    const names = new Map();
+    const contracts = new Map();
+    for (const [index, connection] of connections.entries()) {
+        if (connection.relation !== 'signal')
+            continue;
+        const root = find(index);
+        if (connection.net !== undefined) {
+            const existing = names.get(root);
+            if (existing !== undefined && existing !== connection.net) {
+                throw new SchematicSyntaxError(`Terminal joins conflicting nets ${existing} and ${connection.net}.`, connection.line);
+            }
+            names.set(root, connection.net);
+        }
+        const signalKind = connection.signalKind ?? 'electrical';
+        const width = connection.width ?? 1;
+        const contract = contracts.get(root);
+        if (contract !== undefined &&
+            (contract.signalKind !== signalKind || contract.width !== width)) {
+            throw new SchematicSyntaxError(`Net segments must share one signal kind and width; expected ${contract.signalKind} width ${contract.width}.`, connection.line);
+        }
+        contracts.set(root, { signalKind, width });
+    }
+    const resolved = new Map();
+    let generated = 0;
+    for (const [index, connection] of connections.entries()) {
+        if (connection.relation !== 'signal')
+            continue;
+        const root = find(index);
+        let netId = resolved.get(root);
+        if (netId === undefined) {
+            netId = names.get(root) ?? `$${++generated}`;
+            resolved.set(root, netId);
+        }
+        connection.netId = netId;
+    }
+}
+function normalizeParserFence(value) {
+    if (typeof value !== 'object' || value === null) {
+        throw new SchematicSyntaxError('Parser options must be an object.');
+    }
+    const candidate = value;
+    const rawBounds = candidate.bounds;
+    if (typeof rawBounds !== 'object' || rawBounds === null) {
+        throw new SchematicSyntaxError('Parser options require bounds.');
+    }
+    const bounds = rawBounds;
+    const width = bounds.width;
+    const height = bounds.height;
+    const title = candidate.title;
+    if (typeof width !== 'number' ||
+        !Number.isInteger(width) ||
+        typeof height !== 'number' ||
+        !Number.isInteger(height) ||
+        width < 64 ||
+        height < 64 ||
+        width > 4096 ||
+        height > 4096) {
+        throw new SchematicSyntaxError('Schematic bounds must be integers from 64 through 4096.');
+    }
+    if (typeof title !== 'string' || title.trim() === '') {
+        throw new SchematicSyntaxError('Schematic titles cannot be empty.');
+    }
+    if (title.length > MAX_FENCE_TITLE_LENGTH) {
+        throw new SchematicSyntaxError('Schematic titles cannot exceed 512 characters.');
+    }
+    return { bounds: { width, height }, title };
+}
 export function parseSchematicFence(info, defaultTitle = 'Engineering schematic') {
-    if (info === undefined || !/^schemd(?:\s|$)/i.test(info.trim())) {
+    if (info === undefined || !/^(?:schemd|schematic)(?:\s|$)/i.test(info.trim())) {
         return undefined;
     }
     const match = info.trim().match(SCHEMD_FENCE_PATTERN);
@@ -1142,9 +1254,13 @@ export function parseSchematicFence(info, defaultTitle = 'Engineering schematic'
     return { bounds: { width, height }, title };
 }
 export function parseSchematic(source, fence) {
+    if (typeof source !== 'string') {
+        throw new SchematicSyntaxError('Schematic source must be a string.');
+    }
     if (source.length > MAX_SCHEMATIC_SOURCE_CHARACTERS) {
         throw new SchematicSyntaxError('Schematic source exceeds the 131,072 character limit.');
     }
+    const normalizedFence = normalizeParserFence(fence);
     const components = [];
     const connections = [];
     const componentIds = new Set();
@@ -1162,7 +1278,7 @@ export function parseSchematic(source, fence) {
             if (componentIds.has(component.id)) {
                 throw new SchematicSyntaxError(`Duplicate component ID ${component.id}.`, lineNumber);
             }
-            validateComponent(component, fence);
+            validateComponent(component, normalizedFence);
             componentIds.add(component.id);
             components.push(component);
             continue;
@@ -1186,9 +1302,10 @@ export function parseSchematic(source, fence) {
         validateEndpoint(connection.to, componentsById, connection.line);
         validateConnectionWidth(connection, componentsById);
     }
+    assignConnectionNetIds(connections);
     const document = { components, connections };
-    const routes = validateDocumentGeometry(document, fence);
+    const routes = validateDocumentGeometry(document, normalizedFence);
     const parsedDocument = freezeParsedDocument(document);
-    cacheParsedSchematicRoutes(parsedDocument, fence.bounds, routes);
+    cacheParsedSchematicRoutes(parsedDocument, normalizedFence.bounds, routes);
     return parsedDocument;
 }