rungate 0.8.25 → 0.8.26

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.
@@ -34,6 +34,7 @@
34
34
  * 7's opened-to-closed ratio. {@link uncoveredByMilestone} reports the input
35
35
  * to that decision and stops there.
36
36
  */
37
+ import { parseFrontmatter } from "./frontmatter";
37
38
  import { PHASE_TOKEN, readMilestoneTitle } from "./milestone-title";
38
39
  import { oneScMentionPattern } from "./sc-ids";
39
40
  import { parseCriteria } from "./spec-evidence";
@@ -57,6 +58,53 @@ export const NON_PHASE_PLACEMENTS = [
57
58
  "Not observable here",
58
59
  ] as const;
59
60
 
61
+ /**
62
+ * The non-phase placements under which a criterion is DECLARED — SC-2778.
63
+ *
64
+ * A criterion placed here is named apart by `criterion-coverage` and
65
+ * `declared-work` and leaves both targets: the spec has said it cannot start
66
+ * (or was deliberately not adopted, or cannot be observed here), so counting
67
+ * it as missing asks for an issue the spec says must not exist, and counting
68
+ * it as covered would credit work nobody can do (ADR-018 Decision 5). `Done`
69
+ * is not here: a done criterion is ticked, and both readings already handle
70
+ * a ticked one.
71
+ */
72
+ export const DECLARED_OUTSIDE_PHASES = [
73
+ "Blocked",
74
+ "Not adopted — deliberate",
75
+ "Not observable here",
76
+ ] as const satisfies readonly (typeof NON_PHASE_PLACEMENTS)[number][];
77
+
78
+ /**
79
+ * Where one placement value puts a criterion, for both readings — SC-2778.
80
+ *
81
+ * THE one predicate. `criterionCoverage` and `readDeclaredWork` both annotate
82
+ * their rows with it, so the two readings cannot disagree about a criterion.
83
+ *
84
+ * - `{ outside }`: one of {@link DECLARED_OUTSIDE_PHASES}, the value as written.
85
+ * - `{ unknownPlacement }`: neither a phase nor a known non-phase value. Both
86
+ * readings go UNMEASURED on it, by name, rather than guessing.
87
+ * - `null`: a phase, `Done`, or no placement at all — counted as before. A
88
+ * criterion placed nowhere is `spec-placement`'s UNPLANNED, not this.
89
+ */
90
+ export function outsidePhases(placement: string | undefined): { outside: string } | { unknownPlacement: string } | null {
91
+ if (placement === undefined || PHASE_VALUE.test(placement)) return null;
92
+ if (DECLARED_OUTSIDE_PHASES.some(v => placement.startsWith(v))) return { outside: placement };
93
+ if (NON_PHASE_PLACEMENTS.some(v => placement.startsWith(v))) return null;
94
+ return { unknownPlacement: placement };
95
+ }
96
+
97
+ /**
98
+ * Each criterion's placement value, read from the spec's own table. A
99
+ * criterion placed more than once is an unknown placement naming both values: the
100
+ * table contradicts itself, and picking one is a guess (SC-2778).
101
+ */
102
+ export function placementsById(content: string): Map<string, string> {
103
+ const where = new Map<string, string[]>();
104
+ for (const r of parsePlacementRows(content)) for (const id of r.ids) where.set(id, [...(where.get(id) ?? []), r.placement]);
105
+ return new Map([...where].map(([id, p]) => [id, p.length === 1 ? p[0]! : `placed ${p.length} times: ${p.join(" and ")}`]));
106
+ }
107
+
60
108
  /** `Phase 0`, `Phase 11`. The capture is the number. */
61
109
  export const PHASE_VALUE = new RegExp(`^${PHASE_TOKEN}$`);
62
110
 
@@ -241,21 +289,267 @@ export interface SpecPlacement {
241
289
  /** How many criteria the spec states, and how many the table places. */
242
290
  criteria: number;
243
291
  placed: number;
244
- /** The spec declares `board-scope: deferred` in its frontmatter — SC-2734. */
292
+ /** The spec declares `scope: deferred` (or the legacy `board-scope: deferred`) — SC-2734. */
245
293
  deferred: boolean;
294
+ /** What the spec's own frontmatter says about the board — SC-2776. */
295
+ board: BoardDeclaration;
246
296
  }
