@bushscad/cli 0.0.0-stage → 0.3.1

package/dist/p7-benchmark.js

@@ -0,0 +1,623 @@
+// scripts/parallel-compilation/p7-benchmark.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { basename, dirname as dirname2, resolve } from "node:path";
+
+// scripts/parallel-compilation/report-output.ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+async function writeJsonReport(outPath, report, stdoutReport = report) {
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, `${JSON.stringify(report, null, 2)}
+`, "utf8");
+  process.stdout.write(`${JSON.stringify(stdoutReport, null, 2)}
+`);
+}
+
+// scripts/parallel-compilation/p7-service-client.ts
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+var P7ServiceClient = class _P7ServiceClient {
+  constructor(child, startupWallMs, readyStatus, messages) {
+    this.child = child;
+    this.startupWallMs = startupWallMs;
+    this.readyStatus = readyStatus;
+    this.messages = messages;
+    createInterface({ input: child.stderr }).on(
+      "line",
+      (line) => this.stderr.push(line)
+    );
+  }
+  stderr = [];
+  nextRequestId = 1;
+  /** Starts the real compiled CLI and waits until every OCCT owner is ready. */
+  static async start(cliPath, workerCount) {
+    const startedAt = performance.now();
+    const child = spawn(process.execPath, [cliPath, "--service"], {
+      env: {
+        ...process.env,
+        BUSHSCAD_EXPERIMENTAL_PARALLEL: "1",
+        BUSHSCAD_OCCT_WORKERS: String(workerCount)
+      },
+      windowsHide: true
+    });
+    const messages = [];
+    createInterface({ input: child.stdout }).on("line", (line) => {
+      try {
+        messages.push(JSON.parse(line));
+      } catch {
+        messages.push({ kind: "invalid-json", line });
+      }
+    });
+    const status = await waitForReady(messages, child);
+    const client = new _P7ServiceClient(
+      child,
+      performance.now() - startedAt,
+      status,
+      messages
+    );
+    return client;
+  }
+  /** Sends one source request and captures coordinator wall time separately. */
+  async request(request) {
+    const id = this.nextRequestId++;
+    const startedAt = performance.now();
+    this.child.stdin.write(`${JSON.stringify({ id, ...request })}
+`);
+    const response = await waitForResponse(
+      this.messages,
+      this.child,
+      id,
+      request.kind
+    );
+    return { response, wallMs: performance.now() - startedAt };
+  }
+  /** Returns the newest pool status emitted after task memory was sampled. */
+  latestStatus() {
+    const status = [...this.messages].reverse().find(isPoolStatusMessage);
+    if (!status) return this.readyStatus;
+    return status.status;
+  }
+  /** Gracefully shuts down the service and all child OCCT owners. */
+  async stop() {
+    if (this.child.exitCode !== null) return;
+    this.child.kill("SIGTERM");
+    await new Promise((resolve2) => {
+      this.child.once("exit", () => resolve2());
+      setTimeout(resolve2, 1e4);
+    });
+  }
+};
+async function waitForReady(messages, child) {
+  return waitForValue(
+    messages,
+    child,
+    (message) => isPoolStatusMessage(message) && message.status.state === "ready" ? message.status : void 0
+  );
+}
+async function waitForResponse(messages, child, id, kind) {
+  return waitForValue(
+    messages,
+    child,
+    (message) => responseForRequest(message, id, kind)
+  );
+}
+function responseForRequest(value, id, kind) {
+  if (!isServiceResult(value)) return void 0;
+  return matchesRequest(value, id, kind) ? value : void 0;
+}
+function isServiceResult(value) {
+  return isRecord(value) && typeof value.ok === "boolean";
+}
+function matchesRequest(value, id, kind) {
+  return value.id === id && value.kind === kind;
+}
+async function waitForValue(messages, child, select) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < 24e4) {
+    const value = selectNewest(messages, select);
+    if (value !== void 0) return value;
+    if (child.exitCode !== null)
+      throw new Error(`Compiler service exited with ${child.exitCode}.`);
+    await new Promise((resolve2) => setTimeout(resolve2, 10));
+  }
+  throw new Error("Compiler service response timed out.");
+}
+function selectNewest(messages, select) {
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const value = select(messages[index]);
+    if (value !== void 0) return value;
+  }
+  return void 0;
+}
+function isPoolStatusMessage(value) {
+  return isRecord(value) && value.kind === "pool-status" && isRecord(value.status);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// scripts/parallel-compilation/p7-response-contract.ts
+import { createHash } from "node:crypto";
+function responseContract(response) {
+  const value = response.ok ? successContract(response) : failureContract(response);
+  return {
+    hash: createHash("sha256").update(JSON.stringify(value)).digest("hex"),
+    value
+  };
+}
+function successContract(response) {
+  return {
+    ok: true,
+    program: response.program,
+    meshes: array(response.meshes).map(meshContract),
+    interaction: interactionContract(response.interaction),
+    drawings: response.drawings,
+    validations: response.validations,
+    joints: response.joints,
+    env: response.env,
+    dependents: response.dependents,
+    buffers: array(response.buffers).map(bufferContract),
+    traceErrors: array(response.occtTraceEvents).filter(isErrorTrace).map(traceContract)
+  };
+}
+function failureContract(response) {
+  return {
+    ok: false,
+    errors: response.errors,
+    env: response.env,
+    traceErrors: array(response.occtTraceEvents).filter(isErrorTrace).map(traceContract)
+  };
+}
+function meshContract(value) {
+  if (!isRecord2(value)) return value;
+  const vertices = numberArray(value.vertices);
+  const indices = numberArray(value.indices);
+  const geometry = meshGeometry(vertices);
+  return {
+    partName: value.partName,
+    bodyName: value.bodyName,
+    color: value.color,
+    material: value.material,
+    vertexCount: vertices.length / 3,
+    triangleCount: indices.length / 3,
+    ...geometry
+  };
+}
+function meshGeometry(vertices) {
+  const bounds = [
+    [Infinity, Infinity, Infinity],
+    [-Infinity, -Infinity, -Infinity]
+  ];
+  const sums = [0, 0, 0];
+  for (let index = 0; index < vertices.length; index += 3) {
+    for (let axis = 0; axis < 3; axis++) {
+      const coordinate = vertices[index + axis] ?? 0;
+      bounds[0][axis] = Math.min(bounds[0][axis], coordinate);
+      bounds[1][axis] = Math.max(bounds[1][axis], coordinate);
+      sums[axis] += coordinate;
+    }
+  }
+  return { bounds, sums };
+}
+function interactionContract(value) {
+  if (!isRecord2(value)) return value;
+  return {
+    ...value,
+    topology: array(value.topology).map((entry) => {
+      if (!isRecord2(entry)) return entry;
+      return {
+        meshIndex: entry.meshIndex,
+        partEntityId: entry.partEntityId,
+        objectEntityId: entry.objectEntityId,
+        faces: topologyContract(entry.faces, "triangleCount"),
+        edges: topologyContract(entry.edges, "points"),
+        corners: topologyContract(entry.corners)
+      };
+    })
+  };
+}
+function topologyContract(value, aggregate) {
+  const entries = array(value).filter(isRecord2);
+  const total = entries.reduce(
+    (sum, entry) => sum + (aggregate === "triangleCount" ? number(entry.triangleCount) : aggregate === "points" ? array(entry.points).length : 0),
+    0
+  );
+  return {
+    count: entries.length,
+    ...aggregate === "triangleCount" ? { triangles: total } : {},
+    ...aggregate === "points" ? { points: total } : {},
+    owners: unique(entries.map((entry) => String(entry.ownerEntityId))),
+    targets: unique(
+      entries.flatMap((entry) => array(entry.semanticTargetIds).map(String))
+    )
+  };
+}
+function traceContract(value) {
+  if (!isRecord2(value)) return value;
+  const {
+    timestampMs: _timestamp,
+    elapsedMs: _elapsed,
+    cpuMs: _cpu,
+    ...stable
+  } = value;
+  return stable;
+}
+function isErrorTrace(value) {
+  return isRecord2(value) && (value.kind === "op-error" || value.kind === "build-error");
+}
+function bufferContract(value) {
+  if (!isRecord2(value)) return value;
+  const data = String(value.dataBase64 ?? "");
+  return {
+    name: value.name,
+    byteLength: Buffer.from(data, "base64").byteLength,
+    sha256: createHash("sha256").update(data).digest("hex")
+  };
+}
+function unique(values) {
+  return [...new Set(values)].sort();
+}
+function array(value) {
+  return Array.isArray(value) ? value : [];
+}
+function numberArray(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "number") : [];
+}
+function number(value) {
+  return typeof value === "number" ? value : 0;
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// scripts/parallel-compilation/p7-benchmark-summary.ts
+function summarizeSamples(samples) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const sample of samples) {
+    const key = [
+      sample.workers,
+      sample.workload,
+      sample.engine,
+      sample.phase
+    ].join("|");
+    groups.set(key, [...groups.get(key) ?? [], sample]);
+  }
+  return [...groups.values()].map((group) => {
+    const first = group[0];
+    return {
+      workers: first.workers,
+      workload: first.workload,
+      engine: first.engine,
+      phase: first.phase,
+      samples: group.length,
+      wallMs: statistics(group.map((sample) => sample.wallMs)),
+      compilerElapsedMs: statistics(
+        group.map((sample) => sample.compilerElapsedMs)
+      ),
+      workerCpuMs: statistics(metricValues(group, "workerCpuMs")),
+      workerBusyMs: statistics(metricValues(group, "workerBusyMs")),
+      queueWaitMs: statistics(metricValues(group, "queueWaitMs")),
+      transportMs: statistics(metricValues(group, "transportMs")),
+      workerUtilization: statistics(metricValues(group, "workerUtilization")),
+      peakWorkerRssBytes: Math.max(
+        0,
+        ...metricValues(group, "peakWorkerRssBytes")
+      ),
+      schedulerTaskCount: statistics(metricValues(group, "schedulerTaskCount")),
+      longestWorkerTaskMs: statistics(
+        metricValues(group, "longestWorkerTaskMs")
+      ),
+      nativeBooleanBatchCount: statistics(
+        metricValues(group, "nativeBooleanBatchCount")
+      ),
+      operationTimings: operationTimings(group)
+    };
+  });
+}
+function statistics(values) {
+  if (values.length === 0) return void 0;
+  const sorted = [...values].sort((left, right) => left - right);
+  return {
+    median: percentile(sorted, 0.5),
+    p95: percentile(sorted, 0.95),
+    min: sorted[0],
+    max: sorted.at(-1)
+  };
+}
+function percentile(sorted, fraction) {
+  return sorted[Math.max(0, Math.ceil(sorted.length * fraction) - 1)] ?? 0;
+}
+function metricValues(samples, name) {
+  return samples.flatMap((sample) => {
+    const value = sample.metrics?.[name];
+    return typeof value === "number" ? [value] : [];
+  });
+}
+function operationTimings(samples) {
+  const timings = /* @__PURE__ */ new Map();
+  for (const event of samples.flatMap((sample) => sample.trace))
+    recordOperationTiming(timings, event);
+  return [...timings.entries()].map(([operation, values]) => ({
+    operation,
+    elapsedMs: statistics(values.elapsedMs),
+    cpuMs: statistics(values.cpuMs)
+  }));
+}
+function recordOperationTiming(timings, event) {
+  if (!isTimedOperation(event.kind)) return;
+  const name = operationName(event);
+  const timing = timings.get(name) ?? { elapsedMs: [], cpuMs: [] };
+  appendNumber(timing.elapsedMs, event.elapsedMs);
+  appendNumber(timing.cpuMs, event.cpuMs);
+  timings.set(name, timing);
+}
+function isTimedOperation(kind) {
+  return kind === "op-success" || kind === "native-boolean-batch";
+}
+function operationName(event) {
+  return String(event.opKind ?? event.kind);
+}
+function appendNumber(values, value) {
+  if (typeof value === "number") values.push(value);
+}
+
+// scripts/parallel-compilation/p7-performance-runner.ts
+import { readFile } from "node:fs/promises";
+async function runPerformance(client, rootPath, workers, workloads, runs, samples, progress2) {
+  for (const workload of workloads)
+    await runWorkload(
+      client,
+      rootPath,
+      workers,
+      workload,
+      runs,
+      samples,
+      progress2
+    );
+}
+async function runWorkload(client, rootPath, workers, workload, runs, samples, progress2) {
+  const source = await readFile(workload.filePath, "utf8");
+  for (let round = 0; round < runs; round++)
+    await runRound(
+      client,
+      rootPath,
+      workers,
+      workload,
+      source,
+      round,
+      samples,
+      progress2
+    );
+}
+async function runRound(client, rootPath, workers, workload, source, round, samples, progress2) {
+  for (const engine of engineOrder(round))
+    await sampleEngine(
+      client,
+      rootPath,
+      workers,
+      workload,
+      source,
+      round,
+      engine,
+      samples,
+      progress2
+    );
+}
+async function sampleEngine(client, rootPath, workers, workload, source, round, engine, samples, progress2) {
+  progress2(`preview w${workers} ${workload.id} ${engine} r${round + 1}`);
+  samples.push(await takeSample(client, rootPath, workload, engine, "preview"));
+  samples.push(
+    await takeSample(client, rootPath, workload, engine, "incremental", {
+      [workload.filePath]: `${source}
+// P7 incremental ${round}
+`
+    })
+  );
+  if (!workload.export) return;
+  progress2(`export w${workers} ${workload.id} ${engine} r${round + 1}`);
+  samples.push(await takeSample(client, rootPath, workload, engine, "export"));
+}
+async function takeSample(client, rootPath, workload, engine, phase, overlays) {
+  const exporting = phase === "export";
+  const { response, wallMs } = await client.request({
+    kind: exporting ? "export" : "preview",
+    filePath: workload.filePath,
+    rootPath,
+    engine,
+    occtTrace: !exporting,
+    ...overlays ? { overlays } : {},
+    ...exporting ? { format: "step" } : {}
+  });
+  requireSuccess(response, workload, engine, phase);
+  return {
+    workers: client.readyStatus.desiredWorkers,
+    workload: workload.id,
+    engine,
+    phase,
+    wallMs,
+    compilerElapsedMs: response.elapsedMs,
+    metrics: response.compilerMetrics,
+    trace: records(response.occtTraceEvents)
+  };
+}
+function engineOrder(round) {
+  return round % 2 === 0 ? ["classic", "parallel"] : ["parallel", "classic"];
+}
+function requireSuccess(response, workload, engine, phase) {
+  if (response.ok) return;
+  throw new Error(
+    `${workload.id} ${engine} ${phase} failed: ${JSON.stringify(response)}`
+  );
+}
+function records(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter(
+    (entry) => typeof entry === "object" && entry !== null
+  );
+}
+
+// scripts/parallel-compilation/p7-benchmark.ts
+async function run() {
+  const rootPath = resolve(readArg("--root", "."));
+  const cliPath = resolve(readArg("--cli", "packages/cli/dist/index.js"));
+  const outPath = resolve(
+    readArg(
+      "--out",
+      ".bushscad-analysis/parallel-compilation/p7-benchmark.json"
+    )
+  );
+  const runs = positiveInteger(readArg("--runs", "3"));
+  const workers = readArg("--workers", "1,2,4").split(",").map(positiveInteger);
+  const scope = readArg("--scope", "full");
+  const correctnessCases = await loadSuiteCases(rootPath);
+  const performanceCases = performanceWorkloads(rootPath);
+  const equivalence = [];
+  const samples = [];
+  const lifecycle = [];
+  for (const workerCount of workers)
+    await runWorkerMatrix({
+      cliPath,
+      rootPath,
+      workerCount,
+      scope,
+      runs,
+      correctnessCases,
+      performanceCases,
+      equivalence,
+      samples,
+      lifecycle
+    });
+  const mismatches = equivalence.filter((result) => !result.match);
+  const report = {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    node: process.version,
+    rootPath,
+    cliPath,
+    configuration: { runs, workers, scope },
+    lifecycle,
+    equivalence: {
+      comparisons: equivalence.length,
+      matches: equivalence.length - mismatches.length,
+      mismatches,
+      results: equivalence
+    },
+    summaries: summarizeSamples(samples),
+    samples
+  };
+  await writeJsonReport(outPath, report, {
+    outPath,
+    lifecycle,
+    equivalence: report.equivalence,
+    summaries: report.summaries
+  });
+  if (mismatches.length > 0) process.exitCode = 2;
+}
+async function runWorkerMatrix(input) {
+  progress(`starting ${input.workerCount}-worker pool`);
+  const client = await P7ServiceClient.start(input.cliPath, input.workerCount);
+  try {
+    input.lifecycle.push({
+      workers: input.workerCount,
+      startupWallMs: client.startupWallMs,
+      ready: client.readyStatus
+    });
+    if (input.scope !== "performance")
+      await runEquivalence(
+        client,
+        input.rootPath,
+        input.workerCount,
+        input.correctnessCases,
+        input.equivalence
+      );
+    if (input.scope !== "correctness")
+      await runPerformance(
+        client,
+        input.rootPath,
+        input.workerCount,
+        input.performanceCases,
+        input.runs,
+        input.samples,
+        progress
+      );
+    input.lifecycle.push({
+      workers: input.workerCount,
+      afterMatrix: client.latestStatus()
+    });
+  } finally {
+    await client.stop();
+  }
+}
+async function runEquivalence(client, rootPath, workers, workloads, results) {
+  for (const workload of workloads) {
+    progress(`equivalence w${workers} ${workload.id}`);
+    const classic = await client.request({
+      kind: "preview",
+      filePath: workload.filePath,
+      rootPath,
+      engine: "classic",
+      occtTrace: true
+    });
+    const parallel = await client.request({
+      kind: "preview",
+      filePath: workload.filePath,
+      rootPath,
+      engine: "parallel",
+      occtTrace: true
+    });
+    const classicContract = responseContract(classic.response);
+    const parallelContract = responseContract(parallel.response);
+    results.push({
+      workers,
+      workload: workload.id,
+      classicHash: classicContract.hash,
+      parallelHash: parallelContract.hash,
+      match: classicContract.hash === parallelContract.hash
+    });
+  }
+}
+async function loadSuiteCases(rootPath) {
+  const suitePath = resolve(rootPath, "examples/test_suite/suite.json");
+  const suite = JSON.parse(await readFile2(suitePath, "utf8"));
+  return suite.cases.map((entry) => ({
+    id: entry.id,
+    filePath: resolve(dirname2(suitePath), entry.file),
+    export: false
+  }));
+}
+function performanceWorkloads(rootPath) {
+  const paths = [
+    "examples/test_suite/13_module_library.bushscad",
+    "examples/test_suite/09_assembly_patterns.bushscad",
+    "examples/test_suite/04_solids_and_details.bushscad",
+    "examples/test_suite/12_imported_assets.bushscad",
+    "packages/cli/test/fixtures/parallel-components-p4-loft-benchmark.bushscad",
+    "packages/cli/test/fixtures/parallel-components-p5-reuse.bushscad",
+    "packages/cli/test/fixtures/parallel-p6-native-cut-benchmark.bushscad"
+  ];
+  return paths.map((path) => ({
+    id: basename(path, ".bushscad"),
+    filePath: resolve(rootPath, path),
+    export: path.includes("09_assembly") || path.includes("p6-native-cut")
+  }));
+}
+function positiveInteger(value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1)
+    throw new Error(`Expected a positive integer, received '${value}'.`);
+  return parsed;
+}
+function readArg(name, fallback) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] ?? fallback : fallback;
+}
+function progress(message) {
+  process.stderr.write(`[P7] ${message}
+`);
+}
+void run().catch((error) => {
+  process.stderr.write(
+    `${error instanceof Error ? error.stack : String(error)}
+`
+  );
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,50 @@
-{
-  "name": "@bushscad/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+    "name": "@bushscad/cli",
+    "version": "0.3.1",
+    "type": "module",
+    "bin": {
+        "bushscad": "./dist/index.js"
+    },
+    "exports": {
+        ".": "./dist/index.js",
+        "./protocol": "./src/dto/index.ts"
+    },
+    "scripts": {
+        "build": "node scripts/build.mjs",
+        "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+        "test": "vitest run",
+        "prepack": "npm run build"
+    },
+    "dependencies": {
+        "@bushscad/compiler": "^0.3.0",
+        "@bushscad/ir": "^0.3.0",
+        "opencascade.js": ">=2.0.0-0"
+    },
+    "devDependencies": {
+        "esbuild": "^0.28.0",
+        "typescript": "^5.4.0",
+        "vitest": "^4.1.5"
+    },
+    "license": "Apache-2.0",
+    "description": "The command-line compiler and service interface for BushSCAD. The published package includes the bundled runtime and fonts; OpenCascade is installed as a package dependency.",
+    "homepage": "https://bushscad.byaidan.com/",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/AidanBoissonneault/BushSCAD-Language.git",
+        "directory": "packages/cli"
+    },
+    "bugs": {
+        "url": "https://github.com/AidanBoissonneault/BushSCAD-Language/issues"
+    },
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "files": [
+        "dist/**",
+        "src/dto/**",
+        "src/service/parallel/worker-protocol.ts",
+        "LICENSE",
+        "README.md"
+    ]
+}

package/src/dto/bufferDto.ts

@@ -0,0 +1,22 @@
+/**
+ * @author Aidan Boissonneault
+ * @file bufferDto.ts
+ * @purpose Provides buffer dto behavior for the dto in cli package.
+ * @last-edited October 6, 2026
+ */
+
+import type { BufferDto } from './types.js';
+
+/**
+ * Converts binary export buffers into base64 DTO format.
+ * Buffers must be serialized safely for IPC/service transport.
+ */
+export function bufferToDto(buffer: {
+  name: string;
+  data: ArrayBuffer;
+}): BufferDto {
+  return {
+    name: buffer.name,
+    dataBase64: Buffer.from(buffer.data).toString('base64'),
+  };
+}