rungate 0.6.0 → 0.7.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/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +81 -16
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +93 -14
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +17 -0
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +191 -17
- package/lib/config-loader.ts +39 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1087 -100
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/create-sc.ts +249 -16
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/evidence-prevalidator.ts +224 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +157 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/generators/agents-md.ts +140 -32
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +52 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-id-cross-tree.ts +19 -7
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4661 -64
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +152 -45
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/steps.ts +1413 -244
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +4 -0
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +43 -51
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +241 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-suite-lock.ts +159 -16
- package/lib/tool-probe.ts +31 -9
- package/lib/top-level-cd.ts +393 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/create-sc.ts +21 -1
- package/scripts/extract-constraints.ts +107 -7
- package/scripts/generate-code-map.ts +23 -30
- package/scripts/scaffold-project.ts +8 -1
- package/scripts/sync-sc-status.ts +77 -16
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* workflow-census.ts — what is in `.github/workflows/`, and who wrote it.
|
|
3
|
+
*
|
|
4
|
+
* The harness owns the `test` job in `ci.yml` and the `gates` job in
|
|
5
|
+
* `gates.yml`. It has never owned a workflow FILE, and the owned-path list in
|
|
6
|
+
* `.claude/rules/harness-managed.md` is a list of files the generator writes —
|
|
7
|
+
* so a file the generator did not write could not be added to it without the
|
|
8
|
+
* generator then producing it, and was therefore invisible (#722). A consumer
|
|
9
|
+
* with rungate scaffolded into it ran five gh-aw workflows that cost money,
|
|
10
|
+
* failed on quota and emailed its owner, and every scaffold run reported clean.
|
|
11
|
+
*
|
|
12
|
+
* Ownership here is a property of the BYTES, not of a list in another file.
|
|
13
|
+
* `.claude/rules/*.md` have worked this way since #370: the generator stamps a
|
|
14
|
+
* digest of what it wrote, and the next run asks the file itself. The marker
|
|
15
|
+
* is a YAML comment, so it is invisible to anything that parses the workflow
|
|
16
|
+
* and visible to anything that reads the text.
|
|
17
|
+
*
|
|
18
|
+
* marker present, digest matches the body → generated-and-unchanged
|
|
19
|
+
* marker present, digest does not match → generated-and-hand-edited
|
|
20
|
+
* no marker → NOT-OWNED
|
|
21
|
+
*
|
|
22
|
+
* ## Why `reading` is a field
|
|
23
|
+
*
|
|
24
|
+
* A directory that could not be read yields zero NOT-OWNED files. So does a
|
|
25
|
+
* directory in which every file is owned. Those are the same output and
|
|
26
|
+
* opposite facts, and a caller inferring "clean" from an empty array gets the
|
|
27
|
+
* #646 failure: the answer and the absence of an answer are byte-identical.
|
|
28
|
+
* `0`, `{}`, `null` and silence are indistinguishable from success;
|
|
29
|
+
* `UNMEASURED` is not.
|
|
30
|
+
*
|
|
31
|
+
* ## Why the coverage figure is rendered, not just returned
|
|
32
|
+
*
|
|
33
|
+
* `36/426` and `426/426` are the same PASS today — #492. A verdict that does
|
|
34
|
+
* not state how much of its subject it read cannot be told from a complete
|
|
35
|
+
* one by anybody downstream, so `read/present` goes in the line itself.
|
|
36
|
+
*
|
|
37
|
+
* This module REPORTS. It does not delete, rewrite or refuse anything in a
|
|
38
|
+
* consumer tree: what a consumer does with a NOT-OWNED workflow is theirs.
|
|
39
|
+
*/
|
|
40
|
+
import { readFileSync, readdirSync, statSync } from "fs";
|
|
41
|
+
import { join } from "path";
|
|
42
|
+
|
|
43
|
+
import { lineCommentProvenance } from "./owned-files";
|
|
44
|
+
|
|
45
|
+
// ── The marker ──────────────────────────────────────────
|
|
46
|
+
|
|
47
|
+
const YAML_COMMENT = lineCommentProvenance("#");
|
|
48
|
+
|
|
49
|
+
/** Stamp a generated workflow so the next run can recognise its own output. */
|
|
50
|
+
export const stampWorkflow = YAML_COMMENT.stamp;
|
|
51
|
+
|
|
52
|
+
/** The digest a workflow file declares, or null if it carries no marker. */
|
|
53
|
+
export const workflowMarker = YAML_COMMENT.declared;
|
|
54
|
+
|
|
55
|
+
/** The digest the file's body actually hashes to. */
|
|
56
|
+
export const workflowBodySha = YAML_COMMENT.sha;
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* The workflow without its provenance marker (#767).
|
|
60
|
+
*
|
|
61
|
+
* The marker is harness bookkeeping, and `resolveManagedWrite` treats every
|
|
62
|
+
* line outside a job as the consumer's. Those two facts met in #722 and the
|
|
63
|
+
* merge began refusing its own first line — *"1 line(s) the harness did not
|
|
64
|
+
* author would be dropped from content outside any job"* — so a generator
|
|
65
|
+
* change could not land on any workflow holding a preserved job.
|
|
66
|
+
*/
|
|
67
|
+
export const workflowBody = YAML_COMMENT.body;
|
|
68
|
+
|
|
69
|
+
// ── The reading ─────────────────────────────────────────
|
|
70
|
+
|
|
71
|
+
export type WorkflowStatus =
|
|
72
|
+
/** The harness wrote it and nobody has touched it since. */
|
|
73
|
+
| "generated-and-unchanged"
|
|
74
|
+
/** The harness wrote it and the bytes have moved. Preserved, not rewritten. */
|
|
75
|
+
| "generated-and-hand-edited"
|
|
76
|
+
/** No marker: the harness did not write this and does not manage it. */
|
|
77
|
+
| "NOT-OWNED";
|
|
78
|
+
|
|
79
|
+
export interface WorkflowFinding {
|
|
80
|
+
/** File name within `.github/workflows`, e.g. `issue-triage.lock.yml`. */
|
|
81
|
+
name: string;
|
|
82
|
+
status: WorkflowStatus;
|
|
83
|
+
/** Why this status, in the census's own words. */
|
|
84
|
+
detail: string;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
export interface WorkflowCensus {
|
|
88
|
+
reading: "MEASURED" | "UNMEASURED";
|
|
89
|
+
/** Named causes. Empty exactly when `reading` is MEASURED. */
|
|
90
|
+
unmeasuredReasons: string[];
|
|
91
|
+
files: WorkflowFinding[];
|
|
92
|
+
/** Projection of `files` — NOT-OWNED names, individually (AC-3). */
|
|
93
|
+
notOwned: string[];
|
|
94
|
+
/** How much of the subject was read. `read < present` is a partial scan. */
|
|
95
|
+
coverage: { read: number; present: number };
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
const WORKFLOW_EXT = /\.ya?ml$/i;
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Read `.github/workflows/` and classify every file in it.
|
|
102
|
+
*
|
|
103
|
+
* One exported function, so there is one binding to mutate, and `reading` is
|
|
104
|
+
* derived here and nowhere else — a second boolean beside it would always
|
|
105
|
+
* agree with it, and two deciders that agree are behaviourally one.
|
|
106
|
+
*/
|
|
107
|
+
export function workflowCensus(root: string): WorkflowCensus {
|
|
108
|
+
const dir = join(root, ".github", "workflows");
|
|
109
|
+
const reasons: string[] = [];
|
|
110
|
+
|
|
111
|
+
let entries: string[];
|
|
112
|
+
try {
|
|
113
|
+
if (!statSync(dir).isDirectory()) {
|
|
114
|
+
return census([`WORKFLOWS_DIR_ABSENT: ${dir} is not a directory`], [], 0);
|
|
115
|
+
}
|
|
116
|
+
entries = readdirSync(dir).filter(n => WORKFLOW_EXT.test(n)).sort();
|
|
117
|
+
} catch (e) {
|
|
118
|
+
// An absent directory is deliberately UNMEASURED rather than a measured
|
|
119
|
+
// zero. Every scaffolded project has one — the generator creates it — so
|
|
120
|
+
// its absence means this scan is looking somewhere the workflows are not,
|
|
121
|
+
// which is exactly the reading #646 was about.
|
|
122
|
+
const why = (e as NodeJS.ErrnoException).code === "ENOENT"
|
|
123
|
+
? `WORKFLOWS_DIR_ABSENT: ${dir}`
|
|
124
|
+
: `WORKFLOWS_DIR_UNREADABLE: ${dir} — ${(e as Error).message}`;
|
|
125
|
+
return census([why], [], 0);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
const files: WorkflowFinding[] = [];
|
|
129
|
+
for (const name of entries) {
|
|
130
|
+
let text: string;
|
|
131
|
+
try {
|
|
132
|
+
text = readFileSync(join(dir, name), "utf-8");
|
|
133
|
+
} catch (e) {
|
|
134
|
+
// Not owned and not unowned: both are claims about bytes nobody read.
|
|
135
|
+
reasons.push(`UNREADABLE_WORKFLOW: ${name} — ${(e as Error).message}`);
|
|
136
|
+
continue;
|
|
137
|
+
}
|
|
138
|
+
files.push(classify(name, text));
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
return census(reasons, files, entries.length);
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* The only place a `WorkflowCensus` is constructed.
|
|
146
|
+
*
|
|
147
|
+
* `reading`, `notOwned` and `coverage.read` are all PROJECTIONS of the two
|
|
148
|
+
* inputs, derived here and nowhere else. The first draft of this module set
|
|
149
|
+
* `reading` literally on the early-return path and computed it on the main
|
|
150
|
+
* path — two deciders answering one question, which no behavioural test can
|
|
151
|
+
* tell apart because they always agree
|
|
152
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape). One
|
|
153
|
+
* binding, so there is one thing to mutate.
|
|
154
|
+
*/
|
|
155
|
+
function census(reasons: string[], files: WorkflowFinding[], present: number): WorkflowCensus {
|
|
156
|
+
return {
|
|
157
|
+
reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
|
|
158
|
+
unmeasuredReasons: reasons,
|
|
159
|
+
files,
|
|
160
|
+
notOwned: files.filter(f => f.status === "NOT-OWNED").map(f => f.name),
|
|
161
|
+
coverage: { read: files.length, present },
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
function classify(name: string, text: string): WorkflowFinding {
|
|
166
|
+
const declared = workflowMarker(text);
|
|
167
|
+
if (declared === null) {
|
|
168
|
+
return {
|
|
169
|
+
name,
|
|
170
|
+
status: "NOT-OWNED",
|
|
171
|
+
detail: "no harness provenance marker — rungate did not write this file",
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
const actual = workflowBodySha(text);
|
|
175
|
+
if (declared === actual) {
|
|
176
|
+
return { name, status: "generated-and-unchanged", detail: "harness-written and untouched since" };
|
|
177
|
+
}
|
|
178
|
+
return {
|
|
179
|
+
name,
|
|
180
|
+
status: "generated-and-hand-edited",
|
|
181
|
+
detail: `hand-edited since the harness wrote it (declared ${declared}, body ${actual})`,
|
|
182
|
+
};
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
// ── The report ──────────────────────────────────────────
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* Render the census as scaffold `actions[]` lines.
|
|
189
|
+
*
|
|
190
|
+
* NOT-OWNED files are named one per line rather than counted. "5 unowned
|
|
191
|
+
* workflows" sends nobody anywhere; the five that cost a consumer money each
|
|
192
|
+
* have a name, and the name is the whole of what makes the line actionable.
|
|
193
|
+
*/
|
|
194
|
+
export function censusReport(census: WorkflowCensus): string[] {
|
|
195
|
+
const { read, present } = census.coverage;
|
|
196
|
+
const out: string[] = [
|
|
197
|
+
`WORKFLOWS: ${census.reading} — read ${read}/${present} file(s) in .github/workflows`,
|
|
198
|
+
];
|
|
199
|
+
|
|
200
|
+
for (const reason of census.unmeasuredReasons) {
|
|
201
|
+
out.push(` UNMEASURED: ${reason}`);
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
for (const f of census.files) {
|
|
205
|
+
if (f.status === "generated-and-unchanged") continue;
|
|
206
|
+
out.push(` ${f.status}: ${f.name} — ${f.detail}`);
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
if (census.notOwned.length > 0) {
|
|
210
|
+
out.push(
|
|
211
|
+
` NOT-OWNED workflows run in this repo's CI and rungate does not manage them. ` +
|
|
212
|
+
`Reported, not touched — what happens to them is yours: ${census.notOwned.join(", ")}`,
|
|
213
|
+
);
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
return out;
|
|
217
|
+
}
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* workflow-drift.ts — the consumer-facing reading of #722's census.
|
|
3
|
+
*
|
|
4
|
+
* #722 built `workflowCensus`, which can tell a generated workflow nobody has
|
|
5
|
+
* touched from one somebody hand-edited, and the stamp it reads has been on
|
|
6
|
+
* disk in consumer repos ever since. Nothing a consumer runs ever asked it
|
|
7
|
+
* (#915). So a hand-edit to a generated `ci.yml`, `gates.yml` or
|
|
8
|
+
* `ai-review.yml` was stamped, mechanically detectable, and undetected: the
|
|
9
|
+
* symptom somebody "fixed" by editing the workflow disappears, the generator
|
|
10
|
+
* keeps shipping the unfixed version, and the next `bunx rungate scaffold .`
|
|
11
|
+
* reverts the edit. Nothing reds at any point in that sequence.
|
|
12
|
+
*
|
|
13
|
+
* This module turns the census into a verdict. `lib/conformity.ts` wraps it
|
|
14
|
+
* as `runWorkflowDriftValidation`; the census itself is unchanged.
|
|
15
|
+
*
|
|
16
|
+
* ## Why a hand-edit is not automatically drift (#839, #917)
|
|
17
|
+
*
|
|
18
|
+
* `ci.workflowOverrides` lets a consumer name top-level keys they have taken
|
|
19
|
+
* back from the generator. `mergeManagedWorkflow` leaves a declined key
|
|
20
|
+
* exactly as they wrote it and writes a notice into the file saying which
|
|
21
|
+
* config key declined it. An edit inside such a key is **not** reverted by a
|
|
22
|
+
* re-scaffold, so reporting it as drift would be reporting the escape hatch
|
|
23
|
+
* as a defect — and a check that reds on the supported way to deviate is a
|
|
24
|
+
* check somebody deletes.
|
|
25
|
+
*
|
|
26
|
+
* The stamp covers the WHOLE body, so it can say the bytes moved and cannot
|
|
27
|
+
* say where. That is the honest limit of this reading and it is why there are
|
|
28
|
+
* three outcomes rather than two:
|
|
29
|
+
*
|
|
30
|
+
* hand-edited, no key in this file is the consumer's → DRIFTED. Every byte
|
|
31
|
+
* is the generator's, so the next scaffold reverts the edit.
|
|
32
|
+
* hand-edited, some key in this file IS the consumer's → UNMEASURED, with
|
|
33
|
+
* the keys named. The edit may be inside one of them or outside it, and
|
|
34
|
+
* a whole-body digest cannot tell. Reported loudly rather than waved
|
|
35
|
+
* through: `.claude/rules/config-access.md` — a silent pass here is
|
|
36
|
+
* Silent Default Substitution with the file on the consumer's side.
|
|
37
|
+
* NOT-OWNED → passing, and NAMED (#722 AC-3). A consumer's own workflows
|
|
38
|
+
* are theirs; "5 unowned workflows" sends nobody anywhere.
|
|
39
|
+
*
|
|
40
|
+
* ## Why zero files is not agreement
|
|
41
|
+
*
|
|
42
|
+
* A census over an empty `.github/workflows/` is MEASURED with no findings,
|
|
43
|
+
* which renders exactly like a repo whose three generated workflows are all
|
|
44
|
+
* untouched. That is #621's shape — N things agreeing vacuously — so a
|
|
45
|
+
* reading with nothing stamped in it to compare is UNMEASURED and says which
|
|
46
|
+
* of the two it is.
|
|
47
|
+
*/
|
|
48
|
+
import { readFileSync } from "fs";
|
|
49
|
+
import { join } from "path";
|
|
50
|
+
|
|
51
|
+
import { topLevelKeyOrder } from "./managed-workflow";
|
|
52
|
+
import { workflowCensus } from "./workflow-census";
|
|
53
|
+
|
|
54
|
+
export interface WorkflowDriftFinding {
|
|
55
|
+
/** File name within `.github/workflows`, e.g. `ai-review.yml`. */
|
|
56
|
+
name: string;
|
|
57
|
+
/** Why this verdict, in the reading's own words. */
|
|
58
|
+
detail: string;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export interface WorkflowDriftReading {
|
|
62
|
+
reading: "MEASURED" | "UNMEASURED";
|
|
63
|
+
/** Named causes. Empty exactly when `reading` is MEASURED. */
|
|
64
|
+
unmeasuredReasons: string[];
|
|
65
|
+
/** Hand-edited, and nothing in the file is the consumer's. The refusal. */
|
|
66
|
+
drifted: WorkflowDriftFinding[];
|
|
67
|
+
/** Hand-edited, and the consumer has declared part of this file theirs. */
|
|
68
|
+
consumerOwned: WorkflowDriftFinding[];
|
|
69
|
+
/** NOT-OWNED names, individually. Passing. */
|
|
70
|
+
notOwned: string[];
|
|
71
|
+
/**
|
|
72
|
+
* How much of the subject was read, and how much of what was read this
|
|
73
|
+
* check is even about. `read < present` is a partial scan; `generated === 0`
|
|
74
|
+
* is a scan with nothing to compare, which is not the same as a clean one.
|
|
75
|
+
*/
|
|
76
|
+
coverage: { read: number; present: number; generated: number };
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Read `.github/workflows/` and say whether a generated workflow has moved.
|
|
81
|
+
*
|
|
82
|
+
* `overrides` is `ci.workflowOverrides` as `workflowOverrides()` reads it —
|
|
83
|
+
* passed in rather than loaded here, so the config reader stays the one
|
|
84
|
+
* binding `.claude/rules/config-access.md` requires and this module stays
|
|
85
|
+
* free of a config path of its own.
|
|
86
|
+
*
|
|
87
|
+
* One exported reading, so there is one thing to mutate, and `reading` is
|
|
88
|
+
* derived here and nowhere else.
|
|
89
|
+
*/
|
|
90
|
+
export function workflowDrift(root: string, overrides: readonly string[] = []): WorkflowDriftReading {
|
|
91
|
+
const dir = join(root, ".github", "workflows");
|
|
92
|
+
const census = workflowCensus(root);
|
|
93
|
+
const reasons = [...census.unmeasuredReasons];
|
|
94
|
+
|
|
95
|
+
const generated = census.files.filter(f => f.status !== "NOT-OWNED");
|
|
96
|
+
if (census.coverage.present === 0) {
|
|
97
|
+
reasons.push(
|
|
98
|
+
`NO_WORKFLOW_FILES: ${dir} holds no workflow files — zero files agreeing is not agreement`,
|
|
99
|
+
);
|
|
100
|
+
} else if (generated.length === 0) {
|
|
101
|
+
reasons.push(
|
|
102
|
+
`NO_GENERATED_WORKFLOW: read ${census.coverage.read} file(s) in ${dir} and none carries a ` +
|
|
103
|
+
`harness provenance marker — there is nothing for a drift check to compare. ` +
|
|
104
|
+
`Run \`bunx rungate scaffold .\` if this project is meant to have generated CI`,
|
|
105
|
+
);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
const drifted: WorkflowDriftFinding[] = [];
|
|
109
|
+
const consumerOwned: WorkflowDriftFinding[] = [];
|
|
110
|
+
|
|
111
|
+
for (const file of generated) {
|
|
112
|
+
if (file.status !== "generated-and-hand-edited") continue;
|
|
113
|
+
|
|
114
|
+
let claimed: string[];
|
|
115
|
+
try {
|
|
116
|
+
claimed = consumerKeysIn(readFileSync(join(dir, file.name), "utf-8"), overrides);
|
|
117
|
+
} catch (e) {
|
|
118
|
+
// The census read this file a moment ago. A failure here is not "no
|
|
119
|
+
// keys are claimed" — that is a claim about bytes nobody read.
|
|
120
|
+
reasons.push(`UNREADABLE_WORKFLOW: ${file.name} — ${(e as Error).message}`);
|
|
121
|
+
continue;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
if (claimed.length === 0) {
|
|
125
|
+
drifted.push({
|
|
126
|
+
name: file.name,
|
|
127
|
+
detail:
|
|
128
|
+
`${file.detail}. No top-level key in this file is declared the consumer's, so ` +
|
|
129
|
+
`\`bunx rungate scaffold .\` will overwrite the edit. Make the change in the ` +
|
|
130
|
+
`generator, or name the key in \`ci.workflowOverrides\` to keep it`,
|
|
131
|
+
});
|
|
132
|
+
continue;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
consumerOwned.push({
|
|
136
|
+
name: file.name,
|
|
137
|
+
detail:
|
|
138
|
+
`${file.detail}, and ${claimed.join(", ")} ${claimed.length === 1 ? "is" : "are"} ` +
|
|
139
|
+
`declared the consumer's through \`ci.workflowOverrides\`. The provenance marker ` +
|
|
140
|
+
`digests the whole file, so it cannot say whether the edit landed inside a declared ` +
|
|
141
|
+
`key or outside one — UNMEASURED, not clean`,
|
|
142
|
+
});
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
return {
|
|
146
|
+
reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
|
|
147
|
+
unmeasuredReasons: reasons,
|
|
148
|
+
drifted,
|
|
149
|
+
consumerOwned,
|
|
150
|
+
notOwned: census.notOwned,
|
|
151
|
+
coverage: { read: census.coverage.read, present: census.coverage.present, generated: generated.length },
|
|
152
|
+
};
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* The top-level keys of one workflow that are the consumer's, not the
|
|
157
|
+
* generator's.
|
|
158
|
+
*
|
|
159
|
+
* One source: `ci.workflowOverrides`, intersected with the keys this file
|
|
160
|
+
* actually declares. The config is global and the question is per-file — a
|
|
161
|
+
* project declining `concurrency` has said nothing about a workflow that has
|
|
162
|
+
* no `concurrency:` in it, and treating the decline as covering that file
|
|
163
|
+
* would blind the check to every edit in it.
|
|
164
|
+
*
|
|
165
|
+
* ## Why the file's own override notices are NOT a second source (#958)
|
|
166
|
+
*
|
|
167
|
+
* They were, until #958: the notices `mergeManagedWorkflow` writes were read
|
|
168
|
+
* back and unioned in, with no reference to the config. A notice is a comment
|
|
169
|
+
* anybody can type, so that made the file under inspection the authority on
|
|
170
|
+
* its own exemption — paste one line into a hand-edited workflow and DRIFTED
|
|
171
|
+
* became consumerOwned. #530's shape: the artifact everyone reaches for as
|
|
172
|
+
* ground truth, which always agrees.
|
|
173
|
+
*
|
|
174
|
+
* #928 reasoned the notice source from #722's "ownership travels with the
|
|
175
|
+
* bytes". The analogy does not hold. `generated-sha:` is a digest OF the
|
|
176
|
+
* body — it cannot be written to say something the bytes do not; a notice
|
|
177
|
+
* carries no such binding.
|
|
178
|
+
*
|
|
179
|
+
* Nor does the case it was built for survive inspection. The justification
|
|
180
|
+
* was "a consumer who removed the key from the config but has not
|
|
181
|
+
* re-scaffolded still has a file whose bytes were authored under the
|
|
182
|
+
* decline." That is backwards: if the key is gone from the config the next
|
|
183
|
+
* scaffold RE-MERGES it, so the edit will be reverted — which is precisely
|
|
184
|
+
* what DRIFTED means. The config decides what the next scaffold does, and it
|
|
185
|
+
* is the only authority this reading should have.
|
|
186
|
+
*
|
|
187
|
+
* Hardening the notice branch rather than deleting it — accept a notice key
|
|
188
|
+
* only when the config names it too — is behaviourally identical to this,
|
|
189
|
+
* because the union then collapses to `{config ∩ declared}`. Same verdicts,
|
|
190
|
+
* one less branch, and one less thing a consumer can write.
|
|
191
|
+
*/
|
|
192
|
+
function consumerKeysIn(text: string, overrides: readonly string[]): string[] {
|
|
193
|
+
const declared = new Set(topLevelKeyOrder(text));
|
|
194
|
+
return overrides.filter(k => declared.has(k));
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* Render the reading as report lines.
|
|
199
|
+
*
|
|
200
|
+
* NOT-OWNED files are named one per line rather than counted, and the
|
|
201
|
+
* coverage figure is in the first line, for the reasons `censusReport` gives:
|
|
202
|
+
* `3/12` and `12/12` are the same verdict and no reader can tell them apart
|
|
203
|
+
* from the output.
|
|
204
|
+
*/
|
|
205
|
+
export function workflowDriftReport(reading: WorkflowDriftReading): string[] {
|
|
206
|
+
const { read, present, generated } = reading.coverage;
|
|
207
|
+
const out: string[] = [
|
|
208
|
+
`WORKFLOW DRIFT: ${reading.reading} — read ${read}/${present} file(s), ${generated} generated`,
|
|
209
|
+
];
|
|
210
|
+
for (const reason of reading.unmeasuredReasons) out.push(` UNMEASURED: ${reason}`);
|
|
211
|
+
for (const f of reading.drifted) out.push(` DRIFTED: ${f.name} — ${f.detail}`);
|
|
212
|
+
for (const f of reading.consumerOwned) out.push(` UNMEASURED: ${f.name} — ${f.detail}`);
|
|
213
|
+
if (reading.notOwned.length > 0) {
|
|
214
|
+
out.push(` NOT-OWNED, and not this check's business: ${reading.notOwned.join(", ")}`);
|
|
215
|
+
}
|
|
216
|
+
return out;
|
|
217
|
+
}
|
|
@@ -47,6 +47,7 @@ import {
|
|
|
47
47
|
addFrontmatterToSpecs, addFrontmatterToAdrs, detectOversizedSpecs,
|
|
48
48
|
checkGovernsAlignment, detectMisplacedSpecs, detectUnconvertedSpecs,
|
|
49
49
|
} from "../validators/spec-validators";
|
|
50
|
+
import { ensureConfigTrackable } from "../config-trackable";
|
|
50
51
|
import type { ProjectType } from "../generators/types";
|
|
51
52
|
import { DEFAULT_PROFILE, isStepIncluded, type ScaffoldProfile } from "./profiles";
|
|
52
53
|
|
|
@@ -93,6 +94,9 @@ export function runScaffoldWriteSteps(
|
|
|
93
94
|
|
|
94
95
|
// Phase 0: Security and directory setup
|
|
95
96
|
createGitignore(projectPath, actions);
|
|
97
|
+
// AFTER `createGitignore` and not before: the negation only works as the
|
|
98
|
+
// LAST matching rule, and `createGitignore` appends (#505).
|
|
99
|
+
ensureConfigTrackable(projectPath, actions);
|
|
96
100
|
safeDir(join(projectPath, "specs"), "specs", actions);
|
|
97
101
|
safeDir(join(projectPath, "reference"), "reference", actions);
|
|
98
102
|
safeDir(join(projectPath, ".github"), ".github", actions);
|