@zeyue0329/xiaoma-cli 1.13.0 → 1.15.1

package/tools/validate-frontmatter-prose-routing.js

@@ -0,0 +1,334 @@
+/**
+ * Frontmatter ↔ Prose Routing Consistency Validator (AU-series — run #45)
+ *
+ * Cross-checks each step file's frontmatter routing keys (`nextStepFile`,
+ * `nextStepFile_fail`, `nextStepFile_issues`, `nextStepFile_loop`, etc.)
+ * against the in-prose `**NEXT:**` annotations that look like:
+ *
+ *   - **NEXT:** Proceed to step-06 (test story) [frontmatter: nextStepFile]
+ *
+ * Why this exists:
+ *  - Several past defects (AT1: "到step-07" typo in the PASS path of step-06)
+ *    were caused by prose routing instructions drifting out of sync with the
+ *    canonical frontmatter routing values. The `[frontmatter: keyName]`
+ *    tag is the existing convention; this script enforces that it actually
+ *    matches the frontmatter target.
+ *
+ * Three checks per pipeline:
+ *
+ *   FORWARD (annotation → frontmatter):
+ *     For each `**NEXT:** ... step-NN ... [frontmatter: keyName]` literal:
+ *       a. Frontmatter must define `keyName`.
+ *       b. The value of `keyName` must reference `./step-NN-*.md` —
+ *          i.e. the NN in prose equals the NN embedded in the frontmatter
+ *          path basename.
+ *
+ *   REVERSE (frontmatter → annotation):
+ *     For step files that branch (have more than one `nextStepFile*` key,
+ *     OR define any explicit *non-default* routing key such as
+ *     `nextStepFile_fail` / `nextStepFile_issues` / `nextStepFile_loop`):
+ *       Every routing key declared in frontmatter must be referenced by at
+ *       least one `[frontmatter: keyName]` prose annotation.
+ *     For single-target steps (only `nextStepFile`, no alt branches), the
+ *     reverse check is skipped — the unambiguous default does not require
+ *     in-prose disambiguation.
+ *
+ *   SHORT-FORM (AV-series, run #46):
+ *     For any `**NEXT:** ...` line that references `step-NN` in *short form*
+ *     (i.e., the `step-NN` token is NOT immediately followed by a kebab
+ *     filename like `step-NN-name.md` — path-form lines are self-checking
+ *     against the file system and skipped):
+ *       The line MUST carry a `[frontmatter: keyName]` annotation so the
+ *       FORWARD check can verify the NN against the frontmatter target.
+ *     Without this rule, an orphan line like `**NEXT:** Proceed to step-04`
+ *     could drift silently after a renumber. AV1 (run #46) closed the one
+ *     surviving orphan; this rule prevents recurrence.
+ *
+ * Scope (step files with frontmatter routing):
+ *   - src/xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline/steps/
+ *   - src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline/steps/
+ *
+ * Output format (per pipeline):
+ *   [pipeline-name]
+ *     Forward (annotation → frontmatter): N/M annotations matched
+ *       MISS: <file>:LINE  step-NN [frontmatter: keyName] -> <reason>
+ *     Reverse (frontmatter → annotation): N/M branching keys covered
+ *       MISS: <file>  keyName -> not referenced by any [frontmatter: keyName] annotation
+ *
+ * Exit codes:
+ *   0 — all checks pass
+ *   1 — at least one drift found
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+
+const PIPELINES = [
+  {
+    name: 'auto-requirements-pipeline',
+    stepsDir: path.join(PROJECT_ROOT, 'src/xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline/steps'),
+  },
+  {
+    name: 'auto-story-pipeline',
+    stepsDir: path.join(PROJECT_ROOT, 'src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline/steps'),
+  },
+];
+
+// `**NEXT:** ... step-NN ... [frontmatter: keyName]`
+// Capture step number and frontmatter key name.
+// Allow leading whitespace, list bullets, and any prose between markers.
+const ANNOTATION_RE = /\*\*NEXT:\*\*[^\n]*?step-(\d+)[^\n]*?\[frontmatter:\s*(nextStepFile[A-Za-z_]*)\]/g;
+
+// Any line containing `**NEXT:**` (used for the SHORT-FORM line-level check).
+const NEXT_LINE_RE = /\*\*NEXT:\*\*/;
+
+// `step-NN` references inside a single line.
+// Two flavours:
+//   - PATH-FORM:  `step-NN-kebab-name.md` (self-checking against the FS — skip)
+//   - SHORT-FORM: `step-NN` NOT immediately followed by `-letter` (needs annotation)
+// We discriminate by whether the char after the full `step-NN` is `-[a-z]`.
+// The `(?!\d)` lookahead prevents `\d+` from backtracking and matching a
+// prefix (e.g., capturing `0` from `step-02-...` would otherwise pass the
+// `(?!-[a-z])` check incorrectly).
+const STEP_REF_RE = /step-(\d+)(?!\d)(?!-[a-z])/g;
+
+// Frontmatter routing key line, e.g.
+//   nextStepFile: "./step-06-test-story.md"
+//   nextStepFile_fail: './step-07-fix-and-retest.md'
+//   nextStepFile: null
+const ROUTING_KEY_RE = /^(nextStepFile[A-Za-z_]*)\s*:\s*(.+?)\s*$/;
+
+// Inside a routing key value, pull the step-NN- prefix from the basename.
+const STEP_NUM_RE = /step-(\d+)-/;
+
+function parseFrontmatter(content, file) {
+  // Frontmatter is delimited by --- on its own lines at the top of the file.
+  const lines = content.split('\n');
+  if (lines[0].trim() !== '---') {
+    return { keys: {}, endLine: 0 };
+  }
+  const keys = {};
+  let endLine = -1;
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '---') {
+      endLine = i;
+      break;
+    }
+    const m = line.match(ROUTING_KEY_RE);
+    if (m) {
+      const rawValue = m[2].replaceAll(/^["']|["']$/g, '').trim();
+      keys[m[1]] = { rawValue, lineNumber: i + 1 };
+    }
+  }
+  if (endLine === -1) {
+    throw new Error(`Unterminated frontmatter in ${file}`);
+  }
+  return { keys, endLine: endLine + 1 };
+}
+
+function extractStepNumberFromValue(value) {
+  if (!value || value === 'null') return null;
+  // Strip leading ./ and any quotes already stripped.
+  const basename = path.basename(value);
+  const m = basename.match(STEP_NUM_RE);
+  return m ? parseInt(m[1], 10) : null;
+}
+
+function scanAnnotations(content, frontmatterEndLine) {
+  const annotations = [];
+  // Reset regex state.
+  ANNOTATION_RE.lastIndex = 0;
+  let match;
+  while ((match = ANNOTATION_RE.exec(content)) !== null) {
+    const promptedNum = parseInt(match[1], 10);
+    const keyName = match[2];
+    // Compute line number of the match.
+    const upTo = content.slice(0, match.index);
+    const lineNumber = upTo.split('\n').length;
+    if (lineNumber <= frontmatterEndLine) continue;
+    annotations.push({ promptedNum, keyName, lineNumber, raw: match[0] });
+  }
+  return annotations;
+}
+
+function scanShortFormDrifts(content, frontmatterEndLine, rel) {
+  // Walk line-by-line looking for `**NEXT:**` lines that reference `step-NN` in
+  // short form (no kebab basename suffix). Such lines must carry a
+  // `[frontmatter: keyName]` annotation so the FORWARD check can verify them.
+  const lines = content.split('\n');
+  const drifts = [];
+  let shortFormOk = 0;
+  let shortFormTotal = 0;
+
+  for (const [i, line] of lines.entries()) {
+    const lineNumber = i + 1;
+    if (lineNumber <= frontmatterEndLine) continue;
+    if (!NEXT_LINE_RE.test(line)) continue;
+
+    // Collect short-form refs in this line. We deliberately do NOT count
+    // path-form refs (e.g., `step-04-develop-story.md`) because the path is
+    // self-validating against the file system.
+    STEP_REF_RE.lastIndex = 0;
+    const shortFormRefs = [];
+    let m;
+    while ((m = STEP_REF_RE.exec(line)) !== null) {
+      shortFormRefs.push(parseInt(m[1], 10));
+    }
+    if (shortFormRefs.length === 0) continue;
+
+    shortFormTotal++;
+    if (line.includes('[frontmatter:')) {
+      shortFormOk++;
+      continue;
+    }
+
+    drifts.push({
+      kind: 'short-form-missing-annotation',
+      file: rel,
+      lineNumber,
+      detail: `Line contains \`**NEXT:**\` with short-form step reference(s) [${shortFormRefs.map((n) => `step-${String(n).padStart(2, '0')}`).join(', ')}] but no \`[frontmatter: keyName]\` annotation. Add an annotation so the FORWARD check can verify the target against the frontmatter routing key.`,
+    });
+  }
+
+  return { drifts, shortFormOk, shortFormTotal };
+}
+
+function validatePipeline(pipeline) {
+  const drifts = [];
+  let forwardOk = 0;
+  let forwardTotal = 0;
+  let reverseOk = 0;
+  let reverseTotal = 0;
+  let shortFormOk = 0;
+  let shortFormTotal = 0;
+
+  if (!fs.existsSync(pipeline.stepsDir)) {
+    return { drifts: [{ kind: 'missing-pipeline', detail: `Steps dir not found: ${pipeline.stepsDir}` }] };
+  }
+
+  const stepFiles = fs
+    .readdirSync(pipeline.stepsDir)
+    .filter((f) => /^step-\d+.*\.md$/.test(f))
+    .filter((f) => !f.endsWith('.bak'))
+    .sort();
+
+  for (const stepFile of stepFiles) {
+    const absPath = path.join(pipeline.stepsDir, stepFile);
+    const rel = path.relative(PROJECT_ROOT, absPath);
+    const content = fs.readFileSync(absPath, 'utf8');
+    const { keys: routingKeys, endLine } = parseFrontmatter(content, rel);
+    const annotations = scanAnnotations(content, endLine);
+
+    // SHORT-FORM: lines with `**NEXT:**` + short-form `step-NN` ref must carry an annotation.
+    const sf = scanShortFormDrifts(content, endLine, rel);
+    shortFormOk += sf.shortFormOk;
+    shortFormTotal += sf.shortFormTotal;
+    drifts.push(...sf.drifts);
+
+    // FORWARD: each annotation must agree with frontmatter target.
+    for (const ann of annotations) {
+      forwardTotal++;
+      const fm = routingKeys[ann.keyName];
+      if (!fm) {
+        drifts.push({
+          kind: 'forward-missing-key',
+          file: rel,
+          lineNumber: ann.lineNumber,
+          detail: `Annotation references [frontmatter: ${ann.keyName}] but that key is not declared in the frontmatter. Declared keys: ${Object.keys(routingKeys).join(', ') || '(none)'}.`,
+        });
+        continue;
+      }
+      const fmNum = extractStepNumberFromValue(fm.rawValue);
+      if (fmNum === null) {
+        drifts.push({
+          kind: 'forward-unresolvable-target',
+          file: rel,
+          lineNumber: ann.lineNumber,
+          detail: `Annotation [frontmatter: ${ann.keyName}] references prose step-${String(ann.promptedNum).padStart(2, '0')}, but frontmatter value '${fm.rawValue}' cannot be resolved to a step number.`,
+        });
+        continue;
+      }
+      if (fmNum !== ann.promptedNum) {
+        drifts.push({
+          kind: 'forward-mismatch',
+          file: rel,
+          lineNumber: ann.lineNumber,
+          detail: `Prose says step-${String(ann.promptedNum).padStart(2, '0')} but frontmatter[${ann.keyName}]='${fm.rawValue}' resolves to step-${String(fmNum).padStart(2, '0')}.`,
+        });
+        continue;
+      }
+      forwardOk++;
+    }
+
+    // REVERSE: for branching steps, every routing key must be cited at least once in prose.
+    const routingKeyNames = Object.keys(routingKeys);
+    const branching = routingKeyNames.length > 1 || routingKeyNames.some((k) => k !== 'nextStepFile');
+    if (!branching) continue;
+
+    const citedKeyNames = new Set(annotations.map((a) => a.keyName));
+    for (const k of routingKeyNames) {
+      // Skip null-valued terminal routes (e.g., nextStepFile: null in finalize steps).
+      if (extractStepNumberFromValue(routingKeys[k].rawValue) === null) continue;
+      reverseTotal++;
+      if (citedKeyNames.has(k)) {
+        reverseOk++;
+      } else {
+        drifts.push({
+          kind: 'reverse-uncited-key',
+          file: rel,
+          lineNumber: routingKeys[k].lineNumber,
+          detail: `Branching step declares frontmatter[${k}] but no prose '**NEXT:** ... [frontmatter: ${k}]' annotation references it.`,
+        });
+      }
+    }
+  }
+
+  return { drifts, forwardOk, forwardTotal, reverseOk, reverseTotal, shortFormOk, shortFormTotal };
+}
+
+function main() {
+  console.log('');
+  console.log(`Validating frontmatter ↔ prose routing consistency in: ${PROJECT_ROOT}`);
+  console.log('');
+
+  let totalDrifts = 0;
+  for (const p of PIPELINES) {
+    const result = validatePipeline(p);
+    console.log(`[${p.name}]`);
+    if (result.drifts.length === 0) {
+      console.log(`  Forward (annotation → frontmatter): ${result.forwardOk}/${result.forwardTotal} annotations matched`);
+      console.log(`  Reverse (frontmatter → annotation): ${result.reverseOk}/${result.reverseTotal} branching keys covered`);
+      console.log(
+        `  Short-form (**NEXT:** w/o path needs [frontmatter:]): ${result.shortFormOk}/${result.shortFormTotal} short-form lines annotated`,
+      );
+      console.log('');
+      continue;
+    }
+    console.log(`  Forward (annotation → frontmatter): ${result.forwardOk}/${result.forwardTotal} annotations matched`);
+    console.log(`  Reverse (frontmatter → annotation): ${result.reverseOk}/${result.reverseTotal} branching keys covered`);
+    console.log(
+      `  Short-form (**NEXT:** w/o path needs [frontmatter:]): ${result.shortFormOk}/${result.shortFormTotal} short-form lines annotated`,
+    );
+    console.log('  Drift details:');
+    for (const d of result.drifts) {
+      const locator = d.lineNumber ? `${d.file}:${d.lineNumber}` : d.file || '(?)';
+      console.log(`    [${d.kind}] ${locator}`);
+      console.log(`      ${d.detail}`);
+    }
+    console.log('');
+    totalDrifts += result.drifts.length;
+  }
+
+  if (totalDrifts > 0) {
+    console.log(`FAILED: ${totalDrifts} drift(s) found across ${PIPELINES.length} pipeline(s).`);
+    process.exit(1);
+  }
+  console.log('All frontmatter routing keys agree with their in-prose annotations.');
+}
+
+main();