rungate 0.5.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 +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- 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 +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- 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 +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- 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/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- 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 +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -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/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -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-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- 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 +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- 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/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -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 +411 -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-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- 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/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- package/scripts/sync-spec-tests.ts +2 -1
package/lib/scaffold/steps.ts
CHANGED
|
@@ -7,30 +7,66 @@
|
|
|
7
7
|
* Extracted per SCAFFOLD-DECOMPOSITION-SPEC to keep scaffold-project.ts
|
|
8
8
|
* as orchestrator-only (under 200 lines).
|
|
9
9
|
*/
|
|
10
|
-
import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync,
|
|
10
|
+
import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, statSync } from "fs";
|
|
11
|
+
import { readdirSorted } from "../readdir-sorted";
|
|
11
12
|
import { join, basename, dirname } from "path";
|
|
12
13
|
import { auditSpecs } from "../../scripts/audit-specs";
|
|
13
14
|
import { generateAgentsMd as buildAgentsMdContent, generateScopedRules } from "../generators/agents-md";
|
|
14
15
|
import { isHarnessItself } from "../harness-identity";
|
|
16
|
+
import { scanSpecs } from "../scanner";
|
|
17
|
+
import { projectStateDerivation, projectStateKeyFileNote } from "../project-state-derivation";
|
|
15
18
|
import { generateAgentBriefs as buildAgentBriefsContent } from "../generators/agent-briefs";
|
|
16
19
|
import { generateCodeMap as buildCodeMapContent } from "../generators/code-map";
|
|
17
20
|
import { buildAgentMeta, DEFAULT_AGENT_META } from "../create-brief";
|
|
18
21
|
import { buildDefaultRoles, buildDefaultHooks } from "./defaults";
|
|
19
22
|
import {
|
|
20
|
-
|
|
23
|
+
mergeManagedWorkflowRecording,
|
|
21
24
|
duplicateTopLevelKeys,
|
|
25
|
+
managedPreamble,
|
|
26
|
+
MANAGED_BANNER_PREFIX,
|
|
22
27
|
movedTopLevelKeys,
|
|
28
|
+
WORKFLOW_OVERRIDE_COMMENT,
|
|
29
|
+
workflowOverrides,
|
|
30
|
+
type ComputedSubKeys,
|
|
31
|
+
type MergeProvenance,
|
|
23
32
|
type MovedKey,
|
|
33
|
+
type RevokedSubKey,
|
|
24
34
|
} from "./managed-workflow";
|
|
25
35
|
import { PRE_PUSH_MANAGED_MARKER, prePushHookScript } from "./pre-push-hook";
|
|
36
|
+
import {
|
|
37
|
+
AI_REVIEW_JOB,
|
|
38
|
+
aiReviewScaffoldAction,
|
|
39
|
+
buildAuthDetectStep,
|
|
40
|
+
buildOutcomesHeader,
|
|
41
|
+
buildReviewRunStep,
|
|
42
|
+
vertexCiConfig,
|
|
43
|
+
} from "./ai-review-step";
|
|
44
|
+
import { CI_SUITE_FETCH_DEPTH, baseRefFetchDepth } from "../ci-history-depth";
|
|
45
|
+
import { CLAUDE_CODE_ACTION } from "../claude-code-action";
|
|
46
|
+
import { GOOGLE_AUTH_ACTION } from "../google-auth-action";
|
|
26
47
|
import { loadComplianceConfig, tryLoadRungateConfig } from "../config-loader";
|
|
27
48
|
import { organizeProjectReport } from "../organize";
|
|
28
49
|
import type { ProjectScan, ProjectType, SpecEntry, TestFile, RefFile, DocRoute, Category } from "../generators/types";
|
|
29
|
-
import {
|
|
50
|
+
import {
|
|
51
|
+
TIER2_ALLOWED_VALUE_ERE,
|
|
52
|
+
TIER2_GREP_CASE_FLAG,
|
|
53
|
+
TIER3_ALLOWED_VALUE_ERE,
|
|
54
|
+
tier1Ere,
|
|
55
|
+
tier2Ere,
|
|
56
|
+
tier3Ere,
|
|
57
|
+
} from "../secret-patterns";
|
|
30
58
|
import { healthPathIn } from "../liveness-contradiction";
|
|
59
|
+
import { localCalendarDay } from "../local-calendar-day";
|
|
31
60
|
import { decideRuleWrite } from "../rule-provenance";
|
|
61
|
+
import { actionRef } from "../workflow-actions";
|
|
62
|
+
import { ciSetupStep } from "../ci-setup-step";
|
|
32
63
|
import { DEFAULT_PROFILE, isRuleIncluded, type ScaffoldProfile } from "./profiles";
|
|
33
64
|
import { referencedPaths } from "../agents-md-refs";
|
|
65
|
+
import { scanDocsDirectory } from "../doc-routing";
|
|
66
|
+
import { inferredTestCommand, testCommandDecision } from "../test-command";
|
|
67
|
+
import { declaredBunVersion, setupBunWith } from "../bun-version";
|
|
68
|
+
import { codeMapUnreferenced, unlistedSpecs } from "../spec-listing";
|
|
69
|
+
import { censusReport, stampWorkflow, workflowBody, workflowCensus } from "./workflow-census";
|
|
34
70
|
import {
|
|
35
71
|
readSuccessDoc,
|
|
36
72
|
readSuccessTemplate,
|
|
@@ -40,11 +76,12 @@ import {
|
|
|
40
76
|
} from "../success-doc";
|
|
41
77
|
import { TS_SOURCE_DIRS, typeScriptSourceDirs, typecheckDecision } from "../typescript-project";
|
|
42
78
|
import {
|
|
43
|
-
OWNED_FILES,
|
|
44
79
|
SCAFFOLD_REFUSE,
|
|
45
80
|
decideOwnedWrite,
|
|
81
|
+
ownedFileFor,
|
|
46
82
|
type WriteStrategy,
|
|
47
83
|
} from "./owned-files";
|
|
84
|
+
import type { SectionSpec } from "../agents-md-sections";
|
|
48
85
|
|
|
49
86
|
/**
|
|
50
87
|
* Look for a declared health route in the places a server declares one.
|
|
@@ -115,18 +152,23 @@ export function safeWrite(filePath: string, content: string, label: string, acti
|
|
|
115
152
|
* prose while being written by a helper that skips it.
|
|
116
153
|
*/
|
|
117
154
|
export function ownedStrategy(label: string): WriteStrategy {
|
|
118
|
-
for (const owned of OWNED_FILES) {
|
|
119
|
-
if (owned.path === label) return owned.strategy;
|
|
120
|
-
if (owned.path.includes("*")) {
|
|
121
|
-
const [prefix, suffix] = owned.path.split("*");
|
|
122
|
-
if (label.startsWith(prefix) && label.endsWith(suffix)) return owned.strategy;
|
|
123
|
-
}
|
|
124
|
-
}
|
|
125
155
|
// An unlisted file is regenerated. The direction this is allowed to be
|
|
126
156
|
// wrong in: a file nobody declared gets rewritten with the generator's
|
|
127
157
|
// own output, which is recoverable. Defaulting to create-only would make
|
|
128
158
|
// forgetting to declare a file look exactly like #208.
|
|
129
|
-
return "regenerate";
|
|
159
|
+
return ownedFileFor(label)?.strategy ?? "regenerate";
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* Which section of this label carries forward, from the declaration (#655).
|
|
164
|
+
*
|
|
165
|
+
* `undefined` for every strategy that preserves nothing, and for a
|
|
166
|
+
* `section-preserving` row that forgot to declare one — which
|
|
167
|
+
* `test/scaffold-ownership.test.ts` refuses, because reading it here would
|
|
168
|
+
* make the omission resolve to AGENTS.md's heading and look deliberate.
|
|
169
|
+
*/
|
|
170
|
+
export function ownedSections(label: string): SectionSpec | undefined {
|
|
171
|
+
return ownedFileFor(label)?.sections;
|
|
130
172
|
}
|
|
131
173
|
|
|
132
174
|
export function regenerateOwned(
|
|
@@ -177,7 +219,7 @@ export function regenerateOwned(
|
|
|
177
219
|
return;
|
|
178
220
|
}
|
|
179
221
|
const existing = link ? readFileSync(filePath, "utf-8") : null;
|
|
180
|
-
const decision = decideOwnedWrite(strategy, existing, content);
|
|
222
|
+
const decision = decideOwnedWrite(strategy, existing, content, ownedSections(label));
|
|
181
223
|
|
|
182
224
|
if (decision.action === "preserve") {
|
|
183
225
|
actions.push(
|
|
@@ -186,6 +228,15 @@ export function regenerateOwned(
|
|
|
186
228
|
);
|
|
187
229
|
return;
|
|
188
230
|
}
|
|
231
|
+
if (decision.action === "refuse") {
|
|
232
|
+
// Not the same thing as `preserve`, and the advice is the opposite:
|
|
233
|
+
// `preserve` means the file on disk is yours and the generator stood
|
|
234
|
+
// down, so deleting it accepts the generator. This means the generator
|
|
235
|
+
// cannot produce an output that keeps a promise the spec makes, and
|
|
236
|
+
// deleting the file would destroy exactly the content at issue.
|
|
237
|
+
actions.push(`${SCAFFOLD_REFUSE}: ${label} not written — ${decision.reason}`);
|
|
238
|
+
return;
|
|
239
|
+
}
|
|
189
240
|
if (decision.action === "unchanged") {
|
|
190
241
|
actions.push(`UNCHANGED: ${label} (${decision.reason})`);
|
|
191
242
|
return;
|
|
@@ -241,40 +292,6 @@ function loadHarnessConfig(root: string): any {
|
|
|
241
292
|
|
|
242
293
|
// ── AGENTS.md generation and updates ───────────────────────────
|
|
243
294
|
|
|
244
|
-
export function updateSpecsTable(agentsMdPath: string, actions: string[]): void {
|
|
245
|
-
if (!existsSync(agentsMdPath)) return;
|
|
246
|
-
const specsDir = join(dirname(agentsMdPath), "specs");
|
|
247
|
-
if (!existsSync(specsDir)) return;
|
|
248
|
-
|
|
249
|
-
const specFiles = readdirSync(specsDir).filter(f => f.endsWith(".md") && f !== "SPEC-TEMPLATE.md");
|
|
250
|
-
if (specFiles.length === 0) return;
|
|
251
|
-
|
|
252
|
-
const specRows: string[] = [];
|
|
253
|
-
for (const f of specFiles) {
|
|
254
|
-
const content = readFileSync(join(specsDir, f), "utf-8");
|
|
255
|
-
const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
|
|
256
|
-
let testable = "false";
|
|
257
|
-
let governs = f.replace(/\.md$/, "");
|
|
258
|
-
if (fmMatch) {
|
|
259
|
-
const tMatch = fmMatch[1].match(/testable:\s*(true|false)/);
|
|
260
|
-
if (tMatch) testable = tMatch[1];
|
|
261
|
-
const gMatch = fmMatch[1].match(/governs:\s*(.+)/);
|
|
262
|
-
if (gMatch) governs = gMatch[1].trim();
|
|
263
|
-
}
|
|
264
|
-
specRows.push(`| ${f} | ${governs} | ${testable === "true" ? "yes" : "no"} |`);
|
|
265
|
-
}
|
|
266
|
-
|
|
267
|
-
const existing = readFileSync(agentsMdPath, "utf-8");
|
|
268
|
-
const tablePattern = /(\|[^\n]*Spec[^\n]*\|\n\|[-| ]+\|\n)((?:\|[^\n]+\|\n)*)/;
|
|
269
|
-
const match = existing.match(tablePattern);
|
|
270
|
-
if (match) {
|
|
271
|
-
const newTable = match[1] + specRows.join("\n") + "\n";
|
|
272
|
-
const updated = existing.replace(tablePattern, newTable);
|
|
273
|
-
writeFileSync(agentsMdPath, updated);
|
|
274
|
-
actions.push("UPDATED: AGENTS.md specs table from frontmatter");
|
|
275
|
-
}
|
|
276
|
-
}
|
|
277
|
-
|
|
278
295
|
export function injectEnvironmentSection(root: string, actions: string[]): void {
|
|
279
296
|
const agentsMdPath = join(root, "AGENTS.md");
|
|
280
297
|
if (!existsSync(agentsMdPath)) return;
|
|
@@ -390,7 +407,7 @@ export function generateAgentsMdContent(
|
|
|
390
407
|
// Scan key files
|
|
391
408
|
const keyFiles: Array<{ file: string; what: string; when: string }> = [
|
|
392
409
|
{ file: "AGENTS.md", what: "Project entry point", when: "Always first" },
|
|
393
|
-
{ file: "PROJECT-STATE.md", what:
|
|
410
|
+
{ file: "PROJECT-STATE.md", what: projectStateKeyFileNote(projectStateDerivation(projectPath)), when: "Session start, always first after AGENTS.md" },
|
|
394
411
|
{ file: "project-state.json", what: "Source of truth for project status", when: "When editing state" },
|
|
395
412
|
];
|
|
396
413
|
const conditionalPatterns: Array<{ pattern: string; what: string; when: string }> = [
|
|
@@ -417,78 +434,36 @@ export function generateAgentsMdContent(
|
|
|
417
434
|
}
|
|
418
435
|
}
|
|
419
436
|
|
|
420
|
-
// Scan specs
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
let testable = "TODO";
|
|
430
|
-
if (fmMatch) {
|
|
431
|
-
const gMatch = fmMatch[1].match(/governs:\s*(.+)/);
|
|
432
|
-
if (gMatch && gMatch[1].trim() !== "TODO" && gMatch[1].trim().length > 5) {
|
|
433
|
-
governs = gMatch[1].trim().replace(/\|/g, "—").slice(0, 120);
|
|
434
|
-
}
|
|
435
|
-
const tMatch = fmMatch[1].match(/testable:\s*(.+)/);
|
|
436
|
-
if (tMatch) testable = tMatch[1].trim();
|
|
437
|
-
}
|
|
438
|
-
specEntries.push({ file: f, governs, testable });
|
|
439
|
-
}
|
|
440
|
-
|
|
441
|
-
// Also scan specs subdirectories
|
|
442
|
-
try {
|
|
443
|
-
const specSubDirs = readdirSync(specsDir, { withFileTypes: true })
|
|
444
|
-
.filter(d => d.isDirectory())
|
|
445
|
-
.map(d => d.name);
|
|
446
|
-
for (const sub of specSubDirs) {
|
|
447
|
-
const subPath = join(specsDir, sub);
|
|
448
|
-
const subFiles = readdirSync(subPath).filter(f => f.endsWith(".md") && f !== "INDEX.md");
|
|
449
|
-
if (subFiles.length > 0) {
|
|
450
|
-
const indexPath = join(subPath, "INDEX.md");
|
|
451
|
-
let groupGoverns = `${sub} (${subFiles.length} specs)`;
|
|
452
|
-
if (existsSync(indexPath)) {
|
|
453
|
-
const indexContent = readFileSync(indexPath, "utf-8");
|
|
454
|
-
const fmMatch = indexContent.match(/^---\n([\s\S]*?)\n---/);
|
|
455
|
-
if (fmMatch) {
|
|
456
|
-
const gMatch = fmMatch[1].match(/governs:\s*(.+)/);
|
|
457
|
-
if (gMatch && gMatch[1].trim().length > 5) {
|
|
458
|
-
groupGoverns = gMatch[1].trim().replace(/\|/g, "—").slice(0, 120);
|
|
459
|
-
}
|
|
460
|
-
}
|
|
461
|
-
}
|
|
462
|
-
specEntries.push({ file: `${sub}/ (${subFiles.length} specs)`, governs: groupGoverns, testable: "yes" });
|
|
463
|
-
}
|
|
464
|
-
}
|
|
465
|
-
} catch {}
|
|
466
|
-
}
|
|
437
|
+
// Scan specs — delegated to `lib/scanner.ts`, which is the one derivation.
|
|
438
|
+
// This function used to carry its own copy, and the copy drifted three
|
|
439
|
+
// times (#827): it never set `criteriaNone`, so `STATES NO CRITERIA` was
|
|
440
|
+
// dropped from every row that earned it; it hardcoded `testable: "yes"` on
|
|
441
|
+
// group rows, a word `scanner.ts` notes "means false to the code and true
|
|
442
|
+
// to a reader"; and it filtered spec files by name instead of `isSpecFile`,
|
|
443
|
+
// which is how #382's two scans disagreed about `SPEC-TEMPLATE.md`. All
|
|
444
|
+
// three were fixed in `scanner.ts` alone, because nobody knew this existed.
|
|
445
|
+
const specEntries: SpecEntry[] = scanSpecs(projectPath);
|
|
467
446
|
|
|
468
447
|
// Scan tests
|
|
469
448
|
const testDir = existsSync(join(projectPath, "test")) ? "test" : existsSync(join(projectPath, "tests")) ? "tests" : null;
|
|
470
449
|
const testEntries: TestFile[] = [];
|
|
471
450
|
if (testDir) {
|
|
472
|
-
for (const f of
|
|
451
|
+
for (const f of readdirSorted(join(projectPath, testDir)).filter(f => f.endsWith(".test.ts"))) {
|
|
473
452
|
const label = f.replace(".test.ts", "").replace(/-/g, " ");
|
|
474
453
|
testEntries.push({ label, file: f });
|
|
475
454
|
}
|
|
476
455
|
}
|
|
477
456
|
|
|
478
|
-
// Detect test command
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
|
|
483
|
-
if (pkg.scripts?.test) testCmd = pkg.scripts.test;
|
|
484
|
-
} catch {}
|
|
485
|
-
}
|
|
457
|
+
// Detect test command — through the one binding (#488). This copy read
|
|
458
|
+
// package.json and nothing else, so AGENTS.md's Commands row ignored a
|
|
459
|
+
// `dev.testCmd` the agent briefs honoured and CI ignored both.
|
|
460
|
+
const testCmd = testCommandDecision(projectPath).command;
|
|
486
461
|
|
|
487
462
|
// Scan reference files
|
|
488
463
|
const refDir = join(projectPath, "reference");
|
|
489
464
|
const refEntries: RefFile[] = [];
|
|
490
465
|
if (existsSync(refDir)) {
|
|
491
|
-
for (const f of
|
|
466
|
+
for (const f of readdirSorted(refDir)) {
|
|
492
467
|
refEntries.push({ file: f, what: "Historical reference" });
|
|
493
468
|
}
|
|
494
469
|
}
|
|
@@ -541,42 +516,23 @@ export function generateAgentsMdContent(
|
|
|
541
516
|
// Recursive — see the same fix in scanner.ts. This is a second copy of
|
|
542
517
|
// scanDocRouting and it is the one the scaffold actually calls, so the
|
|
543
518
|
// scanner fix alone changed no generated output at all (#91).
|
|
544
|
-
const files =
|
|
519
|
+
const files = readdirSorted(catPath, { recursive: true }).filter(f => f.endsWith(".md"));
|
|
545
520
|
docRouting.push({ need: `${cat.label} (${files.length} files)`, file: `${cat.dir}/` });
|
|
546
521
|
} else {
|
|
547
522
|
docRouting.push({ need: cat.label, file: `${cat.dir}/` });
|
|
548
523
|
actions.push(`WARN: ${cat.dir}/ listed in routing but directory does not exist`);
|
|
549
524
|
}
|
|
550
525
|
}
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
}
|
|
562
|
-
docRouting.push({ need, file: `docs/${f}` });
|
|
563
|
-
}
|
|
564
|
-
const subDirs = readdirSync(docsDir, { withFileTypes: true })
|
|
565
|
-
.filter(d => d.isDirectory() && !categories.some(c => c.dir === `docs/${d.name}`))
|
|
566
|
-
.map(d => d.name);
|
|
567
|
-
for (const sub of subDirs) {
|
|
568
|
-
const subPath = join(docsDir, sub);
|
|
569
|
-
const subFiles = readdirSync(subPath).filter(f => f.endsWith(".md"));
|
|
570
|
-
if (subFiles.length > 0) {
|
|
571
|
-
docRouting.push({ need: `${sub} (${subFiles.length} files)`, file: `docs/${sub}/` });
|
|
572
|
-
}
|
|
573
|
-
}
|
|
574
|
-
}
|
|
575
|
-
const filteredRouting = docRouting.filter(d => {
|
|
576
|
-
const slug = d.file.replace(/\.md$/, "").replace(/.*\//, "").toLowerCase().replace(/-/g, " ");
|
|
577
|
-
const needLower = d.need.toLowerCase();
|
|
578
|
-
return !needLower.startsWith(slug) || d.need.includes("—") || d.need.includes("(");
|
|
579
|
-
});
|
|
526
|
+
// Through the one binding (#617, #619). This was a complete second copy of
|
|
527
|
+
// `scanDocRouting`, with its own inline `governs:` regex — and it is the copy
|
|
528
|
+
// the scaffold actually calls, so a fix applied only to the scanner changes
|
|
529
|
+
// no generated output at all (#91).
|
|
530
|
+
docRouting.push(...scanDocsDirectory(docsDir, categories.map(c => c.dir)));
|
|
531
|
+
|
|
532
|
+
// The "filter to non-obvious mappings" is deleted here for the same reason
|
|
533
|
+
// as in lib/scanner.ts: it could only ever drop a top-level `docs/*.md`, and
|
|
534
|
+
// dropping those is #617. See lib/doc-routing.ts.
|
|
535
|
+
const filteredRouting = docRouting;
|
|
580
536
|
|
|
581
537
|
const consumers = harness?.consumers || [];
|
|
582
538
|
|
|
@@ -661,8 +617,14 @@ export function generateAgentsMdContent(
|
|
|
661
617
|
* Re-running the generator is safe and cheap: `generateAgentsMdContent` writes
|
|
662
618
|
* only the rules, and returns AGENTS.md content for its caller to write. The
|
|
663
619
|
* return value is discarded here on purpose — AGENTS.md has already been
|
|
664
|
-
* through `
|
|
665
|
-
*
|
|
620
|
+
* through `injectEnvironmentSection` by this point, and rewriting it would
|
|
621
|
+
* undo that.
|
|
622
|
+
*
|
|
623
|
+
* It used to say `updateSpecsTable` as well. That function ran immediately
|
|
624
|
+
* after the generator had rewritten AGENTS.md, edited an EXISTING table
|
|
625
|
+
* matched on a header row containing `Spec`, and the generator emits no such
|
|
626
|
+
* table — so the match never succeeded, the `if` had no `else`, and its
|
|
627
|
+
* action string never once appeared in a report. It is deleted (#382).
|
|
666
628
|
*/
|
|
667
629
|
export function refreshScopedRulesStep(
|
|
668
630
|
root: string,
|
|
@@ -724,19 +686,23 @@ export function refreshAgentsMd(root: string, type: ProjectType, actions: string
|
|
|
724
686
|
} catch (e: unknown) { console.warn('Staleness check failed for', ref, (e as Error).message); }
|
|
725
687
|
}
|
|
726
688
|
|
|
727
|
-
// Check specs table
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
689
|
+
// Check specs table.
|
|
690
|
+
//
|
|
691
|
+
// Across AGENTS.md AND `.claude/rules/`, because D-15 capped AGENTS.md at
|
|
692
|
+
// 100 lines and moved both tables there (#382). Asked of `lib/spec-listing.ts`
|
|
693
|
+
// rather than inline: this site had its own idea of what counts as a spec —
|
|
694
|
+
// every `.md` in `specs/`, including `SPEC-TEMPLATE.md` — and the routing
|
|
695
|
+
// generator had another, so the one entry that could never be listed
|
|
696
|
+
// anywhere was reported on every run.
|
|
697
|
+
const unlisted = unlistedSpecs(root);
|
|
698
|
+
if (unlisted.length > 0) {
|
|
699
|
+
issues.push(`UNLISTED specs: ${unlisted.join(", ")} (in specs/ but not in AGENTS.md or .claude/rules/)`);
|
|
735
700
|
}
|
|
736
701
|
|
|
737
|
-
// Check CODE-MAP.md reference
|
|
738
|
-
|
|
739
|
-
|
|
702
|
+
// Check CODE-MAP.md reference — same surfaces, same reason. It is named in
|
|
703
|
+
// the first row of `.claude/rules/docs-routing.md`.
|
|
704
|
+
if (codeMapUnreferenced(root)) {
|
|
705
|
+
issues.push("CODE-MAP.md exists but not referenced in AGENTS.md or .claude/rules/");
|
|
740
706
|
}
|
|
741
707
|
|
|
742
708
|
if (issues.length > 0 || staleFiles.length > 0) {
|
|
@@ -782,7 +748,7 @@ export function generateConformityTest(root?: string): string {
|
|
|
782
748
|
const from = root && isHarnessItself(root) ? "../lib/conformity" : "rungate/lib/conformity";
|
|
783
749
|
return `import { resolve } from "path";
|
|
784
750
|
import { afterAll } from "bun:test";
|
|
785
|
-
import { runScaffoldConformity, runSpecDiscovery, runSpecDrift, runDocHygiene, runFallowCheck, runAgentFileValidation, runDirectoryValidation, runPackageValidation, runTsconfigValidation, runConfigAccessValidation, runPromptConfigAccessValidation, runSuccessDocValidation, writeFindingsReport } from "${from}";
|
|
751
|
+
import { runScaffoldConformity, runSpecDiscovery, runSpecDrift, runDocHygiene, runFallowCheck, runAgentFileValidation, runDirectoryValidation, runPackageValidation, runTsconfigValidation, runConfigAccessValidation, runPromptConfigAccessValidation, runSuccessDocValidation, runAiReviewValidation, runBranchProtectionValidation, runWorkflowDriftValidation, writeFindingsReport } from "${from}";
|
|
786
752
|
|
|
787
753
|
const ROOT = resolve(import.meta.dir, "..");
|
|
788
754
|
|
|
@@ -798,6 +764,9 @@ runTsconfigValidation(ROOT);
|
|
|
798
764
|
runConfigAccessValidation(ROOT);
|
|
799
765
|
runPromptConfigAccessValidation(ROOT);
|
|
800
766
|
runSuccessDocValidation(ROOT);
|
|
767
|
+
runAiReviewValidation(ROOT);
|
|
768
|
+
runBranchProtectionValidation(ROOT);
|
|
769
|
+
runWorkflowDriftValidation(ROOT);
|
|
801
770
|
|
|
802
771
|
afterAll(() => writeFindingsReport(ROOT));
|
|
803
772
|
`;
|
|
@@ -805,7 +774,26 @@ afterAll(() => writeFindingsReport(ROOT));
|
|
|
805
774
|
|
|
806
775
|
// ── Agent briefs generation ────────────────────────────────────
|
|
807
776
|
|
|
808
|
-
export function generateAgentBriefsStep(
|
|
777
|
+
export function generateAgentBriefsStep(
|
|
778
|
+
root: string,
|
|
779
|
+
actions: string[],
|
|
780
|
+
opts: {
|
|
781
|
+
/**
|
|
782
|
+
* Where the brief templates live. Defaults to the harness's own
|
|
783
|
+
* `templates/agent-briefs/`, which is what every production caller
|
|
784
|
+
* wants and what makes the templates harness-wide (#655).
|
|
785
|
+
*
|
|
786
|
+
* The seam exists because the `section-preserving` refusal below can
|
|
787
|
+
* only fire when the GENERATED brief carries the project-owned heading
|
|
788
|
+
* itself, and no input `root` accepts can produce that — the identity
|
|
789
|
+
* extractor stops at the first `\n##` and the README fallback flattens
|
|
790
|
+
* newlines. Without a seam the refusal would be reachable in
|
|
791
|
+
* production and unreachable in a test, which is the shape
|
|
792
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` is about.
|
|
793
|
+
*/
|
|
794
|
+
templatesDir?: string;
|
|
795
|
+
} = {},
|
|
796
|
+
): void {
|
|
809
797
|
const agentsDir = join(root, ".claude", "agents");
|
|
810
798
|
safeDir(agentsDir, ".claude/agents", actions);
|
|
811
799
|
|
|
@@ -847,7 +835,7 @@ export function generateAgentBriefsStep(root: string, actions: string[]): void {
|
|
|
847
835
|
marcus: [], quinn: [], rook: [], serena: [], aditi: [], discovery: []
|
|
848
836
|
};
|
|
849
837
|
if (existsSync(promptsDir)) {
|
|
850
|
-
const promptFiles =
|
|
838
|
+
const promptFiles = readdirSorted(promptsDir).filter(f => f.endsWith(".md"));
|
|
851
839
|
for (const f of promptFiles) {
|
|
852
840
|
const content = readFileSync(join(promptsDir, f), "utf-8");
|
|
853
841
|
const lower = f.toLowerCase();
|
|
@@ -878,7 +866,8 @@ export function generateAgentBriefsStep(root: string, actions: string[]): void {
|
|
|
878
866
|
const consumers = harness?.consumers || [];
|
|
879
867
|
|
|
880
868
|
// Resolve templates directory relative to this module
|
|
881
|
-
const harnessTemplatesDir =
|
|
869
|
+
const harnessTemplatesDir =
|
|
870
|
+
opts.templatesDir ?? join(dirname(dirname(__dirname)), "templates", "agent-briefs");
|
|
882
871
|
|
|
883
872
|
// buildAgentMeta takes the whole harness config and reads .roles itself.
|
|
884
873
|
// Passing harness?.roles made it look for roles.roles, so every consumer's
|
|
@@ -910,7 +899,7 @@ export function generateAgentBriefsStep(root: string, actions: string[]): void {
|
|
|
910
899
|
identity: projectIdentity,
|
|
911
900
|
techStack: [],
|
|
912
901
|
repoUrl: "",
|
|
913
|
-
testCmd:
|
|
902
|
+
testCmd: testCommandDecision(root).command,
|
|
914
903
|
keyFiles: [],
|
|
915
904
|
specs: [],
|
|
916
905
|
testFiles: [],
|
|
@@ -937,8 +926,40 @@ export function generateAgentBriefsStep(root: string, actions: string[]): void {
|
|
|
937
926
|
|
|
938
927
|
for (const [agentName, content] of Object.entries(briefs)) {
|
|
939
928
|
const p = join(agentsDir, `${agentName}.md`);
|
|
940
|
-
|
|
941
|
-
|
|
929
|
+
const label = `.claude/agents/${agentName}.md`;
|
|
930
|
+
// #654. The probe is taken BEFORE the write it describes. Asked
|
|
931
|
+
// afterwards it is true on every path that reaches it — `writeFileSync`
|
|
932
|
+
// either succeeded, in which case the file is there, or threw, in which
|
|
933
|
+
// case this line never runs — so the `CREATED:` arm was unreachable and
|
|
934
|
+
// a consumer scaffolding for the first time was told its briefs were
|
|
935
|
+
// updated.
|
|
936
|
+
const existedBefore = existsSync(p);
|
|
937
|
+
|
|
938
|
+
// #655. The write used to be a bare `writeFileSync(p, content)` — no
|
|
939
|
+
// `decideOwnedWrite`, no strategy read, nothing. The row in
|
|
940
|
+
// `OWNED_FILES` said `regenerate` and a bare overwrite happens to
|
|
941
|
+
// behave like `regenerate`, so nothing ever disagreed and the
|
|
942
|
+
// declaration test could not see it: reading a strategy is not the same
|
|
943
|
+
// as honouring it. Flipping the row alone would have changed nothing
|
|
944
|
+
// here; this is the other half.
|
|
945
|
+
const existing = existedBefore ? readFileSync(p, "utf-8") : null;
|
|
946
|
+
const decision = decideOwnedWrite(
|
|
947
|
+
ownedStrategy(label),
|
|
948
|
+
existing,
|
|
949
|
+
content,
|
|
950
|
+
ownedSections(label),
|
|
951
|
+
);
|
|
952
|
+
|
|
953
|
+
if (decision.action === "refuse" || decision.action === "preserve") {
|
|
954
|
+
actions.push(`${SCAFFOLD_REFUSE}: ${label} not written — ${decision.reason}`);
|
|
955
|
+
continue;
|
|
956
|
+
}
|
|
957
|
+
if (decision.action === "unchanged") {
|
|
958
|
+
actions.push(`UNCHANGED: ${label} (${decision.reason})`);
|
|
959
|
+
continue;
|
|
960
|
+
}
|
|
961
|
+
writeFileSync(p, decision.content!);
|
|
962
|
+
actions.push(`${existedBefore ? "UPDATED" : "CREATED"}: ${label}`);
|
|
942
963
|
}
|
|
943
964
|
}
|
|
944
965
|
|
|
@@ -969,7 +990,7 @@ export function generateOrAuditProjectHarness(root: string, actions: string[], o
|
|
|
969
990
|
// Scan pages from dashboard/src/pages/*.tsx (file-based routing)
|
|
970
991
|
const dashboardPagesDir = join(root, "dashboard", "src", "pages");
|
|
971
992
|
if (existsSync(dashboardPagesDir)) {
|
|
972
|
-
const pageFiles =
|
|
993
|
+
const pageFiles = readdirSorted(dashboardPagesDir).filter(f => f.endsWith(".tsx") || f.endsWith(".jsx"));
|
|
973
994
|
for (const f of pageFiles) {
|
|
974
995
|
const componentName = f.replace(/\.(tsx|jsx)$/, "");
|
|
975
996
|
// Convert CamelCase to kebab-case route path
|
|
@@ -980,13 +1001,12 @@ export function generateOrAuditProjectHarness(root: string, actions: string[], o
|
|
|
980
1001
|
}
|
|
981
1002
|
}
|
|
982
1003
|
|
|
983
|
-
//
|
|
1004
|
+
// `inferredTestCommand`, not the full decision (#488). This value is what
|
|
1005
|
+
// gets WRITTEN into `dev.testCmd`, so reading `dev.testCmd` to choose it
|
|
1006
|
+
// is circular — and this step runs against trees whose config is
|
|
1007
|
+
// malformed, which is what it exists to repair.
|
|
1008
|
+
const testCmd = inferredTestCommand(root).command;
|
|
984
1009
|
const pkgPath = join(root, "package.json");
|
|
985
|
-
let testCmd = "bun test";
|
|
986
|
-
if (existsSync(pkgPath)) {
|
|
987
|
-
const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
|
|
988
|
-
if (pkg.scripts?.test) testCmd = pkg.scripts.test;
|
|
989
|
-
}
|
|
990
1010
|
// #87 — this defaulted to `bunx tsc --noEmit` for every project, including
|
|
991
1011
|
// one with no tsconfig, and `gates/gate-executor.ts` RUNS what lands here.
|
|
992
1012
|
// Without a tsconfig that command prints 147 lines of help and exits 1, so
|
|
@@ -1071,7 +1091,7 @@ export function generateOrAuditProjectHarness(root: string, actions: string[], o
|
|
|
1071
1091
|
const srcDir = join(root, "src");
|
|
1072
1092
|
if (existsSync(srcDir)) {
|
|
1073
1093
|
const consumerPatterns = ["-routes.ts", "-generator.ts", "-plan.ts", "-intel.ts"];
|
|
1074
|
-
for (const f of
|
|
1094
|
+
for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts"))) {
|
|
1075
1095
|
const content = readFileSync(join(srcDir, f), "utf-8");
|
|
1076
1096
|
const isConsumer = consumerPatterns.some(p => f.includes(p)) ||
|
|
1077
1097
|
content.includes("app.get(") || content.includes("app.post(") ||
|
|
@@ -1158,7 +1178,14 @@ export function generateOrAuditProjectHarness(root: string, actions: string[], o
|
|
|
1158
1178
|
envVars: envVars || [],
|
|
1159
1179
|
ci: {
|
|
1160
1180
|
runner: "ubuntu-latest",
|
|
1161
|
-
|
|
1181
|
+
// Detected, never defaulted (#346, #622). `"latest"` here wrote an
|
|
1182
|
+
// UNPINNED runtime into every greenfield project's CI and called it a
|
|
1183
|
+
// configuration: the job installs whatever shipped this morning, so
|
|
1184
|
+
// re-running a red build is also a Bun upgrade. The bun that ran the
|
|
1185
|
+
// scaffold is a measurement of what this project has been built with,
|
|
1186
|
+
// which is the honest thing to write down, and the operator can change
|
|
1187
|
+
// it in one place afterwards.
|
|
1188
|
+
bunVersion: Bun.version,
|
|
1162
1189
|
branches: ["main"],
|
|
1163
1190
|
},
|
|
1164
1191
|
contextDocs: {},
|
|
@@ -1449,7 +1476,17 @@ function writeDirectoryStructure(
|
|
|
1449
1476
|
* so no later scaffold ever corrected it. Running this step last is what makes
|
|
1450
1477
|
* that skip safe — the content it preserves is now right from run 1.
|
|
1451
1478
|
*/
|
|
1452
|
-
export function generateCodeMapStep(
|
|
1479
|
+
export function generateCodeMapStep(
|
|
1480
|
+
root: string,
|
|
1481
|
+
actions: string[],
|
|
1482
|
+
// #654 — the one injection seam, so the branch where the generator exits 0
|
|
1483
|
+
// and writes nothing can be entered. There is no input to the real
|
|
1484
|
+
// generator that provokes it, and a branch no test can enter is the thing
|
|
1485
|
+
// `.claude/rules/checks-must-be-able-to-fail.md` is about. Optional and
|
|
1486
|
+
// defaulted to the real script, so every caller is unchanged and a test
|
|
1487
|
+
// that forgets it is testing the real thing.
|
|
1488
|
+
opts: { generatorPath?: string } = {},
|
|
1489
|
+
): void {
|
|
1453
1490
|
// No dry-run branch. It reported `GAP: CODE-MAP.md missing` and nothing
|
|
1454
1491
|
// else — one of the four `existsSync` checks that stood in for twenty-five
|
|
1455
1492
|
// write steps and made audit report 0 changes on a tree `--fix` rewrote in
|
|
@@ -1481,11 +1518,31 @@ export function generateCodeMapStep(root: string, actions: string[]): void {
|
|
|
1481
1518
|
}
|
|
1482
1519
|
|
|
1483
1520
|
// Run generate-code-map.ts if available
|
|
1484
|
-
const scriptPath =
|
|
1521
|
+
const scriptPath =
|
|
1522
|
+
opts.generatorPath ?? join(dirname(dirname(__dirname)), "scripts", "generate-code-map.ts");
|
|
1485
1523
|
if (existsSync(scriptPath)) {
|
|
1524
|
+
// #654, and the same shape as the brief loop above with one extra arm.
|
|
1525
|
+
// Asked after the generator ran, `existsSync` answered two questions at
|
|
1526
|
+
// once and got both wrong: a successful generation reported `UPDATED:`
|
|
1527
|
+
// whether or not the file was new, and a generator that exits 0 WITHOUT
|
|
1528
|
+
// writing reported `CREATED:` for a file that is not there. The second
|
|
1529
|
+
// is the one that matters — `lib/scaffold/rehearsal.ts:481` records the
|
|
1530
|
+
// same defect at a site that was fixed, and it survived here because
|
|
1531
|
+
// the note was attached to the site rather than to the shape.
|
|
1532
|
+
const existedBefore = existsSync(codeMapPath);
|
|
1486
1533
|
const result = Bun.spawnSync(["bun", scriptPath, root], { timeout: 60_000 });
|
|
1487
1534
|
if (result.exitCode === 0) {
|
|
1488
|
-
|
|
1535
|
+
const existsNow = existsSync(codeMapPath);
|
|
1536
|
+
actions.push(
|
|
1537
|
+
!existsNow
|
|
1538
|
+
// Neither created nor updated: the generator reported success and
|
|
1539
|
+
// produced nothing, which is a measurement that did not happen
|
|
1540
|
+
// and must not read as one that did.
|
|
1541
|
+
? "UNMEASURED: CODE-MAP.md — the generator exited 0 and wrote no file"
|
|
1542
|
+
: existedBefore
|
|
1543
|
+
? "UPDATED: CODE-MAP.md"
|
|
1544
|
+
: "CREATED: CODE-MAP.md",
|
|
1545
|
+
);
|
|
1489
1546
|
} else {
|
|
1490
1547
|
actions.push("WARN: CODE-MAP.md generation failed via script — trying inline");
|
|
1491
1548
|
generateCodeMapInline(root, codeMapPath, actions);
|
|
@@ -1499,13 +1556,13 @@ function generateCodeMapInline(root: string, outPath: string, actions: string[])
|
|
|
1499
1556
|
const name = basename(root);
|
|
1500
1557
|
const skip = new Set(["node_modules", ".git", "reference", "dist", "build", ".next", ".fallow"]);
|
|
1501
1558
|
const dirs: Array<{ name: string; fileCount: number; types: string[] }> = [];
|
|
1502
|
-
for (const entry of
|
|
1559
|
+
for (const entry of readdirSorted(root)) {
|
|
1503
1560
|
if (entry.startsWith(".") && entry !== ".claude") continue;
|
|
1504
1561
|
if (skip.has(entry)) continue;
|
|
1505
1562
|
const full = join(root, entry);
|
|
1506
1563
|
try {
|
|
1507
1564
|
if (!statSync(full).isDirectory()) continue;
|
|
1508
|
-
const files =
|
|
1565
|
+
const files = readdirSorted(full, { recursive: true });
|
|
1509
1566
|
const exts = new Set(files.map(f => f.split(".").pop()).filter((e): e is string => Boolean(e)));
|
|
1510
1567
|
dirs.push({ name: entry, fileCount: files.length, types: [...exts].slice(0, 5) });
|
|
1511
1568
|
} catch {}
|
|
@@ -1525,7 +1582,7 @@ function generateCodeMapInline(root: string, outPath: string, actions: string[])
|
|
|
1525
1582
|
const srcDir = join(root, "src");
|
|
1526
1583
|
const modules: Array<{ file: string; exports: string[] }> = [];
|
|
1527
1584
|
if (existsSync(srcDir)) {
|
|
1528
|
-
for (const f of
|
|
1585
|
+
for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
|
|
1529
1586
|
const content = readFileSync(join(srcDir, f), "utf-8");
|
|
1530
1587
|
const exports: string[] = [];
|
|
1531
1588
|
const exportPattern = /export\s+(?:function|const|class|type|interface)\s+(\w+)/g;
|
|
@@ -1538,7 +1595,7 @@ function generateCodeMapInline(root: string, outPath: string, actions: string[])
|
|
|
1538
1595
|
// Detect API routes
|
|
1539
1596
|
const routes: Array<{ method: string; path: string; file: string }> = [];
|
|
1540
1597
|
if (existsSync(srcDir)) {
|
|
1541
|
-
for (const f of
|
|
1598
|
+
for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
|
|
1542
1599
|
const content = readFileSync(join(srcDir, f), "utf-8");
|
|
1543
1600
|
const routePatterns = [
|
|
1544
1601
|
/app\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/gi,
|
|
@@ -1599,7 +1656,7 @@ export function copySpecTemplateIfEmpty(specsDir: string, actions: string[]): vo
|
|
|
1599
1656
|
if (!existsSync(specsDir)) return;
|
|
1600
1657
|
|
|
1601
1658
|
// Skip if specs/ already has .md files (besides SPEC-TEMPLATE.md itself)
|
|
1602
|
-
const existingSpecs =
|
|
1659
|
+
const existingSpecs = readdirSorted(specsDir).filter(
|
|
1603
1660
|
f => f.endsWith(".md") && f !== "SPEC-TEMPLATE.md"
|
|
1604
1661
|
);
|
|
1605
1662
|
if (existingSpecs.length > 0) {
|
|
@@ -1779,7 +1836,20 @@ export function missingGitignorePatterns(existing: string): string[] {
|
|
|
1779
1836
|
.map(l => l.trim())
|
|
1780
1837
|
.filter(l => l !== "" && !l.startsWith("#")),
|
|
1781
1838
|
);
|
|
1782
|
-
|
|
1839
|
+
// #586: `X/` is satisfied by an existing `X`, and ONLY in that direction.
|
|
1840
|
+
// This repo's `.gitignore` opens with `node_modules` and the required
|
|
1841
|
+
// pattern is `node_modules/`, so exact matching reported it absent and
|
|
1842
|
+
// every scaffold run re-added a line that changes nothing.
|
|
1843
|
+
//
|
|
1844
|
+
// The direction is the whole safety argument, and it is the opposite of
|
|
1845
|
+
// the trap the docstring above names. A bare `node_modules` matches files
|
|
1846
|
+
// AND directories, so it is STRICTLY BROADER than `node_modules/` — the
|
|
1847
|
+
// requirement is already met. `service-account` present against a required
|
|
1848
|
+
// `service-account*` is the reverse: the required pattern is broader, the
|
|
1849
|
+
// requirement is NOT met, and that case must keep failing.
|
|
1850
|
+
const satisfied = (p: string): boolean =>
|
|
1851
|
+
present.has(p) || (p.endsWith("/") && present.has(p.slice(0, -1)));
|
|
1852
|
+
return requiredGitignorePatterns().filter(p => !satisfied(p));
|
|
1783
1853
|
}
|
|
1784
1854
|
|
|
1785
1855
|
export function createGitignore(root: string, actions: string[]): void {
|
|
@@ -1809,7 +1879,7 @@ export function generateProjectState(root: string, actions: string[]): void {
|
|
|
1809
1879
|
return;
|
|
1810
1880
|
}
|
|
1811
1881
|
|
|
1812
|
-
const today =
|
|
1882
|
+
const today = localCalendarDay();
|
|
1813
1883
|
|
|
1814
1884
|
interface SC { id: string; what: string; done: boolean; }
|
|
1815
1885
|
const scs: SC[] = [];
|
|
@@ -1934,7 +2004,7 @@ export function seedSuccessDoc(root: string, actions: string[]): void {
|
|
|
1934
2004
|
return;
|
|
1935
2005
|
}
|
|
1936
2006
|
|
|
1937
|
-
const today =
|
|
2007
|
+
const today = localCalendarDay();
|
|
1938
2008
|
const owner = process.env.USER || "TODO-OWNER";
|
|
1939
2009
|
// The SHARED substitution. Writing the template raw here while
|
|
1940
2010
|
// `create-success` substituted meant one seed with two possible byte
|
|
@@ -2031,6 +2101,26 @@ export interface ManagedWrite {
|
|
|
2031
2101
|
* was being made.
|
|
2032
2102
|
*/
|
|
2033
2103
|
movedKeys: MovedKey[];
|
|
2104
|
+
/**
|
|
2105
|
+
* Derived grants the merge withdrew because the generator stopped computing
|
|
2106
|
+
* them (#923).
|
|
2107
|
+
*
|
|
2108
|
+
* Not a refusal and not an overwrite — a third thing, and it needs its own
|
|
2109
|
+
* field because the other two would both misreport it. In `lostLines` it is
|
|
2110
|
+
* a refusal over two lines the harness wrote itself; in `overwrittenLines`
|
|
2111
|
+
* it is a report that says "in harness-owned jobs" about a top-level key.
|
|
2112
|
+
*
|
|
2113
|
+
* Reported rather than silent, because the removal is the whole point: a
|
|
2114
|
+
* consumer who removes `ci.vertex` keeps `id-token: write` — the right to
|
|
2115
|
+
* mint an OIDC token for a federation that no longer exists — and a
|
|
2116
|
+
* permission nobody consumes is a permission nobody audits. Taking it away
|
|
2117
|
+
* without saying so would make the scaffold do, silently, the one thing
|
|
2118
|
+
* `ci.workflowOverrides` was built to guarantee is always visible.
|
|
2119
|
+
*
|
|
2120
|
+
* The record travels from the merge rather than being recomputed here. See
|
|
2121
|
+
* `mergeManagedWorkflowRecording`.
|
|
2122
|
+
*/
|
|
2123
|
+
revokedGrants: RevokedSubKey[];
|
|
2034
2124
|
/** Non-null ⇒ the write must not happen. Names the dropped jobs and the line delta. */
|
|
2035
2125
|
refusal: string | null;
|
|
2036
2126
|
}
|
|
@@ -2128,10 +2218,11 @@ function measureWrite(existing: string | null, next: string): { verb: ManagedWri
|
|
|
2128
2218
|
* test/scaffold-ci-preservation-mutation.test.ts performs, so that
|
|
2129
2219
|
* "preservation works" is a claim with a demonstrated way of being false.
|
|
2130
2220
|
*/
|
|
2131
|
-
export function resolveManagedWrite(existing: string | null, generated: string): ManagedWrite {
|
|
2221
|
+
export function resolveManagedWrite(existing: string | null, generated: string, overrides: readonly string[] = [], provenance: MergeProvenance = "UNPROVEN", computed: ComputedSubKeys = new Map()): ManagedWrite {
|
|
2132
2222
|
const base: ManagedWrite = {
|
|
2133
2223
|
content: generated, verb: "CREATED", lineDelta: lineCount(generated),
|
|
2134
|
-
preservedJobs: [], droppedJobs: [], overwrittenLines: [], movedKeys: [],
|
|
2224
|
+
preservedJobs: [], droppedJobs: [], overwrittenLines: [], movedKeys: [], revokedGrants: [],
|
|
2225
|
+
refusal: null,
|
|
2135
2226
|
};
|
|
2136
2227
|
if (existing === null) return base;
|
|
2137
2228
|
|
|
@@ -2160,7 +2251,7 @@ export function resolveManagedWrite(existing: string | null, generated: string):
|
|
|
2160
2251
|
// A refusal that is structurally incapable of firing on the thing being
|
|
2161
2252
|
// destroyed is the defect class .claude/rules/checks-must-be-able-to-fail.md
|
|
2162
2253
|
// exists for, and it was in the fix written to prevent a data-loss bug.
|
|
2163
|
-
const content =
|
|
2254
|
+
const { content, revoked: revokedGrants } = mergeManagedWorkflowRecording(existing, generated, overrides, provenance, computed);
|
|
2164
2255
|
const lineDelta = lineCount(content) - before;
|
|
2165
2256
|
|
|
2166
2257
|
const preservedJobs = existingJobs.filter(j => !generatedJobs.includes(j));
|
|
@@ -2244,19 +2335,98 @@ export function resolveManagedWrite(existing: string | null, generated: string):
|
|
|
2244
2335
|
const block = blocks.get(name);
|
|
2245
2336
|
if (block !== undefined) for (const l of nonBlankLines(block)) harnessOwned.add(l);
|
|
2246
2337
|
}
|
|
2247
|
-
// The harness's own
|
|
2248
|
-
// first run after the banner's text changed
|
|
2249
|
-
// harness had written itself, naming its own
|
|
2250
|
-
// content it declined to drop — a refusal is
|
|
2251
|
-
// somebody else's work.
|
|
2338
|
+
// The harness's own bookkeeping lines are the harness's to reword or
|
|
2339
|
+
// withdraw. Without this, the first run after the banner's text changed
|
|
2340
|
+
// refused to update a file the harness had written itself, naming its own
|
|
2341
|
+
// previous sentence as consumer content it declined to drop — a refusal is
|
|
2342
|
+
// only useful if it is about somebody else's work. The override notice is
|
|
2343
|
+
// here for the same reason and one more: it is DELETED, not reworded, the
|
|
2344
|
+
// run after a consumer removes the config entry, so without this the way
|
|
2345
|
+
// back from an override is a refusal (#839).
|
|
2252
2346
|
for (const l of nonBlankLines(existing)) {
|
|
2253
|
-
if (l.startsWith(
|
|
2347
|
+
if (HARNESS_BOOKKEEPING_PREFIXES.some(p => l.startsWith(p))) harnessOwned.add(l);
|
|
2254
2348
|
}
|
|
2255
2349
|
|
|
2350
|
+
// The harness's own preamble is the harness's to reword — the WHOLE of it
|
|
2351
|
+
// from the banner down, not just the banner line (#834). A bookkeeping
|
|
2352
|
+
// PREFIX catches the sentence it opens and nothing else, so the paragraphs
|
|
2353
|
+
// underneath read as consumer content: a consumer that added `ci.vertex`
|
|
2354
|
+
// had its re-scaffold refused over three lines of the harness's own "no
|
|
2355
|
+
// credential is configured" header, which is precisely the header the new
|
|
2356
|
+
// one replaces. The merge already declares that preamble its own, so this
|
|
2357
|
+
// reads the boundary from `managedPreamble` rather than restating it —
|
|
2358
|
+
// the two disagreeing is what made the refusal possible.
|
|
2359
|
+
//
|
|
2360
|
+
// This SUBSUMES the banner entry in `HARNESS_BOOKKEEPING_PREFIXES` for the
|
|
2361
|
+
// LEADING PREAMBLE, and only there. The banner of a generated workflow is
|
|
2362
|
+
// always in that preamble, so for the file the generator wrote the two
|
|
2363
|
+
// deciders cannot disagree — which is why giving the constant a second
|
|
2364
|
+
// spelling in this module turned 0 of 107 red when #916 landed, and why
|
|
2365
|
+
// saying so was cheaper than implying a guard that is not there
|
|
2366
|
+
// (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
|
|
2367
|
+
//
|
|
2368
|
+
// "Only there" is the part that was missing, and #926 is where it was
|
|
2369
|
+
// measured. `managedPreamble` reads the HEAD section and returns `[]` when
|
|
2370
|
+
// the banner is not in it, so a bookkeeping line anywhere else in the file
|
|
2371
|
+
// — beside the job key it introduces, which is exactly where the override
|
|
2372
|
+
// notice sits — reaches this loss set with nothing above covering it. The
|
|
2373
|
+
// entry is what keeps it out, and the write refuses without it. Both
|
|
2374
|
+
// entries now carry that witness in
|
|
2375
|
+
// `test/scaffold-permissions-merge.test.ts`, generated from the array.
|
|
2376
|
+
//
|
|
2377
|
+
// What the entry is not any more is the thing keeping the HEADER out of the
|
|
2378
|
+
// loss set. That job is `harnessPreamble`'s.
|
|
2379
|
+
const harnessPreamble = new Set(nonBlankLines(managedPreamble(existing).join("\n")));
|
|
2380
|
+
|
|
2381
|
+
// The grants the merge withdrew, as the lines it took out (#923).
|
|
2382
|
+
//
|
|
2383
|
+
// Taken FROM THE MERGE, not recomputed. A second reading here of which
|
|
2384
|
+
// sub-keys ought to have gone would be a decider that can disagree with the
|
|
2385
|
+
// one that actually removed them, and #834 is the bill for exactly that
|
|
2386
|
+
// arrangement: the merge computed the correct file, the write's own view of
|
|
2387
|
+
// what it was allowed to drop refused to put it on disk, and `id-token:
|
|
2388
|
+
// write` stayed off every consumer for it. Here the disagreement would run
|
|
2389
|
+
// the other way and be worse — a line the merge removed and this set did
|
|
2390
|
+
// not cover is a REFUSED re-scaffold, and a line this set covered and the
|
|
2391
|
+
// merge did not remove is a consumer's own content dropped in silence.
|
|
2392
|
+
// A MULTISET, and spending it is what makes it one. A `Set` of line TEXT
|
|
2393
|
+
// excuses every line in the file that happens to share that text, and
|
|
2394
|
+
// ` id-token: write` is a line a multi-job workflow plausibly carries more
|
|
2395
|
+
// than once — one legitimately withdrawn occurrence would then silently
|
|
2396
|
+
// excuse an unrelated one the consumer still wants. A set also cannot
|
|
2397
|
+
// count: two revoked and five present is indistinguishable from one and
|
|
2398
|
+
// one. Exactly as many occurrences are forgiven as the merge removed, and
|
|
2399
|
+
// the rest refuse like any other dropped line.
|
|
2400
|
+
const revocationBudget = new Map<string, number>();
|
|
2401
|
+
for (const r of revokedGrants) {
|
|
2402
|
+
for (const l of nonBlankLines(r.lines.join("\n"))) {
|
|
2403
|
+
revocationBudget.set(l, (revocationBudget.get(l) ?? 0) + 1);
|
|
2404
|
+
}
|
|
2405
|
+
}
|
|
2406
|
+
/** Spend one occurrence, or report that there is none left to spend. */
|
|
2407
|
+
const spendRevocation = (line: string): boolean => {
|
|
2408
|
+
const left = revocationBudget.get(line) ?? 0;
|
|
2409
|
+
if (left === 0) return false;
|
|
2410
|
+
revocationBudget.set(line, left - 1);
|
|
2411
|
+
return true;
|
|
2412
|
+
};
|
|
2413
|
+
|
|
2256
2414
|
const kept = new Set(nonBlankLines(content));
|
|
2257
2415
|
const gone = nonBlankLines(existing).filter(l => !kept.has(l));
|
|
2258
|
-
|
|
2259
|
-
|
|
2416
|
+
// Order matters: `spendRevocation` is reached only when the two cheaper
|
|
2417
|
+
// owners decline, so a line the harness already owns does not burn a
|
|
2418
|
+
// revocation another occurrence may need.
|
|
2419
|
+
const lostLines = gone.filter(
|
|
2420
|
+
l => !harnessOwned.has(l) && !harnessPreamble.has(l) && !spendRevocation(l),
|
|
2421
|
+
);
|
|
2422
|
+
// Rewording its own header is not overwriting somebody's edit, and this
|
|
2423
|
+
// report says "in harness-owned jobs" — which the preamble is not.
|
|
2424
|
+
const overwrittenLines = gone.filter(
|
|
2425
|
+
l =>
|
|
2426
|
+
harnessOwned.has(l) &&
|
|
2427
|
+
!harnessPreamble.has(l) &&
|
|
2428
|
+
!HARNESS_BOOKKEEPING_PREFIXES.some(p => l.startsWith(p)),
|
|
2429
|
+
);
|
|
2260
2430
|
const droppedJobs = existingJobs.filter(j => !resultJobs.includes(j));
|
|
2261
2431
|
|
|
2262
2432
|
if (lostLines.length > 0) {
|
|
@@ -2273,7 +2443,11 @@ export function resolveManagedWrite(existing: string | null, generated: string):
|
|
|
2273
2443
|
};
|
|
2274
2444
|
}
|
|
2275
2445
|
|
|
2276
|
-
|
|
2446
|
+
// `revokedGrants` only reaches a caller on this path. Every return above is
|
|
2447
|
+
// a refusal and `unchanged` carries the empty list from `base`: nothing was
|
|
2448
|
+
// written, so nothing was withdrawn, and a report naming a grant that is
|
|
2449
|
+
// still in the file on disk is the reading disagreeing with reality again.
|
|
2450
|
+
return { content, ...measureWrite(existing, content), preservedJobs, droppedJobs: [], overwrittenLines, movedKeys, revokedGrants, refusal: null };
|
|
2277
2451
|
}
|
|
2278
2452
|
|
|
2279
2453
|
/** Non-blank lines, trimmed — the unit the loss set is counted in. */
|
|
@@ -2282,13 +2456,85 @@ function nonBlankLines(text: string): string[] {
|
|
|
2282
2456
|
}
|
|
2283
2457
|
|
|
2284
2458
|
/**
|
|
2285
|
-
*
|
|
2459
|
+
* Lines in a managed file that are the harness talking to the consumer, not
|
|
2460
|
+
* the consumer's content.
|
|
2461
|
+
*
|
|
2462
|
+
* Both are prefixes rather than whole sentences: the rest of each names a
|
|
2463
|
+
* config path, and that tail is exactly the part that changes.
|
|
2464
|
+
*
|
|
2465
|
+
* EXPORTED so the list itself can be tested rather than its members (#926).
|
|
2466
|
+
* `test/scaffold-permissions-merge.test.ts` demands a WITNESS for every entry
|
|
2467
|
+
* — an input where matching the prefix is what decides the outcome — and
|
|
2468
|
+
* ratchets this array against the witnessed population, so an entry added
|
|
2469
|
+
* here with no case there is red. An entry nothing asserts reads as covered,
|
|
2470
|
+
* and adding the next one is how a dead decider gets in; this is what stops
|
|
2471
|
+
* the next one arriving dead the way the banner entry did.
|
|
2472
|
+
*
|
|
2473
|
+
* The witnesses plant lines built from the constants in `managed-workflow.ts`
|
|
2474
|
+
* rather than from this array, deliberately. A fixture read out of the list
|
|
2475
|
+
* under test matches whatever the list says and cannot see it drift.
|
|
2476
|
+
*/
|
|
2477
|
+
export const HARNESS_BOOKKEEPING_PREFIXES = [MANAGED_BANNER_PREFIX, WORKFLOW_OVERRIDE_COMMENT];
|
|
2478
|
+
|
|
2479
|
+
/**
|
|
2480
|
+
* The sub-keys each generated workflow COMPUTES, by file and then by the
|
|
2481
|
+
* top-level key they sit under (#923).
|
|
2482
|
+
*
|
|
2483
|
+
* Same shape as `HARNESS_OWNED_JOBS` and for the same reason: a
|
|
2484
|
+
* conditionally emitted thing cannot be recognised from the generated side
|
|
2485
|
+
* once it stops being emitted. `mergeTopLevelSection`'s rule — a sub-key
|
|
2486
|
+
* only the consumer declares is the consumer's — is right for a LOCAL KNOB
|
|
2487
|
+
* and wrong for a DERIVED GRANT. `pull-requests: write` that a consumer
|
|
2488
|
+
* added for a job of their own is theirs. `id-token: write` that this
|
|
2489
|
+
* generator emitted because `ci.vertex` resolved is nobody's choice; the
|
|
2490
|
+
* config made it, and when the config goes the justification goes with it.
|
|
2491
|
+
* By the time the merge runs both are just lines in the consumer's file and
|
|
2492
|
+
* nothing records which side wrote them, so this records it instead.
|
|
2493
|
+
*
|
|
2494
|
+
* A sub-key named here is REMOVED from the consumer's section when that
|
|
2495
|
+
* file's generated side does not declare it. Add a conditionally emitted
|
|
2496
|
+
* sub-key in the same commit that makes it conditional.
|
|
2497
|
+
*
|
|
2498
|
+
* ## Keyed by FILE, which is the whole of the scoping
|
|
2499
|
+
*
|
|
2500
|
+
* The merge runs over every managed workflow. Keyed by section alone,
|
|
2501
|
+
* `permissions.id-token` becomes revocable in files whose generator never
|
|
2502
|
+
* emits it under any config — and all three of these emit a top-level
|
|
2503
|
+
* `permissions:`, so a consumer with a deploy job of their own would have
|
|
2504
|
+
* the grant withdrawn out of a workflow this feature was not reasoning
|
|
2505
|
+
* about. That is #923's own defect wearing the other hat: the issue is a
|
|
2506
|
+
* grant outliving its reason, and an unscoped revoker is a WITHDRAWAL
|
|
2507
|
+
* outliving its reason.
|
|
2508
|
+
*
|
|
2509
|
+
* Declared HERE rather than in `managed-workflow.ts` because the write loop
|
|
2510
|
+
* below is the only place that knows which file it is writing, and because
|
|
2511
|
+
* this module already spells that tuple as a literal for
|
|
2512
|
+
* `test/release-guard.test.ts`. A file absent from this map revokes nothing.
|
|
2513
|
+
*
|
|
2514
|
+
* ## Scoped to what the generator COMPUTES
|
|
2515
|
+
*
|
|
2516
|
+
* Not to everything it emits. `contents: read` is unconditional in all three
|
|
2517
|
+
* files, so both sides always declare it, #839's rule already settles it,
|
|
2518
|
+
* and an entry for it would be one no input can reach.
|
|
2519
|
+
* `test/scaffold-permissions-merge.test.ts` holds this map against the
|
|
2520
|
+
* generators themselves — it scaffolds every generated workflow with and
|
|
2521
|
+
* without the config that drives the grant and takes the per-file symmetric
|
|
2522
|
+
* difference of the emitted sub-keys — so the population is read off the
|
|
2523
|
+
* emitting module rather than off this list, and an entry for a file whose
|
|
2524
|
+
* generator never computes the sub-key is red.
|
|
2525
|
+
*
|
|
2526
|
+
* ## Not `ci.workflowOverrides`, which could not be the mechanism
|
|
2286
2527
|
*
|
|
2287
|
-
*
|
|
2288
|
-
*
|
|
2289
|
-
* the
|
|
2528
|
+
* That is an opt-OUT: a consumer names a key and the merge stops touching
|
|
2529
|
+
* it. Revocation needs the opposite default, because the consumer who has
|
|
2530
|
+
* stopped using Vertex is exactly the consumer who will not think to declare
|
|
2531
|
+
* anything about it. The override still wins where it is declared — naming
|
|
2532
|
+
* the top-level key short-circuits `mergeTopLevelSection` before this is
|
|
2533
|
+
* read — so the escape hatch covers the path with no new config surface.
|
|
2290
2534
|
*/
|
|
2291
|
-
const
|
|
2535
|
+
export const HARNESS_COMPUTED_SUBKEYS: ReadonlyMap<string, ComputedSubKeys> = new Map([
|
|
2536
|
+
["ai-review.yml", new Map([["permissions", new Set(["id-token"])]])],
|
|
2537
|
+
]);
|
|
2292
2538
|
|
|
2293
2539
|
/**
|
|
2294
2540
|
* Write a harness-managed file, preserving whatever the harness did not author.
|
|
@@ -2296,27 +2542,75 @@ const MANAGED_BANNER_PREFIX = "# Managed by rungate";
|
|
|
2296
2542
|
* Throws on refusal. Callers decide whether a refusal aborts the run or is
|
|
2297
2543
|
* recorded and reported; what they may not do is write anyway.
|
|
2298
2544
|
*/
|
|
2545
|
+
/**
|
|
2546
|
+
* How a managed file carries the record of who wrote it (#767).
|
|
2547
|
+
*
|
|
2548
|
+
* Optional, because most managed files have no marker. When present it is
|
|
2549
|
+
* applied LAST, to the bytes that land on disk, and stripped from both sides
|
|
2550
|
+
* of every comparison — a marker that describes anything other than the file
|
|
2551
|
+
* it is attached to is worse than no marker, because the census believes it.
|
|
2552
|
+
*/
|
|
2553
|
+
export interface WriteProvenance {
|
|
2554
|
+
/** The document with its marker line removed. */
|
|
2555
|
+
body(text: string): string;
|
|
2556
|
+
/** The document with a marker describing its own body. */
|
|
2557
|
+
stamp(text: string): string;
|
|
2558
|
+
}
|
|
2559
|
+
|
|
2299
2560
|
export function writeManagedFile(
|
|
2300
2561
|
filePath: string,
|
|
2301
2562
|
generated: string,
|
|
2302
2563
|
label: string,
|
|
2303
2564
|
actions: string[],
|
|
2304
|
-
opts: { force?: boolean } = {},
|
|
2565
|
+
opts: { force?: boolean; workflowOverrides?: readonly string[]; computedSubKeys?: ComputedSubKeys } = {},
|
|
2566
|
+
provenance?: WriteProvenance,
|
|
2305
2567
|
): void {
|
|
2306
|
-
const
|
|
2307
|
-
|
|
2568
|
+
const raw = existsSync(filePath) ? readFileSync(filePath, "utf-8") : null;
|
|
2569
|
+
// The marker is stripped from BOTH sides before anything compares them, and
|
|
2570
|
+
// re-applied to whatever is about to be written (#767).
|
|
2571
|
+
//
|
|
2572
|
+
// It has to be both sides and it has to be last. `resolveManagedWrite`
|
|
2573
|
+
// treats every line outside a job as the consumer's, so the OLD marker —
|
|
2574
|
+
// which differs from the new one exactly when the generator changed — read
|
|
2575
|
+
// as content about to be dropped and REFUSED the write. And stamping the
|
|
2576
|
+
// generated text before the merge produced a file whose marker described
|
|
2577
|
+
// bytes that were never written, so a workflow with one preserved job was
|
|
2578
|
+
// classified `generated-and-hand-edited` for ever, about bytes the harness
|
|
2579
|
+
// itself had just written.
|
|
2580
|
+
const existing = raw === null ? null : (provenance ? provenance.body(raw) : raw);
|
|
2581
|
+
const incoming = provenance ? provenance.body(generated) : generated;
|
|
2582
|
+
// What the marker proves about the bytes on disk, read HERE because here is
|
|
2583
|
+
// the only layer that still holds them (#957). Everything below this line
|
|
2584
|
+
// has had the marker stripped, which is the whole reason #941 could not
|
|
2585
|
+
// repair the residue it left: the merge was handed a file with no way of
|
|
2586
|
+
// telling its own old output from the consumer's.
|
|
2587
|
+
//
|
|
2588
|
+
// One expression, over the `WriteProvenance` the caller already supplies:
|
|
2589
|
+
// re-stamping the body reproduces the file exactly when the marker is
|
|
2590
|
+
// present AND describes that body. An absent marker and a stale one are both
|
|
2591
|
+
// UNPROVEN, which is the only distinction the merge acts on, and a managed
|
|
2592
|
+
// file with no provenance at all reads as UNPROVEN too — the fail-closed
|
|
2593
|
+
// direction and the pre-#957 behaviour unchanged.
|
|
2594
|
+
const proven: MergeProvenance =
|
|
2595
|
+
provenance !== undefined && raw !== null && provenance.stamp(provenance.body(raw)) === raw
|
|
2596
|
+
? "VERIFIED"
|
|
2597
|
+
: "UNPROVEN";
|
|
2598
|
+
const resolved = resolveManagedWrite(existing, incoming, opts.workflowOverrides ?? [], proven, opts.computedSubKeys ?? new Map());
|
|
2599
|
+
/** The bytes that land on disk: the decision's content, then the marker. */
|
|
2600
|
+
const stamped = (content: string): string => (provenance ? provenance.stamp(content) : content);
|
|
2308
2601
|
|
|
2309
2602
|
if (opts.force) {
|
|
2310
2603
|
// The escape hatch, and it still reports a measured verb: --force changes
|
|
2311
2604
|
// what is ALLOWED, not what gets claimed about it. The dropped jobs are
|
|
2312
2605
|
// still named, because an operator who overrides the refusal should be
|
|
2313
2606
|
// told in the report exactly what they overrode.
|
|
2314
|
-
const
|
|
2315
|
-
if (
|
|
2607
|
+
const bytes = stamped(incoming);
|
|
2608
|
+
if (bytes === raw) { actions.push(`SKIP: ${label} (unchanged)`); return; }
|
|
2609
|
+
const { verb, lineDelta } = measureWrite(existing, incoming);
|
|
2316
2610
|
const dropped = resolved.droppedJobs.length > 0 ? `, dropped ${resolved.droppedJobs.join(", ")}` : "";
|
|
2317
2611
|
mkdirSync(dirname(filePath), { recursive: true });
|
|
2318
|
-
writeFileSync(filePath,
|
|
2319
|
-
actions.push(`${verb}: ${label} (--force, ${signed(lineDelta)} lines${dropped})`);
|
|
2612
|
+
writeFileSync(filePath, bytes);
|
|
2613
|
+
actions.push(`${verb === "SKIP" ? "UPDATED" : verb}: ${label} (--force, ${signed(lineDelta)} lines${dropped})`);
|
|
2320
2614
|
return;
|
|
2321
2615
|
}
|
|
2322
2616
|
|
|
@@ -2339,16 +2633,296 @@ export function writeManagedFile(
|
|
|
2339
2633
|
`${over.slice(0, 2).map(l => JSON.stringify(l)).join(", ")}` +
|
|
2340
2634
|
`${over.length > 2 ? ` and ${over.length - 2} more` : ""}`;
|
|
2341
2635
|
|
|
2342
|
-
|
|
2636
|
+
const bytes = stamped(resolved.content);
|
|
2637
|
+
|
|
2638
|
+
// Compared as BYTES, not as a verb. `resolved.verb` is a statement about
|
|
2639
|
+
// the bodies, and a file whose body is unchanged can still need writing —
|
|
2640
|
+
// its marker may be absent or describe something else. Reporting SKIP on
|
|
2641
|
+
// that file is how the stamp stayed wrong across every later run.
|
|
2642
|
+
if (bytes === raw) {
|
|
2343
2643
|
actions.push(`SKIP: ${label} (unchanged${kept})`);
|
|
2344
2644
|
return;
|
|
2345
2645
|
}
|
|
2346
2646
|
|
|
2347
2647
|
mkdirSync(dirname(filePath), { recursive: true });
|
|
2348
|
-
writeFileSync(filePath,
|
|
2349
|
-
|
|
2648
|
+
writeFileSync(filePath, bytes);
|
|
2649
|
+
if (resolved.verb === "SKIP") {
|
|
2650
|
+
// Body identical, marker not. Said plainly rather than as `UPDATED (+0
|
|
2651
|
+
// lines)`, which is the line an operator reads as "my generator change
|
|
2652
|
+
// landed" (#767).
|
|
2653
|
+
actions.push(`UPDATED: ${label} (provenance marker refreshed, +0 lines${kept})`);
|
|
2654
|
+
} else {
|
|
2655
|
+
actions.push(`${resolved.verb}: ${label} (${signed(resolved.lineDelta)} lines${kept}${overwrote})`);
|
|
2656
|
+
}
|
|
2657
|
+
actions.push(...revocationActions(label, resolved.revokedGrants));
|
|
2658
|
+
}
|
|
2659
|
+
|
|
2660
|
+
/**
|
|
2661
|
+
* One line per grant the merge withdrew (#923).
|
|
2662
|
+
*
|
|
2663
|
+
* Its OWN line rather than a parenthetical on the write, and after the write
|
|
2664
|
+
* rather than folded into it. "REPLACED (-74 lines)" is already true of a
|
|
2665
|
+
* re-scaffold that withdraws nothing, so a consumer cannot read a withdrawal
|
|
2666
|
+
* out of it, and the thing being reported is not a line count: a standing
|
|
2667
|
+
* right to mint a credential has been taken away. That is the fact #631 says
|
|
2668
|
+
* nobody audits, and burying it inside a byte-delta is how it goes on not
|
|
2669
|
+
* being audited.
|
|
2670
|
+
*
|
|
2671
|
+
* The reason given is the one THIS layer actually knows — the generator
|
|
2672
|
+
* computes this sub-key and has stopped computing it — and not the config
|
|
2673
|
+
* entry that drove it. The merge cannot see `ci.vertex`; a sentence naming it
|
|
2674
|
+
* here would be a second, unverified reading of the generator's own decision,
|
|
2675
|
+
* and it would be wrong the first time a different sub-key joins the map.
|
|
2676
|
+
*/
|
|
2677
|
+
function revocationActions(label: string, revoked: readonly RevokedSubKey[]): string[] {
|
|
2678
|
+
return revoked.map(
|
|
2679
|
+
r =>
|
|
2680
|
+
`REVOKED: ${label} no longer declares \`${r.section}: ${r.key}\` — the harness ` +
|
|
2681
|
+
`computes that sub-key and this project's \`ci\` config no longer produces it, so ` +
|
|
2682
|
+
`the grant has nothing left to justify it. Name \`${r.section}\` in ` +
|
|
2683
|
+
`\`ci.workflowOverrides\` to keep it, and re-scaffold.`,
|
|
2684
|
+
);
|
|
2685
|
+
}
|
|
2686
|
+
|
|
2687
|
+
/** One globally installed CI tool, and the exact version it is pinned to. */
|
|
2688
|
+
export interface GlobalToolPin {
|
|
2689
|
+
package: string;
|
|
2690
|
+
version: string;
|
|
2691
|
+
}
|
|
2692
|
+
|
|
2693
|
+
export interface GlobalToolDecision {
|
|
2694
|
+
/** YAML spliced into the test job ahead of the test step. Never empty. */
|
|
2695
|
+
step: string;
|
|
2696
|
+
/** What will be installed, in declaration order. */
|
|
2697
|
+
pins: GlobalToolPin[];
|
|
2698
|
+
/** Why this and not something else. */
|
|
2699
|
+
reason: string;
|
|
2700
|
+
/** Declarations refused, each naming itself, so the omission is visible. */
|
|
2701
|
+
rejected: string[];
|
|
2702
|
+
}
|
|
2703
|
+
|
|
2704
|
+
/** An npm package name, optionally scoped. Excludes every shell metacharacter. */
|
|
2705
|
+
const SAFE_GLOBAL_TOOL_PACKAGE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
|
|
2706
|
+
|
|
2707
|
+
/**
|
|
2708
|
+
* An EXACT version. Deliberately not a semver test and deliberately not a
|
|
2709
|
+
* range: `^1.2.0`, `latest` and `next` all resolve to whatever shipped today,
|
|
2710
|
+
* which is the state #597 is about, and admitting one here would be a fix
|
|
2711
|
+
* that looks like the fix while reintroducing the defect.
|
|
2712
|
+
*/
|
|
2713
|
+
const PINNED_GLOBAL_TOOL_VERSION = /^[0-9][A-Za-z0-9.+-]*$/;
|
|
2714
|
+
|
|
2715
|
+
/**
|
|
2716
|
+
* A value on its way into a generated YAML comment.
|
|
2717
|
+
*
|
|
2718
|
+
* Only REJECTED entries ever reach a comment, and they are rejected precisely
|
|
2719
|
+
* because they did not match the two charsets above — so this is the one
|
|
2720
|
+
* place in the generator that formats a string nothing has validated. A
|
|
2721
|
+
* newline in it ends the comment, and the next line is a step.
|
|
2722
|
+
*
|
|
2723
|
+
* That was live, not theoretical. Before this function existed, a config
|
|
2724
|
+
* declaring a package named `pwned\n - name: Injected step\n
|
|
2725
|
+
* run: echo INJECTED` produced a generated `ci.yml` containing exactly that
|
|
2726
|
+
* step, runnable. The version field did the same, and a config pairing one
|
|
2727
|
+
* VALID pin with one evil entry injected through the success path too,
|
|
2728
|
+
* because the refusals string is appended there as well.
|
|
2729
|
+
*
|
|
2730
|
+
* The accepted path does not need this — it is charset-validated and single
|
|
2731
|
+
* quoted, two defences chosen to agree. The rejection path is the one that
|
|
2732
|
+
* handles hostile input by definition, which is what made it the hole: the
|
|
2733
|
+
* branch whose whole job is to refuse an unsafe declaration was the branch
|
|
2734
|
+
* that emitted it verbatim.
|
|
2735
|
+
*/
|
|
2736
|
+
function commentSafe(value: string): string {
|
|
2737
|
+
return value.replace(/[\r\n]+/g, " ").replace(/[^\x20-\x7e]/g, "?").slice(0, 120);
|
|
2738
|
+
}
|
|
2739
|
+
|
|
2740
|
+
/**
|
|
2741
|
+
* The global-install step for the generated CI test job (#597).
|
|
2742
|
+
*
|
|
2743
|
+
* `lib/compliance.ts` decides three Layer 1 verdicts by spawning `agnix` and
|
|
2744
|
+
* `npx @reporails/cli`. CI installed neither, so the registry's mood at that
|
|
2745
|
+
* moment was the verdict — an identical SHA re-ran red to green with no code
|
|
2746
|
+
* change. The versions live in ONE position, `ci.globalTools` in
|
|
2747
|
+
* `.claude/rungate/config.json`; this function carries none of them, for the
|
|
2748
|
+
* same reason `setupBunWith` carries no Bun version (#622) and the test step
|
|
2749
|
+
* carries no command (#488).
|
|
2750
|
+
*
|
|
2751
|
+
* It returns LINES rather than writing, which is what lets a test assert the
|
|
2752
|
+
* emission for a declaration no registry has ever served.
|
|
2753
|
+
*
|
|
2754
|
+
* `npm install -g` rather than `bun add -g`: the consumers are
|
|
2755
|
+
* `probeExternalTool("agnix", …)`, which wants a binary on PATH, and
|
|
2756
|
+
* `npx @reporails/cli`, which resolves through npm.
|
|
2757
|
+
*
|
|
2758
|
+
* The absent case emits a REASON, not silence —
|
|
2759
|
+
* `.claude/rules/config-access.md`: `0`, `{}`, `null` and nothing at all are
|
|
2760
|
+
* indistinguishable from success. Same shape as `typecheckStep` below.
|
|
2761
|
+
*/
|
|
2762
|
+
/**
|
|
2763
|
+
* How many CI shards to split the test files across (#728).
|
|
2764
|
+
*
|
|
2765
|
+
* One exported binding, read off the same `ci` object as its siblings, so
|
|
2766
|
+
* there is one thing to mutate and the generator cannot grow a second
|
|
2767
|
+
* opinion about the shard count.
|
|
2768
|
+
*
|
|
2769
|
+
* **Absent means 1, and 1 means the single-job workflow byte for byte.** A
|
|
2770
|
+
* consumer who has never configured this gets exactly what they have today;
|
|
2771
|
+
* sharding is something a project opts into once its suite is slow enough to
|
|
2772
|
+
* be worth the runners.
|
|
2773
|
+
*
|
|
2774
|
+
* Refuses anything that is not a positive whole number, and refuses silently
|
|
2775
|
+
* upward rather than downward — a malformed value yields 1 (no sharding),
|
|
2776
|
+
* never 0 shards, because a matrix with an empty list runs NO tests and
|
|
2777
|
+
* reports success. `0`, `{}` and `null` are indistinguishable from a clean
|
|
2778
|
+
* result (`.claude/rules/config-access.md`); a suite that ran nothing and a
|
|
2779
|
+
* suite that passed must not produce the same verdict.
|
|
2780
|
+
*
|
|
2781
|
+
* Capped at 32: the shard count becomes a matrix leg, and an unbounded value
|
|
2782
|
+
* read from config is an unbounded number of runners billed to whoever
|
|
2783
|
+
* mistyped it.
|
|
2784
|
+
*/
|
|
2785
|
+
export function shardCount(ci: unknown): number {
|
|
2786
|
+
const raw = (ci as { shards?: unknown } | null | undefined)?.shards;
|
|
2787
|
+
if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1) return 1;
|
|
2788
|
+
return Math.min(raw, 32);
|
|
2789
|
+
}
|
|
2790
|
+
|
|
2791
|
+
/**
|
|
2792
|
+
* Top-level workflow keys this consumer has taken back from the generator
|
|
2793
|
+
* (#839). Declared in `lib/scaffold/managed-workflow.ts`, beside the merge
|
|
2794
|
+
* that consumes it and the notice it makes the merge write.
|
|
2795
|
+
*
|
|
2796
|
+
* Re-exported from here, unmoved as far as every caller is concerned, because
|
|
2797
|
+
* `lib/conformity.ts` needs the same reading (#915) and importing this module
|
|
2798
|
+
* to get it would pull the whole scaffold generator graph — the scanner, the
|
|
2799
|
+
* spec auditor, every generator — into the conformity suite of every consumer
|
|
2800
|
+
* project. `managed-workflow.ts` imports `crypto` and nothing else.
|
|
2801
|
+
*
|
|
2802
|
+
* One binding, so there is one thing to mutate. A second reader in
|
|
2803
|
+
* `conformity.ts` would agree with this one on every input the suite has, and
|
|
2804
|
+
* two deciders that agree are behaviourally one
|
|
2805
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
|
|
2806
|
+
*/
|
|
2807
|
+
export { workflowOverrides } from "./managed-workflow";
|
|
2808
|
+
|
|
2809
|
+
export function globalToolInstallStep(ci: unknown, indent = " "): GlobalToolDecision {
|
|
2810
|
+
const declared = (ci as { globalTools?: unknown } | null | undefined)?.globalTools;
|
|
2811
|
+
const entries =
|
|
2812
|
+
declared !== null && typeof declared === "object" && !Array.isArray(declared)
|
|
2813
|
+
? Object.entries(declared as Record<string, unknown>)
|
|
2814
|
+
: [];
|
|
2815
|
+
|
|
2816
|
+
const pins: GlobalToolPin[] = [];
|
|
2817
|
+
const rejected: string[] = [];
|
|
2818
|
+
for (const [name, raw] of entries) {
|
|
2819
|
+
const version = typeof raw === "string" ? raw.trim() : "";
|
|
2820
|
+
if (!SAFE_GLOBAL_TOOL_PACKAGE.test(name)) {
|
|
2821
|
+
rejected.push(`${commentSafe(name)}@${commentSafe(version) || "(nothing)"} (not an npm package name)`);
|
|
2822
|
+
continue;
|
|
2823
|
+
}
|
|
2824
|
+
if (!PINNED_GLOBAL_TOOL_VERSION.test(version)) {
|
|
2825
|
+
rejected.push(`${commentSafe(name)}@${commentSafe(version) || "(nothing)"} (not an exact version)`);
|
|
2826
|
+
continue;
|
|
2827
|
+
}
|
|
2828
|
+
pins.push({ package: name, version });
|
|
2829
|
+
}
|
|
2830
|
+
|
|
2831
|
+
const refusals = rejected.length === 0 ? "" : ` Refused, and so NOT installed: ${rejected.join("; ")}.`;
|
|
2832
|
+
|
|
2833
|
+
if (pins.length === 0) {
|
|
2834
|
+
const reason =
|
|
2835
|
+
entries.length === 0 ? "the config declares no ci.globalTools" : "every ci.globalTools entry was refused";
|
|
2836
|
+
return { step: `\n${indent}# No global tools installed: ${reason}.${refusals}`, pins, reason, rejected };
|
|
2837
|
+
}
|
|
2838
|
+
|
|
2839
|
+
// Validated AND quoted, chosen to agree: the charset above admits nothing
|
|
2840
|
+
// the single quotes would have to defend against, which is what makes
|
|
2841
|
+
// neither defence a place for the other to be relaxed.
|
|
2842
|
+
const specs = pins.map(p => `'${p.package}@${p.version}'`).join(" ");
|
|
2843
|
+
return {
|
|
2844
|
+
// The versions appear on the `run:` line and nowhere else in the emitted
|
|
2845
|
+
// YAML, so a test asserting the pin is asserting the command rather than
|
|
2846
|
+
// a comment that happens to quote it.
|
|
2847
|
+
step:
|
|
2848
|
+
`\n${indent}# Pinned by ci.globalTools in .claude/rungate/config.json — one declaration (#597).` +
|
|
2849
|
+
(rejected.length === 0 ? "" : `\n${indent}#${refusals}`) +
|
|
2850
|
+
`\n${indent}- name: Install pinned global tools` +
|
|
2851
|
+
`\n${indent} run: npm install -g ${specs}`,
|
|
2852
|
+
pins,
|
|
2853
|
+
reason: `ci.globalTools pins ${pins.map(p => `${p.package}@${p.version}`).join(", ")}`,
|
|
2854
|
+
rejected,
|
|
2855
|
+
};
|
|
2350
2856
|
}
|
|
2351
2857
|
|
|
2858
|
+
/**
|
|
2859
|
+
* The top-level concurrency block for the CI workflow.
|
|
2860
|
+
*
|
|
2861
|
+
* The GROUP does the work here, not the flag. A run can only be cancelled by
|
|
2862
|
+
* another run in the SAME group, so a key that is unique per main commit makes
|
|
2863
|
+
* the question moot — there is never a second occupant to do the cancelling.
|
|
2864
|
+
*
|
|
2865
|
+
* #937 tried the other arrangement: a ref-keyed group with
|
|
2866
|
+
* `cancel-in-progress: ${{ github.event_name == 'pull_request' }}`. It does not
|
|
2867
|
+
* work. Measured on this repository's own main after it shipped (#952): three
|
|
2868
|
+
* push runs cancelled inside eight minutes with that expression in the file,
|
|
2869
|
+
* one of them one second after the next run was created, and every cancelled
|
|
2870
|
+
* run had job count 0 — cancellation at queue time. The mechanism is
|
|
2871
|
+
* UNMEASURED; the leading hypothesis is that the result coerces to the
|
|
2872
|
+
* non-empty string "false", which is truthy. This form does not depend on
|
|
2873
|
+
* knowing which, and that is the point of choosing it.
|
|
2874
|
+
*
|
|
2875
|
+
* The three events:
|
|
2876
|
+
*
|
|
2877
|
+
* - A pull request's ref is `refs/pull/<n>/merge`, unique to that PR, so a
|
|
2878
|
+
* new push to PR #5 can only ever cancel PR #5. Superseding it is the
|
|
2879
|
+
* point: the older commit's result is about code nobody will merge.
|
|
2880
|
+
*
|
|
2881
|
+
* - A push to main shares ONE ref with every other push to main. Two merges
|
|
2882
|
+
* landing within a few minutes cancel the first, and the first is the only
|
|
2883
|
+
* run that ever builds that commit — a gap in main's history with no red
|
|
2884
|
+
* check anywhere to say so. Measured on one consumer: five cancelled runs,
|
|
2885
|
+
* all of them main pushes, and the `test` job runs on main push there, so
|
|
2886
|
+
* what was lost was a test result and not just a container build. The repo
|
|
2887
|
+
* and the run IDs are on #937 — the harness does not name its consumers
|
|
2888
|
+
* (#304), and `test/anti.test.ts` SC-A1 is the check that says so.
|
|
2889
|
+
*
|
|
2890
|
+
* - `merge_group` must not be cancelled either. A queue entry builds its own
|
|
2891
|
+
* `gh-readonly-queue/...` ref, so it is already alone in its group, and
|
|
2892
|
+
* cancelling one mid-flight dequeues the PR behind it.
|
|
2893
|
+
*
|
|
2894
|
+
* So: a push keys on `github.sha`, unique per commit and therefore never
|
|
2895
|
+
* shared. Everything else keys on `github.ref`, which is unique per pull
|
|
2896
|
+
* request and per queue entry but STABLE across pushes to the same PR — which
|
|
2897
|
+
* is what lets a PR supersede itself, the one case where cancelling is right.
|
|
2898
|
+
*
|
|
2899
|
+
* This is a SUB-KEY merge under `mergeManagedWorkflow`: a consumer that already
|
|
2900
|
+
* declares `cancel-in-progress` keeps its own value, and this reaches only the
|
|
2901
|
+
* consumers that have no concurrency block at all.
|
|
2902
|
+
*/
|
|
2903
|
+
export const CI_CONCURRENCY = `# The GROUP does the work here, not the flag. A run is only ever cancelled by
|
|
2904
|
+
# another run in the SAME group, so keying a push on its own commit makes the
|
|
2905
|
+
# question moot: there is never a second occupant to do the cancelling.
|
|
2906
|
+
#
|
|
2907
|
+
# A push to \`main\` keys on \`github.sha\`, unique per commit. Every other main
|
|
2908
|
+
# run is in a different group and nothing can cancel it. That matters because
|
|
2909
|
+
# a main run is the ONLY run that will ever build that commit, so losing it
|
|
2910
|
+
# leaves a gap in main's history with no red check anywhere saying so.
|
|
2911
|
+
#
|
|
2912
|
+
# Everything else keys on \`github.ref\`: unique per pull request
|
|
2913
|
+
# (\`refs/pull/<n>/merge\`) and per merge-queue entry
|
|
2914
|
+
# (\`gh-readonly-queue/...\`), but STABLE across pushes to the same pull
|
|
2915
|
+
# request — which is what lets a pull request supersede itself, the one case
|
|
2916
|
+
# where cancelling is the right answer.
|
|
2917
|
+
#
|
|
2918
|
+
# Do NOT "simplify" this to a ref-keyed group with an event expression in
|
|
2919
|
+
# cancel-in-progress. That was tried and measured: three main-push runs
|
|
2920
|
+
# cancelled inside eight minutes with the expression in place.
|
|
2921
|
+
concurrency:
|
|
2922
|
+
group: ci-\${{ github.event_name == 'push' && github.sha || github.ref }}
|
|
2923
|
+
cancel-in-progress: true
|
|
2924
|
+
`;
|
|
2925
|
+
|
|
2352
2926
|
export function createCiWorkflows(root: string, actions: string[], opts: { force?: boolean } = {}): void {
|
|
2353
2927
|
const workflowsDir = join(root, ".github", "workflows");
|
|
2354
2928
|
if (!existsSync(workflowsDir)) {
|
|
@@ -2356,7 +2930,17 @@ export function createCiWorkflows(root: string, actions: string[], opts: { force
|
|
|
2356
2930
|
}
|
|
2357
2931
|
|
|
2358
2932
|
const harness = loadHarnessConfig(root);
|
|
2359
|
-
|
|
2933
|
+
// #622. This was `harness?.ci?.bunVersion || "latest"`, emitted at the two
|
|
2934
|
+
// sites below, while the two hand-owned workflow files this generator never
|
|
2935
|
+
// touches named versions of their own — four positions, three spellings,
|
|
2936
|
+
// and nothing comparing any of them. (Neither of those filenames is spelled
|
|
2937
|
+
// here: test/release-guard.test.ts asserts this module names no workflow it
|
|
2938
|
+
// does not write, and prose is indistinguishable from a write to it.) The
|
|
2939
|
+
// decision and the YAML it becomes are now `lib/bun-version.ts`'s, for the
|
|
2940
|
+
// same reason #87 took the typecheck step and #488 took the test step: two
|
|
2941
|
+
// sites that agree today are one decider too many, and only a mutation of a
|
|
2942
|
+
// SHARED binding can show the agreement is load-bearing.
|
|
2943
|
+
const bunStep = setupBunWith(declaredBunVersion(root), " ");
|
|
2360
2944
|
const runner = harness?.ci?.runner || "ubuntu-latest";
|
|
2361
2945
|
const branches = harness?.ci?.branches || ["main"];
|
|
2362
2946
|
// Branch patterns are globs: a bare `*` is a YAML alias indicator and `*-dev`
|
|
@@ -2393,16 +2977,51 @@ export function createCiWorkflows(root: string, actions: string[], opts: { force
|
|
|
2393
2977
|
// is the gap, not the absence of a validator.
|
|
2394
2978
|
const baseBranch = String(branches[0] ?? "main");
|
|
2395
2979
|
const SAFE_BRANCH = /^[A-Za-z0-9][A-Za-z0-9._\/-]*$/;
|
|
2980
|
+
// #987. This step used to be unconditionally `--depth=200`, and that flag is
|
|
2981
|
+
// what made `fetch-depth: 0` above it inert: a bounded `git fetch`
|
|
2982
|
+
// RE-SHALLOWS a repository that was already complete. Measured on a complete
|
|
2983
|
+
// 40-commit clone, `is-shallow-repository` goes false → true and
|
|
2984
|
+
// `rev-list --count HEAD` drops 40 → 20. The depth is therefore derived from
|
|
2985
|
+
// the checkout's own, in `lib/ci-history-depth.ts`, rather than written here
|
|
2986
|
+
// as a second number that has to agree with the first.
|
|
2987
|
+
//
|
|
2988
|
+
// Unbounded is not expensive in the full-history case: the objects are
|
|
2989
|
+
// already local, so the fetch updates a ref and transfers nothing.
|
|
2990
|
+
const baseDepth = baseRefFetchDepth(CI_SUITE_FETCH_DEPTH);
|
|
2991
|
+
const baseDepthFlag = baseDepth === null ? "" : `--depth=${baseDepth} `;
|
|
2992
|
+
|
|
2993
|
+
// #987. `actions/checkout` with nothing declared clones ONE commit, so every
|
|
2994
|
+
// generated job that reads git history has been reading one commit since the
|
|
2995
|
+
// first workflow this harness wrote. `lib/failure-intake.ts` refuses a
|
|
2996
|
+
// shallow clone by name, which means its reading was UNMEASURED on every run
|
|
2997
|
+
// on every runner — uniformly absent rather than occasionally missing, and
|
|
2998
|
+
// absence looked like quiet.
|
|
2999
|
+
//
|
|
3000
|
+
// Both generated jobs declare it, not just the suite job. `test/scaffold-
|
|
3001
|
+
// conformity.test.ts` calls `runDocHygiene`, HYGIENE-6 inside it is the
|
|
3002
|
+
// intake's only caller, and the gates job names that file directly while the
|
|
3003
|
+
// suite job reaches it through the test command.
|
|
3004
|
+
//
|
|
3005
|
+
// The cost, measured on this repository three times each: depth 1 is
|
|
3006
|
+
// 1.23–1.64s for 6MB, full history is 1.43–1.64s for 13MB. A bounded middle
|
|
3007
|
+
// was measured too and is the worst of the three — 1.54–2.75s for 9MB, and
|
|
3008
|
+
// still UNMEASURED, because a shallow clone is shallow whatever its depth.
|
|
3009
|
+
const checkoutStep = ` - uses: ${actionRef("actions/checkout")}
|
|
3010
|
+
with:
|
|
3011
|
+
# Full history. A bounded depth leaves .git/shallow behind, and
|
|
3012
|
+
# lib/failure-intake.ts refuses on that file rather than on a commit
|
|
3013
|
+
# count — so any bounded value here reports UNMEASURED (#987).
|
|
3014
|
+
# Declared once, in lib/ci-history-depth.ts.
|
|
3015
|
+
fetch-depth: ${CI_SUITE_FETCH_DEPTH}`;
|
|
2396
3016
|
const baseRefStep =
|
|
2397
3017
|
SAFE_BRANCH.test(baseBranch) && !baseBranch.includes("..")
|
|
2398
|
-
? //
|
|
2399
|
-
//
|
|
2400
|
-
//
|
|
2401
|
-
//
|
|
2402
|
-
// is a few hundred KB and spans months of this project's history.
|
|
3018
|
+
? // The conformity ratchet only diffs the tip and was happy with one
|
|
3019
|
+
// commit, but a tip with no history behind it makes any check that
|
|
3020
|
+
// reads the recent log unmeasurable — and an empty log is
|
|
3021
|
+
// indistinguishable from a clean one.
|
|
2403
3022
|
` - name: Fetch the comparison base for the conformity ratchet
|
|
2404
3023
|
run: |
|
|
2405
|
-
git fetch --no-tags
|
|
3024
|
+
git fetch --no-tags ${baseDepthFlag}origin '+refs/heads/${baseBranch}:refs/remotes/origin/${baseBranch}' \\
|
|
2406
3025
|
|| echo "WARN: could not fetch ${baseBranch}; the conformity allowlist growth check will report UNMEASURED."`
|
|
2407
3026
|
: // Not a fetchable ref: a glob pattern, a leading dash, or a traversal
|
|
2408
3027
|
// segment. Emitted as a comment so the omission is visible in the
|
|
@@ -2422,15 +3041,149 @@ export function createCiWorkflows(root: string, actions: string[], opts: { force
|
|
|
2422
3041
|
// `dev.typeCheck` read (#87). This site used to check for
|
|
2423
3042
|
// `scripts/typecheck.ts` on disk, a branch `files:` makes unreachable for
|
|
2424
3043
|
// every consumer, and never looked at a project's own `typecheck` script.
|
|
3044
|
+
// #488. This was `- run: bun test`, hardcoded, while `harness` was in
|
|
3045
|
+
// scope and three of its siblings read `harness?.ci?.*` four lines above.
|
|
3046
|
+
// Same binding AGENTS.md's Commands row and the agent briefs read, for the
|
|
3047
|
+
// same reason the typecheck step below it got one in #87: two sites that
|
|
3048
|
+
// agree today are one decider too many, and only a mutation of a shared
|
|
3049
|
+
// binding can show the agreement is load-bearing.
|
|
3050
|
+
const test = testCommandDecision(root);
|
|
3051
|
+
|
|
3052
|
+
// #597. The Layer 1 compliance checks shell out to agnix and
|
|
3053
|
+
// @reporails/cli; CI installed neither, so what the registry served at that
|
|
3054
|
+
// moment decided the verdict. Pinned from the one declaration, never a
|
|
3055
|
+
// literal here.
|
|
3056
|
+
const globalTools = globalToolInstallStep(harness?.ci);
|
|
3057
|
+
|
|
2425
3058
|
const typecheck = typecheckDecision(root);
|
|
2426
3059
|
const typecheckStep = typecheck.command
|
|
2427
3060
|
? `\n - run: ${typecheck.command}`
|
|
2428
3061
|
: `\n # No type check: ${typecheck.reason}.`;
|
|
2429
3062
|
|
|
2430
|
-
|
|
3063
|
+
// #728. A suite is a wall every branch pays, and this one was 313s of a
|
|
3064
|
+
// 376s run — one `bun test` on one runner, 13,562 tests, while `strict`
|
|
3065
|
+
// branch protection makes every merge re-run it. Sharding splits the FILES
|
|
3066
|
+
// across runners, which is not the same lever as `--parallel`: that one was
|
|
3067
|
+
// tried, and #621 records it starving 122 I/O-bound tests past bun's
|
|
3068
|
+
// per-test timeout so every ship run reported SHIP_PASSED_SUITE_FAILED over
|
|
3069
|
+
// a tree with zero real failures. Separate runners give each shard a whole
|
|
3070
|
+
// machine, so the starvation mechanism is absent by construction.
|
|
3071
|
+
//
|
|
3072
|
+
// Opt-in, and absent config means one shard and the single-job shape byte
|
|
3073
|
+
// for byte — a consumer who has never heard of this gets what they have
|
|
3074
|
+
// today. `shard` is read from the same `harness?.ci` binding as every
|
|
3075
|
+
// sibling above rather than a second reader.
|
|
3076
|
+
const shards = shardCount(harness?.ci);
|
|
3077
|
+
|
|
3078
|
+
// #839. Which top-level keys this consumer has taken back, read from the
|
|
3079
|
+
// same binding as every sibling above rather than a second reader. Absent
|
|
3080
|
+
// config means none, and none means the generator's structural keys reach
|
|
3081
|
+
// every workflow it has ever written — which is the whole point of the
|
|
3082
|
+
// change this config exists to make reversible.
|
|
3083
|
+
const declined = workflowOverrides(harness?.ci);
|
|
3084
|
+
|
|
3085
|
+
// The required status check is the JOB NAME, and a matrix renames it:
|
|
3086
|
+
// `test` becomes `test (1)`, `test (2)`. A repo whose protection requires
|
|
3087
|
+
// `test` would then require a context nothing ever reports, and GitHub
|
|
3088
|
+
// treats an absent required check as pending forever — every PR wedged,
|
|
3089
|
+
// with no error anywhere saying why. So the matrix is `test-shard` and a
|
|
3090
|
+
// dependent job keeps the name `test`, which is the context protection
|
|
3091
|
+
// already names. Do not collapse these two jobs.
|
|
3092
|
+
const ciYml = shards > 1
|
|
3093
|
+
? `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
|
|
3094
|
+
name: CI
|
|
3095
|
+
|
|
3096
|
+
on:
|
|
3097
|
+
# Re-run this workflow on demand, on any ref. Without the trigger the
|
|
3098
|
+
# Actions API refuses with \`HTTP 422: Workflow does not have
|
|
3099
|
+
# 'workflow_dispatch' trigger\` — measured on 2026-10-21 across the fleet,
|
|
3100
|
+
# where 5 of 6 re-run attempts came back 422. The cost is not the button: a
|
|
3101
|
+
# flake cannot be told from a real failure without pushing an empty commit,
|
|
3102
|
+
# and a fix landed on the default branch cannot be confirmed until unrelated
|
|
3103
|
+
# traffic happens to arrive (#940).
|
|
3104
|
+
workflow_dispatch:
|
|
3105
|
+
# merge_group carries NO branches: filter, deliberately. A merge queue builds
|
|
3106
|
+
# a temporary \`gh-readonly-queue/<base>/...\` ref, which no branch list here
|
|
3107
|
+
# would match — so filtering it is the same as not handling the event, and a
|
|
3108
|
+
# trigger that is present and inert is worse than an absent one because the
|
|
3109
|
+
# file then reads as handling it.
|
|
3110
|
+
#
|
|
3111
|
+
# Without this trigger a merge queue cannot work at all, and it fails in the
|
|
3112
|
+
# worst available way: the queue waits for a required check that will never
|
|
3113
|
+
# report, every entry sits pending with no error anywhere, and the repo looks
|
|
3114
|
+
# like it has simply stopped merging. UNMEASURED, not red.
|
|
3115
|
+
#
|
|
3116
|
+
# This is the SHARDED body, and it is the one that matters most: the required
|
|
3117
|
+
# context is the \`test\` aggregate below, which only exists here. The first
|
|
3118
|
+
# draft of #765 added the trigger to the unsharded body only — 91 tests passed
|
|
3119
|
+
# and the repo that needed it was untouched.
|
|
3120
|
+
merge_group:
|
|
3121
|
+
push:
|
|
3122
|
+
branches:
|
|
3123
|
+
${branchList}
|
|
3124
|
+
pull_request:
|
|
3125
|
+
branches:
|
|
3126
|
+
${branchList}
|
|
3127
|
+
|
|
3128
|
+
${CI_CONCURRENCY}
|
|
3129
|
+
permissions:
|
|
3130
|
+
# Least privilege, and it matters most on the consumers. A workflow with
|
|
3131
|
+
# no permissions: block inherits the REPOSITORY default, which is a setting
|
|
3132
|
+
# the harness does not control and cannot read at generation time. Measured
|
|
3133
|
+
# 2026-10-20 across the consumers this harness serves: the default is
|
|
3134
|
+
# read-only on some and WRITE on others, so a generated job that declares
|
|
3135
|
+
# nothing holds a push-capable GITHUB_TOKEN wherever the default is write.
|
|
3136
|
+
# Neither job needs it: both check out, install and run tests.
|
|
3137
|
+
contents: read
|
|
3138
|
+
|
|
3139
|
+
jobs:
|
|
3140
|
+
test-shard:
|
|
3141
|
+
runs-on: ${runsOn}
|
|
3142
|
+
strategy:
|
|
3143
|
+
# One red shard must not cancel the others: the whole point is to see
|
|
3144
|
+
# every failure in one run rather than re-running to find the next.
|
|
3145
|
+
fail-fast: false
|
|
3146
|
+
matrix:
|
|
3147
|
+
shard: [${Array.from({ length: shards }, (_, i) => i + 1).join(", ")}]
|
|
3148
|
+
steps:
|
|
3149
|
+
${checkoutStep}
|
|
3150
|
+
${baseRefStep}
|
|
3151
|
+
- uses: ${actionRef("oven-sh/setup-bun")}
|
|
3152
|
+
with:
|
|
3153
|
+
${bunStep}
|
|
3154
|
+
- run: bun install${globalTools.step}${ciSetupStep()}
|
|
3155
|
+
- run: ${test.command} --shard=\${{ matrix.shard }}/${shards}${typecheckStep}
|
|
3156
|
+
|
|
3157
|
+
# The aggregate. Named "test" because that is the context branch protection
|
|
3158
|
+
# requires; it exists to turn N shard results into the one verdict.
|
|
3159
|
+
test:
|
|
3160
|
+
runs-on: ${runsOn}
|
|
3161
|
+
needs: test-shard
|
|
3162
|
+
# always() so a failed or cancelled shard reaches this job instead of
|
|
3163
|
+
# skipping it. A skipped required check is not a failed one, and some
|
|
3164
|
+
# protection configurations read a skip as satisfied — which would make
|
|
3165
|
+
# this aggregate a gate that cannot refuse.
|
|
3166
|
+
if: always()
|
|
3167
|
+
steps:
|
|
3168
|
+
- name: Every shard passed
|
|
3169
|
+
run: |
|
|
3170
|
+
result='\${{ needs.test-shard.result }}'
|
|
3171
|
+
if [ "$result" != "success" ]; then
|
|
3172
|
+
echo "::error::test-shard concluded '$result' — the suite is not green."
|
|
3173
|
+
exit 1
|
|
3174
|
+
fi
|
|
3175
|
+
echo "All ${shards} shards passed."
|
|
3176
|
+
`
|
|
3177
|
+
: `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
|
|
2431
3178
|
name: CI
|
|
2432
3179
|
|
|
2433
3180
|
on:
|
|
3181
|
+
# See the sharded body above: a re-run of this workflow is a 422 without
|
|
3182
|
+
# this trigger, so a flake and a real failure are indistinguishable.
|
|
3183
|
+
workflow_dispatch:
|
|
3184
|
+
# See the sharded body above: no branches: filter, and its absence hangs a
|
|
3185
|
+
# merge queue silently rather than failing it.
|
|
3186
|
+
merge_group:
|
|
2434
3187
|
push:
|
|
2435
3188
|
branches:
|
|
2436
3189
|
${branchList}
|
|
@@ -2438,23 +3191,40 @@ ${branchList}
|
|
|
2438
3191
|
branches:
|
|
2439
3192
|
${branchList}
|
|
2440
3193
|
|
|
3194
|
+
${CI_CONCURRENCY}
|
|
3195
|
+
permissions:
|
|
3196
|
+
# Least privilege, and it matters most on the consumers. A workflow with
|
|
3197
|
+
# no permissions: block inherits the REPOSITORY default, which is a setting
|
|
3198
|
+
# the harness does not control and cannot read at generation time. Measured
|
|
3199
|
+
# 2026-10-20 across the consumers this harness serves: the default is
|
|
3200
|
+
# read-only on some and WRITE on others, so a generated job that declares
|
|
3201
|
+
# nothing holds a push-capable GITHUB_TOKEN wherever the default is write.
|
|
3202
|
+
# Neither job needs it: both check out, install and run tests.
|
|
3203
|
+
contents: read
|
|
3204
|
+
|
|
2441
3205
|
jobs:
|
|
2442
3206
|
test:
|
|
2443
3207
|
runs-on: ${runsOn}
|
|
2444
3208
|
steps:
|
|
2445
|
-
|
|
3209
|
+
${checkoutStep}
|
|
2446
3210
|
${baseRefStep}
|
|
2447
|
-
- uses: oven-sh/setup-bun
|
|
3211
|
+
- uses: ${actionRef("oven-sh/setup-bun")}
|
|
2448
3212
|
with:
|
|
2449
|
-
|
|
2450
|
-
- run: bun install
|
|
2451
|
-
- run:
|
|
3213
|
+
${bunStep}
|
|
3214
|
+
- run: bun install${globalTools.step}${ciSetupStep()}
|
|
3215
|
+
- run: ${test.command}${typecheckStep}
|
|
2452
3216
|
`;
|
|
2453
3217
|
|
|
2454
3218
|
const gatesYml = `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
|
|
2455
3219
|
name: Gates
|
|
2456
3220
|
|
|
2457
3221
|
on:
|
|
3222
|
+
# See ci.yml above: without this the Actions API refuses a re-run with a
|
|
3223
|
+
# 422, and the gates are the checks most worth re-running on their own.
|
|
3224
|
+
workflow_dispatch:
|
|
3225
|
+
# See ci.yml above: a merge queue builds a ref no branch list matches, so
|
|
3226
|
+
# this trigger carries no filter and its absence hangs the queue silently.
|
|
3227
|
+
merge_group:
|
|
2458
3228
|
push:
|
|
2459
3229
|
branches:
|
|
2460
3230
|
${branchList}
|
|
@@ -2462,14 +3232,24 @@ ${branchList}
|
|
|
2462
3232
|
branches:
|
|
2463
3233
|
${branchList}
|
|
2464
3234
|
|
|
3235
|
+
permissions:
|
|
3236
|
+
# Least privilege, and it matters most on the consumers. A workflow with
|
|
3237
|
+
# no permissions: block inherits the REPOSITORY default, which is a setting
|
|
3238
|
+
# the harness does not control and cannot read at generation time. Measured
|
|
3239
|
+
# 2026-10-20 across the consumers this harness serves: the default is
|
|
3240
|
+
# read-only on some and WRITE on others, so a generated job that declares
|
|
3241
|
+
# nothing holds a push-capable GITHUB_TOKEN wherever the default is write.
|
|
3242
|
+
# Neither job needs it: both check out, install and run tests.
|
|
3243
|
+
contents: read
|
|
3244
|
+
|
|
2465
3245
|
jobs:
|
|
2466
3246
|
gates:
|
|
2467
3247
|
runs-on: ${runsOn}
|
|
2468
3248
|
steps:
|
|
2469
|
-
|
|
2470
|
-
- uses: oven-sh/setup-bun
|
|
3249
|
+
${checkoutStep}
|
|
3250
|
+
- uses: ${actionRef("oven-sh/setup-bun")}
|
|
2471
3251
|
with:
|
|
2472
|
-
|
|
3252
|
+
${bunStep}
|
|
2473
3253
|
- run: bun install
|
|
2474
3254
|
- name: Conformity + spec drift
|
|
2475
3255
|
run: bun test test/scaffold-conformity.test.ts
|
|
@@ -2486,6 +3266,9 @@ jobs:
|
|
|
2486
3266
|
# CLAIM parity while CI carried 3 patterns and the hook carried 8 —
|
|
2487
3267
|
# CI missed gho_, ghs_, github_pat_, sk-ant- and PEM private keys
|
|
2488
3268
|
# entirely. Asserted now in test/unit/secret-patterns.test.ts.
|
|
3269
|
+
# Tier 1 also owns the signed JWT, because it is the one unquoted
|
|
3270
|
+
# credential whose shape is a dotted identifier path and so is
|
|
3271
|
+
# excused by the tier-2 exclusion below (#863).
|
|
2489
3272
|
if git grep -I -lE '${tier1Ere()}' -- .; then
|
|
2490
3273
|
echo "::error::Potential secrets detected in tracked files"
|
|
2491
3274
|
exit 1
|
|
@@ -2497,8 +3280,14 @@ jobs:
|
|
|
2497
3280
|
# NOTE: do NOT append "|| true" to the assignment below. It makes the
|
|
2498
3281
|
# assignment itself succeed, so $? is always 0 and the error branch
|
|
2499
3282
|
# becomes dead code — the scan would fail open on a git error.
|
|
3283
|
+
# -i on tier 2 only, never on the tier-1 scan above: tier 1 matches
|
|
3284
|
+
# anchored key FORMATS whose case is part of the format, and it has
|
|
3285
|
+
# no allowlist to absorb a false positive. The flag is interpolated
|
|
3286
|
+
# from lib/secret-patterns.ts rather than typed here, because four
|
|
3287
|
+
# hand-written flags are four things that can disagree about what
|
|
3288
|
+
# counts as a secret (#844).
|
|
2500
3289
|
set +e
|
|
2501
|
-
tier2=$(git grep -I -hoE '(
|
|
3290
|
+
tier2=$(git grep -I -hoE ${TIER2_GREP_CASE_FLAG} '${tier2Ere()}' -- .)
|
|
2502
3291
|
rc=$?
|
|
2503
3292
|
set -e
|
|
2504
3293
|
# git grep: 0 = match, 1 = no match, >1 = real error.
|
|
@@ -2509,26 +3298,196 @@ jobs:
|
|
|
2509
3298
|
# Exclusion applies to the extracted VALUE, not the whole line.
|
|
2510
3299
|
# Matching anywhere on the line let a trailing "# placeholder"
|
|
2511
3300
|
# launder a real secret past the check.
|
|
2512
|
-
|
|
3301
|
+
# It reads case the same way the capture does, for a reason
|
|
3302
|
+
# recorded in lib/secret-patterns.ts: the population the capture
|
|
3303
|
+
# newly sees is mostly .env.example, where a non-value is spelled
|
|
3304
|
+
# CHANGEME and PLACEHOLDER (#844).
|
|
3305
|
+
# The last alternative excuses a DOTTED IDENTIFIER PATH, anchored at
|
|
3306
|
+
# both ends so the whole value must be one. The value charset has no
|
|
3307
|
+
# quote characters, so in source tier 2 only ever sees an unquoted
|
|
3308
|
+
# value, and an unquoted value is an expression: apiKey:
|
|
3309
|
+
# config.judge.apiKey is a property reference, not a credential
|
|
3310
|
+
# (#863). A JWT has the same shape and is a credential, which is why
|
|
3311
|
+
# the tier-1 scan above carries it.
|
|
3312
|
+
# The optional dash after the separator is the shell-default
|
|
3313
|
+
# separator, so the placeholder vocabulary can reach the value of a
|
|
3314
|
+
# NAME:-default form. That vocabulary is a closed list of documented
|
|
3315
|
+
# non-values, not a judgement that a value looks harmless: a 32-char
|
|
3316
|
+
# random default carries none of its words and is still reported.
|
|
3317
|
+
if printf '%s\\n' "$tier2" | grep -qvE ${TIER2_GREP_CASE_FLAG} '${TIER2_ALLOWED_VALUE_ERE}'; then
|
|
2513
3318
|
echo "::error::Potential credential assignment in tracked files"
|
|
2514
3319
|
exit 1
|
|
2515
3320
|
fi
|
|
3321
|
+
# Tier 3 — a credential written as a shell default, caught by SHAPE
|
|
3322
|
+
# rather than by a name. Tier 2 can only see one whose variable name
|
|
3323
|
+
# carries credential vocabulary; a variable named for what it holds
|
|
3324
|
+
# is invisible to it, and every neighbouring line in such a block
|
|
3325
|
+
# genuinely is a default, so the one that is not sits in a list of
|
|
3326
|
+
# things that look alike (#848).
|
|
3327
|
+
#
|
|
3328
|
+
# Captured first for the same reason tier 2 is: piping git straight
|
|
3329
|
+
# into the filter turns an error into empty input, which reads as
|
|
3330
|
+
# clean. No "|| true" on the assignment — see the note above.
|
|
3331
|
+
#
|
|
3332
|
+
# No -i here, and that is not an oversight: tier 3 has no vocabulary
|
|
3333
|
+
# to spell in the wrong case. Its classes already cover both cases,
|
|
3334
|
+
# and the flag would only widen the value class.
|
|
3335
|
+
set +e
|
|
3336
|
+
tier3=$(git grep -I -hoE '${tier3Ere()}' -- .)
|
|
3337
|
+
rc=$?
|
|
3338
|
+
set -e
|
|
3339
|
+
if [ "$rc" -gt 1 ]; then
|
|
3340
|
+
echo "::error::git grep failed (exit $rc) — refusing to report a clean scan"
|
|
3341
|
+
exit 1
|
|
3342
|
+
fi
|
|
3343
|
+
# The exclusion is the discriminator, not the length floor: a value
|
|
3344
|
+
# with no digit or no letter is a path, a container name or a port,
|
|
3345
|
+
# and those are what this shape is full of.
|
|
3346
|
+
if printf '%s\\n' "$tier3" | grep -qvE '${TIER3_ALLOWED_VALUE_ERE}'; then
|
|
3347
|
+
echo "::error::Potential credential in a shell default in tracked files"
|
|
3348
|
+
exit 1
|
|
3349
|
+
fi
|
|
2516
3350
|
echo "Secret scan clean"
|
|
2517
3351
|
`;
|
|
2518
3352
|
|
|
3353
|
+
// #630. The ai-review job, and the one property that makes it a check
|
|
3354
|
+
// rather than a decoration: there is NO `if:` here, at job level or step
|
|
3355
|
+
// level. A job skipped by `if:` reports `skipped`, and a skipped required
|
|
3356
|
+
// check can be treated as satisfied — a green required check for a review
|
|
3357
|
+
// that never ran. `secrets` is unavailable in `if:` at any level anyway, so
|
|
3358
|
+
// the mode is resolved inside `run:`, where it can emit an annotation and
|
|
3359
|
+
// choose an exit code. The step text is `buildAuthDetectStep()`'s verbatim,
|
|
3360
|
+
// not a copy: one decider for the script, and a mutation of it has one
|
|
3361
|
+
// binding. See lib/scaffold/ai-review-step.ts.
|
|
3362
|
+
//
|
|
3363
|
+
// `pull_request` and `merge_group`, and NOT `push`. A review of a pull
|
|
3364
|
+
// request has nothing to say about a push to a branch, and a trigger that
|
|
3365
|
+
// fires where the job cannot do its work is a run whose outcome means
|
|
3366
|
+
// nothing.
|
|
3367
|
+
//
|
|
3368
|
+
// `merge_group` is the exception to that sentence, and #867 is why it had to
|
|
3369
|
+
// be. This job was `pull_request`-only on exactly the reasoning above: a
|
|
3370
|
+
// merge group has no pull request, so the review would be vacuous. True, and
|
|
3371
|
+
// the wrong conclusion — it is an argument about what the job can DO on the
|
|
3372
|
+
// event, and it was applied to whether the job REPORTS on it. A consumer
|
|
3373
|
+
// makes `ai-review` a required context precisely because it is the check
|
|
3374
|
+
// that reads the code; a required context that never reports does not fail
|
|
3375
|
+
// the queue, it HANGS it, with every entry pending and nothing red anywhere.
|
|
3376
|
+
//
|
|
3377
|
+
// So the trigger is here and the vacuousness is handled where it belongs, in
|
|
3378
|
+
// the report step, which exits 0 on this event and says in a notice that no
|
|
3379
|
+
// review ran and why. That is sound rather than a green check for nothing: a
|
|
3380
|
+
// pull request cannot enter a merge queue without first satisfying its
|
|
3381
|
+
// required checks, so `ai-review` has already run on that exact head commit.
|
|
3382
|
+
//
|
|
3383
|
+
// No `branches:` filter, for the reason ci.yml states at length: the queue
|
|
3384
|
+
// builds a `gh-readonly-queue/<base>/...` ref that no branch list matches,
|
|
3385
|
+
// so a filtered trigger is an absent one that reads as handled.
|
|
3386
|
+
// #631. Workload Identity Federation, read from the consumer's own config.
|
|
3387
|
+
// One reading, taken here and threaded into both the permission block and
|
|
3388
|
+
// the steps — a second `vertexCiConfig(...)` call beside either would be a
|
|
3389
|
+
// decider that always agrees with this one and could never be told apart
|
|
3390
|
+
// from it (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
|
|
3391
|
+
const vertex = vertexCiConfig(harness?.ci);
|
|
3392
|
+
|
|
3393
|
+
// `id-token: write` is what lets the runner mint the OIDC token GCP's STS
|
|
3394
|
+
// exchanges. Granted ONLY when there is a federation to use it, because a
|
|
3395
|
+
// permission nobody consumes is a permission nobody audits.
|
|
3396
|
+
const aiReviewPermissions =
|
|
3397
|
+
vertex.config === null
|
|
3398
|
+
? `permissions:\n contents: read`
|
|
3399
|
+
: `permissions:\n contents: read\n # Mint the OIDC token Workload Identity Federation exchanges (#631).\n id-token: write`;
|
|
3400
|
+
|
|
3401
|
+
const aiReviewYml = `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
|
|
3402
|
+
#
|
|
3403
|
+
${buildOutcomesHeader(vertex)}#
|
|
3404
|
+
# This job is deliberately unconditional. A job skipped by a condition reports
|
|
3405
|
+
# \`skipped\`, which a required status check can be configured to accept, and
|
|
3406
|
+
# that is a green check for a review that never ran. The credential check
|
|
3407
|
+
# happens inside \`run:\` instead, and reports UNMEASURED when there is none.
|
|
3408
|
+
#
|
|
3409
|
+
# The second step says the same thing for the other door: a credential that
|
|
3410
|
+
# resolved with no reviewer wired to use it (#631) has also not produced a
|
|
3411
|
+
# review, and a check that stays quiet about that is the same defect.
|
|
3412
|
+
#
|
|
3413
|
+
# AUTHENTICATION. There is no service-account key in this file and no input
|
|
3414
|
+
# that could carry one. Vertex authenticates with Workload Identity
|
|
3415
|
+
# Federation: GitHub mints a short-lived OIDC token for this run, GCP's STS
|
|
3416
|
+
# exchanges it for an access token that expires in an hour, and no long-lived
|
|
3417
|
+
# credential exists anywhere on the runner (#677 AC-15). What this job holds
|
|
3418
|
+
# as read from this consumer's config:
|
|
3419
|
+
# ${vertex.reason}
|
|
3420
|
+
name: AI Review
|
|
3421
|
+
|
|
3422
|
+
on:
|
|
3423
|
+
# See the block comment in lib/scaffold/steps.ts: no branches: filter, and
|
|
3424
|
+
# its absence hangs a merge queue silently rather than failing it (#867).
|
|
3425
|
+
merge_group:
|
|
3426
|
+
pull_request:
|
|
3427
|
+
branches:
|
|
3428
|
+
${branchList}
|
|
3429
|
+
|
|
3430
|
+
${aiReviewPermissions}
|
|
3431
|
+
|
|
3432
|
+
jobs:
|
|
3433
|
+
${AI_REVIEW_JOB}:
|
|
3434
|
+
runs-on: ${runsOn}
|
|
3435
|
+
steps:
|
|
3436
|
+
${buildAuthDetectStep(vertex)}${buildReviewRunStep(vertex, {
|
|
3437
|
+
checkout: actionRef("actions/checkout"),
|
|
3438
|
+
auth: actionRef(GOOGLE_AUTH_ACTION),
|
|
3439
|
+
review: actionRef(CLAUDE_CODE_ACTION),
|
|
3440
|
+
})}`;
|
|
3441
|
+
|
|
2519
3442
|
// Not `writeFileSync`. The harness owns the `test` and `gates` jobs; it does
|
|
2520
3443
|
// not own the file, and a consumer's own jobs have to survive the update
|
|
2521
3444
|
// that re-scaffolding IS. A refusal is recorded rather than thrown so that
|
|
2522
3445
|
// one unpreservable workflow does not abandon the rest of the scaffold
|
|
2523
3446
|
// half-done — scripts/scaffold-project.ts exits non-zero on it.
|
|
2524
|
-
|
|
3447
|
+
// The filenames are spelled here, not read from a constant, because
|
|
3448
|
+
// test/release-guard.test.ts pins this tuple as a literal: a directory-wide
|
|
3449
|
+
// write would take the caller-owned workflows with it, and a name behind an
|
|
3450
|
+
// import is a name that assertion cannot see. (That test also asserts this
|
|
3451
|
+
// module names no workflow it does not write — prose is indistinguishable
|
|
3452
|
+
// from a write to it — so the caller-owned files are not spelled anywhere
|
|
3453
|
+
// here, this comment included.) `AI_REVIEW_WORKFLOW_FILE` is the spelling
|
|
3454
|
+
// lib/conformity.ts reads back, and the two are held together by
|
|
3455
|
+
// test/ai-review-workflow.test.ts AC-1, which looks for the constant's
|
|
3456
|
+
// filename in what this loop actually wrote.
|
|
3457
|
+
for (const [name, content] of [["ci.yml", ciYml], ["gates.yml", gatesYml], ["ai-review.yml", aiReviewYml]] as const) {
|
|
2525
3458
|
const label = `.github/workflows/${name}`;
|
|
2526
3459
|
try {
|
|
2527
|
-
|
|
3460
|
+
// Keyed by FILE, and the lookup is here because this loop is the only
|
|
3461
|
+
// place that knows which file is being written (#923).
|
|
3462
|
+
const computedSubKeys = HARNESS_COMPUTED_SUBKEYS.get(name) ?? new Map();
|
|
3463
|
+
// Stamped, so the file says who wrote it. The owned-path list is a list
|
|
3464
|
+
// of files this generator writes, which is precisely why it could never
|
|
3465
|
+
// describe a file it does not write — ownership has to travel with the
|
|
3466
|
+
// bytes for an unowned workflow to be visible at all (#722). The marker
|
|
3467
|
+
// is a YAML comment, so nothing that parses the workflow can see it.
|
|
3468
|
+
writeManagedFile(join(workflowsDir, name), content, label, actions, { ...opts, workflowOverrides: declined, computedSubKeys }, {
|
|
3469
|
+
body: workflowBody,
|
|
3470
|
+
stamp: stampWorkflow,
|
|
3471
|
+
});
|
|
2528
3472
|
} catch (e) {
|
|
2529
3473
|
actions.push(`REFUSED: ${(e as Error).message}`);
|
|
2530
3474
|
}
|
|
2531
3475
|
}
|
|
3476
|
+
|
|
3477
|
+
// #632 AC-14. One line, every scaffold, unconditional. `writeManagedFile`
|
|
3478
|
+
// above already reported that the FILE was written; this reports the thing
|
|
3479
|
+
// writing it does not establish — that the gate it contains is inert until
|
|
3480
|
+
// a credential resolves, which the generator cannot see and must therefore
|
|
3481
|
+
// not guess at. A consumer who reads only the checks list sees a green
|
|
3482
|
+
// `ai-review` and has no reason to look further, and that is #630.
|
|
3483
|
+
actions.push(aiReviewScaffoldAction(vertex));
|
|
3484
|
+
|
|
3485
|
+
// Everything else in the directory, named. This generator writes three
|
|
3486
|
+
// files; a consumer's CI may run any number, and until #722 the ones it did
|
|
3487
|
+
// not write were not merely unmanaged but unreported — a clean run over 2 of
|
|
3488
|
+
// 7 workflow files, which reads exactly like a clean run over 7 of 7.
|
|
3489
|
+
// Reporting only: what a consumer does with a NOT-OWNED workflow is theirs.
|
|
3490
|
+
actions.push(...censusReport(workflowCensus(root)));
|
|
2532
3491
|
}
|
|
2533
3492
|
|
|
2534
3493
|
// ── Consumer hook deployment ─────────────────────────────────
|
|
@@ -2614,6 +3573,62 @@ export function deployHooksToConsumers(root: string, actions: string[]): void {
|
|
|
2614
3573
|
}
|
|
2615
3574
|
}
|
|
2616
3575
|
|
|
3576
|
+
/**
|
|
3577
|
+
* ## The generated pre-commit hook, as one binding (#610)
|
|
3578
|
+
*
|
|
3579
|
+
* ## What was wrong
|
|
3580
|
+
*
|
|
3581
|
+
* The hook decided WHICH updater to run by sniffing the working tree at
|
|
3582
|
+
* commit time:
|
|
3583
|
+
*
|
|
3584
|
+
* updater=""
|
|
3585
|
+
* if [ -f "scripts/update-project-state.ts" ]; then
|
|
3586
|
+
* updater="scripts/update-project-state.ts"
|
|
3587
|
+
* elif [ -f "node_modules/rungate/scripts/update-project-state.ts" ]; then
|
|
3588
|
+
* updater="node_modules/rungate/scripts/update-project-state.ts"
|
|
3589
|
+
* fi
|
|
3590
|
+
*
|
|
3591
|
+
* and the comment above it said the order was deliberate because "a checkout
|
|
3592
|
+
* that has its own scripts/ copy is the harness". That is an identity
|
|
3593
|
+
* inferred from a FILENAME. "This tree holds a file at this path" and "this
|
|
3594
|
+
* tree is the rungate harness" are different facts, and the hook treated the
|
|
3595
|
+
* first as proof of the second — so a consumer that keeps a script at that
|
|
3596
|
+
* path for its own reasons was silently reclassified as the harness and ran a
|
|
3597
|
+
* different program than the one rungate installed. Nothing in the commit
|
|
3598
|
+
* recorded which branch fired, so the two outcomes were indistinguishable
|
|
3599
|
+
* afterwards.
|
|
3600
|
+
*
|
|
3601
|
+
* A detector narrower than what it detects
|
|
3602
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, second shape), with the
|
|
3603
|
+
* *Silent Default Substitution* that `.claude/rules/config-access.md` refuses
|
|
3604
|
+
* sitting underneath it.
|
|
3605
|
+
*
|
|
3606
|
+
* ## What it does instead
|
|
3607
|
+
*
|
|
3608
|
+
* The decision is taken HERE, at generation time, and one concrete path is
|
|
3609
|
+
* baked into the emitted script. The hook names the program it runs; a tree
|
|
3610
|
+
* that acquires a same-named file afterwards cannot change what executes.
|
|
3611
|
+
*
|
|
3612
|
+
* Identity is read from the project's own declaration — `isHarnessItself`,
|
|
3613
|
+
* which reads `package.json`'s `name` and is the single existing binding for
|
|
3614
|
+
* this question in the tree (#380). It is deliberately NOT a second reading
|
|
3615
|
+
* of the same fact: two deciders that agree are behaviourally one, and no
|
|
3616
|
+
* mutation of either could tell them apart.
|
|
3617
|
+
*
|
|
3618
|
+
* ## Three readings, and UNMEASURED is one of them
|
|
3619
|
+
*
|
|
3620
|
+
* | the tree declares | the candidate | emitted |
|
|
3621
|
+
* |---|---|---|
|
|
3622
|
+
* | `name: "rungate"` | `scripts/update-project-state.ts` | that path, baked |
|
|
3623
|
+
* | anything else | `node_modules/rungate/scripts/…` | that path, baked |
|
|
3624
|
+
* | either, candidate absent | — | UNMEASURED, and no lookup at all |
|
|
3625
|
+
*
|
|
3626
|
+
* The third row is the one that must not be a guess. A hook carrying a
|
|
3627
|
+
* lookup "in case the file turns up later" succeeds at some unknown future
|
|
3628
|
+
* commit for a reason nobody chose, and `0`, `""`, `null` and a
|
|
3629
|
+
* plausible-looking path are all indistinguishable from success.
|
|
3630
|
+
*/
|
|
3631
|
+
|
|
2617
3632
|
/**
|
|
2618
3633
|
* The line that marks a pre-commit hook as ours, so a fix can reach one that
|
|
2619
3634
|
* already exists (#450).
|
|
@@ -2627,18 +3642,104 @@ export function deployHooksToConsumers(root: string, actions: string[]): void {
|
|
|
2627
3642
|
*/
|
|
2628
3643
|
export const PRE_COMMIT_MANAGED_MARKER = "# Managed by rungate — secret scan + PROJECT-STATE update";
|
|
2629
3644
|
|
|
2630
|
-
|
|
2631
|
-
|
|
2632
|
-
|
|
3645
|
+
/**
|
|
3646
|
+
* Present in EVERY form this generator emits, resolved or not.
|
|
3647
|
+
*
|
|
3648
|
+
* `scripts/check-installed-hook-currency.ts` probes for it to tell a hook
|
|
3649
|
+
* that predates #610 from one that carries it, and that probe has to work for
|
|
3650
|
+
* a consumer and for the harness alike — so it cannot be either baked path.
|
|
3651
|
+
*/
|
|
3652
|
+
export const UPDATER_GENERATION_MARKER =
|
|
3653
|
+
"# Which updater runs was decided when this hook was generated (#610), not here.";
|
|
2633
3654
|
|
|
2634
|
-
|
|
3655
|
+
/** The harness's own copy, relative to the project root. */
|
|
3656
|
+
export const HARNESS_UPDATER = "scripts/update-project-state.ts";
|
|
2635
3657
|
|
|
2636
|
-
|
|
2637
|
-
|
|
2638
|
-
|
|
2639
|
-
|
|
2640
|
-
|
|
2641
|
-
|
|
3658
|
+
/** The copy rungate installs into a consumer, relative to the project root. */
|
|
3659
|
+
export const VENDORED_UPDATER = "node_modules/rungate/scripts/update-project-state.ts";
|
|
3660
|
+
|
|
3661
|
+
export type UpdaterIdentity = "harness" | "consumer";
|
|
3662
|
+
|
|
3663
|
+
export interface UpdaterResolution {
|
|
3664
|
+
/** What the tree declared itself to be, read from package.json's name. */
|
|
3665
|
+
identity: UpdaterIdentity;
|
|
3666
|
+
/** The one path that identity selects — present or not. */
|
|
3667
|
+
candidate: string;
|
|
3668
|
+
/** The path baked into the hook, or null when the candidate is absent. */
|
|
3669
|
+
path: string | null;
|
|
3670
|
+
}
|
|
3671
|
+
|
|
3672
|
+
/**
|
|
3673
|
+
* The single decider. One binding to mutate, asked once by
|
|
3674
|
+
* `preCommitHookScript` and nowhere else.
|
|
3675
|
+
*/
|
|
3676
|
+
export function resolveUpdater(root: string): UpdaterResolution {
|
|
3677
|
+
const identity: UpdaterIdentity = isHarnessItself(root) ? "harness" : "consumer";
|
|
3678
|
+
const candidate = identity === "harness" ? HARNESS_UPDATER : VENDORED_UPDATER;
|
|
3679
|
+
return {
|
|
3680
|
+
identity,
|
|
3681
|
+
candidate,
|
|
3682
|
+
path: existsSync(join(root, candidate)) ? candidate : null,
|
|
3683
|
+
};
|
|
3684
|
+
}
|
|
3685
|
+
|
|
3686
|
+
const IDENTITY_NOTE: Record<UpdaterIdentity, string> = {
|
|
3687
|
+
harness:
|
|
3688
|
+
"# package.json names this tree as the rungate harness, so the updater is its own\n" +
|
|
3689
|
+
" # scripts/ copy — never a vendored duplicate of itself, which would be stale.",
|
|
3690
|
+
consumer:
|
|
3691
|
+
"# package.json does not name this tree as the harness, so the updater is the copy\n" +
|
|
3692
|
+
" # rungate installed. A script this project keeps at scripts/ is its own program\n" +
|
|
3693
|
+
" # and is not run here, whatever it is called.",
|
|
3694
|
+
};
|
|
3695
|
+
|
|
3696
|
+
/**
|
|
3697
|
+
* The block that goes inside the primary-checkout arm.
|
|
3698
|
+
*
|
|
3699
|
+
* The resolved form contains the path EXACTLY ONCE — in the assignment — so
|
|
3700
|
+
* there is one literal to mutate and one literal for a test to count. The
|
|
3701
|
+
* echo below it reports `$updater` rather than repeating the path, which is
|
|
3702
|
+
* the same reason: a second copy would survive any mutation of the first.
|
|
3703
|
+
*/
|
|
3704
|
+
function updaterBlock(r: UpdaterResolution): string {
|
|
3705
|
+
if (r.path === null) {
|
|
3706
|
+
return ` ${UPDATER_GENERATION_MARKER}
|
|
3707
|
+
${IDENTITY_NOTE[r.identity]}
|
|
3708
|
+
#
|
|
3709
|
+
# Nothing was found there when this hook was generated, so this hook runs
|
|
3710
|
+
# no updater and performs no lookup. A lookup kept "in case it turns up"
|
|
3711
|
+
# would succeed at some later commit for a reason nobody chose.
|
|
3712
|
+
echo "project-state: UNMEASURED — when this hook was generated this tree read as a ${r.identity} checkout and no updater was present at ${r.candidate}. This hook runs none and stages nothing. Re-scaffold once it is installed." >&2`;
|
|
3713
|
+
}
|
|
3714
|
+
return ` ${UPDATER_GENERATION_MARKER}
|
|
3715
|
+
${IDENTITY_NOTE[r.identity]}
|
|
3716
|
+
updater="${r.path}"
|
|
3717
|
+
# Say which program is about to run, before running it. Without this the
|
|
3718
|
+
# commit's output records nothing about which updater fired and the
|
|
3719
|
+
# answer is only recoverable by inspecting the tree afterwards (#610).
|
|
3720
|
+
echo "project-state: running $updater (resolved when this hook was generated)" >&2
|
|
3721
|
+
if bun "$updater" --skip-tests >&2; then
|
|
3722
|
+
# Staged only after the updater SUCCEEDED. Staging regardless is the
|
|
3723
|
+
# fail-open the readings above exist to replace: it puts yesterday's
|
|
3724
|
+
# PROJECT-STATE.md in today's commit, and the commit then looks exactly
|
|
3725
|
+
# like one that updated it.
|
|
3726
|
+
git add PROJECT-STATE.md project-state.json 2>/dev/null || true
|
|
3727
|
+
else
|
|
3728
|
+
echo "project-state: UNMEASURED — $updater exited non-zero, so PROJECT-STATE.md and project-state.json were NOT staged. Run it by hand to see why." >&2
|
|
3729
|
+
fi`;
|
|
3730
|
+
}
|
|
3731
|
+
|
|
3732
|
+
/**
|
|
3733
|
+
* What `createGitHooks` writes, for a given project root.
|
|
3734
|
+
*
|
|
3735
|
+
* A function of the root rather than a constant, because the updater is
|
|
3736
|
+
* resolved here. It writes nothing: `scripts/check-installed-hook-currency.ts`
|
|
3737
|
+
* has to obtain the text for a project it is only INSPECTING, and a generator
|
|
3738
|
+
* that could only answer by installing itself would make the check the thing
|
|
3739
|
+
* it is checking.
|
|
3740
|
+
*/
|
|
3741
|
+
export function preCommitHookScript(root: string): string {
|
|
3742
|
+
return `#!/bin/sh
|
|
2642
3743
|
${PRE_COMMIT_MANAGED_MARKER}
|
|
2643
3744
|
#
|
|
2644
3745
|
# Scans the staged DIFF, not files on disk. This is deliberate and fixes four
|
|
@@ -2678,14 +3779,43 @@ fi
|
|
|
2678
3779
|
# Exclusions are env lookups and explicit non-values. password =
|
|
2679
3780
|
# process.env.DB_PASSWORD is a reference, not a secret, and flagging it would
|
|
2680
3781
|
# only train people to reach for --no-verify.
|
|
3782
|
+
#
|
|
3783
|
+
# Both expressions are interpolated from lib/secret-patterns.ts, never
|
|
3784
|
+
# written here. A hardcoded copy is a second binding for one string, and
|
|
3785
|
+
# #489's narrowing then has to be applied in places nothing compares. The
|
|
3786
|
+
# allowlist's leading \`^$|\` alternative cannot fire on this pipeline —
|
|
3787
|
+
# grep -oE emits no empty lines — so using the one constant is the same
|
|
3788
|
+
# behaviour with one fewer decider.
|
|
3789
|
+
#
|
|
3790
|
+
# -i is on both tier-2 greps and on neither tier-1 one, interpolated from the
|
|
3791
|
+
# same constant the CI job uses. Without it the vocabulary could only see
|
|
3792
|
+
# lowercase, which is the spelling an environment variable or a shell default
|
|
3793
|
+
# is least often written in (#844).
|
|
2681
3794
|
if printf '%s\\n' "$staged_diff" \\
|
|
2682
3795
|
| grep '^+' \\
|
|
2683
|
-
| grep -oE '(
|
|
2684
|
-
| grep -qvE '
|
|
3796
|
+
| grep -oE ${TIER2_GREP_CASE_FLAG} '${tier2Ere()}' \\
|
|
3797
|
+
| grep -qvE ${TIER2_GREP_CASE_FLAG} '${TIER2_ALLOWED_VALUE_ERE}'; then
|
|
2685
3798
|
echo "ERROR: Potential credential assignment in staged changes"
|
|
2686
3799
|
exit 1
|
|
2687
3800
|
fi
|
|
2688
3801
|
|
|
3802
|
+
# Tier 3 — a credential written as a shell default, caught by shape rather
|
|
3803
|
+
# than by the variable name. Tier 2 only sees one whose name carries
|
|
3804
|
+
# credential vocabulary (#848).
|
|
3805
|
+
#
|
|
3806
|
+
# Both expressions are interpolated from lib/secret-patterns.ts for the
|
|
3807
|
+
# reason tier 2's are: a hardcoded copy is a second binding for one string.
|
|
3808
|
+
#
|
|
3809
|
+
# No -i, deliberately. Tier 3 has no vocabulary to miss in the wrong case,
|
|
3810
|
+
# and the flag would only widen the value class.
|
|
3811
|
+
if printf '%s\\n' "$staged_diff" \\
|
|
3812
|
+
| grep '^+' \\
|
|
3813
|
+
| grep -oE '${tier3Ere()}' \\
|
|
3814
|
+
| grep -qvE '${TIER3_ALLOWED_VALUE_ERE}'; then
|
|
3815
|
+
echo "ERROR: Potential credential in a shell default in staged changes"
|
|
3816
|
+
exit 1
|
|
3817
|
+
fi
|
|
3818
|
+
|
|
2689
3819
|
# Update PROJECT-STATE if it exists — but NEVER from a linked worktree (#450).
|
|
2690
3820
|
#
|
|
2691
3821
|
# project-state.json, PROJECT-STATE.md and SUCCESS.md are DA-owned: a single
|
|
@@ -2709,17 +3839,28 @@ fi
|
|
|
2709
3839
|
# linked worktree. An unmeasured guard is indistinguishable from an absent
|
|
2710
3840
|
# one, so it is absent. git hooks run from the toplevel, and both calls share
|
|
2711
3841
|
# a cwd, so there was never a case that needed it.
|
|
3842
|
+
#
|
|
3843
|
+
# The primary arm had three fail-opens in two lines (#599), and the shape is
|
|
3844
|
+
# this file's recurring one: a check that passed because of what it never
|
|
3845
|
+
# looked at. The path was the CONSUMER layout, so in the harness's own
|
|
3846
|
+
# checkout — which has scripts/update-project-state.ts and no
|
|
3847
|
+
# node_modules/rungate at all — bun exited non-zero on a file that is not
|
|
3848
|
+
# there. 2>/dev/null threw the ENOENT away, || true threw the status away, and
|
|
3849
|
+
# the git add below then staged whatever happened to be on disk.
|
|
3850
|
+
#
|
|
3851
|
+
# Every message is on STDERR: stdout is what a caller captures as the
|
|
3852
|
+
# command's answer, and a decline, a reading and an updater's progress are all
|
|
3853
|
+
# diagnosis rather than output.
|
|
2712
3854
|
if [ -f "project-state.json" ]; then
|
|
2713
3855
|
gitdir=$(git rev-parse --git-dir)
|
|
2714
3856
|
commondir=$(git rev-parse --git-common-dir)
|
|
2715
3857
|
if [ -n "$gitdir" ] && [ "$gitdir" = "$commondir" ]; then
|
|
2716
|
-
|
|
2717
|
-
git add PROJECT-STATE.md project-state.json 2>/dev/null || true
|
|
3858
|
+
${updaterBlock(resolveUpdater(root))}
|
|
2718
3859
|
else
|
|
2719
3860
|
# Announced, not silent. A developer who expected the state files to move
|
|
2720
3861
|
# would otherwise be left guessing, and SKIP that says nothing is
|
|
2721
3862
|
# indistinguishable from the update having happened.
|
|
2722
|
-
echo "project-state: SKIPPED — linked worktree. project-state.json, PROJECT-STATE.md and SUCCESS.md are DA-owned (#296); update them from the primary checkout."
|
|
3863
|
+
echo "project-state: SKIPPED — linked worktree. project-state.json, PROJECT-STATE.md and SUCCESS.md are DA-owned (#296); update them from the primary checkout." >&2
|
|
2723
3864
|
fi
|
|
2724
3865
|
fi
|
|
2725
3866
|
|
|
@@ -2728,61 +3869,95 @@ fi
|
|
|
2728
3869
|
# made the hook exit non-zero and reject a perfectly good commit. Everything
|
|
2729
3870
|
# that should block has already exited 1 above.
|
|
2730
3871
|
exit 0
|
|
2731
|
-
|
|
2732
|
-
|
|
2733
|
-
actions.push(
|
|
2734
|
-
existingPreCommit === null
|
|
2735
|
-
? "CREATED: .git/hooks/pre-commit (secret scan + PROJECT-STATE update)"
|
|
2736
|
-
: "UPDATED: .git/hooks/pre-commit (secret scan + PROJECT-STATE update)",
|
|
2737
|
-
);
|
|
2738
|
-
}
|
|
3872
|
+
`;
|
|
3873
|
+
}
|
|
2739
3874
|
|
|
2740
|
-
|
|
2741
|
-
|
|
3875
|
+
/**
|
|
3876
|
+
* One hook the scaffold installs (#891).
|
|
3877
|
+
*
|
|
3878
|
+
* `createGitHooks` used to name each hook in its own paragraph of imperative
|
|
3879
|
+
* code, and `scripts/check-installed-hook-currency.ts` joined the literal
|
|
3880
|
+
* `pre-commit` and compared that one file. Two positions deciding what the
|
|
3881
|
+
* set of hooks is, with nothing comparing them — so the installed `pre-push`
|
|
3882
|
+
* in this repository sat four months and one mutation battery behind its
|
|
3883
|
+
* generator while the currency check printed a verdict about the other hook
|
|
3884
|
+
* and exited 0.
|
|
3885
|
+
*
|
|
3886
|
+
* This is the declaration both of them read. A hook added here is installed
|
|
3887
|
+
* by the loop below AND reported by the checker, without either being
|
|
3888
|
+
* edited; that is the property `test/unit/hook-currency-population.test.ts`
|
|
3889
|
+
* AC-5 plants a case for, and it is what the cheap repair — adding the
|
|
3890
|
+
* string `"pre-push"` to the checker — does not buy.
|
|
3891
|
+
*
|
|
3892
|
+
* `script` takes the project root because the pre-commit hook's content
|
|
3893
|
+
* depends on it (#610): the updater it names is resolved at generation time
|
|
3894
|
+
* from what the project declares itself to be. A hook that does not care
|
|
3895
|
+
* ignores the argument.
|
|
3896
|
+
*/
|
|
3897
|
+
export interface GeneratedHook {
|
|
3898
|
+
/** The file name under the hooks directory, and the name every report uses. */
|
|
3899
|
+
name: string;
|
|
3900
|
+
/** The script this project should have, generated and written nowhere. */
|
|
3901
|
+
script: (root: string) => string;
|
|
3902
|
+
/** The line that marks an installed copy as one of ours. */
|
|
3903
|
+
marker: string;
|
|
3904
|
+
/** What the scaffold's action log calls it. */
|
|
3905
|
+
describes: string;
|
|
3906
|
+
}
|
|
2742
3907
|
|
|
2743
|
-
|
|
2744
|
-
|
|
2745
|
-
|
|
2746
|
-
|
|
2747
|
-
|
|
2748
|
-
|
|
2749
|
-
|
|
2750
|
-
|
|
2751
|
-
|
|
2752
|
-
|
|
2753
|
-
|
|
3908
|
+
export const GENERATED_HOOKS: ReadonlyArray<GeneratedHook> = [
|
|
3909
|
+
{
|
|
3910
|
+
name: "pre-commit",
|
|
3911
|
+
script: preCommitHookScript,
|
|
3912
|
+
marker: PRE_COMMIT_MANAGED_MARKER,
|
|
3913
|
+
describes: "secret scan + PROJECT-STATE update",
|
|
3914
|
+
},
|
|
3915
|
+
{
|
|
3916
|
+
// Checks the COMMITS BEING PUSHED, not the working tree (#85). The old
|
|
3917
|
+
// hook ran conformity in the working tree, which is not what is being
|
|
3918
|
+
// pushed: on 2026-10-05 that let a regression reach main, because
|
|
3919
|
+
// HYGIENE-3's reference index recursed into `.claude/worktrees/` and
|
|
3920
|
+
// every file looked referenced. A gate that inspects something other
|
|
3921
|
+
// than what it is gating is not a weaker gate; it is a different gate
|
|
3922
|
+
// wearing the name of the one you wanted.
|
|
3923
|
+
//
|
|
3924
|
+
// The script itself lives in `lib/scaffold/pre-push-hook.ts` (#397). As
|
|
3925
|
+
// a template literal here it was unrunnable, and the thing nothing runs
|
|
3926
|
+
// is the thing nothing checks.
|
|
3927
|
+
name: "pre-push",
|
|
3928
|
+
script: () => prePushHookScript(),
|
|
3929
|
+
marker: PRE_PUSH_MANAGED_MARKER,
|
|
3930
|
+
describes: "conformity check",
|
|
3931
|
+
},
|
|
3932
|
+
];
|
|
2754
3933
|
|
|
2755
|
-
|
|
2756
|
-
|
|
2757
|
-
|
|
2758
|
-
|
|
2759
|
-
|
|
2760
|
-
|
|
2761
|
-
//
|
|
2762
|
-
//
|
|
2763
|
-
//
|
|
2764
|
-
//
|
|
2765
|
-
|
|
2766
|
-
|
|
2767
|
-
|
|
2768
|
-
|
|
2769
|
-
|
|
2770
|
-
|
|
2771
|
-
|
|
2772
|
-
|
|
2773
|
-
|
|
2774
|
-
|
|
2775
|
-
|
|
2776
|
-
|
|
2777
|
-
|
|
2778
|
-
|
|
2779
|
-
|
|
2780
|
-
|
|
2781
|
-
|
|
2782
|
-
chmodSync(prePush, 0o755);
|
|
2783
|
-
actions.push(existing === null
|
|
2784
|
-
? "CREATED: .git/hooks/pre-push (conformity check)"
|
|
2785
|
-
: "UPDATED: .git/hooks/pre-push (conformity check)");
|
|
3934
|
+
export function createGitHooks(root: string, actions: string[]): void {
|
|
3935
|
+
const hooksDir = join(root, ".git", "hooks");
|
|
3936
|
+
if (!existsSync(hooksDir)) return;
|
|
3937
|
+
|
|
3938
|
+
const { chmodSync } = require("fs");
|
|
3939
|
+
|
|
3940
|
+
// A loop over the declaration, and not four paragraphs. The old shape also
|
|
3941
|
+
// carried a `return` in the pre-push SKIP arm, which was harmless only
|
|
3942
|
+
// because pre-push happened to be last — a third hook would have been
|
|
3943
|
+
// silently skipped for every project with a hand-written pre-push.
|
|
3944
|
+
for (const hook of GENERATED_HOOKS) {
|
|
3945
|
+
const at = join(hooksDir, hook.name);
|
|
3946
|
+
const existing = existsSync(at) ? readFileSync(at, "utf-8") : null;
|
|
3947
|
+
// Overwrite only our own managed hook; a hook a human wrote is left
|
|
3948
|
+
// alone. The old guard here was `if (!existsSync(prePush))`, so once a
|
|
3949
|
+
// hook existed it was never updated again and every fix to it — this one
|
|
3950
|
+
// included — would have reached nobody.
|
|
3951
|
+
if (existing !== null && !existing.includes(hook.marker)) {
|
|
3952
|
+
actions.push(`SKIP: .git/hooks/${hook.name} (hand-written, not overwriting)`);
|
|
3953
|
+
continue;
|
|
3954
|
+
}
|
|
3955
|
+
writeFileSync(at, hook.script(root));
|
|
3956
|
+
chmodSync(at, 0o755);
|
|
3957
|
+
actions.push(
|
|
3958
|
+
`${existing === null ? "CREATED" : "UPDATED"}: .git/hooks/${hook.name} (${hook.describes})`,
|
|
3959
|
+
);
|
|
3960
|
+
}
|
|
2786
3961
|
}
|
|
2787
3962
|
|
|
2788
3963
|
/**
|
|
@@ -3113,7 +4288,7 @@ export function runAuditSpecsFix(root: string, actions: string[]): void {
|
|
|
3113
4288
|
actions.push("SKIP: audit-specs (no specs/ directory)");
|
|
3114
4289
|
return;
|
|
3115
4290
|
}
|
|
3116
|
-
const specFiles =
|
|
4291
|
+
const specFiles = readdirSorted(specsDir).filter(f => f.endsWith(".md"));
|
|
3117
4292
|
if (specFiles.length === 0) {
|
|
3118
4293
|
actions.push("SKIP: audit-specs (no spec files)");
|
|
3119
4294
|
return;
|
|
@@ -3225,15 +4400,64 @@ export function writtenPath(line: string): string | null {
|
|
|
3225
4400
|
return m?.[1] ?? null;
|
|
3226
4401
|
}
|
|
3227
4402
|
|
|
3228
|
-
|
|
4403
|
+
/**
|
|
4404
|
+
* What an action line carries when the run that produced it was a rehearsal.
|
|
4405
|
+
*
|
|
4406
|
+
* **A TRAILING marker, and that is a constraint rather than a preference.**
|
|
4407
|
+
* `writtenPath` above matches `^(?:CREATED|UPDATED|…): path` after a trim,
|
|
4408
|
+
* and two callers depend on it: `postScaffoldCommit` stages by it, and
|
|
4409
|
+
* `test/scaffold-audit-agreement.test.ts` compares the paths audit NAMES
|
|
4410
|
+
* against the paths `--fix` WROTE. A leading `REHEARSED ` prefix — the form
|
|
4411
|
+
* #642 suggests — makes `writtenPath` return null for every audit line, so
|
|
4412
|
+
* that comparison would go green with nothing in it on both sides. Agreement
|
|
4413
|
+
* by both sides reporting nothing is the vacuous shape #398 built it to
|
|
4414
|
+
* avoid.
|
|
4415
|
+
*
|
|
4416
|
+
* Square brackets rather than parentheses on purpose: most action lines
|
|
4417
|
+
* already end in a parenthetical (`(security template)`, `(rungate devDep)`),
|
|
4418
|
+
* and a marker that looks like one more of those is one a reader skims past.
|
|
4419
|
+
*
|
|
4420
|
+
* One exported binding, so there is one thing to mutate and one string for a
|
|
4421
|
+
* consumer to grep.
|
|
4422
|
+
*/
|
|
4423
|
+
export const REHEARSAL_MARKER = " [REHEARSAL — not applied]";
|
|
4424
|
+
|
|
4425
|
+
/**
|
|
4426
|
+
* ## Every line, because a line is the unit a reader consumes (#642)
|
|
4427
|
+
*
|
|
4428
|
+
* The mode was announced exactly once, by `rehearsalNotice`, at the top of
|
|
4429
|
+
* the run — and then no line of the report carried it. Measured on two
|
|
4430
|
+
* planted repositories: **all 56 of an audit's report lines were
|
|
4431
|
+
* byte-identical to the lines `--fix` printed for the same work.** So
|
|
4432
|
+
* `grep ci.yml`, `| tail -25`, a scrolled terminal, and an agent reading the
|
|
4433
|
+
* last N lines of a tool result all received `REPLACED: … (+114 lines)` with
|
|
4434
|
+
* no way to tell it from a write that landed. The issue's author read one
|
|
4435
|
+
* four times and filed a missing-write bug off it. The report never lied;
|
|
4436
|
+
* its unit of qualification was wider than its unit of consumption.
|
|
4437
|
+
*
|
|
4438
|
+
* `mode` is REQUIRED rather than defaulted. A default of `false` is a silent
|
|
4439
|
+
* default substitution (`.claude/rules/config-access.md`): a future call site
|
|
4440
|
+
* that forgets to say which mode it is in would print unqualified lines and
|
|
4441
|
+
* look exactly like one that meant to.
|
|
4442
|
+
*
|
|
4443
|
+
* **Not sufficient: marking the `Total:` line, or the first line.** That is
|
|
4444
|
+
* the cheapest repair and it leaves every grep/tail/scrolled consumer in
|
|
4445
|
+
* precisely the position the issue is about. The `Total:` line is marked as
|
|
4446
|
+
* well, but after the per-line marking, not instead of it.
|
|
4447
|
+
*/
|
|
4448
|
+
export function reportScaffoldActions(actions: string[], mode: { rehearsed: boolean }): number {
|
|
4449
|
+
const qualify = (line: string) => (mode.rehearsed ? `${line}${REHEARSAL_MARKER}` : line);
|
|
3229
4450
|
console.log("\n=== Scaffold Report ===");
|
|
3230
|
-
for (const action of actions) console.log(` ${action}`);
|
|
4451
|
+
for (const action of actions) console.log(` ${qualify(action)}`);
|
|
3231
4452
|
const count = (verb: string) => actions.filter(a => a.startsWith(verb)).length;
|
|
3232
4453
|
// AUTO-FIXED is reported separately from AUDITED on purpose (#42 SC-3).
|
|
3233
4454
|
// What the scaffold CHANGED and what it merely NOTICED are different facts,
|
|
3234
4455
|
// and a reader who cannot tell them apart has to diff the tree to find out
|
|
3235
4456
|
// which of the reported gaps are still gaps.
|
|
3236
|
-
|
|
4457
|
+
// The marker goes on the END of this line rather than into the `Total:`
|
|
4458
|
+
// token: `test/scaffold-auto-fix.test.ts` finds it with
|
|
4459
|
+
// `startsWith("\nTotal:")`, and a reader's eye finds it the same way.
|
|
4460
|
+
console.log(qualify(`\nTotal: ${count("CREATED")} created, ${count("REPLACED")} replaced, ${count("AUTO-FIXED")} auto-fixed, ${count("SKIP")} skipped, ${count("REFUSED")} refused`));
|
|
3237
4461
|
return count("REFUSED");
|
|
3238
4462
|
}
|
|
3239
4463
|
|