android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/agent-render/snapshot.js

@@ -0,0 +1,267 @@
+import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  mergeAreaReqMarkdown,
+  mergeAreaReqTxt,
+  mergeReqMarkdown,
+  mergeReqTxt,
+} from "./merge.js";
+import {
+  areaDirFor,
+  expandAreaRenderItems,
+  expandRenderItems,
+  renderDirFor,
+} from "./orchestrate.js";
+/** Read a finalized per-Feature output written by either Stage 2 dispatch
+ * mode.  Exported for downstream handoff adapters so they can consume the
+ * structured result without reverse-parsing req text. */
+export async function readAttempt(file) {
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf8"));
+    // A partially-written or failed output.json counts as "not rendered" —
+    // and so does a not-yet-finalized one: in subagent mode (ADR-0005)
+    // outputPath is first written by the subagent's own raw judgment (which
+    // can legitimately carry status "ok" before it has passed self-check)
+    // and only overwritten in place once `finalize` runs, so `finalized`
+    // must hold too, not just `status`.
+    return parsed.finalized === true &&
+      parsed.status === "ok" &&
+      typeof parsed.body === "string"
+      ? parsed
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+/** Read a finalized per-Area output written by Stage 2. */
+export async function readAreaAttempt(file) {
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf8"));
+    // A partially-written or failed output.json counts as "not rendered" —
+    // see readAttempt above for why `finalized` must hold too, not just
+    // `status`.
+    if (parsed.status !== "ok" || parsed.finalized !== true) return undefined;
+    const features = new Map();
+    for (const [id, featureResult] of Object.entries(parsed.features ?? {})) {
+      if (
+        featureResult.status === "ok" &&
+        typeof featureResult.body === "string"
+      ) {
+        features.set(id, featureResult);
+      }
+    }
+    return {
+      status: "ok",
+      areaId: parsed.areaId,
+      ...(parsed.areaDescription === undefined
+        ? {}
+        : { areaDescription: parsed.areaDescription }),
+      ...(parsed.accessPath === undefined
+        ? {}
+        : { accessPath: parsed.accessPath }),
+      ...(parsed.reachable === undefined
+        ? {}
+        : { reachable: parsed.reachable }),
+      features,
+      ...(parsed.addedFeatures === undefined
+        ? {}
+        : { addedFeatures: parsed.addedFeatures }),
+      ...(parsed.hasFeature === false ? { hasFeature: false } : {}),
+      attempt: parsed.attempt,
+    };
+  } catch {
+    return undefined;
+  }
+}
+/** Offline merge: reads rendering/ output.json files only, never touches a
+ * backend. Failed/missing entries fall back to the template body.
+ * `renderableReqModel` (post-filterRenderableAreas) decides which output.json
+ * files to look for; `fullReqModel` must be the same, unfiltered req-model
+ * templateText was rendered from, so the merge walk's Area/Feature positions
+ * line up with the template text — filtering only some Areas out of
+ * rendering must not desync it from the template it is walking. */
+export async function snapshotReq(
+  renderableReqModel,
+  fullReqModel,
+  renderDir,
+  outputDirectory,
+  templateText,
+  mergeOptions = {},
+  clock = Date.now,
+) {
+  const items = expandRenderItems(renderableReqModel);
+  const results = new Map();
+  for (const item of items) {
+    const file = path.join(
+      renderDir,
+      renderDirFor(item.feature.id),
+      "output.json",
+    );
+    const attempt = await readAttempt(file);
+    if (attempt !== undefined) results.set(item.feature.id, attempt);
+  }
+  const timestamp = new Date(clock()).toISOString().replace(/[:.]/g, "-");
+  const snapshotFile = path.join(outputDirectory, `req-${timestamp}.md`);
+  await writeFile(
+    snapshotFile,
+    mergeReqMarkdown(
+      fullReqModel,
+      renderableReqModel,
+      results,
+      templateText,
+      mergeOptions,
+    ),
+    "utf8",
+  );
+  return {
+    snapshotFile,
+    total: items.length,
+    aiRendered: results.size,
+    fallback: items.length - results.size,
+  };
+}
+/** Offline merge for per-Area rendering: reads rendering/ output.json files.
+ * See snapshotReq for why both a renderable and a full req-model are needed. */
+export async function snapshotAreaReq(
+  renderableReqModel,
+  fullReqModel,
+  renderDir,
+  outputDirectory,
+  templateText,
+  mergeOptions = {},
+  clock = Date.now,
+) {
+  const items = expandAreaRenderItems(renderableReqModel);
+  const areaResults = new Map();
+  let totalFeatures = 0;
+  let aiRendered = 0;
+  for (const item of items) {
+    totalFeatures += item.area.features.length;
+    const file = path.join(renderDir, areaDirFor(item.area.id), "output.json");
+    const attempt = await readAreaAttempt(file);
+    if (attempt !== undefined) {
+      areaResults.set(item.area.id, attempt);
+      aiRendered += attempt.features.size;
+    }
+  }
+  const timestamp = new Date(clock()).toISOString().replace(/[:.]/g, "-");
+  const snapshotFile = path.join(outputDirectory, `req-${timestamp}.md`);
+  await writeFile(
+    snapshotFile,
+    mergeAreaReqMarkdown(
+      fullReqModel,
+      renderableReqModel,
+      areaResults,
+      templateText,
+      mergeOptions,
+    ),
+    "utf8",
+  );
+  return {
+    snapshotFile,
+    totalAreas: items.length,
+    totalFeatures,
+    aiRendered,
+    fallback: totalFeatures - aiRendered,
+  };
+}
+/** Write this run's compact req-N.txt sequence and remove only obsolete files
+ * in the Stage 2-owned numbered naming scheme. This keeps reruns from
+ * retaining an empty/stale file whose Area no longer has a Feature. */
+export async function writeReqTxtFiles(outputDirectory, txtAreas) {
+  await mkdir(outputDirectory, { recursive: true });
+  await Promise.all(
+    txtAreas.map((content, index) =>
+      writeFile(
+        path.join(outputDirectory, `req-${index + 1}.txt`),
+        content,
+        "utf8",
+      ),
+    ),
+  );
+  const currentNames = new Set(
+    txtAreas.map((_, index) => `req-${index + 1}.txt`),
+  );
+  const entries = await readdir(outputDirectory, { withFileTypes: true });
+  await Promise.all(
+    entries.flatMap((entry) =>
+      entry.isFile() &&
+      /^req-\d+\.txt$/u.test(entry.name) &&
+      !currentNames.has(entry.name)
+        ? [unlink(path.join(outputDirectory, entry.name))]
+        : [],
+    ),
+  );
+}
+/** Offline merge for per-Area rendering → per-area req-{idx}.txt files. */
+export async function snapshotAreaReqTxt(
+  renderableReqModel,
+  fullReqModel,
+  graph,
+  renderDir,
+  outputDirectory,
+  mergeOptions = {},
+) {
+  const items = expandAreaRenderItems(renderableReqModel);
+  const areaResults = new Map();
+  let totalFeatures = 0;
+  let aiRendered = 0;
+  for (const item of items) {
+    totalFeatures += item.area.features.length;
+    const file = path.join(renderDir, areaDirFor(item.area.id), "output.json");
+    const attempt = await readAreaAttempt(file);
+    if (attempt !== undefined) {
+      areaResults.set(item.area.id, attempt);
+      aiRendered += attempt.features.size;
+    }
+  }
+  const txtAreas = mergeAreaReqTxt(
+    fullReqModel,
+    renderableReqModel,
+    areaResults,
+    graph,
+    mergeOptions,
+  );
+  await writeReqTxtFiles(outputDirectory, txtAreas);
+  return {
+    totalAreas: txtAreas.length,
+    totalFeatures,
+    aiRendered,
+    fallback: totalFeatures - aiRendered,
+  };
+}
+/** Offline merge for per-Feature rendering → per-area req-{idx}.txt files. */
+export async function snapshotReqTxt(
+  renderableReqModel,
+  fullReqModel,
+  graph,
+  renderDir,
+  outputDirectory,
+  mergeOptions = {},
+) {
+  const items = expandRenderItems(renderableReqModel);
+  const results = new Map();
+  for (const item of items) {
+    const file = path.join(
+      renderDir,
+      renderDirFor(item.feature.id),
+      "output.json",
+    );
+    const attempt = await readAttempt(file);
+    if (attempt !== undefined) results.set(item.feature.id, attempt);
+  }
+  const txtAreas = mergeReqTxt(
+    fullReqModel,
+    renderableReqModel,
+    results,
+    graph,
+    mergeOptions,
+  );
+  await writeReqTxtFiles(outputDirectory, txtAreas);
+  return {
+    totalAreas: txtAreas.length,
+    totalFeatures: items.length,
+    aiRendered: results.size,
+    fallback: items.length - results.size,
+  };
+}

