@smallpen/cli 0.1.0-alpha.13 → 0.1.0-alpha.15

package/bin/command-contract.mjs

@@ -28,6 +28,11 @@ const integer = (option, description, extra = {}) =>
   });
 
 const PARAMETERS = {
+  targetTimeout: integer(
+    "--target-timeout",
+    "Maximum milliseconds per validation target, including native layout; progress uses JSON lines on stderr and interruption returns partial coverage",
+    { minimum: 1, maximum: 600_000, default: 30_000 },
+  ),
   stdout: flag(
     "--stdout",
     "Print large results to stdout instead of saving a temporary result file",
@@ -488,7 +493,7 @@ export const COMMAND_CONTRACTS = {
   ),
   validate: command(
     "Validate canonical data and report text/layout/contrast issues and coverage; a page checks every version and a component every variant unless one is named",
-    [...TARGET, ...VIEW, "designSystem", "limit", "offset"],
+    [...TARGET, ...VIEW, "designSystem", "limit", "offset", "targetTimeout"],
     { conflicts: { designSystem: ["page", "component"] } },
   ),
   inspect: command("Read package identity, revision and counts"),

package/bin/design-output.mjs

@@ -261,7 +261,7 @@ export function componentLookup(workspace) {
   }
   return (reference) =>
     reference
-      ? (sets.get(`${reference.packageId}\0${reference.assetId}`) ?? sets.get(reference.assetId))
+      ? (reference.packageId ? sets.get(`${reference.packageId}\0${reference.assetId}`) : sets.get(reference.assetId))
       : undefined;
 }
 
@@ -468,7 +468,8 @@ function variantPairs(selection, set) {
 // Node IDs show only with full: agents read and edit by name.
 export function outlineTree(tree, projection, { full = false, components, ids = full } = {}) {
   const lines = [];
-  const size = (node) => `${Math.round(node.bounds.width)}×${Math.round(node.bounds.height)}`;
+  const dimension = value => Number.isFinite(value) ? Math.round(value) : "?";
+  const size = (node) => `${dimension(node.bounds?.width)}×${dimension(node.bounds?.height)}`;
   const describe = (node) => {
     const raw = projection.nodes[node.id];
     const reference = instanceReference(node, projection);

package/bin/schema.mjs

@@ -765,8 +765,8 @@ function setTopic(command) {
     command,
     fields: {
       set: "FIELD=VALUE, repeatable; VALUE is JSON (320, [8,16], {\"Style\":\"ghost\"}, true) or plain text; {token.path} binds a Token",
-      element: "fields: width, height (number, fill, hug), fill, stroke, radius, opacity, shadow, visible, rotation, margin, min/max sizes; texts: text, color, font, fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, textTransform, textDecoration, textAlign; containers: layout (row|column|none), gap, padding, align, justify",
-      copy: "a copy of a component: props, text {\"Element\": \"text\"}, set {\"Element.field\": value}, width, height (numbers), visible, opacity",
+      element: "fields: width, height (number, px, Token, fill, hug), fill, stroke, radius, opacity, shadow, visible, rotation, margin, min/max sizes; texts: text, color, font, fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, textTransform, textDecoration, textAlign; containers: layout (row|column|none), gap, padding, align, justify",
+      copy: "a copy of a component: props, text {\"Element\": \"text\"}, set {\"Element.field\": value}, width/height (numbers, px, Tokens, hug, or fill in a row/column parent), visible, opacity. Sizes inside set (Element.width/height) take numbers or Tokens",
       itself: "without --element: the page version (or the variant) itself, for example its width and height",
     },
     example: [

package/bin/smallpen.mjs

@@ -99,7 +99,9 @@ import {
   staleInstanceDiagnostics,
 } from "@smallpen/core";
 import {
+  BATCH_HISTORY_LIMITS,
   applyOperationBatch,
+  batchHistoryPath,
   defaultLibraryCacheRoot,
   fontVariantName,
   importDraft,
@@ -169,6 +171,8 @@ import {
   viewSummary,
 } from "./read-output.mjs";
 
+import { runValidationJobs } from "./validation-runner.mjs";
+
 let writeState = "not-applied";
 async function trackedWrite(action) {
   writeState = "unknown";
@@ -438,6 +442,8 @@ function printJson(value) {
       "libraryRevisions",
       "batchId",
       "alreadyApplied",
+      "history",
+      "historyWindow",
       "changed",
       "dryRun",
       "noChange",
@@ -1181,7 +1187,7 @@ async function writeReply(result, args) {
               ],
             }
           : {
-              ledgerPath: `${resolve(args[1])}.batches.json`,
+              ledgerPath: await batchHistoryPath(resolve(args[1])),
               batchId: result.batchId,
             }),
       };
@@ -1973,8 +1979,11 @@ async function designCommand(packagePath, args, override) {
   };
 }
 
-async function validationDesigns(workspace, args) {
-  if (!flag(args, "--all")) return [await designForCommand(workspace, args)];
+async function validationJobs(workspace, args) {
+  if (!flag(args, "--all")) {
+    const design = await designForCommand(workspace, args);
+    return [{ design, selection: design.selection }];
+  }
   const componentId = option(args, "--component-id"),
     screenId = option(args, "--screen-id");
   if (!componentId && !screenId)
@@ -1992,11 +2001,9 @@ async function validationDesigns(workspace, args) {
       (snapshot) => snapshot?.manifest.packageId === first.selection.packageId,
     );
     return owner.domain.componentSets.get(componentId).variants.map((variant) =>
-      selectedDesign(workspace, designSelector(args), {
-        componentId,
-        packageId: first.selection.packageId,
-        variantId: variant.id,
-      }),
+      ({ selector: designSelector(args),
+        target: { componentId, packageId: first.selection.packageId, variantId: variant.id },
+        selection: { componentId, packageId: first.selection.packageId, variantId: variant.id } }),
     );
   }
   const screen = workspace.product.manifest.entries.screens
@@ -2005,11 +2012,8 @@ async function validationDesigns(workspace, args) {
   if (!screen)
     throw new SmallPenError("missing_screen", `No Screen ${screenId}`);
   return screen.presentations.map((presentation) =>
-    selectedDesign(workspace, {
-      ...designSelector(args),
-      screenId,
-      presentationId: presentation.id,
-    }),
+    ({ selector: { ...designSelector(args), screenId, presentationId: presentation.id },
+      selection: { screenId, presentationId: presentation.id } }),
   );
 }
 
@@ -3235,6 +3239,13 @@ async function changesCommand(packagePath, args) {
   const revisions = {
     revision: product.revision,
     ...(foundation ? { foundationRevision: foundation.revision } : {}),
+    historyWindow: packages.map((snapshot, index) => ({
+      packageId: snapshot.manifest.packageId,
+      ...BATCH_HISTORY_LIMITS,
+      retainedBatches: histories[index].length,
+      oldestRevision: histories[index][0]?.baseRevision,
+      newestRevision: histories[index].at(-1)?.revision,
+    })),
   };
   if (since === undefined) {
     const limit = integerOption(args, "--limit") || 10;
@@ -3265,6 +3276,7 @@ async function changesCommand(packagePath, args) {
       "unknown_revision",
       "This revision is not in the recorded history; read the current design with view instead",
       {
+        historyWindow: revisions.historyWindow,
         nextOperations: [
           { argv: ["changes", packagePath, "--json"], operation: "smallpen.changes" },
           { argv: ["view", packagePath, "--as", "text", "--json"], operation: "smallpen.view" },
@@ -3570,30 +3582,27 @@ async function validateWholePackage(packagePath, args, workspace, resolution, on
   };
   const issues = [], checked = [], skipped = [], hints = [];
   let unreadable = 0;
+  const jobs = [];
   for (const target of targets) {
     try {
-      const report = await validateTargets(workspace, ["validate", packagePath, ...target.ids, ...pass]);
-      for (const issue of report.issues ?? []) {
-        const named = selectionNames(workspace, issue.target ?? {});
-        const at = [named.page ?? named.component ?? target.where, named.platform ?? named.variant].filter(Boolean);
-        const { target: _target, ...rest } = issue;
-        issues.push({ target: at.length > 1 ? `${at[0]} (${at[1]})` : at[0], ...rest });
-      }
-      checked.push(...(report.coverage?.targets ?? []));
-      skipped.push(...(report.coverage?.skipped ?? []).map((skip) => ({ ...skip, label: targetLabel(skip.target) })));
-      for (const hint of report.hints ?? [])
-        if (!hints.some((other) => JSON.stringify(other) === JSON.stringify(hint))) hints.push(hint);
+      jobs.push(...await validationJobs(workspace, ["validate", packagePath, ...target.ids, ...pass]));
     } catch (error) {
       unreadable += 1;
-      issues.push({
-        target: target.where,
-        code: error?.code ?? "unreadable_target",
-        severity: "error",
-        check: "read",
-        message: `${target.where} cannot be drawn: ${error?.message ?? error}`,
-      });
+      issues.push({ target: target.where, code: error.code ?? "unreadable_target", severity: "error", check: "read", message: error.message });
     }
   }
+  const outcome = await runChecks(workspace, jobs, args);
+  for (const result of outcome.results) {
+    const report = validationResult(result);
+    for (const issue of report.issues ?? []) {
+      const { target: _target, ...rest } = issue;
+      issues.push({ target: validationLabel(workspace, report.selection), ...rest });
+    }
+    if (result.report) checked.push(report.selection);
+    skipped.push(...(report.coverage?.skipped ?? []).map(skip => ({ ...skip, target: report.selection, label: validationLabel(workspace, report.selection) })));
+    for (const hint of report.hints ?? [])
+      if (!hints.some(other => JSON.stringify(other) === JSON.stringify(hint))) hints.push(hint);
+  }
   // Layout limits belong to the tool, with full diagnostics kept separately
   // from design issues and every skipped layout check counted in coverage.
   const limits = issues.filter((issue) => issue.code === "layout_projection_partial");
@@ -3604,9 +3613,9 @@ async function validateWholePackage(packagePath, args, workspace, resolution, on
   return {
     packageId: product.manifest.packageId,
     ...workspaceRevisions(product, workspace.foundation, workspace.libraries),
-    status: unreadable ? "invalid" : "valid",
+    status: outcome.interrupted ? "interrupted" : outcome.results.some(result => result.error) ? "partial" : unreadable ? "invalid" : "valid",
     dataStatus: unreadable ? "invalid" : "valid",
-    visualStatus: design.length ? "issues" : "no-issues-found",
+    visualStatus: design.length ? "issues" : outcome.interrupted ? "partial" : "no-issues-found",
     issueCount: design.length,
     issues: full ? design : page.items,
     ...(full ? {} : { page: page.page }),
@@ -3618,7 +3627,8 @@ async function validateWholePackage(packagePath, args, workspace, resolution, on
     selection: { themes: themeSettings(workspace).selection.themes },
     coverage: {
       // Every target drawn and every check run on it.
-      complete: unreadable === 0 && notChecked.length === 0,
+      complete: unreadable === 0 && notChecked.length === 0 && !outcome.interrupted,
+      ...executionCoverage(outcome),
       targetCount: checked.length,
       // By name, short: "Home (desktop)", "Button (Style=primary)".
       // Pages by version; components as one line each unless --full.
@@ -3763,48 +3773,63 @@ function projectSummary(snapshot) {
   };
 }
 
-// Every check of the selected targets, untruncated.
-async function validateTargets(workspace, args) {
-  const designs = await validationDesigns(workspace, args);
-  const reports = [];
-  for (const design of designs) {
-    const report = {
-      ...(await validateDesign(workspace, design)),
-      selection: design.selection,
-    };
-    // A skipped check names its element; its path is a projected node id.
-    const nodes = design.projection?.nodes ?? {};
-    report.coverage.skipped = (report.coverage.skipped ?? []).map((skip) => {
-      const at = typeof skip.path === "string" && Object.hasOwn(nodes, skip.path) ? skip.path
-        : typeof skip.nodeId === "string" && Object.hasOwn(nodes, skip.nodeId) ? skip.nodeId : undefined;
-      if (at === undefined) return skip;
-      const { path: _path, ...rest } = skip;
-      return { ...rest, element: elementPath(nodes, design.projection.rootId, at) || nodes[at].name };
+function validationLabel(workspace, selection) {
+  const named = selectionNames(workspace, selection);
+  const parts = [named.page ?? named.component, named.platform ?? named.variant].filter(Boolean);
+  return parts.length > 1 ? `${parts[0]} (${parts[1]})` : parts[0] ?? "design";
+}
+
+async function runChecks(workspace, jobs, args) {
+  const controller = new AbortController();
+  const interrupt = () => controller.abort();
+  process.once("SIGINT", interrupt);
+  process.once("SIGTERM", interrupt);
+  try {
+    const outcome = await runValidationJobs(workspace, jobs.map(job => ({
+      ...job, label: validationLabel(workspace, job.selection),
+    })), {
+      timeoutMs: Number(option(args, "--target-timeout") ?? 30_000),
+      signal: controller.signal,
+      progress: event => process.stderr.write(JSON.stringify(event) + "\n"),
     });
-    if (design.selection.screenId) {
-      const flow = prototypeConnections(
-        workspace.product,
-        design.selection,
-        {
-          ...workspace,
-          context: design.projection.context,
-          initialProjection: design.projection,
-        },
-      );
-      report.issues.push(
-        ...flow.issues.map((issue) => ({
-          ...issue,
-          check: "prototype-connections",
-        })),
-      );
-      report.coverage.checks.push("prototype-connections");
-      report.coverage.connectionCount = flow.connections.length;
-    }
-    reports.push(report);
+    if (outcome.interrupted) process.exitCode = 130;
+    return outcome;
+  } finally {
+    process.removeListener("SIGINT", interrupt);
+    process.removeListener("SIGTERM", interrupt);
   }
+}
+
+function executionCoverage(outcome) {
+  return {
+    totalTargetCount: outcome.total,
+    completedTargetCount: outcome.results.length,
+    failedTargetCount: outcome.results.filter(result => result.error).length,
+    remainingCount: outcome.remaining.length,
+    remaining: outcome.remaining,
+    interrupted: outcome.interrupted,
+  };
+}
+
+function validationResult({ job, report, error }) {
+  return report ?? {
+    selection: job.selection,
+    issues: [{ ...error, severity: "error", check: "execution" }],
+    coverage: { complete: false, nodeCount: 0, visibleNodeCount: 0, checks: [],
+      skipped: [{ check: "native-layout", reason: error.message, code: error.code, target: job.selection }] },
+  };
+}
+
+// Every check of the selected targets, untruncated.
+async function validateTargets(workspace, args) {
+  const outcome = await runChecks(workspace, await validationJobs(workspace, args), args);
+  const reports = outcome.results.map(validationResult);
+  const empty = { issues: [], coverage: { complete: false, checks: [], skipped: [], nodeCount: 0, visibleNodeCount: 0 } };
   const all = flag(args, "--all");
   const visual = {
-    ...reports[0],
+    ...(reports[0] ?? empty),
+    ...(outcome.interrupted ? { status: "interrupted", visualStatus: "partial" }
+      : outcome.results.some(result => result.error) ? { status: "partial", visualStatus: "partial" } : {}),
     ...(reports.some((report) => report.hints?.length) ? { hints: reports.flatMap((report) => report.hints ?? []) } : {}),
     issues: reports.flatMap((report) =>
       report.issues.map((issue) =>
@@ -3812,7 +3837,9 @@ async function validateTargets(workspace, args) {
       ),
     ),
     coverage: {
-      ...reports[0].coverage,
+      ...(reports[0]?.coverage ?? empty.coverage),
+      ...executionCoverage(outcome),
+      complete: !outcome.interrupted && reports.every(report => report.coverage.complete),
       targets: reports.map((report) => ({ ...selectionNames(workspace, report.selection), ...report.selection })),
       targetCount: reports.length,
       nodeCount: reports.reduce(
@@ -3859,7 +3886,7 @@ async function validateTargets(workspace, args) {
       ...(option(args, "--component-id")
         ? {
             componentId: option(args, "--component-id"),
-            packageId: reports[0].selection.packageId,
+            packageId: reports[0]?.selection.packageId,
           }
         : { screenId: option(args, "--screen-id") }),
     };

package/bin/validation-runner.mjs

@@ -0,0 +1,62 @@
+import { Worker } from "node:worker_threads";
+
+// A persistent worker reuses the shared App runtime. Terminating the worker
+// also stops synchronous WASM; a Promise timeout in this process cannot.
+export async function runValidationJobs(workspace, jobs, {
+  timeoutMs = 30_000, signal, progress = () => {},
+  workerUrl = new URL("./validation-worker.mjs", import.meta.url),
+} = {}) {
+  const results = [];
+  let worker;
+  const emit = (event, extra = {}) => progress({
+    type: "validation-progress", event, total: jobs.length, completed: results.length, ...extra,
+  });
+  emit("start");
+  try {
+    for (const job of jobs) {
+      if (signal?.aborted) break;
+      emit("target", { target: job.label });
+      worker ??= new Worker(workerUrl, { workerData: workspace });
+      const result = await new Promise(resolve => {
+        let finished = false;
+        const finish = value => {
+          if (finished) return;
+          finished = true;
+          clearTimeout(timer);
+          worker.off("message", onMessage);
+          worker.off("error", onError);
+          worker.off("exit", onExit);
+          signal?.removeEventListener("abort", onAbort);
+          resolve(value);
+        };
+        const onMessage = value => finish(value);
+        const onError = error => finish({ error: { code: "validation_worker_failed", message: error.message }, restart: true });
+        const onExit = code => onError(new Error(`Validation worker exited (${code})`));
+        const onAbort = () => finish({ interrupted: true, restart: true });
+        const timer = setTimeout(() => finish({ error: {
+          code: "validation_target_timeout", message: `Target exceeded ${timeoutMs}ms`,
+          details: { timeoutMs, target: job.label, selection: job.selection },
+        }, restart: true }), timeoutMs);
+        worker.once("message", onMessage);
+        worker.once("error", onError);
+        worker.once("exit", onExit);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted) onAbort();
+        else worker.postMessage(job);
+      });
+      if (result.restart) {
+        await worker.terminate();
+        worker = undefined;
+      }
+      if (result.interrupted) break;
+      results.push({ job, ...result });
+      emit("completed", { target: job.label, status: result.error ? result.error.code : "checked" });
+    }
+  } finally {
+    await worker?.terminate();
+  }
+  const remaining = jobs.slice(results.length).map(job => ({ target: job.label, selection: job.selection }));
+  const interrupted = Boolean(signal?.aborted);
+  emit(interrupted ? "interrupted" : "finished", { remaining: remaining.length });
+  return { results, interrupted, remaining, total: jobs.length };
+}

package/bin/validation-worker.mjs

@@ -0,0 +1,29 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { elementPath, prototypeConnections } from "@smallpen/core";
+import { selectedDesign, validateDesign } from "./design-output.mjs";
+
+const workspace = workerData;
+parentPort.on("message", async (job) => {
+  try {
+    const design = job.design ?? selectedDesign(workspace, job.selector, job.target);
+    const report = { ...(await validateDesign(workspace, design)), selection: design.selection };
+    const nodes = design.projection.nodes;
+    report.coverage.skipped = (report.coverage.skipped ?? []).map(skip => {
+      const at = [skip.path, skip.nodeId].find(id => typeof id === "string" && Object.hasOwn(nodes, id));
+      if (!at) return skip;
+      const { path: _path, ...rest } = skip;
+      return { ...rest, element: elementPath(nodes, design.projection.rootId, at) || nodes[at].name };
+    });
+    if (design.selection.screenId) {
+      const flow = prototypeConnections(workspace.product, design.selection, {
+        ...workspace, context: design.projection.context, initialProjection: design.projection,
+      });
+      report.issues.push(...flow.issues.map(issue => ({ ...issue, check: "prototype-connections" })));
+      report.coverage.checks.push("prototype-connections");
+      report.coverage.connectionCount = flow.connections.length;
+    }
+    parentPort.postMessage({ report });
+  } catch (error) {
+    parentPort.postMessage({ error: { code: error.code ?? "unreadable_target", message: error.message, details: error.details } });
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smallpen/cli",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.15",
   "publishConfig": {
     "access": "public"
   },
@@ -15,8 +15,8 @@
     "bin"
   ],
   "dependencies": {
-    "@smallpen/core": "0.1.0-alpha.13",
-    "@smallpen/local-package": "0.1.0-alpha.13"
+    "@smallpen/core": "0.1.0-alpha.15",
+    "@smallpen/local-package": "0.1.0-alpha.15"
   },
   "repository": {
     "type": "git",