@opengsd/gsd-core 1.18.0 → 1.20.0

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

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Roadmap Progress Module (#5761, Phase 1 of epic #5692): the single owner of
+ * "which table is this ROADMAP's Progress table, and what is its milestone
+ * slice".
+ *
+ * Before this module the question was answered by six locators/scopers that
+ * disagreed on `## Progress Tracker`, on a `## Progress` inside a fenced block,
+ * and on the headingless fallback. Every READER now asks `locateRoadmapProgress`
+ * (or, for the "does this span hold the Progress section" probe,
+ * `findProgressSection`); a second hand-written `## Progress` regex or
+ * table-locating call in a reader is the DEFECT.GENERATIVE-FIX shape.
+ *
+ * The rule, defined once:
+ *   - The Progress section is the first level-2 ATX heading, outside fenced
+ *     code, whose text starts with the word `Progress` (`## Progress`,
+ *     `## Progress Tracker`). It runs to the next level-1/2 heading outside
+ *     fenced code.
+ *   - The table is the first table in that section whose header is a SUPERSET
+ *     of the requested column set (ADR-2143 §3: addressed by NAME, never
+ *     ordinal). A section with no matching table yields no table; it does not
+ *     fall through to the rest of the document (#2012 decoy avoidance).
+ *   - A document with no Progress heading is scanned whole (a headingless
+ *     milestone slice, #1445, keeps resolving).
+ *   - Two readers had a wider pre-owner reach and ask for it by name, so the
+ *     rule stays single (#5692: no behavior change for existing ROADMAP.md
+ *     files): `levels: [1, 2]` for the archive-span probe, which always took a
+ *     level-1 `# Progress`, and `sectionMiss: 'document'` for the workstream
+ *     inventory, which always read a table outside a table-less section.
+ *   - The milestone slice (#5165): when the caller names a milestone and the
+ *     table carries a `Milestone` column, only that milestone's rows.
+ *
+ * The writers (`roadmap.cts` update-plan-progress / phase add, `phase.cts`
+ * complete / remove) cut their slice with `editRoadmapProgress` (#5762), the
+ * write side of the same rule, so a writer edits only the section the readers
+ * read. `phase.cts`'s `cmdPhaseComplete` already-complete check still slices
+ * the Milestone column itself, with a blank-milestone-matches-nothing rule this
+ * owner deliberately does not share.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isProgressHeadingTitle = isProgressHeadingTitle;
+exports.normalizeMilestoneToken = normalizeMilestoneToken;
+exports.milestoneVersionOf = milestoneVersionOf;
+exports.findProgressSection = findProgressSection;
+exports.editRoadmapProgress = editRoadmapProgress;
+exports.locateRoadmapProgress = locateRoadmapProgress;
+const markdown_table_cjs_1 = require("./markdown-table.cjs");
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+/** The canonical column set both RoadmapProgress variants carry. */
+const CANONICAL_COLUMNS = ['Phase', 'Plans Complete', 'Status', 'Completed'];
+/**
+ * The ONE textual expression of "this heading is titled Progress": the title
+ * starts with the word `Progress`, any suffix admitted (`Progress`,
+ * `Progress Tracker`, `Progress (v2.1)`), case-insensitive. `findProgressSection`
+ * adds the level-2 anchor; the bracket writers (`phase.cts`) reuse the title
+ * test at their own levels (#4304).
+ */
+function isProgressHeadingTitle(text) {
+    return /^Progress\b/i.test(text.trim());
+}
+/**
+ * #5165: a milestone token compared by identity, not spelling — `v1.1`, `V1.1`
+ * and ` 1.1 ` name one milestone. A hand-decorated Progress cell
+ * (`**v1.1**`, `` `v1.1` ``, `v1.1 (current)`) still names its first
+ * whitespace-separated token. Absent/blank tokens normalize to `''`.
+ */
+function normalizeMilestoneToken(value) {
+    // `[v1.1](ROADMAP.md#v11)` names its link text.
+    const unlinked = (milestoneVersionOf(value) ?? '').replace(/\[([^\]]*)\]\([^)]*\)/g, '$1');
+    const first = unlinked.split(/\s+/)[0] ?? '';
+    return first.replace(/^[*_`]+|[*_`:,;]+$/g, '').replace(/^v/i, '').toLowerCase();
+}
+/**
+ * #5165: a STATE.md `milestone:` frontmatter value as a trimmed version string,
+ * or null when it is absent, blank or not scalar text.
+ */
+function milestoneVersionOf(value) {
+    if (typeof value !== 'string' && typeof value !== 'number')
+        return null;
+    const text = String(value).trim();
+    return text === '' ? null : text;
+}
+/**
+ * The Progress section of `content`: the first level-2 heading (`levels` widens
+ * this) outside fenced code whose text starts with the word `Progress`, up to
+ * the next level-1/2 heading. Null when the document has no such heading.
+ */
+function findProgressSection(content, options = {}) {
+    const headings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content);
+    const { active, exclude, levels = [2] } = options;
+    const isProgress = (h) => levels.includes(h.level) && isProgressHeadingTitle(h.text) && !(exclude && exclude(h.offset));
+    // #5553: with an active-milestone range, the first Progress heading INSIDE it wins over an
+    // earlier one (a shipped plain section's own table); with none in range, the first overall.
+    const inActive = active ? headings.findIndex((h) => isProgress(h) && h.offset >= active.start && h.offset < active.end) : -1;
+    const index = inActive !== -1 ? inActive : headings.findIndex(isProgress);
+    if (index === -1)
+        return null;
+    return (0, markdown_sectionizer_cjs_1.headingSliceRange)(content, headings, index, headings[index].level);
+}
+/**
+ * The WRITE side of the same rule (#5762): run `edit` on the Progress section
+ * `findProgressSection` locates and splice the result back byte-exact, so a
+ * writer can only ever edit the section the readers read.
+ *
+ * A document with no Progress heading is what the readers scan whole;
+ * `headingless: 'whole'` (default) gives `edit` that same whole document,
+ * `'skip'` leaves it untouched (a destructive writer that must not guess a
+ * table by column names alone).
+ */
+function editRoadmapProgress(content, edit, options = {}) {
+    const section = findProgressSection(content, { active: options.active });
+    if (!section)
+        return options.headingless === 'skip' ? content : edit(content);
+    return (0, markdown_sectionizer_cjs_1.editHeadingSlice)(content, section, edit);
+}
+/** Which table is the Progress table, and what is its milestone slice. */
+function locateRoadmapProgress(content, options = {}) {
+    const section = findProgressSection(content);
+    const scoped = section ? content.slice(section.start, section.end) : content;
+    // `sectionMiss: 'document'` widens each column set's probe from the section to the whole
+    // document, set by set, so an earlier set found anywhere still beats a later set in the section.
+    const widen = section !== null && options.sectionMiss === 'document';
+    let table = null;
+    for (const columns of options.columns ?? [CANONICAL_COLUMNS]) {
+        table = (0, markdown_table_cjs_1.findTableWithColumns)(scoped, [...columns]) ?? (widen ? (0, markdown_table_cjs_1.findTableWithColumns)(content, [...columns]) : null);
+        if (table)
+            break;
+    }
+    if (!table)
+        return { table: null, rows: [], section };
+    const want = normalizeMilestoneToken(options.milestone);
+    const rows = want !== '' && table.columns.includes('Milestone')
+        ? table.rows.filter((r) => normalizeMilestoneToken(r['Milestone']) === want)
+        : table.rows;
+    return { table, rows, section };
+}

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

@@ -12,8 +12,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-const node_child_process_1 = require("node:child_process");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const phase_entry_grammar_cjs_1 = require("./phase-entry-grammar.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -1398,10 +1398,11 @@ function computeBracketPlan(cwd) {
     // bullet stayed legacy after an otherwise-done migration, so the
     // bracket-mode milestone id set carried the stale legacy token alongside
     // the bracket ones.
-    const CHECKLIST_BULLET_PREFIX_SRC = '[-*]\\s*\\[[ x]\\]\\s*\\*{0,2}';
+    // #5764: the prefix is the phase-entry grammar's (line-anchored, indent included).
+    const CHECKLIST_BULLET_PREFIX_SRC = (0, phase_entry_grammar_cjs_1.phaseEntryPrefixSrc)();
     const CHECKLIST_PHASE_INTRO_SRC = phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, undefined, true);
-    const mnnChecklistRe = new RegExp(`^(\\s*${CHECKLIST_BULLET_PREFIX_SRC})${CHECKLIST_PHASE_INTRO_SRC}(${MNN_SOURCE_TOKEN_SOURCE})(${OPTIONAL_PHASE_TAG_SOURCE})`, 'i');
-    const legacyChecklistRe = new RegExp(`^(\\s*${CHECKLIST_BULLET_PREFIX_SRC})${CHECKLIST_PHASE_INTRO_SRC}(${PHASE_NUMBER_TOKEN_SOURCE})(${OPTIONAL_PHASE_TAG_SOURCE})`, 'i');
+    const mnnChecklistRe = new RegExp(`(${CHECKLIST_BULLET_PREFIX_SRC})${CHECKLIST_PHASE_INTRO_SRC}(${MNN_SOURCE_TOKEN_SOURCE})(${OPTIONAL_PHASE_TAG_SOURCE})`, 'i');
+    const legacyChecklistRe = new RegExp(`(${CHECKLIST_BULLET_PREFIX_SRC})${CHECKLIST_PHASE_INTRO_SRC}(${PHASE_NUMBER_TOKEN_SOURCE})(${OPTIONAL_PHASE_TAG_SOURCE})`, 'i');
     // #4144 round 8 I1: `legacyChecklistRe` above requires nothing at all
     // after the number/tag — deliberately, since Tier 1 (reader-recognized,
     // `isReaderRecognizedBullet` below) must match exactly what the readers'
@@ -1753,7 +1754,8 @@ function computeMigrationPlan(cwd, options = {}) {
         if (roadmapEdits.some(e => e.lineIndex === i))
             continue;
         // Match checklist items: "- [ ] **Phase N:**" or "- [x] Phase N:"  (also decimal)
-        const checklistMatch = line.match(new RegExp(`^(\\s*-\\s*\\[[ x]\\]\\s*\\*{0,2}Phase\\s+)(${PHASE_NUMBER_TOKEN_SOURCE})(\\s*[:\\s*])`, 'i'));
+        // The entry prefix (marker, box, bold token) is the phase-entry grammar's (#5764).
+        const checklistMatch = line.match(new RegExp(`(${(0, phase_entry_grammar_cjs_1.phaseEntryPrefixSrc)()}Phase[ \\t]+)(${PHASE_NUMBER_TOKEN_SOURCE})(\\s*[:\\s*])`, 'i'));
         if (checklistMatch) {
             const legacyNum = checklistMatch[2];
             const cIntPart = parseInt(legacyNum, 10);
@@ -1779,7 +1781,7 @@ function computeMigrationPlan(cwd, options = {}) {
                     newId = found.newId;
             }
             if (newId) {
-                const newLine = line.replace(new RegExp(`^(\\s*-\\s*\\[[ x]\\]\\s*\\*{0,2}Phase\\s+)${PHASE_NUMBER_TOKEN_SOURCE}(\\s*[:\\s*])`, 'i'), `$1${newId}$2`);
+                const newLine = line.replace(new RegExp(`(${(0, phase_entry_grammar_cjs_1.phaseEntryPrefixSrc)()}Phase[ \\t]+)${PHASE_NUMBER_TOKEN_SOURCE}(\\s*[:\\s*])`, 'i'), `$1${newId}$2`);
                 if (newLine !== line) {
                     roadmapEdits.push({ lineIndex: i, from: line, to: newLine });
                 }
@@ -1923,7 +1925,45 @@ function applyMigration(cwd, plan, options = {}) {
     // ── Real run: verify clean working tree ───────────────────────────────────
     let gitStatus;
     try {
-        gitStatus = (0, node_child_process_1.execSync)('git status --porcelain', { cwd, encoding: 'utf8', windowsHide: true, timeout: 10_000 });
+        // #5048: this is a read-only spawn, but git still refreshes the index under
+        // it and takes the optional `.git/index.lock` to write the refreshed copy
+        // back — which can lose a race against a real `git add` / `git commit` in
+        // the same repo. Routing through the shared execGit seam (CONTEXT.md, OS
+        // Shell Projection) is what gets GIT_OPTIONAL_LOCKS=0 here; a bare execSync
+        // bypassed the seam and therefore the opt-out, so this call site was the one
+        // read-only `git status` the seam change did not reach. shell-free, so no
+        // argv quoting or PATH-resolution policy is introduced.
+        const statusTimeoutMs = 10_000;
+        const result = (0, shell_command_projection_cjs_1.execGit)(['status', '--porcelain'], { cwd, timeout: statusTimeoutMs });
+        // #5048: execSync carried the cause on the thrown error. execGit reports a
+        // timeout, a spawn/buffer failure or a signal through `timedOut`/`error`/
+        // `signal` with an exit code of `status ?? 1` and often an empty stderr.
+        // Order matters: a maxBuffer overflow returns signal SIGTERM *and*
+        // error.code ENOBUFS — check `error` before `signal` so the real cause is
+        // not reported as "killed by SIGTERM". Only a genuine non-zero exit falls
+        // through. (ENOENT is rewritten by `_spawnResult` to exit 127 + stderr.)
+        if (result.timedOut) {
+            throw new Error(`git status timed out after ${statusTimeoutMs} ms`);
+        }
+        if (result.error) {
+            // The cause is not always a failed spawn: ENOBUFS and EPERM reach this
+            // branch with the process already started (a maxBuffer overflow returns
+            // signal SIGTERM *and* error.code ENOBUFS). So the message stays neutral
+            // about starting and names the code instead of inferring a cause from it.
+            const code = result.error.code;
+            const why = code === 'ENOBUFS' ? 'output exceeded the buffer' : code;
+            const detail = why && !result.error.message.includes(why)
+                ? `${result.error.message} (${why})`
+                : result.error.message;
+            throw new Error(detail);
+        }
+        if (result.signal) {
+            throw new Error(`git status was killed by ${result.signal}`);
+        }
+        if (result.exitCode !== 0) {
+            throw new Error(result.stderr || `git exited ${result.exitCode}`);
+        }
+        gitStatus = result.stdout;
     }
     catch (err) {
         throw new Error(`git status failed: ${err.message}`);