@ktpartners/dgs-platform 3.5.0 → 3.5.3

package/deliver-great-systems/bin/lib/jobs.cjs

@@ -1157,52 +1157,77 @@ function analyzeMilestonePhases(cwd, version) {
     );
     const sectionMatch = content.match(sectionHeadingPattern);
     if (!sectionMatch) {
-      throw new Error(`Milestone ${version} not found in ROADMAP.md`);
-    }
+      // No ##-#### heading carries the version. Support the newer
+      // single-milestone ROADMAP format where the version appears ONLY in the
+      // `# Roadmap: ... (vX.Y)` title and a `**Milestone:** vX.Y` bold line.
+      // Gate the whole-roadmap phase scan behind a single-milestone check so a
+      // stray bold line on a multi-milestone roadmap does not mis-derive a range.
+      const boldMilestonePattern = new RegExp(
+        '^\\*\\*Milestone:\\*\\*\\s*' + escapedVersion + '\\b',
+        'im'
+      );
+      const versionHeadings = content.match(/^#{2,4}\s+.*v\d+\.\d+/gim) || [];
+      const isSingleMilestone = versionHeadings.length <= 1;
+      if (boldMilestonePattern.test(content) && isSingleMilestone) {
+        const fullPhasePattern = /Phase\s+(\d+)/gi;
+        const phaseNumbers = [];
+        let fpMatch;
+        while ((fpMatch = fullPhasePattern.exec(content)) !== null) {
+          phaseNumbers.push(parseInt(fpMatch[1], 10));
+        }
+        if (phaseNumbers.length === 0) {
+          throw new Error(`Milestone ${version} not found in ROADMAP.md`);
+        }
+        phaseStart = Math.min(...phaseNumbers);
+        phaseEnd = Math.max(...phaseNumbers);
+      } else {
+        throw new Error(`Milestone ${version} not found in ROADMAP.md`);
+      }
+    } else {
+      const headingLevel = sectionMatch[1].length;
+      const sectionStart = sectionMatch.index + sectionMatch[0].length;
 
-    const headingLevel = sectionMatch[1].length;
-    const sectionStart = sectionMatch.index + sectionMatch[0].length;
+      // Find the end of this section (next heading at same or higher level)
+      const endPattern = new RegExp(
+        `^#{2,${headingLevel}}\\s+`,
+        'im'
+      );
+      const restContent = content.slice(sectionStart);
+      const endMatch = restContent.match(endPattern);
+      const sectionContent = endMatch
+        ? restContent.slice(0, endMatch.index)
+        : restContent;
+
+      // Collect Phase N: headers within this section
+      const phaseHeaderPattern = /Phase\s+(\d+)\s*:/gi;
+      const phaseNumbers = [];
+      let phMatch;
+      while ((phMatch = phaseHeaderPattern.exec(sectionContent)) !== null) {
+        phaseNumbers.push(parseInt(phMatch[1], 10));
+      }
 
-    // Find the end of this section (next heading at same or higher level)
-    const endPattern = new RegExp(
-      `^#{2,${headingLevel}}\\s+`,
-      'im'
-    );
-    const restContent = content.slice(sectionStart);
-    const endMatch = restContent.match(endPattern);
-    const sectionContent = endMatch
-      ? restContent.slice(0, endMatch.index)
-      : restContent;
-
-    // Collect Phase N: headers within this section
-    const phaseHeaderPattern = /Phase\s+(\d+)\s*:/gi;
-    const phaseNumbers = [];
-    let phMatch;
-    while ((phMatch = phaseHeaderPattern.exec(sectionContent)) !== null) {
-      phaseNumbers.push(parseInt(phMatch[1], 10));
-    }
+      // If section-based search found nothing (common when ROADMAP has peer-level
+      // ## headings like ## v1.0, ## Overview, ## Phase Details), search the entire
+      // ROADMAP for Phase N: headings. For single-milestone ROADMAPs all phases
+      // belong to the milestone.
+      if (phaseNumbers.length === 0) {
+        const fullPhasePattern = new RegExp(
+          `Phase\\s+(\\d+)`,
+          'gi'
+        );
+        let fpMatch;
+        while ((fpMatch = fullPhasePattern.exec(content)) !== null) {
+          phaseNumbers.push(parseInt(fpMatch[1], 10));
+        }
+      }
 
-    // If section-based search found nothing (common when ROADMAP has peer-level
-    // ## headings like ## v1.0, ## Overview, ## Phase Details), search the entire
-    // ROADMAP for Phase N: headings. For single-milestone ROADMAPs all phases
-    // belong to the milestone.
-    if (phaseNumbers.length === 0) {
-      const fullPhasePattern = new RegExp(
-        `Phase\\s+(\\d+)`,
-        'gi'
-      );
-      let fpMatch;
-      while ((fpMatch = fullPhasePattern.exec(content)) !== null) {
-        phaseNumbers.push(parseInt(fpMatch[1], 10));
+      if (phaseNumbers.length === 0) {
+        throw new Error(`Milestone ${version} not found in ROADMAP.md`);
       }
-    }
 
-    if (phaseNumbers.length === 0) {
-      throw new Error(`Milestone ${version} not found in ROADMAP.md`);
+      phaseStart = Math.min(...phaseNumbers);
+      phaseEnd = Math.max(...phaseNumbers);
     }
-
-    phaseStart = Math.min(...phaseNumbers);
-    phaseEnd = Math.max(...phaseNumbers);
   }
 
   // Extract all phase detail sections: ### Phase N: Name
@@ -1272,7 +1297,19 @@ function detectActiveMilestone(content) {
   if (match) return match[1];
   // Fallback: milestone list item with (in progress)
   const listMatch = content.match(/-\s+.*?(v\d+\.\d+).*?\((?:in\s+progress)\)/i);
-  return listMatch ? listMatch[1] : null;
+  if (listMatch) return listMatch[1];
+  // Ad-hoc container format: version on the heading, in-progress on a separate
+  // **Status:** line (NO parenthetical on the heading). Runs after the legacy
+  // In-Progress heading/list signals so a real multi-milestone In-Progress
+  // heading still wins on multi-milestone roadmaps.
+  const adhocMatch = content.match(/^##\s+Active Milestone:\s*(v\d+\.\d+)/im);
+  if (adhocMatch) return adhocMatch[1];
+  // Final fallback: newer single-milestone format with a `**Milestone:** vX.Y`
+  // bold line. Runs LAST so legacy In-Progress heading/list signals win when
+  // present on multi-milestone roadmaps.
+  const boldMatch = content.match(/^\*\*Milestone:\*\*\s*(v\d+\.\d+)/im);
+  if (boldMatch) return boldMatch[1];
+  return null;
 }
 
 // ─── Milestone Job CLI Wrappers ─────────────────────────────────────────────
@@ -1302,7 +1339,14 @@ function cmdJobsCreateMilestone(cwd, version, check, raw) {
       throw new Error('No active milestone found in ROADMAP.md');
     }
   } else {
-    // Validate the version exists in ROADMAP
+    // Validate the version exists in ROADMAP.
+    // Confirmed against every real generator: each emits whitespace immediately
+    // after the FIRST occurrence of the version — a space in the ad-hoc /
+    // bullet headings (`v25.1 add-prs`, `Active Milestone: v25.1 add-prs`) and a
+    // newline after the bold line (`**Milestone:** v25.1\n`). The namespaced
+    // `Phases v25.1/1-9` form has a non-whitespace `/` delimiter, but it is
+    // never the FIRST occurrence (the bold bullet `v25.1 add-prs` precedes it),
+    // so `\s+` always matches the first occurrence. No change needed here.
     const escapedV = resolvedVersion.replace(/\./g, '\\.');
     const versionPattern = new RegExp(escapedV + '\\s+', 'i');
     if (!versionPattern.test(roadmapContent)) {
@@ -1421,47 +1465,86 @@ function cmdJobsMilestonePreview(cwd, version, check, raw) {
 function listJobs(cwd) {
   const jobsDir = path.join(getPlanningRoot(cwd), 'jobs');
   const groups = { in_progress: [], pending: [], completed: [] };
-  const dirMap = { 'in-progress': 'in_progress', 'pending': 'pending', 'completed': 'completed' };
+  const statusToGroup = { 'in-progress': 'in_progress', 'pending': 'pending', 'completed': 'completed' };
+
+  // Shared flat-job predicate (identical to findJobFile/healthCheck — reused,
+  // not reinvented). Excludes summary files (job-*-SUMMARY.md).
+  const isJobFile = f => f.startsWith('milestone-') && f.endsWith('.md');
+  const seenVersions = new Set();
+
+  // Stage entries with their mtime so each group sorts most-recent-first.
+  const staged = { in_progress: [], pending: [], completed: [] };
+
+  function stageEntry(groupKey, fullPath, parsed) {
+    let mtime = 0;
+    try { mtime = fs.statSync(fullPath).mtimeMs; } catch {}
+    staged[groupKey].push({
+      mtime,
+      entry: {
+        version: parsed.version,
+        status: parsed.status,
+        check: parsed.check,
+        created_by: parsed.created_by,
+        progress: `${parsed.completedCount}/${parsed.stepCount}`,
+        file: fullPath,
+      },
+    });
+  }
 
-  for (const [dirName, groupKey] of Object.entries(dirMap)) {
-    const dirPath = path.join(jobsDir, dirName);
-    if (!fs.existsSync(dirPath)) {
-      fs.mkdirSync(dirPath, { recursive: true });
+  // Flat-first scan: jobs/milestone-*.md grouped by parsed frontmatter status.
+  let flatFiles = [];
+  try {
+    flatFiles = fs.readdirSync(jobsDir).filter(isJobFile);
+  } catch {
+    flatFiles = [];
+  }
+  for (const file of flatFiles) {
+    const fullPath = path.join(jobsDir, file);
+    try {
+      const parsed = parseJobFile(fullPath);
+      const groupKey = statusToGroup[parsed.status];
+      if (!groupKey) continue; // guard unknown/missing status
+      stageEntry(groupKey, fullPath, parsed);
+      if (parsed.version) seenVersions.add(parsed.version);
+    } catch {
+      // Skip unparseable files
     }
+  }
+
+  // Legacy subdir fallback — existence-gated, NEVER created (read-only).
+  const legacyDirs = ['in-progress', 'pending', 'completed'];
+  for (const dirName of legacyDirs) {
+    const dirPath = path.join(jobsDir, dirName);
+    if (!fs.existsSync(dirPath)) continue;
 
     let files;
     try {
-      files = fs.readdirSync(dirPath).filter(f => f.startsWith('milestone-') && f.endsWith('.md'));
+      files = fs.readdirSync(dirPath).filter(isJobFile);
     } catch {
       continue;
     }
-
-    // Sort by modification time, most recent first
-    const fileStats = files.map(f => {
-      const fullPath = path.join(dirPath, f);
-      let mtime = 0;
-      try { mtime = fs.statSync(fullPath).mtimeMs; } catch {}
-      return { file: f, fullPath, mtime };
-    });
-    fileStats.sort((a, b) => b.mtime - a.mtime);
-
-    for (const { file, fullPath } of fileStats) {
+    for (const file of files) {
+      const fullPath = path.join(dirPath, file);
       try {
         const parsed = parseJobFile(fullPath);
-        groups[groupKey].push({
-          version: parsed.version,
-          status: parsed.status,
-          check: parsed.check,
-          created_by: parsed.created_by,
-          progress: `${parsed.completedCount}/${parsed.stepCount}`,
-          file: fullPath,
-        });
+        if (parsed.version && seenVersions.has(parsed.version)) continue;
+        // Group by parsed status, falling back to the dir name if status missing.
+        const groupKey = statusToGroup[parsed.status] || statusToGroup[dirName];
+        if (!groupKey) continue;
+        stageEntry(groupKey, fullPath, parsed);
+        if (parsed.version) seenVersions.add(parsed.version);
       } catch {
         // Skip unparseable files
       }
     }
   }
 
+  // Sort each group most-recent-first and unwrap to entry objects.
+  for (const key of Object.keys(groups)) {
+    staged[key].sort((a, b) => b.mtime - a.mtime);
+    groups[key] = staged[key].map(s => s.entry);
+  }
+
   return groups;
 }
 
@@ -1519,37 +1602,63 @@ function cancelJob(cwd, version) {
 }
 
 /**
- * Validate jobs directory structure. Auto-create missing directories.
+ * Validate jobs directory structure (flat-first).
+ *
+ * Scans the flat `jobs/milestone-*.md` layout first. Legacy
+ * `pending/in-progress/completed` subdirs are an existence-gated optional
+ * fallback: they are counted + parse-validated when present, but are never
+ * created and their absence is not an issue. Only genuine parse failures
+ * flip `healthy` to false.
  *
  * @param {string} cwd - Working directory
  * @returns {{ healthy: boolean, directories: Array, job_count: number, issues?: Array }}
  */
 function healthCheck(cwd) {
   const jobsDir = path.join(getPlanningRoot(cwd), 'jobs');
-  const requiredDirs = ['pending', 'in-progress', 'completed'];
   const directories = [];
   const issues = [];
   let jobCount = 0;
 
-  for (const dirName of requiredDirs) {
-    const dirPath = path.join(jobsDir, dirName);
-    const exists = fs.existsSync(dirPath);
-    let created = false;
+  // An absent/empty jobs dir is healthy. Ensure it exists, but do not flag it.
+  let jobsCreated = false;
+  if (!fs.existsSync(jobsDir)) {
+    fs.mkdirSync(jobsDir, { recursive: true });
+    jobsCreated = true;
+  }
+
+  // Shared flat-job predicate (identical to findJobFile/listJobs). Excludes
+  // summary files (job-*-SUMMARY.md) since they do not start with 'milestone-'.
+  const isJobFile = f => f.startsWith('milestone-') && f.endsWith('.md');
 
-    if (!exists) {
-      fs.mkdirSync(dirPath, { recursive: true });
-      created = true;
-      issues.push(`Missing directory auto-created: ${dirName}/`);
+  // Flat-first scan: jobs/milestone-*.md
+  try {
+    const flatFiles = fs.readdirSync(jobsDir).filter(isJobFile);
+    jobCount += flatFiles.length;
+    for (const file of flatFiles) {
+      const filePath = path.join(jobsDir, file);
+      try {
+        parseJobFile(filePath);
+      } catch (err) {
+        issues.push(`Parse failure in ${file}: ${err.message}`);
+      }
     }
+  } catch {
+    // jobs dir unreadable; treat as empty.
+  }
+
+  directories.push({ name: 'jobs', exists: true, created: jobsCreated });
 
-    directories.push({ name: dirName, exists: exists || created, created });
+  // Legacy subdirs: existence-gated optional fallback. Never created.
+  const legacyDirs = ['pending', 'in-progress', 'completed'];
+  for (const dirName of legacyDirs) {
+    const dirPath = path.join(jobsDir, dirName);
+    if (!fs.existsSync(dirPath)) continue;
+
+    directories.push({ name: dirName, exists: true, created: false });
 
-    // Scan for job files
     try {
-      const files = fs.readdirSync(dirPath).filter(f => f.startsWith('milestone-') && f.endsWith('.md'));
+      const files = fs.readdirSync(dirPath).filter(isJobFile);
       jobCount += files.length;
-
-      // Validate each file
       for (const file of files) {
         const filePath = path.join(dirPath, file);
         try {
@@ -1559,7 +1668,7 @@ function healthCheck(cwd) {
         }
       }
     } catch {
-      // Directory just created, no files
+      // Subdir unreadable; skip.
     }
   }
 
@@ -2117,6 +2226,8 @@ module.exports = {
   cmdJobsInsertPhaseGapFix,
   cmdJobsCreateMilestone,
   cmdJobsMilestonePreview,
+  analyzeMilestonePhases,
+  detectActiveMilestone,
   cmdJobsListJobs,
   cmdJobsCancelJob,
   cmdJobsRecordStartShas,