package/skills/a2h-app-req-gen/scripts/reqgen/src/agent-render/types.js

@@ -0,0 +1 @@
+export {};

package/skills/a2h-app-req-gen/scripts/reqgen/src/agent-render/validate.js

@@ -0,0 +1,122 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+async function checkCitation(citation, resolvedRoot, readFileFn) {
+  // Agents often echo absolute paths from their own Read/Grep tools even
+  // though the prompt asks for project-relative paths — accept either, but
+  // still enforce the project.root boundary.
+  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 readFileFn(resolvedFile);
+  } catch {
+    return { citation, reason: "file-not-found" };
+  }
+  return undefined;
+}
+export async function validateCitations(
+  citations,
+  projectRoot,
+  readFileFn = (file) => readFile(file, "utf8"),
+) {
+  const resolvedRoot = path.resolve(projectRoot);
+  const invalid = [];
+  for (const citation of citations) {
+    const problem = await checkCitation(citation, resolvedRoot, readFileFn);
+    if (problem !== undefined) invalid.push(problem);
+  }
+  return { valid: invalid.length === 0, invalid };
+}
+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);
+    const kb = Object.keys(b);
+    if (ka.length !== kb.length) return false;
+    return ka.every((k) => deepEqual(a[k], b[k]));
+  }
+  return false;
+}
+// controlType is deliberately skipped: the new model's `trigger` carries
+// different semantics than the old control.type (SPEC-0001 open question,
+//评审倾向跳过). Only default/options are compared.
+export function validateRestatedFacts(restatedFacts, feature) {
+  const mismatches = [];
+  const expectedDefault =
+    feature.defaultValue?.status === "resolved"
+      ? feature.defaultValue.value
+      : undefined;
+  if (
+    expectedDefault !== undefined &&
+    !deepEqual(restatedFacts.default, expectedDefault)
+  ) {
+    mismatches.push("default");
+  }
+  const expectedOptions = new Set(
+    feature.options.map((option) => option.value),
+  );
+  const actualOptions = new Set(restatedFacts.options ?? []);
+  const optionsMatch =
+    expectedOptions.size === actualOptions.size &&
+    [...expectedOptions].every((label) => actualOptions.has(label));
+  if (!optionsMatch) mismatches.push("options");
+  return { valid: mismatches.length === 0, mismatches };
+}
+/** Placeholder "待确认" must never survive into the final title.
+ * Resolved UI-literal names (translatable=false) must appear verbatim —
+ * the Agent may rewrite a code-identifier name (translatable=true), but
+ * it must not alter a name Stage 1 already resolved from UI text.
+ * Quote consistency is deferred to a non-blocking audit (overview.ts). */
+export function validateTitle(agentTitle, parts) {
+  const problems = [];
+  // Still-pending: placeholder must be replaced
+  if (!parts.areaResolved && agentTitle.includes("Area 名称待确认")) {
+    problems.push("area-segment-still-pending");
+  }
+  if (!parts.featureResolved && agentTitle.includes("控件名称待确认")) {
+    problems.push("feature-segment-still-pending");
+  }
+  // Resolved UI-literal name must survive verbatim
+  if (
+    parts.areaResolved &&
+    !parts.areaTranslatable &&
+    !agentTitle.includes(parts.areaName)
+  ) {
+    problems.push("resolved-area-segment-rewritten");
+  }
+  if (
+    parts.featureResolved &&
+    !parts.featureTranslatable &&
+    !agentTitle.includes(parts.featureName)
+  ) {
+    problems.push("resolved-feature-segment-rewritten");
+  }
+  return { valid: problems.length === 0, problems };
+}
+/** Same rules as validateTitle, applied to every member of a merged req item
+ * (see FeatureRenderResult.mergedRequirementIds) — the one shared title must
+ * satisfy each merged Control's own name-inclusion requirement. Degenerates
+ * to validateTitle's result for a single-member list (the ordinary,
+ * non-merged case). */
+export function validateTitleForMembers(agentTitle, partsList) {
+  const problems = new Set();
+  for (const parts of partsList) {
+    for (const problem of validateTitle(agentTitle, parts).problems)
+      problems.add(problem);
+  }
+  return { valid: problems.size === 0, problems: [...problems] };
+}

