rungate 0.8.13 → 0.8.16
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 +182 -0
- package/gates/.gate-salt +1 -1
- package/hooks/HarnessAFKGate.hook.ts +5 -1
- package/hooks/HookCurrency.hook.ts +11 -8
- package/hooks/MergeGuard.hook.ts +7 -1
- package/hooks/StaleTTLCleanup.hook.ts +4 -4
- package/hooks/VerifyPhaseLock.hook.ts +3 -3
- package/hooks/lib/findWorkflow.ts +3 -2
- package/hooks/lib/paths.ts +14 -2
- package/hooks/lib/utils.ts +23 -3
- package/lib/active-milestone.ts +50 -0
- package/lib/ai-review-rounds.ts +99 -0
- package/lib/ai-review-suppression.ts +200 -21
- package/lib/bash-write-guard.ts +397 -23
- package/lib/board-flow.ts +280 -0
- package/lib/board-lane-health.ts +578 -0
- package/lib/board-mirror.ts +136 -39
- package/lib/board-ready-fanout.ts +297 -14
- package/lib/board-ready-rule.ts +1211 -0
- package/lib/board-throughput.ts +136 -0
- package/lib/board-walkthrough.ts +240 -0
- package/lib/body-evidence.ts +203 -0
- package/lib/branch-protection.ts +399 -9
- package/lib/bun-version.ts +36 -0
- package/lib/cli-commands.ts +75 -4
- package/lib/closing-reference-audit.ts +307 -6
- package/lib/config-loader.ts +254 -25
- package/lib/config-readers.ts +170 -10
- package/lib/config-trackable.ts +96 -57
- package/lib/conformity.ts +121 -7
- package/lib/create-sc.ts +25 -2
- package/lib/derived-spec.ts +21 -9
- package/lib/filing-compliance.ts +367 -0
- package/lib/filing-plan.ts +47 -21
- package/lib/finding-arbiter.ts +79 -5
- package/lib/finding-jury.ts +43 -4
- package/lib/finding-promotion.ts +1123 -0
- package/lib/generators/agents-md.ts +149 -0
- package/lib/git-isolation.ts +137 -1
- package/lib/github-api-base.ts +66 -0
- package/lib/github.ts +194 -9
- package/lib/graphql-cursor.ts +80 -0
- package/lib/hook-scopes.ts +78 -0
- package/lib/issue-create-override.ts +415 -3
- package/lib/issue-decomposition.ts +124 -7
- package/lib/issue-extraction.ts +9 -7
- package/lib/issue-file-overlap.ts +373 -0
- package/lib/issue-filing-gate.ts +1109 -52
- package/lib/issue-repair.ts +90 -9
- package/lib/issue-shape.ts +199 -0
- package/lib/live-issues.ts +31 -2
- package/lib/local-work.ts +423 -0
- package/lib/markdown-fence.ts +134 -0
- package/lib/milestone-title.ts +46 -0
- package/lib/scaffold/ai-review-findings.ts +148 -3
- package/lib/scaffold/ai-review-step.ts +65 -5
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
- package/lib/scaffold/steps.ts +115 -9
- package/lib/source-census.ts +108 -0
- package/lib/spec-deps.ts +55 -11
- package/lib/spec-placement.ts +203 -13
- package/lib/spec-registry.ts +75 -16
- package/lib/spec-source.ts +609 -0
- package/lib/spec-write-sweep.ts +4 -0
- package/lib/stage-ladder.ts +896 -3
- package/lib/state-claim-readings.ts +252 -0
- package/lib/success-doc.ts +7 -6
- package/lib/test-command-positions.ts +135 -1
- package/lib/work-status.ts +551 -0
- package/lib/worktree-repo.ts +14 -2
- package/package.json +7 -1
- package/scripts/ai-review-findings.ts +8 -13
- package/scripts/ai-review-threads.ts +16 -17
- package/scripts/audit-closing-references.ts +330 -0
- package/scripts/audit-specs.ts +59 -103
- package/scripts/board-conformance.ts +747 -40
- package/scripts/board-mirror.ts +594 -13
- package/scripts/board-ready.ts +979 -0
- package/scripts/board-snapshot.ts +464 -12
- package/scripts/claim-files.ts +578 -0
- package/scripts/criterion-inventory.ts +526 -50
- package/scripts/finding-promotion.ts +547 -0
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/plan-issues.ts +279 -40
- package/scripts/plan-spec.ts +105 -3
- package/scripts/sync-sc-status.ts +147 -7
- package/scripts/worktree-census.ts +958 -0
- package/scripts/worktree-sweep.ts +269 -0
package/lib/spec-deps.ts
CHANGED
|
@@ -20,9 +20,9 @@
|
|
|
20
20
|
*
|
|
21
21
|
* ## The phase sequence is the phases that EXIST, never N-1 arithmetic
|
|
22
22
|
*
|
|
23
|
-
* {@link dependencyPlan} sorts the phases that actually carry issues and
|
|
24
|
-
*
|
|
25
|
-
* number — Phase 0, 1, 3 with nothing in 2 — would otherwise leave Phase 3
|
|
23
|
+
* {@link dependencyPlan} sorts the phases that actually carry issues and hands
|
|
24
|
+
* that list to {@link chainAdjacentPhases}. A spec whose placement table skips
|
|
25
|
+
* a number — Phase 0, 1, 3 with nothing in 2 — would otherwise leave Phase 3
|
|
26
26
|
* blocked by a phase that does not exist, which reads as *unblocked* and puts
|
|
27
27
|
* the last phase in the Ready lane beside the first.
|
|
28
28
|
*
|
|
@@ -45,6 +45,7 @@
|
|
|
45
45
|
* `includeClosed` to derive them anyway; the default is to leave them out.
|
|
46
46
|
*/
|
|
47
47
|
import { phaseOf } from "./board-mirror";
|
|
48
|
+
import { familyOf } from "./spec-placement";
|
|
48
49
|
|
|
49
50
|
export interface DepIssue {
|
|
50
51
|
readonly number: number;
|
|
@@ -164,6 +165,36 @@ export function degenerateReasons(r: {
|
|
|
164
165
|
return out;
|
|
165
166
|
}
|
|
166
167
|
|
|
168
|
+
/**
|
|
169
|
+
* The cross product of each phase with the one immediately before it in the
|
|
170
|
+
* list it is handed — the whole of the ordering rule, in one symbol.
|
|
171
|
+
*
|
|
172
|
+
* `phases` must be the phases that EXIST, ascending. This function does no
|
|
173
|
+
* arithmetic on the numbers: it pairs index `k` with index `k - 1`, so a
|
|
174
|
+
* placement table that skips Phase 2 chains 1 → 3 rather than leaving Phase 3
|
|
175
|
+
* blocked by a phase carrying nothing. Passing an unsorted list, or one
|
|
176
|
+
* containing a phase with no issues, is what a caller must not do.
|
|
177
|
+
*
|
|
178
|
+
* It lives here rather than inline in {@link dependencyPlan} because SC-2606
|
|
179
|
+
* is the criterion that this rule is *named*: a reader looking for where
|
|
180
|
+
* adjacency is decided has one symbol to open, and a mutation of it moves
|
|
181
|
+
* every edge the plan reports.
|
|
182
|
+
*/
|
|
183
|
+
export function chainAdjacentPhases(
|
|
184
|
+
phases: readonly number[],
|
|
185
|
+
byPhase: ReadonlyMap<number, readonly DepIssue[]>,
|
|
186
|
+
): DepEdge[] {
|
|
187
|
+
const edges: DepEdge[] = [];
|
|
188
|
+
for (let k = 1; k < phases.length; k++) {
|
|
189
|
+
for (const blocked of byPhase.get(phases[k]) ?? []) {
|
|
190
|
+
for (const blocker of byPhase.get(phases[k - 1]) ?? []) {
|
|
191
|
+
edges.push({ blocked: blocked.number, blocker: blocker.number });
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
return edges;
|
|
196
|
+
}
|
|
197
|
+
|
|
167
198
|
/**
|
|
168
199
|
* What the repository's `blocked by` edges should be, given the phases its
|
|
169
200
|
* issues sit in.
|
|
@@ -183,6 +214,9 @@ export function dependencyPlan(
|
|
|
183
214
|
const unphased: number[] = [];
|
|
184
215
|
const byPhase = new Map<number, DepIssue[]>();
|
|
185
216
|
for (const i of considered) {
|
|
217
|
+
// One reading of the title (#2057): a phase always has a family, so the
|
|
218
|
+
// "phase but no family" state the review of #2055 had to report is gone.
|
|
219
|
+
// `Release (Phase 3)` is not a phase milestone, to every reader.
|
|
186
220
|
const p = phaseOf(i.milestone);
|
|
187
221
|
if (p === null) {
|
|
188
222
|
unphased.push(i.number);
|
|
@@ -200,16 +234,26 @@ export function dependencyPlan(
|
|
|
200
234
|
truncated: issues.filter(i => i.blockedByTruncated === true).map(i => i.number),
|
|
201
235
|
});
|
|
202
236
|
|
|
203
|
-
// Adjacent members of the phases that EXIST
|
|
204
|
-
//
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
237
|
+
// Adjacent members of the phases that EXIST, chained WITHIN each milestone
|
|
238
|
+
// family (#2024, SC-2617). See the header: `p - 1` would leave a phase after
|
|
239
|
+
// a gap blocked by nothing and reading as startable. And `Convergence
|
|
240
|
+
// Phase 1` follows `Convergence Phase 0`, never `Pipeline Phase 0`: a
|
|
241
|
+
// repository-wide plan bucketed by number alone chains one spec to another,
|
|
242
|
+
// which is how #1903's reading measured 129 of 154 and was withdrawn.
|
|
243
|
+
// `plan-deps` narrows to one family before calling, so it sees one bucket.
|
|
244
|
+
const byFamily = new Map<string, Map<number, DepIssue[]>>();
|
|
245
|
+
for (const [p, members] of byPhase) {
|
|
246
|
+
for (const i of members) {
|
|
247
|
+
const f = familyOf(i.milestone) as string;
|
|
248
|
+
const fam = byFamily.get(f) ?? new Map<number, DepIssue[]>();
|
|
249
|
+
fam.set(p, [...(fam.get(p) ?? []), i]);
|
|
250
|
+
byFamily.set(f, fam);
|
|
211
251
|
}
|
|
212
252
|
}
|
|
253
|
+
const derived: DepEdge[] = [];
|
|
254
|
+
for (const fam of byFamily.values()) {
|
|
255
|
+
derived.push(...chainAdjacentPhases([...fam.keys()].sort((a, b) => a - b), fam));
|
|
256
|
+
}
|
|
213
257
|
|
|
214
258
|
const key = (e: DepEdge): string => `${e.blocked}<-${e.blocker}`;
|
|
215
259
|
const derivedKeys = new Set(derived.map(key));
|
package/lib/spec-placement.ts
CHANGED
|
@@ -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 { PHASE_TOKEN, readMilestoneTitle } from "./milestone-title";
|
|
37
38
|
import { oneScMentionPattern } from "./sc-ids";
|
|
38
39
|
import { parseCriteria } from "./spec-evidence";
|
|
39
40
|
|
|
@@ -57,7 +58,7 @@ export const NON_PHASE_PLACEMENTS = [
|
|
|
57
58
|
] as const;
|
|
58
59
|
|
|
59
60
|
/** `Phase 0`, `Phase 11`. The capture is the number. */
|
|
60
|
-
export const PHASE_VALUE =
|
|
61
|
+
export const PHASE_VALUE = new RegExp(`^${PHASE_TOKEN}$`);
|
|
61
62
|
|
|
62
63
|
/**
|
|
63
64
|
* Which phase of `prefix`'s family this milestone title is, or `null`.
|
|
@@ -78,8 +79,9 @@ export const PHASE_VALUE = /^Phase (\d+)$/;
|
|
|
78
79
|
* them a case is holding up: `.claude/rules/checks-must-be-able-to-fail.md`,
|
|
79
80
|
* fourth shape.
|
|
80
81
|
*
|
|
81
|
-
* The
|
|
82
|
-
*
|
|
82
|
+
* The family is compared as a string against `readMilestoneTitle`'s reading,
|
|
83
|
+
* never compiled into a pattern, so a family name containing regex
|
|
84
|
+
* punctuation (`C++`) means itself.
|
|
83
85
|
*
|
|
84
86
|
* Not to be confused with `phaseOf` in `lib/board-mirror.ts`, which reads a
|
|
85
87
|
* phase number out of ANY title regardless of family. That one answers a
|
|
@@ -88,8 +90,29 @@ export const PHASE_VALUE = /^Phase (\d+)$/;
|
|
|
88
90
|
* is derived.
|
|
89
91
|
*/
|
|
90
92
|
export function phaseInFamily(title: string | null | undefined, prefix: string): number | null {
|
|
91
|
-
|
|
92
|
-
|
|
93
|
+
// #2057: compared against the one reading, not interpolated into a second
|
|
94
|
+
// regex. An empty prefix is no family here: it is refused upstream
|
|
95
|
+
// (lib/live-issues.ts) and must not match every bare `Phase N` title.
|
|
96
|
+
const r = readMilestoneTitle(title);
|
|
97
|
+
return prefix !== "" && r !== null && r.family === prefix ? r.phase : null;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* The family a phase milestone belongs to — `Pipeline` for `Pipeline Phase 6
|
|
102
|
+
* — …`, `""` for a bare `Phase N` title (a repository with no prefix has one
|
|
103
|
+
* family, the reading `familyRank` takes for a null prefix), or null when
|
|
104
|
+
* the title is neither shape (#2024). Null is not a family: a caller must
|
|
105
|
+
* not fold it into one, or every unreadable title chains to every other.
|
|
106
|
+
*
|
|
107
|
+
* The same grammar as {@link phaseInFamily}, read the other way: for every
|
|
108
|
+
* title this returns a NON-EMPTY family for, `phaseInFamily(title,
|
|
109
|
+
* familyOf(title))` is the title's phase. The unprefixed family `""` is the
|
|
110
|
+
* one exception — `phaseInFamily` takes a prefix and an empty one is refused
|
|
111
|
+
* upstream (`lib/live-issues.ts`), so it has no `""` reading to agree with. `test/plan-deps.test.ts` asserts that agreement, so the
|
|
112
|
+
* two cannot drift into a second decider of what a family is.
|
|
113
|
+
*/
|
|
114
|
+
export function familyOf(title: string | null | undefined): string | null {
|
|
115
|
+
return readMilestoneTitle(title)?.family ?? null;
|
|
93
116
|
}
|
|
94
117
|
|
|
95
118
|
export interface PlacementRow {
|
|
@@ -141,11 +164,14 @@ export function parsePlacementRows(content: string): PlacementRow[] {
|
|
|
141
164
|
return out;
|
|
142
165
|
}
|
|
143
166
|
|
|
167
|
+
/** `## Phase N — title` to `#### …`: the heading a milestone is named from. */
|
|
168
|
+
const PHASE_HEADING = new RegExp(String.raw`^#{2,4} (${PHASE_TOKEN}(?:\s*[—–-]\s*(.*))?)\s*$`);
|
|
169
|
+
|
|
144
170
|
/** Every `### Phase N — …` heading, in document order. */
|
|
145
171
|
export function parsePhaseHeadings(content: string): PhaseHeading[] {
|
|
146
172
|
const out: PhaseHeading[] = [];
|
|
147
173
|
content.split("\n").forEach((line, i) => {
|
|
148
|
-
const m = line.match(
|
|
174
|
+
const m = line.match(PHASE_HEADING);
|
|
149
175
|
if (!m) return;
|
|
150
176
|
out.push({ number: Number(m[2]), title: (m[3] ?? "").trim(), heading: m[1].trim(), line: i + 1 });
|
|
151
177
|
});
|
|
@@ -203,6 +229,130 @@ export function placementReading(content: string): PlacementReading {
|
|
|
203
229
|
};
|
|
204
230
|
}
|
|
205
231
|
|
|
232
|
+
/** What one spec's planning state is, across the whole tree — SC-2611. */
|
|
233
|
+
export type PlacementState = "PLANNED" | "UNPLANNED" | "NO_CRITERIA" | "UNREADABLE";
|
|
234
|
+
|
|
235
|
+
export interface SpecPlacement {
|
|
236
|
+
/** Repo-relative, as the sweep spells it. */
|
|
237
|
+
path: string;
|
|
238
|
+
state: PlacementState;
|
|
239
|
+
/** Why it is not PLANNED. Empty exactly when it is. */
|
|
240
|
+
reasons: string[];
|
|
241
|
+
/** How many criteria the spec states, and how many the table places. */
|
|
242
|
+
criteria: number;
|
|
243
|
+
placed: number;
|
|
244
|
+
/** The spec declares `board-scope: deferred` in its frontmatter — SC-2734. */
|
|
245
|
+
deferred: boolean;
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* Whether a spec holds itself back from the board — SC-2734.
|
|
250
|
+
*
|
|
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.
|
|
254
|
+
*/
|
|
255
|
+
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]!);
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
export interface PlacementCoverage {
|
|
262
|
+
/** UNMEASURED FAILS. An empty list from a sweep that failed is not a clean one. */
|
|
263
|
+
reading: "MEASURED" | "UNMEASURED";
|
|
264
|
+
unmeasuredReasons: string[];
|
|
265
|
+
/** Every spec the sweep located, in its order. */
|
|
266
|
+
specs: SpecPlacement[];
|
|
267
|
+
/** The paths in each state, so a caller reports names rather than a count. */
|
|
268
|
+
planned: string[];
|
|
269
|
+
unplanned: string[];
|
|
270
|
+
noCriteria: string[];
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
/** THE one way out of {@link placementCoverage} without a reading. */
|
|
274
|
+
function unmeasuredCoverage(reasons: string[]): PlacementCoverage {
|
|
275
|
+
return { reading: "UNMEASURED", unmeasuredReasons: reasons, specs: [], planned: [], unplanned: [], noCriteria: [] };
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/**
|
|
279
|
+
* Every spec in the tree, and whether its criteria are placed — SC-2611.
|
|
280
|
+
*
|
|
281
|
+
* **The gap this closes.** {@link placementReading} answers the question for
|
|
282
|
+
* ONE spec, and both of its callers are given a spec on the command line. So
|
|
283
|
+
* a spec with no `### Phase placement` table contributed nothing to any
|
|
284
|
+
* repository-wide view: it had no phases, so it raised no milestone, so it
|
|
285
|
+
* appeared in no lane. 1 of 26 specs had a table on 2026-10-29 and the other
|
|
286
|
+
* 25 were indistinguishable from specs with no work left — which is the
|
|
287
|
+
* flattering reading of the two, and the wrong one.
|
|
288
|
+
*
|
|
289
|
+
* **`NO_CRITERIA` is separate from `UNPLANNED` deliberately.** A spec that
|
|
290
|
+
* states nothing to place genuinely has no work in it; a spec that states
|
|
291
|
+
* twelve criteria and places none has twelve. Folding them together
|
|
292
|
+
* reproduces the defect one level up — the count would be honest and the
|
|
293
|
+
* reader still could not act on it.
|
|
294
|
+
*
|
|
295
|
+
* **One unreadable spec makes the whole reading UNMEASURED**, not a shorter
|
|
296
|
+
* list: a shorter list is exactly what a tree with fewer specs produces. The
|
|
297
|
+
* spec is still carried in `specs` as `UNREADABLE` so the reason names it.
|
|
298
|
+
*
|
|
299
|
+
* The enumeration is `listSpecs`, not a second directory walk. `specs/` is
|
|
300
|
+
* already swept in one place, and a second walk is a second decider for
|
|
301
|
+
* "which files are specs" that no behavioural test of either could separate
|
|
302
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`).
|
|
303
|
+
*/
|
|
304
|
+
export function placementCoverage(
|
|
305
|
+
root: string,
|
|
306
|
+
listSpecs: (root: string) => { reading: "MEASURED" | "UNMEASURED"; unmeasuredReasons: string[]; paths: string[] },
|
|
307
|
+
readSpec: (root: string, path: string) => string,
|
|
308
|
+
): PlacementCoverage {
|
|
309
|
+
const sweep = listSpecs(root);
|
|
310
|
+
if (sweep.reading === "UNMEASURED") {
|
|
311
|
+
return unmeasuredCoverage([
|
|
312
|
+
`the specs/ sweep could not be taken, so nothing below is a reading of this tree: ` +
|
|
313
|
+
sweep.unmeasuredReasons.join("; "),
|
|
314
|
+
]);
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
const specs: SpecPlacement[] = [];
|
|
318
|
+
const reasons: string[] = [];
|
|
319
|
+
for (const path of sweep.paths) {
|
|
320
|
+
let content: string;
|
|
321
|
+
try {
|
|
322
|
+
content = readSpec(root, path);
|
|
323
|
+
} catch (e) {
|
|
324
|
+
specs.push({ path, state: "UNREADABLE", reasons: [(e as Error).message], criteria: 0, placed: 0, deferred: false });
|
|
325
|
+
reasons.push(`could not read ${path}: ${(e as Error).message}`);
|
|
326
|
+
continue;
|
|
327
|
+
}
|
|
328
|
+
const r = placementReading(content);
|
|
329
|
+
const placed = r.criteria.length - r.unplaced.length;
|
|
330
|
+
const state: PlacementState =
|
|
331
|
+
r.criteria.length === 0 ? "NO_CRITERIA" : r.reading === "MEASURED" ? "PLANNED" : "UNPLANNED";
|
|
332
|
+
specs.push({
|
|
333
|
+
path,
|
|
334
|
+
state,
|
|
335
|
+
reasons: state === "PLANNED" ? [] : r.unmeasuredReasons,
|
|
336
|
+
criteria: r.criteria.length,
|
|
337
|
+
placed,
|
|
338
|
+
deferred: declaresDeferred(content),
|
|
339
|
+
});
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
if (reasons.length > 0) {
|
|
343
|
+
// Carry the per-spec rows: the refusal has to be able to NAME the file.
|
|
344
|
+
return { ...unmeasuredCoverage(reasons), specs };
|
|
345
|
+
}
|
|
346
|
+
return {
|
|
347
|
+
reading: "MEASURED",
|
|
348
|
+
unmeasuredReasons: [],
|
|
349
|
+
specs,
|
|
350
|
+
planned: specs.filter(s => s.state === "PLANNED").map(s => s.path),
|
|
351
|
+
unplanned: specs.filter(s => s.state === "UNPLANNED").map(s => s.path),
|
|
352
|
+
noCriteria: specs.filter(s => s.state === "NO_CRITERIA").map(s => s.path),
|
|
353
|
+
};
|
|
354
|
+
}
|
|
355
|
+
|
|
206
356
|
/** One criterion, and what the board says about it — item **B2**. */
|
|
207
357
|
export interface CriterionCoverage {
|
|
208
358
|
id: string;
|
|
@@ -338,12 +488,34 @@ export function milestoneBody(criteria: string[]): string {
|
|
|
338
488
|
* A live milestone whose title carries no `Phase N` for this prefix is left
|
|
339
489
|
* alone and reported by the caller, not deleted. `Convergence Machinery` is
|
|
340
490
|
* the live instance: real, in use, and derived from nothing here.
|
|
491
|
+
*
|
|
492
|
+
* ## `renameFrom`: moving a whole family to a new name (#2124)
|
|
493
|
+
*
|
|
494
|
+
* Without it, renaming the family in config plans a CREATE per phase, and
|
|
495
|
+
* every issue stays in the old milestones, now unmanaged. With it, a phase
|
|
496
|
+
* that has no milestone in `prefix` takes the one `renameFrom` holds for that
|
|
497
|
+
* phase as its existing milestone. The action is then a rename that keeps
|
|
498
|
+
* the milestone number, so every issue keeps its lane. Only the table's
|
|
499
|
+
* phases are adopted; an old-family milestone for any other phase stays
|
|
500
|
+
* unmanaged.
|
|
501
|
+
*
|
|
502
|
+
* A phase both families hold is a `conflict`. Neither milestone is picked,
|
|
503
|
+
* because either pick strands the other's issues. The caller refuses.
|
|
341
504
|
*/
|
|
505
|
+
export interface FamilyConflict {
|
|
506
|
+
phase: number;
|
|
507
|
+
/** The milestone already in the family being written. */
|
|
508
|
+
current: LiveMilestone;
|
|
509
|
+
/** The milestone in the family being renamed from. */
|
|
510
|
+
previous: LiveMilestone;
|
|
511
|
+
}
|
|
512
|
+
|
|
342
513
|
export function milestonePlan(
|
|
343
514
|
content: string,
|
|
344
515
|
live: LiveMilestone[],
|
|
345
516
|
prefix: string,
|
|
346
|
-
|
|
517
|
+
renameFrom?: string,
|
|
518
|
+
): { actions: MilestoneAction[]; unmanaged: LiveMilestone[]; conflicts: FamilyConflict[] } {
|
|
347
519
|
const headings = new Map(parsePhaseHeadings(content).map(h => [h.number, h]));
|
|
348
520
|
const rows = parsePlacementRows(content);
|
|
349
521
|
const byPhase = new Map<number, string[]>();
|
|
@@ -358,13 +530,31 @@ export function milestonePlan(
|
|
|
358
530
|
const n = phaseOf(l.title);
|
|
359
531
|
if (n !== null) liveByPhase.set(n, l);
|
|
360
532
|
}
|
|
533
|
+
const previousByPhase = new Map<number, LiveMilestone>();
|
|
534
|
+
if (renameFrom !== undefined) {
|
|
535
|
+
for (const l of live) {
|
|
536
|
+
const n = phaseInFamily(l.title, renameFrom);
|
|
537
|
+
if (n !== null && byPhase.has(n)) previousByPhase.set(n, l);
|
|
538
|
+
}
|
|
539
|
+
}
|
|
540
|
+
const conflicts: FamilyConflict[] = [];
|
|
541
|
+
for (const [phase, previous] of previousByPhase) {
|
|
542
|
+
const current = liveByPhase.get(phase);
|
|
543
|
+
if (current) conflicts.push({ phase, current, previous });
|
|
544
|
+
}
|
|
545
|
+
// Adopted means USED as a phase's existing milestone. A conflicting phase
|
|
546
|
+
// keeps its current-family milestone, so its old one is in no action and
|
|
547
|
+
// must stay in `unmanaged` rather than vanish (review of #2126).
|
|
548
|
+
const adopted = new Set(
|
|
549
|
+
[...previousByPhase].filter(([phase]) => !liveByPhase.has(phase)).map(([, m]) => m.number),
|
|
550
|
+
);
|
|
361
551
|
|
|
362
552
|
const actions = [...byPhase.keys()]
|
|
363
553
|
.sort((a, b) => a - b)
|
|
364
554
|
.map((phase): MilestoneAction => {
|
|
365
555
|
const heading = headings.get(phase);
|
|
366
556
|
const title = `${prefix} ${heading ? heading.heading : `Phase ${phase}`}`;
|
|
367
|
-
const existing = liveByPhase.get(phase);
|
|
557
|
+
const existing = liveByPhase.get(phase) ?? previousByPhase.get(phase);
|
|
368
558
|
const criteria = byPhase.get(phase) ?? [];
|
|
369
559
|
if (!existing) return { title, phase, criteria, action: "create" };
|
|
370
560
|
// Both halves of what `--write` would put there, so `unchanged` means
|
|
@@ -383,11 +573,11 @@ export function milestonePlan(
|
|
|
383
573
|
};
|
|
384
574
|
});
|
|
385
575
|
|
|
386
|
-
return {
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
576
|
+
return {
|
|
577
|
+
actions,
|
|
578
|
+
unmanaged: live.filter(l => phaseOf(l.title) === null && !adopted.has(l.number)),
|
|
579
|
+
conflicts: conflicts.sort((a, b) => a.phase - b.phase),
|
|
580
|
+
};
|
|
391
581
|
}
|
|
392
582
|
|
|
393
583
|
/**
|
package/lib/spec-registry.ts
CHANGED
|
@@ -8,6 +8,14 @@
|
|
|
8
8
|
* conformity.ts, spec-validators.ts). This module centralizes the contract
|
|
9
9
|
* so doc-hygiene, scaffold, and gate enforcement share one source of truth.
|
|
10
10
|
*
|
|
11
|
+
* #1692 and #1906 finished that for the two that DECIDE: `governsOf` is the
|
|
12
|
+
* one extractor and `isValidGoverns` the one predicate, and `HYGIENE-1` in
|
|
13
|
+
* `lib/conformity.ts` calls both. This module holds no frontmatter parser of
|
|
14
|
+
* its own, and `test/governs-folded-scalar.test.ts` asserts that rather than
|
|
15
|
+
* leaving it to this sentence. `scanner.ts` and `spec-validators.ts` still
|
|
16
|
+
* extract their own; they render text and compose a warning, and neither
|
|
17
|
+
* decides whether a spec is governed.
|
|
18
|
+
*
|
|
11
19
|
* Issue: #24
|
|
12
20
|
*/
|
|
13
21
|
|
|
@@ -24,26 +32,77 @@ export interface SpecEntry {
|
|
|
24
32
|
}
|
|
25
33
|
|
|
26
34
|
/**
|
|
27
|
-
*
|
|
28
|
-
*
|
|
35
|
+
* A YAML block-scalar header, which is what a line-based frontmatter reader
|
|
36
|
+
* captures when the value is folded onto the lines below it.
|
|
37
|
+
*
|
|
38
|
+
* `>` folds, `|` keeps newlines, either may carry a chomping indicator
|
|
39
|
+
* (`-`/`+`) and an explicit indentation digit, in either order, and either
|
|
40
|
+
* may be followed by a comment. The class is deliberately a touch wider than
|
|
41
|
+
* YAML — `>--` is not legal YAML and is not governs text either, and a
|
|
42
|
+
* detector narrower than the syntax it detects is the defect in #1692, not
|
|
43
|
+
* the fix for it.
|
|
44
|
+
*
|
|
45
|
+
* The comment is matched here rather than stripped beforehand, so a `#` in
|
|
46
|
+
* real governs text — "the # anchor parser" — is never cut: nothing is
|
|
47
|
+
* removed unless what precedes it is already a block header.
|
|
29
48
|
*/
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
49
|
+
const BLOCK_SCALAR_HEADER = /^[>|][0-9+-]{0,2}(\s+#.*)?$/;
|
|
50
|
+
|
|
51
|
+
/** The frontmatter block: everything between the opening and closing `---`. */
|
|
52
|
+
const FRONTMATTER = /^---\n([\s\S]*?)\n---/;
|
|
53
|
+
|
|
54
|
+
/** A `governs:` line at column 0, and whatever follows it on that line. */
|
|
55
|
+
const GOVERNS_LINE = /^governs:[ \t]*(.*)$/m;
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* The inline text of a document's `governs:` field — the one extractor.
|
|
59
|
+
*
|
|
60
|
+
* Returns `undefined` when the document declares no `governs` at all, and
|
|
61
|
+
* the empty string when it declares one whose value is not on that line.
|
|
62
|
+
* Those are different facts and both callers need to tell them apart.
|
|
63
|
+
*
|
|
64
|
+
* Deliberately reads the inline text ONLY. Raised in review of #1906: the
|
|
65
|
+
* two callers used to extract `governs` with two different frontmatter
|
|
66
|
+
* parsers, and on a bare `governs:` with the text indented below,
|
|
67
|
+
* `lib/conformity.ts`'s flattened the continuation lines and joined them
|
|
68
|
+
* with `"; "` while `lib/spec-registry.ts`'s never set the key — so
|
|
69
|
+
* HYGIENE-1 called the spec governed and `getUngoverned` called the same
|
|
70
|
+
* spec ungoverned, in the same run. Unifying the predicate had not fixed
|
|
71
|
+
* that, because the disagreement was upstream of the predicate.
|
|
72
|
+
*
|
|
73
|
+
* A value on the lines below is therefore absent to both readers rather
|
|
74
|
+
* than present and different. That is the same decision #1692 made about
|
|
75
|
+
* the folded form, applied to the shape that has no indicator: `governs`
|
|
76
|
+
* is one line, and anything else is refused rather than guessed at.
|
|
77
|
+
*/
|
|
78
|
+
export function governsOf(content: string): string | undefined {
|
|
79
|
+
const fm = FRONTMATTER.exec(content);
|
|
80
|
+
if (!fm) return undefined;
|
|
81
|
+
const line = GOVERNS_LINE.exec(fm[1]);
|
|
82
|
+
return line ? line[1].trim() : undefined;
|
|
39
83
|
}
|
|
40
84
|
|
|
41
85
|
/**
|
|
42
|
-
* Check if a governs field value is valid (non-empty, not TODO
|
|
86
|
+
* Check if a governs field value is valid (non-empty, not TODO, not a
|
|
87
|
+
* folded block whose text this reader never saw).
|
|
88
|
+
*
|
|
89
|
+
* #1692: `governs: >-` with the prose on the indented lines below parses to
|
|
90
|
+
* the two characters `">-"` in every line-based reader in this tree. That is
|
|
91
|
+
* non-empty and contains no `TODO`, so it used to pass here and in
|
|
92
|
+
* `HYGIENE-1` while `lib/scanner.ts` dropped it for being under six
|
|
93
|
+
* characters and rendered a blank routing row. A folded `governs` is
|
|
94
|
+
* REFUSED rather than supported: all specs state it on one line, and
|
|
95
|
+
* supporting it means a reader that knows how `>` and `|` join their lines,
|
|
96
|
+
* which nothing here needs.
|
|
97
|
+
*
|
|
98
|
+
* `lib/conformity.ts`'s HYGIENE-1 calls this, over a value `governsOf`
|
|
99
|
+
* extracted. One extractor and one predicate — two copies of either is what
|
|
100
|
+
* let the disagreement sit unnoticed.
|
|
43
101
|
*/
|
|
44
|
-
function isValidGoverns(governs: string | undefined): governs is string {
|
|
102
|
+
export function isValidGoverns(governs: string | undefined): governs is string {
|
|
45
103
|
if (!governs) return false;
|
|
46
104
|
const trimmed = governs.trim();
|
|
105
|
+
if (BLOCK_SCALAR_HEADER.test(trimmed)) return false;
|
|
47
106
|
return trimmed.length > 0 && !trimmed.includes('TODO');
|
|
48
107
|
}
|
|
49
108
|
|
|
@@ -73,13 +132,13 @@ function scanSpecDir(dir: string, prefix: string = ''): { governed: SpecEntry[];
|
|
|
73
132
|
|
|
74
133
|
const filePath = join(dir, entry.name);
|
|
75
134
|
const content = readFileSync(filePath, 'utf-8');
|
|
76
|
-
const
|
|
135
|
+
const governs = governsOf(content); // #1906 — the one extractor
|
|
77
136
|
const relFile = prefix ? `${prefix}/${entry.name}` : entry.name;
|
|
78
137
|
|
|
79
|
-
if (
|
|
138
|
+
if (isValidGoverns(governs)) {
|
|
80
139
|
governed.push({
|
|
81
140
|
file: relFile,
|
|
82
|
-
governs
|
|
141
|
+
governs,
|
|
83
142
|
path: filePath,
|
|
84
143
|
});
|
|
85
144
|
} else {
|