android2harmony 0.1.7 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen-selfcheck.mjs

@@ -0,0 +1,555 @@
+#!/usr/bin/env node
+// Standalone self-check/finalize script for stage2 subagent-mode rendering
+// (ADR-0005: docs/ADR/ADR-0005-subagent-launch-mode-for-stage2.md).
+//
+// Deliberately independent of this repository's TypeScript build: a subagent
+// rendering a page invokes this with plain `node`, with its cwd inside the
+// *target* Android project, not this repo. Zero npm dependencies, Node
+// built-ins only. Bundled inside the skill (not the parent TS project's
+// scripts/) so it travels with the skill wherever it's installed.
+//
+// This file re-implements (does not import) the validation rules in
+// src/agent-render/validate.ts and the stripLeadingTitle helper in
+// src/agent-render/merge.ts. Keep the two in sync by hand when either
+// changes — see ADR-0005 follow-ups.
+//
+// Usage:
+//   node reqgen-selfcheck.mjs check    <outputPath> <expectedPath> <projectRoot>
+//   node reqgen-selfcheck.mjs finalize <outputPath> <expectedPath> <projectRoot>
+//
+// There is one file, `outputPath`, throughout: the subagent's first write is
+// its own raw, not-yet-validated judgment; `finalize` reads that same path
+// and overwrites it in place with either a validated success (`finalized:
+// true`) or a diagnostic validation failure (`finalized: false`) — there is
+// no separate draft file and nothing gets copied between two files.
+//
+// Exit codes:
+//   0 - the script itself ran to completion. For `check`, this is true
+//       whether or not the draft passed (see the printed report's `ok`
+//       field) — a failed check is a normal, expected outcome, not a script
+//       error. For `finalize`, 0 means outputPath was overwritten in place;
+//       inspect the printed `ok` field to learn whether it passed validation.
+//   2 - the script could not run at all (bad arguments, unreadable/unparsable
+//       outputPath or expectedPath, missing projectRoot) — this is a data/
+//       environment problem the caller must fix before retrying, not a
+//       "content failed validation" result.
+
+import { readFile, writeFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(2);
+}
+
+async function readJson(filePath, label) {
+  let text;
+  try {
+    text = await readFile(filePath, "utf8");
+  } catch (error) {
+    fail(`Cannot read ${label} at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    fail(`${label} at ${filePath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+async function requireDirectory(dirPath, label) {
+  let info;
+  try {
+    info = await stat(dirPath);
+  } catch (error) {
+    fail(`Cannot stat ${label} at ${dirPath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!info.isDirectory()) fail(`${label} at ${dirPath} is not a directory`);
+}
+
+// ---------------------------------------------------------------------------
+// Ported from src/agent-render/validate.ts (verbatim logic, plain JS).
+// Keep the two in sync by hand — see ADR-0005 follow-ups.
+// ---------------------------------------------------------------------------
+
+async function checkCitation(citation, resolvedRoot) {
+  const resolvedFile = path.isAbsolute(citation.file)
+    ? path.resolve(citation.file)
+    : path.resolve(resolvedRoot, citation.file);
+  if (
+    resolvedFile !== resolvedRoot &&
+    !resolvedFile.startsWith(resolvedRoot + path.sep)
+  ) {
+    return { citation, reason: "outside-project-root" };
+  }
+  try {
+    await stat(resolvedFile);
+  } catch {
+    return { citation, reason: "file-not-found" };
+  }
+  return undefined;
+}
+
+async function validateCitations(citations, projectRoot) {
+  const resolvedRoot = path.resolve(projectRoot);
+  const invalid = [];
+  for (const citation of citations) {
+    const problem = await checkCitation(citation, resolvedRoot);
+    if (problem !== undefined) invalid.push(problem);
+  }
+  return { valid: invalid.length === 0, invalid };
+}
+
+// Deep equality that handles arrays ([] !== [] in JS).
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object" && a !== null && b !== null) {
+    const ka = Object.keys(a), kb = Object.keys(b);
+    if (ka.length !== kb.length) return false;
+    return ka.every((k) => deepEqual(a[k], b[k]));
+  }
+  return false;
+}
+
+// expectedRestatedFacts: { default: {status:"resolved", value} | {status:"unresolved"}, options: string[] }
+function validateRestatedFacts(restatedFacts, expectedRestatedFacts) {
+  const mismatches = [];
+  const rf = restatedFacts ?? {};
+  const expectedDefault = expectedRestatedFacts.default;
+  if (expectedDefault !== undefined && expectedDefault.status === "resolved") {
+    if (!deepEqual(rf.default, expectedDefault.value)) mismatches.push("default");
+  }
+  const expectedOptions = new Set(expectedRestatedFacts.options ?? []);
+  const actualOptions = new Set(rf.options ?? []);
+  const optionsMatch = expectedOptions.size === actualOptions.size &&
+    [...expectedOptions].every((label) => actualOptions.has(label));
+  if (!optionsMatch) mismatches.push("options");
+  return { valid: mismatches.length === 0, mismatches };
+}
+
+// expectedTitle: { areaName, featureName, areaResolved, featureResolved, areaTranslatable, featureTranslatable, template }
+// Only checks that UI-literal names survive and placeholders are replaced.
+// Quote consistency is NOT checked here — it's a prompt-level concern.
+function validateTitle(agentTitle, expectedTitle) {
+  const problems = [];
+  // Still-pending: placeholder must be replaced
+  if (!expectedTitle.areaResolved && agentTitle.includes("Area 名称待确认")) {
+    problems.push("area-segment-still-pending");
+  }
+  if (!expectedTitle.featureResolved && agentTitle.includes("控件名称待确认")) {
+    problems.push("feature-segment-still-pending");
+  }
+  // Resolved UI-literal name must appear verbatim
+  if (
+    expectedTitle.areaResolved && !expectedTitle.areaTranslatable &&
+    !agentTitle.includes(expectedTitle.areaName)
+  ) {
+    problems.push("resolved-area-segment-rewritten");
+  }
+  if (
+    expectedTitle.featureResolved && !expectedTitle.featureTranslatable &&
+    !agentTitle.includes(expectedTitle.featureName)
+  ) {
+    problems.push("resolved-feature-segment-rewritten");
+  }
+  return { valid: problems.length === 0, problems };
+}
+
+// Ported from src/agent-render/merge.ts.
+function stripLeadingTitle(body, title) {
+  const trimmed = body.replace(/^\s+/, "");
+  if (!trimmed.startsWith(title)) return body;
+  return trimmed.slice(title.length).replace(/^\s*\n+/, "");
+}
+
+// ---------------------------------------------------------------------------
+// Per-entry evaluation shared by `check` and `finalize`.
+// ---------------------------------------------------------------------------
+
+// Check that body has properly formatted enumeration lines when options is non-empty.
+// Format: 4 spaces + "N,选项名：说明" — one line per option, count must match.
+// enum-missing is blocking; enum-count-mismatch is a non-blocking warning.
+function validateOptionEnumeration(body, options) {
+  if (!options || options.length === 0) return { valid: true, problems: [], warnings: [] };
+  if (typeof body !== "string") return { valid: false, problems: ["body-missing"], warnings: [] };
+  const lines = body.split("\n");
+  const enumLines = lines.filter((l) => /^    \d+,/.test(l));
+  const problems = [];
+  const warnings = [];
+  if (enumLines.length === 0) {
+    problems.push(
+      "enum-missing: options 非空但 body 中没有枚举行。" +
+      "正确格式：正文后紧跟枚举行，每行 4 个空格缩进 + 数字序号逗号 + 选项名 + 全角冒号 + 说明。" +
+      "例：\n" +
+      "    1,米：采用公制单位\n" +
+      "    2,英里：采用英制单位"
+    );
+  } else if (enumLines.length !== options.length) {
+    warnings.push(
+      `enum-count-mismatch: options 有 ${options.length} 项，枚举行有 ${enumLines.length} 行。` +
+      "每项 option 都需要单独一行枚举行（4 空格 + N,选项名：说明），不能漏写或多写。"
+    );
+  }
+  return { valid: problems.length === 0, problems, warnings };
+}
+
+async function evaluateEntry(entry, expected, projectRoot) {
+  const citationsResult = await validateCitations(entry?.citations ?? [], projectRoot);
+  const restatedResult = validateRestatedFacts(entry?.restatedFacts ?? {}, expected.restatedFacts);
+  const titleResult = entry?.title === undefined
+    ? { valid: false, problems: ["title-missing"] }
+    : validateTitle(entry.title, expected.title);
+  const optionEnumResult = validateOptionEnumeration(
+    entry?.body, expected.restatedFacts.options
+  );
+  const warnings = [
+    ...citationsResult.invalid.map((inv) => ({ source: "citation", ...inv })),
+    ...restatedResult.mismatches.map((field) => ({ source: "restatedFacts", field })),
+    ...titleResult.problems.map((reason) => ({ source: "title", reason })),
+    ...optionEnumResult.problems.map((reason) => ({ source: "optionEnum", reason })),
+    ...optionEnumResult.warnings.map((reason) => ({ source: "optionEnum", reason }))
+  ];
+  return { citationsResult, restatedResult, titleResult, optionEnumResult, warnings };
+}
+
+function problemsForEntry(requirementId, evaluation) {
+  const problems = [];
+  for (const inv of evaluation.citationsResult.invalid) {
+    problems.push({
+      requirementId,
+      check: "citation",
+      reason: inv.reason,
+      file: inv.citation.file,
+      startLine: inv.citation.startLine,
+      endLine: inv.citation.endLine
+    });
+  }
+  for (const field of evaluation.restatedResult.mismatches) {
+    problems.push({ requirementId, check: "restatedFacts", field });
+  }
+  for (const reason of evaluation.titleResult.problems) {
+    problems.push({ requirementId, check: "title", reason });
+  }
+  for (const reason of evaluation.optionEnumResult?.problems ?? []) {
+    problems.push({ requirementId, check: "optionEnum", reason });
+  }
+  return problems;
+}
+
+function finalizeEntryFields(entry, expected, evaluation, stripTitleOverride) {
+  const stripTitle = stripTitleOverride ?? expected.title.template;
+  return {
+    status: "ok",
+    title: entry?.title,
+    titleValid: evaluation.titleResult.valid,
+    body: entry?.body === undefined
+      ? undefined
+      : stripLeadingTitle(entry.body, stripTitle),
+    restatedFacts: entry?.restatedFacts,
+    citations: entry?.citations,
+    confidence: entry?.confidence,
+    citationsValid: evaluation.citationsResult.valid,
+    invalidCitations: evaluation.citationsResult.invalid,
+    restatedFactsValid: evaluation.restatedResult.valid,
+    restatedFactsMismatches: evaluation.restatedResult.mismatches,
+    optionEnumValid: evaluation.optionEnumResult.valid,
+    optionEnumProblems: evaluation.optionEnumResult.problems,
+    warnings: evaluation.warnings
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Area-mode grouping: mirrors validateAreaOutput in orchestrate.ts — group by
+// every requirementId an entry covers (not a plain Map) so a repeated id is
+// reported as a collision instead of silently overwritten. An entry covers
+// just its own `requirementId` normally, or every id listed in
+// `mergedRequirementIds` (including its own) when the subagent merged
+// several Controls into one req item (see prompt.ts's "合并规则").
+// ---------------------------------------------------------------------------
+
+function coveredRequirementIds(entry) {
+  return Array.isArray(entry.mergedRequirementIds) && entry.mergedRequirementIds.length > 0
+    ? entry.mergedRequirementIds
+    : [entry.requirementId ?? ""];
+}
+
+function groupByRequirementId(entries) {
+  const byRequirementId = new Map();
+  for (const entry of entries ?? []) {
+    for (const key of coveredRequirementIds(entry)) {
+      const group = byRequirementId.get(key);
+      if (group === undefined) byRequirementId.set(key, [entry]);
+      else group.push(entry);
+    }
+  }
+  return byRequirementId;
+}
+
+// Mirrors validateTitleForMembers in validate.ts: the one shared title of a
+// merged req item must satisfy every covered member's own name-inclusion
+// requirement. Degenerates to validateTitle's result for a single-member list.
+function validateTitleForMembers(agentTitle, expectedTitleList) {
+  const problems = new Set();
+  for (const expectedTitle of expectedTitleList) {
+    for (const problem of validateTitle(agentTitle, expectedTitle).problems) problems.add(problem);
+  }
+  return { valid: problems.size === 0, problems: [...problems] };
+}
+
+// Mirrors validateFeatureOutput's merged branch in orchestrate.ts:
+// restatedFacts checked against `memberExps[0]` (the earliest member in
+// Area order), title checked against every member's own parts, and the
+// leading-title-line strip target is the entry's own title (there is no
+// single per-member template that represents the whole group).
+async function evaluateMergedEntry(entry, memberExps, projectRoot) {
+  const citationsResult = await validateCitations(entry?.citations ?? [], projectRoot);
+  const restatedResult = validateRestatedFacts(entry?.restatedFacts ?? {}, memberExps[0].restatedFacts);
+  const titleResult = entry?.title === undefined
+    ? { valid: false, problems: ["title-missing"] }
+    : validateTitleForMembers(entry.title, memberExps.map((exp) => exp.title));
+  const optionEnumResult = validateOptionEnumeration(
+    entry?.body, memberExps[0].restatedFacts.options
+  );
+  const warnings = [
+    ...citationsResult.invalid.map((inv) => ({ source: "citation", ...inv })),
+    ...restatedResult.mismatches.map((field) => ({ source: "restatedFacts", field })),
+    ...titleResult.problems.map((reason) => ({ source: "title", reason })),
+    ...optionEnumResult.problems.map((reason) => ({ source: "optionEnum", reason })),
+    ...optionEnumResult.warnings.map((reason) => ({ source: "optionEnum", reason }))
+  ];
+  return { citationsResult, restatedResult, titleResult, optionEnumResult, warnings };
+}
+
+function isAgentAddedFeature(entry) {
+  return entry?.kind === "agent-added";
+}
+
+async function evaluateAgentAddedFeature(entry, projectRoot) {
+  const citations = entry?.citations ?? [];
+  const citationsResult = await validateCitations(citations, projectRoot);
+  const title = typeof entry?.title === "string" ? entry.title.trim() : "";
+  const body = typeof entry?.body === "string" ? entry.body.trim() : "";
+  const reason = title.length === 0
+    ? "agent-added-feature-title-missing"
+    : body.length === 0
+      ? "agent-added-feature-body-missing"
+      : citations.length === 0
+        ? "agent-added-feature-citations-missing"
+        : citationsResult.valid ? undefined : "agent-added-feature-citations-invalid";
+  return { entry, citationsResult, reason };
+}
+
+function agentAddedProblems(evaluation) {
+  const problems = [];
+  if (evaluation.reason !== undefined) {
+    problems.push({ check: "agent-added-feature", reason: evaluation.reason });
+  }
+  return problems;
+}
+
+function finalizeAgentAddedFeature(evaluation) {
+  const { entry, citationsResult, reason } = evaluation;
+  return {
+    status: reason === undefined ? "ok" : "error",
+    ...(reason === undefined ? {} : { error: reason }),
+    ...(entry?.title === undefined ? {} : { title: entry.title }),
+    ...(entry?.body === undefined ? {} : { body: entry.body }),
+    ...(entry?.citations === undefined ? {} : { citations: entry.citations }),
+    ...(entry?.confidence === undefined ? {} : { confidence: entry.confidence }),
+    citationsValid: citationsResult.valid,
+    ...(citationsResult.invalid.length === 0
+      ? {}
+      : { invalidCitations: citationsResult.invalid })
+  };
+}
+
+async function evaluateArea(draft, expected, projectRoot) {
+  const rawFeatures = draft.features ?? [];
+  const byRequirementId = groupByRequirementId(rawFeatures.filter((entry) => !isAgentAddedFeature(entry)));
+  const expByRequirementId = new Map(expected.features.map((exp) => [exp.requirementId, exp]));
+  const problems = [];
+  const addedFeatures = await Promise.all(
+    rawFeatures.filter(isAgentAddedFeature).map((entry) => evaluateAgentAddedFeature(entry, projectRoot))
+  );
+  for (const added of addedFeatures) problems.push(...agentAddedProblems(added));
+  if (expected.features.length === 0 && rawFeatures.length === 0 && draft.hasFeature !== false) {
+    problems.push({ check: "presence", reason: "has-feature-marker-missing-in-draft" });
+  }
+  if (draft.hasFeature === false && (expected.features.length > 0 || rawFeatures.length > 0)) {
+    problems.push({ check: "presence", reason: "has-feature-marker-conflicts-with-features" });
+  }
+  const perFeature = [];
+  // A merge group's single entry is validated once and the evaluation
+  // shared by every member it covers, instead of re-running citation/title
+  // checks once per member.
+  const evaluatedEntries = new Map();
+  expected.features.forEach((exp, index) => {
+    const group = byRequirementId.get(exp.requirementId);
+    if (group === undefined) {
+      problems.push({ requirementId: exp.requirementId, check: "presence", reason: "feature-missing-in-draft" });
+      perFeature.push({ exp, error: "feature-missing-in-agent-output" });
+      return;
+    }
+    if (group.length > 1) {
+      problems.push({ requirementId: exp.requirementId, check: "presence", reason: "feature-id-collision-in-draft" });
+      perFeature.push({ exp, error: "feature-id-collision-in-agent-output" });
+      return;
+    }
+    const entry = group[0];
+    const coveredIds = coveredRequirementIds(entry);
+    const merged = coveredIds.length > 1;
+    // Only checked for a non-merged entry — see validateAreaOutput in
+    // orchestrate.ts for why this cross-check is skipped for a merged entry.
+    if (!merged && entry.controlIndex !== undefined && entry.controlIndex !== index + 1) {
+      problems.push({ requirementId: exp.requirementId, check: "presence", reason: "feature-index-mismatch-in-draft" });
+      perFeature.push({ exp, error: "feature-index-mismatch-in-agent-output" });
+      return;
+    }
+    perFeature.push({ exp, entry, merged, coveredIds });
+  });
+  for (const item of perFeature) {
+    if (item.error !== undefined) continue;
+    let evaluation = evaluatedEntries.get(item.entry);
+    if (evaluation === undefined) {
+      if (item.merged) {
+        const memberExps = item.coveredIds
+          .map((id) => expByRequirementId.get(id))
+          .filter((exp) => exp !== undefined);
+        evaluation = await evaluateMergedEntry(
+          item.entry, memberExps.length > 0 ? memberExps : [item.exp], projectRoot
+        );
+      } else {
+        evaluation = await evaluateEntry(item.entry, item.exp, projectRoot);
+      }
+      evaluatedEntries.set(item.entry, evaluation);
+    }
+    item.evaluation = evaluation;
+    problems.push(...problemsForEntry(item.exp.requirementId, evaluation));
+  }
+  return { perFeature, addedFeatures, problems };
+}
+
+function finalizeAreaFields(draft, expected, evaluated) {
+  const featuresObj = {};
+  const expByRequirementId = new Map(expected.features.map((exp) => [exp.requirementId, exp]));
+  for (const item of evaluated.perFeature) {
+    if (item.error !== undefined) {
+      featuresObj[item.exp.featureId] = {
+        status: "error",
+        error: item.error,
+        citationsValid: false,
+        restatedFactsValid: false
+      };
+      continue;
+    }
+    if (item.merged) {
+      // The merged entry's own title (not any single member's template) is
+      // the correct leading-title-line strip target — see evaluateMergedEntry.
+      const fields = finalizeEntryFields(item.entry, item.exp, item.evaluation, item.entry?.title);
+      const mergedFeatureIds = item.coveredIds
+        .map((id) => expByRequirementId.get(id)?.featureId)
+        .filter((id) => id !== undefined);
+      featuresObj[item.exp.featureId] = { ...fields, mergedFeatureIds };
+    } else {
+      featuresObj[item.exp.featureId] = finalizeEntryFields(item.entry, item.exp, item.evaluation);
+    }
+  }
+  const addedFeatures = evaluated.addedFeatures.map(finalizeAgentAddedFeature);
+  return {
+    status: "ok",
+    areaId: expected.areaId,
+    ...(draft.areaDescription === undefined ? {} : { areaDescription: draft.areaDescription }),
+    ...(draft.accessPath === undefined ? {} : { accessPath: draft.accessPath }),
+    ...(draft.reachable === undefined ? {} : { reachable: draft.reachable }),
+    ...(Object.keys(featuresObj).length === 0 ? {} : { features: featuresObj }),
+    ...(addedFeatures.length === 0 ? {} : { addedFeatures }),
+    ...(expected.features.length === 0 && addedFeatures.length === 0
+      ? { hasFeature: false }
+      : {}),
+    attempt: 1
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+async function loadInputs(path_, expectedPath, projectRoot) {
+  const draft = await readJson(path_, "outputPath");
+  const expected = await readJson(expectedPath, "expectedPath");
+  await requireDirectory(path.resolve(projectRoot), "projectRoot");
+  if (expected.kind !== "feature" && expected.kind !== "area") {
+    fail(`expectedPath at ${expectedPath} has unknown "kind": ${String(expected.kind)}`);
+  }
+  return { draft, expected };
+}
+
+async function runCheck(path_, expectedPath, projectRoot) {
+  const { draft, expected } = await loadInputs(path_, expectedPath, projectRoot);
+  let problems;
+  if (expected.kind === "feature") {
+    const evaluation = await evaluateEntry(draft, expected, projectRoot);
+    problems = problemsForEntry(expected.requirementId, evaluation);
+  } else {
+    const evaluated = await evaluateArea(draft, expected, projectRoot);
+    problems = evaluated.problems;
+  }
+  process.stdout.write(`${JSON.stringify({ ok: problems.length === 0, problems }, null, 2)}\n`);
+}
+
+// In-place: reads `path_` (the subagent's raw, not-yet-validated write) and
+// overwrites that same path with the finalized result — no separate
+// draft/output pair, nothing to copy between two files. `finalized: true`
+// is the marker that distinguishes "actually went through finalize" from a
+// raw draft that merely happens to have status "ok" (its own self-report,
+// not a validation verdict). It is written only when validation has no
+// problems, so callers (isUnitDone, snapshot.ts) must check it together with
+// status instead of trusting a raw draft.
+async function runFinalize(path_, expectedPath, projectRoot) {
+  const { draft, expected } = await loadInputs(path_, expectedPath, projectRoot);
+  let result;
+  let problems;
+  if (expected.kind === "feature") {
+    const evaluation = await evaluateEntry(draft, expected, projectRoot);
+    problems = problemsForEntry(expected.requirementId, evaluation);
+    result = {
+      ...draft,
+      ...finalizeEntryFields(draft, expected, evaluation),
+      attempt: 1
+    };
+  } else {
+    const evaluated = await evaluateArea(draft, expected, projectRoot);
+    problems = evaluated.problems;
+    result = { ...finalizeAreaFields(draft, expected, evaluated) };
+  }
+  const ok = problems.length === 0;
+  result = {
+    ...result,
+    status: "ok",
+    ...(ok ? {} : { problems }),
+    finalized: true
+  };
+  await writeFile(path_, JSON.stringify(result, null, 2), "utf8");
+  process.stdout.write(`${JSON.stringify({ ok, outputPath: path_, ...(ok ? {} : { problems }) }, null, 2)}\n`);
+}
+
+async function main() {
+  const [, , mode, ...rest] = process.argv;
+  if (mode === "check" && rest.length === 3) {
+    await runCheck(rest[0], rest[1], rest[2]);
+    return;
+  }
+  if (mode === "finalize" && rest.length === 3) {
+    await runFinalize(rest[0], rest[1], rest[2]);
+    return;
+  }
+  fail(
+    "Usage:\n" +
+    "  node reqgen-selfcheck.mjs check    <outputPath> <expectedPath> <projectRoot>\n" +
+    "  node reqgen-selfcheck.mjs finalize <outputPath> <expectedPath> <projectRoot>"
+  );
+}
+
+await main();