gcf-aif-ext 0.32.0 → 0.36.0
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 +45 -6
- package/commands/gcf.js +344 -82
- package/extension.json +1 -1
- package/injections/plan-context.md +3 -0
- package/lib/agent-permissions.js +28 -4
- package/lib/audit-core.js +72 -127
- package/lib/board.js +22 -10
- package/lib/changes.js +7 -1
- package/lib/commit-files.js +1 -0
- package/lib/commit-move.js +56 -10
- package/lib/config-set.js +52 -14
- package/lib/context.js +29 -16
- package/lib/d2-states.js +208 -0
- package/lib/design-parts.js +37 -7
- package/lib/domain.js +144 -11
- package/lib/gcf-paths.js +13 -2
- package/lib/git.js +62 -17
- package/lib/inbox-categories.js +3 -0
- package/lib/inbox.js +69 -4
- package/lib/lessons.js +133 -4
- package/lib/main-lock.js +195 -3
- package/lib/plan-check.js +339 -37
- package/lib/play.js +21 -20
- package/lib/review.js +111 -2
- package/lib/rules.js +428 -0
- package/lib/session-mark.js +2 -1
- package/lib/systems-doc.js +60 -13
- package/lib/validate-item.js +9 -0
- package/lib/work-ops.js +109 -50
- package/package.json +1 -1
- package/profiles/plan.md +1 -1
- package/schemas/item.schema.json +4 -0
- package/skills/gcf-audit/SKILL.md +10 -5
- package/skills/gcf-card/SKILL.md +12 -10
- package/skills/gcf-chat/SKILL.md +14 -10
- package/skills/gcf-triage/SKILL.md +19 -1
- package/skills/gcf-verdict/SKILL.md +7 -5
- package/templates/agents-block.md +23 -2
- package/templates/config.yml +10 -6
package/lib/main-lock.js
CHANGED
|
@@ -4,13 +4,28 @@
|
|
|
4
4
|
// holds it across the merge and the move it records.
|
|
5
5
|
import { AsyncLocalStorage } from 'node:async_hooks';
|
|
6
6
|
import { link, mkdir, readFile, stat, unlink, writeFile } from 'node:fs/promises';
|
|
7
|
-
import {
|
|
7
|
+
import {
|
|
8
|
+
existsSync,
|
|
9
|
+
mkdirSync,
|
|
10
|
+
readdirSync,
|
|
11
|
+
readFileSync,
|
|
12
|
+
renameSync,
|
|
13
|
+
rmSync,
|
|
14
|
+
writeFileSync,
|
|
15
|
+
} from 'node:fs';
|
|
8
16
|
import { randomUUID } from 'node:crypto';
|
|
9
17
|
import path from 'node:path';
|
|
18
|
+
// Not `process.stdin.isTTY`: reading it opens stdin, which may keep a piped command alive.
|
|
19
|
+
import { isatty } from 'node:tty';
|
|
20
|
+
import { dirtyGcf, moveBy } from './git.js';
|
|
21
|
+
import { refusal } from './refusal.js';
|
|
10
22
|
|
|
11
23
|
const chain = new AsyncLocalStorage();
|
|
12
24
|
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
13
25
|
|
|
26
|
+
/** How often a move waiting behind a main run looks at gcf/, and how long a claim yields to one. */
|
|
27
|
+
export const waitTiming = { pollMs: 1000, yieldMs: 5000 };
|
|
28
|
+
|
|
14
29
|
export const lockFile = (projectDir) =>
|
|
15
30
|
path.join(path.resolve(projectDir), '.gcf-session', 'main.lock');
|
|
16
31
|
|
|
@@ -179,10 +194,187 @@ async function clearStale(file, text) {
|
|
|
179
194
|
* @returns {Promise<T>}
|
|
180
195
|
*/
|
|
181
196
|
export async function withMainLock(projectDir, fn, { waitMs = 60000 } = {}) {
|
|
182
|
-
const file = lockFile(projectDir);
|
|
183
197
|
const held = chain.getStore() ?? new Set();
|
|
184
|
-
if (held.has(
|
|
198
|
+
if (held.has(lockFile(projectDir))) return fn();
|
|
199
|
+
const once = () => holding(projectDir, held, fn, waitMs);
|
|
200
|
+
if (!mayWait()) return once();
|
|
201
|
+
|
|
202
|
+
// The operator's move stopped by a main run's gcf/ edits waits for them, without the lock (the
|
|
203
|
+
// run's own moves need it), then goes again from its first read (docs/Main-Run-Moves-Plan.md).
|
|
204
|
+
const wait = waiter(projectDir);
|
|
205
|
+
try {
|
|
206
|
+
for (;;) {
|
|
207
|
+
try {
|
|
208
|
+
return await once();
|
|
209
|
+
} catch (e) {
|
|
210
|
+
await wait(e);
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
} finally {
|
|
214
|
+
wait.end();
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* Only the operator waits, from a terminal or a board that knows its move (`GCF_MOVE_TAG`): a
|
|
220
|
+
* session's or a script's command is killed by its caller's timeout, maybe mid-commit.
|
|
221
|
+
*/
|
|
222
|
+
const mayWait = () => moveBy() === 'operator' && (isatty(0) || Boolean(process.env.GCF_MOVE_TAG));
|
|
223
|
+
|
|
224
|
+
const TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* The card a live main run works now; null with none, or when the lock holds the token of a
|
|
228
|
+
* build, a push or a play: their edits are no run's that a commit of it would clear.
|
|
229
|
+
*/
|
|
230
|
+
function mainRunCard(projectDir) {
|
|
231
|
+
try {
|
|
232
|
+
const file = path.join(path.resolve(projectDir), '.gcf-session', 'runs', `${MAIN_RUN}.lock`);
|
|
233
|
+
const [pid, item] = readFileSync(file, 'utf8')
|
|
234
|
+
.split('\n')
|
|
235
|
+
.map((s) => s.trim());
|
|
236
|
+
const n = Number(pid);
|
|
237
|
+
|
|
238
|
+
return item && !TOKEN.test(item) && n > 0 && n !== process.pid && alive(n) ? item : null;
|
|
239
|
+
} catch {
|
|
240
|
+
return null;
|
|
241
|
+
}
|
|
242
|
+
}
|
|
185
243
|
|
|
244
|
+
const waitingDir = (projectDir) => path.join(path.resolve(projectDir), '.gcf-session', 'waiting');
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* The records of moves waiting behind a main run (`.gcf-session/waiting/<pid>.json`), each with
|
|
248
|
+
* its `pid` and `file`. A record whose process died is left over: it is removed, not listed.
|
|
249
|
+
* @returns {Array<{pid: number, file: string, message?: string, items?: string[],
|
|
250
|
+
* tag?: string | null, behind?: string, paths?: string[], cancel?: string, going?: boolean}>}
|
|
251
|
+
*/
|
|
252
|
+
export function liveWaiting(projectDir) {
|
|
253
|
+
const dir = waitingDir(projectDir);
|
|
254
|
+
let names;
|
|
255
|
+
try {
|
|
256
|
+
names = readdirSync(dir);
|
|
257
|
+
} catch {
|
|
258
|
+
return [];
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
return names.flatMap((name) => {
|
|
262
|
+
const pid = Number(/^(\d+)\.json$/.exec(name)?.[1]);
|
|
263
|
+
if (!pid) return [];
|
|
264
|
+
const file = path.join(dir, name);
|
|
265
|
+
if (!alive(pid)) {
|
|
266
|
+
rmSync(file, { force: true });
|
|
267
|
+
|
|
268
|
+
return [];
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
try {
|
|
272
|
+
return [{ ...JSON.parse(readFileSync(file, 'utf8')), pid, file }];
|
|
273
|
+
} catch {
|
|
274
|
+
return [];
|
|
275
|
+
}
|
|
276
|
+
});
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* The wait of one move: `wait(e)` rethrows a failure that is no main run's `dirty` refusal;
|
|
281
|
+
* else it keeps its record, tells once, and resolves when the refusal's paths are clean. It
|
|
282
|
+
* rethrows the refusal when the run is gone, and refuses on a cancel file. Its record says
|
|
283
|
+
* `going` once the paths cleared and the move goes again. `wait.end()` removes the record and
|
|
284
|
+
* the cancel file, on every way out of the move.
|
|
285
|
+
*/
|
|
286
|
+
function waiter(projectDir) {
|
|
287
|
+
const dir = waitingDir(projectDir);
|
|
288
|
+
const record = path.join(dir, `${process.pid}.json`);
|
|
289
|
+
const cancel = process.env.GCF_MOVE_CANCEL || path.join(dir, `${process.pid}.cancel`);
|
|
290
|
+
let told = false;
|
|
291
|
+
|
|
292
|
+
/** @param {any} e */
|
|
293
|
+
const wait = async (e) => {
|
|
294
|
+
const card = e?.refusal?.code === 'dirty' ? mainRunCard(projectDir) : null;
|
|
295
|
+
if (!card) throw e;
|
|
296
|
+
const { paths } = e.refusal;
|
|
297
|
+
const { message = 'the move', items = [] } = e.move ?? {};
|
|
298
|
+
const tag = process.env.GCF_MOVE_TAG || null;
|
|
299
|
+
const keep = (going = false) => {
|
|
300
|
+
// Whole or not at all: a reader never parses half a record.
|
|
301
|
+
writeFileSync(
|
|
302
|
+
`${record}.tmp`,
|
|
303
|
+
JSON.stringify({ message, items, tag, behind: card, paths, cancel, going }),
|
|
304
|
+
);
|
|
305
|
+
renameSync(`${record}.tmp`, record);
|
|
306
|
+
};
|
|
307
|
+
|
|
308
|
+
mkdirSync(dir, { recursive: true });
|
|
309
|
+
if (!told) {
|
|
310
|
+
// A cancel a dead move of this pid left behind is no cancel of this one.
|
|
311
|
+
rmSync(cancel, { force: true });
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
keep();
|
|
315
|
+
if (!told) {
|
|
316
|
+
told = true;
|
|
317
|
+
process.stderr.write(
|
|
318
|
+
`${message} waits: the run of ${card} holds gcf/ edits (${paths.join(', ')}); it goes ` +
|
|
319
|
+
'when they are committed. Nothing is written while it waits.\n' +
|
|
320
|
+
`gcf-waiting: ${JSON.stringify({ behind: card, paths })}\n`,
|
|
321
|
+
);
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
if (!(await cleared(card, paths, message))) throw e;
|
|
325
|
+
// It goes again: a Cancel from now on comes too late (the board answers "already recorded").
|
|
326
|
+
keep(true);
|
|
327
|
+
};
|
|
328
|
+
|
|
329
|
+
/** True once `paths` are clean, false when the run is gone with them still dirty. */
|
|
330
|
+
const cleared = async (card, paths, message) => {
|
|
331
|
+
// shortcut: one `git status` a second per waiting move, cheap for a few; watch gcf/ when
|
|
332
|
+
// many moves wait at once.
|
|
333
|
+
for (;;) {
|
|
334
|
+
await sleep(waitTiming.pollMs);
|
|
335
|
+
if (existsSync(cancel)) {
|
|
336
|
+
rmSync(cancel, { force: true });
|
|
337
|
+
throw refusal(
|
|
338
|
+
'cancelled',
|
|
339
|
+
{},
|
|
340
|
+
`${message}: cancelled while it waited behind the run of ${card} — nothing was recorded`,
|
|
341
|
+
);
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
const dirty = new Set(dirtyGcf(projectDir));
|
|
345
|
+
if (!paths.some((p) => dirty.has(p))) return true;
|
|
346
|
+
// Gone with its edits left: they are no run's now, and today's refusal names them.
|
|
347
|
+
if (!mainRunCard(projectDir)) return false;
|
|
348
|
+
}
|
|
349
|
+
};
|
|
350
|
+
|
|
351
|
+
// A cancel that came as it went is no cancel of a later move under the same pid.
|
|
352
|
+
wait.end = () => {
|
|
353
|
+
rmSync(record, { force: true });
|
|
354
|
+
rmSync(cancel, { force: true });
|
|
355
|
+
};
|
|
356
|
+
|
|
357
|
+
return wait;
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
/**
|
|
361
|
+
* A card's claim lets a waiting move go first (docs/Main-Run-Moves-Plan.md d4): after a run's
|
|
362
|
+
* last commit gcf/ is clean, and a claim would soil it again before the move's next look. Only
|
|
363
|
+
* when every waiting move's paths are clean already, and for `waitTiming.yieldMs` at most.
|
|
364
|
+
*/
|
|
365
|
+
export async function yieldToWaiting(projectDir) {
|
|
366
|
+
const waits = liveWaiting(projectDir);
|
|
367
|
+
if (!waits.length) return;
|
|
368
|
+
const dirty = new Set(dirtyGcf(projectDir));
|
|
369
|
+
if (waits.some((w) => (w.paths ?? []).some((p) => dirty.has(p)))) return;
|
|
370
|
+
const until = Date.now() + waitTiming.yieldMs;
|
|
371
|
+
while (Date.now() < until && waits.some((w) => existsSync(w.file) && alive(w.pid)))
|
|
372
|
+
await sleep(100);
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
/** Take the main lock, run `fn` under it, let it go. */
|
|
376
|
+
async function holding(projectDir, held, fn, waitMs) {
|
|
377
|
+
const file = lockFile(projectDir);
|
|
186
378
|
await mkdir(path.dirname(file), { recursive: true });
|
|
187
379
|
const token = randomUUID();
|
|
188
380
|
const until = Date.now() + waitMs;
|
package/lib/plan-check.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
// `gcf plan check <id>` (Methodology §5.2.1): the deterministic check after each
|
|
1
|
+
// `gcf plan check <id>` (Methodology §5.2.1): the deterministic check after each review pass —
|
|
2
2
|
// the plan exists, it holds task checkboxes, and the item's readset fits the context budget.
|
|
3
|
-
// Whether the plan is any good is the
|
|
3
|
+
// Whether the plan is any good is the review passes' job; this only says it is usable. Its
|
|
4
4
|
// form against the `plan` profile (CNL-P: blocks, one idea a line, no fact twice) is reported
|
|
5
5
|
// as `format` lines, never a problem: a long line must not cost the item its paid passes.
|
|
6
6
|
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
|
|
@@ -21,20 +21,67 @@ const PASS_LINE = new RegExp(
|
|
|
21
21
|
`^- pass (\\d+)(?: \\(cycle (\\d+)\\))?: blocking (\\d+), polish (\\d+)` +
|
|
22
22
|
`(?:, by (${WHO})(?:, for (${WHO}))?)?$`,
|
|
23
23
|
);
|
|
24
|
-
const SECTION = { plan: /^## Passes\s*$/, code: /^## Reviews\s*$/ };
|
|
25
|
-
const HEADING = { plan: '## Passes', code: '## Reviews' };
|
|
24
|
+
const SECTION = { plan: /^## Passes\s*$/, code: /^## Reviews\s*$/, findings: /^## Findings\s*$/ };
|
|
25
|
+
const HEADING = { plan: '## Passes', code: '## Reviews', findings: '## Findings' };
|
|
26
|
+
|
|
27
|
+
// A plan review's finding with the author's verdict (Plan-Review-Rework-Plan d2), one line each in
|
|
28
|
+
// `## Findings`: `- [c<C>.]p<K>.<N> <severity> <verdict> <where>: <summary>[; <reason>]`; the
|
|
29
|
+
// cycle's tag only past cycle 0. The summary holds no `; `: the reason begins at the first one.
|
|
30
|
+
const FINDING_LINE = new RegExp(
|
|
31
|
+
'^- (?:c(\\d+)\\.)?p(\\d+)\\.(\\d+) (blocking|polish) (accepted|rejected|downgraded) ' +
|
|
32
|
+
'(\\S+): (.*?)(?:; (.*))?$',
|
|
33
|
+
);
|
|
34
|
+
const SEVERITIES = ['blocking', 'polish'];
|
|
35
|
+
const VERDICTS = ['accepted', 'rejected', 'downgraded'];
|
|
26
36
|
const PASSES_ANY = /^## Passes\s*$/m;
|
|
27
37
|
|
|
28
38
|
/** The review kinds: the plan's passes, the code's before its commit. */
|
|
29
39
|
export const KINDS = ['plan', 'code'];
|
|
30
40
|
|
|
41
|
+
// A fence hides the `## ` lines in it, as the board's folds read a plan (planFile.ts fenceAfter).
|
|
42
|
+
const FENCE = /^\s*(`{3,}|~{3,})(.*)$/;
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* The fence open after `line` (CommonMark): 3 or more backticks or tildes open one, a backtick
|
|
46
|
+
* fence's info has no backtick; only a line of the same character, as long or longer and nothing
|
|
47
|
+
* after, closes it. Null outside a fence.
|
|
48
|
+
* @param {string | null} fence
|
|
49
|
+
* @param {string} line
|
|
50
|
+
*/
|
|
51
|
+
function fenceAfter(fence, line) {
|
|
52
|
+
const m = FENCE.exec(line);
|
|
53
|
+
if (!fence) return m && !(m[1][0] === '`' && m[2].includes('`')) ? m[1] : null;
|
|
54
|
+
const closes = m && m[1][0] === fence[0] && m[1].length >= fence.length && !m[2].trim();
|
|
55
|
+
|
|
56
|
+
return closes ? null : fence;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Each line of `text` with the index of the `## ` heading it falls under (-1 before any), a
|
|
61
|
+
* heading inside a fence no heading.
|
|
62
|
+
*/
|
|
63
|
+
function sectioned(text) {
|
|
64
|
+
let fence = /** @type {string | null} */ (null);
|
|
65
|
+
let at = -1;
|
|
66
|
+
|
|
67
|
+
return text.split(/\r?\n/).map((line, n) => {
|
|
68
|
+
const was = fence;
|
|
69
|
+
fence = fenceAfter(fence, line);
|
|
70
|
+
if (!was && !fence && /^## /.test(line)) at = n;
|
|
71
|
+
|
|
72
|
+
return { line, at };
|
|
73
|
+
});
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** Whether a line of `sectioned` lies in a section `re` heads. */
|
|
77
|
+
const under = (all, x, re) => x.at >= 0 && re.test(all[x.at].line);
|
|
78
|
+
|
|
31
79
|
/** The passes a plan's section of `kind` records, of every cycle, in order. */
|
|
32
80
|
export function planPasses(text, kind = 'plan') {
|
|
33
81
|
const out = [];
|
|
34
|
-
|
|
35
|
-
for (const
|
|
36
|
-
|
|
37
|
-
const m = inside ? PASS_LINE.exec(line.trim()) : null;
|
|
82
|
+
const all = sectioned(text);
|
|
83
|
+
for (const x of all) {
|
|
84
|
+
const m = under(all, x, SECTION[kind]) ? PASS_LINE.exec(x.line.trim()) : null;
|
|
38
85
|
if (!m) continue;
|
|
39
86
|
const by = m[5] ? { by: m[5], ...(m[6] ? { for: m[6] } : {}) } : {};
|
|
40
87
|
out.push({ pass: +m[1], cycle: +(m[2] ?? 0), blocking: +m[3], polish: +m[4], ...by });
|
|
@@ -43,10 +90,62 @@ export function planPasses(text, kind = 'plan') {
|
|
|
43
90
|
return out;
|
|
44
91
|
}
|
|
45
92
|
|
|
93
|
+
/** The findings `## Findings` records (d2), of every cycle, in order; a line of no form skipped. */
|
|
94
|
+
export function planFindings(text) {
|
|
95
|
+
const out = [];
|
|
96
|
+
const all = sectioned(text);
|
|
97
|
+
for (const x of all) {
|
|
98
|
+
const m = under(all, x, SECTION.findings) ? FINDING_LINE.exec(x.line.trim()) : null;
|
|
99
|
+
if (!m) continue;
|
|
100
|
+
const [, c, k, n, severity, verdict, where, summary, reason] = m;
|
|
101
|
+
out.push({
|
|
102
|
+
...{ tag: x.line.trim().split(' ')[1], cycle: +(c ?? 0), pass: +k, n: +n },
|
|
103
|
+
...{ severity, verdict, where, summary, reason: reason ?? null },
|
|
104
|
+
});
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
return out;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Where the plan review keeps what each pass saw (Plan-Review-Rework-Plan d3), in
|
|
112
|
+
* `.gcf-session/plans/`: the plan of the last pass asked and the record of that pass
|
|
113
|
+
* `{cycle, pass, mode, diff?}`; `next`, the new snapshot till its record is written.
|
|
114
|
+
*/
|
|
115
|
+
export function snapshotFiles(projectDir, id) {
|
|
116
|
+
const home = path.join(path.resolve(projectDir), '.gcf-session', 'plans');
|
|
117
|
+
|
|
118
|
+
return {
|
|
119
|
+
...{ home, snap: path.join(home, `${id}.md`), mark: path.join(home, `${id}.json`) },
|
|
120
|
+
next: path.join(home, `${id}.next.md`),
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* The record of the last plan pass asked of a reviewer; null with none or none to read.
|
|
126
|
+
* @returns {{cycle?: number, pass?: number, mode?: string, diff?: object} | null}
|
|
127
|
+
*/
|
|
128
|
+
export function reviewMark(projectDir, id) {
|
|
129
|
+
try {
|
|
130
|
+
return JSON.parse(readFileSync(snapshotFiles(projectDir, id).mark, 'utf8'));
|
|
131
|
+
} catch {
|
|
132
|
+
return null; // No pass asked yet, or a record broken: none.
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** The findings of the plan of an item with frontmatter `data` (d2); none without a plan. */
|
|
137
|
+
export function itemFindings(projectDir, data) {
|
|
138
|
+
const file = path.resolve(projectDir, planTicks(projectDir, data).plan);
|
|
139
|
+
|
|
140
|
+
return existsSync(file) ? planFindings(readFileSync(file, 'utf8')) : [];
|
|
141
|
+
}
|
|
142
|
+
|
|
46
143
|
/**
|
|
47
144
|
* The verdict on one cycle's passes (t2 d3): `converged` when the last found nothing blocking
|
|
48
145
|
* (or no row reviews); `continue` while a row is left for the next pass (the operator's `more`
|
|
49
|
-
* adds them); `stalled` when the rows are over, then the operator decides.
|
|
146
|
+
* adds them); `stalled` when the rows are over, then the operator decides. A pass recorded from
|
|
147
|
+
* its findings (d8) counts its rejected and downgraded blocking ones too: such a pass is not the
|
|
148
|
+
* last, a check of the author's verdicts follows.
|
|
50
149
|
*/
|
|
51
150
|
export function passVerdict(passes, rows, more = 0) {
|
|
52
151
|
if (rows === 0) return 'converged';
|
|
@@ -98,6 +197,15 @@ async function passesOf(projectDir, data, { text, done, kind = 'plan' }) {
|
|
|
98
197
|
return { cycle, passes, verdict, rows };
|
|
99
198
|
}
|
|
100
199
|
|
|
200
|
+
/** Whether the plan review of the item with frontmatter `data` (its `id` in) is stalled now. */
|
|
201
|
+
export async function planStalled(projectDir, data) {
|
|
202
|
+
const { plan, done } = planTicks(projectDir, data);
|
|
203
|
+
const file = path.resolve(projectDir, plan);
|
|
204
|
+
const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
|
|
205
|
+
|
|
206
|
+
return (await passesOf(projectDir, data, { text, done })).verdict === 'stalled';
|
|
207
|
+
}
|
|
208
|
+
|
|
101
209
|
/**
|
|
102
210
|
* An item's plan and its task checkboxes: `{plan, tasks, done}`, `tasks` null when there is no
|
|
103
211
|
* plan file. `data` is the item's frontmatter.
|
|
@@ -139,21 +247,47 @@ export function profiledText(text, keys) {
|
|
|
139
247
|
|
|
140
248
|
/**
|
|
141
249
|
* The plan's form against the `plan` profile, as `<line>: <message>` lines; the project
|
|
142
|
-
* glossary's avoided words count.
|
|
143
|
-
* change its form. A plan in no block of the profile (aif-plan's own layout)
|
|
250
|
+
* glossary's avoided words count. Once a task is ticked only the size line (d7): work in flight
|
|
251
|
+
* is not asked to change its form. A plan in no block of the profile (aif-plan's own layout)
|
|
252
|
+
* gets one line.
|
|
144
253
|
*/
|
|
145
254
|
export async function planFormat(projectDir, text) {
|
|
146
|
-
|
|
255
|
+
// The size counts in work too (d7): the next plan learns from it; the form does not.
|
|
256
|
+
const size = sizeNote(text);
|
|
257
|
+
if (/^\s*- \[[xX]\] /m.test(text)) return size;
|
|
147
258
|
const profile = await loadDocProfile('plan');
|
|
148
259
|
const keys = profile.sections.map((s) => s.key);
|
|
149
260
|
if (!new RegExp(`^(${keys.join('|')}):`, 'm').test(text))
|
|
150
|
-
return [`the plan is not in the plan profile: blocks ${keys.join(', ')}`];
|
|
261
|
+
return [...size, `the plan is not in the plan profile: blocks ${keys.join(', ')}`];
|
|
151
262
|
const glossary = path.join(path.resolve(projectDir), GLOSSARY_NAME);
|
|
152
263
|
const avoid = existsSync(glossary) ? glossaryAvoids(readFileSync(glossary, 'utf8')) : [];
|
|
153
264
|
|
|
154
|
-
return
|
|
155
|
-
|
|
156
|
-
|
|
265
|
+
return [
|
|
266
|
+
...size,
|
|
267
|
+
...bodyIssues(profiledText(text, keys), profile, { avoid }).map(
|
|
268
|
+
(i) => `${i.line}: ${i.message}`,
|
|
269
|
+
),
|
|
270
|
+
];
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
// The plan's depth (Plan-Review-Rework-Plan d7): past these, details the implementer's tests own.
|
|
274
|
+
const PLAN_LINES = 150;
|
|
275
|
+
const PLAN_TASKS = 20;
|
|
276
|
+
// GCF's own sections of a plan: the review's record and the run's notes are not its size.
|
|
277
|
+
const NOT_SIZE = /^## (Passes|Findings|Play notes|Handoff)\s*$/;
|
|
278
|
+
|
|
279
|
+
/** One line when the plan's blocks are over ~150 lines or ~20 tasks (d7), else none. */
|
|
280
|
+
function sizeNote(text) {
|
|
281
|
+
const all = sectioned(text);
|
|
282
|
+
const lines = all.filter((x) => !under(all, x, NOT_SIZE) && x.line.trim()).map((x) => x.line);
|
|
283
|
+
const tasks = lines.filter((l) => /^\s*- \[[ xX]\] /.test(l)).length;
|
|
284
|
+
if (lines.length <= PLAN_LINES && tasks <= PLAN_TASKS) return [];
|
|
285
|
+
|
|
286
|
+
return [
|
|
287
|
+
`the plan is long: ${lines.length} lines, ${tasks} tasks (about ${PLAN_LINES} and ` +
|
|
288
|
+
`${PLAN_TASKS} at most): keep decisions and file-level tasks with what proves them; ` +
|
|
289
|
+
"fixtures, case lists and step-by-step code are the implementer's",
|
|
290
|
+
];
|
|
157
291
|
}
|
|
158
292
|
|
|
159
293
|
export async function planCheck(projectDir, id) {
|
|
@@ -176,6 +310,8 @@ export async function planCheck(projectDir, id) {
|
|
|
176
310
|
return {
|
|
177
311
|
...{ id, plan, tasks, done, problems, format, ok: problems.length === 0 },
|
|
178
312
|
...{ cycle, passes, converged: verdict === 'converged', stalled: verdict === 'stalled' },
|
|
313
|
+
// The plan review's findings with the author's verdicts, of every cycle (d2).
|
|
314
|
+
findings: planFindings(text),
|
|
179
315
|
// The code's review passes (t2 d3): the same verdict over `## Reviews`.
|
|
180
316
|
review: { passes: code.passes, verdict: code.verdict, rows: code.rows },
|
|
181
317
|
};
|
|
@@ -185,40 +321,205 @@ export async function planCheck(projectDir, id) {
|
|
|
185
321
|
* `gcf plan pass` (Hold-Plan d12, t2 d3): record pass K of the current cycle in the plan's
|
|
186
322
|
* section of `kind` (`## Passes`, the code's `## Reviews`), K the next number, and answer the
|
|
187
323
|
* verdict on the cycle's passes so far. `for`: the row the pass was asked of, written only when
|
|
188
|
-
* `by` is someone else (self or a stand-in, Fallback-Fidelity-Plan d2).
|
|
324
|
+
* `by` is someone else (self or a stand-in, Fallback-Fidelity-Plan d2). With `findings` (a JSON
|
|
325
|
+
* file, Plan-Review-Rework-Plan d2) the core writes them to `## Findings` and counts the pass
|
|
326
|
+
* line's numbers itself; without, the counts given are written as they are.
|
|
189
327
|
* @param {string} projectDir
|
|
190
328
|
* @param {string} id
|
|
191
|
-
* @param {{blocking
|
|
329
|
+
* @param {{blocking?: number, polish?: number, findings?: string, by?: string, for?: string,
|
|
330
|
+
* kind?: string}} pass
|
|
192
331
|
*/
|
|
193
332
|
export async function recordPass(projectDir, id, pass) {
|
|
194
|
-
const {
|
|
195
|
-
|
|
196
|
-
if (!KINDS.includes(kind)) throw new Error(`--kind is ${KINDS.join(' | ')}, got ${kind}`);
|
|
333
|
+
const { by, kind = 'plan' } = pass;
|
|
334
|
+
const form = passForm(projectDir, pass, kind);
|
|
197
335
|
const item = (await buildLedger(projectDir)).item(id);
|
|
198
336
|
if (!item) throw new Error(`${id} is not a work item of gcf/work/`);
|
|
199
337
|
const { plan } = planTicks(projectDir, { ...item.data, id });
|
|
200
338
|
const file = path.resolve(projectDir, plan);
|
|
201
339
|
if (!existsSync(file)) throw new Error(`no plan at ${plan}: write it first`);
|
|
202
|
-
|
|
340
|
+
let text = readFileSync(file, 'utf8');
|
|
203
341
|
const cycle = Number(item.data.plan_cycle ?? 0);
|
|
204
342
|
const k = planPasses(text, kind).filter((x) => x.cycle === cycle).length + 1;
|
|
343
|
+
const earlier = planFindings(text);
|
|
344
|
+
formFits(projectDir, id, { form, kind, cycle, k, earlier, by, row: pass.for });
|
|
345
|
+
// A raise reads this cycle's findings alone: an older cycle's ended (the operator's accept).
|
|
346
|
+
const mine = earlier.filter((f) => f.cycle === cycle);
|
|
347
|
+
const { list, counts } = findingsOf(form, pass, { cycle, k, earlier: mine });
|
|
348
|
+
const { blocking, polish } = counts;
|
|
349
|
+
passArgs(blocking, polish, by, pass.for);
|
|
205
350
|
const tag = cycle ? ` (cycle ${cycle})` : '';
|
|
206
351
|
const line = `- pass ${k}${tag}: blocking ${blocking}, polish ${polish}${whoOf(by, pass.for)}`;
|
|
207
|
-
|
|
352
|
+
text = withPass(text, line, kind);
|
|
353
|
+
for (const f of list ?? []) text = withPass(text, findingLine(f), 'findings');
|
|
354
|
+
readsBack(text, { plan, kind, cycle, k, findings: earlier.length + (list?.length ?? 0) });
|
|
355
|
+
writeFileSync(file, text);
|
|
208
356
|
const r = await planCheck(projectDir, id);
|
|
209
|
-
const now = kind === 'plan' ? { passes: r.passes, verdict:
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
357
|
+
const now = kind === 'plan' ? { passes: r.passes, verdict: planVerdict(r) } : r.review;
|
|
358
|
+
|
|
359
|
+
return {
|
|
360
|
+
...{ id, kind, pass: k, cycle, verdict: now.verdict },
|
|
361
|
+
passes: now.passes.map((x) => x.blocking),
|
|
362
|
+
...(list ? { findings: list } : {}),
|
|
363
|
+
};
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
/**
|
|
367
|
+
* Refuse a pass in a form that would close the review with no check (d3, d8): one from findings
|
|
368
|
+
* no reviewer was given (`review row` for pass `k` of `cycle` kept what it saw), or the old
|
|
369
|
+
* counts in a plan cycle that already records findings (an old harness never writes them), or
|
|
370
|
+
* a findings file labelled for another pass.
|
|
371
|
+
*/
|
|
372
|
+
function formFits(projectDir, id, { form, kind, cycle, k, earlier, by, row }) {
|
|
373
|
+
if (!form && kind === 'plan' && earlier.some((f) => f.cycle === cycle))
|
|
374
|
+
throw new Error(
|
|
375
|
+
`the plan review of this cycle records ## Findings: pass ${k} is --findings <file.json>, ` +
|
|
376
|
+
'not --blocking/--polish',
|
|
377
|
+
);
|
|
378
|
+
if (!form) return;
|
|
379
|
+
askedOf(projectDir, id, { cycle, k });
|
|
380
|
+
labelFits(form, { cycle, k, by, row });
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
/**
|
|
384
|
+
* Refuse a write whose pass (and findings) would not read back: a fence left open above
|
|
385
|
+
* `## Passes` hides the section, and the count would stay at this pass for ever.
|
|
386
|
+
*/
|
|
387
|
+
function readsBack(text, { plan, kind, cycle, k, findings }) {
|
|
388
|
+
const passes = planPasses(text, kind).filter((x) => x.cycle === cycle).length;
|
|
389
|
+
if (passes === k && planFindings(text).length === findings) return;
|
|
390
|
+
throw new Error(
|
|
391
|
+
`${plan}: pass ${k} would not read back from its section; is a \`\`\` or ~~~ fence left ` +
|
|
392
|
+
'open above it? Close it, then record the pass again',
|
|
393
|
+
);
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
/** Refuse a pass from findings no reviewer was given: `review row` kept nothing for it. */
|
|
397
|
+
function askedOf(projectDir, id, { cycle, k }) {
|
|
398
|
+
const asked = reviewMark(projectDir, id);
|
|
399
|
+
if (asked?.cycle === cycle && asked?.pass === k) return;
|
|
400
|
+
throw new Error(
|
|
401
|
+
`pass ${k}${cycle ? ` of cycle ${cycle}` : ''} was not asked of a reviewer: run ` +
|
|
402
|
+
`gcf review row ${id} --kind plan --pass ${k} first`,
|
|
403
|
+
);
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
const planVerdict = (r) => (r.converged ? 'converged' : r.stalled ? 'stalled' : 'continue');
|
|
407
|
+
|
|
408
|
+
/**
|
|
409
|
+
* Pass `k`'s findings as their lines will hold them, tagged `[c<C>.]p<k>.<n>`, and the pass
|
|
410
|
+
* line's counts derived from them (d2): every blocking one counts, whatever its verdict (d8).
|
|
411
|
+
* No findings (`form` null, the old form): the counts given.
|
|
412
|
+
*/
|
|
413
|
+
function findingsOf(form, given, { cycle, k, earlier }) {
|
|
414
|
+
if (!form) return { list: null, counts: given };
|
|
415
|
+
const list = form.list.map((f, n) =>
|
|
416
|
+
findingOf(f, `${cycle ? `c${cycle}.` : ''}p${k}.${n + 1}`, earlier),
|
|
417
|
+
);
|
|
418
|
+
const count = (s) => list.filter((f) => f.severity === s).length;
|
|
419
|
+
|
|
420
|
+
return { list, counts: { blocking: count('blocking'), polish: count('polish') } };
|
|
421
|
+
}
|
|
422
|
+
|
|
423
|
+
/**
|
|
424
|
+
* A pass's form, refused when it is neither or both (d2): its `--findings` file read (`{name, list,
|
|
425
|
+
* label}`), null for the old `--blocking N --polish M`.
|
|
426
|
+
*/
|
|
427
|
+
function passForm(projectDir, pass, kind) {
|
|
428
|
+
const given = pass.blocking !== undefined || pass.polish !== undefined;
|
|
429
|
+
if (pass.findings !== undefined && given)
|
|
430
|
+
throw new Error('--findings counts the pass itself: give it or --blocking/--polish, not both');
|
|
431
|
+
if (pass.findings === undefined && !given)
|
|
432
|
+
throw new Error('a pass is --findings <file.json>, or --blocking <n> --polish <m>');
|
|
433
|
+
if (!KINDS.includes(kind)) throw new Error(`--kind is ${KINDS.join(' | ')}, got ${kind}`);
|
|
434
|
+
if (pass.findings === undefined) return null;
|
|
435
|
+
if (kind !== 'plan') throw new Error("--findings is the plan review's: --kind plan");
|
|
436
|
+
|
|
437
|
+
return readFindings(projectDir, pass.findings);
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
/**
|
|
441
|
+
* Refuse a `--findings` file labelled for another pass: its `cycle` and `pass` the pass recorded,
|
|
442
|
+
* its `by` and `for` the ones given; a field it does not carry is not checked.
|
|
443
|
+
*/
|
|
444
|
+
function labelFits({ name, label }, { cycle, k, by, row }) {
|
|
445
|
+
const off = (key, want, same = (a, b) => Number(a) === b) =>
|
|
446
|
+
label[key] != null && want !== undefined && !same(label[key], want)
|
|
447
|
+
? `${key} ${label[key]}, not ${want}`
|
|
448
|
+
: null;
|
|
449
|
+
const who = (a, b) => rowKey(String(a)) === rowKey(b);
|
|
450
|
+
const why = [off('cycle', cycle), off('pass', k), off('by', by, who), off('for', row, who)];
|
|
451
|
+
const bad = why.filter(Boolean);
|
|
452
|
+
if (bad.length)
|
|
453
|
+
throw new Error(`--findings ${name} is another pass's: ${bad.join('; ')}; ask this pass again`);
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
/**
|
|
457
|
+
* The findings of a `--findings` file: a list, or `{findings: […]}` as a reviewer answers, and
|
|
458
|
+
* the object's label (`cycle`, `pass`, `by`, `for`), none for a list.
|
|
459
|
+
*/
|
|
460
|
+
function readFindings(projectDir, name) {
|
|
461
|
+
let json;
|
|
462
|
+
try {
|
|
463
|
+
json = JSON.parse(readFileSync(path.resolve(projectDir, name), 'utf8'));
|
|
464
|
+
} catch (e) {
|
|
465
|
+
throw new Error(`--findings ${name}: ${e.message}`, { cause: e });
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
const list = Array.isArray(json) ? json : json?.findings;
|
|
469
|
+
if (!Array.isArray(list))
|
|
470
|
+
throw new Error(`--findings ${name}: a list of findings, or {findings}`);
|
|
471
|
+
|
|
472
|
+
return { name, list, label: Array.isArray(json) ? {} : json };
|
|
220
473
|
}
|
|
221
474
|
|
|
475
|
+
/** Text on one line: its runs of white space one space. */
|
|
476
|
+
const oneLine = (s) => (typeof s === 'string' ? s.replace(/\s+/g, ' ').trim() : '');
|
|
477
|
+
|
|
478
|
+
/**
|
|
479
|
+
* Finding `f` with the author's verdict, checked, as its line will hold it (d2, d5, d8): a
|
|
480
|
+
* blocking one without a scenario is polish (`no scenario`), unless it `raises` an earlier
|
|
481
|
+
* blocking one; a blocking one that raises a finding the author rejected or downgraded counts
|
|
482
|
+
* as accepted.
|
|
483
|
+
*/
|
|
484
|
+
function findingOf(f, tag, earlier) {
|
|
485
|
+
const { summary, reason } = checkedFinding(f, `finding ${tag}`);
|
|
486
|
+
const raised = earlier.find((e) => e.tag === f.raises && e.severity === 'blocking');
|
|
487
|
+
const blind = f.severity === 'blocking' && !oneLine(f.scenario) && !raised;
|
|
488
|
+
const severity = blind ? 'polish' : f.severity;
|
|
489
|
+
const again = severity === 'blocking' && raised && raised.verdict !== 'accepted';
|
|
490
|
+
const why = [again && `raised again after ${raised.tag}`, blind && 'no scenario', reason];
|
|
491
|
+
|
|
492
|
+
return {
|
|
493
|
+
...{ tag, severity, verdict: again ? 'accepted' : f.verdict },
|
|
494
|
+
// One token on the line: a space in a path is `_`.
|
|
495
|
+
...{ where: oneLine(f.where).replace(/\s+/g, '_') || '-', summary },
|
|
496
|
+
reason: why.filter(Boolean).join(', ') || null,
|
|
497
|
+
};
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
/** Finding `f`'s refusal, if any; its summary and reason on one line each. */
|
|
501
|
+
function checkedFinding(f, at) {
|
|
502
|
+
if (!f || typeof f !== 'object') throw new Error(`${at}: an object`);
|
|
503
|
+
if (!SEVERITIES.includes(f.severity))
|
|
504
|
+
throw new Error(`${at}: severity is ${SEVERITIES.join(' | ')}, got ${f.severity}`);
|
|
505
|
+
if (!VERDICTS.includes(f.verdict))
|
|
506
|
+
throw new Error(`${at}: verdict is ${VERDICTS.join(' | ')}, got ${f.verdict}`);
|
|
507
|
+
if (f.verdict === 'downgraded' && f.severity !== 'blocking')
|
|
508
|
+
throw new Error(`${at}: only a blocking finding is downgraded`);
|
|
509
|
+
// The summary's `; ` a comma: the line's reason begins at the first one.
|
|
510
|
+
const summary = oneLine(f.summary).replaceAll('; ', ', ');
|
|
511
|
+
if (!summary) throw new Error(`${at}: a summary`);
|
|
512
|
+
const reason = oneLine(f.reason);
|
|
513
|
+
if (f.verdict !== 'accepted' && !reason) throw new Error(`${at}: ${f.verdict} needs a reason`);
|
|
514
|
+
|
|
515
|
+
return { summary, reason };
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
/** A finding's line of `## Findings` (d2). */
|
|
519
|
+
const findingLine = (f) =>
|
|
520
|
+
`- ${f.tag} ${f.severity} ${f.verdict} ${f.where}: ${f.summary}` +
|
|
521
|
+
(f.reason ? `; ${f.reason}` : '');
|
|
522
|
+
|
|
222
523
|
/** A row as one: its Codex slug read as its family. */
|
|
223
524
|
const rowKey = (s) =>
|
|
224
525
|
s
|
|
@@ -246,11 +547,12 @@ function passArgs(blocking, polish, by, row) {
|
|
|
246
547
|
/** The plan with `line` at the end of its section of `kind`, the section added when none. */
|
|
247
548
|
function withPass(text, line, kind) {
|
|
248
549
|
const eol = text.includes('\r\n') ? '\r\n' : '\n';
|
|
249
|
-
const
|
|
250
|
-
const
|
|
550
|
+
const all = sectioned(text);
|
|
551
|
+
const lines = all.map((x) => x.line);
|
|
552
|
+
const at = all.findIndex((x, n) => x.at === n && SECTION[kind].test(x.line));
|
|
251
553
|
if (at < 0)
|
|
252
554
|
return `${text.replace(/\s*$/, '')}${eol}${eol}${HEADING[kind]}${eol}${eol}${line}${eol}`;
|
|
253
|
-
let end =
|
|
555
|
+
let end = all.findIndex((x, n) => n > at && x.at === n);
|
|
254
556
|
if (end < 0) end = lines.length;
|
|
255
557
|
// After the section's last line with words: its blank lines stay below it.
|
|
256
558
|
while (end > at + 1 && !lines[end - 1].trim()) end--;
|