@opengsd/gsd-core 1.19.0 → 1.20.0

package/gsd-core/bin/lib/milestone.cjs

@@ -38,7 +38,7 @@ const stateContract = require("./state-contract.cjs");
 const { publishStateContract } = stateContract;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, matchPhaseDirs, isSentinelPhaseId, isSentinelPhaseDir, buildPhaseHeadingScanRegex, PHASE_HEADING_BASELINE } = phaseIdMod;
+const { isSentinelPhaseId, isSentinelPhaseDir, buildPhaseHeadingScanRegex, PHASE_HEADING_BASELINE } = phaseIdMod;
 const pattern_cjs_1 = require("./pattern.cjs");
 const milestone_release_map_cjs_1 = require("./milestone-release-map.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -55,7 +55,7 @@ const planScanMod = require("./plan-scan.cjs");
 const { scanPhasePlans } = planScanMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { listMilestonePhaseDirs } = phaseLocatorMod;
+const { phaseDirectoryOptions, listMilestonePhaseDirs, resolvePhaseDirectoryLookup, matchPhaseDirsForLookup } = phaseLocatorMod;
 const { planningPaths, resolvePhaseIdConvention } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
 // ADR-3408 §8.3 / #3469: `writeStateMd` gets sync and NO preservation — the
@@ -73,43 +73,6 @@ const { syncAndPreserveStateMd, withStateLock, readModifyWriteStateMd, assertVer
 // the caller-supplied `--archive-version` override and the STATE.md-derived
 // live-read value, so a crafted value cannot escape `.planning/milestones/`.
 const ARCHIVE_VERSION_LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
-/**
- * Scope an `updateTableCell` call to the `## Traceability` (or
- * `## Traceability Status`) heading's own section — up to the next H1/H2
- * heading — instead of handing it the WHOLE REQUIREMENTS.md content.
- *
- * F1 (#2245 review, BLOCKER): `updateTableCell` binds to the FIRST GFM table
- * found in whatever text it is given. The shipped requirements template
- * (gsd-core/templates/requirements.md) puts an `## Out of Scope` table
- * (`| Feature | Reason |`, no `Status` column) BEFORE `## Traceability` — so
- * an unscoped whole-file call targets the Out-of-Scope table instead, fails
- * with `{ok:false, reason:'unknown column: Status'}`, and the real
- * Traceability row is never flipped, while the checkbox surface still flips
- * and the command reports success (the #2140 silent-divergence class one
- * level deeper). Mirrors phase.cts's `editProgressHeadingSlice` scoping of
- * `## Progress` writes to that heading's own slice.
- *
- * Falls back to running `updateTableCell` against the whole `text` when no
- * `## Traceability` heading exists — matching the previous (unscoped)
- * behaviour for a REQUIREMENTS.md whose traceability table sits under some
- * other heading, or with no heading at all (never worse than before this fix).
- */
-function updateTraceabilityCell(text, match, column, newValue) {
-    const headingMatch = text.match(/^##[ \t]+Traceability(?:[ \t]+Status)?\b/im);
-    if (!headingMatch || headingMatch.index === undefined) {
-        return (0, markdown_table_cjs_1.updateTableCell)(text, match, column, newValue);
-    }
-    const headingOffset = headingMatch.index;
-    const before = text.slice(0, headingOffset);
-    const fromHeading = text.slice(headingOffset);
-    const nextHeadingOffset = fromHeading.search(/\n#{1,2}[ \t]/);
-    const scoped = nextHeadingOffset >= 0 ? fromHeading.slice(0, nextHeadingOffset) : fromHeading;
-    const after = nextHeadingOffset >= 0 ? fromHeading.slice(nextHeadingOffset) : '';
-    const result = (0, markdown_table_cjs_1.updateTableCell)(scoped, match, column, newValue);
-    if (!result.ok)
-        return result;
-    return { ok: true, value: before + result.value + after };
-}
 function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
     if (!reqIdsRaw || reqIdsRaw.length === 0) {
         error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
@@ -187,7 +150,7 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
         // Complete" gate is folded into the newValue callback so one
         // updateTableCell call both probes the current value and writes.
         let tableHit = false;
-        const tableUpdate = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+        const tableUpdate = (0, markdown_table_cjs_1.updateTraceabilityCell)(reqContent, rowMatch, 'Status', (current) => {
             // #2788: accept `Gaps Found` as a forward input too — `revert-phase` (the
             // documented gaps_found response) leaves a row stranded at Gaps Found with
             // no inverse; a genuinely-satisfied requirement must be able to reach
@@ -230,7 +193,7 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
         // that genuinely exists. Probe via a no-op updateTableCell write (its own
         // tolerant scan) instead of findTableWithColumns (whole-table parse gate).
         let currentStatusCell = '';
-        const statusProbe = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+        const statusProbe = (0, markdown_table_cjs_1.updateTraceabilityCell)(reqContent, rowMatch, 'Status', (current) => {
             currentStatusCell = current;
             return current;
         });
@@ -434,7 +397,7 @@ function cmdRequirementsRevertPhase(cwd, reqIdsRaw, raw) {
         // "only flip Pending -> Complete" gate, in reverse).
         const rowMatch = (row) => (Object.values(row)[0] ?? '').trim().toLowerCase() === reqId.toLowerCase();
         let tableHit = false;
-        const tableUpdate = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+        const tableUpdate = (0, markdown_table_cjs_1.updateTraceabilityCell)(reqContent, rowMatch, 'Status', (current) => {
             if (/^complete$/i.test(current.trim())) {
                 tableHit = true;
                 return ' Gaps Found ';
@@ -585,7 +548,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // `platformEnsureDir(archiveDir)` below — a refused run (scope not COMPLETE,
     // no --force) must be a true no-op on disk, and creating the archive
     // directory first left an empty directory behind even on refusal.
-    const isDirInMilestone = getMilestonePhaseFilter(cwd, version);
+    const isDirInMilestone = getMilestonePhaseFilter(cwd, version, undefined, undefined, phaseDirectoryOptions(cwd));
     if (isDirInMilestone.missingExplicitVersion) {
         error(`no phases found for milestone ${version} in ROADMAP.md`);
     }
@@ -610,6 +573,10 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             `entries, even though the ROADMAP has phase entries elsewhere), so phase scoping ` +
             `cannot be trusted for this destructive operation. Re-run with --force to override.`);
     }
+    // #2761/#4304: resolve once for every phase-directory consumer in this
+    // command. The matcher opts in only for bracket; the milestone enumerator
+    // retains the full resolved value it already accepted.
+    const phaseConvention = resolvePhaseIdConvention(cwd);
     // Guard: prevent marking complete when ROADMAP still lists phases that have
     // no directory on disk (disk_status: no_directory). This catches the case
     // where the active milestone was erroneously marked complete before phases
@@ -691,8 +658,8 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             // properly-scaffolded bracket phase reads as disk_status: 'no_directory'
             // — turning a real bracket project's own phases into false "ROADMAP
             // lists N unstarted phase(s)" failures on `milestone complete`.
-            const convention = resolvePhaseIdConvention(cwd);
-            const { regex: phasePattern, phaseNumGroup } = buildPhaseHeadingScanRegex(PHASE_HEADING_BASELINE.ANY_BRACKET, convention);
+            const directoryContext = phaseDirectoryOptions(cwd, undefined, scopedContent);
+            const { regex: phasePattern, phaseNumGroup } = buildPhaseHeadingScanRegex(PHASE_HEADING_BASELINE.ANY_BRACKET, phaseConvention, directoryContext);
             const noDirectoryPhases = [];
             let pm;
             const phaseDirEntries = (() => {
@@ -716,12 +683,14 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
                 // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this local check already covered both 0 and 999; now delegates to the single canonical owner.
                 if (isSentinelPhaseId(phaseNum))
                     continue;
-                const normalized = normalizePhaseName(phaseNum);
+                const lookup = resolvePhaseDirectoryLookup(cwd, phaseNum, undefined, directoryContext);
                 // A phase has disk_status: 'no_directory' when no phase directory
                 // with a matching token exists on disk. Use the same matchPhaseDirs
                 // owner that roadmap.analyze uses to avoid false positives on decimal
-                // (2.1) and letter-suffix (12A) phase IDs. (#2528)
-                const hasDirectory = matchPhaseDirs(phaseDirEntries, normalized, convention).matches.length > 0;
+                // (2.1) and letter-suffix (12A) phase IDs. (#2528) Under #4304 the
+                // current checkout's bracket convention and migration-window legacy
+                // fallback are both owned by the shared lookup adapter.
+                const hasDirectory = matchPhaseDirsForLookup(phaseDirEntries, lookup, undefined, directoryContext).matches.length > 0;
                 if (!hasDirectory) {
                     noDirectoryPhases.push(phaseNum);
                 }
@@ -751,7 +720,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     let totalPlans = 0;
     let totalTasks = 0;
     const accomplishments = [];
-    // #2761 (round-11 BLOCKER): resolved ONCE, ambiently (no explicit `ws` —
+    // #2761: resolved ONCE above, ambiently (no explicit `ws` —
     // this function has none of its own and already resolves everything else
     // off `cwd` via planningPaths(cwd), matching the ambient-workstream
     // contract `resolvePhaseIdConvention`/`planningDir` share), and threaded
@@ -766,7 +735,6 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // the silent-inherit path without changing behavior for `null` /
     // `milestone-prefixed` projects, whose resolved convention is the same
     // value `undefined` would have lazily produced anyway.
-    const phaseConvention = resolvePhaseIdConvention(cwd);
     // #3597 (ADR-3180 Decision 2): SINGLE resolution of "which phase
     // directories belong to the current milestone" AND the SCOPE discriminator
     // that resolution came from — shared verbatim by the read-only stats loop

package/gsd-core/bin/lib/phase-entry-grammar.cjs

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Phase-entry grammar — the one definition of a ROADMAP phase-list entry
+ * (`- [ ] **Phase 1: Name**`): bullet marker, checkbox, bold token and line
+ * anchoring (#5763, Phase 3 of epic #5692; census in #5703).
+ *
+ * Before this module every reader owned a private pattern, and the patterns
+ * disagreed on each axis (`-` only vs `[-*]`; required, optional or `\*{0,2}`
+ * bold; `[ x]` vs `[ xX]` vs `(x| )`; `^`-anchored vs the unanchored forms
+ * behind #4965 and #5545). Readers now compose their pattern from the prefix
+ * built here and keep only their own tail (label, id token, separator).
+ *
+ * The accepted grammar:
+ *   entry  := indent marker mgap box gap bold? gap <caller tail>
+ *   indent := [ \t]*                   — an entry starts its line
+ *   marker := '-' | '*'
+ *   mgap   := [ \t]{1,4}               — a list item: `-[ ]` is not one (#5764)
+ *   box    := '[' (' ' | 'x' | 'X') ']'
+ *   bold   := '**' | '__'              — a reader may require it
+ *   gap    := [ \t]*                   — horizontal whitespace only
+ * A reader that needs plain `- **Phase N**` bullets may make the box optional.
+ *
+ * Writers (flip, delete, renumber, id rewrite) compose their patterns here too
+ * (#5764, Phase 4): `phaseEntryRegExp` for a whole-line match and
+ * `phaseEntrySplitRegExp` when the writer rewrites the box and needs the text on
+ * either side of it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PHASE_ENTRY_BOLD_CLOSE_SRC = exports.PHASE_ENTRY_BOLD_TOKEN_SRC = void 0;
+exports.phaseEntryPrefixSrc = phaseEntryPrefixSrc;
+exports.phaseEntryRegExp = phaseEntryRegExp;
+exports.phaseEntrySplitRegExp = phaseEntrySplitRegExp;
+exports.isPhaseEntryChecked = isPhaseEntryChecked;
+exports.isBoxCharChecked = isBoxCharChecked;
+const MARKER_SRC = '[-*]';
+// A list item has 1 to 4 spaces or tabs after its marker (CommonMark: none is not a list item,
+// five or more makes the rest an indented code block), so `-[ ] **Phase 1**` is not an entry.
+const MARKER_GAP_SRC = '[ \\t]{1,4}';
+const BOLD_TOKEN_SRC = '(?:\\*\\*|__)';
+/** Regex source of one bold token, for a reader that must also consume the closing wrapper. */
+exports.PHASE_ENTRY_BOLD_TOKEN_SRC = BOLD_TOKEN_SRC;
+/**
+ * Regex source of a closing bold wrapper for a reader that captures the entry's
+ * name up to it. `**` closes anywhere; `__` closes only at the end of the line,
+ * so a name that contains `__init__` or `__tests__` is not cut short.
+ */
+exports.PHASE_ENTRY_BOLD_CLOSE_SRC = '(?:\\*\\*|__(?=[ \\t]*\\r?$))';
+/**
+ * Line start, indent, marker and the marker's gap, up to where the box opens.
+ * A leading BOM can only precede the first line; it is not part of the grammar's indent.
+ */
+const LINE_OPEN_SRC = `^\\uFEFF?[ \\t]*${MARKER_SRC}${MARKER_GAP_SRC}`;
+/**
+ * Source for the bold token and its trailing gap. `(?:token[ \t]*)?` rather than
+ * `[ \t]*` + token + `[ \t]*`, which backtracks quadratically on a long blank run.
+ */
+function boldSrcFor(bold) {
+    return bold === 'required' ? `${BOLD_TOKEN_SRC}[ \\t]*` : `(?:${BOLD_TOKEN_SRC}[ \\t]*)?`;
+}
+/** Source for the box interior, honouring the requested state filter. */
+function stateSrc(state) {
+    if (state === 'unchecked')
+        return ' ';
+    if (state === 'checked')
+        return '[xX]';
+    if (state === 'captured')
+        return '([ xX])';
+    return '[ xX]';
+}
+/**
+ * Regex source of everything before the caller's `Phase`/label tail: line start, indent,
+ * marker, box, bold token and the horizontal gaps between them. A `captured`
+ * state adds exactly one capture group (the box character) at the front.
+ */
+function phaseEntryPrefixSrc(options = {}) {
+    const { bold = 'optional', box = 'required', state = 'any', decorated = false } = options;
+    // The decoration may not contain the word `Phase`, so the entry's own label is the first one
+    // on the line and `- [ ] **Phase 5**: needs Phase 2` is not an entry of phase 2. No gap
+    // before the run: `[ \t]*` then a lazy run overlap and backtrack quadratically.
+    if (decorated)
+        return `${LINE_OPEN_SRC}\\[${stateSrc(state)}\\](?:(?!Phase)[^\\r\\n])*?`;
+    const boxSrc = `\\[${stateSrc(state)}\\][ \\t]*`;
+    const body = box === 'optional' ? `(?:${boxSrc})?` : boxSrc;
+    return `${LINE_OPEN_SRC}${body}${boldSrcFor(bold)}`;
+}
+/**
+ * A RegExp for a phase entry: the grammar prefix followed by the caller's
+ * `tailSrc`. The `m` flag is always set, so `^` is a line start.
+ */
+function phaseEntryRegExp(tailSrc, flags = '', options = {}) {
+    const withM = flags.includes('m') ? flags : `${flags}m`;
+    return new RegExp(`${phaseEntryPrefixSrc(options)}${tailSrc}`, withM);
+}
+/**
+ * A RegExp for a phase entry a writer rewrites at the box: capture group 1 is
+ * everything through the opening `[` (indent, marker, gap) and capture group 2
+ * is everything from the closing `]` through the end of `tailSrc` (gap, bold
+ * token, label). A flip is `line.replace(re, '$1x$2')`; the box state itself is
+ * matched, not captured, so the writer chooses the new state. The `m` flag is
+ * always set.
+ */
+function phaseEntrySplitRegExp(tailSrc, flags = '', options = {}) {
+    const { bold = 'optional', state = 'any' } = options;
+    const withM = flags.includes('m') ? flags : `${flags}m`;
+    return new RegExp(`(${LINE_OPEN_SRC}\\[)${stateSrc(state)}(\\][ \\t]*${boldSrcFor(bold)}${tailSrc})`, withM);
+}
+const ENTRY_BOX_RE = new RegExp(`^\\uFEFF?[ \\t]*${MARKER_SRC}${MARKER_GAP_SRC}\\[([ xX])\\]`);
+/**
+ * Whether a phase entry line (or a regex match of one, which starts at the
+ * line) is ticked. The single place the box character is interpreted.
+ */
+function isPhaseEntryChecked(entryText) {
+    const m = ENTRY_BOX_RE.exec(entryText);
+    return m !== null && m[1].toLowerCase() === 'x';
+}
+/** Whether a captured box character (`captured` state option) is a tick. */
+function isBoxCharChecked(boxChar) {
+    return boxChar.toLowerCase() === 'x';
+}

package/gsd-core/bin/lib/phase-id-display.cjs

@@ -75,4 +75,6 @@ function renderBracketMilestoneDisplay(milestone, projectCode) {
 module.exports = {
     renderBracketPhaseDisplay,
     renderBracketMilestoneDisplay,
+    milestoneToken,
+    phaseToken,
 };