android2harmony 0.1.7 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/dump/index.js

@@ -0,0 +1 @@
+export * from "./dump.js";

package/skills/a2h-app-req-gen/scripts/reqgen/src/dump-cli.js

@@ -0,0 +1,251 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  dumpAreaGraph,
+  dumpDiagnostics,
+  dumpGapAudit,
+  dumpReqModel,
+} from "./dump/index.js";
+import { sha256Text } from "./pipeline/output.js";
+export const DUMP_USAGE = `Usage:
+  pnpm dump -- --input <stage1-output-directory>
+
+Reads the Stage 1 JSON artifacts in <stage1-output-directory> (schema is a
+stable Stage 1 -> Stage 2 contract, see ADR-0004) and writes a human-readable
+recursive tree dump next to each one this tool knows how to render:
+  area-graph.json  -> area-graph.dump.txt
+  req-model.json   -> req-model.dump.txt
+  gap-audit.json   -> gap-audit.dump.txt
+  diagnostics.json -> diagnostics.dump.txt
+
+Every dumped JSON is verified against the sha256 recorded for it in
+run-report.json before being rendered; a missing run-report.json or a hash
+mismatch fails the run instead of dumping unverified data (ADR-0004). An
+artifact run-report.json does not record (for example area-graph.json on a
+run that failed before the graph stage) is silently skipped, not an error.
+`;
+export class DumpCliError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DumpCliError";
+  }
+}
+const DUMPABLE_ARTIFACTS = [
+  {
+    kind: "area-graph",
+    filename: "area-graph.json",
+    dumpFilename: "area-graph.dump.txt",
+    dump: (text, _areaGraph, sourceFacts, nameTraceability) =>
+      dumpAreaGraph(JSON.parse(text), sourceFacts, nameTraceability),
+  },
+  {
+    kind: "req-model",
+    filename: "req-model.json",
+    dumpFilename: "req-model.dump.txt",
+    dump: (text, areaGraph, sourceFacts, nameTraceability) =>
+      dumpReqModel(JSON.parse(text), areaGraph, sourceFacts, nameTraceability),
+  },
+  {
+    kind: "gap-audit",
+    filename: "gap-audit.json",
+    dumpFilename: "gap-audit.dump.txt",
+    dump: (text, _areaGraph, sourceFacts) =>
+      dumpGapAudit(JSON.parse(text), sourceFacts),
+  },
+  {
+    kind: "diagnostics",
+    filename: "diagnostics.json",
+    dumpFilename: "diagnostics.dump.txt",
+    dump: (text) => dumpDiagnostics(JSON.parse(text)),
+  },
+];
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+async function readRunReport(inputDirectory) {
+  let text;
+  try {
+    text = await readFile(join(inputDirectory, "run-report.json"), "utf8");
+  } catch (error) {
+    throw new DumpCliError(
+      `${inputDirectory} does not contain run-report.json; dump requires a ` +
+        "Stage 1 output directory so its JSON artifacts can be hash-verified " +
+        "(ADR-0004).",
+    );
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new DumpCliError("run-report.json is not valid JSON");
+  }
+  if (!isRecord(value) || !Array.isArray(value.artifacts)) {
+    throw new DumpCliError("run-report.json has an unsupported envelope");
+  }
+  return value;
+}
+async function writeDumpFile(directory, filename, content) {
+  const root = resolve(directory);
+  await mkdir(root, { recursive: true });
+  const target = join(root, filename);
+  const normalized = content.endsWith("\n") ? content : `${content}\n`;
+  const temporary = join(root, `.${filename}.${process.pid}.${Date.now()}.tmp`);
+  try {
+    await writeFile(temporary, normalized, { encoding: "utf8", flag: "wx" });
+    await rename(temporary, target);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+const defaultIo = {
+  stdout: (text) => process.stdout.write(text),
+  stderr: (text) => process.stderr.write(text),
+};
+function parseDumpArguments(argv) {
+  const args = argv[0] === "--" ? argv.slice(1) : argv;
+  const values = new Map();
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (!token.startsWith("--")) {
+      throw new DumpCliError(`Unexpected argument: ${token}`);
+    }
+    const name = token.slice(2);
+    if (name !== "input") {
+      throw new DumpCliError(`Unknown option: --${name}`);
+    }
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+      throw new DumpCliError(`Option requires a value: --${name}`);
+    }
+    values.set(name, value);
+    index += 1;
+  }
+  const input = values.get("input");
+  if (input === undefined) {
+    throw new DumpCliError("Missing required option: --input");
+  }
+  return { input: resolve(input) };
+}
+/** Reads+hash-verifies one artifact recorded in run-report.json; returns
+ * undefined only when that run never recorded it (ADR-0004 skip case). */
+async function readVerifiedArtifact(inputDirectory, report, kind, filename) {
+  const recorded = report.artifacts.find(
+    (candidate) =>
+      candidate.kind === kind && candidate.relativePath === filename,
+  );
+  if (recorded === undefined) return undefined;
+  let text;
+  try {
+    text = await readFile(join(inputDirectory, filename), "utf8");
+  } catch (error) {
+    throw new DumpCliError(
+      `run-report.json records ${filename} but it is missing from ${inputDirectory}`,
+    );
+  }
+  if (recorded.sha256 !== sha256Text(text)) {
+    throw new DumpCliError(
+      `${filename} does not match the artifact hash recorded in ` +
+        "run-report.json; refusing to dump unverified data (ADR-0004).",
+    );
+  }
+  return text;
+}
+/** Dumps every Stage 1 JSON artifact this tool renders, trusting only what
+ * run-report.json's `artifacts[]` manifest actually recorded: an artifact it
+ * doesn't mention is skipped (that Stage 1 run never produced it), an
+ * artifact it mentions but whose file is missing or hash-mismatched fails
+ * the run (ADR-0004 forbids dumping an unverified same-named file). */
+export async function runDump(inputDirectory) {
+  const report = await readRunReport(inputDirectory);
+  const dumped = [];
+  // area-graph.dump.txt and req-model.dump.txt additionally cross-reference
+  // area-graph.json, source-facts.json, and generation/name-traceability.json
+  // (same ADR-0004 hash verification) when that run recorded them, so they
+  // can render each entity's Symbol and @Anchor (DEVELOPER.md) — req-model
+  // resolves Area/Control/Action identity from the exact same graph objects
+  // area-graph's own dump uses (see dump/dump.ts); name-traceability's ranked
+  // identity decision is preferred over the source-facts heuristic for
+  // Area/Control when present.
+  const areaGraphText = await readVerifiedArtifact(
+    inputDirectory,
+    report,
+    "area-graph",
+    "area-graph.json",
+  );
+  const areaGraph =
+    areaGraphText !== undefined ? JSON.parse(areaGraphText) : undefined;
+  const sourceFactsText = await readVerifiedArtifact(
+    inputDirectory,
+    report,
+    "source-facts",
+    "source-facts.json",
+  );
+  const sourceFacts =
+    sourceFactsText !== undefined ? JSON.parse(sourceFactsText) : undefined;
+  const nameTraceabilityText = await readVerifiedArtifact(
+    inputDirectory,
+    report,
+    "name-traceability",
+    "generation/name-traceability.json",
+  );
+  const nameTraceability =
+    nameTraceabilityText !== undefined
+      ? JSON.parse(nameTraceabilityText)
+      : undefined;
+  for (const artifact of DUMPABLE_ARTIFACTS) {
+    const text = await readVerifiedArtifact(
+      inputDirectory,
+      report,
+      artifact.kind,
+      artifact.filename,
+    );
+    if (text === undefined) continue;
+    await writeDumpFile(
+      inputDirectory,
+      artifact.dumpFilename,
+      artifact.dump(text, areaGraph, sourceFacts, nameTraceability),
+    );
+    dumped.push(artifact.dumpFilename);
+  }
+  return dumped;
+}
+export async function runDumpCli(argv, io = defaultIo) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    io.stdout(DUMP_USAGE);
+    return 0;
+  }
+  let options;
+  try {
+    options = parseDumpArguments(argv);
+  } catch (error) {
+    io.stderr(
+      `${error instanceof Error ? error.message : String(error)}\n\n${DUMP_USAGE}`,
+    );
+    return 2;
+  }
+  try {
+    const dumped = await runDump(options.input);
+    if (dumped.length === 0) {
+      io.stderr(
+        "No dumpable Stage 1 JSON artifacts (area-graph.json, req-model.json, " +
+          `gap-audit.json, diagnostics.json) were recorded in ${options.input}\n`,
+      );
+      return 1;
+    }
+    for (const filename of dumped) {
+      io.stdout(`${join(options.input, filename)}\n`);
+    }
+    return 0;
+  } catch (error) {
+    io.stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+}
+const isDirectExecution =
+  process.argv[1] !== undefined &&
+  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+if (isDirectExecution) {
+  process.exitCode = await runDumpCli(process.argv.slice(2));
+}

