@vessel-dsp/core 0.5.0 → 0.6.0

package/src/formats/interchange/serializer.ts

@@ -15,14 +15,19 @@ import type {
     ControlOutput,
     DocumentSource,
     PanelElementBinding,
+    PanelElementPhysicalPlacement,
     PanelElementPlacement,
     PanelFace,
+    PanelFaceGeometry,
     PanelGridLayout,
     PanelGridPosition,
     PanelPlacementMetadata,
     Point,
     PropertyValue,
     Terminal,
+    VdspBuildDataObject,
+    VdspBuildDataScalar,
+    VdspBuildDataValue,
     Warning,
     Wire,
 } from '../../model/types';
@@ -44,8 +49,9 @@ export function serializeInterchangeYaml(
     options: SerializeInterchangeYamlOptions = {},
 ): string {
     const connectivity = resolveConnectivity(doc);
+    const schema = hasV3OnlyFields(doc) ? 'circuit-interchange/v3' : 'circuit-interchange/v2';
     const root: MutableYamlObject = {
-        schema: 'circuit-interchange/v2',
+        schema,
         metadata: {
             name: doc.metadata.name,
             description: doc.metadata.description,
@@ -62,6 +68,21 @@ export function serializeInterchangeYaml(
     if (doc.controlContexts !== undefined) {
         root.controlContexts = doc.controlContexts.map(controlContextBlock);
     }
+    if (doc.mechanical !== undefined) {
+        root.mechanical = buildDataObjectBlock(doc.mechanical);
+    }
+    if (doc.build !== undefined) {
+        root.build = buildDataObjectBlock(doc.build);
+    }
+    if (doc.bom !== undefined) {
+        root.bom = buildDataObjectBlock(doc.bom);
+    }
+    if (doc.partProfiles !== undefined) {
+        root.partProfiles = buildDataObjectBlock(doc.partProfiles);
+    }
+    if (doc.footprints !== undefined) {
+        root.footprints = buildDataObjectBlock(doc.footprints);
+    }
     if (doc.deviceInterface !== undefined) {
         root.deviceInterface = deviceInterfaceBlock(doc.deviceInterface);
     }
@@ -74,6 +95,9 @@ export function serializeInterchangeYaml(
     if (doc.controlOutputs !== undefined) {
         root.controlOutputs = doc.controlOutputs.map(controlOutputBlock);
     }
+    if (doc.offBoardWiring !== undefined) {
+        root.offBoardWiring = buildDataObjectBlock(doc.offBoardWiring);
+    }
     Object.assign(root, {
         components: doc.components.map((component) => componentBlock(component, connectivity)),
         nodes: nodeBlocks(connectivity),
@@ -82,10 +106,36 @@ export function serializeInterchangeYaml(
         diagnostics: doc.warnings.map(warningBlock),
         rawAttributes: doc.rawAttributes,
     });
+    if (doc.boards !== undefined) {
+        root.boards = doc.boards.map(buildDataObjectBlock);
+    }
 
     return `${emitYaml(root, 0)}\n`;
 }
 
+function hasV3OnlyFields(doc: CircuitDocument): boolean {
+    return doc.mechanical !== undefined
+        || doc.build !== undefined
+        || doc.bom !== undefined
+        || doc.partProfiles !== undefined
+        || doc.footprints !== undefined
+        || doc.offBoardWiring !== undefined
+        || doc.boards !== undefined
+        || hasV3PanelFields(doc.panel);
+}
+
+function hasV3PanelFields(panel: PanelPlacementMetadata | undefined): boolean {
+    return panel?.faces.some((face) =>
+        face.geometry !== undefined
+        || face.elements.some((element) =>
+            element.id !== undefined
+            || element.physical !== undefined
+            || element.kind === 'selector'
+            || element.kind === 'footswitch'
+        )
+    ) ?? false;
+}
+
 function deviceBlock(device: CircuitDocumentDevice): MutableYamlObject {
     const out: MutableYamlObject = {
         kind: device.kind,
@@ -313,6 +363,9 @@ function panelFaceBlock(face: PanelFace): MutableYamlObject {
         out.label = face.label;
     }
     out.layout = panelLayoutBlock(face.layout);
+    if (face.geometry !== undefined) {
+        out.geometry = panelFaceGeometryBlock(face.geometry);
+    }
     out.elements = face.elements.map(panelElementBlock);
     return out;
 }
@@ -339,15 +392,29 @@ function panelElementBlock(element: PanelElementPlacement): MutableYamlObject {
         kind: element.kind,
         grid: panelGridPositionBlock(element.grid),
     };
+    if (element.id !== undefined) {
+        out.id = element.id;
+    }
     if (element.label !== undefined) {
         out.label = element.label;
     }
     if (element.interfaceControlId !== undefined) {
         out.interfaceControlId = element.interfaceControlId;
     }
+    if (element.physical !== undefined) {
+        out.physical = panelElementPhysicalBlock(element.physical);
+    }
     return out;
 }
 
+function panelFaceGeometryBlock(geometry: PanelFaceGeometry): MutableYamlObject {
+    return buildDataObjectBlock(geometry);
+}
+
+function panelElementPhysicalBlock(physical: PanelElementPhysicalPlacement): MutableYamlObject {
+    return buildDataObjectBlock(physical);
+}
+
 function panelElementBindingBlock(binding: PanelElementBinding): MutableYamlObject {
     const out: MutableYamlObject = {
         componentId: binding.componentId,
@@ -476,6 +543,26 @@ function pointBlock(point: Point): MutableYamlObject {
     };
 }
 
+function buildDataObjectBlock(value: VdspBuildDataObject): MutableYamlObject {
+    const out: MutableYamlObject = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (child !== undefined) {
+            out[key] = buildDataValueBlock(child);
+        }
+    }
+    return out;
+}
+
+function buildDataValueBlock(value: VdspBuildDataValue): YamlValue {
+    if (isBuildDataScalar(value)) {
+        return value;
+    }
+    if (isBuildDataArray(value)) {
+        return value.map(buildDataValueBlock);
+    }
+    return buildDataObjectBlock(value);
+}
+
 function emitYaml(value: YamlValue, indent: number): string {
     if (isScalar(value)) {
         return `${spaces(indent)}${formatScalar(value)}`;
@@ -556,6 +643,14 @@ function isYamlArray(value: YamlValue): value is readonly YamlValue[] {
     return Array.isArray(value);
 }
 
+function isBuildDataScalar(value: VdspBuildDataValue): value is VdspBuildDataScalar {
+    return value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+}
+
+function isBuildDataArray(value: VdspBuildDataValue): value is readonly VdspBuildDataValue[] {
+    return Array.isArray(value);
+}
+
 function formatKey(key: string): string {
     return isPlainScalar(key) ? key : JSON.stringify(key);
 }

package/src/index.ts

@@ -1,11 +1,40 @@
-export const VERSION = '0.5.0';
+export const VERSION = '0.6.0';
 
 export type {
+    BoardApplicability,
+    BoardEdgeTerminal,
+    BoardFamily,
+    BoardFootprint,
+    BoardFootprintCatalog,
+    BoardFootprintPlacement,
+    BoardHole,
+    BoardKind,
+    BoardNet,
+    BoardNetlist,
+    BoardNetMember,
+    BoardNetRef,
+    BoardPlacedPad,
+    BoardRealization,
+    BoardReview,
+    BoardRoute,
+    BoardSourceCircuitHash,
+    BoardSubtype,
+    BuildBom,
+    BuildBomItem,
+    BuildBomRef,
+    BuildBomRefKind,
+    BuildCompleteness,
+    BuildIntent,
+    BuildPartProfile,
+    BuildPartProfileCatalog,
+    BuildScope,
+    CanonicalCircuitNetRef,
     CircuitDocument,
     CircuitDocumentDevice,
     CircuitDocumentDeviceKind,
     Component,
     ComponentKind,
+    ComponentTerminalRef,
     ControlApplicabilityPredicate,
     ControlContext,
     ControlGroup,
@@ -23,12 +52,25 @@ export type {
     DeviceInterfaceControlKind,
     DocumentMetadata,
     DocumentSource,
+    MechanicalBuildMetadata,
+    MillimeterRect,
+    OffBoardSignalRef,
+    OffBoardWireAttributes,
+    OffBoardWiringConnection,
+    OffBoardWiringCoverage,
+    OffBoardWiringEndpoint,
+    OffBoardWiringEndpointKind,
+    OffBoardWiringHarness,
+    OffBoardWiringHarnessStatus,
+    OffBoardWiringPlan,
     PanelColumnOrder,
     PanelControlKind,
     PanelControlPlacement,
     PanelElementBinding,
+    PanelElementPhysicalPlacement,
     PanelElementPlacement,
     PanelFace,
+    PanelFaceGeometry,
     PanelGridIndexing,
     PanelGridLayout,
     PanelGridPosition,
@@ -40,6 +82,9 @@ export type {
     PropertyValue,
     Rotation,
     Terminal,
+    VdspBuildDataObject,
+    VdspBuildDataScalar,
+    VdspBuildDataValue,
     Warning,
     Wire,
 } from './model/types';
@@ -87,6 +132,10 @@ export type {
     SerializeCircuitDocumentFileOptions,
     SerializeVdspCircuitDocumentOptions,
     ConvertCircuitDocumentFileOptions,
+    ConvertCircuitDocumentFileWithReportOptions,
+    CircuitDocumentConversionDiagnostic,
+    CircuitDocumentConversionLossPolicy,
+    CircuitDocumentFileConversionReport,
     VdspSchemaValidationIssue,
     VdspSchemaValidationResult,
 } from './formats/document';
@@ -102,6 +151,7 @@ export {
     parseCircuitDocumentFile,
     serializeCircuitDocumentFile,
     convertCircuitDocumentFile,
+    convertCircuitDocumentFileWithReport,
     serializeVdspCircuitDocument,
 } from './formats/document';
 export { parseLtspiceAsc } from './formats/ltspice/parser';

package/src/model/types.ts

@@ -236,7 +236,7 @@ export type PanelGridLayout = Readonly<{
     columnOrder?: PanelColumnOrder;
 }>;
 
-export type PanelControlKind = 'knob' | 'slider' | 'switch' | 'led' | 'jack';
+export type PanelControlKind = 'knob' | 'slider' | 'switch' | 'selector' | 'footswitch' | 'led' | 'jack';
 
 export type PanelGridPosition = Readonly<{
     row: number;
@@ -253,11 +253,13 @@ export type PanelElementBinding = Readonly<{
 }>;
 
 export type PanelElementPlacement = Readonly<{
+    id?: string;
     bind: PanelElementBinding;
     kind: PanelControlKind;
     grid: PanelGridPosition;
     label?: string;
     interfaceControlId?: string;
+    physical?: PanelElementPhysicalPlacement;
 }>;
 
 /** @deprecated Use PanelElementPlacement. */
@@ -267,6 +269,7 @@ export type PanelFace = Readonly<{
     id: string;
     label?: string;
     layout: PanelGridLayout;
+    geometry?: PanelFaceGeometry;
     elements: readonly PanelElementPlacement[];
 }>;
 
@@ -274,6 +277,297 @@ export type PanelPlacementMetadata = Readonly<{
     faces: readonly PanelFace[];
 }>;
 
+export type VdspBuildDataScalar = string | number | boolean | null;
+
+export type VdspBuildDataValue = VdspBuildDataScalar | readonly VdspBuildDataValue[] | VdspBuildDataObject;
+
+export type VdspBuildDataObject = Readonly<{
+    readonly [key: string]: VdspBuildDataValue | undefined;
+}>;
+
+export type MillimeterRect = Readonly<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>;
+
+export type PanelFaceGeometry = VdspBuildDataObject & Readonly<{
+    units?: string;
+    surface?: string;
+    usableRectMm?: MillimeterRect;
+}>;
+
+export type PanelElementPhysicalPlacement = VdspBuildDataObject & Readonly<{
+    units?: string;
+    centerMm?: Point;
+    drillDiameterMm?: number;
+    partProfileId?: string;
+    locked?: boolean;
+}>;
+
+export type BuildIntent = 'diy-build-artifact' | 'schema-review-sample';
+
+export type BuildCompleteness = 'complete-selected-build' | 'partial-offboard-wiring';
+
+export type BuildScope = VdspBuildDataObject & Readonly<{
+    schema: 'build-scope/v1';
+    intent?: BuildIntent;
+    completeness?: BuildCompleteness;
+    selectedBoardId?: string;
+    selectedOffBoardWiringHarnessIds?: readonly string[];
+    alternateBoardIds?: readonly string[];
+    bomScope?: string;
+}>;
+
+export type MechanicalBuildMetadata = VdspBuildDataObject & Readonly<{
+    schema?: string;
+    units?: string;
+    coordinateSystem?: VdspBuildDataObject;
+    enclosure?: VdspBuildDataObject & Readonly<{
+        profileId?: string;
+        label?: string;
+        outerSizeMm?: VdspBuildDataObject;
+        wallThicknessMm?: number;
+    }>;
+    internalBoard?: VdspBuildDataObject & Readonly<{
+        preferredBoardId?: string;
+        usableRectMm?: MillimeterRect;
+        keepoutRectsMm?: readonly VdspBuildDataObject[];
+    }>;
+}>;
+
+export type BuildBomRefKind =
+    | 'component'
+    | 'device-interface-control'
+    | 'panel-element'
+    | 'board'
+    | 'freeform-build-item';
+
+export type BuildBomRef = VdspBuildDataObject & Readonly<{
+    kind: BuildBomRefKind;
+    componentId?: string;
+    controlId?: string;
+    panelElementId?: string;
+    boardId?: string;
+    label?: string;
+}>;
+
+export type BuildBomItem = VdspBuildDataObject & Readonly<{
+    id: string;
+    refs: readonly BuildBomRef[];
+    quantity: number;
+    value?: string;
+    partProfileId?: string;
+    category?: string;
+    sku?: string;
+}>;
+
+export type BuildBom = VdspBuildDataObject & Readonly<{
+    schema: 'build-bom/v1';
+    items: readonly BuildBomItem[];
+}>;
+
+export type BuildPartProfile = VdspBuildDataObject & Readonly<{
+    id: string;
+    kind?: string;
+}>;
+
+export type BuildPartProfileCatalog = VdspBuildDataObject & Readonly<{
+    schema: 'part-profile-catalog/v1';
+    resolution?: string;
+    units?: string;
+    profiles: readonly BuildPartProfile[];
+}>;
+
+export type BoardFootprint = VdspBuildDataObject & Readonly<{
+    id: string;
+    boardApplicability?: BoardApplicability;
+}>;
+
+export type BoardFootprintCatalog = VdspBuildDataObject & Readonly<{
+    schema: 'board-footprint-catalog/v1';
+    resolution?: string;
+    units?: string;
+    footprints: readonly BoardFootprint[];
+}>;
+
+export type OffBoardWiringCoverage = 'selected-build-complete' | 'representative-selected-build-endpoints';
+
+export type OffBoardWiringHarnessStatus = 'complete' | 'partial' | 'candidate';
+
+export type OffBoardWiringEndpointKind =
+    | 'panel-component-terminal'
+    | 'board-terminal'
+    | 'power-terminal'
+    | 'footswitch-terminal'
+    | 'free-wire-label';
+
+export type OffBoardWiringEndpoint = VdspBuildDataObject & Readonly<{
+    id: string;
+    kind: OffBoardWiringEndpointKind;
+    componentId?: string;
+    terminalName?: string;
+    panelElementId?: string;
+    boardId?: string;
+    terminalId?: string;
+    label?: string;
+}>;
+
+export type BoardNetRef = VdspBuildDataObject & Readonly<{
+    source: 'board-netlist';
+    boardId?: string;
+    netId: string;
+}>;
+
+export type CanonicalCircuitNetRef = VdspBuildDataObject & Readonly<{
+    source: 'canonical-circuit';
+    member?: ComponentTerminalRef;
+}>;
+
+export type OffBoardSignalRef = BoardNetRef | CanonicalCircuitNetRef | VdspBuildDataObject;
+
+export type OffBoardWireAttributes = VdspBuildDataObject & Readonly<{
+    color?: string;
+    gaugeAwg?: number;
+    reviewedLengthMm?: number;
+    groupId?: string;
+}>;
+
+export type OffBoardWiringConnection = VdspBuildDataObject & Readonly<{
+    id: string;
+    fromEndpointId: string;
+    toEndpointId: string;
+    signalRef?: OffBoardSignalRef;
+    wire?: OffBoardWireAttributes;
+}>;
+
+export type OffBoardWiringHarness = VdspBuildDataObject & Readonly<{
+    id: string;
+    status?: OffBoardWiringHarnessStatus;
+    notes?: string;
+    endpoints: readonly OffBoardWiringEndpoint[];
+    connections: readonly OffBoardWiringConnection[];
+}>;
+
+export type OffBoardWiringPlan = VdspBuildDataObject & Readonly<{
+    schema: 'offboard-wiring/v1';
+    source?: string;
+    coverage?: OffBoardWiringCoverage;
+    harnesses: readonly OffBoardWiringHarness[];
+}>;
+
+export type BoardFamily = 'prototype-board' | 'fabricated-board';
+
+export type BoardKind = 'stripboard' | 'perfboard' | 'breadboard-pattern' | 'pcb';
+
+export type BoardSubtype =
+    | 'veroboard'
+    | 'isolated-pad'
+    | 'solderable-half-breadboard'
+    | 'single-sided-through-hole'
+    | 'two-layer-through-hole';
+
+export type BoardApplicability = VdspBuildDataObject & Readonly<{
+    family: BoardFamily;
+    kind: BoardKind;
+    subtype?: BoardSubtype;
+}>;
+
+export type ComponentTerminalRef = VdspBuildDataObject & Readonly<{
+    componentId: string;
+    terminalName: string;
+}>;
+
+export type BoardSourceCircuitHash = VdspBuildDataObject & Readonly<{
+    schema: 'canonical-circuit-facts-hash/v1';
+    hashAlgorithm: 'sha256';
+    hash: string;
+}>;
+
+export type BoardHole = VdspBuildDataObject & Readonly<{
+    row: number;
+    column: number;
+}>;
+
+export type BoardEdgeTerminal = VdspBuildDataObject & Readonly<{
+    id: string;
+    role?: string;
+    terminalRef?: ComponentTerminalRef;
+    hole?: BoardHole;
+}>;
+
+export type BoardPlacedPad = VdspBuildDataObject & Readonly<{
+    padId: string;
+    terminalName?: string;
+    hole?: BoardHole;
+    positionMm?: Point;
+}>;
+
+export type BoardFootprintPlacement = VdspBuildDataObject & Readonly<{
+    componentId: string;
+    footprintId: string;
+    atGrid?: BoardHole;
+    atMm?: Point;
+    rotationDeg?: number;
+    pads: readonly BoardPlacedPad[];
+}>;
+
+export type BoardNetMember = VdspBuildDataObject & Readonly<{
+    componentId: string;
+    terminalName: string;
+    padId?: string;
+    terminalId?: string;
+}>;
+
+export type BoardNet = VdspBuildDataObject & Readonly<{
+    id: string;
+    name?: string;
+    members: readonly BoardNetMember[];
+}>;
+
+export type BoardNetlist = VdspBuildDataObject & Readonly<{
+    source?: string;
+    nets: readonly BoardNet[];
+}>;
+
+export type BoardRoute = VdspBuildDataObject & Readonly<{
+    id: string;
+    netRef?: BoardNetRef | CanonicalCircuitNetRef | VdspBuildDataObject;
+    locked?: boolean;
+    conductors?: readonly VdspBuildDataObject[];
+    copper?: readonly VdspBuildDataObject[];
+    vias?: readonly VdspBuildDataObject[];
+    zones?: readonly VdspBuildDataObject[];
+    drills?: readonly VdspBuildDataObject[];
+}>;
+
+export type BoardReview = VdspBuildDataObject & Readonly<{
+    status?: 'buildable' | 'candidate' | 'stale' | string;
+    reviewedBy?: string;
+    reviewedAt?: string;
+    notes?: string;
+}>;
+
+export type BoardRealization = VdspBuildDataObject & Readonly<{
+    id: string;
+    schema: 'circuit-board/v1';
+    family: BoardFamily;
+    kind: BoardKind;
+    subtype?: BoardSubtype;
+    source?: string;
+    units?: string;
+    locked?: boolean;
+    sourceCircuit?: BoardSourceCircuitHash;
+    edgeTerminals: readonly BoardEdgeTerminal[];
+    footprintPlacements: readonly BoardFootprintPlacement[];
+    netlist?: BoardNetlist;
+    routes: readonly BoardRoute[];
+    zones?: readonly VdspBuildDataObject[];
+    drills?: readonly VdspBuildDataObject[];
+    review?: BoardReview;
+}>;
+
 export type Warning = Readonly<{
     code: string;
     message: string;
@@ -287,6 +581,13 @@ export type CircuitDocument = Readonly<{
     device?: CircuitDocumentDevice;
     controlGroups?: readonly ControlGroup[];
     controlContexts?: readonly ControlContext[];
+    mechanical?: MechanicalBuildMetadata;
+    build?: BuildScope;
+    bom?: BuildBom;
+    partProfiles?: BuildPartProfileCatalog;
+    footprints?: BoardFootprintCatalog;
+    offBoardWiring?: OffBoardWiringPlan;
+    boards?: readonly BoardRealization[];
     deviceInterface?: DeviceInterface;
     panel?: PanelPlacementMetadata;
     controlInterfaces?: readonly ControlInterface[];