@educa-corp/sdd-framework 0.9.2 → 0.9.3

package/scripts/migrate-qc-docs.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * migrate-qc-docs — move per-UC QC working docs into the per-PRD layout.
+ *
+ *   docs/{TICKET-ID}-UC{N}/{platform}/…
+ *     → docs/{TICKET-ID}/{platform}/…
+ *
+ * The per-UC layout shattered one feature across N sibling folders (10 UCs = 10 root
+ * folders, 30 files). It was the framework's own imposition when the QC skills were
+ * ported: upstream has always been PRD-scoped — their real file is `DOC_GAP_FEAT-02-3.md`
+ * (no UC suffix), the gap-ID format `GAP-<UC>-001` only means anything when ONE file holds
+ * several UCs, and `qa-planner/test-plan.md` says "Test Plan cho một feature". See B11.
+ *
+ * WHY THIS SCRIPT DOES NOT MERGE. Collapsing N UC folders into one makes UC1's
+ * REQUIREMENT_ANALYSIS.md and UC2's collide on the same target path, and two prose
+ * documents cannot be merged mechanically. So:
+ *
+ *   test-cases/*   → MOVED   (filenames carry <FEATURE>, they do not collide)
+ *   the 3 top docs → ARCHIVED to {qc}/_archive-per-uc/{UC-ID}/{platform}/
+ *                    and listed as NEEDS REGENERATE
+ *
+ * Regenerating beats hand-merging: a PRD-level pass reads the PRD, design-spec and
+ * tech-doc ONCE instead of once per UC, and it sees cross-UC contradictions that N
+ * separate passes structurally cannot. Nothing is deleted — the archive is the way back,
+ * and the only way to check whether the PRD-level run caught anything the old ones missed.
+ *
+ * Also folds in the pending `DOC_GAPS.md` → `DOC_GAP.md` rename (B9), in the same pass,
+ * including for folders that are ALREADY in the new layout. Without it `/qc-plan` reports
+ * "DOC_GAP not found" while the analysis sits right there under the old name.
+ *
+ * Reports (does NOT guess) two conditions that need a human:
+ *   - NO PLATFORM : files sit directly under {qc}/{UC-ID}/ with no platform level. The
+ *                   platform cannot be inferred from a QC artifact, so they are left alone.
+ *   - OCCUPIED    : the target path already holds a file — moving would overwrite it.
+ *
+ * DRY-RUN by default (prints the plan, changes nothing). Pass --apply to execute.
+ * Tracked files move with `git mv` to preserve history; the rest with fs.rename.
+ *
+ * Usage (from the consumer project root):
+ *   node scripts/migrate-qc-docs.js                 # dry-run, prints plan
+ *   node scripts/migrate-qc-docs.js --apply         # execute
+ *   node scripts/migrate-qc-docs.js --qc docs --root .
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// ── args ──────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2);
+const has = f => argv.includes(f);
+const flag = (f, d) => { const i = argv.indexOf(f); return i !== -1 ? argv[i + 1] : d; };
+
+const APPLY = has('--apply');
+const ROOT = path.resolve(flag('--root', '.'));
+const QC = flag('--qc', 'docs');
+
+const qcAbs = path.join(ROOT, QC);
+const ARCHIVE = '_archive-per-uc';
+
+// The three PRD-level documents. Anything else at that level is archived too (safe
+// default) but called out separately so nobody loses a file without seeing its name.
+const TOP_DOCS = ['REQUIREMENT_ANALYSIS.md', 'DOC_GAP.md', 'DOC_GAPS.md', 'TEST_PLAN.md'];
+
+// `{TICKET-ID}-UC{N}` — the framework's UC-ID contract (steps/gate.md Bước 1: TICKET-ID is
+// the part before `-UC`). Anchored at both ends so `FEAT-01-2-UC1` matches but a folder
+// that merely contains the letters "uc" does not.
+const UC_DIR = /^(.+)-UC(\d+)$/i;
+
+// ── git tracked set (for `git mv`) ────────────────────────────────────────────
+let tracked = null;
+try {
+  const out = execSync('git ls-files', { cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  tracked = new Set(out.split('\n').filter(Boolean).map(p => p.replace(/\\/g, '/')));
+} catch { tracked = null; }
+
+const rel = abs => path.relative(ROOT, abs).replace(/\\/g, '/');
+const isTracked = abs => !!(tracked && tracked.has(rel(abs)));
+const isDir = p => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+
+function walk(dir) {
+  let out = [];
+  if (!isDir(dir)) return out;
+  for (const n of fs.readdirSync(dir)) {
+    const p = path.join(dir, n);
+    out = out.concat(isDir(p) ? walk(p) : [p]);
+  }
+  return out;
+}
+
+// ── plan ──────────────────────────────────────────────────────────────────────
+const moves = [];       // { from, to, kind }
+const noPlatform = [];  // { ucDir, files }
+const occupied = [];    // { from, to }
+const regen = new Map();// "TICKET|platform" → { ticket, platform, ucs:Set }
+
+if (!isDir(qcAbs)) {
+  console.log(`\n${QC}/ does not exist under ${ROOT} — nothing to migrate.\n`);
+  process.exit(0);
+}
+
+const ucDirs = fs.readdirSync(qcAbs)
+  .filter(n => n !== ARCHIVE)
+  .map(n => ({ name: n, abs: path.join(qcAbs, n) }))
+  .filter(d => isDir(d.abs) && UC_DIR.test(d.name));
+
+function plan(from, to, kind) {
+  // Never overwrite, and never let two sources land on one target.
+  if (fs.existsSync(to) || moves.some(m => m.to === to)) { occupied.push({ from, to }); return; }
+  moves.push({ from, to, kind });
+}
+
+for (const d of ucDirs) {
+  const m = UC_DIR.exec(d.name);
+  const ticket = m[1];
+  const ucNum = m[2];
+  const ucId = d.name;
+
+  // Files sitting directly under {qc}/{UC-ID}/ mean the platform level is absent. A QC
+  // artifact carries no @trace.platform, so there is nothing to infer it from — leave them.
+  const loose = fs.readdirSync(d.abs).filter(x => !isDir(path.join(d.abs, x)));
+  if (loose.length) noPlatform.push({ ucDir: ucId, files: loose });
+
+  for (const platform of fs.readdirSync(d.abs).filter(x => isDir(path.join(d.abs, x)))) {
+    const src = path.join(d.abs, platform);
+
+    const key = `${ticket}|${platform}`;
+    if (!regen.has(key)) regen.set(key, { ticket, platform, ucs: new Set() });
+    regen.get(key).ucs.add(`UC${ucNum}`);
+
+    for (const abs of walk(src)) {
+      const within = path.relative(src, abs).replace(/\\/g, '/');
+      const base = path.basename(abs);
+
+      if (within.startsWith('test-cases/')) {
+        // Survives the merge — the filename carries <FEATURE>, and the Trace SC column
+        // is what says which UC a TC belongs to.
+        plan(abs, path.join(qcAbs, ticket, platform, within), 'test-case');
+      } else {
+        // Archive, renaming DOC_GAPS.md → DOC_GAP.md so the archive uses one name.
+        const outName = base === 'DOC_GAPS.md' ? 'DOC_GAP.md' : base;
+        const outRel = path.join(path.dirname(within), outName);
+        plan(abs, path.join(qcAbs, ARCHIVE, ucId, platform, outRel),
+          TOP_DOCS.includes(base) ? 'archive' : 'archive-other');
+      }
+    }
+  }
+}
+
+// ── second pass — DOC_GAPS.md → DOC_GAP.md for folders ALREADY in the new layout ──
+for (const abs of walk(qcAbs)) {
+  if (path.basename(abs) !== 'DOC_GAPS.md') continue;
+  if (rel(abs).includes(`/${ARCHIVE}/`)) continue;
+  if (moves.some(mv => mv.from === abs)) continue;   // already handled above
+  plan(abs, path.join(path.dirname(abs), 'DOC_GAP.md'), 'rename');
+}
+
+// ── report ────────────────────────────────────────────────────────────────────
+const pad = (s, n) => s + ' '.repeat(Math.max(0, n - s.length));
+console.log('');
+console.log('╔════════════════════════════════════════════════╗');
+console.log(`║  migrate-qc-docs  —  ${pad(APPLY ? 'APPLY' : 'DRY RUN', 25)}║`);
+console.log('╚════════════════════════════════════════════════╝');
+console.log(`Root  : ${ROOT}`);
+console.log(`QC    : ${QC}/   Git: ${tracked ? 'yes (git mv)' : 'no (fs move)'}`);
+console.log('');
+
+if (!moves.length && !noPlatform.length && !occupied.length) {
+  console.log('Nothing to migrate — no per-UC folder found, and no DOC_GAPS.md to rename.');
+  console.log(`(Scanned ${QC}/ for folders matching {TICKET-ID}-UC{N}.)`);
+  console.log('');
+  process.exit(0);
+}
+
+const byKind = k => moves.filter(m => m.kind === k);
+const show = (title, list) => {
+  if (!list.length) return;
+  console.log(`${title}  (${list.length})`);
+  for (const m of list) console.log(`  ${rel(m.from)}\n    -> ${rel(m.to)}`);
+  console.log('');
+};
+
+show('📦 MOVE — test cases (survive the merge)', byKind('test-case'));
+show('🗄  ARCHIVE — the 3 PRD-level docs (regenerate instead of merging)', byKind('archive'));
+show('🗄  ARCHIVE — other files found at that level', byKind('archive-other'));
+show('✏️  RENAME — DOC_GAPS.md -> DOC_GAP.md (B9, already-new layout)', byKind('rename'));
+
+if (noPlatform.length) {
+  console.log(`⚠️  NO PLATFORM — left in place (${noPlatform.length})`);
+  console.log('    Files sit directly under the UC folder with no web/app/system level.');
+  console.log('    A QC artifact carries no @trace.platform, so the platform cannot be');
+  console.log('    inferred — move these by hand into the right platform folder.');
+  for (const x of noPlatform) console.log(`  ${QC}/${x.ucDir}/  ->  ${x.files.join(', ')}`);
+  console.log('');
+}
+
+if (occupied.length) {
+  console.log(`❌ OCCUPIED — NOT moved, target already exists (${occupied.length})`);
+  console.log('    Moving would overwrite. Resolve by hand, then re-run.');
+  for (const x of occupied) console.log(`  ${rel(x.from)}\n    x ${rel(x.to)}`);
+  console.log('');
+}
+
+if (regen.size) {
+  console.log('🔄 NEEDS REGENERATE — run these after the move:');
+  for (const r of regen.values()) {
+    console.log(`  /qc-analyze ${r.ticket} ${r.platform}      <- was ${[...r.ucs].sort().join(' + ')}`);
+    console.log(`  /qc-plan    ${r.ticket} ${r.platform}`);
+  }
+  console.log('');
+  console.log('    The archived per-UC docs are the way back, and the only way to check');
+  console.log('    whether the PRD-level run caught cross-UC contradictions the old ones');
+  console.log('    could not see. Compare, then delete the archive when you are satisfied.');
+  console.log('');
+}
+
+if (!APPLY) {
+  console.log('DRY RUN — nothing changed. Re-run with --apply to execute.');
+  console.log('');
+  process.exit(0);
+}
+
+// ── execute ───────────────────────────────────────────────────────────────────
+function mv(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  if (isTracked(from)) execSync(`git mv -k "${rel(from)}" "${rel(to)}"`, { cwd: ROOT, stdio: ['ignore', 'ignore', 'pipe'] });
+  else fs.renameSync(from, to);
+}
+
+let moved = 0, failed = 0;
+for (const m of moves) {
+  try { mv(m.from, m.to); moved++; }
+  catch (err) {
+    console.log(`  ❌ ${rel(m.from)} — ${err.message.split('\n')[0]}`);
+    failed++;
+  }
+}
+
+// Prune folders the move emptied — deepest first, and only if genuinely empty.
+let pruned = 0;
+const dirsDeepFirst = [];
+(function collect(dir) {
+  if (!isDir(dir)) return;
+  for (const n of fs.readdirSync(dir)) collect(path.join(dir, n));
+  dirsDeepFirst.push(dir);
+})(qcAbs);
+for (const d of dirsDeepFirst) {
+  if (d === qcAbs) continue;
+  try { if (fs.readdirSync(d).length === 0) { fs.rmdirSync(d); pruned++; } } catch { /* keep */ }
+}
+
+console.log(`✅ Moved ${moved} file(s)${failed ? `, ${failed} FAILED` : ''}.`);
+console.log(`✅ Pruned ${pruned} empty folder(s).`);
+console.log('');
+console.log('Next:');
+console.log('  1. git status  — review the moves (nothing was deleted)');
+console.log('  2. Run the /qc-analyze + /qc-plan commands listed above');
+console.log(`  3. Compare against ${QC}/${ARCHIVE}/, then remove the archive when satisfied`);
+console.log('');