@gtrabanco/agentic-workflow 4.10.0 → 5.0.0-canary.20261104.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +30 -6
- package/bin/agentic-workflow.mjs +62 -7
- package/package.json +1 -1
- package/src/edit/Roadmap.mjs +13 -8
- package/src/edit/UnitDoc.mjs +2 -2
- package/src/index-document.mjs +304 -0
package/README.md
CHANGED
|
@@ -15,12 +15,36 @@ as subcommands of it.
|
|
|
15
15
|
throwaway producer output. It is committed as a directory (`.gitkeep`) so the
|
|
16
16
|
convention exists on a fresh clone.
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
18
|
+
The crate is the lane's **runner**: every deterministic file service, sensor and
|
|
19
|
+
guard the workflow needs ships as a subcommand here, so a skill or a target
|
|
20
|
+
project invokes one pinned CLI instead of a tree of loose scripts.
|
|
21
|
+
|
|
22
|
+
## Commands
|
|
23
|
+
|
|
24
|
+
```text
|
|
25
|
+
usage: agentic-workflow <unit-doc|roadmap|changelog|budgets|manifest|doc|memory> ...
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Every operation prints one fixed receipt block (with `--json` the same receipt
|
|
29
|
+
as JSON). A refused operation exits **2** with `EDIT REFUSAL — <reason>` **before
|
|
30
|
+
writing anything**.
|
|
31
|
+
|
|
32
|
+
| Command | What it does |
|
|
33
|
+
|---|---|
|
|
34
|
+
| `unit-doc <NN-slug> <op>` | Typed unit-document service: `create`, `setSection`, `evidence`, `progress`, `validate` — schema-checked, unknown sections refused |
|
|
35
|
+
| `roadmap <op>` | Roadmap writer: `rowUpsert` and `annotate` take a table path, and `roadmap check <unit-doc> [--roadmap <f>] [--index <f>] [--json]` returns named violation codes (0 clean · 1 violations · 2 usage) |
|
|
36
|
+
| `changelog [file] <json>` | Appends a changelog row through the writer (defaults to `./CHANGELOG.md`) |
|
|
37
|
+
| `budgets [file] <json>` | Re-bases one context-budget ceiling with its growth source; a ceiling shrinkage without a growth source is refused |
|
|
38
|
+
| `manifest [plugin.json] <op>` | `skillAdd` / `skillRemove` on the plugin manifest — the alphabetical machine-surface registration |
|
|
39
|
+
| `doc (--sync \| --query <term> \| --status \| --rebuild) [--json-only]` | The **retrieval index** (feature 65): one gitignored SQLite store under `.agentic-workflow/index/`, freshness checked on every query, `--query` answering over FTS5 keyword search and — when `AGENTIC_WORKFLOW_DOC_EMBEDDINGS_BASE_URL` / `_MODEL` / `_API_KEY` are set — a hybrid pass over stored vectors. Degradations are declared, never silent: `unavailable-embeddings-not-configured`, `unavailable-embeddings-not-indexed`, `embeddings-model-mismatch`, `unavailable-embeddings-provider-down`. Discovery only: no gate reads it. Positional doc ops (`read`/`edit`/`index`) ship with unit 71 and are refused by name until then |
|
|
40
|
+
| `memory probe [--json]` | The five-check memory-substrate health sensor (below) — writes nothing, always exits 0 |
|
|
41
|
+
|
|
42
|
+
Two sibling binaries ship in the same package and are invoked by the skills:
|
|
43
|
+
|
|
44
|
+
| Binary | What it does |
|
|
45
|
+
|---|---|
|
|
46
|
+
| `bin/path-guard.mjs` | Tier 1 path-protection gate (feature 60): `path-guard --unit <unit-dir> --phase <P<n>> [--base <ref>]`, read-only and offline, printing `PATH-GUARD <pass\|fail> — <code>` · exit 0 pass, 1 fail, 2 usage |
|
|
47
|
+
| `bin/turn-contract.mjs` | Verifies the canonical turn contract's mechanical boxes: prints `TURN-CONTRACT ok` or `TURN-CONTRACT fail box<N>: <code>`; `--finished` also requires the pushed branch with its open pull request |
|
|
24
48
|
|
|
25
49
|
## `memory probe` — bounded memory-substrate health (feature 66)
|
|
26
50
|
|
package/bin/agentic-workflow.mjs
CHANGED
|
@@ -27,6 +27,14 @@ import { join, resolve, basename, dirname } from "node:path";
|
|
|
27
27
|
// Import SDK modules
|
|
28
28
|
import { create, setSection, evidence_addRow, progress_logEntry, validate } from "../src/edit/UnitDoc.mjs";
|
|
29
29
|
import { rowUpsert, annotate as roadmapAnnotate, checkUnitDoc, ROADMAP_CHECK_CODES } from "../src/edit/Roadmap.mjs";
|
|
30
|
+
import {
|
|
31
|
+
FIX_INDEX_DOCUMENT,
|
|
32
|
+
ROADMAP_DOCUMENT,
|
|
33
|
+
ROADMAP_FIXES_HEADING,
|
|
34
|
+
RoadmapMovedError,
|
|
35
|
+
resolveRoadmapSource,
|
|
36
|
+
roadmapSection,
|
|
37
|
+
} from "../src/index-document.mjs";
|
|
30
38
|
import { rowAdd } from "../src/edit/Changelog.mjs";
|
|
31
39
|
import { ceilingRebase } from "../src/edit/Budgets.mjs";
|
|
32
40
|
import { skillAdd, skillRemove } from "../src/edit/Manifest.mjs";
|
|
@@ -69,9 +77,31 @@ function refuse(reason) {
|
|
|
69
77
|
}
|
|
70
78
|
|
|
71
79
|
/**
|
|
72
|
-
* Walk up from a unit doc to the repo root until the default index
|
|
73
|
-
*
|
|
80
|
+
* Walk up from a unit doc to the repo root until the default index exists; null
|
|
81
|
+
* when no ancestor carries it.
|
|
74
82
|
*/
|
|
83
|
+
/** Strip the docs root from a published index path (`docs/X/Y.md` → `X/Y.md`). */
|
|
84
|
+
function relativeToDocs(index) {
|
|
85
|
+
return index.replace(/^docs\//, "");
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* The index this tree carries, resolved by the shared reader so the documented
|
|
90
|
+
* rollback lever applies here exactly as it does everywhere else: the reader
|
|
91
|
+
* decides which path is readable, and a tree that carries only the pre-move
|
|
92
|
+
* path while the window is closed is refused with its pointer at the new home.
|
|
93
|
+
* Returns `{ direct, index }`: the path a caller passed explicitly (never
|
|
94
|
+
* resolved through the tree) and the walked-up index path.
|
|
95
|
+
*
|
|
96
|
+
* @param {string} docPath — the unit doc the walk starts from
|
|
97
|
+
* @param {string|undefined} direct — `--roadmap`/`--index`, already read
|
|
98
|
+
*/
|
|
99
|
+
function resolveIndex(docPath, direct) {
|
|
100
|
+
if (direct !== undefined) return { direct: resolve(direct), index: null };
|
|
101
|
+
const source = resolveRoadmapSource({ exists: (relative) => findUpIndex(docPath, relative) !== null });
|
|
102
|
+
return { direct: null, index: source === null ? null : findUpIndex(docPath, source.path) };
|
|
103
|
+
}
|
|
104
|
+
|
|
75
105
|
function findUpIndex(docPath, relativeIndex) {
|
|
76
106
|
let dir = dirname(docPath);
|
|
77
107
|
for (;;) {
|
|
@@ -278,18 +308,43 @@ switch (command) {
|
|
|
278
308
|
// contradiction).
|
|
279
309
|
const parts = docPath.split("/");
|
|
280
310
|
const isFix = parts.includes("docs") && parts[parts.indexOf("docs") + 1] === "fix";
|
|
281
|
-
|
|
311
|
+
// One index (issue #319): a feature row and a fix row are two tables of
|
|
312
|
+
// the same document, so both kinds default to it and `checkUnitDoc`
|
|
313
|
+
// reads its own table there. A pre-319 tree still has the pre-move
|
|
314
|
+
// roadmap and the standalone fix index under the alias.
|
|
282
315
|
const indexArg = flag("--roadmap") ?? flag("--index");
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
316
|
+
// The index is resolved through the shared reader, so the documented
|
|
317
|
+
// rollback lever (`ROADMAP_LEGACY_READ`) governs this consumer too: with
|
|
318
|
+
// the window closed a pre-move-only tree is refused with the pointer at
|
|
319
|
+
// its new home, and with the lever on the same tree reads as before.
|
|
320
|
+
const resolved = resolveIndex(docPath, indexArg);
|
|
321
|
+
const indexPath = resolved.direct ?? resolved.index;
|
|
286
322
|
if (!indexPath) {
|
|
287
323
|
refuse(`index not found for ${docArg} — pass --roadmap <file>`);
|
|
288
324
|
}
|
|
289
325
|
const dirName = basename(dirname(docPath));
|
|
290
326
|
const nn = /^(\d+)/.exec(dirName)?.[1] ?? "";
|
|
291
327
|
const slug = dirName.replace(/^\d+-/, "");
|
|
292
|
-
|
|
328
|
+
// A half-migrated tree (issue #319): the consolidated index exists but
|
|
329
|
+
// carries no `## Fixes` table, so the active fix rows are still in the
|
|
330
|
+
// standalone fix index. `MIGRATION.md` and `init-workspace`'s upgrade
|
|
331
|
+
// reference promise that state is readable, so a fix doc falls back to
|
|
332
|
+
// it exactly as the sensor, router, settle validator and ceremony CLI
|
|
333
|
+
// do — never a feature row read as a fix row, never a vacuous pass.
|
|
334
|
+
const indexText = readFileSync(indexPath, "utf8");
|
|
335
|
+
const fixIndexText = isFix && !indexArg && roadmapSection(indexText, ROADMAP_FIXES_HEADING) === null
|
|
336
|
+
? (() => {
|
|
337
|
+
const standalone = findUpIndex(docPath, relativeToDocs(FIX_INDEX_DOCUMENT));
|
|
338
|
+
return standalone === null ? null : readFileSync(standalone, "utf8");
|
|
339
|
+
})()
|
|
340
|
+
: null;
|
|
341
|
+
const result = checkUnitDoc({
|
|
342
|
+
nn,
|
|
343
|
+
slug,
|
|
344
|
+
kind: isFix ? "fix" : "feature",
|
|
345
|
+
docText,
|
|
346
|
+
indexText: fixIndexText ?? indexText,
|
|
347
|
+
});
|
|
293
348
|
if (parsed.json) {
|
|
294
349
|
console.log(
|
|
295
350
|
JSON.stringify(
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gtrabanco/agentic-workflow",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "5.0.0-canary.20261104.1",
|
|
4
4
|
"description": "Deterministic runner for the agentic-workflow lane: file services (agwo edit), sensors, guards and receipts. One pinned pure-JS dependency, no native deps, no build step.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>",
|
package/src/edit/Roadmap.mjs
CHANGED
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
|
|
10
10
|
import { readFileSync, writeFileSync } from "node:fs";
|
|
11
11
|
import { createHash } from "node:crypto";
|
|
12
|
+
import { roadmapTableRows } from "../index-document.mjs";
|
|
12
13
|
|
|
13
14
|
/**
|
|
14
15
|
* The separator rule matches the table that exists in this repository
|
|
@@ -149,15 +150,19 @@ function rowNumber(cell) {
|
|
|
149
150
|
return m ? m[1] ?? m[2] : null;
|
|
150
151
|
}
|
|
151
152
|
|
|
152
|
-
|
|
153
|
+
/**
|
|
154
|
+
* The index rows of one kind, keyed by unit number. Scoped through
|
|
155
|
+
* `roadmapTableRows` so a consolidated document (issue #319) never answers a
|
|
156
|
+
* fix check with a feature row of the same number, while a pre-319 document or
|
|
157
|
+
* a caller-supplied fragment keeps its single-table meaning.
|
|
158
|
+
*/
|
|
159
|
+
function parseIndexRows(indexText, kind) {
|
|
153
160
|
const rows = new Map();
|
|
154
|
-
for (const
|
|
155
|
-
if (
|
|
156
|
-
const
|
|
157
|
-
if (cells.length < 4) continue;
|
|
158
|
-
const nn = rowNumber(cells[1] ?? "");
|
|
161
|
+
for (const cells of roadmapTableRows(indexText, kind === "fix" ? "fix" : "feature")) {
|
|
162
|
+
if (cells.length < 3) continue;
|
|
163
|
+
const nn = rowNumber(cells[0] ?? "");
|
|
159
164
|
if (!nn) continue;
|
|
160
|
-
rows.set(nn, { status: cells[
|
|
165
|
+
rows.set(nn, { status: cells[2] ?? "", slug: (cells[1] ?? "").replace(/`/g, "") });
|
|
161
166
|
}
|
|
162
167
|
return rows;
|
|
163
168
|
}
|
|
@@ -206,7 +211,7 @@ function ownPrUrls(docText) {
|
|
|
206
211
|
*/
|
|
207
212
|
export function checkUnitDoc({ nn, slug, kind, docText, indexText }) {
|
|
208
213
|
const violations = [];
|
|
209
|
-
const row = parseIndexRows(indexText).get(String(nn));
|
|
214
|
+
const row = parseIndexRows(indexText, kind).get(String(nn));
|
|
210
215
|
if (!row) {
|
|
211
216
|
if (kind !== "fix") {
|
|
212
217
|
violations.push({ code: "row-missing", line: 1, detail: `no roadmap row for NN ${nn}` });
|
package/src/edit/UnitDoc.mjs
CHANGED
|
@@ -197,8 +197,8 @@ OPEN rows only: a row a review persisted as fix-now work and no fold has closed.
|
|
|
197
197
|
A folded row leaves this table and becomes a \`## Log\` line. Rows are appended by
|
|
198
198
|
\`review-change\` and \`triage-issue\`.
|
|
199
199
|
|
|
200
|
-
| id | S# / file:line | axis | severity | class | route |
|
|
201
|
-
|
|
200
|
+
| id | S# / file:line | axis | severity | impact | class | route |
|
|
201
|
+
|---|---|---|---|---|---|---|
|
|
202
202
|
|
|
203
203
|
## Log
|
|
204
204
|
|
|
@@ -0,0 +1,304 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The location indexes — one document, two tables (issue #319).
|
|
3
|
+
*
|
|
4
|
+
* `docs/ROADMAP.md` is the single index: `## Features` orders feature units,
|
|
5
|
+
* `## Fixes` carries the active fixes that used to live in `docs/fix/README.md`.
|
|
6
|
+
* The path is published here so a consumer never hardcodes it again — the
|
|
7
|
+
* 15-file recurrence the move was made to end.
|
|
8
|
+
*
|
|
9
|
+
* The same constants are mirrored by `@gtrabanco/agentic-workflow-schema`
|
|
10
|
+
* (`src/paths.ts`), the package the orchestration layer imports; the mirror is
|
|
11
|
+
* held in step by `scripts/index-document.test.mjs`, which reads both sources.
|
|
12
|
+
* The pre-move path is spelled exactly once in the tree, in this file: the
|
|
13
|
+
* alias below.
|
|
14
|
+
*
|
|
15
|
+
* The migration window is CLOSED (owner decision D4, 2026-10-30; it supersedes
|
|
16
|
+
* unit 319's D2): every reader resolves {@link ROADMAP_DOCUMENT} only. A
|
|
17
|
+
* repository that still carries the pre-move path is refused with a
|
|
18
|
+
* `roadmap-moved` pointer at its new home — never a silent empty parse, and
|
|
19
|
+
* never an empty index. `ROADMAP_LEGACY_READ` stays as the documented
|
|
20
|
+
* rollback lever: flipping it back to `true` re-opens the alias for an
|
|
21
|
+
* emergency, it is not a normal operating mode.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
import fs from "node:fs";
|
|
25
|
+
import path from "node:path";
|
|
26
|
+
|
|
27
|
+
/** The consolidated index. */
|
|
28
|
+
export const ROADMAP_DOCUMENT = "docs/ROADMAP.md";
|
|
29
|
+
/** The pre-move path: detected only, so the refusal can name it. Never read. */
|
|
30
|
+
export const ROADMAP_LEGACY_DOCUMENT = "docs/features/ROADMAP.md";
|
|
31
|
+
/** The fix index file. Before unit 319 it was the index itself; now it is a stub. */
|
|
32
|
+
export const FIX_INDEX_DOCUMENT = "docs/fix/README.md";
|
|
33
|
+
/** The features table's heading in the consolidated index. */
|
|
34
|
+
export const ROADMAP_FEATURES_HEADING = "Features";
|
|
35
|
+
/** The fixes table's heading in the consolidated index. */
|
|
36
|
+
export const ROADMAP_FIXES_HEADING = "Fixes";
|
|
37
|
+
/**
|
|
38
|
+
* D4: the read alias is closed. Kept as an explicit, tested rollback lever:
|
|
39
|
+
* `true` re-opens the pre-move path for an emergency, and every consumer reads
|
|
40
|
+
* it through this one value.
|
|
41
|
+
*
|
|
42
|
+
* An operator rolling back cannot edit an installed package, so
|
|
43
|
+
* `AGENTIC_WORKFLOW_ROADMAP_LEGACY_READ=1` re-opens it at run time — the same
|
|
44
|
+
* value, one channel wider. It never re-opens by accident: only the exact `1`.
|
|
45
|
+
*/
|
|
46
|
+
export const ROADMAP_LEGACY_READ = process.env.AGENTIC_WORKFLOW_ROADMAP_LEGACY_READ === "1";
|
|
47
|
+
/** The closed code a closed window refuses the pre-move path with. */
|
|
48
|
+
export const ROADMAP_MOVED_CODE = "roadmap-moved";
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* The pre-move path was read after the window closed. The error names the file
|
|
52
|
+
* that moved and where it moved to, so a consumer reconciles instead of parsing
|
|
53
|
+
* an empty document.
|
|
54
|
+
*/
|
|
55
|
+
export class RoadmapMovedError extends Error {
|
|
56
|
+
constructor(from = ROADMAP_LEGACY_DOCUMENT, to = ROADMAP_DOCUMENT) {
|
|
57
|
+
super(`${ROADMAP_MOVED_CODE}: ${from} has moved to ${to} — read ${to}`);
|
|
58
|
+
this.name = "RoadmapMovedError";
|
|
59
|
+
this.code = ROADMAP_MOVED_CODE;
|
|
60
|
+
this.from = from;
|
|
61
|
+
this.to = to;
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Which index a repository carries, without reading it: `{ path, source }`
|
|
67
|
+
* where `source` is `"canonical"`, or `"legacy"` only while the rollback lever
|
|
68
|
+
* is on; `null` when neither exists. A repository that carries only the
|
|
69
|
+
* pre-move path and no rollback is refused here, before any read.
|
|
70
|
+
*
|
|
71
|
+
* `exists` is the caller's own existence check, so a consumer that confines
|
|
72
|
+
* reads to its project root (the sensor) keeps its confinement instead of
|
|
73
|
+
* bypassing it with a second filesystem call.
|
|
74
|
+
*
|
|
75
|
+
* @param {object} options
|
|
76
|
+
* @param {(relative: string) => boolean} options.exists
|
|
77
|
+
* @param {boolean} [options.legacy] — defaults to the window flag.
|
|
78
|
+
* @returns {{path: string, source: "canonical"|"legacy"} | null}
|
|
79
|
+
*/
|
|
80
|
+
export function resolveRoadmapSource({ exists, legacy = ROADMAP_LEGACY_READ }) {
|
|
81
|
+
if (exists(ROADMAP_DOCUMENT)) return { path: ROADMAP_DOCUMENT, source: "canonical" };
|
|
82
|
+
if (!exists(ROADMAP_LEGACY_DOCUMENT)) return null;
|
|
83
|
+
if (!legacy) throw new RoadmapMovedError();
|
|
84
|
+
return { path: ROADMAP_LEGACY_DOCUMENT, source: "legacy" };
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Read the index a repository carries: `{ path, source, text }` or `null`.
|
|
89
|
+
* Throws `RoadmapMovedError` when only the pre-move path exists and the window
|
|
90
|
+
* is closed.
|
|
91
|
+
*
|
|
92
|
+
* @param {string} rootDir
|
|
93
|
+
* @param {{legacy?: boolean}} [options]
|
|
94
|
+
*/
|
|
95
|
+
export function readRoadmapIndex(rootDir, { legacy = ROADMAP_LEGACY_READ } = {}) {
|
|
96
|
+
const exists = (relative) => {
|
|
97
|
+
try {
|
|
98
|
+
return fs.lstatSync(path.join(rootDir, relative)).isFile();
|
|
99
|
+
} catch {
|
|
100
|
+
return false;
|
|
101
|
+
}
|
|
102
|
+
};
|
|
103
|
+
const source = resolveRoadmapSource({ exists, legacy });
|
|
104
|
+
if (source === null) return null;
|
|
105
|
+
return { ...source, text: fs.readFileSync(path.join(rootDir, source.path), "utf8") };
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* A fence-looking line: up to three spaces, then three-or-more backticks or
|
|
110
|
+
* tildes. `marker` is the character that opened the run, `length` how long it is.
|
|
111
|
+
* (CommonMark's shape, which the schema package's `advanceFence` shares.)
|
|
112
|
+
*/
|
|
113
|
+
const FENCE_LINE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Advance the fence state over one line, returning the block still open after it
|
|
117
|
+
* — the one grammar for every reader of the index.
|
|
118
|
+
*
|
|
119
|
+
* A block closes only on a run of the character that OPENED it, at least as long,
|
|
120
|
+
* with nothing but spaces after it. A block that is not open ignores input
|
|
121
|
+
* indented four columns or more: that is an indented code block, not a fence.
|
|
122
|
+
* Every consumer decides through this one function, so the heading scan and the
|
|
123
|
+
* row scan can never track differently — a fenced example row is document text,
|
|
124
|
+
* never a live row of a table.
|
|
125
|
+
*
|
|
126
|
+
* @param {string} line
|
|
127
|
+
* @param {{marker: string, length: number} | null} open
|
|
128
|
+
* @returns {{marker: string, length: number} | null}
|
|
129
|
+
*/
|
|
130
|
+
export function fenceRun(line, open) {
|
|
131
|
+
const run = FENCE_LINE.exec(line);
|
|
132
|
+
if (run === null) {
|
|
133
|
+
if (open === null && /^ {4,}/.test(line) && line.trimStart().startsWith("|")) return open;
|
|
134
|
+
return open;
|
|
135
|
+
}
|
|
136
|
+
const marker = run[1][0];
|
|
137
|
+
const length = run[1].length;
|
|
138
|
+
if (open === null) {
|
|
139
|
+
if (/^ {4,}/.test(line)) return null;
|
|
140
|
+
return { marker, length };
|
|
141
|
+
}
|
|
142
|
+
return marker === open.marker && length >= open.length && run[2].trim() === "" ? null : open;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* Whether a line is a live table row: a table row that no open fence owns. Rows
|
|
147
|
+
* indented four columns or more are an indented code block's lines, not rows.
|
|
148
|
+
*
|
|
149
|
+
* @param {string} line
|
|
150
|
+
* @param {{marker: string, length: number} | null} open — the block open before this line
|
|
151
|
+
* @returns {boolean}
|
|
152
|
+
*/
|
|
153
|
+
export function isLiveTableRow(line, open) {
|
|
154
|
+
if (open !== null) return false;
|
|
155
|
+
if (/^ {4,}/.test(line)) return false;
|
|
156
|
+
return line.trimStart().startsWith("|");
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* The body of one `## <heading>` section, or `null` when the document has no
|
|
161
|
+
* such heading. Fenced code blocks are respected: a `##` line inside a fence is
|
|
162
|
+
* document text, not a heading.
|
|
163
|
+
*
|
|
164
|
+
* @param {string} text
|
|
165
|
+
* @param {string} heading
|
|
166
|
+
* @returns {string | null}
|
|
167
|
+
*/
|
|
168
|
+
export function roadmapSection(text, heading) {
|
|
169
|
+
if (typeof text !== "string") return null;
|
|
170
|
+
const wanted = heading.trim().toLowerCase();
|
|
171
|
+
const out = [];
|
|
172
|
+
let fence = null;
|
|
173
|
+
let level = 0;
|
|
174
|
+
for (const line of text.split("\n")) {
|
|
175
|
+
fence = fenceRun(line, fence);
|
|
176
|
+
const match = fence === null ? /^(#{1,6})\s+(.*)$/.exec(line) : null;
|
|
177
|
+
if (match) {
|
|
178
|
+
if (level !== 0 && match[1].length <= level) break; // the section ended
|
|
179
|
+
if (level === 0 && match[2].trim().toLowerCase() === wanted) {
|
|
180
|
+
level = match[1].length;
|
|
181
|
+
continue;
|
|
182
|
+
}
|
|
183
|
+
if (level === 0) continue;
|
|
184
|
+
}
|
|
185
|
+
if (level !== 0) out.push(line);
|
|
186
|
+
}
|
|
187
|
+
return level === 0 ? null : out.join("\n");
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* The cells of one Markdown table row, splitting only on unescaped pipes and
|
|
192
|
+
* dropping only the boundary cells the pipes actually delimit — the same
|
|
193
|
+
* contract the schema package's mirror holds, so a row reads identically on
|
|
194
|
+
* both published sides whether or not it carries a trailing pipe (issue #319,
|
|
195
|
+
* F15).
|
|
196
|
+
*/
|
|
197
|
+
export function tableCells(line) {
|
|
198
|
+
const cells = [];
|
|
199
|
+
let current = "";
|
|
200
|
+
for (let index = 0; index < line.length; index += 1) {
|
|
201
|
+
const char = line[index];
|
|
202
|
+
if (char === "\\" && line[index + 1] === "|") {
|
|
203
|
+
current += "|";
|
|
204
|
+
index += 1;
|
|
205
|
+
} else if (char === "|") {
|
|
206
|
+
cells.push(current.trim());
|
|
207
|
+
current = "";
|
|
208
|
+
} else {
|
|
209
|
+
current += char;
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
cells.push(current.trim());
|
|
213
|
+
if (cells.length < 2) return [];
|
|
214
|
+
const body = cells[0] === "" ? cells.slice(1) : cells;
|
|
215
|
+
return body[body.length - 1] === "" ? body.slice(0, -1) : body;
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
const isSeparatorRow = (cells) => cells.length > 0 && cells.every((cell) => /^[-:\s]*$/.test(cell));
|
|
219
|
+
|
|
220
|
+
/**
|
|
221
|
+
* Whether a document declares its tables by heading — the consolidated index,
|
|
222
|
+
* and any document that has begun migrating to it. A pre-319 roadmap puts one
|
|
223
|
+
* table straight under its title and is not one.
|
|
224
|
+
*
|
|
225
|
+
* @param {string} text
|
|
226
|
+
* @returns {boolean}
|
|
227
|
+
*/
|
|
228
|
+
function declaresTablesByHeading(text) {
|
|
229
|
+
return roadmapSection(text, ROADMAP_FEATURES_HEADING) !== null || roadmapSection(text, ROADMAP_FIXES_HEADING) !== null;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* The data rows of the table that belongs to `kind` — `"feature"` reads
|
|
234
|
+
* `## Features`, `"fix"` reads `## Fixes`.
|
|
235
|
+
*
|
|
236
|
+
* Scoping is what keeps the two tables apart: in a consolidated document a
|
|
237
|
+
* feature row numbered `N` and a fix row for issue `N` are different rows, and a
|
|
238
|
+
* parser handed the whole file must never mix them. A document without the
|
|
239
|
+
* heading (a pre-319 roadmap, a standalone fix index, a caller-supplied
|
|
240
|
+
* fragment) keeps its single-table meaning: every row is the caller's kind.
|
|
241
|
+
*
|
|
242
|
+
* A document that declares its tables by heading is the exception: when its
|
|
243
|
+
* `## Fixes` heading is absent, the fix table is empty rather than inherited
|
|
244
|
+
* from `## Features`. Reading the features table as fixes there is the
|
|
245
|
+
* half-migrated defect (issue #319, F1) — feature row `N` would answer for fix
|
|
246
|
+
* row `N` and report a slug mismatch against another kind.
|
|
247
|
+
*
|
|
248
|
+
* The inverse is not symmetric: a pre-319 roadmap keeps its features table under
|
|
249
|
+
* its title, so a feature read that finds no `## Features` heading but does find
|
|
250
|
+
* `## Fixes` is a half-migrated roadmap, never an empty feature table.
|
|
251
|
+
*
|
|
252
|
+
* Only live rows are returned: a fenced code block (a writer's example of the
|
|
253
|
+
* row format) and an indented code block are content, never data — the same
|
|
254
|
+
* `fenceRun` grammar the heading scan uses, so no reader can track differently.
|
|
255
|
+
*
|
|
256
|
+
* @param {string} text
|
|
257
|
+
* @param {"feature"|"fix"} kind
|
|
258
|
+
* @returns {string[][]}
|
|
259
|
+
*/
|
|
260
|
+
export function roadmapTableRows(text, kind) {
|
|
261
|
+
if (typeof text !== "string") return [];
|
|
262
|
+
const heading = kind === "fix" ? ROADMAP_FIXES_HEADING : ROADMAP_FEATURES_HEADING;
|
|
263
|
+
const section = roadmapSection(text, heading);
|
|
264
|
+
const emptyFixTable = section === null && kind === "fix" && declaresTablesByHeading(text);
|
|
265
|
+
const body = emptyFixTable ? "" : (section ?? text);
|
|
266
|
+
const rows = [];
|
|
267
|
+
let fence = null;
|
|
268
|
+
for (const line of body.split("\n")) {
|
|
269
|
+
if (isLiveTableRow(line, fence)) {
|
|
270
|
+
const cells = tableCells(line);
|
|
271
|
+
if (cells.length > 0 && !isSeparatorRow(cells)) rows.push(cells);
|
|
272
|
+
}
|
|
273
|
+
fence = fenceRun(line, fence);
|
|
274
|
+
}
|
|
275
|
+
return rows;
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/**
|
|
279
|
+
* The fix index's rows for this repository: the `## Fixes` table of the
|
|
280
|
+
* consolidated index when it has one, else the standalone `docs/fix/README.md`
|
|
281
|
+
* of a pre-319 tree. `{ path, text }` or `null`.
|
|
282
|
+
*
|
|
283
|
+
* @param {string} rootDir
|
|
284
|
+
* @param {{legacy?: boolean}} [options]
|
|
285
|
+
*/
|
|
286
|
+
export function readFixIndexTable(rootDir, { legacy = ROADMAP_LEGACY_READ } = {}) {
|
|
287
|
+
const index = readRoadmapIndex(rootDir, { legacy });
|
|
288
|
+
if (index !== null) {
|
|
289
|
+
const section = roadmapSection(index.text, ROADMAP_FIXES_HEADING);
|
|
290
|
+
if (section !== null) return { path: index.path, text: section };
|
|
291
|
+
}
|
|
292
|
+
const standalone = path.join(rootDir, FIX_INDEX_DOCUMENT);
|
|
293
|
+
try {
|
|
294
|
+
if (!fs.lstatSync(standalone).isFile()) return null;
|
|
295
|
+
return { path: FIX_INDEX_DOCUMENT, text: fs.readFileSync(standalone, "utf8") };
|
|
296
|
+
} catch {
|
|
297
|
+
return null;
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
/** Whether a caller-supplied document path is the consolidated index. */
|
|
302
|
+
export function isRoadmapDocument(documentPath) {
|
|
303
|
+
return typeof documentPath === "string" && (documentPath === ROADMAP_DOCUMENT || documentPath.endsWith(`/${ROADMAP_DOCUMENT}`));
|
|
304
|
+
}
|