package/skills/a2h-app-req-gen/scripts/reqgen/src/generation/artifacts.js

@@ -0,0 +1,49 @@
+import {
+  NAME_TRACEABILITY_FILENAME,
+  buildNameTraceability,
+} from "../analysis/names/index.js";
+import { writeJsonArtifact, writeTextArtifact } from "../pipeline/output.js";
+import { buildQualityReport } from "./quality-report.js";
+import { renderReqDraft, renderReqMarkdown } from "./render.js";
+export const REQ_FILENAME = "req.draft.md";
+export const QUALITY_REPORT_FILENAME = "quality-report.json";
+/**
+ * Write the deterministic generation directory (Stage 1 only).
+ * Writes req.draft.md (deterministic markdown draft for human review).
+ * Stage 2 does NOT read this file — it recomputes from req-model + area-graph. */
+export async function writeDeterministicGenerationArtifacts(
+  outputDirectory,
+  input,
+) {
+  const reqText = renderReqDraft(input.reqModel, input.graph);
+  const nameTraceability = buildNameTraceability({
+    ...input,
+    reqText,
+  });
+  const artifacts = [];
+  artifacts.push(
+    await writeTextArtifact(
+      outputDirectory,
+      REQ_FILENAME,
+      "req-text",
+      renderReqMarkdown(input.reqModel, input.graph),
+    ),
+  );
+  artifacts.push(
+    await writeJsonArtifact(
+      outputDirectory,
+      QUALITY_REPORT_FILENAME,
+      "quality-report",
+      buildQualityReport(input.reqModel),
+    ),
+  );
+  artifacts.push(
+    await writeJsonArtifact(
+      outputDirectory,
+      NAME_TRACEABILITY_FILENAME,
+      "name-traceability",
+      nameTraceability,
+    ),
+  );
+  return { reqText, nameTraceability, artifacts };
+}

