@aipper/aiws 0.0.23 → 0.0.25

package/src/commands/change-status-context.js

@@ -0,0 +1,202 @@
+import path from "node:path";
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {{
+ *   currentBranch: (gitRoot: string) => Promise<string>,
+ *   listGitWorktrees: (gitRoot: string) => Promise<Array<{ worktree: string, branch: string }>>,
+ *   pathExists: (path: string) => Promise<boolean>,
+ *   isGitRepository: (path: string) => Promise<boolean>,
+ *   inferChangeIdFromBranch: (branch: string) => string
+ * }} deps
+ */
+export async function resolveChangeStatusContext(gitRoot, changeId, deps) {
+  const rootBranch = await deps.currentBranch(gitRoot);
+  /** @type {Array<{ worktree: string, branch: string }>} */
+  let worktrees = [];
+  try {
+    worktrees = await deps.listGitWorktrees(gitRoot);
+  } catch {
+    worktrees = [];
+  }
+
+  const changeRef = `refs/heads/change/${changeId}`;
+  const changeWorktree = worktrees.find((worktree) => String(worktree.branch || "") === changeRef)?.worktree || "";
+  const rootWorktree = path.resolve(gitRoot);
+  let contextWorktree = rootWorktree;
+  let source = "current_worktree";
+  let warning = "";
+  if (changeWorktree && path.resolve(changeWorktree) !== rootWorktree) {
+    const candidate = path.resolve(changeWorktree);
+    const candidateExists = await deps.pathExists(candidate);
+    const candidateReady = candidateExists ? await deps.isGitRepository(candidate) : false;
+    if (candidateReady) {
+      contextWorktree = candidate;
+      source = "change_worktree";
+    } else {
+      warning = `stale change worktree metadata: ${candidate} (run \`git worktree prune\`)`;
+    }
+  }
+  const contextBranch = await deps.currentBranch(contextWorktree);
+  const inferred = deps.inferChangeIdFromBranch(contextBranch);
+
+  return {
+    worktree: contextWorktree,
+    branch: contextBranch,
+    branchMatchesChange: inferred === changeId,
+    source,
+    warning,
+    currentWorktree: rootWorktree,
+    currentBranch: rootBranch,
+    changeWorktree: changeWorktree ? path.resolve(changeWorktree) : "",
+  };
+}
+
+/**
+ * @param {string} changeDir
+ * @param {{ pathExists: (path: string) => Promise<boolean>, readText: (path: string) => Promise<string> }} deps
+ */
+export async function readChangeMetrics(changeDir, deps) {
+  const metricsAbs = path.join(changeDir, "metrics.json");
+  if (!(await deps.pathExists(metricsAbs))) return { state: "missing", abs: metricsAbs, events: [] };
+  try {
+    const parsed = JSON.parse(await deps.readText(metricsAbs));
+    const events = Array.isArray(parsed?.events) ? parsed.events : [];
+    return { state: "ok", abs: metricsAbs, events };
+  } catch {
+    return { state: "invalid", abs: metricsAbs, events: [] };
+  }
+}
+
+const FINISH_DONE_COMPLETED_CLEANUPS = new Set([
+  "removed",
+  "pruned-missing",
+  "skipped:no_separate_change_worktree",
+  "skipped:current_worktree",
+]);
+
+/**
+ * @param {any} ev
+ * @returns {{ state: string, reason: string, eventType: string } | null}
+ */
+function classifyFinishLifecycleEvent(ev) {
+  const type = String(ev?.type || "").trim();
+  if (!type) return null;
+  if (type === "finish_local") {
+    return { state: "local", reason: "", eventType: type };
+  }
+  if (type === "finish_failed") {
+    return { state: "failed", reason: String(ev?.payload?.error || ""), eventType: type };
+  }
+  if (type === "finish_cleanup_pending") {
+    return {
+      state: "cleanup_pending",
+      reason: String(ev?.payload?.reason || ev?.payload?.cleanup || ""),
+      eventType: type,
+    };
+  }
+  if (type === "finish") {
+    return { state: "done", reason: "", eventType: type };
+  }
+  if (type !== "finish_done") return null;
+
+  const payload = ev?.payload && typeof ev.payload === "object" ? ev.payload : null;
+  const hasPush = payload ? Object.prototype.hasOwnProperty.call(payload, "push") : false;
+  const pushCompleted = hasPush ? payload?.push === true : null;
+  const cleanup = String(payload?.cleanup || "").trim();
+
+  if (pushCompleted === false || cleanup === "not_requested") {
+    return { state: "local", reason: "", eventType: type };
+  }
+  if (!cleanup) {
+    return { state: "done", reason: "", eventType: type };
+  }
+  if (FINISH_DONE_COMPLETED_CLEANUPS.has(cleanup)) {
+    return { state: "done", reason: "", eventType: type };
+  }
+
+  return {
+    state: "cleanup_pending",
+    reason: cleanup.startsWith("skipped:") ? cleanup.slice("skipped:".length) : cleanup,
+    eventType: type,
+  };
+}
+
+/**
+ * @param {{ state: string, events: any[] }} metrics
+ */
+export function summarizeLifecycleSignals(metrics) {
+  const events = Array.isArray(metrics?.events) ? metrics.events : [];
+  /** @type {Record<string, number>} */
+  const eventCounts = {};
+  let finishState = "";
+  let finishStateReason = "";
+  let finishStateEventType = "";
+  for (const ev of events) {
+    const type = String(ev?.type || "").trim();
+    if (!type) continue;
+    eventCounts[type] = (eventCounts[type] || 0) + 1;
+    const finishIsTerminal = finishState === "done";
+    if (finishIsTerminal && type !== "finish_done" && type !== "finish") continue;
+    const classified = classifyFinishLifecycleEvent(ev);
+    if (!classified) continue;
+    finishState = classified.state;
+    finishStateReason = classified.reason;
+    finishStateEventType = classified.eventType;
+  }
+
+  const latest = events.length > 0 ? events[events.length - 1] : null;
+  const validateEvents = events.filter((ev) => ev?.type === "validate");
+  const latestStrictValidate = [...validateEvents].reverse().find((ev) => ev?.payload?.strict === true) || null;
+  const latestStrictScopeValidate =
+    [...validateEvents].reverse().find((ev) => ev?.payload?.strict === true && ev?.payload?.check_scope === true) || null;
+  const strictScopeValidateRuns = validateEvents.filter((ev) => ev?.payload?.strict === true && ev?.payload?.check_scope === true).length;
+
+  return {
+    metricsState: String(metrics?.state || "missing"),
+    latestEventType: String(latest?.type || ""),
+    eventCounts,
+    evidenceRuns: eventCounts.evidence || 0,
+    finishRuns: (eventCounts.finish || 0) + (eventCounts.finish_done || 0),
+    finishCleanupPendingReason: finishState === "cleanup_pending" ? finishStateReason : "",
+    finishState,
+    finishStateReason,
+    finishStateEventType,
+    archiveRuns: eventCounts.archive || 0,
+    strictValidatePass: latestStrictValidate ? latestStrictValidate?.payload?.ok === true : false,
+    strictScopeValidateRuns,
+    strictScopeValidatePass: latestStrictScopeValidate ? latestStrictScopeValidate?.payload?.ok === true : false,
+    strictScopeValidateAt: String(latestStrictScopeValidate?.timestamp || ""),
+    strictScopeValidateErrors: Number(latestStrictScopeValidate?.payload?.errors || 0),
+    strictScopeValidateWarnings: Number(latestStrictScopeValidate?.payload?.warnings || 0),
+  };
+}
+
+/**
+ * @param {Record<string, string | null>} curTruth
+ * @param {any} baseline
+ * @returns {{ baselineLabel: string, baselineAt: string, driftFiles: string[] }}
+ */
+export function truthDrift(curTruth, baseline) {
+  /** @type {string[]} */
+  const driftFiles = [];
+
+  const createdTruth = baseline?.base_truth_files && typeof baseline.base_truth_files === "object" ? baseline.base_truth_files : {};
+  const syncedTruth = baseline?.synced_truth_files && typeof baseline.synced_truth_files === "object" ? baseline.synced_truth_files : {};
+  const effective = Object.keys(syncedTruth).length > 0 ? syncedTruth : createdTruth;
+  const baselineLabel = Object.keys(syncedTruth).length > 0 ? "sync" : "creation";
+  const baselineAt = Object.keys(syncedTruth).length > 0 ? String(baseline?.synced_at || "") : String(baseline?.created_at || "");
+
+  for (const [rel, info] of Object.entries(effective || {})) {
+    const baseSha = info && typeof info === "object" ? String(info.sha256 || "") : "";
+    const curSha = curTruth[rel] ?? null;
+    if (curSha == null) {
+      driftFiles.push(rel);
+      continue;
+    }
+    if (baseSha && curSha !== baseSha) driftFiles.push(rel);
+  }
+
+  return { baselineLabel, baselineAt, driftFiles };
+}

