rungate 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +81 -16
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +93 -14
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +17 -0
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +191 -17
- package/lib/config-loader.ts +39 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1087 -100
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/create-sc.ts +249 -16
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/evidence-prevalidator.ts +224 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +157 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/generators/agents-md.ts +140 -32
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +52 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-id-cross-tree.ts +19 -7
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4661 -64
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +152 -45
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/steps.ts +1413 -244
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +4 -0
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +43 -51
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +241 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-suite-lock.ts +159 -16
- package/lib/tool-probe.ts +31 -9
- package/lib/top-level-cd.ts +393 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/create-sc.ts +21 -1
- package/scripts/extract-constraints.ts +107 -7
- package/scripts/generate-code-map.ts +23 -30
- package/scripts/scaffold-project.ts +8 -1
- package/scripts/sync-sc-status.ts +77 -16
package/lib/scaffold/steps.ts
CHANGED
|
@@ -7,34 +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";
|
|
31
59
|
import { localCalendarDay } from "../local-calendar-day";
|
|
32
60
|
import { decideRuleWrite } from "../rule-provenance";
|
|
61
|
+
import { actionRef } from "../workflow-actions";
|
|
62
|
+
import { ciSetupStep } from "../ci-setup-step";
|
|
33
63
|
import { DEFAULT_PROFILE, isRuleIncluded, type ScaffoldProfile } from "./profiles";
|
|
34
64
|
import { referencedPaths } from "../agents-md-refs";
|
|
65
|
+
import { scanDocsDirectory } from "../doc-routing";
|
|
35
66
|
import { inferredTestCommand, testCommandDecision } from "../test-command";
|
|
36
67
|
import { declaredBunVersion, setupBunWith } from "../bun-version";
|
|
37
68
|
import { codeMapUnreferenced, unlistedSpecs } from "../spec-listing";
|
|
69
|
+
import { censusReport, stampWorkflow, workflowBody, workflowCensus } from "./workflow-census";
|
|
38
70
|
import {
|
|
39
71
|
readSuccessDoc,
|
|
40
72
|
readSuccessTemplate,
|
|
@@ -44,11 +76,12 @@ import {
|
|
|
44
76
|
} from "../success-doc";
|
|
45
77
|
import { TS_SOURCE_DIRS, typeScriptSourceDirs, typecheckDecision } from "../typescript-project";
|
|
46
78
|
import {
|
|
47
|
-
OWNED_FILES,
|
|
48
79
|
SCAFFOLD_REFUSE,
|
|
49
80
|
decideOwnedWrite,
|
|
81
|
+
ownedFileFor,
|
|
50
82
|
type WriteStrategy,
|
|
51
83
|
} from "./owned-files";
|
|
84
|
+
import type { SectionSpec } from "../agents-md-sections";
|
|
52
85
|
|
|
53
86
|
/**
|
|
54
87
|
* Look for a declared health route in the places a server declares one.
|
|
@@ -119,18 +152,23 @@ export function safeWrite(filePath: string, content: string, label: string, acti
|
|
|
119
152
|
* prose while being written by a helper that skips it.
|
|
120
153
|
*/
|
|
121
154
|
export function ownedStrategy(label: string): WriteStrategy {
|
|
122
|
-
for (const owned of OWNED_FILES) {
|
|
123
|
-
if (owned.path === label) return owned.strategy;
|
|
124
|
-
if (owned.path.includes("*")) {
|
|
125
|
-
const [prefix, suffix] = owned.path.split("*");
|
|
126
|
-
if (label.startsWith(prefix) && label.endsWith(suffix)) return owned.strategy;
|
|
127
|
-
}
|
|
128
|
-
}
|
|
129
155
|
// An unlisted file is regenerated. The direction this is allowed to be
|
|
130
156
|
// wrong in: a file nobody declared gets rewritten with the generator's
|
|
131
157
|
// own output, which is recoverable. Defaulting to create-only would make
|
|
132
158
|
// forgetting to declare a file look exactly like #208.
|
|
133
|
-
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;
|
|
134
172
|
}
|
|
135
173
|
|
|
136
174
|
export function regenerateOwned(
|
|
@@ -181,7 +219,7 @@ export function regenerateOwned(
|
|
|
181
219
|
return;
|
|
182
220
|
}
|
|
183
221
|
const existing = link ? readFileSync(filePath, "utf-8") : null;
|
|
184
|
-
const decision = decideOwnedWrite(strategy, existing, content);
|
|
222
|
+
const decision = decideOwnedWrite(strategy, existing, content, ownedSections(label));
|
|
185
223
|
|
|
186
224
|
if (decision.action === "preserve") {
|
|
187
225
|
actions.push(
|
|
@@ -369,7 +407,7 @@ export function generateAgentsMdContent(
|
|
|
369
407
|
// Scan key files
|
|
370
408
|
const keyFiles: Array<{ file: string; what: string; when: string }> = [
|
|
371
409
|
{ file: "AGENTS.md", what: "Project entry point", when: "Always first" },
|
|
372
|
-
{ file: "PROJECT-STATE.md", what:
|
|
410
|
+
{ file: "PROJECT-STATE.md", what: projectStateKeyFileNote(projectStateDerivation(projectPath)), when: "Session start, always first after AGENTS.md" },
|
|
373
411
|
{ file: "project-state.json", what: "Source of truth for project status", when: "When editing state" },
|
|
374
412
|
];
|
|
375
413
|
const conditionalPatterns: Array<{ pattern: string; what: string; when: string }> = [
|
|
@@ -396,59 +434,21 @@ export function generateAgentsMdContent(
|
|
|
396
434
|
}
|
|
397
435
|
}
|
|
398
436
|
|
|
399
|
-
// Scan specs
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
let testable = "TODO";
|
|
409
|
-
if (fmMatch) {
|
|
410
|
-
const gMatch = fmMatch[1].match(/governs:\s*(.+)/);
|
|
411
|
-
if (gMatch && gMatch[1].trim() !== "TODO" && gMatch[1].trim().length > 5) {
|
|
412
|
-
governs = gMatch[1].trim().replace(/\|/g, "—").slice(0, 120);
|
|
413
|
-
}
|
|
414
|
-
const tMatch = fmMatch[1].match(/testable:\s*(.+)/);
|
|
415
|
-
if (tMatch) testable = tMatch[1].trim();
|
|
416
|
-
}
|
|
417
|
-
specEntries.push({ file: f, governs, testable });
|
|
418
|
-
}
|
|
419
|
-
|
|
420
|
-
// Also scan specs subdirectories
|
|
421
|
-
try {
|
|
422
|
-
const specSubDirs = readdirSync(specsDir, { withFileTypes: true })
|
|
423
|
-
.filter(d => d.isDirectory())
|
|
424
|
-
.map(d => d.name);
|
|
425
|
-
for (const sub of specSubDirs) {
|
|
426
|
-
const subPath = join(specsDir, sub);
|
|
427
|
-
const subFiles = readdirSync(subPath).filter(f => f.endsWith(".md") && f !== "INDEX.md");
|
|
428
|
-
if (subFiles.length > 0) {
|
|
429
|
-
const indexPath = join(subPath, "INDEX.md");
|
|
430
|
-
let groupGoverns = `${sub} (${subFiles.length} specs)`;
|
|
431
|
-
if (existsSync(indexPath)) {
|
|
432
|
-
const indexContent = readFileSync(indexPath, "utf-8");
|
|
433
|
-
const fmMatch = indexContent.match(/^---\n([\s\S]*?)\n---/);
|
|
434
|
-
if (fmMatch) {
|
|
435
|
-
const gMatch = fmMatch[1].match(/governs:\s*(.+)/);
|
|
436
|
-
if (gMatch && gMatch[1].trim().length > 5) {
|
|
437
|
-
groupGoverns = gMatch[1].trim().replace(/\|/g, "—").slice(0, 120);
|
|
438
|
-
}
|
|
439
|
-
}
|
|
440
|
-
}
|
|
441
|
-
specEntries.push({ file: `${sub}/ (${subFiles.length} specs)`, governs: groupGoverns, testable: "yes" });
|
|
442
|
-
}
|
|
443
|
-
}
|
|
444
|
-
} catch {}
|
|
445
|
-
}
|
|
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);
|
|
446
446
|
|
|
447
447
|
// Scan tests
|
|
448
448
|
const testDir = existsSync(join(projectPath, "test")) ? "test" : existsSync(join(projectPath, "tests")) ? "tests" : null;
|
|
449
449
|
const testEntries: TestFile[] = [];
|
|
450
450
|
if (testDir) {
|
|
451
|
-
for (const f of
|
|
451
|
+
for (const f of readdirSorted(join(projectPath, testDir)).filter(f => f.endsWith(".test.ts"))) {
|
|
452
452
|
const label = f.replace(".test.ts", "").replace(/-/g, " ");
|
|
453
453
|
testEntries.push({ label, file: f });
|
|
454
454
|
}
|
|
@@ -463,7 +463,7 @@ export function generateAgentsMdContent(
|
|
|
463
463
|
const refDir = join(projectPath, "reference");
|
|
464
464
|
const refEntries: RefFile[] = [];
|
|
465
465
|
if (existsSync(refDir)) {
|
|
466
|
-
for (const f of
|
|
466
|
+
for (const f of readdirSorted(refDir)) {
|
|
467
467
|
refEntries.push({ file: f, what: "Historical reference" });
|
|
468
468
|
}
|
|
469
469
|
}
|
|
@@ -516,42 +516,23 @@ export function generateAgentsMdContent(
|
|
|
516
516
|
// Recursive — see the same fix in scanner.ts. This is a second copy of
|
|
517
517
|
// scanDocRouting and it is the one the scaffold actually calls, so the
|
|
518
518
|
// scanner fix alone changed no generated output at all (#91).
|
|
519
|
-
const files =
|
|
519
|
+
const files = readdirSorted(catPath, { recursive: true }).filter(f => f.endsWith(".md"));
|
|
520
520
|
docRouting.push({ need: `${cat.label} (${files.length} files)`, file: `${cat.dir}/` });
|
|
521
521
|
} else {
|
|
522
522
|
docRouting.push({ need: cat.label, file: `${cat.dir}/` });
|
|
523
523
|
actions.push(`WARN: ${cat.dir}/ listed in routing but directory does not exist`);
|
|
524
524
|
}
|
|
525
525
|
}
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
}
|
|
537
|
-
docRouting.push({ need, file: `docs/${f}` });
|
|
538
|
-
}
|
|
539
|
-
const subDirs = readdirSync(docsDir, { withFileTypes: true })
|
|
540
|
-
.filter(d => d.isDirectory() && !categories.some(c => c.dir === `docs/${d.name}`))
|
|
541
|
-
.map(d => d.name);
|
|
542
|
-
for (const sub of subDirs) {
|
|
543
|
-
const subPath = join(docsDir, sub);
|
|
544
|
-
const subFiles = readdirSync(subPath).filter(f => f.endsWith(".md"));
|
|
545
|
-
if (subFiles.length > 0) {
|
|
546
|
-
docRouting.push({ need: `${sub} (${subFiles.length} files)`, file: `docs/${sub}/` });
|
|
547
|
-
}
|
|
548
|
-
}
|
|
549
|
-
}
|
|
550
|
-
const filteredRouting = docRouting.filter(d => {
|
|
551
|
-
const slug = d.file.replace(/\.md$/, "").replace(/.*\//, "").toLowerCase().replace(/-/g, " ");
|
|
552
|
-
const needLower = d.need.toLowerCase();
|
|
553
|
-
return !needLower.startsWith(slug) || d.need.includes("—") || d.need.includes("(");
|
|
554
|
-
});
|
|
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;
|
|
555
536
|
|
|
556
537
|
const consumers = harness?.consumers || [];
|
|
557
538
|
|
|
@@ -767,7 +748,7 @@ export function generateConformityTest(root?: string): string {
|
|
|
767
748
|
const from = root && isHarnessItself(root) ? "../lib/conformity" : "rungate/lib/conformity";
|
|
768
749
|
return `import { resolve } from "path";
|
|
769
750
|
import { afterAll } from "bun:test";
|
|
770
|
-
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}";
|
|
771
752
|
|
|
772
753
|
const ROOT = resolve(import.meta.dir, "..");
|
|
773
754
|
|
|
@@ -783,6 +764,9 @@ runTsconfigValidation(ROOT);
|
|
|
783
764
|
runConfigAccessValidation(ROOT);
|
|
784
765
|
runPromptConfigAccessValidation(ROOT);
|
|
785
766
|
runSuccessDocValidation(ROOT);
|
|
767
|
+
runAiReviewValidation(ROOT);
|
|
768
|
+
runBranchProtectionValidation(ROOT);
|
|
769
|
+
runWorkflowDriftValidation(ROOT);
|
|
786
770
|
|
|
787
771
|
afterAll(() => writeFindingsReport(ROOT));
|
|
788
772
|
`;
|
|
@@ -790,7 +774,26 @@ afterAll(() => writeFindingsReport(ROOT));
|
|
|
790
774
|
|
|
791
775
|
// ── Agent briefs generation ────────────────────────────────────
|
|
792
776
|
|
|
793
|
-
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 {
|
|
794
797
|
const agentsDir = join(root, ".claude", "agents");
|
|
795
798
|
safeDir(agentsDir, ".claude/agents", actions);
|
|
796
799
|
|
|
@@ -832,7 +835,7 @@ export function generateAgentBriefsStep(root: string, actions: string[]): void {
|
|
|
832
835
|
marcus: [], quinn: [], rook: [], serena: [], aditi: [], discovery: []
|
|
833
836
|
};
|
|
834
837
|
if (existsSync(promptsDir)) {
|
|
835
|
-
const promptFiles =
|
|
838
|
+
const promptFiles = readdirSorted(promptsDir).filter(f => f.endsWith(".md"));
|
|
836
839
|
for (const f of promptFiles) {
|
|
837
840
|
const content = readFileSync(join(promptsDir, f), "utf-8");
|
|
838
841
|
const lower = f.toLowerCase();
|
|
@@ -863,7 +866,8 @@ export function generateAgentBriefsStep(root: string, actions: string[]): void {
|
|
|
863
866
|
const consumers = harness?.consumers || [];
|
|
864
867
|
|
|
865
868
|
// Resolve templates directory relative to this module
|
|
866
|
-
const harnessTemplatesDir =
|
|
869
|
+
const harnessTemplatesDir =
|
|
870
|
+
opts.templatesDir ?? join(dirname(dirname(__dirname)), "templates", "agent-briefs");
|
|
867
871
|
|
|
868
872
|
// buildAgentMeta takes the whole harness config and reads .roles itself.
|
|
869
873
|
// Passing harness?.roles made it look for roles.roles, so every consumer's
|
|
@@ -922,8 +926,40 @@ export function generateAgentBriefsStep(root: string, actions: string[]): void {
|
|
|
922
926
|
|
|
923
927
|
for (const [agentName, content] of Object.entries(briefs)) {
|
|
924
928
|
const p = join(agentsDir, `${agentName}.md`);
|
|
925
|
-
|
|
926
|
-
|
|
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}`);
|
|
927
963
|
}
|
|
928
964
|
}
|
|
929
965
|
|
|
@@ -954,7 +990,7 @@ export function generateOrAuditProjectHarness(root: string, actions: string[], o
|
|
|
954
990
|
// Scan pages from dashboard/src/pages/*.tsx (file-based routing)
|
|
955
991
|
const dashboardPagesDir = join(root, "dashboard", "src", "pages");
|
|
956
992
|
if (existsSync(dashboardPagesDir)) {
|
|
957
|
-
const pageFiles =
|
|
993
|
+
const pageFiles = readdirSorted(dashboardPagesDir).filter(f => f.endsWith(".tsx") || f.endsWith(".jsx"));
|
|
958
994
|
for (const f of pageFiles) {
|
|
959
995
|
const componentName = f.replace(/\.(tsx|jsx)$/, "");
|
|
960
996
|
// Convert CamelCase to kebab-case route path
|
|
@@ -1055,7 +1091,7 @@ export function generateOrAuditProjectHarness(root: string, actions: string[], o
|
|
|
1055
1091
|
const srcDir = join(root, "src");
|
|
1056
1092
|
if (existsSync(srcDir)) {
|
|
1057
1093
|
const consumerPatterns = ["-routes.ts", "-generator.ts", "-plan.ts", "-intel.ts"];
|
|
1058
|
-
for (const f of
|
|
1094
|
+
for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts"))) {
|
|
1059
1095
|
const content = readFileSync(join(srcDir, f), "utf-8");
|
|
1060
1096
|
const isConsumer = consumerPatterns.some(p => f.includes(p)) ||
|
|
1061
1097
|
content.includes("app.get(") || content.includes("app.post(") ||
|
|
@@ -1440,7 +1476,17 @@ function writeDirectoryStructure(
|
|
|
1440
1476
|
* so no later scaffold ever corrected it. Running this step last is what makes
|
|
1441
1477
|
* that skip safe — the content it preserves is now right from run 1.
|
|
1442
1478
|
*/
|
|
1443
|
-
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 {
|
|
1444
1490
|
// No dry-run branch. It reported `GAP: CODE-MAP.md missing` and nothing
|
|
1445
1491
|
// else — one of the four `existsSync` checks that stood in for twenty-five
|
|
1446
1492
|
// write steps and made audit report 0 changes on a tree `--fix` rewrote in
|
|
@@ -1472,11 +1518,31 @@ export function generateCodeMapStep(root: string, actions: string[]): void {
|
|
|
1472
1518
|
}
|
|
1473
1519
|
|
|
1474
1520
|
// Run generate-code-map.ts if available
|
|
1475
|
-
const scriptPath =
|
|
1521
|
+
const scriptPath =
|
|
1522
|
+
opts.generatorPath ?? join(dirname(dirname(__dirname)), "scripts", "generate-code-map.ts");
|
|
1476
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);
|
|
1477
1533
|
const result = Bun.spawnSync(["bun", scriptPath, root], { timeout: 60_000 });
|
|
1478
1534
|
if (result.exitCode === 0) {
|
|
1479
|
-
|
|
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
|
+
);
|
|
1480
1546
|
} else {
|
|
1481
1547
|
actions.push("WARN: CODE-MAP.md generation failed via script — trying inline");
|
|
1482
1548
|
generateCodeMapInline(root, codeMapPath, actions);
|
|
@@ -1490,13 +1556,13 @@ function generateCodeMapInline(root: string, outPath: string, actions: string[])
|
|
|
1490
1556
|
const name = basename(root);
|
|
1491
1557
|
const skip = new Set(["node_modules", ".git", "reference", "dist", "build", ".next", ".fallow"]);
|
|
1492
1558
|
const dirs: Array<{ name: string; fileCount: number; types: string[] }> = [];
|
|
1493
|
-
for (const entry of
|
|
1559
|
+
for (const entry of readdirSorted(root)) {
|
|
1494
1560
|
if (entry.startsWith(".") && entry !== ".claude") continue;
|
|
1495
1561
|
if (skip.has(entry)) continue;
|
|
1496
1562
|
const full = join(root, entry);
|
|
1497
1563
|
try {
|
|
1498
1564
|
if (!statSync(full).isDirectory()) continue;
|
|
1499
|
-
const files =
|
|
1565
|
+
const files = readdirSorted(full, { recursive: true });
|
|
1500
1566
|
const exts = new Set(files.map(f => f.split(".").pop()).filter((e): e is string => Boolean(e)));
|
|
1501
1567
|
dirs.push({ name: entry, fileCount: files.length, types: [...exts].slice(0, 5) });
|
|
1502
1568
|
} catch {}
|
|
@@ -1516,7 +1582,7 @@ function generateCodeMapInline(root: string, outPath: string, actions: string[])
|
|
|
1516
1582
|
const srcDir = join(root, "src");
|
|
1517
1583
|
const modules: Array<{ file: string; exports: string[] }> = [];
|
|
1518
1584
|
if (existsSync(srcDir)) {
|
|
1519
|
-
for (const f of
|
|
1585
|
+
for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
|
|
1520
1586
|
const content = readFileSync(join(srcDir, f), "utf-8");
|
|
1521
1587
|
const exports: string[] = [];
|
|
1522
1588
|
const exportPattern = /export\s+(?:function|const|class|type|interface)\s+(\w+)/g;
|
|
@@ -1529,7 +1595,7 @@ function generateCodeMapInline(root: string, outPath: string, actions: string[])
|
|
|
1529
1595
|
// Detect API routes
|
|
1530
1596
|
const routes: Array<{ method: string; path: string; file: string }> = [];
|
|
1531
1597
|
if (existsSync(srcDir)) {
|
|
1532
|
-
for (const f of
|
|
1598
|
+
for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
|
|
1533
1599
|
const content = readFileSync(join(srcDir, f), "utf-8");
|
|
1534
1600
|
const routePatterns = [
|
|
1535
1601
|
/app\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/gi,
|
|
@@ -1590,7 +1656,7 @@ export function copySpecTemplateIfEmpty(specsDir: string, actions: string[]): vo
|
|
|
1590
1656
|
if (!existsSync(specsDir)) return;
|
|
1591
1657
|
|
|
1592
1658
|
// Skip if specs/ already has .md files (besides SPEC-TEMPLATE.md itself)
|
|
1593
|
-
const existingSpecs =
|
|
1659
|
+
const existingSpecs = readdirSorted(specsDir).filter(
|
|
1594
1660
|
f => f.endsWith(".md") && f !== "SPEC-TEMPLATE.md"
|
|
1595
1661
|
);
|
|
1596
1662
|
if (existingSpecs.length > 0) {
|
|
@@ -2035,6 +2101,26 @@ export interface ManagedWrite {
|
|
|
2035
2101
|
* was being made.
|
|
2036
2102
|
*/
|
|
2037
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[];
|
|
2038
2124
|
/** Non-null ⇒ the write must not happen. Names the dropped jobs and the line delta. */
|
|
2039
2125
|
refusal: string | null;
|
|
2040
2126
|
}
|
|
@@ -2132,10 +2218,11 @@ function measureWrite(existing: string | null, next: string): { verb: ManagedWri
|
|
|
2132
2218
|
* test/scaffold-ci-preservation-mutation.test.ts performs, so that
|
|
2133
2219
|
* "preservation works" is a claim with a demonstrated way of being false.
|
|
2134
2220
|
*/
|
|
2135
|
-
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 {
|
|
2136
2222
|
const base: ManagedWrite = {
|
|
2137
2223
|
content: generated, verb: "CREATED", lineDelta: lineCount(generated),
|
|
2138
|
-
preservedJobs: [], droppedJobs: [], overwrittenLines: [], movedKeys: [],
|
|
2224
|
+
preservedJobs: [], droppedJobs: [], overwrittenLines: [], movedKeys: [], revokedGrants: [],
|
|
2225
|
+
refusal: null,
|
|
2139
2226
|
};
|
|
2140
2227
|
if (existing === null) return base;
|
|
2141
2228
|
|
|
@@ -2164,7 +2251,7 @@ export function resolveManagedWrite(existing: string | null, generated: string):
|
|
|
2164
2251
|
// A refusal that is structurally incapable of firing on the thing being
|
|
2165
2252
|
// destroyed is the defect class .claude/rules/checks-must-be-able-to-fail.md
|
|
2166
2253
|
// exists for, and it was in the fix written to prevent a data-loss bug.
|
|
2167
|
-
const content =
|
|
2254
|
+
const { content, revoked: revokedGrants } = mergeManagedWorkflowRecording(existing, generated, overrides, provenance, computed);
|
|
2168
2255
|
const lineDelta = lineCount(content) - before;
|
|
2169
2256
|
|
|
2170
2257
|
const preservedJobs = existingJobs.filter(j => !generatedJobs.includes(j));
|
|
@@ -2248,19 +2335,98 @@ export function resolveManagedWrite(existing: string | null, generated: string):
|
|
|
2248
2335
|
const block = blocks.get(name);
|
|
2249
2336
|
if (block !== undefined) for (const l of nonBlankLines(block)) harnessOwned.add(l);
|
|
2250
2337
|
}
|
|
2251
|
-
// The harness's own
|
|
2252
|
-
// first run after the banner's text changed
|
|
2253
|
-
// harness had written itself, naming its own
|
|
2254
|
-
// content it declined to drop — a refusal is
|
|
2255
|
-
// 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).
|
|
2256
2346
|
for (const l of nonBlankLines(existing)) {
|
|
2257
|
-
if (l.startsWith(
|
|
2347
|
+
if (HARNESS_BOOKKEEPING_PREFIXES.some(p => l.startsWith(p))) harnessOwned.add(l);
|
|
2348
|
+
}
|
|
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
|
+
}
|
|
2258
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
|
+
};
|
|
2259
2413
|
|
|
2260
2414
|
const kept = new Set(nonBlankLines(content));
|
|
2261
2415
|
const gone = nonBlankLines(existing).filter(l => !kept.has(l));
|
|
2262
|
-
|
|
2263
|
-
|
|
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
|
+
);
|
|
2264
2430
|
const droppedJobs = existingJobs.filter(j => !resultJobs.includes(j));
|
|
2265
2431
|
|
|
2266
2432
|
if (lostLines.length > 0) {
|
|
@@ -2277,7 +2443,11 @@ export function resolveManagedWrite(existing: string | null, generated: string):
|
|
|
2277
2443
|
};
|
|
2278
2444
|
}
|
|
2279
2445
|
|
|
2280
|
-
|
|
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 };
|
|
2281
2451
|
}
|
|
2282
2452
|
|
|
2283
2453
|
/** Non-blank lines, trimmed — the unit the loss set is counted in. */
|
|
@@ -2286,13 +2456,85 @@ function nonBlankLines(text: string): string[] {
|
|
|
2286
2456
|
}
|
|
2287
2457
|
|
|
2288
2458
|
/**
|
|
2289
|
-
*
|
|
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.
|
|
2290
2508
|
*
|
|
2291
|
-
*
|
|
2292
|
-
*
|
|
2293
|
-
*
|
|
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
|
|
2527
|
+
*
|
|
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.
|
|
2294
2534
|
*/
|
|
2295
|
-
const
|
|
2535
|
+
export const HARNESS_COMPUTED_SUBKEYS: ReadonlyMap<string, ComputedSubKeys> = new Map([
|
|
2536
|
+
["ai-review.yml", new Map([["permissions", new Set(["id-token"])]])],
|
|
2537
|
+
]);
|
|
2296
2538
|
|
|
2297
2539
|
/**
|
|
2298
2540
|
* Write a harness-managed file, preserving whatever the harness did not author.
|
|
@@ -2300,27 +2542,75 @@ const MANAGED_BANNER_PREFIX = "# Managed by rungate";
|
|
|
2300
2542
|
* Throws on refusal. Callers decide whether a refusal aborts the run or is
|
|
2301
2543
|
* recorded and reported; what they may not do is write anyway.
|
|
2302
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
|
+
|
|
2303
2560
|
export function writeManagedFile(
|
|
2304
2561
|
filePath: string,
|
|
2305
2562
|
generated: string,
|
|
2306
2563
|
label: string,
|
|
2307
2564
|
actions: string[],
|
|
2308
|
-
opts: { force?: boolean } = {},
|
|
2565
|
+
opts: { force?: boolean; workflowOverrides?: readonly string[]; computedSubKeys?: ComputedSubKeys } = {},
|
|
2566
|
+
provenance?: WriteProvenance,
|
|
2309
2567
|
): void {
|
|
2310
|
-
const
|
|
2311
|
-
|
|
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);
|
|
2312
2601
|
|
|
2313
2602
|
if (opts.force) {
|
|
2314
2603
|
// The escape hatch, and it still reports a measured verb: --force changes
|
|
2315
2604
|
// what is ALLOWED, not what gets claimed about it. The dropped jobs are
|
|
2316
2605
|
// still named, because an operator who overrides the refusal should be
|
|
2317
2606
|
// told in the report exactly what they overrode.
|
|
2318
|
-
const
|
|
2319
|
-
if (
|
|
2607
|
+
const bytes = stamped(incoming);
|
|
2608
|
+
if (bytes === raw) { actions.push(`SKIP: ${label} (unchanged)`); return; }
|
|
2609
|
+
const { verb, lineDelta } = measureWrite(existing, incoming);
|
|
2320
2610
|
const dropped = resolved.droppedJobs.length > 0 ? `, dropped ${resolved.droppedJobs.join(", ")}` : "";
|
|
2321
2611
|
mkdirSync(dirname(filePath), { recursive: true });
|
|
2322
|
-
writeFileSync(filePath,
|
|
2323
|
-
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})`);
|
|
2324
2614
|
return;
|
|
2325
2615
|
}
|
|
2326
2616
|
|
|
@@ -2343,16 +2633,296 @@ export function writeManagedFile(
|
|
|
2343
2633
|
`${over.slice(0, 2).map(l => JSON.stringify(l)).join(", ")}` +
|
|
2344
2634
|
`${over.length > 2 ? ` and ${over.length - 2} more` : ""}`;
|
|
2345
2635
|
|
|
2346
|
-
|
|
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) {
|
|
2347
2643
|
actions.push(`SKIP: ${label} (unchanged${kept})`);
|
|
2348
2644
|
return;
|
|
2349
2645
|
}
|
|
2350
2646
|
|
|
2351
2647
|
mkdirSync(dirname(filePath), { recursive: true });
|
|
2352
|
-
writeFileSync(filePath,
|
|
2353
|
-
|
|
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));
|
|
2354
2658
|
}
|
|
2355
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
|
+
};
|
|
2856
|
+
}
|
|
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
|
+
|
|
2356
2926
|
export function createCiWorkflows(root: string, actions: string[], opts: { force?: boolean } = {}): void {
|
|
2357
2927
|
const workflowsDir = join(root, ".github", "workflows");
|
|
2358
2928
|
if (!existsSync(workflowsDir)) {
|
|
@@ -2407,16 +2977,51 @@ export function createCiWorkflows(root: string, actions: string[], opts: { force
|
|
|
2407
2977
|
// is the gap, not the absence of a validator.
|
|
2408
2978
|
const baseBranch = String(branches[0] ?? "main");
|
|
2409
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}`;
|
|
2410
3016
|
const baseRefStep =
|
|
2411
3017
|
SAFE_BRANCH.test(baseBranch) && !baseBranch.includes("..")
|
|
2412
|
-
? //
|
|
2413
|
-
//
|
|
2414
|
-
//
|
|
2415
|
-
//
|
|
2416
|
-
// 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.
|
|
2417
3022
|
` - name: Fetch the comparison base for the conformity ratchet
|
|
2418
3023
|
run: |
|
|
2419
|
-
git fetch --no-tags
|
|
3024
|
+
git fetch --no-tags ${baseDepthFlag}origin '+refs/heads/${baseBranch}:refs/remotes/origin/${baseBranch}' \\
|
|
2420
3025
|
|| echo "WARN: could not fetch ${baseBranch}; the conformity allowlist growth check will report UNMEASURED."`
|
|
2421
3026
|
: // Not a fetchable ref: a glob pattern, a leading dash, or a traversal
|
|
2422
3027
|
// segment. Emitted as a comment so the omission is visible in the
|
|
@@ -2444,15 +3049,75 @@ export function createCiWorkflows(root: string, actions: string[], opts: { force
|
|
|
2444
3049
|
// binding can show the agreement is load-bearing.
|
|
2445
3050
|
const test = testCommandDecision(root);
|
|
2446
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
|
+
|
|
2447
3058
|
const typecheck = typecheckDecision(root);
|
|
2448
3059
|
const typecheckStep = typecheck.command
|
|
2449
3060
|
? `\n - run: ${typecheck.command}`
|
|
2450
3061
|
: `\n # No type check: ${typecheck.reason}.`;
|
|
2451
3062
|
|
|
2452
|
-
|
|
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.
|
|
2453
3094
|
name: CI
|
|
2454
3095
|
|
|
2455
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:
|
|
2456
3121
|
push:
|
|
2457
3122
|
branches:
|
|
2458
3123
|
${branchList}
|
|
@@ -2460,16 +3125,93 @@ ${branchList}
|
|
|
2460
3125
|
branches:
|
|
2461
3126
|
${branchList}
|
|
2462
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
|
+
|
|
2463
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.
|
|
2464
3159
|
test:
|
|
2465
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()
|
|
2466
3167
|
steps:
|
|
2467
|
-
-
|
|
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.
|
|
3178
|
+
name: CI
|
|
3179
|
+
|
|
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:
|
|
3187
|
+
push:
|
|
3188
|
+
branches:
|
|
3189
|
+
${branchList}
|
|
3190
|
+
pull_request:
|
|
3191
|
+
branches:
|
|
3192
|
+
${branchList}
|
|
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
|
+
|
|
3205
|
+
jobs:
|
|
3206
|
+
test:
|
|
3207
|
+
runs-on: ${runsOn}
|
|
3208
|
+
steps:
|
|
3209
|
+
${checkoutStep}
|
|
2468
3210
|
${baseRefStep}
|
|
2469
|
-
- uses: oven-sh/setup-bun
|
|
3211
|
+
- uses: ${actionRef("oven-sh/setup-bun")}
|
|
2470
3212
|
with:
|
|
2471
3213
|
${bunStep}
|
|
2472
|
-
- run: bun install
|
|
3214
|
+
- run: bun install${globalTools.step}${ciSetupStep()}
|
|
2473
3215
|
- run: ${test.command}${typecheckStep}
|
|
2474
3216
|
`;
|
|
2475
3217
|
|
|
@@ -2477,6 +3219,12 @@ ${bunStep}
|
|
|
2477
3219
|
name: Gates
|
|
2478
3220
|
|
|
2479
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:
|
|
2480
3228
|
push:
|
|
2481
3229
|
branches:
|
|
2482
3230
|
${branchList}
|
|
@@ -2484,12 +3232,22 @@ ${branchList}
|
|
|
2484
3232
|
branches:
|
|
2485
3233
|
${branchList}
|
|
2486
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
|
+
|
|
2487
3245
|
jobs:
|
|
2488
3246
|
gates:
|
|
2489
3247
|
runs-on: ${runsOn}
|
|
2490
3248
|
steps:
|
|
2491
|
-
|
|
2492
|
-
- uses: oven-sh/setup-bun
|
|
3249
|
+
${checkoutStep}
|
|
3250
|
+
- uses: ${actionRef("oven-sh/setup-bun")}
|
|
2493
3251
|
with:
|
|
2494
3252
|
${bunStep}
|
|
2495
3253
|
- run: bun install
|
|
@@ -2508,6 +3266,9 @@ ${bunStep}
|
|
|
2508
3266
|
# CLAIM parity while CI carried 3 patterns and the hook carried 8 —
|
|
2509
3267
|
# CI missed gho_, ghs_, github_pat_, sk-ant- and PEM private keys
|
|
2510
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).
|
|
2511
3272
|
if git grep -I -lE '${tier1Ere()}' -- .; then
|
|
2512
3273
|
echo "::error::Potential secrets detected in tracked files"
|
|
2513
3274
|
exit 1
|
|
@@ -2519,8 +3280,14 @@ ${bunStep}
|
|
|
2519
3280
|
# NOTE: do NOT append "|| true" to the assignment below. It makes the
|
|
2520
3281
|
# assignment itself succeed, so $? is always 0 and the error branch
|
|
2521
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).
|
|
2522
3289
|
set +e
|
|
2523
|
-
tier2=$(git grep -I -hoE '(
|
|
3290
|
+
tier2=$(git grep -I -hoE ${TIER2_GREP_CASE_FLAG} '${tier2Ere()}' -- .)
|
|
2524
3291
|
rc=$?
|
|
2525
3292
|
set -e
|
|
2526
3293
|
# git grep: 0 = match, 1 = no match, >1 = real error.
|
|
@@ -2531,26 +3298,196 @@ ${bunStep}
|
|
|
2531
3298
|
# Exclusion applies to the extracted VALUE, not the whole line.
|
|
2532
3299
|
# Matching anywhere on the line let a trailing "# placeholder"
|
|
2533
3300
|
# launder a real secret past the check.
|
|
2534
|
-
|
|
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
|
|
2535
3318
|
echo "::error::Potential credential assignment in tracked files"
|
|
2536
3319
|
exit 1
|
|
2537
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
|
|
2538
3350
|
echo "Secret scan clean"
|
|
2539
3351
|
`;
|
|
2540
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
|
+
|
|
2541
3442
|
// Not `writeFileSync`. The harness owns the `test` and `gates` jobs; it does
|
|
2542
3443
|
// not own the file, and a consumer's own jobs have to survive the update
|
|
2543
3444
|
// that re-scaffolding IS. A refusal is recorded rather than thrown so that
|
|
2544
3445
|
// one unpreservable workflow does not abandon the rest of the scaffold
|
|
2545
3446
|
// half-done — scripts/scaffold-project.ts exits non-zero on it.
|
|
2546
|
-
|
|
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) {
|
|
2547
3458
|
const label = `.github/workflows/${name}`;
|
|
2548
3459
|
try {
|
|
2549
|
-
|
|
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
|
+
});
|
|
2550
3472
|
} catch (e) {
|
|
2551
3473
|
actions.push(`REFUSED: ${(e as Error).message}`);
|
|
2552
3474
|
}
|
|
2553
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)));
|
|
2554
3491
|
}
|
|
2555
3492
|
|
|
2556
3493
|
// ── Consumer hook deployment ─────────────────────────────────
|
|
@@ -2636,6 +3573,62 @@ export function deployHooksToConsumers(root: string, actions: string[]): void {
|
|
|
2636
3573
|
}
|
|
2637
3574
|
}
|
|
2638
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
|
+
|
|
2639
3632
|
/**
|
|
2640
3633
|
* The line that marks a pre-commit hook as ours, so a fix can reach one that
|
|
2641
3634
|
* already exists (#450).
|
|
@@ -2649,18 +3642,104 @@ export function deployHooksToConsumers(root: string, actions: string[]): void {
|
|
|
2649
3642
|
*/
|
|
2650
3643
|
export const PRE_COMMIT_MANAGED_MARKER = "# Managed by rungate — secret scan + PROJECT-STATE update";
|
|
2651
3644
|
|
|
2652
|
-
|
|
2653
|
-
|
|
2654
|
-
|
|
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.";
|
|
2655
3654
|
|
|
2656
|
-
|
|
3655
|
+
/** The harness's own copy, relative to the project root. */
|
|
3656
|
+
export const HARNESS_UPDATER = "scripts/update-project-state.ts";
|
|
2657
3657
|
|
|
2658
|
-
|
|
2659
|
-
|
|
2660
|
-
|
|
2661
|
-
|
|
2662
|
-
|
|
2663
|
-
|
|
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
|
|
2664
3743
|
${PRE_COMMIT_MANAGED_MARKER}
|
|
2665
3744
|
#
|
|
2666
3745
|
# Scans the staged DIFF, not files on disk. This is deliberate and fixes four
|
|
@@ -2700,14 +3779,43 @@ fi
|
|
|
2700
3779
|
# Exclusions are env lookups and explicit non-values. password =
|
|
2701
3780
|
# process.env.DB_PASSWORD is a reference, not a secret, and flagging it would
|
|
2702
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).
|
|
2703
3794
|
if printf '%s\\n' "$staged_diff" \\
|
|
2704
3795
|
| grep '^+' \\
|
|
2705
|
-
| grep -oE '(
|
|
2706
|
-
| grep -qvE '
|
|
3796
|
+
| grep -oE ${TIER2_GREP_CASE_FLAG} '${tier2Ere()}' \\
|
|
3797
|
+
| grep -qvE ${TIER2_GREP_CASE_FLAG} '${TIER2_ALLOWED_VALUE_ERE}'; then
|
|
2707
3798
|
echo "ERROR: Potential credential assignment in staged changes"
|
|
2708
3799
|
exit 1
|
|
2709
3800
|
fi
|
|
2710
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
|
+
|
|
2711
3819
|
# Update PROJECT-STATE if it exists — but NEVER from a linked worktree (#450).
|
|
2712
3820
|
#
|
|
2713
3821
|
# project-state.json, PROJECT-STATE.md and SUCCESS.md are DA-owned: a single
|
|
@@ -2738,10 +3846,7 @@ fi
|
|
|
2738
3846
|
# checkout — which has scripts/update-project-state.ts and no
|
|
2739
3847
|
# node_modules/rungate at all — bun exited non-zero on a file that is not
|
|
2740
3848
|
# there. 2>/dev/null threw the ENOENT away, || true threw the status away, and
|
|
2741
|
-
# the git add below then staged whatever happened to be on disk.
|
|
2742
|
-
# regenerated nothing was byte-indistinguishable from one that regenerated
|
|
2743
|
-
# everything, and the only reason anyone noticed is that the stamp is UTC, so
|
|
2744
|
-
# the stale copy differs from the fresh one for four hours an evening.
|
|
3849
|
+
# the git add below then staged whatever happened to be on disk.
|
|
2745
3850
|
#
|
|
2746
3851
|
# Every message is on STDERR: stdout is what a caller captures as the
|
|
2747
3852
|
# command's answer, and a decline, a reading and an updater's progress are all
|
|
@@ -2750,26 +3855,7 @@ if [ -f "project-state.json" ]; then
|
|
|
2750
3855
|
gitdir=$(git rev-parse --git-dir)
|
|
2751
3856
|
commondir=$(git rev-parse --git-common-dir)
|
|
2752
3857
|
if [ -n "$gitdir" ] && [ "$gitdir" = "$commondir" ]; then
|
|
2753
|
-
|
|
2754
|
-
# the harness, and the harness must not regenerate its state with a stale
|
|
2755
|
-
# vendored duplicate of its own updater.
|
|
2756
|
-
updater=""
|
|
2757
|
-
if [ -f "scripts/update-project-state.ts" ]; then
|
|
2758
|
-
updater="scripts/update-project-state.ts"
|
|
2759
|
-
elif [ -f "node_modules/rungate/scripts/update-project-state.ts" ]; then
|
|
2760
|
-
updater="node_modules/rungate/scripts/update-project-state.ts"
|
|
2761
|
-
fi
|
|
2762
|
-
if [ -z "$updater" ]; then
|
|
2763
|
-
echo "project-state: UNMEASURED — project-state.json is here, but no update-project-state.ts was found at scripts/update-project-state.ts or node_modules/rungate/scripts/update-project-state.ts. Nothing was regenerated and nothing was staged." >&2
|
|
2764
|
-
elif bun "$updater" --skip-tests >&2; then
|
|
2765
|
-
# Staged only after the updater SUCCEEDED. Staging regardless is the
|
|
2766
|
-
# fail-open the readings above exist to replace: it puts yesterday's
|
|
2767
|
-
# PROJECT-STATE.md in today's commit, and the commit then looks exactly
|
|
2768
|
-
# like one that updated it.
|
|
2769
|
-
git add PROJECT-STATE.md project-state.json 2>/dev/null || true
|
|
2770
|
-
else
|
|
2771
|
-
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
|
|
2772
|
-
fi
|
|
3858
|
+
${updaterBlock(resolveUpdater(root))}
|
|
2773
3859
|
else
|
|
2774
3860
|
# Announced, not silent. A developer who expected the state files to move
|
|
2775
3861
|
# would otherwise be left guessing, and SKIP that says nothing is
|
|
@@ -2783,61 +3869,95 @@ fi
|
|
|
2783
3869
|
# made the hook exit non-zero and reject a perfectly good commit. Everything
|
|
2784
3870
|
# that should block has already exited 1 above.
|
|
2785
3871
|
exit 0
|
|
2786
|
-
|
|
2787
|
-
|
|
2788
|
-
actions.push(
|
|
2789
|
-
existingPreCommit === null
|
|
2790
|
-
? "CREATED: .git/hooks/pre-commit (secret scan + PROJECT-STATE update)"
|
|
2791
|
-
: "UPDATED: .git/hooks/pre-commit (secret scan + PROJECT-STATE update)",
|
|
2792
|
-
);
|
|
2793
|
-
}
|
|
3872
|
+
`;
|
|
3873
|
+
}
|
|
2794
3874
|
|
|
2795
|
-
|
|
2796
|
-
|
|
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
|
+
}
|
|
2797
3907
|
|
|
2798
|
-
|
|
2799
|
-
|
|
2800
|
-
|
|
2801
|
-
|
|
2802
|
-
|
|
2803
|
-
|
|
2804
|
-
|
|
2805
|
-
|
|
2806
|
-
|
|
2807
|
-
|
|
2808
|
-
|
|
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
|
+
];
|
|
2809
3933
|
|
|
2810
|
-
|
|
2811
|
-
|
|
2812
|
-
|
|
2813
|
-
|
|
2814
|
-
|
|
2815
|
-
|
|
2816
|
-
//
|
|
2817
|
-
//
|
|
2818
|
-
//
|
|
2819
|
-
//
|
|
2820
|
-
|
|
2821
|
-
|
|
2822
|
-
|
|
2823
|
-
|
|
2824
|
-
|
|
2825
|
-
|
|
2826
|
-
|
|
2827
|
-
|
|
2828
|
-
|
|
2829
|
-
|
|
2830
|
-
|
|
2831
|
-
|
|
2832
|
-
|
|
2833
|
-
|
|
2834
|
-
|
|
2835
|
-
|
|
2836
|
-
|
|
2837
|
-
chmodSync(prePush, 0o755);
|
|
2838
|
-
actions.push(existing === null
|
|
2839
|
-
? "CREATED: .git/hooks/pre-push (conformity check)"
|
|
2840
|
-
: "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
|
+
}
|
|
2841
3961
|
}
|
|
2842
3962
|
|
|
2843
3963
|
/**
|
|
@@ -3168,7 +4288,7 @@ export function runAuditSpecsFix(root: string, actions: string[]): void {
|
|
|
3168
4288
|
actions.push("SKIP: audit-specs (no specs/ directory)");
|
|
3169
4289
|
return;
|
|
3170
4290
|
}
|
|
3171
|
-
const specFiles =
|
|
4291
|
+
const specFiles = readdirSorted(specsDir).filter(f => f.endsWith(".md"));
|
|
3172
4292
|
if (specFiles.length === 0) {
|
|
3173
4293
|
actions.push("SKIP: audit-specs (no spec files)");
|
|
3174
4294
|
return;
|
|
@@ -3280,15 +4400,64 @@ export function writtenPath(line: string): string | null {
|
|
|
3280
4400
|
return m?.[1] ?? null;
|
|
3281
4401
|
}
|
|
3282
4402
|
|
|
3283
|
-
|
|
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);
|
|
3284
4450
|
console.log("\n=== Scaffold Report ===");
|
|
3285
|
-
for (const action of actions) console.log(` ${action}`);
|
|
4451
|
+
for (const action of actions) console.log(` ${qualify(action)}`);
|
|
3286
4452
|
const count = (verb: string) => actions.filter(a => a.startsWith(verb)).length;
|
|
3287
4453
|
// AUTO-FIXED is reported separately from AUDITED on purpose (#42 SC-3).
|
|
3288
4454
|
// What the scaffold CHANGED and what it merely NOTICED are different facts,
|
|
3289
4455
|
// and a reader who cannot tell them apart has to diff the tree to find out
|
|
3290
4456
|
// which of the reported gaps are still gaps.
|
|
3291
|
-
|
|
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`));
|
|
3292
4461
|
return count("REFUSED");
|
|
3293
4462
|
}
|
|
3294
4463
|
|