247
297
 
248
298
  /**
249
- * Whether a spec holds itself back from the board — SC-2734.
299
+ * Whether a spec is on the board, read from its own frontmatter — SC-2776.
300
+ *
301
+ * - `active`: a `board:` block with `scope: active`. The only value the
302
+ * engine consumes.
303
+ * - `deferred`: `scope: deferred`, or the legacy `board-scope: deferred`
304
+ * line, which reads the same (ADR-018 Decision 9).
305
+ * - `undeclared`: no `board:` block and no legacy line. Never planned,
306
+ * labelled or placed, whatever else the spec carries — a placement table
307
+ * alone pulls nothing in (ADR-018 Decision 8).
308
+ * - `invalid`: a declaration the engine could not read. `problems` says why,
309
+ * and the spec is consumed no more than an undeclared one.
310
+ */
311
+ export type BoardScope = "active" | "deferred" | "undeclared" | "invalid";
312
+
313
+ export interface BoardDeclaration {
314
+ scope: BoardScope;
315
+ /**
316
+ * Every key in {@link BOARD_KEYS} the block sets, as text — `prefix` is
317
+ * `settings.prefix`. Carried whole, so the snapshot and
318
+ * `board-conformance` pass a new setting through without naming it.
319
+ */
320
+ settings: Record<string, string>;
321
+ /**
322
+ * What stops the engine reading the declaration as written — an unknown
323
+ * scope value, an active spec with no prefix, a block that is not YAML, a
324
+ * declaration made twice. `spec-placement` refuses on any of these, by name.
325
+ */
326
+ problems: string[];
327
+ /**
328
+ * Keys {@link BOARD_KEYS} does not hold. Reported by name and otherwise
329
+ * ignored (ADR-018 Decision 9): they never block a reading, and
330
+ * `test/board-families.test.ts` fails the pull request that adds one to a
331
+ * spec in this tree, which is where a teammate hears about a typo.
332
+ */
333
+ unknownKeys: string[];
334
+ }
335
+
336
+ /**
337
+ * The keys the engine reads inside `board:` — ADR-018 Decision 9.
250
338
  *
251
- * Read from the FRONTMATTER only: a body line spelling the same words is
252
- * prose about the convention, not a declaration, and reading it would let a
253
- * spec defer itself by quoting this rule.
339
+ * **THE one place a board setting is added.** The sweep, the snapshot and
340
+ * `board-conformance` carry {@link BoardDeclaration} whole, so none of them
341
+ * names a key; only the code that acts on a setting has to know it exists.
342
+ * `values` closes a key to a set, reported by name when anything else is
343
+ * written; a key without it takes any single value.
344
+ *
345
+ * The list lives in code, not config, on purpose: a key with no code behind it
346
+ * does nothing, and a config that could name one would promise a setting the
347
+ * engine silently ignores.
348
+ */
349
+ export const BOARD_KEYS: Readonly<Record<string, { what: string; values?: readonly string[] }>> = {
350
+ scope: { what: "whether the engine consumes this spec", values: ["active", "deferred"] },
351
+ prefix: { what: "the milestone family the spec's phases are named in" },
352
+ };
353
+
354
+ /**
355
+ * One frontmatter entry's value, parsed as YAML — only that entry, never the
356
+ * whole block. Whole-block YAML is not available here: the engine spec's own
357
+ * `governs:` line carries a `: ` inside a plain scalar, which YAML refuses.
358
+ */
359
+ function yamlValue(e: { key: string; inline: string; block: string[] }): { value: unknown } | { error: string } {
360
+ const text = [`${e.key}:${e.inline === "" ? "" : ` ${e.inline}`}`, ...e.block].join("\n");
361
+ try {
362
+ const doc = Bun.YAML.parse(text) as Record<string, unknown> | null;
363
+ return { value: doc?.[e.key] ?? null };
364
+ } catch (err) {
365
+ return { error: (err as Error).message };
366
+ }
367
+ }
368
+
369
+ /**
370
+ * The index of the `}` closing the flow mapping that opens `text`, or -1.
371
+ * Quoted text is skipped (with YAML's `\"` and `''` escapes), so a brace
372
+ * inside a value or a trailing comment cannot end the mapping early.
373
+ */
374
+ function closingBrace(text: string): number {
375
+ let depth = 0;
376
+ for (let i = 0; i < text.length; i++) {
377
+ const c = text[i];
378
+ if (c === '"') {
379
+ for (i++; i < text.length && text[i] !== '"'; i++) if (text[i] === "\\") i++;
380
+ } else if (c === "'") {
381
+ for (i++; i < text.length; i++) {
382
+ if (text[i] !== "'") continue;
383
+ if (text[i + 1] === "'") i++;
384
+ else break;
385
+ }
386
+ } else if (c === "{" || c === "[") depth++;
387
+ else if ((c === "}" || c === "]") && --depth === 0) return i;
388
+ }
389
+ return -1;
390
+ }
391
+
392
+ /**
393
+ * Keys written twice at the top of `board:`, in either form. YAML keeps the
394
+ * last silently, which is the guess this reading must not make.
395
+ *
396
+ * The block form is read line by line at the first key's indent. The one-line
397
+ * form is re-read by the YAML parser as a SEQUENCE — `{ a: 1, a: 2 }` becomes
398
+ * `[ a: 1, a: 2 ]`, which YAML parses as one single-pair mapping per entry —
399
+ * so every pair survives, duplicates included, with YAML's own quoting and
400
+ * nesting rules. `null` means the one-line form could not be re-read, which
401
+ * the caller reports rather than taking as "no repeats".
402
+ */
403
+ function repeatedKeys(e: { inline: string; block: string[] }): string[] | null {
404
+ const names: string[] = [];
405
+ if (e.inline.startsWith("{")) {
406
+ const close = closingBrace(e.inline);
407
+ if (close < 0) return null;
408
+ try {
409
+ const pairs = (Bun.YAML.parse(`x: [${e.inline.slice(1, close)}]`) as { x: unknown }).x;
410
+ if (!Array.isArray(pairs)) return null;
411
+ for (const p of pairs) {
412
+ if (typeof p !== "object" || p === null || Array.isArray(p)) return null;
413
+ names.push(...Object.keys(p));
414
+ }
415
+ } catch {
416
+ // Refused as a sequence while it parsed as a mapping: the pairs cannot
417
+ // be counted, so the caller reports it instead of reading "no repeats".
418
+ return null;
419
+ }
420
+ }
421
+ // The block form's top level is read as bare `key:` names ONLY. A line
422
+ // there spelled any other way — a quoted key, a `? ` complex key, a `<<:`
423
+ // merge — is refused rather than parsed, so no YAML spelling of a repeat
424
+ // can slip past (review of #2308). Deeper lines are nested values.
425
+ const lines = e.block.filter(l => l.trim() !== "" && !l.trim().startsWith("#"));
426
+ const top = lines[0]?.match(/^[ \t]*/)?.[0];
427
+ for (const l of lines) {
428
+ if (l.match(/^[ \t]*/)?.[0] !== top) continue;
429
+ const m = /^[ \t]+([A-Za-z_][\w-]*)[ \t]*:/.exec(l);
430
+ if (m === null) return null;
431
+ names.push(m[1]!);
432
+ }
433
+ return [...new Set(names.filter((n, i) => names.indexOf(n) !== i))];
434
+ }
435
+
436
+ /**
437
+ * What a spec's frontmatter says about the board — SC-2776.
438
+ *
439
+ * Read from the FRONTMATTER only, through `parseFrontmatter`: a body line
440
+ * spelling the same words is prose about the convention, not a declaration,
441
+ * and reading it would let a spec opt itself in, or hold itself back, by
442
+ * quoting this rule. The `board:` entry itself is parsed by Bun's YAML
443
+ * parser, so quoting, commas, comments and the one-line `{ … }` form mean
444
+ * what YAML says they mean.
445
+ *
446
+ * **Reported, never guessed.** An unknown key is named and otherwise
447
+ * ignored, so a typo — `scpoe: active` — leaves the spec with no scope and
448
+ * opts nothing in. An unknown scope value is named and opts nothing in. An
449
+ * active spec with no prefix stays active, so the reading can name it,
450
+ * and the prefix is not invented from the filename: `CODE-REVIEW-CONVERGENCE-SPEC.md`
451
+ * would derive *Code Review Convergence*, which is not what its milestones
452
+ * are called (see {@link milestonePlan}).
453
+ */
454
+ export function boardDeclaration(content: string): BoardDeclaration {
455
+ const none = (): BoardDeclaration => ({ scope: "undeclared", settings: {}, problems: [], unknownKeys: [] });
456
+ if (!/^---\r?\n/.test(content)) return none();
457
+ const fm = parseFrontmatter(content);
458
+ if (fm === null) {
459
+ // A block the parser refuses — a column-0 `#` comment is the live one —
460
+ // still cannot opt in if no line of it so much as starts a board key.
461
+ // With no closing fence at all, everything after the opening one is the
462
+ // block as far as anyone can tell, so that is what gets scanned — the
463
+ // fenced regex alone would hand back "" and read the most broken input
464
+ // as undeclared (review of #2308).
465
+ const fenced = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
466
+ const raw = fenced?.[1] ?? content.replace(/^---\r?\n/, "");
467
+ if (!/^board(?:-scope)?[ \t]*:/m.test(raw)) return none();
468
+ return {
469
+ ...none(),
470
+ scope: "invalid",
471
+ problems: ["the frontmatter has a line no key owns, so whether it opts this spec in cannot be read"],
472
+ };
473
+ }
474
+ const blocks = fm.entries.filter(e => e.key === "board");
475
+ const legacy = fm.entries.filter(e => e.key === "board-scope");
476
+ if (blocks.length === 0 && legacy.length === 0) return none();
477
+
478
+ const settings: Record<string, string> = {};
479
+ const problems: string[] = [];
480
+ const unknownKeys: string[] = [];
481
+ // A declaration made twice, or two that disagree, is one the engine cannot
482
+ // read: picking either is the guess this function exists not to make.
483
+ let contested = false;
484
+ const twice = (what: string) => {
485
+ problems.push(`${what} is declared more than once`);
486
+ contested = true;
487
+ };
488
+ if (blocks.length > 1) twice("`board:`");
489
+ if (legacy.length > 1) twice("`board-scope:`");
490
+
491
+ const block = blocks[0];
492
+ if (block !== undefined) {
493
+ const read = yamlValue(block);
494
+ const keys = Object.keys(BOARD_KEYS).join(", ");
495
+ if ("error" in read) problems.push(`the \`board:\` block is not valid YAML (${read.error})`);
496
+ else if (typeof read.value !== "object" || read.value === null || Array.isArray(read.value)) {
497
+ problems.push(`\`board:\` must be a block of keys (${keys}), not ${JSON.stringify(read.value)}`);
498
+ } else {
499
+ const repeats = repeatedKeys(block);
500
+ if (repeats === null) {
501
+ problems.push(
502
+ "`board:` could not be checked for a key written twice — at its top level the engine reads only " +
503
+ "bare `key:` names, so a quoted, complex or merge key is refused",
504
+ );
505
+ contested = true;
506
+ } else for (const k of repeats) twice(`\`board.${k}\``);
507
+ for (const [key, v] of Object.entries(read.value as Record<string, unknown>)) {
508
+ const known = BOARD_KEYS[key];
509
+ if (known === undefined) {
510
+ unknownKeys.push(key);
511
+ continue;
512
+ }
513
+ if (v !== null && typeof v === "object") {
514
+ problems.push(`\`board.${key}\` takes a single value, not ${JSON.stringify(v)}`);
515
+ continue;
516
+ }
517
+ const text = v === null ? "" : String(v);
518
+ if (known.values !== undefined && !known.values.includes(text)) {
519
+ problems.push(`\`board.${key}: ${text}\` is not a value the engine knows (${known.values.join(" or ")})`);
520
+ }
521
+ if (text !== "") settings[key] = text;
522
+ }
523
+ if (!("scope" in (read.value as object))) problems.push("the `board:` block declares no `scope`");
524
+ }
525
+ }
526
+
527
+ let scope = settings.scope;
528
+ const old = legacy[0];
529
+ if (old !== undefined) {
530
+ const read = yamlValue(old);
531
+ if ("error" in read || read.value !== "deferred") {
532
+ problems.push(`\`board-scope: ${old.inline}\` — the legacy line takes only \`deferred\``);
533
+ contested = true;
534
+ } else if (scope !== undefined && scope !== "deferred") {
535
+ problems.push(`\`board.scope: ${scope}\` and the legacy \`board-scope: deferred\` disagree`);
536
+ contested = true;
537
+ } else scope = "deferred";
538
+ }
539
+ if (scope === "active" && settings.prefix === undefined) {
540
+ problems.push("the spec is active and declares no `prefix`, so no milestone can be named for its phases");
541
+ }
542
+
543
+ const read: BoardScope = !contested && (scope === "active" || scope === "deferred") ? scope : "invalid";
544
+ return { scope: read, settings, problems, unknownKeys };
545
+ }
546
+
547
+ /**
548
+ * Whether a spec holds itself back from the board — SC-2734, read through
549
+ * {@link boardDeclaration} so the deferral and the opt-in are one reading.
254
550
  */