package/src/commands/change-validate-entry.js

@@ -0,0 +1,45 @@
+/**
+ * @param {{
+ *   gitRoot: string,
+ *   changeId: string,
+ *   options: { strict: boolean, allowTruthDrift: boolean, checkEvidence: boolean, checkScope: boolean }
+ * }} input
+ * @param {{
+ *   appendMetricsEvent: (gitRoot: string, changeId: string, type: string, payload: any) => Promise<void>,
+ *   validateChangeArtifacts: (gitRoot: string, changeId: string, options: any) => Promise<any>,
+ *   UserError: typeof import("../errors.js").UserError
+ * }} deps
+ */
+export async function runChangeValidateCommand(input, deps) {
+  const { gitRoot, changeId, options } = input;
+  const result = await deps.validateChangeArtifacts(gitRoot, changeId, {
+    strict: options.strict === true,
+    allowTruthDrift: options.allowTruthDrift === true,
+    checkEvidence: options.checkEvidence === true,
+    checkScope: options.checkScope === true,
+  });
+
+  await deps.appendMetricsEvent(gitRoot, changeId, "validate", {
+    ok: result.ok === true,
+    strict: options.strict === true,
+    allow_truth_drift: options.allowTruthDrift === true,
+    check_evidence: options.checkEvidence === true,
+    check_scope: options.checkScope === true,
+    errors: Array.isArray(result.errors) ? result.errors.length : 0,
+    warnings: Array.isArray(result.warnings) ? result.warnings.length : 0,
+    exit_code: result.exitCode,
+  });
+
+  if (result.raw) {
+    return {
+      output: result.ok ? `ok: change validated (${changeId})\n` : "",
+      stderr: result.raw + "\n",
+      errorToThrow: result.ok ? null : new deps.UserError(""),
+    };
+  }
+  return {
+    output: result.ok ? `ok: change validated (${changeId})\n` : "",
+    stderr: "",
+    errorToThrow: result.ok ? null : new deps.UserError(""),
+  };
+}

