@bushscad/cli 0.0.0-stage → 0.3.1

package/src/dto/types.ts

@@ -0,0 +1,195 @@
+/**
+ * @author Aidan Boissonneault
+ * @file types.ts
+ * @purpose Provides types behavior for the dto in cli package.
+ * @last-edited October 6, 2026
+ */
+
+import type {
+  CompileError,
+  DrawingResult,
+  ExportFormat,
+  IRProgram,
+  InteractionSnapshot,
+  MaterialAppearance,
+  OcctTraceEvent,
+  ResolvedJointData,
+  ValidationResult,
+} from '@bushscad/ir';
+import type { EnvManifestEntry } from '@bushscad/compiler';
+import type {
+  CompileEntrypointMode,
+  FileOverlayMap,
+} from '@bushscad/compiler/node';
+
+/**
+ * Mesh dto, including part name, body name, color, uses default color, and material.
+ */
+export type MeshDto = {
+  partName: string;
+  bodyName?: string;
+  color: string;
+  usesDefaultColor?: boolean;
+  material?: MaterialAppearance;
+  vertices: number[];
+  normals: number[];
+  indices: number[];
+  isHardwareVisual?: boolean;
+  hardwareKind?: 'bolt' | 'insert';
+};
+
+/**
+ * Buffer dto, including name and encoded geometry data.
+ */
+export type BufferDto = {
+  name: string;
+  dataBase64: string;
+};
+
+/**
+ * Accepted values for compiler engine are 'classic' and 'parallel'.
+ */
+export type CompilerEngine = 'classic' | 'parallel';
+/**
+ * Accepted values for drawing output mode are 'write-source-paths' and 'return-content'.
+ */
+export type DrawingOutputMode = 'write-source-paths' | 'return-content';
+
+/**
+ * Measurements for compiler, including engine, fallback reason, worker count, ready worker
+ * count, and IR compilation time.
+ */
+export type CompilerMetrics = {
+  engine: CompilerEngine;
+  fallbackReason?: string;
+  workerCount: number;
+  readyWorkerCount: number;
+  compileIrMs: number;
+  geometryMs: number;
+  assemblyMs: number;
+  workerStartupMs: number;
+  reusedWarmWorkers: boolean;
+  schedulerTaskCount?: number;
+  workerBusyMs?: number;
+  workerCpuMs?: number;
+  queueWaitMs?: number;
+  transportMs?: number;
+  workerUtilization?: number;
+  longestWorkerTaskMs?: number;
+  aggregateWorkerRssBytes?: number;
+  peakWorkerRssBytes?: number;
+  componentPreparationMs?: number;
+  componentReductionMs?: number;
+  preparedComponentCount?: number;
+  componentRecipeCount?: number;
+  componentCacheHitCount?: number;
+  nativeBooleanBatchCount?: number;
+  nativeBooleanAvoidedBuildCount?: number;
+  nativeBooleanRejectionCount?: number;
+};
+
+/**
+ * Accepted values for compiler request kind are 'check', 'preview', 'export', and
+ * 'exportDrawings'.
+ */
+export type CompilerRequestKind =
+  | 'check'
+  | 'preview'
+  | 'export'
+  | 'exportDrawings';
+
+/**
+ * Request to compiler, including operation kind, source file path, workspace root, entrypoint
+ * mode, and source overlays.
+ */
+export type CompilerRequest = {
+  kind: CompilerRequestKind;
+  filePath: string;
+  rootPath?: string | null;
+  entrypointMode?: CompileEntrypointMode;
+  overlays?: FileOverlayMap;
+  env?: Record<string, string>;
+  format?: ExportFormat;
+  cursorOpIndex?: number;
+  suppressedOpIndices?: number[];
+  occtTrace?: boolean;
+  engine?: CompilerEngine;
+  drawingOutputMode?: DrawingOutputMode;
+};
+
+/**
+ * Derives `ServiceRequest` from `CompilerRequest & { id: number }` to preserve its type relationship
+ * in the dto layer.
+ */
+export type ServiceRequest = CompilerRequest & { id: number };
+
+/**
+ * Written drawing dto, including name, path, and export format.
+ */
+type WrittenDrawingDto = { name: string; path: string; format: string };
+
+/**
+ * Response from service is tagged by ok: 'true' carries program, meshes, interaction and 'false'
+ * carries errors.
+ */
+export type ServiceResponse =
+  | {
+      id: number;
+      kind: ServiceRequest['kind'];
+      ok: true;
+      program?: IRProgram;
+      meshes?: MeshDto[];
+      interaction?: InteractionSnapshot;
+      drawings?: DrawingResult[];
+      buffers?: BufferDto[];
+      validations?: ValidationResult[];
+      joints?: ResolvedJointData[];
+      writtenDrawings?: WrittenDrawingDto[];
+      occtTraceEvents?: OcctTraceEvent[];
+      env: EnvManifestEntry[];
+      dependents?: Record<string, string[]>;
+      elapsedMs: number;
+      compilerMetrics?: CompilerMetrics;
+    }
+  | {
+      id: number;
+      kind: ServiceRequest['kind'];
+      ok: false;
+      errors: CompileError[];
+      occtTraceEvents?: OcctTraceEvent[];
+      env: EnvManifestEntry[];
+      elapsedMs: number;
+      compilerMetrics?: CompilerMetrics;
+    };
+
+/**
+ * Message for service trace, including identifier, operation kind, and event.
+ */
+export type ServiceTraceMessage = {
+  id: number;
+  kind: 'occt-trace';
+  event: OcctTraceEvent;
+};
+
+/**
+ * Message for service pool, including operation kind and status.
+ */
+export type ServicePoolMessage = {
+  kind: 'pool-status';
+  status: CompilerPoolStatus;
+};
+
+/**
+ * status of compiler pool represented by
+ * import('../service/parallel/worker-protocol.js').ParallelPoolStatus.
+ */
+export type CompilerPoolStatus =
+  import('../service/parallel/worker-protocol.js').ParallelPoolStatus;
+
+/**
+ * Message for service accepts ServiceResponse, ServiceTraceMessage, and ServicePoolMessage.
+ */
+export type ServiceMessage =
+  | ServiceResponse
+  | ServiceTraceMessage
+  | ServicePoolMessage;