package/skills/a2h-app-req-gen/scripts/reqgen/src/generation/index.js

@@ -0,0 +1,18 @@
+export {
+  QUALITY_REPORT_FILENAME,
+  REQ_FILENAME,
+  writeDeterministicGenerationArtifacts,
+} from "./artifacts.js";
+export { buildQualityReport } from "./quality-report.js";
+export {
+  buildAreaContentTxt,
+  renderReqDraft,
+  renderReqMarkdown,
+  renderAllReqTxt,
+  renderReqTxtArea,
+  renderedPath,
+  resolvedName,
+  serializeReqMarkdown,
+  serializeReqTxtAreaContent,
+} from "./render.js";
+export { GENERATION_CONTRACT_VERSION } from "./types.js";

package/skills/a2h-app-req-gen/scripts/reqgen/src/generation/quality-report.js

@@ -0,0 +1,125 @@
+import { GENERATION_CONTRACT_VERSION } from "./types.js";
+function increment(target, key) {
+  target.set(key, (target.get(key) ?? 0) + 1);
+}
+function normalizedMessage(value) {
+  return value.trim().replace(/\s+/gu, " ");
+}
+function featureHasUnknownEffect(feature, unresolvedById) {
+  const interactionEffects =
+    feature.interactions && feature.interactions.length > 0
+      ? feature.interactions.map((interaction) => interaction.effects)
+      : [feature.effects];
+  if (
+    interactionEffects.some(
+      (effects) =>
+        effects.length === 0 ||
+        effects.some((effect) => effect.kind === "unknown"),
+    )
+  )
+    return true;
+  return feature.unresolvedRefs.some((ref) => {
+    const unresolved = unresolvedById.get(ref);
+    return unresolved?.impact.includes("req-feature-effect") === true;
+  });
+}
+export function buildQualityReport(reqModel) {
+  const canonicalPathStatus = {
+    resolved: 0,
+    unreachable: 0,
+    unresolved: 0,
+  };
+  let unknownAreaNames = 0;
+  let areasWithUnresolved = 0;
+  let featureCount = 0;
+  let unknownFeatureNames = 0;
+  let unknownFeatureEffects = 0;
+  let featuresWithUnresolved = 0;
+  const unresolvedById = new Map(
+    reqModel.unresolved.map((item) => [item.id, item]),
+  );
+  for (const area of reqModel.areas) {
+    canonicalPathStatus[area.canonicalPath.status] += 1;
+    if (area.displayName.status === "unresolved") unknownAreaNames += 1;
+    if (area.unresolvedRefs.length > 0) areasWithUnresolved += 1;
+    for (const feature of area.features) {
+      featureCount += 1;
+      if (feature.displayName.status === "unresolved") {
+        unknownFeatureNames += 1;
+      }
+      if (featureHasUnknownEffect(feature, unresolvedById)) {
+        unknownFeatureEffects += 1;
+      }
+      if (feature.unresolvedRefs.length > 0) {
+        featuresWithUnresolved += 1;
+      }
+    }
+  }
+  const reasonCounts = new Map();
+  const impactCounts = new Map();
+  for (const unresolved of reqModel.unresolved) {
+    increment(reasonCounts, unresolved.reasonCode);
+    for (const impact of new Set(unresolved.impact)) {
+      increment(impactCounts, impact);
+    }
+  }
+  const limitationMessages = new Map();
+  let criticalLimitations = 0;
+  const limitations = reqModel.limitations ?? [];
+  for (const limitation of limitations) {
+    if (limitation.critical) criticalLimitations += 1;
+    const message = normalizedMessage(limitation.message);
+    const counts = limitationMessages.get(message) ?? {
+      count: 0,
+      criticalCount: 0,
+      nonCriticalCount: 0,
+    };
+    counts.count += 1;
+    if (limitation.critical) {
+      counts.criticalCount += 1;
+    } else {
+      counts.nonCriticalCount += 1;
+    }
+    limitationMessages.set(message, counts);
+  }
+  const messages = [...limitationMessages]
+    .sort(([left], [right]) => left.localeCompare(right, "en"))
+    .map(([message, counts]) => ({ message, ...counts }));
+  return {
+    contractVersion: GENERATION_CONTRACT_VERSION,
+    artifactKind: "quality-report",
+    caseId: reqModel.caseId,
+    reqModelSchemaVersion: reqModel.schemaVersion,
+    completeness: reqModel.semanticCompleteness ?? "unknown",
+    analysisContext: reqModel.analysisContext,
+    areas: {
+      total: reqModel.areas.length,
+      unknownNameCount: unknownAreaNames,
+      withUnresolvedCount: areasWithUnresolved,
+      canonicalPathStatus,
+    },
+    features: {
+      total: featureCount,
+      unknownNameCount: unknownFeatureNames,
+      unknownEffectCount: unknownFeatureEffects,
+      withUnresolvedCount: featuresWithUnresolved,
+    },
+    unresolved: {
+      total: reqModel.unresolved.length,
+      byReason: [...reasonCounts]
+        .sort(([left], [right]) => left.localeCompare(right, "en"))
+        .map(([reasonCode, count]) => ({ reasonCode, count })),
+      byImpact: [...impactCounts]
+        .sort(([left], [right]) => left.localeCompare(right, "en"))
+        .map(([impact, count]) => ({ impact, count })),
+    },
+    limitations: {
+      total: limitations.length,
+      criticalCount: criticalLimitations,
+      nonCriticalCount: limitations.length - criticalLimitations,
+      uniqueMessageCount: messages.length,
+      duplicateMessageCount: limitations.length - messages.length,
+      messages,
+    },
+  };
+}