@smartmemory/compose 0.1.7-beta → 0.1.8-beta

package/lib/roadmap-gen.js

@@ -7,8 +7,32 @@
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { listFeatures } from './feature-json.js';
+import { loadFeaturesDir } from './project-paths.js';
+import {
+  readPhaseOverrides,
+  readAnonymousRows,
+  readPreservedSections,
+  readPreservedSectionAnchors,
+  readPhaseOrder,
+  readPhaseBlocks,
+} from './roadmap-preservers.js';
+import { emitDrift } from './roadmap-drift.js';
 
 const STATUS_ORDER = ['IN_PROGRESS', 'PARTIAL', 'PLANNED', 'COMPLETE', 'SUPERSEDED', 'PARKED'];
+const STATUS_TOKENS = ['COMPLETE', 'IN_PROGRESS', 'PARTIAL', 'PLANNED', 'SUPERSEDED', 'PARKED', 'BLOCKED', 'KILLED'];
+
+/**
+ * Extract the leading status token from override text like
+ * `PARTIAL (1a–1d COMPLETE, 2 PLANNED)` → `PARTIAL`.
+ * Returns null if no token recognized.
+ */
+function parseStatusToken(override) {
+  for (const t of STATUS_TOKENS) {
+    if (override === t) return t;
+    if (override.startsWith(t + ' ') || override.startsWith(t + '(')) return t;
+  }
+  return null;
+}
 
 /**
  * Compute the aggregate status for a phase based on its features.
@@ -32,11 +56,27 @@ function phaseStatus(features) {
  * @returns {string} - Generated ROADMAP.md content
  */
 export function generateRoadmap(cwd, opts = {}) {
-  const featuresDir = opts.featuresDir ?? 'docs/features';
+  const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
   const features = listFeatures(cwd, featuresDir);
 
-  // Read existing ROADMAP.md to preserve header/preamble
-  const preamble = readPreamble(cwd, opts);
+  // Read existing ROADMAP.md once: preamble + curated content for splice-back.
+  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const existingText = existsSync(roadmapPath) ? readFileSync(roadmapPath, 'utf-8') : '';
+  const preamble = readPreamble(cwd, opts, existingText);
+  const overrides = readPhaseOverrides(existingText);
+  const anonRows = readAnonymousRows(existingText);
+  const preserved = readPreservedSections(existingText);
+  const anchors = readPreservedSectionAnchors(existingText);
+  const sourcePhaseOrder = readPhaseOrder(existingText);
+  const phaseBlocks = readPhaseBlocks(existingText);
+
+  // Build anchor → preservedIds Map for splice-back during phase emission.
+  const anchorToPreserved = new Map();
+  for (const [id, anchor] of anchors) {
+    const arr = anchorToPreserved.get(anchor) ?? [];
+    arr.push(id);
+    anchorToPreserved.set(anchor, arr);
+  }
 
   // Group by phase
   const phases = new Map();
@@ -54,27 +94,97 @@ export function generateRoadmap(cwd, opts = {}) {
 
   const sections = [preamble.trimEnd()];
 
-  // Sort phases by the minimum position of their features (preserves ROADMAP order)
-  const sortedPhases = [...phases.entries()].sort((a, b) => {
-    const minA = Math.min(...a[1].map(f => f.position ?? 999));
-    const minB = Math.min(...b[1].map(f => f.position ?? 999));
+  // Splice in any preserved sections anchored to null (top-of-file, before first phase).
+  for (const id of anchorToPreserved.get(null) ?? []) {
+    sections.push(preserved.get(id));
+  }
+
+  // Build merged phase order: source order first (preserves curated sequencing
+  // for empty/legacy phases that have no feature.json), then any feature.json
+  // phases not yet in source (truly new phases) sorted by feature position.
+  const orderedPhaseIds = [...sourcePhaseOrder];
+  const seenInSource = new Set(sourcePhaseOrder);
+  const newPhases = [...phases.keys()].filter(p => !seenInSource.has(p));
+  newPhases.sort((a, b) => {
+    const minA = Math.min(...phases.get(a).map(f => f.position ?? 999));
+    const minB = Math.min(...phases.get(b).map(f => f.position ?? 999));
     return minA - minB;
   });
+  orderedPhaseIds.push(...newPhases);
+
+  // Render each phase. Phases with feature.json features render their tables;
+  // phases that exist only in source (override + anon rows) render heading + anon rows.
+  const emittedPreservedIds = new Set();
+  for (const phase of orderedPhaseIds) {
+    const phaseFeatures = phases.get(phase) ?? [];
+    const override = overrides.get(phase);
 
-  // Render each phase
-  for (const [phase, phaseFeatures] of sortedPhases) {
-    const status = phaseStatus(phaseFeatures);
-    sections.push(renderPhase(phase, status, phaseFeatures));
+    if (phaseFeatures.length === 0) {
+      // No feature.json features for this phase. Splice the original phase
+      // block verbatim — preserves heading override + intro prose + table
+      // (anon rows) + exit text. If the source has no block (truly new phase
+      // with no source counterpart and no features), skip.
+      const block = phaseBlocks.get(phase);
+      if (block && block.trim().length > 0) {
+        sections.push(block.trimEnd());
+        for (const id of anchorToPreserved.get(phase) ?? []) {
+          sections.push(preserved.get(id));
+          emittedPreservedIds.add(id);
+        }
+      }
+      continue;
+    }
+
+    // Typed phase: render from feature.json with override + anon-row interleave.
+    const rollupStatus = phaseStatus(phaseFeatures);
+    let headingStatus = rollupStatus;
+    if (override) {
+      const overrideToken = parseStatusToken(override);
+      if (overrideToken && overrideToken !== rollupStatus) {
+        emitDrift(cwd, { phaseId: phase, override, computed: rollupStatus });
+      }
+      // Override always wins. We can't reliably distinguish curated overrides
+      // from previously-auto-generated rollups without explicit marking, so
+      // we preserve all overrides and let drift detection surface divergence.
+      headingStatus = override;
+    }
+    const phaseAnonRows = anonRows.get(phase) ?? [];
+    const sourceBlock = phaseBlocks.get(phase);
+    if (sourceBlock) {
+      // Splice regenerated table into the source block so curated prose
+      // (intro paragraph, exit text, links) survives.
+      sections.push(spliceTableIntoBlock(sourceBlock, phase, headingStatus, phaseFeatures, phaseAnonRows));
+    } else {
+      // Truly new phase (no source counterpart): synthesize from scratch.
+      sections.push(renderPhase(phase, headingStatus, phaseFeatures, phaseAnonRows));
+    }
+
+    for (const id of anchorToPreserved.get(phase) ?? []) {
+      sections.push(preserved.get(id));
+      emittedPreservedIds.add(id);
+    }
   }
 
   // Render ungrouped features
   if (ungrouped.length > 0) {
-    sections.push(renderPhase('Features', phaseStatus(ungrouped), ungrouped));
+    sections.push(renderPhase('Features', phaseStatus(ungrouped), ungrouped, []));
+  }
+
+  // Splice any preserved sections whose anchor phase didn't survive — append at end.
+  for (const [id, anchor] of anchors) {
+    if (anchor === null) continue;
+    if (emittedPreservedIds.has(id)) continue;
+    if (!phases.has(anchor)) {
+      sections.push(preserved.get(id));
+    }
   }
 
-  // Key documents section
-  const keyDocs = buildKeyDocs(features, featuresDir);
-  if (keyDocs) sections.push(keyDocs);
+  // Key documents auto-gen is suppressed when a `key-documents` preserved-section exists.
+  // The preserved section already carries the curated content (including external links).
+  if (!preserved.has('key-documents')) {
+    const keyDocs = buildKeyDocs(features, featuresDir);
+    if (keyDocs) sections.push(keyDocs);
+  }
 
   return sections.join('\n\n---\n\n') + '\n';
 }
@@ -83,16 +193,27 @@ export function generateRoadmap(cwd, opts = {}) {
  * Read the preamble (everything before the first ## Phase/Feature section)
  * from an existing ROADMAP.md, or generate a default one.
  */
-function readPreamble(cwd, opts) {
-  const roadmapPath = join(cwd, 'ROADMAP.md');
-  if (existsSync(roadmapPath)) {
-    const text = readFileSync(roadmapPath, 'utf-8');
-    // Find the first ## heading that looks like a phase/feature section
-    const match = text.match(/^(---\s*\n\s*)?(?=## )/m);
-    if (match) {
-      const idx = text.indexOf(match[0]);
-      const pre = text.slice(0, idx).trimEnd();
-      if (pre.length > 0) return pre;
+function readPreamble(cwd, opts, existingText) {
+  if (existingText && existingText.length > 0) {
+    // Find the first `## ` or `<!-- preserved-section: ... -->` marker.
+    // Preserved-section markers belong to the preservation flow, not the preamble,
+    // so they bound the preamble the same way phase headings do.
+    let firstHeadingIdx = -1;
+    for (const re of [/^## /m, /^<!--\s*preserved-section:/m]) {
+      const m = existingText.match(re);
+      if (m) {
+        const idx = existingText.indexOf(m[0]);
+        if (firstHeadingIdx === -1 || idx < firstHeadingIdx) firstHeadingIdx = idx;
+      }
+    }
+    if (firstHeadingIdx > 0) {
+      // Walk back over a possible `---\n\n` separator immediately before the heading
+      // so it doesn't get duplicated against the join("\n\n---\n\n") below.
+      let cutIdx = firstHeadingIdx;
+      const tail = existingText.slice(0, cutIdx).trimEnd();
+      // If preamble ends with `---`, strip it.
+      const stripped = tail.replace(/\n---\s*$/, '').trimEnd();
+      if (stripped.length > 0) return stripped;
     }
   }
 
@@ -119,7 +240,131 @@ ${desc ? desc + '\n\n' : ''}<!-- Generated from feature.json — do not edit man
 /**
  * Render a phase section with its feature table.
  */
-function renderPhase(phaseName, status, features) {
+/**
+ * Splice a regenerated table into a source phase block so curated prose
+ * (intro paragraph, exit text, doc links) survives a no-op regen.
+ *
+ * Strategy: the source block is `<heading>\n\n<prose>\n\n<table>\n\n<trailing>`.
+ * Find the table boundaries (header row + divider through the last contiguous
+ * `|...|` row), replace heading line with the override/rollup-aware version,
+ * replace the table portion with a freshly rendered one, keep everything else.
+ */
+function spliceTableIntoBlock(sourceBlock, phaseName, headingStatus, features, anonRows) {
+  const lines = sourceBlock.split('\n');
+  const isTableLine = (s) => /^\s*\|.*\|\s*$/.test(s);
+
+  // Locate the first table row (header) — first `|...|` line.
+  let tableStart = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (isTableLine(lines[i])) {
+      tableStart = i;
+      break;
+    }
+  }
+
+  // Locate the last contiguous table row — walk forward from tableStart over
+  // any `|...|` lines. Allow blank lines inside if the next non-blank is a
+  // table line (rare but possible). Simpler: stop at first non-table-non-blank.
+  let tableEnd = tableStart;
+  if (tableStart !== -1) {
+    let i = tableStart;
+    while (i < lines.length) {
+      if (isTableLine(lines[i])) {
+        tableEnd = i;
+        i++;
+      } else if (lines[i].trim() === '' && i + 1 < lines.length && isTableLine(lines[i + 1])) {
+        i++; // skip blank between rows
+      } else {
+        break;
+      }
+    }
+  }
+
+  // Build the replacement table (header + divider + rows with anon interleave).
+  const newTable = renderTableLines(features, anonRows);
+
+  // Replace heading line (always lines[0] for a phase block).
+  const headingLine = `## ${phaseName} — ${headingStatus}`;
+  const out = [headingLine];
+
+  if (tableStart === -1) {
+    // No existing table — append the new one after the existing prose.
+    for (let i = 1; i < lines.length; i++) out.push(lines[i]);
+    if (out.length > 0 && out[out.length - 1].trim() !== '') out.push('');
+    out.push(...newTable);
+    return out.join('\n');
+  }
+
+  // Emit prose between heading and table.
+  for (let i = 1; i < tableStart; i++) out.push(lines[i]);
+
+  // Emit the regenerated table.
+  out.push(...newTable);
+
+  // Emit trailing content after the original table.
+  for (let i = tableEnd + 1; i < lines.length; i++) out.push(lines[i]);
+
+  return out.join('\n');
+}
+
+/**
+ * Render the table portion (header + divider + rows) for a phase. Anon rows
+ * interleave by predecessorCode rules.
+ */
+function renderTableLines(features, anonRows) {
+  const hasSubItems = features.some(f => f.items && f.items.length > 0);
+  const lines = [];
+
+  const anonByPredecessor = new Map();
+  for (const row of anonRows) {
+    const arr = anonByPredecessor.get(row.predecessorCode) ?? [];
+    arr.push(row.rawLine);
+    anonByPredecessor.set(row.predecessorCode, arr);
+  }
+  const emitAnonAfter = (code) => {
+    for (const raw of anonByPredecessor.get(code) ?? []) lines.push(raw);
+    anonByPredecessor.delete(code);
+  };
+
+  if (hasSubItems) {
+    lines.push('| # | Feature | Item | Status |');
+    lines.push('|---|---------|------|--------|');
+    emitAnonAfter(null);
+    for (const f of features) {
+      if (f.items && f.items.length > 0) {
+        for (const item of f.items) {
+          const num = item.position ?? '—';
+          const desc = item.description ?? '';
+          const st = item.status ?? f.status;
+          lines.push(`| ${num} | ${f.code} | ${desc} | ${st} |`);
+        }
+      } else {
+        const num = f.position ?? '—';
+        lines.push(`| ${num} | ${f.code} | ${f.description} | ${f.status} |`);
+      }
+      emitAnonAfter(f.code);
+    }
+  } else {
+    lines.push('| # | Feature | Description | Status |');
+    lines.push('|---|---------|-------------|--------|');
+    emitAnonAfter(null);
+    for (const f of features) {
+      const num = f.position ?? '—';
+      const desc = f.description ?? '';
+      lines.push(`| ${num} | ${f.code} | ${desc} | ${f.status} |`);
+      emitAnonAfter(f.code);
+    }
+  }
+
+  // Leftovers (predecessor deleted) — append at end of table.
+  for (const [, leftover] of anonByPredecessor) {
+    for (const raw of leftover) lines.push(raw);
+  }
+
+  return lines;
+}
+
+function renderPhase(phaseName, status, features, anonRows = []) {
   const lines = [`## ${phaseName} — ${status}`, ''];
 
   // Phase description from the first feature's phaseDescription if available
@@ -131,10 +376,24 @@ function renderPhase(phaseName, status, features) {
   // Determine table columns based on whether features have sub-items
   const hasSubItems = features.some(f => f.items && f.items.length > 0);
 
+  // Index anon rows by predecessorCode for interleave.
+  const anonByPredecessor = new Map();
+  for (const row of anonRows) {
+    const key = row.predecessorCode; // null = head-of-table
+    const arr = anonByPredecessor.get(key) ?? [];
+    arr.push(row.rawLine);
+    anonByPredecessor.set(key, arr);
+  }
+  const emitAnonAfter = (code) => {
+    for (const raw of anonByPredecessor.get(code) ?? []) lines.push(raw);
+    anonByPredecessor.delete(code);
+  };
+
   if (hasSubItems) {
     // Expanded: one row per sub-item
     lines.push('| # | Feature | Item | Status |');
     lines.push('|---|---------|------|--------|');
+    emitAnonAfter(null); // any head-of-table anon rows
     for (const f of features) {
       if (f.items && f.items.length > 0) {
         for (const item of f.items) {
@@ -147,18 +406,29 @@ function renderPhase(phaseName, status, features) {
         const num = f.position ?? '—';
         lines.push(`| ${num} | ${f.code} | ${f.description} | ${f.status} |`);
       }
+      emitAnonAfter(f.code);
     }
   } else {
     // Simple: one row per feature
     lines.push('| # | Feature | Description | Status |');
     lines.push('|---|---------|-------------|--------|');
+    // COMP-MCP-MIGRATION-2-1: no truncation. Curated descriptions are
+     // often multi-sentence; truncating them at 80 chars makes regen lossy.
+     // Markdown tables tolerate long cells fine.
+    emitAnonAfter(null); // any head-of-table anon rows
     for (const f of features) {
       const num = f.position ?? '—';
-      const desc = f.description.length > 80 ? f.description.slice(0, 77) + '...' : f.description;
+      const desc = f.description ?? '';
       lines.push(`| ${num} | ${f.code} | ${desc} | ${f.status} |`);
+      emitAnonAfter(f.code);
     }
   }
 
+  // Any anon rows whose predecessor was deleted: append at the end of the table.
+  for (const [, leftover] of anonByPredecessor) {
+    for (const raw of leftover) lines.push(raw);
+  }
+
   // Exit criteria
   const exit = features[0]?.phaseExit;
   if (exit) {