@aipper/aiws 0.0.24 → 0.0.25

package/src/commands/change-evidence.js

@@ -0,0 +1,338 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { pathExists } from "../fs.js";
+
+/**
+ * @param {string} input
+ */
+function normalizeSlashes(input) {
+  return String(input || "").replaceAll("\\", "/");
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} absPath
+ */
+export function relFromRoot(gitRoot, absPath) {
+  return normalizeSlashes(path.relative(gitRoot, absPath));
+}
+
+/**
+ * @param {string} absDir
+ * @param {{ maxDepth?: number, maxFiles?: number }} [options]
+ * @returns {Promise<string[]>}
+ */
+async function listFilesRecursive(absDir, options) {
+  const maxDepth = Number(options?.maxDepth ?? 4);
+  const maxFiles = Number(options?.maxFiles ?? 200);
+  /** @type {string[]} */
+  const out = [];
+
+  /** @param {string} curAbs @param {number} depth */
+  async function walk(curAbs, depth) {
+    if (depth > maxDepth) return;
+    let entries = [];
+    try {
+      entries = await fs.readdir(curAbs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (out.length >= maxFiles) return;
+      const nextAbs = path.join(curAbs, entry.name);
+      if (entry.isDirectory()) {
+        await walk(nextAbs, depth + 1);
+        continue;
+      }
+      if (entry.isFile()) out.push(nextAbs);
+    }
+  }
+
+  if (!(await pathExists(absDir))) return out;
+  await walk(absDir, 0);
+  return out;
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeDir
+ */
+export async function collectCollaborationArtifacts(gitRoot, changeDir) {
+  const groups = [
+    ["analysis", "analysis"],
+    ["patches", "patches"],
+    ["review", "review"],
+    ["evidence", "evidence"],
+  ];
+
+  /** @type {Record<string, { label: string, dir: string, exists: boolean, count: number, files: string[], truncated: boolean }>} */
+  const dirs = {};
+  const counts = {
+    analysis: 0,
+    patches: 0,
+    review: 0,
+    evidence: 0,
+    total: 0,
+  };
+
+  for (const [key, label] of groups) {
+    const abs = path.join(changeDir, key);
+    const exists = await pathExists(abs);
+    const filesAbs = exists ? await listFilesRecursive(abs, { maxDepth: 4, maxFiles: 200 }) : [];
+    const files = filesAbs.map((item) => relFromRoot(gitRoot, item));
+    dirs[key] = {
+      label,
+      dir: relFromRoot(gitRoot, abs),
+      exists,
+      count: files.length,
+      files: files.slice(0, 8),
+      truncated: files.length > 8,
+    };
+    counts[key] = files.length;
+    counts.total += files.length;
+  }
+
+  return { dirs, counts };
+}
+
+/**
+ * Evidence_Path is user-declared; we treat it as best-effort hints, not hard gates.
+ *
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {string[]} evidencePaths
+ * @returns {Promise<{
+ *   entries: Array<{rel: string, abs: string, exists: boolean, kind: string, isAbsolute: boolean}>,
+ *   counts: { total: number, exists: number, missing: number, tmp: number, persistent: number, other: number, absolute: number },
+ *   missing: string[]
+ * }>}
+ */
+export async function analyzeEvidencePaths(gitRoot, changeId, evidencePaths) {
+  const changePrefix = `changes/${changeId}/`;
+  const evidencePrefix = `changes/${changeId}/evidence/`;
+  const reviewPrefix = `changes/${changeId}/review/`;
+
+  const entries = await Promise.all(
+    (evidencePaths || []).map(async (raw) => {
+      const rel = String(raw || "").trim();
+      const isAbsolute = path.isAbsolute(rel);
+      const abs = isAbsolute ? rel : path.join(gitRoot, rel);
+      const exists = rel ? await pathExists(abs) : false;
+
+      const relNorm = normalizeSlashes(rel);
+      let kind = "other";
+      if (relNorm.startsWith(".agentdocs/tmp/") || relNorm.startsWith(".agentdocs/")) kind = "tmp";
+      else if (relNorm.startsWith(evidencePrefix) || relNorm.startsWith(reviewPrefix) || relNorm.startsWith(changePrefix)) kind = "persistent";
+
+      return { rel, abs: path.resolve(abs), exists, kind, isAbsolute };
+    }),
+  );
+
+  const missing = entries.filter((entry) => entry.rel && !entry.exists).map((entry) => entry.rel);
+  const counts = {
+    total: entries.filter((entry) => entry.rel).length,
+    exists: entries.filter((entry) => entry.rel && entry.exists).length,
+    missing: missing.length,
+    tmp: entries.filter((entry) => entry.rel && entry.kind === "tmp").length,
+    persistent: entries.filter((entry) => entry.rel && entry.kind === "persistent").length,
+    other: entries.filter((entry) => entry.rel && entry.kind === "other").length,
+    absolute: entries.filter((entry) => entry.rel && entry.isAbsolute).length,
+  };
+
+  return { entries: entries.filter((entry) => entry.rel), counts, missing };
+}
+
+/**
+ * @param {string[]} a
+ * @param {string[]} b
+ */
+export function mergeDeclaredValues(a, b) {
+  const seen = new Set();
+  /** @type {string[]} */
+  const out = [];
+  for (const raw of [...(a || []), ...(b || [])]) {
+    const value = String(raw || "").trim().replace(/^`+/, "").replace(/`+$/, "").trim();
+    if (!value) continue;
+    if (seen.has(value)) continue;
+    seen.add(value);
+    out.push(value);
+  }
+  return out;
+}
+
+/**
+ * @param {string[]} values
+ */
+export function formatDeclaredValues(values) {
+  return (values || []).join(", ");
+}
+
+/**
+ * @param {string} input
+ */
+function escapeRegExp(input) {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Replace or insert a simple "ID: value" style line in Markdown.
+ *
+ * @param {string} text
+ * @param {string[]} labelCandidates
+ * @param {string} value
+ * @param {{ insertAfterLabels?: string[] }} options
+ */
+export function upsertIdLine(text, labelCandidates, value, options) {
+  const src = String(text || "");
+  const labels = Array.isArray(labelCandidates) ? labelCandidates : [];
+  for (const label of labels) {
+    const re = new RegExp(`^(.*${escapeRegExp(label)}.*?[:=][ \\t]*)(.*)$`, "m");
+    const match = re.exec(src);
+    if (!match) continue;
+    const prefix = match[1] || "";
+    const replaced = src.replace(re, `${prefix}${value}`);
+    return { ok: true, changed: replaced !== src, text: replaced, mode: "replaced", label };
+  }
+
+  const insertAfter = Array.isArray(options?.insertAfterLabels) ? options.insertAfterLabels : [];
+  const lines = src.split(/\r?\n/);
+  let idx = 0;
+  for (let i = 0; i < Math.min(lines.length, 80); i++) {
+    const line = lines[i] || "";
+    if (insertAfter.some((label) => line.includes(label))) idx = i + 1;
+  }
+  const insertedLabel = labels[0] || "Evidence_Path";
+  lines.splice(idx, 0, `- ${insertedLabel}: ${value}`);
+  const inserted = lines.join("\n");
+  return { ok: true, changed: inserted !== src, text: inserted, mode: "inserted", label: labels[0] || "" };
+}
+
+/**
+ * Special-case insertion for proposal.md template style.
+ *
+ * @param {string} proposalText
+ * @param {string} value
+ */
+export function upsertProposalEvidencePath(proposalText, value) {
+  const src = String(proposalText || "");
+  const re = new RegExp(`^(.*${escapeRegExp("Evidence_Path")}.*?[:=][ \\t]*)(.*)$`, "m");
+  if (re.test(src)) {
+    const match = re.exec(src);
+    const prefix = match?.[1] || "";
+    const out = src.replace(re, `${prefix}${value}`);
+    return { changed: out !== src, text: out, mode: "replaced" };
+  }
+  const lines = src.split(/\r?\n/);
+  let idx = 0;
+  for (let i = 0; i < Math.min(lines.length, 120); i++) {
+    if ((lines[i] || "").includes("Plan_File")) {
+      idx = i + 1;
+      break;
+    }
+  }
+  lines.splice(idx, 0, `- \`Evidence_Path\` = ${value}`);
+  const inserted = lines.join("\n");
+  return { changed: inserted !== src, text: inserted, mode: "inserted" };
+}
+
+/**
+ * @param {string} changeId
+ */
+export function planVerifyHint(changeId) {
+  return `执行前质量门（优先）：\`aiws change validate ${changeId} --strict\`（AI 工具中等价于 \`$ws-plan-verify\`）`;
+}
+
+/**
+ * @param {string} absDir
+ * @param {(fileName: string) => boolean} predicate
+ */
+export async function findLatestFileByMtime(absDir, predicate) {
+  /** @type {Array<{ abs: string, mtimeMs: number }>} */
+  const matches = [];
+  if (!(await pathExists(absDir))) return "";
+  try {
+    const entries = await fs.readdir(absDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (!predicate(entry.name)) continue;
+      const abs = path.join(absDir, entry.name);
+      const st = await fs.stat(abs);
+      matches.push({ abs, mtimeMs: st.mtimeMs });
+    }
+  } catch {
+    return "";
+  }
+  matches.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return matches[0]?.abs || "";
+}
+
+/**
+ * @param {{
+ *   gitRoot: string,
+ *   changeId: string,
+ *   branch: string,
+ *   status: any,
+ *   collaboration: any,
+ *   created: string[],
+ *   validateRes: any,
+ *   validateFailed: boolean
+ * }} options
+ */
+export function buildDeliverySummary(options) {
+  const { gitRoot, changeId, branch, status, collaboration, created, validateRes, validateFailed } = options;
+  /** @type {string[]} */
+  const lines = [];
+  lines.push(`# Delivery Summary: ${changeId}`);
+  lines.push("");
+  lines.push(`Generated: ${new Date().toISOString().replace(/\.\d{3}Z$/, "Z")}`);
+  lines.push("");
+  lines.push("## Context");
+  lines.push(`- Worktree: \`${gitRoot}\``);
+  lines.push(`- Branch: \`${branch || "(detached)"}\``);
+  lines.push("");
+  lines.push("## Status");
+  lines.push(`- Phase: \`${status.phase}\``);
+  lines.push(`- Tasks: ${status.tasks.done}/${status.tasks.total} (unchecked=${status.tasks.unchecked})`);
+  lines.push(`- Truth drift: ${status.driftFiles.length > 0 ? status.driftFiles.join(", ") : "(none)"}`);
+  lines.push("");
+  lines.push("## Collaboration");
+  lines.push(`- analysis: ${collaboration.counts.analysis}`);
+  lines.push(`- patches: ${collaboration.counts.patches}`);
+  lines.push(`- review: ${collaboration.counts.review}`);
+  lines.push(`- evidence dir files: ${collaboration.counts.evidence}`);
+  for (const key of ["analysis", "patches", "review"]) {
+    const group = collaboration.dirs[key];
+    if (!group || group.count === 0) continue;
+    lines.push(`- ${group.label} files:`);
+    for (const rel of group.files) lines.push(`  - \`${rel}\``);
+    if (group.truncated) lines.push("  - ...(truncated)");
+  }
+  lines.push("");
+  lines.push("## Bindings");
+  if (status.reqId) lines.push(`- Req_ID: \`${status.reqId}\``);
+  if (status.probId) lines.push(`- Problem_ID: \`${status.probId}\``);
+  if (status.bindings?.contractRow) lines.push(`- Contract_Row: \`${status.bindings.contractRow}\``);
+  if (status.bindings?.planFile) lines.push(`- Plan_File: \`${status.bindings.planFile}\``);
+  lines.push("");
+  lines.push("## Evidence (Created/Collected)");
+  if (created.length === 0) lines.push("- (none)");
+  else for (const item of created) lines.push(`- \`${item}\``);
+  lines.push("");
+  lines.push("## Quality Gate");
+  if (!validateRes) {
+    lines.push("- Strict validation: (skipped via --no-validate)");
+  } else {
+    lines.push(`- Strict validation ok: \`${validateRes.ok === true}\``);
+    lines.push(`- Errors: \`${Array.isArray(validateRes.errors) ? validateRes.errors.length : 0}\``);
+    lines.push(`- Warnings: \`${Array.isArray(validateRes.warnings) ? validateRes.warnings.length : 0}\``);
+  }
+  lines.push("");
+  lines.push("## Next");
+  lines.push(`- ${planVerifyHint(changeId)}`);
+  if (validateFailed) lines.push("- Fix strict validation errors, then re-run `aiws change evidence`");
+  else lines.push(`- Verify evidence gate: \`aiws change validate ${changeId} --strict --check-evidence\``);
+  if (collaboration.counts.patches > 0) lines.push("- Review delegated patch drafts before apply/merge; do not treat `changes/<id>/patches/` as auto-applied changes");
+  if (collaboration.counts.analysis > 0 && collaboration.counts.review === 0) lines.push("- Summarize delegated analysis into `changes/<id>/review/` before delivery");
+  return lines.join("\n") + "\n";
+}