@zeyue0329/xiaoma-cli 1.13.0 → 1.15.0

package/tools/validate-step-schemas.js

@@ -0,0 +1,401 @@
+/**
+ * Step Frontmatter Schema Validator (N-series — closes proposal (c) in
+ * pipeline-optimization-report.md)
+ *
+ * Scans every step file under the five auto-* pipelines and validates its
+ * YAML frontmatter against the strict Zod schema in tools/schema/step.js.
+ *
+ * Why this exists:
+ *   E1 (run #3) cleaned up auto-story-pipeline/steps/step-02-create-story.md
+ *   so every auto-* pipeline step file carries only `name` / `description` /
+ *   `nextStepFile` (+ optional `nextStepFile_loop` / `_issues` / `_fail` /
+ *   `_skip` / `altStepFile`) in its frontmatter. The cleanup was enforced by
+ *   convention only — nothing prevented future drift. N2 turns that
+ *   convention into a strict CI-grade lint.
+ *
+ * Scope:
+ *   Only the auto-* pipelines (auto-requirements-pipeline, auto-story-pipeline,
+ *   auto-prd-to-stories, auto-full-pipeline). The auto-story-pipeline-batch
+ *   has no step files (it is a scheduler workflow.md). Step files outside the
+ *   auto-* family (src/core/tasks/xiaoma-create-prd/, src/xmc/workflows/xiaoma-quick-flow/)
+ *   intentionally use a richer frontmatter shape and are NOT validated here.
+ *
+ * Usage:
+ *   node tools/validate-step-schemas.js                 # default (exit 1 on errors)
+ *   node tools/validate-step-schemas.js --verbose       # log every file checked
+ *   node tools/validate-step-schemas.js --strict-kind   # additionally exit 2 when
+ *                                                       # any step file omits the
+ *                                                       # optional `kind` enum
+ *                                                       # field (R2 — promotes the
+ *                                                       # informational adoption
+ *                                                       # histogram into a hard CI
+ *                                                       # gate; safe to enable
+ *                                                       # because the live tree is
+ *                                                       # already 100% adopted).
+ *   node tools/validate-step-schemas.js --emit-doc      # write docs/step-kinds.md
+ *                                                       # (Y1 — auto-generated
+ *                                                       # reference of every step's
+ *                                                       # kind annotation, grouped
+ *                                                       # per pipeline + global
+ *                                                       # histogram).
+ *   node tools/validate-step-schemas.js --emit-doc \
+ *           --dry-run                                   # AA1 (run #25) — print the
+ *                                                       # generated markdown to
+ *                                                       # stdout instead of writing
+ *                                                       # to disk. Closes proposal
+ *                                                       # (ff): lets CI sanity-check
+ *                                                       # the generator without
+ *                                                       # polluting the working tree,
+ *                                                       # and lets local maintainers
+ *                                                       # pipe / diff the output.
+ *                                                       # No-op when --emit-doc is
+ *                                                       # absent.
+ *   node tools/validate-step-schemas.js --check-doc     # drift-check the on-disk
+ *                                                       # doc against the live tree
+ *                                                       # (exit 3 on mismatch;
+ *                                                       # wired into `npm run
+ *                                                       # quality`).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const yaml = require('yaml');
+const {
+  validateStepFrontmatter,
+  verifyStepReferences,
+  verifyPipelineKindInvariants,
+  formatStepKindsDoc,
+  KIND_VALUES,
+} = require('./schema/step.js');
+
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+const VERBOSE = process.argv.includes('--verbose');
+// R2 (run #16) — opt-in hard gate on the otherwise-informational kind histogram.
+// When --strict-kind is passed and any step file omits `kind`, exit with code 2
+// (distinct from the schema-failure exit 1 so CI dashboards can distinguish
+// "frontmatter shape broken" from "kind annotation missing"). The flag is safe
+// to wire into the quality chain only after the live tree reaches 100% adoption
+// — Q1–Q3 (run #15) achieved that, so this gate now defends against regression.
+const STRICT_KIND = process.argv.includes('--strict-kind');
+
+// Y1 (run #23) — opt-in emit/check modes for docs/step-kinds.md. EMIT_DOC writes
+// the generated markdown to the default doc path; CHECK_DOC re-generates in
+// memory and compares against the on-disk file (exit 3 on drift, distinct from
+// the schema-failure exit 1 and the strict-kind exit 2 so CI dashboards can
+// tell apart "schema broken" / "kind missing" / "doc stale"). Both modes still
+// require schema validation + the strict-kind gate to pass first, so a single
+// invocation can validate + emit/check in one pass.
+const EMIT_DOC = process.argv.includes('--emit-doc');
+const CHECK_DOC = process.argv.includes('--check-doc');
+// AA1 (run #25) — opt-in companion to --emit-doc that prints the generated
+// markdown to stdout instead of writing it to disk. Closes proposal (ff) from
+// run #23 §7. Useful for (a) CI sanity-checking the generator without dirtying
+// the working tree, (b) piping the output into shell tools (diff, less, grep),
+// and (c) local maintainers previewing a kind change before committing the
+// regenerated doc. Silently ignored unless --emit-doc is also passed.
+const DRY_RUN = process.argv.includes('--dry-run');
+const DEFAULT_DOC_PATH = 'docs/step-kinds.md';
+
+// Pipeline roots whose step files MUST conform to the strict step schema.
+// Each entry is a directory containing step-NN-*.md files.
+const PIPELINE_STEP_DIRS = [
+  'src/xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline/steps',
+  'src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline/steps',
+  'src/xmc-skills/5-full-pipeline/xiaoma-auto-full-pipeline/steps',
+  'src/xmc-skills/5-full-pipeline/xiaoma-auto-prd-to-stories/steps',
+];
+
+function listStepFiles(dirRelative) {
+  const dirAbs = path.join(PROJECT_ROOT, dirRelative);
+  if (!fs.existsSync(dirAbs)) return [];
+  return fs
+    .readdirSync(dirAbs)
+    .filter((f) => /^step-\d{2}[a-z]?-.*\.md$/.test(f))
+    .map((f) => path.join(dirRelative, f))
+    .sort();
+}
+
+// Extract the YAML frontmatter block from a step file. Returns null when the
+// file has no frontmatter (which is itself an error for auto-* step files).
+function extractFrontmatter(absPath) {
+  const content = fs.readFileSync(absPath, 'utf8');
+  const lines = content.split('\n');
+
+  if (lines[0] !== '---') {
+    return { ok: false, reason: 'missing opening "---" delimiter (file has no YAML frontmatter)' };
+  }
+
+  let closingIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') {
+      closingIndex = i;
+      break;
+    }
+  }
+  if (closingIndex === -1) {
+    return { ok: false, reason: 'frontmatter is not terminated (no closing "---")' };
+  }
+
+  const yamlBlock = lines.slice(1, closingIndex).join('\n');
+  try {
+    const parsed = yaml.parse(yamlBlock);
+    return { ok: true, frontmatter: parsed };
+  } catch (error) {
+    return { ok: false, reason: `frontmatter YAML parse error: ${error.message}` };
+  }
+}
+
+// Verify that every `nextStepFile*` reference points to a sibling file that
+// actually exists on disk. Delegates to the shared verifyStepReferences in
+// tools/schema/step.js (O1) so the same routine is exercised by the unit tests
+// in test/test-step-schema.js. This wrapper only formats the issues into the
+// project-relative lines the CLI walker prints.
+function verifyReferences(relPath, frontmatter) {
+  const dirAbsolute = path.join(PROJECT_ROOT, path.dirname(relPath));
+  const issues = verifyStepReferences(dirAbsolute, frontmatter);
+  return issues.map(({ key, value, targetAbsolute }) => {
+    const targetRelative = path.relative(PROJECT_ROOT, targetAbsolute);
+    return `${key} → ${value} (file not found at ${targetRelative})`;
+  });
+}
+
+function formatZodErrors(zodError) {
+  return zodError.errors
+    .map((issue) => {
+      const fieldPath = issue.path.length === 0 ? '<root>' : issue.path.join('.');
+      return `    - ${fieldPath}: ${issue.message}`;
+    })
+    .join('\n');
+}
+
+function main() {
+  console.log('Step Frontmatter Schema Validator\n');
+
+  let totalFiles = 0;
+  let okCount = 0;
+  const failures = [];
+
+  // Q4 (run #15) — kind-distribution histogram. Tracks the optional `kind` enum
+  // field (introduced by P1 in run #14) across every successfully-validated step
+  // file. The "unclassified" bucket counts files that omit the field entirely.
+  // Adoption progress is the ratio (totalFiles - unclassified) / totalFiles.
+  const kindCounts = Object.fromEntries(KIND_VALUES.map((v) => [v, 0]));
+  kindCounts.unclassified = 0;
+  // Track which pipeline each kind-tagged file belongs to, so the histogram
+  // can be broken down per pipeline when --verbose is enabled.
+  const perPipelineKindCounts = {};
+
+  // S2 (run #17) — collect per-pipeline ordered step descriptors so we can run
+  // pipeline-shape invariants (e.g. bridge-position) after the per-file checks.
+  const perPipelineSteps = {};
+
+  for (const dir of PIPELINE_STEP_DIRS) {
+    const stepFiles = listStepFiles(dir);
+    if (stepFiles.length === 0) {
+      console.warn(`  WARN: no step files found in ${dir}`);
+      continue;
+    }
+
+    for (const relPath of stepFiles) {
+      totalFiles++;
+      const absPath = path.join(PROJECT_ROOT, relPath);
+
+      const extract = extractFrontmatter(absPath);
+      if (!extract.ok) {
+        failures.push({ relPath, reason: extract.reason });
+        continue;
+      }
+
+      const result = validateStepFrontmatter(relPath, extract.frontmatter);
+      if (!result.success) {
+        failures.push({
+          relPath,
+          reason: 'schema validation failed:\n' + formatZodErrors(result.error),
+        });
+        continue;
+      }
+
+      const refIssues = verifyReferences(relPath, extract.frontmatter);
+      if (refIssues.length > 0) {
+        failures.push({
+          relPath,
+          reason: 'broken next-step reference(s):\n' + refIssues.map((line) => `    - ${line}`).join('\n'),
+        });
+        continue;
+      }
+
+      okCount++;
+
+      // Q4 (run #15) — tally kind distribution for this OK file.
+      const fmKind = extract.frontmatter && typeof extract.frontmatter === 'object' ? extract.frontmatter.kind : undefined;
+      const bucket = fmKind && Object.prototype.hasOwnProperty.call(kindCounts, fmKind) ? fmKind : 'unclassified';
+      kindCounts[bucket]++;
+      if (!perPipelineKindCounts[dir]) {
+        perPipelineKindCounts[dir] = Object.fromEntries(KIND_VALUES.map((v) => [v, 0]));
+        perPipelineKindCounts[dir].unclassified = 0;
+      }
+      perPipelineKindCounts[dir][bucket]++;
+
+      // S2 (run #17) — record this step's name + kind in pipeline order for the
+      // post-loop pipeline-shape invariant pass. The file list was already sorted
+      // by listStepFiles, so insertion order here matches on-disk step order.
+      // U1 (run #19) — also propagate `nextStepFile_loop` so the
+      // loop-self-reference invariant can validate it without re-parsing.
+      if (!perPipelineSteps[dir]) perPipelineSteps[dir] = [];
+      perPipelineSteps[dir].push({
+        name: extract.frontmatter.name,
+        kind: fmKind,
+        nextStepFile_loop: extract.frontmatter.nextStepFile_loop,
+        // Y1 (run #23) — also carry the human-readable description so
+        // `formatStepKindsDoc` can render it in the docs/step-kinds.md
+        // table. The field is unused by `verifyPipelineKindInvariants`
+        // (which only inspects name/kind/nextStepFile_loop) and is
+        // therefore opt-in additional context.
+        description: extract.frontmatter.description,
+        // AB1 (run #26) — main-flow + conditional `nextStepFile*` references
+        // feed `formatMermaidFlowchart` (invoked from `formatStepKindsDoc`)
+        // so each pipeline gets a visual graph. Unused by the existing
+        // invariant rules so the additional fields stay backward-compatible.
+        nextStepFile: extract.frontmatter.nextStepFile,
+        nextStepFile_issues: extract.frontmatter.nextStepFile_issues,
+        nextStepFile_fail: extract.frontmatter.nextStepFile_fail,
+        nextStepFile_skip: extract.frontmatter.nextStepFile_skip,
+        altStepFile: extract.frontmatter.altStepFile,
+      });
+
+      if (VERBOSE) {
+        const kindSuffix = fmKind ? ` [kind=${fmKind}]` : ' [kind=unclassified]';
+        console.log(`  OK  ${relPath}${kindSuffix}`);
+      }
+    }
+  }
+
+  // S2 (run #17) — run pipeline-shape invariants per pipeline. Violations
+  // become failures with rule + pipeline labels so operators see immediately
+  // which pipeline broke which rule. The current ruleset (one rule: bridge
+  // position) is checked by `verifyPipelineKindInvariants` in the shared
+  // schema module so unit tests exercise the same code path.
+  for (const dir of PIPELINE_STEP_DIRS) {
+    const steps = perPipelineSteps[dir];
+    if (!steps || steps.length === 0) continue;
+    const invariantIssues = verifyPipelineKindInvariants(steps);
+    if (invariantIssues.length === 0) continue;
+    const pipelineLabel = dir.split('/').at(-2);
+    for (const issue of invariantIssues) {
+      failures.push({
+        relPath: `${dir}/${issue.name}.md`,
+        reason: `pipeline-shape invariant violated [${issue.rule}] in ${pipelineLabel}:\n    - ${issue.message}`,
+      });
+    }
+  }
+
+  console.log('');
+  console.log(`Files scanned:     ${totalFiles}`);
+  console.log(`OK:                ${okCount}`);
+  console.log(`Failures:          ${failures.length}`);
+  console.log('');
+
+  // Q4 (run #15) — print the kind distribution histogram. Display the enum
+  // values in declaration order followed by the unclassified bucket so the
+  // adoption gap (= unclassified count) reads at a glance.
+  if (okCount > 0) {
+    const adopted = okCount - kindCounts.unclassified;
+    const adoptionPct = okCount === 0 ? 0 : Math.round((adopted / okCount) * 100);
+    console.log(`Kind distribution (P1 adoption: ${adopted}/${okCount} = ${adoptionPct}%):`);
+    for (const kindValue of KIND_VALUES) {
+      console.log(`  ${kindValue.padEnd(13)} ${kindCounts[kindValue]}`);
+    }
+    console.log(`  ${'unclassified'.padEnd(13)} ${kindCounts.unclassified}`);
+    console.log('');
+    if (VERBOSE) {
+      console.log('Per-pipeline kind distribution:');
+      for (const dir of PIPELINE_STEP_DIRS) {
+        const counts = perPipelineKindCounts[dir];
+        if (!counts) continue;
+        const pipelineLabel = dir.split('/').at(-2);
+        const breakdown = [...KIND_VALUES, 'unclassified']
+          .filter((k) => counts[k] > 0)
+          .map((k) => `${k}=${counts[k]}`)
+          .join(', ');
+        console.log(`  ${pipelineLabel.padEnd(28)} ${breakdown}`);
+      }
+      console.log('');
+    }
+  }
+
+  if (failures.length > 0) {
+    console.error('Schema validation failures:\n');
+    for (const failure of failures) {
+      console.error(`  ✗ ${failure.relPath}`);
+      console.error(`    ${failure.reason.split('\n').join('\n    ')}`);
+      console.error('');
+    }
+    process.exit(1);
+  }
+
+  // R2 (run #16) — strict-kind gate. Runs only after the schema layer passes
+  // (so we never mask a schema failure with a kind-adoption failure). Exit code
+  // 2 is intentionally distinct from the schema-failure exit code 1.
+  if (STRICT_KIND && kindCounts.unclassified > 0) {
+    console.error(`Strict-kind mode: ${kindCounts.unclassified} step file(s) omit the optional "kind" field.`);
+    console.error('Re-run without --strict-kind to inspect the histogram, or annotate the missing files.');
+    process.exit(2);
+  }
+
+  // Y1 (run #23) — emit/check docs/step-kinds.md. Both modes run after the
+  // schema + strict-kind gates so we never emit a doc from a broken tree.
+  // The pipeline label for the heading is the parent directory name (e.g.
+  // `auto-requirements-pipeline`), matching how the rest of the report and
+  // walker label pipelines.
+  if (EMIT_DOC || CHECK_DOC) {
+    const pipelinesForDoc = PIPELINE_STEP_DIRS.filter((dir) => perPipelineSteps[dir]).map((dir) => ({
+      label: dir.split('/').at(-2),
+      steps: perPipelineSteps[dir],
+    }));
+    const generated = formatStepKindsDoc(pipelinesForDoc);
+    const docAbsolute = path.join(PROJECT_ROOT, DEFAULT_DOC_PATH);
+
+    if (EMIT_DOC) {
+      // AA1 (run #25) — --dry-run companion: print to stdout instead of
+      // writing to disk. The marker line `--- docs/step-kinds.md (dry-run, N bytes) ---`
+      // (built from DEFAULT_DOC_PATH so the comment cannot drift from the
+      // emitted bytes — AC1 / run #27 fixed a pre-existing drift where this
+      // comment said `step-kinds.md` while the actual marker line included
+      // the `docs/` prefix) before and after the doc body makes the boundary
+      // obvious when piped alongside other stdout content (e.g. the
+      // schema-validator summary above). Writes go to stdout (not stderr) so
+      // shell pipelines like
+      // `node tools/validate-step-schemas.js --emit-doc --dry-run | diff -
+      // docs/step-kinds.md` Just Work.
+      if (DRY_RUN) {
+        const marker = `--- ${DEFAULT_DOC_PATH} (dry-run, ${generated.length} bytes) ---`;
+        process.stdout.write(`${marker}\n${generated}${marker}\n`);
+        console.log(`Dry-run: would have emitted ${DEFAULT_DOC_PATH} (${generated.length} bytes).`);
+      } else {
+        fs.mkdirSync(path.dirname(docAbsolute), { recursive: true });
+        fs.writeFileSync(docAbsolute, generated, 'utf8');
+        console.log(`Emitted ${DEFAULT_DOC_PATH} (${generated.length} bytes).`);
+      }
+    } else {
+      // CHECK_DOC — drift detection. Exit 3 distinguishes "doc stale" from
+      // schema-failure (1) and strict-kind (2). Missing file is a drift.
+      if (!fs.existsSync(docAbsolute)) {
+        console.error(`Doc drift: ${DEFAULT_DOC_PATH} is missing on disk.`);
+        console.error('Run `node tools/validate-step-schemas.js --emit-doc` to generate it.');
+        process.exit(3);
+      }
+      const onDisk = fs.readFileSync(docAbsolute, 'utf8');
+      if (onDisk !== generated) {
+        console.error(`Doc drift: ${DEFAULT_DOC_PATH} differs from the live step tree.`);
+        console.error('Run `node tools/validate-step-schemas.js --emit-doc` to regenerate it, then commit the change.');
+        process.exit(3);
+      }
+      console.log(`${DEFAULT_DOC_PATH} is in sync with the live step tree.`);
+    }
+  }
+
+  console.log('All step files pass strict schema validation.');
+  process.exit(0);
+}
+
+main();

package/tools/validate-svg-changes.sh

@@ -10,7 +10,7 @@
 
 set -e
 
-SVG_FILE="${1:-src/bmm/docs/images/workflow-method-greenfield.svg}"
+SVG_FILE="${1:?Usage: ./tools/validate-svg-changes.sh <path-to-svg>}"
 TMP_DIR="/tmp/svg-validation-$$"
 
 echo "🎨 Visual SVG Validation"