@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/lib/markdown-table.cjs

@@ -11,7 +11,7 @@
  * {ok,data|kind}; the two never mix (different modules).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TABLE_SCHEMAS = void 0;
+exports.QUICK_TASKS_SECTION_ABSENT = exports.TABLE_SCHEMAS = void 0;
 exports.matchTableSchema = matchTableSchema;
 exports.splitTableRow = splitTableRow;
 exports.isDelimiterRow = isDelimiterRow;
@@ -23,6 +23,7 @@ exports.findTableBySchema = findTableBySchema;
 exports.findTableWithColumns = findTableWithColumns;
 exports.escapeCell = escapeCell;
 exports.appendQuickTaskRow = appendQuickTaskRow;
+exports.resetQuickTaskRows = resetQuickTaskRows;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // ─── Schema registry ──────────────────────────────────────────────────────────
 /**
@@ -280,32 +281,54 @@ function unescapeCellText(raw) {
  */
 function updateTableCell(tableText, match, column, newValue) {
     const lines = splitLinesWithOffsets(tableText);
+    // #3255: pick the first VALID table whose columns include `column`. The prior
+    // code bound to the FIRST table of any shape and returned 'unknown column' if
+    // that one lacked the column — so a section holding a summary table above the
+    // target (e.g. ## Traceability: a phase-summary table, then the requirement
+    // rows) never reached the target table. Scan for the first valid table that
+    // carries the column; if none does but a valid table exists, still return
+    // 'unknown column' (single-table behaviour unchanged). Track the first
+    // malformation reason so a lone malformed table keeps its specific error.
     let headerIdx = -1;
+    let columns = [];
+    let firstValidIdx = -1;
+    let firstMalformedReason = null;
+    const recordMalformed = (reason) => {
+        if (firstMalformedReason === null && firstValidIdx === -1)
+            firstMalformedReason = reason;
+    };
     for (let i = 0; i < lines.length; i++) {
         const trimmed = lines[i].line.trim();
-        if (trimmed.startsWith('|') && trimmed.indexOf('|', 1) !== -1) {
+        if (!trimmed.startsWith('|') || trimmed.indexOf('|', 1) === -1)
+            continue;
+        const delimiterLine = lines[i + 1]?.line;
+        if (delimiterLine === undefined || !delimiterLine.trim().startsWith('|')) {
+            recordMalformed('missing delimiter row');
+            continue;
+        }
+        const candidateRanges = splitTableRowRanges(lines[i].line, lines[i].start);
+        const candidateColumns = candidateRanges.map((r) => unescapeCellText(tableText.slice(r.start, r.end)));
+        const delimiterCells = splitTableRow(delimiterLine);
+        if (!isDelimiterRow(delimiterCells)) {
+            recordMalformed('missing delimiter row');
+            continue;
+        }
+        if (delimiterCells.length !== candidateColumns.length) {
+            recordMalformed('delimiter/header column count mismatch');
+            continue;
+        }
+        if (firstValidIdx === -1)
+            firstValidIdx = i;
+        if (candidateColumns.includes(column)) {
             headerIdx = i;
+            columns = candidateColumns;
             break;
         }
     }
     if (headerIdx === -1) {
-        return { ok: false, reason: 'no table found' };
-    }
-    const delimiterLine = lines[headerIdx + 1]?.line;
-    if (delimiterLine === undefined || !delimiterLine.trim().startsWith('|')) {
-        return { ok: false, reason: 'missing delimiter row' };
-    }
-    const headerRanges = splitTableRowRanges(lines[headerIdx].line, lines[headerIdx].start);
-    const columns = headerRanges.map((r) => unescapeCellText(tableText.slice(r.start, r.end)));
-    const delimiterCells = splitTableRow(delimiterLine);
-    if (!isDelimiterRow(delimiterCells)) {
-        return { ok: false, reason: 'missing delimiter row' };
-    }
-    if (delimiterCells.length !== columns.length) {
-        return { ok: false, reason: 'delimiter/header column count mismatch' };
-    }
-    if (!columns.includes(column)) {
-        return { ok: false, reason: `unknown column: ${column}` };
+        if (firstValidIdx !== -1)
+            return { ok: false, reason: `unknown column: ${column}` };
+        return { ok: false, reason: firstMalformedReason ?? 'no table found' };
     }
     const targetColIdx = columns.indexOf(column);
     let selectedRange;
@@ -623,6 +646,17 @@ function escapeCell(value) {
         .replace(/\|/g, '\\|')
         .trim();
 }
+/**
+ * Shared sentinel `reason` returned by both `appendQuickTaskRow` and
+ * `resetQuickTaskRows` when the "Quick Tasks Completed" heading is absent
+ * from `stateContent` (#2142). The section is created lazily by
+ * `gsd-core/workflows/quick.md` Step 7b and is absent from
+ * `gsd-core/templates/state.md`, so an absent section is the common case,
+ * not an anomaly — callers compare against this constant rather than
+ * matching on the free-form reason string (CONTRIBUTING.md "Prohibited:
+ * Raw Text Matching").
+ */
+exports.QUICK_TASKS_SECTION_ABSENT = 'no Quick Tasks Completed section';
 /**
  * Append one row to STATE.md's "Quick Tasks Completed" table.
  *
@@ -645,7 +679,7 @@ function escapeCell(value) {
 function appendQuickTaskRow(stateContent, fields) {
     const section = (0, markdown_sectionizer_cjs_1.collectSection)(stateContent, (h) => /^quick tasks completed$/i.test(h.text.trim()));
     if (!section) {
-        return { ok: false, reason: 'no Quick Tasks Completed section' };
+        return { ok: false, reason: exports.QUICK_TASKS_SECTION_ABSENT };
     }
     const parsed = parseMarkdownTable(section.body);
     if (!parsed.ok) {
@@ -694,5 +728,84 @@ function appendQuickTaskRow(stateContent, fields) {
     const content = (0, markdown_sectionizer_cjs_1.replaceSection)(stateContent, section, newBody);
     return { ok: true, value: { content, row, variant: match.label } };
 }
+// ─── resetQuickTaskRows (#2142) ────────────────────────────────────────────
+/**
+ * Clear every DATA row from STATE.md's "Quick Tasks Completed" table, leaving
+ * the header + delimiter lines byte-identical, for use at milestone close when
+ * `--archive-quick` has actually moved the underlying `.planning/quick/*`
+ * directories out from under the table (see `src/milestone.cts`'s
+ * `archiveQuickTaskDirectories` / `cmdMilestoneComplete` wiring).
+ *
+ * Mirrors `appendQuickTaskRow`'s exact contract (same `collectSection` ->
+ * `parseMarkdownTable` -> `matchTableSchema` pipeline, same fail-loud posture,
+ * same EOL-detect-before-split handling) rather than inventing a second one:
+ *   - no "Quick Tasks Completed" heading -> `{ok:false, reason:
+ *     QUICK_TASKS_SECTION_ABSENT}` (no-op; a STATE.md without the section has
+ *     nothing to reset — per #2142 design doc §40, behavior table row 5, the
+ *     section is created lazily by quick.md Step 7b and is absent from
+ *     templates/state.md, so absence is the common path, not an anomaly.
+ *     Callers MUST treat this sentinel as silent — never surface it as a
+ *     `preservation_warnings` entry).
+ *   - the section body doesn't parse as a GFM table -> `{ok:false, reason}`.
+ *   - the table's header doesn't match a known `TABLE_SCHEMAS.QuickTasks`
+ *     variant -> `{ok:false, reason}` and — CRITICAL — no modification at
+ *     all. A user-added column means the data can't be safely addressed by
+ *     name, so clearing it would destroy rows under a schema we don't
+ *     understand (Postel's Law: liberal in accepting known shapes,
+ *     conservative about destroying what we don't).
+ */
+function resetQuickTaskRows(stateContent) {
+    if (typeof stateContent !== 'string' || stateContent.trim() === '') {
+        return { ok: false, reason: 'empty or non-string input' };
+    }
+    const section = (0, markdown_sectionizer_cjs_1.collectSection)(stateContent, (h) => /^quick tasks completed$/i.test(h.text.trim()));
+    if (!section) {
+        return { ok: false, reason: exports.QUICK_TASKS_SECTION_ABSENT };
+    }
+    const parsed = parseMarkdownTable(section.body);
+    if (!parsed.ok) {
+        return { ok: false, reason: `quick-tasks table: ${parsed.reason}` };
+    }
+    const match = matchTableSchema(parsed.value.columns);
+    if (!match || match.id !== 'QuickTasks') {
+        // Refuse the reset — keep every row, caller-owned content is untouched.
+        return {
+            ok: false,
+            reason: `unrecognized Quick Tasks schema (columns: ${parsed.value.columns.join(' | ')})`,
+        };
+    }
+    const cleared = parsed.value.rows.length;
+    // Detect the section's EOL BEFORE splitting on /\r?\n/ (which discards it) —
+    // exactly `appendQuickTaskRow`'s convention — so a CRLF document is not
+    // downgraded to mixed EOL by the rejoin below.
+    const eol = /\r\n/.test(section.body) ? '\r\n' : '\n';
+    const lines = section.body.split(/\r?\n/);
+    let headerIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim().startsWith('|')) {
+            headerIdx = i;
+            break;
+        }
+    }
+    // headerIdx is always found here — parseMarkdownTable already confirmed a
+    // header + delimiter row exist in this same `section.body`.
+    let lastTableLineIdx = headerIdx + 1; // delimiter row, when there are zero data rows
+    for (let i = headerIdx + 2; i < lines.length; i++) {
+        if (!lines[i].trim().startsWith('|'))
+            break;
+        lastTableLineIdx = i;
+    }
+    // Keep the header + delimiter lines [0 .. headerIdx+1] plus everything
+    // after the contiguous run of `|`-prefixed data rows — dropping only the
+    // data rows themselves. Non-table content before/after the table inside
+    // the section is preserved untouched.
+    const newLines = [
+        ...lines.slice(0, headerIdx + 2),
+        ...lines.slice(lastTableLineIdx + 1),
+    ];
+    const newBody = newLines.join(eol);
+    const content = (0, markdown_sectionizer_cjs_1.replaceSection)(stateContent, section, newBody);
+    return { ok: true, value: { content, cleared, variant: match.label } };
+}
 // Consumers: require('../gsd-core/bin/lib/markdown-table.cjs')
 // Named CJS exports are the canonical surface (ADR-457 .cts → .cjs build-at-publish).