@opengsd/gsd-core 1.13.0 → 1.15.0

package/gsd-core/bin/lib/roadmap-parser.cjs

@@ -571,6 +571,55 @@ function sliceMilestoneWindow(content, version) {
         return null;
     return content.slice(selected.index, computeMilestoneSectionEnd(content, selected[0], selected.index));
 }
+/**
+ * Enumerate the milestone section ranges recognized by the ROADMAP readers.
+ * Markdown boundaries reuse the reader's heading tokenizer, milestone-signal
+ * vocabulary, name/version extractor, and section-end owner. Collapsed
+ * archives reuse the same `<details><summary>` shape handled by
+ * `extractCurrentMilestoneScoped`.
+ */
+function milestoneSections(content) {
+    const sections = [];
+    const headings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content);
+    for (const heading of headings) {
+        if (heading.level < 1 || heading.level > 3)
+            continue;
+        if (/^Phase\s+\S/i.test(heading.text))
+            continue;
+        if (!MILESTONE_HEADING_SIGNAL_PATTERN.test(heading.text))
+            continue;
+        const extracted = extractMilestoneHeadingName(heading.text);
+        const version = extracted?.version ?? null;
+        const versionMajor = version?.match(/^v(\d+)/i);
+        const milestoneInt = versionMajor ? parseInt(versionMajor[1], 10) : null;
+        const lineEnd = content.indexOf('\n', heading.offset);
+        const fullLine = content.slice(heading.offset, lineEnd === -1 ? content.length : lineEnd);
+        sections.push({
+            start: heading.offset,
+            end: computeMilestoneSectionEnd(content, fullLine, heading.offset, undefined, headings),
+            version,
+            milestoneInt: milestoneInt !== null && Number.isSafeInteger(milestoneInt) ? milestoneInt : null,
+        });
+    }
+    const detailsPattern = /<details\b[^>]*>[\s\S]*?<\/details>/gi;
+    let detailsMatch;
+    while ((detailsMatch = detailsPattern.exec(content)) !== null) {
+        const summary = detailsMatch[0].match(/<summary[^>]*>([^<]*)<\/summary>/i)?.[1]?.trim() ?? '';
+        if (!MILESTONE_HEADING_SIGNAL_PATTERN.test(summary))
+            continue;
+        const extracted = extractMilestoneHeadingName(summary);
+        const version = extracted?.version ?? null;
+        const versionMajor = version?.match(/^v(\d+)/i);
+        const milestoneInt = versionMajor ? parseInt(versionMajor[1], 10) : null;
+        sections.push({
+            start: detailsMatch.index,
+            end: detailsMatch.index + detailsMatch[0].length,
+            version,
+            milestoneInt: milestoneInt !== null && Number.isSafeInteger(milestoneInt) ? milestoneInt : null,
+        });
+    }
+    return sections.sort((a, b) => a.start - b.start || a.end - b.end);
+}
 /**
  * #3184: counts RAW phase references — a `#{2,4} Phase <id>:` heading
  * (fence-aware via `tokenizeHeadings`) or a `#2199` bullet entry — BEFORE any
@@ -600,17 +649,37 @@ function sliceMilestoneWindow(content, version) {
 // decoy `### [GSD.04] Notes:` outside the window manufactured a false V005
 // while suppressing the correct V004. The digit anchor forecloses both.
 const BRACKET_PHASE_ENTRY_HEADING_RE = new RegExp(`^${PHASE_HEADING_PREFIX_SRC}${PHASE_NUMBER_TOKEN_SOURCE}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'i');
+// #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal
+// mirror of OPTIONAL_PHASE_TAG_SOURCE). Hoisted out of hasPhaseEntries (#4144
+// round 5 Blocker 1) so a consumer OUTSIDE this file's own phase-entry count —
+// the bracket roadmap migrator's "phase-like but unparsed" refusal
+// (src/roadmap-upgrade.cts) — can ask "is this heading text a phase heading
+// by the readers' own rules" without re-deriving the pattern. A heading with
+// no phase-number token and no trailing colon (`## Phase Details`, `##
+// Phase Lifecycle`, `### Phase Notes`) is NOT a phase heading by this
+// grammar — it is an ordinary section heading that happens to start with the
+// word "Phase".
+const PHASE_HEADING_TEXT_RE = /^(?:\[[^\]]{1,200}\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*:/i;
+/**
+ * #4144 round 5 Blocker 1: whether `headingText` — a heading's text with its
+ * leading `#{1,6}` markers and surrounding whitespace already stripped
+ * (`tokenizeHeadings`'s own `h.text`, or the equivalent for a line a caller
+ * already knows is a `#{2,4}` heading) — is a phase heading by the readers'
+ * own grammar. The single owner of this test; `hasPhaseEntries` below is
+ * itself just the first caller.
+ */
+function isPhaseHeadingText(headingText) {
+    return PHASE_HEADING_TEXT_RE.test(headingText);
+}
 function hasPhaseEntries(markdown, phaseIdConvention) {
-    // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
     // #3641: the widened grammar engages ONLY when the resolved convention is
     // 'bracket' — a project that has not opted in runs the legacy pattern
     // alone, byte-identically.
-    const phaseHeadingPattern = /^(?:\[[^\]]{1,200}\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*:/i;
     const bracketMode = phaseIdConvention === 'bracket';
     for (const h of (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(markdown)) {
         if (h.level < 2 || h.level > 4)
             continue;
-        if (phaseHeadingPattern.test(h.text))
+        if (isPhaseHeadingText(h.text))
             return true;
         if (bracketMode && BRACKET_PHASE_ENTRY_HEADING_RE.test(h.text))
             return true;
@@ -626,16 +695,17 @@ function hasPhaseEntries(markdown, phaseIdConvention) {
     return collectTablePhaseRows(markdown).length > 0;
 }
 // ─── #3577: markdown-table phase listings ─────────────────────────────────────
-// #3577: a GFM table declares phases when its header's FIRST cell is the literal
-// `Phase` (optionally `Phase #` / `Phase No.` / `Phase number`) and the header does
-// NOT match a known non-listing schema — the canonical RoadmapProgress table
-// (`| Phase | Plans Complete | Status | Completed |`) leads with `Phase` too, and
-// its rows are progress markers, not declarations. Data rows carry the phase id in
-// their first cell (digit-bearing canonical shape — `Phase`-word header cells and
-// `---` delimiter rows are digit-free and excluded by construction). Fence-aware
-// via stripFencedCode, matching the #3184 lesson: a fenced EXAMPLE of the table
-// form is not a declared phase.
+// #3577/#4480: a GFM table declares phases only when its header's FIRST cell is
+// the literal `Phase` (optionally `Phase #` / `Phase No.` / `Phase number`) AND
+// it positively identifies a `Name` or `Phase Name` column. This fails closed:
+// ordinary progress/summary tables such as `| Phase | Status |` cannot mint a
+// phase whose name is whichever value happens to occupy column two. Data rows
+// carry the phase id in their first cell (digit-bearing canonical shape —
+// `Phase`-word header cells and `---` delimiter rows are digit-free and excluded
+// by construction). Fence-aware via stripFencedCode, matching the #3184 lesson:
+// a fenced EXAMPLE of the table form is not a declared phase.
 const PHASE_LISTING_HEADER_RE = /^\|?\s*phase(?:\s*(?:#|no\.?|number))?\s*\|/i;
+const PHASE_NAME_HEADER_RE = /^(?:phase\s+)?name$/i;
 const TABLE_PHASE_ID_RE = /^[A-Za-z]?\d[\w.-]*$/;
 function collectTablePhaseRows(window) {
     const unfenced = (0, markdown_sectionizer_cjs_1.stripFencedCode)(window).text;
@@ -645,8 +715,9 @@ function collectTablePhaseRows(window) {
         if (!PHASE_LISTING_HEADER_RE.test(lines[i]))
             continue;
         const headerCells = (0, markdown_table_cjs_1.splitTableRow)(lines[i]);
-        if ((0, markdown_table_cjs_1.matchTableSchema)(headerCells) !== null)
-            continue; // canonical non-listing schema
+        const nameColumn = headerCells.findIndex((cell) => PHASE_NAME_HEADER_RE.test(cell));
+        if (nameColumn === -1)
+            continue;
         if (!(0, markdown_table_cjs_1.isDelimiterRow)((0, markdown_table_cjs_1.splitTableRow)(lines[i + 1])))
             continue;
         for (let j = i + 2; j < lines.length; j++) {
@@ -662,12 +733,30 @@ function collectTablePhaseRows(window) {
             if (!TABLE_PHASE_ID_RE.test(first))
                 continue;
             if (!/^999\b/.test(first)) {
-                rows.push({ id: first, name: cells[1] && cells[1] !== '' ? cells[1] : null, row: lines[j] });
+                const name = cells[nameColumn];
+                rows.push({ id: first, name: name && name !== '' ? name : null, row: lines[j] });
             }
         }
     }
     return rows;
 }
+/**
+ * True when `content` contains a GFM table whose header row is phase-listing
+ * SHAPED (`| Phase | ... |`), regardless of whether it also declares a `Name`
+ * column. `collectTablePhaseRows` correctly refuses to mint a phase from a
+ * `| Phase | Status |`-shaped table (no name column, so no declaration) —
+ * but that table's mere presence still signals this roadmap has moved to
+ * table-based tracking, not checklist-based tracking. Callers that decide
+ * whether to treat bare checklist entries as phase declarations (#4899's
+ * roadmap.cts synthesis fallback) must see this signal even when
+ * `collectTablePhaseRows` itself returns nothing for the same content —
+ * otherwise a thin, name-less Progress table cannot suppress a checklist
+ * synthesis it was never meant to coexist with.
+ */
+function hasPhaseListingTableHeader(content) {
+    const unfenced = (0, markdown_sectionizer_cjs_1.stripFencedCode)(content).text;
+    return unfenced.split(/\r?\n/).some((line) => PHASE_LISTING_HEADER_RE.test(line));
+}
 /**
  * #3262: the sole owner of "which phase ids does THIS milestone window
  * declare". Extracted verbatim from `getMilestonePhaseFilter`'s former inline
@@ -962,6 +1051,7 @@ function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
                 const preambleCutoff = firstMilestoneMatch ? firstMilestoneMatch.index : detailsOpenIdx;
                 const preamble = (0, markdown_sectionizer_cjs_1.stripTaggedBlocks)(content.slice(0, preambleCutoff), 'details')
                     // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+                    // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
                     .replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*(?:\s*\([^)\n]{0,200}\))?\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
                     .replace(/^#{1,4}\s*Phase Details\b[^\n]*\n?/gim, '');
                 const value = preamble + content.slice(detailsOpenIdx, detailsEnd);
@@ -1197,6 +1287,7 @@ function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
     // every phase (phase_count: 0, exit 0). Only strip preamble phase details when
     // the selected milestone section actually contains its own — otherwise the
     // preamble phases ARE this milestone's phases and must be preserved.
+    // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
     const currentSectionHasPhaseDetails = /^#{2,4}\s*Phase\s+\S/im.test(currentSection);
     const preambleBase = (0, markdown_sectionizer_cjs_1.stripTaggedBlocks)(beforeMilestones, 'details');
     // #3235: the conditional wraps the REPLACE, not the pattern. This used to select between the
@@ -1205,6 +1296,7 @@ function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
     // replacement argument, so changing `''` would silently give the no-op branch a real effect.
     // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
     const preambleWithoutPhaseDetails = currentSectionHasPhaseDetails
+        // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
         ? preambleBase.replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*(?:\s*\([^)\n]{0,200}\))?\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
         : preambleBase;
     // Unconditional in BOTH branches -- the #730 `Phase Details` heading strip is independent of
@@ -1481,6 +1573,23 @@ function findRoadmapProgressTable(roadmapContent) {
 function stripLeadingDelimiter(s) {
     return s.replace(/^[\s—–:-]+/, '').trim();
 }
+/**
+ * #4134/#4433 (§7.2 rule 6 floor, applied symmetrically): a captured "name"
+ * with no letter or digit anywhere is heading/bullet STRUCTURE, not a curated
+ * name — e.g. the trailing `)` a name-then-version heading leaves after its
+ * version token, or a malformed 🚧-bullet whose only content past the version
+ * is punctuation (`---`, `***`, a lone `:`). #4134 fixed this for
+ * `extractMilestoneHeadingName`'s heading path only; #4433 found the sibling
+ * 🚧-bullet capture (`getMilestoneInfo`'s `listMatch`) and the no-STATE.md
+ * fallback (`inProgressMatch`) both skipped straight to a bare truthiness
+ * check, so a punctuation-only bullet name passed through as a real one. This
+ * is now the SOLE name-validity predicate — every capture site in this file
+ * calls it instead of re-deriving the character class. A name that merely
+ * CONTAINS punctuation is unaffected; digits alone qualify.
+ */
+function hasNameableContent(s) {
+    return /[\p{L}\p{N}]/u.test(s);
+}
 /**
  * #3216 (ADR-3180 §7.2's "Name extraction — pinned rule"): the sole "milestone
  * heading text → version + curated name" rule. Strips everything through the
@@ -1493,6 +1602,13 @@ function stripLeadingDelimiter(s) {
  * one implementation. Returns `null` when `headingText` carries no version
  * token at all (e.g. a non-milestone heading reached this by mistake).
  *
+ * #4134 (§7.2 rule 6 floor): the rule's direction assumes version-then-name.
+ * A name-then-version heading (`# Roadmap: Project — Name (v1.13)`) leaves a
+ * punctuation fragment (`)`) after the token; a remainder with no letter or
+ * digit anywhere is heading structure, not a curated name, and is refused as
+ * `name: null` so callers report the honest rule-6 answer instead of
+ * fabricating garbage. Names that merely CONTAIN punctuation are unaffected.
+ *
  * @param expectedVersion - When the caller already knows the exact version it
  *   is looking for (the STATE-anchored `getMilestoneInfo` path, which located
  *   this heading via `selectMilestoneHeading(roadmap, stateVersion)`), pass it
@@ -1529,7 +1645,18 @@ function extractMilestoneHeadingName(headingText, expectedVersion) {
     // whitespace — the marker is already carried structurally by `closed`, so
     // duplicating it inside `name` (e.g. "Old ✅") is redundant and wrong. Only
     // these three markers, only at the end; a marker inside a name is untouched.
-    const name = stripLeadingDelimiter(afterVersion).replace(/\s*(?:[✅📋🚧]\s*)+$/, '') || null;
+    const candidate = stripLeadingDelimiter(afterVersion).replace(/\s*(?:[✅📋🚧]\s*)+$/, '') || null;
+    // #4134 (§7.2 rule 6 floor): a "name" with no letter or digit anywhere is
+    // heading structure, not a curated name. The pinned rule takes everything
+    // AFTER the version token, so a name-then-version heading (`# Roadmap:
+    // Project — Name (v1.13)` — the shape a first-ever ROADMAP.md drifts into)
+    // leaves exactly `)` there, which used to be returned as a COMPLETE-scope
+    // name and propagated into init.* output and STATE.md. Refuse it: callers
+    // already report the honest rule-6 answer (version kept, `name: null`,
+    // scope TRUNCATED) for an unresolvable name. A name that merely CONTAINS
+    // punctuation is untouched — `(` is an ordinary name character (#3171) —
+    // and digits alone qualify (`## v4.0 — 42` is the name `42`).
+    const name = candidate !== null && hasNameableContent(candidate) ? candidate : null;
     return { version, name };
 }
 /**
@@ -1614,7 +1741,7 @@ function getMilestoneInfo(cwd) {
             const listMatch = roadmap.match(new RegExp(`🚧\\s*\\*?\\*?${escapedVer}\\*?\\*?\\s+([^*\\n]+)`, 'i'));
             if (listMatch) {
                 const name = stripLeadingDelimiter(listMatch[1]);
-                if (name)
+                if (name && hasNameableContent(name))
                     return scoped({ version: stateVersion, name }, SCOPE.COMPLETE);
             }
             // #3216: heading selection routes through the shared owner
@@ -1648,7 +1775,10 @@ function getMilestoneInfo(cwd) {
         // (unchanged from the pre-#3216 fallback).
         const inProgressMatch = roadmap.match(/🚧\s*\*\*v(\d+(?:\.\d+)+)\s+([^*]+)\*\*/);
         if (inProgressMatch) {
-            return scoped({ version: 'v' + inProgressMatch[1], name: inProgressMatch[2].trim() }, SCOPE.COMPLETE);
+            const inProgressName = inProgressMatch[2].trim();
+            if (hasNameableContent(inProgressName)) {
+                return scoped({ version: 'v' + inProgressMatch[1], name: inProgressName }, SCOPE.COMPLETE);
+            }
         }
         // #3216: enumerate every OPEN (non-shipped) milestone heading via the
         // shared owner and take the first in document order — deletes the
@@ -2015,6 +2145,69 @@ function currentMilestoneRawRanges(content, cwd) {
     }
     return { primary: { start: sectionStart, end: sectionEnd }, details };
 }
+/**
+ * #4731 — extract a bold-labeled phase field (Goal, Requirements, ...) reading
+ * past hard-wrapped continuation lines. The roadmapper soft-wraps long fields
+ * at ~85 chars, so a single-line capture silently truncated every wrapped
+ * Goal/Requirements. Stops at: another `**Field**` label line, a blank line,
+ * or any heading. Wrapped lines are trimmed and joined with single spaces; a
+ * single-line field is returned unchanged (trimmed). Returns null when the
+ * label is absent.
+ */
+function extractPhaseFieldMultiline(section, label) {
+    // #2769 label shapes: `**X:**`, `**X**:`, and the spaced `**X** :`.
+    // #4837: anchored to line start (`^[ \t]*`, `m` flag) so an inline
+    // `**Label**` mention embedded in an EARLIER field's own body text cannot
+    // shadow the real field's own declaration line. `[ \t]*` (not `\s*`) keeps
+    // the anchor scoped to same-line leading whitespace under the `m` flag.
+    const labelRe = new RegExp('^[ \\t]*\\*\\*' + label + '(?::\\*\\*|\\*\\*\\s*:?)\\s*([^\\n]+)', 'im');
+    const match = section.match(labelRe);
+    if (!match)
+        return null;
+    const startIdx = match.index ?? 0;
+    const after = section.slice(startIdx + match[0].length);
+    const firstLine = match[1].trim();
+    // #4837 (isolated-review finding): the continuation loop's fence-stop check
+    // only ever sees lines AFTER the label's own line — a fence opener on the
+    // SAME line as the label (`**Requirements:** ```js`) was invisible to it,
+    // leaking one line of fence content before the closing fence line
+    // coincidentally matched the same stop check. Checked here too, so a fence
+    // opening on the label's own line is caught just as conservatively.
+    if (/^(?:`{3,}|~{3,})/.test(firstLine))
+        return null;
+    const contLines = [];
+    const lines = after.split('\n');
+    for (let li = 0; li < lines.length; li++) {
+        const raw = lines[li];
+        // The split's first element is the remainder of the captured first line's
+        // own newline — an empty leading element is the line break, not a blank
+        // continuation line.
+        if (li === 0 && !raw.trim())
+            continue;
+        if (!raw.trim())
+            break;
+        // #4837: a list item is a structural boundary — the real corruption
+        // vector (a `- Deferred to Phase N: OTHER-ID` bullet folding a foreign
+        // REQ-ID into this field's citation-scan input).
+        if (/^\s*[-*+]\s/.test(raw))
+            break;
+        // #4837: case-insensitive label-start character class — a
+        // lowercase-first-letter label (`**requirements:**`) is as much a field
+        // boundary as a capitalized one.
+        if (/^\s*\*\*[A-Za-z][A-Za-z ]*:?(\*\*)?:?\s/.test(raw))
+            break;
+        if (/^\s*#{1,4}\s/.test(raw))
+            break;
+        if (/^\s*\|/.test(raw))
+            break;
+        // #4837: a fenced code block opener stops the scan — folding fence
+        // content is never safe, and stopping early is conservative.
+        if (/^\s*(?:`{3,}|~{3,})/.test(raw))
+            break;
+        contLines.push(raw.trim());
+    }
+    return [firstLine, ...contLines].join(' ').trim() || null;
+}
 module.exports = {
     stripShippedMilestones,
     extractCurrentMilestone,
@@ -2036,6 +2229,7 @@ module.exports = {
     // own doc comment. milestone.cts's destructive-consumer guard consumes
     // this instead of composing locate+select+section-end itself.
     sliceMilestoneWindow,
+    milestoneSections,
     hasVersionedMilestones,
     hasMilestoneSectioning,
     // #3642: the >=1 sibling buildStateFrontmatter's unbounded branch consumes.
@@ -2049,9 +2243,16 @@ module.exports = {
     // guards and the edit-phase workflow's pre/post capture are built on.
     scanMilestonePhaseIds,
     collectTablePhaseRows,
+    hasPhaseListingTableHeader,
     findMilestoneScopeHeadingLines,
     // #3641: the scope axis's phase-ENTRY predicate, exported so roadmap
     // validate's V004 document-level check routes through the same single
     // owner (and its convention gate) instead of a private inline copy.
+    extractPhaseFieldMultiline,
     hasPhaseEntries,
+    // #4144 round 5 Blocker 1: the readers' own phase-heading grammar, so the
+    // bracket roadmap migrator's "phase-like but unparsed" refusal
+    // (src/roadmap-upgrade.cts) can gate on it instead of a private, looser
+    // "starts with the word Phase" regex.
+    isPhaseHeadingText,
 };