package/src/service/parallel/worker-protocol.ts

@@ -0,0 +1,164 @@
+/**
+ * @author Aidan Boissonneault
+ * @file worker-protocol.ts
+ * @purpose Provides worker protocol behavior for the service parallel in cli package.
+ * @last-edited October 6, 2026
+ */
+
+import type {
+  CompileAssets,
+  DrawingProgram,
+  DrawingResult,
+  SourceSpan,
+  ExportFormat,
+  IRProgram,
+  InteractionSnapshot,
+  MeshData,
+  NativeBooleanBatchPlan,
+  OcctTraceEvent,
+  PreparedComponentArtifact,
+  ResolvedJointData,
+  ValidationResult,
+} from '@bushscad/ir';
+
+/**
+ * Parallel build task, including task id, part name, source index, auto color offset, and
+ * program.
+ */
+export type ParallelBuildTask = {
+  taskId: number;
+  partName: string;
+  sourceIndex: number;
+  autoColorOffset: number;
+  program: IRProgram;
+  assets: CompileAssets;
+  trace: boolean;
+  drawingProgram?: DrawingProgram;
+  preparedComponents?: PreparedComponentArtifact[];
+  nativeBooleanPlan?: NativeBooleanBatchPlan;
+  nativeBooleanConcurrencyLimit?: number;
+};
+
+/**
+ * Parallel worker telemetry, including worker cpu milliseconds and worker rss bytes.
+ */
+export type ParallelWorkerTelemetry = {
+  workerCpuMs: number;
+  workerRssBytes: number;
+};
+
+/**
+ * Derives `ParallelBuildOutput` from `ParallelWorkerTelemetry & { taskId: number; partName: string;
+ * sourceIndex: number; meshes: MeshData[]; drawings: DrawingResult[]; interaction?:
+ * InteractionSnapshot; validations: ValidationResult[]; joints: ResolvedJointData[]; traceEvents:
+ * OcctTraceEvent[]; elapsedMs: number; }` to preserve its type relationship in the service parallel
+ * layer.
+ */
+export type ParallelBuildOutput = ParallelWorkerTelemetry & {
+  taskId: number;
+  partName: string;
+  sourceIndex: number;
+  meshes: MeshData[];
+  drawings: DrawingResult[];
+  interaction?: InteractionSnapshot;
+  validations: ValidationResult[];
+  joints: ResolvedJointData[];
+  traceEvents: OcctTraceEvent[];
+  elapsedMs: number;
+};
+
+/**
+ * Parallel component task, including task id, part name, source index, name, and recipe digest.
+ */
+export type ParallelComponentTask = {
+  taskId: number;
+  partName: string;
+  sourceIndex: number;
+  name: string;
+  recipeDigest: string;
+  program: IRProgram;
+  assets: CompileAssets;
+  semanticConsumerIds: string[];
+  trace: boolean;
+};
+
+/**
+ * Derives `ParallelComponentOutput` from `ParallelWorkerTelemetry & { taskId: number; partName:
+ * string; sourceIndex: number; recipeDigest: string; artifact: PreparedComponentArtifact; traceEvents:
+ * OcctTraceEvent[]; startedAtMs: number; finishedAtMs: number; elapsedMs: number; }` to preserve its
+ * type relationship in the service parallel layer.
+ */
+export type ParallelComponentOutput = ParallelWorkerTelemetry & {
+  taskId: number;
+  partName: string;
+  sourceIndex: number;
+  recipeDigest: string;
+  artifact: PreparedComponentArtifact;
+  traceEvents: OcctTraceEvent[];
+  startedAtMs: number;
+  finishedAtMs: number;
+  elapsedMs: number;
+};
+
+/**
+ * Parallel export task, including task id, program, assets, drawing program, and export format.
+ */
+export type ParallelExportTask = {
+  taskId: number;
+  program: IRProgram;
+  assets: CompileAssets;
+  drawingProgram: DrawingProgram;
+  format: ExportFormat;
+  nativeBooleanPlan?: NativeBooleanBatchPlan;
+};
+
+/**
+ * Derives `ParallelExportOutput` from `ParallelWorkerTelemetry & { taskId: number; buffers: { name:
+ * string; data: ArrayBuffer }[]; drawings: DrawingResult[]; elapsedMs: number; }` to preserve its type
+ * relationship in the service parallel layer.
+ */
+export type ParallelExportOutput = ParallelWorkerTelemetry & {
+  taskId: number;
+  buffers: { name: string; data: ArrayBuffer }[];
+  drawings: DrawingResult[];
+  elapsedMs: number;
+};
+
+/**
+ * Request to parallel worker is tagged by kind: 'build' carries task, 'prepare-component'
+ * carries task, 'export' carries task, and 'shutdown'.
+ */
+export type ParallelWorkerRequest =
+  | { kind: 'build'; task: ParallelBuildTask }
+  | { kind: 'prepare-component'; task: ParallelComponentTask }
+  | { kind: 'export'; task: ParallelExportTask }
+  | { kind: 'shutdown' };
+
+/**
+ * Message for parallel worker is tagged by kind: 'ready' carries startup duration, worker rss
+ * bytes, 'trace' carries task id, event, 'result' carries output, 'component-result' carries
+ * output, 'export-result' carries output, and 'error' carries task id, message, span.
+ */
+export type ParallelWorkerMessage =
+  | { kind: 'ready'; startupMs: number; workerRssBytes: number }
+  | { kind: 'trace'; taskId: number; event: OcctTraceEvent }
+  | { kind: 'result'; output: ParallelBuildOutput }
+  | { kind: 'component-result'; output: ParallelComponentOutput }
+  | { kind: 'export-result'; output: ParallelExportOutput }
+  | { kind: 'error'; taskId: number; message: string; span?: SourceSpan };
+
+/**
+ * Status of parallel pool, including current state, desired worker count, warming workers, ready
+ * worker count, and busy workers.
+ */
+export type ParallelPoolStatus = {
+  state: 'warming' | 'ready' | 'busy' | 'degraded' | 'failed' | 'stopped';
+  desiredWorkers: number;
+  warmingWorkers: number;
+  readyWorkers: number;
+  busyWorkers: number;
+  failedWorkers: number;
+  startupMs: number;
+  aggregateWorkerRssBytes: number;
+  peakAggregateWorkerRssBytes: number;
+};