* chore(#2143): markdown table model + schema registry + fail-loud pilot — Phase 1 Phase 1 of epic #2143 (ADR-2143): consolidate markdown table parsing onto a canonical seam and migrate the pilot reader. - Add src/markdown-table.cts: parseMarkdownTable (GFM tables -> typed {columns, rows} addressed by column NAME; ragged rows are typed parse errors, not silent), a single-source TABLE_SCHEMAS registry (RoadmapProgress / RequirementsTraceability / QuickTasks / Security, with variants under one id), matchTableSchema, and findTableBySchema. Result<T> is scoped to this seam (distinct from the dispatch Result). - Migrate deriveProgressFromRoadmap (src/phase-lifecycle.cts) off the position-anchored regex to name-based resolution via the seam — fixes #2137 (the 5-column milestone-grouped Progress table previously returned all-null). - Add a schema-backed `gsd-tools quick-tasks-append` subcommand and route fast.md's log_to_state through it, retiring the inline `awk NF-2` column arithmetic — fixes #2133 (addresses #2012, #2119). Cell values are escaped (| and newlines) and the STATE.md read-modify-write is atomic under readModifyWriteStateMd (lost-update race, cf. #500/#905/#1230). - Writer/reader/template parity test guards TABLE_SCHEMAS against drift (ADR-2143 §3 Generative-Fix-Divergence). Registration: .gitignore, eslint.config.mjs, docs/INVENTORY.md + INVENTORY-MANIFEST.json, CONTEXT.md glossary, docs/CLI-TOOLS.md. Behaviour-preserving for the canonical 4-column Progress table; the named bugs are driven fail-first. Extend-never-mutate (ADR-2143 §2). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore(#2242): backfill changeset PR number (#2248) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#2242): escape backslash before pipe in markdown-table cell escaping CodeQL js/incomplete-sanitization (high): escapeCell escaped | -> \| but not the backslash itself. Now escapes \ -> \\ before | -> \|, and splitTableRow unescapes both \\ -> \ and \| -> | symmetrically so cell values (incl. literal backslashes) round-trip exactly. Added backslash round-trip tests. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#2242): read ROADMAP Progress table by column name — supersede #2168 ad-hoc scan Rebase reconciliation with #2168 (the tactical #2137 fix that marked itself "pending #2143"). deriveProgressFromRoadmap now resolves the Progress table via a new seam helper findTableWithColumns (first table whose header is a superset of Phase/Plans Complete/Status/Completed, any order, extra columns ignored) and reads cells by NAME — order/injection-invariant per ADR-2143 §3 — instead of the exact TABLE_SCHEMAS match. This satisfies #2168's column-invariance property test while staying seam-based and preserving its `## Progress` scoping (#2012/#1445). Ragged Progress tables now resolve to null (ADR-2143 fail-loud); updated the stale state.test.cjs assertion that predated the Phase-1 migration. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
367
src/markdown-table.cts
Normal file
367
src/markdown-table.cts
Normal file
@@ -0,0 +1,367 @@
|
||||
/**
|
||||
* Markdown Table Model — canonical GFM table parsing + schema registry seam
|
||||
* (ADR-2143, epic #2143). Pure functions, Node built-ins only, string-in/value-out,
|
||||
* no I/O. Compiled by tsc to gsd-core/bin/lib/markdown-table.cjs.
|
||||
*
|
||||
* NOTE: the `Result<T>` here is the ADR-2143 parse-result shape {ok,value|reason} —
|
||||
* deliberately distinct from command-routing-hub's dispatch `Result` {ok,data|kind};
|
||||
* the two never mix (different modules).
|
||||
*/
|
||||
|
||||
import { collectSection, replaceSection } from './markdown-sectionizer.cjs';
|
||||
|
||||
// ─── Types ────────────────────────────────────────────────────────────────────
|
||||
|
||||
export type Result<T> = { ok: true; value: T } | { ok: false; reason: string };
|
||||
|
||||
/** A parsed GFM pipe table: header column names + rows addressed by column name. */
|
||||
export interface MarkdownTable {
|
||||
columns: string[];
|
||||
rows: Record<string, string>[];
|
||||
}
|
||||
|
||||
/** One recognised header-shape variant of a canonical table kind. */
|
||||
export interface CanonicalTableVariant {
|
||||
label: string;
|
||||
columns: string[];
|
||||
}
|
||||
|
||||
// ─── Schema registry ──────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Canonical column-header shapes for every GFM table GSD parses or generates.
|
||||
* Each entry in `TABLE_SCHEMAS[id]` is one accepted variant (exact column names,
|
||||
* in order); `matchTableSchema` resolves a parsed header back to `{id, label}`.
|
||||
*
|
||||
* This registry is the single source of truth — a parity test
|
||||
* (tests/markdown-table.test.cjs) asserts every variant's header appears
|
||||
* verbatim in the template/workflow file that generates it, so the registry
|
||||
* and the templates can never silently drift (ADR-2143 §3 Generative-Fix-
|
||||
* Divergence guard).
|
||||
*/
|
||||
export const TABLE_SCHEMAS: Record<string, CanonicalTableVariant[]> = {
|
||||
RoadmapProgress: [
|
||||
{ label: 'flat', columns: ['Phase', 'Plans Complete', 'Status', 'Completed'] },
|
||||
{
|
||||
label: 'milestone-grouped',
|
||||
columns: ['Phase', 'Milestone', 'Plans Complete', 'Status', 'Completed'],
|
||||
},
|
||||
],
|
||||
RequirementsTraceability: [
|
||||
{ label: 'default', columns: ['Requirement', 'Phase', 'Status'] },
|
||||
],
|
||||
QuickTasks: [
|
||||
{ label: 'no-status', columns: ['#', 'Description', 'Date', 'Commit', 'Directory'] },
|
||||
{
|
||||
label: 'with-status',
|
||||
columns: ['#', 'Description', 'Date', 'Commit', 'Status', 'Directory'],
|
||||
},
|
||||
],
|
||||
Security: [
|
||||
{ label: 'trust-boundaries', columns: ['Boundary', 'Description', 'Data Crossing'] },
|
||||
{
|
||||
label: 'threat-register',
|
||||
columns: [
|
||||
'Threat ID',
|
||||
'Category',
|
||||
'Component',
|
||||
'Severity',
|
||||
'Disposition',
|
||||
'Mitigation',
|
||||
'Status',
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'accepted-risks',
|
||||
columns: ['Risk ID', 'Threat Ref', 'Rationale', 'Accepted By', 'Date'],
|
||||
},
|
||||
{
|
||||
label: 'audit-trail',
|
||||
columns: ['Audit Date', 'Threats Total', 'Closed', 'Open', 'Run By'],
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
/**
|
||||
* Resolve a parsed table's header columns to the canonical schema it matches
|
||||
* (exact column names, same length, same order), else `null`.
|
||||
*/
|
||||
export function matchTableSchema(columns: string[]): { id: string; label: string } | null {
|
||||
for (const [id, variants] of Object.entries(TABLE_SCHEMAS)) {
|
||||
for (const variant of variants) {
|
||||
if (
|
||||
variant.columns.length === columns.length
|
||||
&& variant.columns.every((col, idx) => col === columns[idx])
|
||||
) {
|
||||
return { id, label: variant.label };
|
||||
}
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
// ─── Parsing ──────────────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Split one GFM table row line into trimmed cell strings.
|
||||
* Strips one leading and one trailing `|`, splits on unescaped `|`, trims
|
||||
* each cell, and unescapes `\\` back to `\` and `\|` back to `|` (the exact
|
||||
* reverse of `escapeCell`'s `\`->`\\` then `|`->`\|` order below), so cell
|
||||
* values round-trip exactly — including literal backslashes.
|
||||
*/
|
||||
function splitTableRow(line: string): string[] {
|
||||
let stripped = line.trim();
|
||||
if (stripped.startsWith('|')) stripped = stripped.slice(1);
|
||||
if (stripped.endsWith('|')) stripped = stripped.slice(0, -1);
|
||||
return stripped.split(/(?<!\\)\|/).map((cell) => cell.trim().replace(/\\([\\|])/g, '$1'));
|
||||
}
|
||||
|
||||
/** True when every delimiter cell matches GFM's `:?-{1,}:?` shape (spaces removed). */
|
||||
function isDelimiterRow(cells: string[]): boolean {
|
||||
return cells.every((cell) => /^:?-{1,}:?$/.test(cell.replace(/\s+/g, '')));
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse the FIRST GFM pipe table found in `sectionText`.
|
||||
*
|
||||
* Defensive by design: never throws — every malformed shape (no table,
|
||||
* missing/misaligned delimiter row, ragged data row) returns a typed
|
||||
* `{ok:false, reason}` instead of silently coercing or dropping data
|
||||
* (ADR-2143 §3 — ragged rows are errors, not silent).
|
||||
*
|
||||
* Scope note: GSD planning tables (STATE.md/ROADMAP.md/requirements.md/
|
||||
* SECURITY.md) are always fully-piped (leading + trailing `|` on every row)
|
||||
* and non-indented — this parser targets THAT shape, not arbitrary
|
||||
* CommonMark (which also allows non-piped rows and up to 3 leading spaces).
|
||||
*/
|
||||
export function parseMarkdownTable(sectionText: string): Result<MarkdownTable> {
|
||||
if (typeof sectionText !== 'string' || sectionText.trim() === '') {
|
||||
return { ok: false, reason: 'empty or non-string input' };
|
||||
}
|
||||
|
||||
const lines = sectionText.split(/\r?\n/);
|
||||
|
||||
let headerIdx = -1;
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const trimmed = lines[i].trim();
|
||||
if (trimmed.startsWith('|') && trimmed.indexOf('|', 1) !== -1) {
|
||||
headerIdx = i;
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (headerIdx === -1) {
|
||||
return { ok: false, reason: 'no table found' };
|
||||
}
|
||||
|
||||
const columns = splitTableRow(lines[headerIdx]);
|
||||
|
||||
const delimiterLine = lines[headerIdx + 1];
|
||||
if (delimiterLine === undefined || !delimiterLine.trim().startsWith('|')) {
|
||||
return { ok: false, reason: 'missing delimiter row' };
|
||||
}
|
||||
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' };
|
||||
}
|
||||
|
||||
const rows: Record<string, string>[] = [];
|
||||
let rowNum = 0;
|
||||
for (let i = headerIdx + 2; i < lines.length; i++) {
|
||||
const trimmed = lines[i].trim();
|
||||
if (!trimmed.startsWith('|')) break;
|
||||
|
||||
rowNum += 1;
|
||||
const cells = splitTableRow(lines[i]);
|
||||
if (cells.length !== columns.length) {
|
||||
return {
|
||||
ok: false,
|
||||
reason: `row ${rowNum} has ${cells.length} cells, expected ${columns.length}`,
|
||||
};
|
||||
}
|
||||
|
||||
const row: Record<string, string> = {};
|
||||
columns.forEach((col, idx) => {
|
||||
row[col] = cells[idx];
|
||||
});
|
||||
rows.push(row);
|
||||
}
|
||||
|
||||
return { ok: true, value: { columns, rows } };
|
||||
}
|
||||
|
||||
/**
|
||||
* Find the first table in `text` whose header matches `TABLE_SCHEMAS[schemaId]`,
|
||||
* scanning the WHOLE document (not just a named section). Returns `null` when
|
||||
* no table with that schema is found.
|
||||
*
|
||||
* Fixes the regression where callers first located a named heading (e.g.
|
||||
* `## Progress`) via `collectSection` and only then parsed a table inside it —
|
||||
* a schema-matching table that lives under a differently-named heading (or no
|
||||
* heading at all), or that isn't the first table in the document, was
|
||||
* invisible to that approach. Scanning the whole document by schema restores
|
||||
* the old "find the progress table anywhere" behaviour while staying
|
||||
* seam-based (ADR-2143).
|
||||
*/
|
||||
export function findTableBySchema(text: string, schemaId: string): MarkdownTable | null {
|
||||
if (typeof text !== 'string') return null;
|
||||
const lines = text.split(/\r?\n/);
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const t = lines[i].trim();
|
||||
if (!t.startsWith('|') || t.indexOf('|', 1) === -1) continue;
|
||||
const cols = splitTableRow(lines[i]);
|
||||
const m = matchTableSchema(cols);
|
||||
if (m && m.id === schemaId) {
|
||||
const parsed = parseMarkdownTable(lines.slice(i).join('\n'));
|
||||
if (parsed.ok) return parsed.value;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Find the first GFM table in `text` whose header contains ALL of `required`
|
||||
* column names (order-independent; extra/injected columns allowed). Returns
|
||||
* the parsed `MarkdownTable`, or `null` when no table's header is a superset
|
||||
* of `required`.
|
||||
*
|
||||
* Column-NAME/order/count-invariant counterpart to `findTableBySchema` (ADR-2143
|
||||
* §3 "addressed by NAME, never ordinal"): where `findTableBySchema` requires an
|
||||
* EXACT canonical column set+order registered in `TABLE_SCHEMAS`, this scans
|
||||
* for any header that names the required columns, in any order, tolerating
|
||||
* extra/unrelated injected columns. Cells remain addressable by column NAME
|
||||
* via the returned `MarkdownTable`.
|
||||
*/
|
||||
export function findTableWithColumns(text: string, required: string[]): MarkdownTable | null {
|
||||
if (typeof text !== 'string') return null;
|
||||
const lines = text.split(/\r?\n/);
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const t = lines[i].trim();
|
||||
if (!t.startsWith('|') || t.indexOf('|', 1) === -1) continue;
|
||||
const cols = splitTableRow(lines[i]);
|
||||
if (required.every((rq) => cols.includes(rq))) {
|
||||
const parsed = parseMarkdownTable(lines.slice(i).join('\n'));
|
||||
if (parsed.ok) return parsed.value;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
// ─── Quick Tasks row append (#2133) ────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Escape one dynamic cell value for insertion into a GFM pipe-table row.
|
||||
*
|
||||
* Escapes `\` -> `\\` FIRST, then `|` -> `\|` (in that order, so a literal
|
||||
* backslash already in the value is never mistaken for part of an escape
|
||||
* sequence introduced by this function — CodeQL js/incomplete-sanitization).
|
||||
* `splitTableRow` reverses both in the opposite order (`\\` -> `\` then
|
||||
* `\|` -> `|`, see line ~114 above), so escaping/unescaping round-trips
|
||||
* exactly, including literal backslashes. Newlines are collapsed to a
|
||||
* single space — a raw `|` or embedded newline in a cell value (e.g. a task
|
||||
* `description`) would otherwise corrupt the table (extra column / a fake
|
||||
* extra row) and get rejected by the now-fail-loud `parseMarkdownTable` as a
|
||||
* ragged row.
|
||||
*/
|
||||
function escapeCell(value: string): string {
|
||||
return String(value)
|
||||
.replace(/\r?\n+/g, ' ')
|
||||
.replace(/\\/g, '\\\\') // escape the escape char FIRST (CodeQL js/incomplete-sanitization)
|
||||
.replace(/\|/g, '\\|')
|
||||
.trim();
|
||||
}
|
||||
|
||||
/** Fields needed to render one "Quick Tasks Completed" row (schema-driven). */
|
||||
export interface QuickTaskFields {
|
||||
description: string;
|
||||
date: string;
|
||||
commit: string;
|
||||
status?: string;
|
||||
directory?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Append one row to STATE.md's "Quick Tasks Completed" table.
|
||||
*
|
||||
* Pure, schema-driven replacement for fast.md's inline `awk NF-2` column-count
|
||||
* guess (#2133, ADR-2143 §3 schema registry / §7 fail-loud unrecognized-schema
|
||||
* guard). Never touches disk, git, or the clock — callers (the `gsd-tools
|
||||
* quick-tasks-append` subcommand) compute `date`/`commit` and pass them in.
|
||||
*
|
||||
* Fails loud (`{ok:false, reason}`, never a silent skip) when:
|
||||
* - no "Quick Tasks Completed" heading exists in `stateContent`
|
||||
* - the section's body doesn't parse as a GFM table (parseMarkdownTable failure)
|
||||
* - the table's header doesn't match a known `TABLE_SCHEMAS.QuickTasks` variant
|
||||
* (the old awk arithmetic silently skipped here instead — that silent-skip
|
||||
* branch is the bug this replaces).
|
||||
*
|
||||
* The new row is inserted immediately after the LAST existing table row line
|
||||
* (or immediately after the header/delimiter when the table has zero data
|
||||
* rows), preserving any surrounding blank lines/trailing content in the section.
|
||||
*/
|
||||
export function appendQuickTaskRow(
|
||||
stateContent: string,
|
||||
fields: QuickTaskFields,
|
||||
): Result<{ content: string; row: string; variant: string }> {
|
||||
const section = collectSection(stateContent, (h) => /^quick tasks completed$/i.test(h.text.trim()));
|
||||
if (!section) {
|
||||
return { ok: false, reason: 'no Quick Tasks Completed section' };
|
||||
}
|
||||
|
||||
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') {
|
||||
return {
|
||||
ok: false,
|
||||
reason: `unrecognized Quick Tasks schema (columns: ${parsed.value.columns.join(' | ')})`,
|
||||
};
|
||||
}
|
||||
|
||||
const variant = TABLE_SCHEMAS.QuickTasks.find((v) => v.label === match.label);
|
||||
const columns = variant ? variant.columns : parsed.value.columns;
|
||||
|
||||
const rowNumber = parsed.value.rows.length + 1;
|
||||
const cellFor = (col: string): string => {
|
||||
switch (col) {
|
||||
case '#': return escapeCell(String(rowNumber));
|
||||
case 'Description': return escapeCell(fields.description);
|
||||
case 'Date': return escapeCell(fields.date);
|
||||
case 'Commit': return escapeCell(fields.commit);
|
||||
case 'Status': return escapeCell(fields.status ?? '—');
|
||||
case 'Directory': return escapeCell(fields.directory ?? '—');
|
||||
default: return '—';
|
||||
}
|
||||
};
|
||||
const row = `| ${columns.map(cellFor).join(' | ')} |`;
|
||||
|
||||
// Detect the section's EOL BEFORE splitting on /\r?\n/ (which discards it) so
|
||||
// the rejoin below preserves CRLF instead of downgrading a CRLF section to
|
||||
// mixed EOL (the inserted `row` itself never contains a newline).
|
||||
const eol = /\r\n/.test(section.body) ? '\r\n' : '\n';
|
||||
const lines = section.body.split(/\r?\n/);
|
||||
let lastTableLineIdx = -1;
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
if (lines[i].trim().startsWith('|')) lastTableLineIdx = i;
|
||||
}
|
||||
// lastTableLineIdx is always >= 0 here — parseMarkdownTable already
|
||||
// confirmed a header + delimiter row exist in this same `section.body`.
|
||||
const newLines = [
|
||||
...lines.slice(0, lastTableLineIdx + 1),
|
||||
row,
|
||||
...lines.slice(lastTableLineIdx + 1),
|
||||
];
|
||||
const newBody = newLines.join(eol);
|
||||
|
||||
const content = replaceSection(stateContent, section, newBody);
|
||||
|
||||
return { ok: true, value: { content, row, 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).
|
||||
@@ -20,6 +20,8 @@
|
||||
* - Issue #4 (open-gsd/gsd-core)
|
||||
*/
|
||||
|
||||
import { findTableWithColumns } from './markdown-table.cjs';
|
||||
|
||||
/** Result of deriveProgressFromRoadmap. */
|
||||
export interface RoadmapProgress {
|
||||
completedPhases: number | null;
|
||||
@@ -30,6 +32,30 @@ export interface RoadmapProgress {
|
||||
/**
|
||||
* Derive completed_phases, total_phases, and total_plans from ROADMAP content.
|
||||
* Root cause fix for issue #4 — see gen-phase-lifecycle.mjs for full documentation.
|
||||
*
|
||||
* ADR-2143 §3 ("addressed by NAME, never ordinal"): the Progress table is
|
||||
* located via the markdown-table seam's `findTableWithColumns`, which is
|
||||
* column-NAME/order/count-invariant — it matches the first table whose header
|
||||
* is a SUPERSET of the canonical `Phase` / `Plans Complete` / `Status` /
|
||||
* `Completed` names, in any order, tolerating extra/injected unrelated
|
||||
* columns (#2137's fast-check property test shuffles headers and injects
|
||||
* columns and asserts the derived counts never change). This supersedes the
|
||||
* earlier `findTableBySchema` exact-schema lookup, which required an exact
|
||||
* canonical column SET+ORDER and returned all-null on any reordering or
|
||||
* injection.
|
||||
*
|
||||
* Scoped to the `## Progress` section when the document has one (#2012 decoy
|
||||
* avoidance — a differently-headed table sharing the same column names must
|
||||
* not be picked up instead); a headingless milestone slice (#1445) falls back
|
||||
* to scanning the whole input, preserving the "Progress table not under a
|
||||
* `## Progress` heading, or not the first table in the document, still
|
||||
* resolves" behaviour.
|
||||
*
|
||||
* Cells are read by column NAME (`r['Status']`, `r['Plans Complete']`,
|
||||
* `r['Phase']`), fixing #2137 (the old position-based regex assumed "Status"
|
||||
* was always the 3rd cell and "Plans Complete" the 2nd, which broke for the
|
||||
* 5-column milestone-grouped variant that inserts a `Milestone` column ahead
|
||||
* of them).
|
||||
*/
|
||||
export function deriveProgressFromRoadmap(roadmapContent: string): RoadmapProgress {
|
||||
let completedPhases: number | null = null;
|
||||
@@ -37,97 +63,40 @@ export function deriveProgressFromRoadmap(roadmapContent: string): RoadmapProgre
|
||||
let totalPlans: number | null = null;
|
||||
|
||||
try {
|
||||
// Parse the Progress table by HEADER, not by a fixed column count. The
|
||||
// writer (cmdPhaseComplete) already branches on `cells.length === 5`, so it
|
||||
// understands both the 4-column greenfield table
|
||||
// | Phase | Plans Complete | Status | Completed |
|
||||
// and the 5-column milestone-grouped table the same template ships
|
||||
// | Phase | Milestone | Plans Complete | Status | Completed |
|
||||
// The reader used two 4-column-only regexes, so every project past its v1.0
|
||||
// milestone (5-column shape) parsed to all-null and phase.complete silently
|
||||
// skipped the STATE progress write. Reading column indices by NAME keeps the
|
||||
// reader and writer in agreement across both shapes and any future column
|
||||
// (#2137). The table is located by its header row rather than a `## Progress`
|
||||
// heading because some callers pass a milestone slice with no heading (#1445).
|
||||
//
|
||||
// When a `## Progress` heading IS present, scope the search to that section
|
||||
// (mirroring the writer's #2012 scoping in cmdPhaseComplete) so the reader
|
||||
// cannot bind to an earlier Phase/Status/Completed-shaped table elsewhere in
|
||||
// the roadmap. Callers that pass a headingless milestone slice fall back to
|
||||
// scanning the whole input.
|
||||
// Line-anchored h2 match — `indexOf('## Progress')` would also match inside
|
||||
// an h3 `### Progress` (the `## Progress` substring starts at the 2nd hash),
|
||||
// letting a decoy subheading hijack the slice.
|
||||
// Case-insensitive to match the case-insensitive header-cell comparison below.
|
||||
//
|
||||
// allow-adhoc-markdown: line-based Progress-table scan (header lookup +
|
||||
// positional cell indexing); table parsing is out of the markdown-sectionizer
|
||||
// seam's scope. Superseded by the ADR-2143 parseMarkdownTable/TABLE_SCHEMAS
|
||||
// seam; pending #2143.
|
||||
// ADR-2143 §3: read the Progress table by column NAME (order/injection-invariant),
|
||||
// via the markdown-table seam. Scope to the `## Progress` section when present
|
||||
// (#2012 decoy avoidance); a headingless milestone slice (#1445) falls back to the
|
||||
// whole input. Requires the canonical Phase/Plans Complete/Status/Completed columns
|
||||
// in any order (extra columns ignored) — supersedes findTableBySchema's exact-schema lookup.
|
||||
const progressMatch = roadmapContent.match(/^##[ \t]+Progress\b/im);
|
||||
let scoped = roadmapContent;
|
||||
if (progressMatch && progressMatch.index !== undefined) {
|
||||
// Slice from `## Progress` to the next h1/h2 heading (or end); h3+ headings
|
||||
// inside the section do not terminate it. The heading sits at index 0 of
|
||||
// this slice with no leading newline, so the `\n#` search cannot match it.
|
||||
const afterHeading = roadmapContent.slice(progressMatch.index);
|
||||
const nextHeading = afterHeading.search(/\n#{1,2}[ \t]/);
|
||||
scoped = nextHeading >= 0 ? afterHeading.slice(0, nextHeading) : afterHeading;
|
||||
}
|
||||
const lines = scoped.split('\n');
|
||||
const table = findTableWithColumns(scoped, ['Phase', 'Plans Complete', 'Status', 'Completed']);
|
||||
|
||||
// Split a markdown table row into trimmed cells — the same
|
||||
// `split('|').slice(1, -1)` boundary the writer uses (phase.cts).
|
||||
const rowCells = (line: string): string[] =>
|
||||
line.split('|').slice(1, -1).map((c) => c.trim());
|
||||
const isTableRow = (line: string): boolean => line.trim().startsWith('|');
|
||||
const isSeparatorRow = (cells: string[]): boolean =>
|
||||
cells.length > 0 && cells.every((c) => /^:?-+:?$/.test(c));
|
||||
if (table) {
|
||||
const allRows = table.rows;
|
||||
|
||||
let headerLine = -1;
|
||||
let phaseIdx = -1;
|
||||
let statusIdx = -1;
|
||||
let plansIdx = -1;
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
if (!isTableRow(lines[i])) continue;
|
||||
const lc = rowCells(lines[i]).map((c) => c.toLowerCase());
|
||||
const p = lc.indexOf('phase');
|
||||
const s = lc.indexOf('status');
|
||||
const c = lc.indexOf('completed');
|
||||
if (p >= 0 && s >= 0 && c >= 0) {
|
||||
headerLine = i;
|
||||
phaseIdx = p;
|
||||
statusIdx = s;
|
||||
plansIdx = lc.findIndex((h) => h.includes('plans'));
|
||||
break;
|
||||
const completed = allRows.filter((r) => /^complete$/i.test((r['Status'] ?? '').trim())).length;
|
||||
completedPhases = completed > 0 ? completed : null;
|
||||
|
||||
// Data rows only (exclude 999.x backlog phases). Mirrors init.cts /^999(?:\.|$)/ filter.
|
||||
const dataRows = allRows.filter((r) => {
|
||||
const phase = (r['Phase'] ?? '').trim();
|
||||
return /^\d/.test(phase) && !/^999\b/.test(phase);
|
||||
});
|
||||
totalPhases = dataRows.length > 0 ? dataRows.length : null;
|
||||
|
||||
let totalPlansSum = 0;
|
||||
for (const r of allRows) {
|
||||
const cell = (r['Plans Complete'] ?? '').trim();
|
||||
const m = /(\d+)\s*\/\s*(\d+)/.exec(cell);
|
||||
if (m) totalPlansSum += parseInt(m[2], 10);
|
||||
}
|
||||
}
|
||||
|
||||
if (headerLine >= 0) {
|
||||
let phaseCount = 0;
|
||||
let completedCount = 0;
|
||||
let plansSum = 0;
|
||||
// Walk the contiguous rows after the header; a markdown table ends at the
|
||||
// first non-`|` line.
|
||||
for (let i = headerLine + 1; i < lines.length; i++) {
|
||||
if (!isTableRow(lines[i])) break;
|
||||
const cells = rowCells(lines[i]);
|
||||
if (isSeparatorRow(cells)) continue;
|
||||
const phaseToken = (cells[phaseIdx] ?? '').trim();
|
||||
if (!/^\d/.test(phaseToken)) continue; // not a data row
|
||||
if (/^999\b/.test(phaseToken)) continue; // 999.x backlog sentinel (#1445)
|
||||
phaseCount++;
|
||||
if ((cells[statusIdx] ?? '').toLowerCase() === 'complete') completedCount++;
|
||||
if (plansIdx >= 0) {
|
||||
const mn = (cells[plansIdx] ?? '').match(/^(\d+)\/(\d+)$/);
|
||||
if (mn) plansSum += parseInt(mn[2], 10);
|
||||
}
|
||||
}
|
||||
// Preserve the prior contract: a count of 0 is reported as null (absent),
|
||||
// so the consumer leaves the existing STATE value untouched.
|
||||
completedPhases = completedCount > 0 ? completedCount : null;
|
||||
totalPhases = phaseCount > 0 ? phaseCount : null;
|
||||
totalPlans = plansSum > 0 ? plansSum : null;
|
||||
totalPlans = totalPlansSum > 0 ? totalPlansSum : null;
|
||||
}
|
||||
} catch { /* intentionally empty — fall through to existing values */ }
|
||||
|
||||
|
||||
Reference in New Issue
Block a user