@vessel-dsp/core 0.5.0

package/src/model/netlist.ts

@@ -0,0 +1,375 @@
+import { getPinNode, resolveConnectivity, type Connectivity, type NodeId } from './connectivity';
+import { parseQuantity } from './quantity';
+import { propertyQuantityValue, propertyStringValue } from './properties';
+import type { CircuitDocument, Component, ComponentKind, ParsedQuantity } from './types';
+
+export type SpiceLetter = 'R' | 'C' | 'L' | 'D' | 'Q' | 'J' | 'M' | 'V' | 'I';
+
+export type NetlistComponent = Readonly<{
+    id: string;
+    kind: ComponentKind;
+    spiceLetter: SpiceLetter | null;
+    value: ParsedQuantity | null;
+    nodes: readonly NodeId[];
+    model: string | null;
+    extras: Readonly<Record<string, string>>;
+}>;
+
+export type NetlistView = Readonly<{
+    components: readonly NetlistComponent[];
+    nodeCount: number;
+    groundNodeId: NodeId | null;
+    directives: readonly string[];
+    warnings: readonly string[];
+}>;
+
+const SPICE_LETTER: Partial<Record<ComponentKind, SpiceLetter>> = {
+    resistor: 'R',
+    'variable-resistor': 'R',
+    capacitor: 'C',
+    inductor: 'L',
+    diode: 'D',
+    led: 'D',
+    bjt: 'Q',
+    jfet: 'J',
+    mosfet: 'M',
+    'voltage-source': 'V',
+    'current-source': 'I',
+    battery: 'V',
+    rail: 'V',
+};
+
+const NODE_ORDER: Partial<Record<ComponentKind, readonly string[]>> = {
+    resistor: ['a', 'b'],
+    'variable-resistor': ['a', 'b'],
+    capacitor: ['a', 'b'],
+    inductor: ['a', 'b'],
+    diode: ['anode', 'cathode'],
+    led: ['anode', 'cathode'],
+    'tube-diode': ['anode', 'cathode'],
+    bjt: ['collector', 'base', 'emitter'],
+    jfet: ['drain', 'gate', 'source'],
+    mosfet: ['drain', 'gate', 'source', 'body'],
+    'voltage-source': ['+', '-'],
+    'current-source': ['+', '-'],
+    battery: ['+', '-'],
+    // Rails have a single terminal "t" that's hot; the other side is implicit ground.
+    // toNetlistView appends groundNodeId after node resolution to produce a SPICE-shaped 2-node row.
+    rail: ['t'],
+    opamp: ['vin+', 'vin-', 'vout', 'vcc', 'vee'],
+    triode: ['plate', 'grid', 'cathode'],
+    pentode: ['plate', 'screen', 'grid', 'cathode', 'suppressor'],
+};
+
+const VALUE_PROPERTY: Partial<Record<ComponentKind, string>> = {
+    resistor: 'R',
+    'variable-resistor': 'R',
+    capacitor: 'C',
+    inductor: 'L',
+    'voltage-source': 'V',
+    'current-source': 'I',
+    battery: 'V',
+    rail: 'V',
+};
+
+// Source-format aliases for the value property (e.g. LiveSPICE stores R as "Resistance").
+// Keep in sync with the alias lists in src/model/validation.ts until both fold into the catalog.
+const VALUE_PROPERTY_ALIASES: Partial<Record<ComponentKind, readonly string[]>> = {
+    resistor: ['Resistance', 'resistance'],
+    'variable-resistor': ['Resistance', 'resistance'],
+    capacitor: ['Capacitance', 'capacitance'],
+    inductor: ['Inductance', 'inductance'],
+    'voltage-source': ['Voltage', 'voltage'],
+    'current-source': ['Current', 'current'],
+    battery: ['Voltage', 'voltage'],
+    rail: ['Voltage', 'voltage'],
+};
+
+const REQUIRES_VALUE: ReadonlySet<ComponentKind> = new Set<ComponentKind>([
+    'resistor',
+    'capacitor',
+    'inductor',
+    'voltage-source',
+    'current-source',
+    'battery',
+    'rail',
+]);
+
+const HAS_MODEL: ReadonlySet<ComponentKind> = new Set<ComponentKind>([
+    'diode',
+    'led',
+    'bjt',
+    'jfet',
+    'mosfet',
+    'opamp',
+    'triode',
+    'pentode',
+    'tube-diode',
+]);
+
+const SKIP_KINDS: ReadonlySet<ComponentKind> = new Set<ComponentKind>([
+    'ground',
+    'label',
+    'named-wire',
+    'port',
+    'jack',
+]);
+
+const MODEL_PROPERTY_NAMES: readonly string[] = [
+    'model',
+    'Model',
+    'modelName',
+    'ModelName',
+    'partNumber',
+    'PartNumber',
+    'Type',
+];
+
+export function getSpiceLetter(kind: ComponentKind): SpiceLetter | null {
+    return SPICE_LETTER[kind] ?? null;
+}
+
+export function getSpiceNodeOrder(kind: ComponentKind): readonly string[] | null {
+    return NODE_ORDER[kind] ?? null;
+}
+
+export function kindForSpiceLetter(letter: SpiceLetter): ComponentKind {
+    switch (letter) {
+        case 'R': return 'resistor';
+        case 'C': return 'capacitor';
+        case 'L': return 'inductor';
+        case 'D': return 'diode';
+        case 'Q': return 'bjt';
+        case 'J': return 'jfet';
+        case 'M': return 'mosfet';
+        case 'V': return 'voltage-source';
+        case 'I': return 'current-source';
+    }
+}
+
+export function toNetlistView(doc: CircuitDocument, precomputed?: Connectivity): NetlistView {
+    const connectivity = precomputed ?? resolveConnectivity(doc);
+    const components: NetlistComponent[] = [];
+    const warnings: string[] = [];
+
+    for (const component of doc.components) {
+        if (SKIP_KINDS.has(component.kind)) {
+            continue;
+        }
+
+        if (component.kind === 'unsupported') {
+            warnings.push(
+                `${component.id}: unsupported source type ${component.sourceTypeName ?? 'unknown'} — skipped from netlist`,
+            );
+            continue;
+        }
+
+        // Components that need a SPICE subcircuit (opamps, pots, tubes, etc.) are signaled
+        // structurally via `spiceLetter: null` — no per-component warning needed.
+
+        const spiceLetter = SPICE_LETTER[component.kind] ?? null;
+        const expectedOrder = spiceLetter === null && component.terminals.length === 0
+            ? null
+            : NODE_ORDER[component.kind] ?? null;
+        const ordered = orderedNodes(component, connectivity, expectedOrder);
+        warnings.push(...ordered.warnings);
+
+        let nodes = ordered.nodes;
+        if (component.kind === 'rail') {
+            // Append implicit ground as the negative terminal so the SPICE row is well-shaped.
+            if (connectivity.groundNodeId === null) {
+                warnings.push(`${component.id} (rail): no ground node in document — cannot anchor implicit return`);
+            } else {
+                nodes = [...nodes, connectivity.groundNodeId];
+            }
+        }
+
+        const valueResult = extractValue(component);
+        const value = valueResult.value;
+        if (value === null && REQUIRES_VALUE.has(component.kind) && !valueResult.present) {
+            warnings.push(`${component.id} (${component.kind}): missing required value property`);
+        }
+
+        const model = extractModel(component);
+        const consumed = consumedPropertyKeys(component.kind);
+        const extras = extractExtras(component, consumed);
+
+        components.push({
+            id: component.id,
+            kind: component.kind,
+            spiceLetter,
+            value,
+            nodes,
+            model,
+            extras,
+        });
+    }
+
+    return {
+        components,
+        nodeCount: connectivity.nodeCount,
+        groundNodeId: connectivity.groundNodeId,
+        directives: doc.directives,
+        warnings,
+    };
+}
+
+function orderedNodes(
+    component: Component,
+    connectivity: Connectivity,
+    expected: readonly string[] | null,
+): { nodes: readonly NodeId[]; warnings: readonly string[] } {
+    const warnings: string[] = [];
+
+    if (expected === null) {
+        const nodes = collectDeclarationOrder(component, connectivity, warnings);
+        return { nodes, warnings };
+    }
+
+    const byName = new Map(component.terminals.map((t) => [t.name, t]));
+    const missing: string[] = [];
+    const ordered: NodeId[] = [];
+
+    for (const name of expected) {
+        const terminal = byName.get(name);
+        if (terminal === undefined) {
+            missing.push(name);
+            continue;
+        }
+        const node = getPinNode(connectivity, { componentId: component.id, terminalName: name });
+        if (node === undefined) {
+            warnings.push(`${component.id}: terminal "${name}" has no resolved node`);
+        } else {
+            ordered.push(node);
+        }
+    }
+
+    if (missing.length > 0) {
+        warnings.push(
+            `${component.id} (${component.kind}): expected terminals [${expected.join(', ')}], missing [${missing.join(', ')}] — falling back to declaration order`,
+        );
+        const fallback = collectDeclarationOrder(component, connectivity, warnings);
+        return { nodes: fallback, warnings };
+    }
+
+    return { nodes: ordered, warnings };
+}
+
+function collectDeclarationOrder(
+    component: Component,
+    connectivity: Connectivity,
+    warnings: string[],
+): readonly NodeId[] {
+    const nodes: NodeId[] = [];
+    for (const terminal of component.terminals) {
+        const node = getPinNode(connectivity, { componentId: component.id, terminalName: terminal.name });
+        if (node === undefined) {
+            warnings.push(`${component.id}: terminal "${terminal.name}" has no resolved node`);
+        } else {
+            nodes.push(node);
+        }
+    }
+    return nodes;
+}
+
+function extractValue(component: Component): { value: ParsedQuantity | null; present: boolean } {
+    const baseName = VALUE_PROPERTY[component.kind];
+    if (baseName === undefined) {
+        return { value: null, present: false };
+    }
+
+    const aliases = VALUE_PROPERTY_ALIASES[component.kind] ?? [];
+    const variants = uniqueVariants([
+        baseName,
+        baseName.toLowerCase(),
+        baseName.toUpperCase(),
+        capitalize(baseName),
+        ...aliases,
+        'value',
+        'Value',
+    ]);
+
+    for (const name of variants) {
+        const raw = component.properties[name];
+        if (raw === undefined) {
+            continue;
+        }
+        if (typeof raw === 'string') {
+            return { value: parseQuantity(raw), present: raw.trim().length > 0 };
+        }
+        return { value: propertyQuantityValue(raw), present: true };
+    }
+    return { value: null, present: false };
+}
+
+function extractModel(component: Component): string | null {
+    if (!HAS_MODEL.has(component.kind)) {
+        return null;
+    }
+    for (const name of MODEL_PROPERTY_NAMES) {
+        const raw = component.properties[name];
+        if (typeof raw === 'string' && raw.length > 0) {
+            return raw;
+        }
+    }
+    return null;
+}
+
+function consumedPropertyKeys(kind: ComponentKind): ReadonlySet<string> {
+    const consumed = new Set<string>();
+    const baseName = VALUE_PROPERTY[kind];
+    if (baseName !== undefined) {
+        consumed.add(baseName);
+        consumed.add(baseName.toLowerCase());
+        consumed.add(baseName.toUpperCase());
+        consumed.add(capitalize(baseName));
+        for (const alias of VALUE_PROPERTY_ALIASES[kind] ?? []) {
+            consumed.add(alias);
+        }
+        consumed.add('value');
+        consumed.add('Value');
+    }
+    if (HAS_MODEL.has(kind)) {
+        for (const name of MODEL_PROPERTY_NAMES) {
+            consumed.add(name);
+        }
+    }
+    return consumed;
+}
+
+function extractExtras(
+    component: Component,
+    consumed: ReadonlySet<string>,
+): Readonly<Record<string, string>> {
+    const extras: Record<string, string> = {};
+    for (const [key, value] of Object.entries(component.properties)) {
+        if (consumed.has(key)) {
+            continue;
+        }
+        const text = propertyStringValue(value);
+        if (text !== null) {
+            extras[key] = text;
+        }
+    }
+    return extras;
+}
+
+function uniqueVariants(input: readonly string[]): readonly string[] {
+    const seen = new Set<string>();
+    const out: string[] = [];
+    for (const name of input) {
+        if (seen.has(name)) {
+            continue;
+        }
+        seen.add(name);
+        out.push(name);
+    }
+    return out;
+}
+
+function capitalize(s: string): string {
+    if (s.length === 0) {
+        return s;
+    }
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/src/model/properties.ts

@@ -0,0 +1,101 @@
+import { parseQuantity } from './quantity';
+import type { ParsedQuantity, PropertyObject, PropertyValue } from './types';
+
+export function isParsedQuantity(value: unknown): value is ParsedQuantity {
+    if (!isUnknownRecord(value)) {
+        return false;
+    }
+    return typeof value['raw'] === 'string' &&
+        typeof value['value'] === 'number' &&
+        typeof value['unit'] === 'string';
+}
+
+export function isPropertyObject(value: PropertyValue | undefined): value is PropertyObject {
+    return isUnknownRecord(value) && !Array.isArray(value) && !isParsedQuantity(value);
+}
+
+export function propertyStringValue(value: PropertyValue | undefined): string | null {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    if (isParsedQuantity(value)) {
+        return value.raw;
+    }
+    return null;
+}
+
+export function propertyQuantityValue(value: PropertyValue | undefined): ParsedQuantity | null {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (isParsedQuantity(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        return parseQuantity(value);
+    }
+    if (typeof value === 'number') {
+        return {
+            raw: String(value),
+            value,
+            unit: '',
+        };
+    }
+    return null;
+}
+
+export function propertyNumericValue(value: PropertyValue | undefined): number | undefined {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (isParsedQuantity(value)) {
+        return Number.isFinite(value.value) ? value.value : undefined;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!/^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(trimmed)) {
+            return undefined;
+        }
+        const parsed = Number.parseFloat(trimmed);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+
+export function propertyBooleanValue(value: PropertyValue | undefined): boolean | undefined {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    const text = propertyStringValue(value)?.trim().toLowerCase();
+    if (text === 'true' || text === '1' || text === 'yes') {
+        return true;
+    }
+    if (text === 'false' || text === '0' || text === 'no') {
+        return false;
+    }
+    return undefined;
+}
+
+export function propertyValueForSourceAttribute(value: PropertyValue): string | null {
+    const scalar = propertyStringValue(value);
+    if (scalar !== null) {
+        return scalar;
+    }
+    return null;
+}
+
+function isUnknownRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/model/quantity.ts

@@ -0,0 +1,173 @@
+import type { ParsedQuantity } from './types';
+
+const SI_PREFIXES: Readonly<Record<string, number>> = {
+    f: 1e-15,
+    p: 1e-12,
+    n: 1e-9,
+    u: 1e-6,
+    'µ': 1e-6, // MICRO SIGN
+    'μ': 1e-6, // GREEK SMALL LETTER MU — LiveSPICE writes "μF" with this codepoint
+    m: 1e-3,
+    k: 1e3,
+    K: 1e3,
+    M: 1e6,
+    G: 1e9,
+    T: 1e12,
+};
+
+const SHORTHAND_MARKERS: Readonly<Record<string, { readonly multiplier: number; readonly impliedUnit?: string }>> = {
+    f: { multiplier: 1e-15 },
+    p: { multiplier: 1e-12 },
+    n: { multiplier: 1e-9 },
+    u: { multiplier: 1e-6 },
+    'µ': { multiplier: 1e-6 },
+    'μ': { multiplier: 1e-6 },
+    m: { multiplier: 1e-3 },
+    k: { multiplier: 1e3 },
+    K: { multiplier: 1e3 },
+    M: { multiplier: 1e6 },
+    G: { multiplier: 1e9 },
+    T: { multiplier: 1e12 },
+    R: { multiplier: 1, impliedUnit: 'Ω' },
+    r: { multiplier: 1, impliedUnit: 'Ω' },
+};
+
+const UNIT_ALIASES: Readonly<Record<string, string>> = {
+    F: 'F',
+    f: 'F',
+    H: 'H',
+    h: 'H',
+    V: 'V',
+    v: 'V',
+    A: 'A',
+    a: 'A',
+    W: 'W',
+    w: 'W',
+    'Ω': 'Ω', // GREEK CAPITAL LETTER OMEGA — canonical form
+    'Ω': 'Ω', // OHM SIGN — LiveSPICE writes "Ω" with this codepoint; canonicalize
+    ohm: 'Ω',
+    Ohm: 'Ω',
+    OHM: 'Ω',
+    ohms: 'Ω',
+    Hz: 'Hz',
+    HZ: 'Hz',
+    hz: 'Hz',
+    s: 's',
+    S: 's',
+};
+
+const QUANTITY_REGEX = /^([+-]?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?)([A-Za-zµμΩΩ]*)$/;
+const SHORTHAND_QUANTITY_REGEX = /^([+-]?\d+)([fFpPnNuUµμmMkKGTRr])(\d+)([A-Za-zµμΩΩ]*)$/;
+const SPICE_MEG = /^(?:Meg|MEG|meg)/;
+
+export function parseQuantity(input: string): ParsedQuantity | null {
+    const raw = input.trim();
+    if (raw.length === 0) {
+        return null;
+    }
+
+    const compact = raw.replace(/\s+/g, '');
+    const shorthand = parseShorthandQuantity(raw, compact);
+    if (shorthand !== null) {
+        return shorthand;
+    }
+
+    const match = compact.match(QUANTITY_REGEX);
+    if (!match) {
+        return null;
+    }
+
+    const numStr = match[1];
+    const suffix = match[2] ?? '';
+    if (numStr === undefined) {
+        return null;
+    }
+
+    const baseValue = Number.parseFloat(numStr);
+    if (!Number.isFinite(baseValue)) {
+        return null;
+    }
+
+    const parsed = parseSuffix(suffix);
+
+    return {
+        raw,
+        value: baseValue * parsed.multiplier,
+        unit: parsed.unit,
+    };
+}
+
+function parseShorthandQuantity(raw: string, compact: string): ParsedQuantity | null {
+    const match = compact.match(SHORTHAND_QUANTITY_REGEX);
+    if (match === null) {
+        return null;
+    }
+
+    const whole = match[1];
+    const marker = match[2];
+    const fractional = match[3];
+    const trailingUnit = match[4] ?? '';
+    if (whole === undefined || marker === undefined || fractional === undefined) {
+        return null;
+    }
+
+    const markerDef = SHORTHAND_MARKERS[marker];
+    if (markerDef === undefined) {
+        return null;
+    }
+
+    const value = Number.parseFloat(`${whole}.${fractional}`);
+    if (!Number.isFinite(value)) {
+        return null;
+    }
+
+    const aliasedTrailingUnit = UNIT_ALIASES[trailingUnit];
+    const unit = trailingUnit.length > 0
+        ? aliasedTrailingUnit ?? trailingUnit
+        : markerDef.impliedUnit ?? '';
+
+    return {
+        raw,
+        value: value * markerDef.multiplier,
+        unit,
+    };
+}
+
+function parseSuffix(suffix: string): { multiplier: number; unit: string } {
+    if (suffix.length === 0) {
+        return { multiplier: 1, unit: '' };
+    }
+
+    // SPICE convention: "Meg" / "MEG" / "meg" = 1e6, distinct from milli "m".
+    // Match before the single-char prefix loop so "meg" doesn't get read as milli + "eg".
+    const megMatch = SPICE_MEG.exec(suffix);
+    if (megMatch) {
+        const rest = suffix.slice(megMatch[0].length);
+        if (rest.length === 0) {
+            return { multiplier: 1e6, unit: '' };
+        }
+        const restUnit = UNIT_ALIASES[rest];
+        return { multiplier: 1e6, unit: restUnit ?? rest };
+    }
+
+    const first = suffix.charAt(0);
+    const rest = suffix.slice(1);
+    const prefixMultiplier = SI_PREFIXES[first];
+
+    if (prefixMultiplier !== undefined) {
+        if (rest.length === 0) {
+            return { multiplier: prefixMultiplier, unit: '' };
+        }
+        const restUnit = UNIT_ALIASES[rest];
+        if (restUnit !== undefined) {
+            return { multiplier: prefixMultiplier, unit: restUnit };
+        }
+    }
+
+    const fullUnit = UNIT_ALIASES[suffix];
+    if (fullUnit !== undefined) {
+        return { multiplier: 1, unit: fullUnit };
+    }
+
+    return { multiplier: 1, unit: suffix };
+}