package/skills/a2h-app-req-gen/scripts/reqgen/src/analysis/callback-call-sites.js

@@ -0,0 +1,62 @@
+export function executionFlowsForward(flowKind) {
+  return (
+    flowKind === "listener-invocation" ||
+    flowKind === "direct-call" ||
+    flowKind === "event-channel"
+  );
+}
+/**
+ * True only for value-flow edges that represent an argument supplied to one
+ * concrete invocation. Declaration aliases intentionally have no call-site
+ * identity and keep their previous context-free behavior.
+ */
+export function isCallSiteArgumentStep(step) {
+  return (
+    step.flowKind === "argument-to-parameter" ||
+    (step.flowKind === "method-reference" &&
+      (step.callSiteKey !== undefined || step.parameterName !== undefined))
+  );
+}
+/**
+ * Maintains the minimum call string needed to pair a formal callback slot
+ * with the actual callback supplied at the same invocation.
+ *
+ * A direct call pushes its raw call-site identity. Traversing a callback
+ * argument backwards (formal slot -> actual implementation) must match and
+ * pop that identity. If execution starts inside a reusable declaration there
+ * is no call-site frame; a unique actual is safe, while multiple actuals are
+ * deliberately rejected instead of being cross-wired.
+ */
+export function advanceCallSiteStack(
+  current,
+  step,
+  reverseArgumentCandidateCount,
+) {
+  if (step.flowKind === "direct-call" && step.callSiteKey) {
+    return {
+      accepted: true,
+      callSiteStack: [...current, step.callSiteKey],
+    };
+  }
+  if (!isCallSiteArgumentStep(step)) {
+    return { accepted: true, callSiteStack: current };
+  }
+  const expected = current.at(-1);
+  if (expected !== undefined) {
+    if (step.callSiteKey !== undefined) {
+      if (step.callSiteKey !== expected) {
+        return { accepted: false, callSiteStack: current };
+      }
+    } else if (reverseArgumentCandidateCount !== 1) {
+      return { accepted: false, callSiteStack: current };
+    }
+    return {
+      accepted: true,
+      callSiteStack: current.slice(0, -1),
+    };
+  }
+  if (reverseArgumentCandidateCount !== 1) {
+    return { accepted: false, callSiteStack: current };
+  }
+  return { accepted: true, callSiteStack: current };
+}