package/src/commands/change-validate.js

@@ -0,0 +1,127 @@
+function parseChangeCheckerOutput(stdout, stderr) {
+  const text = [String(stdout || ""), String(stderr || "")].filter(Boolean).join("\n");
+  /** @type {string[]} */
+  const errors = [];
+  /** @type {string[]} */
+  const warnings = [];
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (line.startsWith("error: ")) errors.push(line.replace(/^error:\s*/, ""));
+    else if (line.startsWith("warn: ")) warnings.push(line.replace(/^warn:\s*/, ""));
+  }
+  return { errors, warnings, raw: text.trim() };
+}
+
+function classifyCheckMessage(msg) {
+  const s = String(msg || "");
+  if (s.includes("truth file") || s.includes("truth drift") || s.includes("allow-truth-drift")) return "truth_drift";
+  if (s.includes("WS:TODO") || s.includes("unrendered template placeholders")) return "placeholders";
+  if (s.includes("missing:") || s.includes("empty:") || s.includes("Missing change dir")) return "missing_files";
+  if (
+    s.includes("Change_ID") ||
+    s.includes("Req_ID") ||
+    s.includes("Problem_ID") ||
+    s.includes("Contract_Row") ||
+    s.includes("Plan_File") ||
+    s.includes("Evidence_Path")
+  ) {
+    return "bindings";
+  }
+  if (s.includes("scope check") || s.includes("out-of-scope")) return "scope_gate";
+  if (
+    s.includes("finish gate") ||
+    s.includes("validate stamp") ||
+    s.includes("verify-before-complete") ||
+    s.includes("spec review") ||
+    s.includes("quality review")
+  ) {
+    return "finish_gate";
+  }
+  if (
+    s.includes("missing required sections") ||
+    s.includes("has empty sections") ||
+    s.includes("Plan section") ||
+    s.includes("Verify section") ||
+    s.includes("scope is too broad") ||
+    s.includes("too abstract")
+  ) {
+    return "plan_quality";
+  }
+  return "other";
+}
+
+function groupCheckMessages(errors, warnings) {
+  const groups = {
+    truth_drift: { errors: [], warnings: [] },
+    missing_files: { errors: [], warnings: [] },
+    placeholders: { errors: [], warnings: [] },
+    bindings: { errors: [], warnings: [] },
+    scope_gate: { errors: [], warnings: [] },
+    finish_gate: { errors: [], warnings: [] },
+    plan_quality: { errors: [], warnings: [] },
+    other: { errors: [], warnings: [] },
+  };
+
+  for (const message of errors || []) {
+    const group = classifyCheckMessage(message);
+    groups[group].errors.push(message);
+  }
+  for (const message of warnings || []) {
+    const group = classifyCheckMessage(message);
+    groups[group].warnings.push(message);
+  }
+  return groups;
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {{ strict: boolean, allowTruthDrift: boolean, checkEvidence?: boolean, checkScope?: boolean }} options
+ * @param {{
+ *   assertValidChangeId: (changeId: string) => void,
+ *   collectFinishGateErrors: (changeId: string, reviewGates: any) => string[],
+ *   computeChangeStatus: (gitRoot: string, changeId: string) => Promise<any>,
+ *   ensureTruthFiles: (gitRoot: string) => Promise<void>,
+ *   resolveWsChangeChecker: (gitRoot: string) => Promise<{ args: string[] }>,
+ *   runPython: (cwd: string, args: string[]) => Promise<{ code: number, stdout: string, stderr: string }>
+ * }} deps
+ */
+export async function validateChangeArtifacts(gitRoot, changeId, options, deps) {
+  deps.assertValidChangeId(changeId);
+  await deps.ensureTruthFiles(gitRoot);
+
+  const checker = await deps.resolveWsChangeChecker(gitRoot);
+  const args = [...checker.args, "--workspace-root", gitRoot, "--change-id", changeId];
+  if (options.strict) args.push("--strict");
+  if (options.allowTruthDrift) args.push("--allow-truth-drift");
+  if (options.checkEvidence) args.push("--check-evidence");
+  if (options.checkScope) args.push("--check-scope");
+
+  const res = await deps.runPython(gitRoot, ["-u", ...args]);
+  const parsed = parseChangeCheckerOutput(res.stdout, res.stderr);
+  const errors = [...parsed.errors];
+  const warnings = [...parsed.warnings];
+
+  if (options.checkEvidence === true) {
+    const status = await deps.computeChangeStatus(gitRoot, changeId);
+    errors.push(...deps.collectFinishGateErrors(changeId, status.reviewGates));
+  }
+
+  const rawLines = [];
+  if (parsed.raw) rawLines.push(parsed.raw);
+  for (const message of errors.slice(parsed.errors.length)) rawLines.push(`error: ${message}`);
+  for (const message of warnings.slice(parsed.warnings.length)) rawLines.push(`warn: ${message}`);
+  const exitCode = res.code === 0 && errors.length > 0 ? 1 : res.code;
+  return {
+    ok: exitCode === 0,
+    changeId,
+    strict: options.strict === true,
+    allowTruthDrift: options.allowTruthDrift === true,
+    exitCode,
+    errors,
+    warnings,
+    groups: groupCheckMessages(errors, warnings),
+    raw: rawLines.filter(Boolean).join("\n").trim(),
+  };
+}