255
551
  export function declaresDeferred(content: string): boolean {
256
- const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
257
- if (m === null) return false;
258
- return /^board-scope:[ \t]*(["']?)deferred\1[ \t]*\r?$/m.test(m[1]!);
552
+ return boardDeclaration(content).scope === "deferred";
259
553
  }
260
554
 
261
555
  export interface PlacementCoverage {
@@ -321,11 +615,20 @@ export function placementCoverage(
321
615
  try {
322
616
  content = readSpec(root, path);
323
617
  } catch (e) {
324
- specs.push({ path, state: "UNREADABLE", reasons: [(e as Error).message], criteria: 0, placed: 0, deferred: false });
618
+ specs.push({
619
+ path,
620
+ state: "UNREADABLE",
621
+ reasons: [(e as Error).message],
622
+ criteria: 0,
623
+ placed: 0,
624
+ deferred: false,
625
+ board: { scope: "undeclared", settings: {}, problems: [], unknownKeys: [] },
626
+ });
325
627
  reasons.push(`could not read ${path}: ${(e as Error).message}`);
326
628
  continue;
327
629
  }
328
630
  const r = placementReading(content);
631
+ const board = boardDeclaration(content);
329
632
  const placed = r.criteria.length - r.unplaced.length;
330
633
  const state: PlacementState =
331
634
  r.criteria.length === 0 ? "NO_CRITERIA" : r.reading === "MEASURED" ? "PLANNED" : "UNPLANNED";
@@ -335,7 +638,8 @@ export function placementCoverage(
335
638
  reasons: state === "PLANNED" ? [] : r.unmeasuredReasons,
336
639
  criteria: r.criteria.length,
337
640
  placed,
338
- deferred: declaresDeferred(content),
641
+ deferred: board.scope === "deferred",
642
+ board,
339
643
  });
340
644
  }
341
645
 
@@ -370,6 +674,10 @@ export interface CriterionCoverage {
370
674
  satisfiedByIssue: number | null;
371
675
  /** The spec's own checkbox is ticked — already true, needing only a binding. */
372
676
  recordedTrue: boolean;
677
+ /** Placed under one of {@link DECLARED_OUTSIDE_PHASES} — SC-2778. Present only when it is. */
678
+ outside?: string;
679
+ /** Placed under a value the engine does not know — SC-2778. Present only when it is. */
680
+ unknownPlacement?: string;
373
681
  }
374
682
 
375
683
  /**
@@ -415,11 +723,12 @@ export function criterionCoverage(
415
723
  // Ascending, so "the lowest number wins" is the first write rather than a
416
724
  // comparison every later issue has to remember to make.
417
725
  const ordered = [...issues].sort((a, b) => a.number - b.number);
726
+ const placed = placementsById(content);
418
727
  return parseCriteria(content).map(c => {
419
728
  const naming = ordered.find(
420
729
  i => typeof i.criteriaField === "string" && oneScMentionPattern(c.id).test(i.criteriaField),
421
730
  );
422
- return { id: c.id, satisfiedByIssue: naming?.number ?? null, recordedTrue: c.ticked };
731
+ return { id: c.id, satisfiedByIssue: naming?.number ?? null, recordedTrue: c.ticked, ...outsidePhases(placed.get(c.id)) };
423
732
  });
424
733
  }
425
734
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.8.25",
3
+ "version": "0.8.26",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
6
  "repository": {