rungate 0.5.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +411 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- package/scripts/sync-spec-tests.ts +2 -1
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env bun
|
|
2
2
|
import { readFileSync, readdirSync } from "fs";
|
|
3
3
|
import { join, basename, resolve } from "path";
|
|
4
|
+
import { localCalendarDay } from "../lib/local-calendar-day";
|
|
4
5
|
import {
|
|
5
6
|
type ToolCall,
|
|
6
7
|
type TranscriptData,
|
|
@@ -184,7 +185,7 @@ export function formatReport(audits: AgentAudit[]): string {
|
|
|
184
185
|
const lines: string[] = [];
|
|
185
186
|
lines.push("# Workflow Transcript Audit Report");
|
|
186
187
|
lines.push(`\nAudited: ${audits.length} agents`);
|
|
187
|
-
lines.push(`Date: ${
|
|
188
|
+
lines.push(`Date: ${localCalendarDay()}`);
|
|
188
189
|
|
|
189
190
|
const avgScore = Math.round(audits.reduce((s, a) => s + a.score, 0) / audits.length);
|
|
190
191
|
lines.push(`\n## Summary: ${avgScore}% average (${audits.map((a) => a.grade).join(", ")})`);
|
package/scripts/convert-spec.ts
CHANGED
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
|
|
17
17
|
import { join, basename, dirname } from "path";
|
|
18
18
|
import { SIGNAL_PHRASE_PATTERNS } from "../lib/signal-phrases";
|
|
19
|
+
import { localCalendarDay } from "../lib/local-calendar-day";
|
|
19
20
|
|
|
20
21
|
// ── Argument parsing ──────────────────────────────────────────
|
|
21
22
|
|
|
@@ -225,7 +226,7 @@ function deriveSlug(title: string): string {
|
|
|
225
226
|
// ── Spec generation ───────────────────────────────────────────
|
|
226
227
|
|
|
227
228
|
function generateSpec(rules: ExtractedRule[], title: string, governs: string): string {
|
|
228
|
-
const today =
|
|
229
|
+
const today = localCalendarDay();
|
|
229
230
|
|
|
230
231
|
// Build SC lines
|
|
231
232
|
const scLines = rules.map((rule, i) => {
|
package/scripts/create-sc.ts
CHANGED
|
@@ -5,19 +5,25 @@
|
|
|
5
5
|
* Usage:
|
|
6
6
|
* bun scripts/create-sc.ts --pattern file-exists --params '{"file":"AGENTS.md"}'
|
|
7
7
|
* bun scripts/create-sc.ts --pattern file-exists --params '{"file":"AGENTS.md"}' --spec specs/MY-SPEC.md
|
|
8
|
+
* bun scripts/create-sc.ts --pattern file-exists --params '{...}' --spec specs/X.md --owner '#725'
|
|
8
9
|
* bun scripts/create-sc.ts --list
|
|
9
10
|
*
|
|
11
|
+
* `--owner` names the entry in `specs/sc-reservations.json` to allocate from.
|
|
12
|
+
* It defaults to this checkout's branch. An owner holding no block allocates
|
|
13
|
+
* above every block in the store, which is the safe direction.
|
|
14
|
+
*
|
|
10
15
|
* Thin CLI consumer — all logic lives in lib/create-sc.ts.
|
|
11
16
|
*/
|
|
12
17
|
import { readFileSync, writeFileSync, existsSync } from "fs";
|
|
13
18
|
import {
|
|
19
|
+
allocateScNumber,
|
|
14
20
|
generateSCText,
|
|
15
21
|
listPatterns,
|
|
16
|
-
nextSCNumber,
|
|
17
22
|
formatSCLine,
|
|
18
23
|
} from "../lib/create-sc";
|
|
19
24
|
import { readScRegistry } from "./sync-sc-status";
|
|
20
|
-
import {
|
|
25
|
+
import { describeReading } from "../lib/sc-id-cross-tree";
|
|
26
|
+
import { currentScOwner } from "../lib/sc-reservations";
|
|
21
27
|
import { join } from "path";
|
|
22
28
|
|
|
23
29
|
/** Same resolution sync-sc-status uses, so both halves read one tree. */
|
|
@@ -83,17 +89,41 @@ try {
|
|
|
83
89
|
// spell SC ids in the same namespace without appearing in any registry,
|
|
84
90
|
// so an allocation that consults only the registry can mint a criterion
|
|
85
91
|
// out of a number a fixture already depends on.
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
92
|
+
//
|
|
93
|
+
// And a THIRD half, which is the one the first two could not see (#503):
|
|
94
|
+
// the registry is `specs/` in whichever working tree this command runs
|
|
95
|
+
// in. Two sessions in two worktrees both read "highest + 1" correctly and
|
|
96
|
+
// both got the same number.
|
|
97
|
+
//
|
|
98
|
+
// All three widths compose inside `allocateScNumber`, so this CLI cannot
|
|
99
|
+
// assemble two of them and believe it asked.
|
|
100
|
+
//
|
|
101
|
+
// And a FOURTH, which none of the first three can be (#725): every one of
|
|
102
|
+
// them reads ids that are already written down somewhere, and the four
|
|
103
|
+
// collisions of 2026-10-19 were ids that had been decided on and not yet
|
|
104
|
+
// typed. `specs/sc-reservations.json` is where a session declares a block
|
|
105
|
+
// before consuming it; the owner is this checkout's branch, so a session
|
|
106
|
+
// that reserved one is handed an id out of it and a session that did not
|
|
107
|
+
// is handed one above every block in the store.
|
|
108
|
+
//
|
|
109
|
+
// `--owner` overrides the branch for the case the store is keyed by issue
|
|
110
|
+
// rather than by branch. An owner matching no block is not an error: it
|
|
111
|
+
// is the no-block path, which is the safe one.
|
|
112
|
+
const owner = getFlag("owner") ?? currentScOwner(ROOT);
|
|
113
|
+
const { number: scNumber, namespace } = allocateScNumber(ROOT, content, readScRegistry(), { owner });
|
|
91
114
|
const scLine = formatSCLine(scNumber, statement);
|
|
92
115
|
|
|
93
116
|
// Append SC line to the end of the file
|
|
94
117
|
const newContent = content.trimEnd() + "\n" + scLine + "\n";
|
|
95
118
|
writeFileSync(specPath, newContent);
|
|
96
119
|
console.log(`Appended to ${specPath}: ${scLine}`);
|
|
120
|
+
// What the number is a floor over, stated rather than implied. A clone on
|
|
121
|
+
// another machine is outside anything this process can reach, and an
|
|
122
|
+
// allocator that printed only the number would be claiming a guarantee it
|
|
123
|
+
// cannot give (`.claude/rules/config-access.md`).
|
|
124
|
+
console.log(` namespace: ${describeReading(namespace)}`);
|
|
125
|
+
console.log(` owner: ${owner ?? "(none — allocated above every reserved block)"}`);
|
|
126
|
+
for (const gap of namespace.unmeasured) console.log(` UNMEASURED: ${gap}`);
|
|
97
127
|
} else {
|
|
98
128
|
// Output to stdout for piping
|
|
99
129
|
const scLine = formatSCLine(0, statement);
|
package/scripts/create-spec.ts
CHANGED
|
@@ -17,6 +17,7 @@ import { existsSync, writeFileSync, mkdirSync } from "fs";
|
|
|
17
17
|
import { join } from "path";
|
|
18
18
|
import { isMatchablePattern, isBehavioralSC, type ParsedSC } from "../lib/conformity";
|
|
19
19
|
import { loadRegistry, type RegistryEntry } from "../lib/create-sc";
|
|
20
|
+
import { localCalendarDay } from "../lib/local-calendar-day";
|
|
20
21
|
|
|
21
22
|
// ── Argument parsing ──────────────────────────────────────────
|
|
22
23
|
|
|
@@ -123,7 +124,7 @@ if (scStatements.length > 0) {
|
|
|
123
124
|
|
|
124
125
|
// ── Generate spec content ─────────────────────────────────────
|
|
125
126
|
|
|
126
|
-
const today =
|
|
127
|
+
const today = localCalendarDay();
|
|
127
128
|
|
|
128
129
|
// Build SC lines from validated --sc statements, or use placeholder
|
|
129
130
|
let scSection: string;
|
|
@@ -19,6 +19,7 @@ import { existsSync, lstatSync, readFileSync, unlinkSync, writeFileSync } from "
|
|
|
19
19
|
import { dirname, join, resolve } from "path";
|
|
20
20
|
import { fileURLToPath } from "url";
|
|
21
21
|
import { seedFromTemplate } from "../lib/success-doc";
|
|
22
|
+
import { localCalendarDay } from "../lib/local-calendar-day";
|
|
22
23
|
|
|
23
24
|
const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
|
|
24
25
|
|
|
@@ -121,7 +122,7 @@ if (/[\r\n:]/.test(owner)) {
|
|
|
121
122
|
);
|
|
122
123
|
process.exit(1);
|
|
123
124
|
}
|
|
124
|
-
const today =
|
|
125
|
+
const today = localCalendarDay();
|
|
125
126
|
|
|
126
127
|
// The SHARED substitution, so this and the scaffold's seed step cannot
|
|
127
128
|
// produce different bytes for the same logical seed.
|
|
@@ -1,9 +1,25 @@
|
|
|
1
1
|
#!/usr/bin/env bun
|
|
2
2
|
import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
|
|
3
3
|
import { join, relative } from "path";
|
|
4
|
-
import { createHash } from "crypto";
|
|
5
4
|
import { SIGNAL_PHRASE_PATTERNS } from "../lib/signal-phrases";
|
|
6
5
|
import { planDocScan, type DocScanPlan } from "../lib/doc-scan-targets";
|
|
6
|
+
import { lastCommitDates } from "../lib/git-dates";
|
|
7
|
+
import { contentHash } from "../lib/content-hash";
|
|
8
|
+
import {
|
|
9
|
+
mineFixCommits,
|
|
10
|
+
type EvidenceCandidate,
|
|
11
|
+
type FailureIntakeReading,
|
|
12
|
+
} from "../lib/failure-intake";
|
|
13
|
+
import {
|
|
14
|
+
promoteCandidates,
|
|
15
|
+
PROMOTION_BUDGET_RULES,
|
|
16
|
+
type PromotionReading,
|
|
17
|
+
} from "../lib/rule-promotion";
|
|
18
|
+
import {
|
|
19
|
+
retireUnresolvable,
|
|
20
|
+
survivingSubset,
|
|
21
|
+
type RetirementReading,
|
|
22
|
+
} from "../lib/rule-retirement";
|
|
7
23
|
|
|
8
24
|
// ── Types ────────────────────────────────────────────────────────
|
|
9
25
|
|
|
@@ -21,6 +37,37 @@ export interface StalenessEntry {
|
|
|
21
37
|
type: string;
|
|
22
38
|
}
|
|
23
39
|
|
|
40
|
+
/**
|
|
41
|
+
* What the scan planned against what it actually read (#508).
|
|
42
|
+
*
|
|
43
|
+
* `scan` below says what the walk could SEE. Nothing said what the extractor
|
|
44
|
+
* then managed to READ, and the two are different questions: a candidate
|
|
45
|
+
* count of zero from a scan that read 91 documents and a candidate count of
|
|
46
|
+
* zero from a scan that read 4 are the same line of output.
|
|
47
|
+
*
|
|
48
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` states the general form
|
|
49
|
+
* after #492 measured it — *a scan that reports a verdict should report its
|
|
50
|
+
* own coverage* — and HYGIENE-6 is the verdict in question: it ended in
|
|
51
|
+
* `expect(true).toBe(true)`, so a timeout was the only red it could produce.
|
|
52
|
+
*/
|
|
53
|
+
export interface ScanCoverage {
|
|
54
|
+
/** Documents the plan listed. */
|
|
55
|
+
planned: number;
|
|
56
|
+
/** Documents whose bytes reached `extractSignalPhrases`. */
|
|
57
|
+
read: number;
|
|
58
|
+
/**
|
|
59
|
+
* Planned documents the read could not take, with the error that stopped
|
|
60
|
+
* it — `ENOENT` for a file that moved between the walk and the read,
|
|
61
|
+
* `EISDIR`, `EACCES`.
|
|
62
|
+
*
|
|
63
|
+
* Recorded rather than thrown, and recorded rather than dropped. A throw
|
|
64
|
+
* takes an advisory backlog report down over one transient file; a drop
|
|
65
|
+
* makes a partial scan indistinguishable from a complete one, which is
|
|
66
|
+
* the failure this whole interface exists to stop.
|
|
67
|
+
*/
|
|
68
|
+
unread: Array<{ file: string; reason: string }>;
|
|
69
|
+
}
|
|
70
|
+
|
|
24
71
|
export interface ExtractResult {
|
|
25
72
|
candidates: Candidate[];
|
|
26
73
|
deduped: {
|
|
@@ -29,6 +76,34 @@ export interface ExtractResult {
|
|
|
29
76
|
candidatesRemoved: number;
|
|
30
77
|
};
|
|
31
78
|
staleness: StalenessEntry[];
|
|
79
|
+
/** What was planned against what was read. Never inferred from `candidates`. */
|
|
80
|
+
coverage: ScanCoverage;
|
|
81
|
+
/**
|
|
82
|
+
* Observed failures mined from `fix:` and `Revert` commits (#545).
|
|
83
|
+
*
|
|
84
|
+
* Carried BESIDE `candidates` rather than merged into it, deliberately. The
|
|
85
|
+
* two populations answer different questions — "is this sentence
|
|
86
|
+
* rule-shaped" against "did something go wrong and cost us something" — and
|
|
87
|
+
* folding them together would move HYGIENE-6's advisory backlog count for a
|
|
88
|
+
* reason that has nothing to do with the backlog.
|
|
89
|
+
*/
|
|
90
|
+
evidence: FailureIntakeReading;
|
|
91
|
+
/**
|
|
92
|
+
* Who survives, and why everything else did not (#544). Computed over BOTH
|
|
93
|
+
* populations, which is the point: the doc candidates are what the
|
|
94
|
+
* evidence-required criterion is being applied to.
|
|
95
|
+
*/
|
|
96
|
+
promotion: PromotionReading;
|
|
97
|
+
/**
|
|
98
|
+
* What the generator stopped emitting, and why (#544, SC-1941).
|
|
99
|
+
*
|
|
100
|
+
* Separate from `promotion` for the same reason `evidence` is: a candidate
|
|
101
|
+
* dropped because the commit it cites was rebased away and one dropped
|
|
102
|
+
* because it ranked below the cut are different events with different
|
|
103
|
+
* repairs, and one `withheld` list carrying both would need a reader to
|
|
104
|
+
* tell them apart by reason string.
|
|
105
|
+
*/
|
|
106
|
+
retirement: RetirementReading<EvidenceCandidate | Candidate>;
|
|
32
107
|
/**
|
|
33
108
|
* What was scanned and what could not be (#440).
|
|
34
109
|
*
|
|
@@ -42,9 +117,14 @@ export interface ExtractResult {
|
|
|
42
117
|
|
|
43
118
|
// ── Helpers ──────────────────────────────────────────────────────
|
|
44
119
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
120
|
+
// `contentHash` lives in `lib/content-hash.ts` now and is re-exported here
|
|
121
|
+
// under the name its callers already know — one binding, two names, the
|
|
122
|
+
// arrangement `lastCommitDates` has with `lib/conformity.ts` (#508). It moved
|
|
123
|
+
// because `lib/failure-intake.ts` is a second producer of candidates and the
|
|
124
|
+
// SC-137 veto table matches on this hash: two implementations of it would be
|
|
125
|
+
// behaviourally one until the day they disagreed, and the veto would silently
|
|
126
|
+
// stop applying to whichever producer used the other copy.
|
|
127
|
+
export { contentHash };
|
|
48
128
|
|
|
49
129
|
function surroundingContext(lines: string[], lineIdx: number): string {
|
|
50
130
|
const start = Math.max(0, lineIdx - 1);
|
|
@@ -111,24 +191,44 @@ function loadRejectedHashes(projectPath: string): Set<string> {
|
|
|
111
191
|
return hashes;
|
|
112
192
|
}
|
|
113
193
|
|
|
194
|
+
/**
|
|
195
|
+
* One git subprocess for every document, not one per document (#508).
|
|
196
|
+
*
|
|
197
|
+
* This was `Bun.spawnSync(["git", …, "log", "-1", …, "--", rel])` inside
|
|
198
|
+
* the loop — the exact code #323 removed from `runDocHygiene`, in a file
|
|
199
|
+
* #323 did not touch. 92 documents meant 92 serial subprocesses against
|
|
200
|
+
* the same repository, and nothing was wrong with any single one: the
|
|
201
|
+
* check was load-sensitive by construction, so a busy machine, a cold
|
|
202
|
+
* cache or another suite holding the index pushed it past the 5000ms
|
|
203
|
+
* default test timeout. Measured before the change at 4169ms, 4521ms and
|
|
204
|
+
* 3969ms on an IDLE machine with a warm cache; HYGIENE-6 had been seen red
|
|
205
|
+
* four times in full runs and green standalone every time.
|
|
206
|
+
*
|
|
207
|
+
* `lastCommitDates` walks the whole history newest-first with `--name-only`
|
|
208
|
+
* and returns every path's latest commit date from one call. Imported from
|
|
209
|
+
* `lib/git-dates.ts` rather than copied, because two implementations of
|
|
210
|
+
* one question are behaviourally one and no test can tell them apart.
|
|
211
|
+
*/
|
|
114
212
|
function computeStaleness(projectPath: string, files: string[]): StalenessEntry[] {
|
|
213
|
+
const considered = files
|
|
214
|
+
.map(f => relative(projectPath, f))
|
|
215
|
+
.filter(rel => !(rel.includes("docs/adr/") || /ADR/i.test(rel)));
|
|
216
|
+
// The exact lookup set is the pathspec, so the keys and the query cannot
|
|
217
|
+
// drift — #323 got this wrong first time by passing the directories.
|
|
218
|
+
const lastCommit = lastCommitDates(projectPath, considered);
|
|
219
|
+
|
|
115
220
|
const stale: StalenessEntry[] = [];
|
|
116
|
-
for (const
|
|
117
|
-
const
|
|
118
|
-
|
|
119
|
-
if (
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
const type = isSpec ? "spec" : "guide";
|
|
128
|
-
if (daysSince > threshold) {
|
|
129
|
-
stale.push({ file: rel, daysSince: Math.floor(daysSince), threshold, type });
|
|
130
|
-
}
|
|
131
|
-
} catch {}
|
|
221
|
+
for (const rel of considered) {
|
|
222
|
+
const dateStr = lastCommit.get(rel);
|
|
223
|
+
// No commit means untracked or newly added, which is the opposite of stale.
|
|
224
|
+
if (!dateStr) continue;
|
|
225
|
+
const daysSince = (Date.now() - new Date(dateStr).getTime()) / (1000 * 60 * 60 * 24);
|
|
226
|
+
const isSpec = rel.startsWith("specs/");
|
|
227
|
+
const threshold = isSpec ? 90 : 180;
|
|
228
|
+
const type = isSpec ? "spec" : "guide";
|
|
229
|
+
if (daysSince > threshold) {
|
|
230
|
+
stale.push({ file: rel, daysSince: Math.floor(daysSince), threshold, type });
|
|
231
|
+
}
|
|
132
232
|
}
|
|
133
233
|
return stale;
|
|
134
234
|
}
|
|
@@ -171,16 +271,32 @@ function applyToAgentsMd(projectPath: string, candidates: Candidate[]): void {
|
|
|
171
271
|
|
|
172
272
|
export async function extractConstraints(
|
|
173
273
|
projectPath: string,
|
|
174
|
-
options?: { apply?: boolean }
|
|
274
|
+
options?: { apply?: boolean; plan?: DocScanPlan }
|
|
175
275
|
): Promise<ExtractResult> {
|
|
176
|
-
|
|
276
|
+
// `plan` is a seam, and it is here for one reason worth stating: the
|
|
277
|
+
// unread branch below is unreachable from outside this function, because
|
|
278
|
+
// the walk that produces the plan only lists files it has just stat'd. A
|
|
279
|
+
// branch no test can reach is the subject of this repo's central rule, so
|
|
280
|
+
// the plan is an input a caller may supply — which is also the race the
|
|
281
|
+
// branch is about, a plan taken a moment before the tree moved.
|
|
282
|
+
const scan = options?.plan ?? planDocScan(projectPath);
|
|
177
283
|
const scanFiles = scan.files;
|
|
178
284
|
const existingConstraints = loadExistingConstraints(projectPath);
|
|
179
285
|
const rejectedHashes = loadRejectedHashes(projectPath);
|
|
180
286
|
|
|
181
287
|
let allCandidates: Candidate[] = [];
|
|
288
|
+
const unread: ScanCoverage["unread"] = [];
|
|
289
|
+
let read = 0;
|
|
182
290
|
for (const filePath of scanFiles) {
|
|
183
|
-
|
|
291
|
+
let content: string;
|
|
292
|
+
try {
|
|
293
|
+
content = readFileSync(filePath, "utf-8");
|
|
294
|
+
} catch (err) {
|
|
295
|
+
const e = err as NodeJS.ErrnoException;
|
|
296
|
+
unread.push({ file: relative(projectPath, filePath), reason: e.code ?? e.name });
|
|
297
|
+
continue;
|
|
298
|
+
}
|
|
299
|
+
read++;
|
|
184
300
|
allCandidates.push(...extractSignalPhrases(content, filePath, projectPath));
|
|
185
301
|
}
|
|
186
302
|
|
|
@@ -203,18 +319,73 @@ export async function extractConstraints(
|
|
|
203
319
|
|
|
204
320
|
const staleness = computeStaleness(projectPath, scanFiles);
|
|
205
321
|
|
|
206
|
-
|
|
207
|
-
|
|
322
|
+
// #545. One bounded `git log`, after the document walk, so a repository
|
|
323
|
+
// without one costs nothing and a repository with one is read once.
|
|
324
|
+
const evidence = mineFixCommits(projectPath);
|
|
325
|
+
|
|
326
|
+
// #544. The doc candidates arrive with no `evidence` field at all, so the
|
|
327
|
+
// gate withholds every one of them. That is not a bug in the wiring — it is
|
|
328
|
+
// the measurement: signal-phrase extraction produces nothing a promotion
|
|
329
|
+
// criterion based on observed failure can promote.
|
|
330
|
+
// #544 SC-1941. Retirement runs BEFORE promotion and over both
|
|
331
|
+
// populations: a candidate citing a commit that was rebased away, or a
|
|
332
|
+
// `path:line` in a file that has since moved, is dropped rather than
|
|
333
|
+
// ranked. Recency is the only ordering signal the promoter has, so a
|
|
334
|
+
// candidate citing a vanished sha would otherwise rank at the very top.
|
|
335
|
+
//
|
|
336
|
+
// Its reading is folded into the promotion as an upstream, not merged into
|
|
337
|
+
// one here: `0 retired` on a shallow clone means the question could not be
|
|
338
|
+
// asked, and a promotion that reported MEASURED over that population would
|
|
339
|
+
// be claiming a completeness nothing established.
|
|
340
|
+
const retirement = retireUnresolvable(
|
|
341
|
+
[...evidence.candidates, ...allCandidates],
|
|
342
|
+
projectPath,
|
|
343
|
+
);
|
|
344
|
+
|
|
345
|
+
const promotion = promoteCandidates(
|
|
346
|
+
retirement.kept,
|
|
347
|
+
{
|
|
348
|
+
budget: PROMOTION_BUDGET_RULES,
|
|
349
|
+
rejectedHashes: rejectedHashes,
|
|
350
|
+
upstream: [evidence, retirement],
|
|
351
|
+
},
|
|
352
|
+
);
|
|
353
|
+
|
|
354
|
+
// #544. The gate has to reach the WRITE, or it is a control with no sink.
|
|
355
|
+
//
|
|
356
|
+
// Until this line, `--apply` wrote `allCandidates` — the unfiltered list —
|
|
357
|
+
// so a candidate the retirement pass had just dropped was written into
|
|
358
|
+
// `AGENTS.md` anyway and `retirement` was a field on the result that
|
|
359
|
+
// nothing downstream consulted. A gate whose verdict changes no output is
|
|
360
|
+
// not a fail-open; it is decoration.
|
|
361
|
+
//
|
|
362
|
+
// Filtered by object identity, not by hash: the same candidate objects
|
|
363
|
+
// flow through `retireUnresolvable`, and a hash is a judgement about a
|
|
364
|
+
// SENTENCE — two candidates mined from different positions can share one
|
|
365
|
+
// (`lib/failure-intake.ts` relies on exactly that for a revert and the fix
|
|
366
|
+
// it reverts), so matching on it would drop a survivor alongside a retired
|
|
367
|
+
// twin.
|
|
368
|
+
const keptDocCandidates = survivingSubset(allCandidates, retirement);
|
|
369
|
+
|
|
370
|
+
if (options?.apply && keptDocCandidates.length > 0) {
|
|
371
|
+
applyToAgentsMd(projectPath, keptDocCandidates);
|
|
208
372
|
}
|
|
209
373
|
|
|
210
374
|
return {
|
|
211
|
-
|
|
375
|
+
// The backlog HYGIENE-6 counts is the surviving population, for the same
|
|
376
|
+
// reason: re-reporting a candidate the generator has already retired
|
|
377
|
+
// asks somebody to triage a position that is not there any more.
|
|
378
|
+
candidates: keptDocCandidates,
|
|
212
379
|
deduped: {
|
|
213
380
|
existingConstraints: existingRemoved,
|
|
214
381
|
rejectedPrior: rejectedRemoved,
|
|
215
382
|
candidatesRemoved: existingRemoved + rejectedRemoved,
|
|
216
383
|
},
|
|
217
384
|
staleness,
|
|
385
|
+
coverage: { planned: scanFiles.length, read, unread },
|
|
386
|
+
evidence,
|
|
387
|
+
retirement,
|
|
388
|
+
promotion,
|
|
218
389
|
scan,
|
|
219
390
|
};
|
|
220
391
|
}
|
|
@@ -10,6 +10,13 @@
|
|
|
10
10
|
*/
|
|
11
11
|
import { existsSync, readFileSync, readdirSync, writeFileSync, statSync } from "fs";
|
|
12
12
|
import { join, basename } from "path";
|
|
13
|
+
import { localCalendarDay } from "../lib/local-calendar-day";
|
|
14
|
+
import {
|
|
15
|
+
fallowAvailable,
|
|
16
|
+
fallowUnmeasuredNotice,
|
|
17
|
+
runFallowJson,
|
|
18
|
+
type FallowUnavailable,
|
|
19
|
+
} from "../lib/fallow-availability";
|
|
13
20
|
|
|
14
21
|
const projectPath = process.argv[2];
|
|
15
22
|
if (!projectPath || !existsSync(projectPath)) {
|
|
@@ -18,7 +25,7 @@ if (!projectPath || !existsSync(projectPath)) {
|
|
|
18
25
|
}
|
|
19
26
|
|
|
20
27
|
const projectName = basename(projectPath);
|
|
21
|
-
const today =
|
|
28
|
+
const today = localCalendarDay();
|
|
22
29
|
|
|
23
30
|
// ── Fallow analysis ──────────────────────────────────────────
|
|
24
31
|
|
|
@@ -30,27 +37,45 @@ interface FallowData {
|
|
|
30
37
|
elapsed: number;
|
|
31
38
|
}
|
|
32
39
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
40
|
+
/**
|
|
41
|
+
* Three outcomes, not two (#581).
|
|
42
|
+
*
|
|
43
|
+
* This returned `null` for "not installed", "the spawn failed", "the output
|
|
44
|
+
* did not parse" and — through `||` in the summary table below — "it ran and
|
|
45
|
+
* found zero". A CODE-MAP written from any of them was byte-identical, so a
|
|
46
|
+
* reader could not tell a project with no dead code from a project nobody
|
|
47
|
+
* looked at.
|
|
48
|
+
*/
|
|
49
|
+
type FallowOutcome = { data: FallowData } | { unavailable: FallowUnavailable };
|
|
50
|
+
|
|
51
|
+
function runFallow(): FallowOutcome {
|
|
52
|
+
// Resolved locally, with no network path. A bare `npx fallow` for a tool
|
|
53
|
+
// that is not a declared dependency is a registry fetch on the SCAFFOLD
|
|
54
|
+
// path — once per consumer, forever, including behind a proxy and in an
|
|
55
|
+
// air-gapped CI. `lib/conformity.ts` fixed this for itself in #510 and
|
|
56
|
+
// this caller never got it.
|
|
57
|
+
//
|
|
58
|
+
// The spawn, the budget and the classification are no longer here: they
|
|
59
|
+
// were a second copy of `lib/conformity.ts`'s, with a second `30_000`
|
|
60
|
+
// literal, and the two disagreed about what to do with a killed run. One
|
|
61
|
+
// binding now, in `lib/fallow-availability.ts` (#935). What stays here is
|
|
62
|
+
// the SHAPING of fallow's JSON into the fields CODE-MAP.md needs, which is
|
|
63
|
+
// this script's own business and nobody else's.
|
|
64
|
+
const root = fallowAvailable(projectPath) ? projectPath : process.cwd();
|
|
65
|
+
const reading = runFallowJson<any>(root, ["dead-code"]);
|
|
66
|
+
if ("unavailable" in reading) return { unavailable: reading.unavailable };
|
|
67
|
+
const d = reading.data;
|
|
68
|
+
return { data: {
|
|
69
|
+
entryPoints: d.entry_points?.total || 0,
|
|
70
|
+
unusedFiles: (d.unused_files || []).map((f: any) => f.path),
|
|
71
|
+
unusedExports: (d.unused_exports || []).map((e: any) => ({
|
|
72
|
+
path: e.path, export_name: e.export_name, line: e.line
|
|
73
|
+
})),
|
|
74
|
+
circularDeps: (d.circular_dependencies || []).map((c: any) => ({
|
|
75
|
+
files: c.files || [c.path]
|
|
76
|
+
})),
|
|
77
|
+
elapsed: d.elapsed_ms || 0,
|
|
78
|
+
} };
|
|
54
79
|
}
|
|
55
80
|
|
|
56
81
|
// ── Route scanning ───────────────────────────────────────────
|
|
@@ -192,7 +217,9 @@ function readPackageInfo(): { name: string; deps: number; devDeps: number; scrip
|
|
|
192
217
|
|
|
193
218
|
console.log(`Scanning ${projectName}...`);
|
|
194
219
|
|
|
195
|
-
const
|
|
220
|
+
const fallowOutcome = runFallow();
|
|
221
|
+
const fallow = "data" in fallowOutcome ? fallowOutcome.data : null;
|
|
222
|
+
const fallowMissing = "unavailable" in fallowOutcome ? fallowOutcome.unavailable : null;
|
|
196
223
|
const routes = scanRoutes();
|
|
197
224
|
const dirs = scanDirectories();
|
|
198
225
|
const components = scanComponents();
|
|
@@ -200,7 +227,9 @@ const pkg = readPackageInfo();
|
|
|
200
227
|
const consumerMappings = scanConsumerModules();
|
|
201
228
|
const pageMappings = scanPageComponents();
|
|
202
229
|
|
|
203
|
-
console.log(
|
|
230
|
+
console.log(
|
|
231
|
+
` Fallow: ${fallow ? `${fallow.entryPoints} entry points, ${fallow.elapsed}ms` : `UNMEASURED — ${fallowMissing?.reason}`}`,
|
|
232
|
+
);
|
|
204
233
|
console.log(` Routes: ${routes.length}`);
|
|
205
234
|
console.log(` Directories: ${dirs.length}`);
|
|
206
235
|
console.log(` Components: ${components.length}`);
|
|
@@ -240,10 +269,10 @@ sections.push(`## Summary
|
|
|
240
269
|
| Dev dependencies | ${pkg.devDeps} |
|
|
241
270
|
| API routes | ${routes.length} |
|
|
242
271
|
| React components | ${components.length} |
|
|
243
|
-
| Entry points (fallow) | ${fallow
|
|
244
|
-
| Unused files | ${fallow
|
|
245
|
-
| Unused exports | ${fallow
|
|
246
|
-
| Circular dependencies | ${fallow
|
|
272
|
+
| Entry points (fallow) | ${fallow ? fallow.entryPoints : "UNMEASURED"} |
|
|
273
|
+
| Unused files | ${fallow ? fallow.unusedFiles.length : "UNMEASURED"} |
|
|
274
|
+
| Unused exports | ${fallow ? fallow.unusedExports.length : "UNMEASURED"} |
|
|
275
|
+
| Circular dependencies | ${fallow ? fallow.circularDeps.length : "UNMEASURED"} |
|
|
247
276
|
| Module import mappings | ${consumerMappings.length} |
|
|
248
277
|
| Page-component mappings | ${pageMappings.length} |`);
|
|
249
278
|
|
|
@@ -324,6 +353,11 @@ if (fallow) {
|
|
|
324
353
|
}
|
|
325
354
|
|
|
326
355
|
sections.push(health.trim());
|
|
356
|
+
} else if (fallowMissing) {
|
|
357
|
+
// Named, not omitted. A missing section and a section reporting nothing
|
|
358
|
+
// wrong are the same absence to a reader, and the reader of a CODE-MAP is
|
|
359
|
+
// an agent deciding whether this project has dead code.
|
|
360
|
+
sections.push(fallowUnmeasuredNotice(fallowMissing));
|
|
327
361
|
}
|
|
328
362
|
|
|
329
363
|
// Scripts
|
|
@@ -104,11 +104,21 @@ if (fix) {
|
|
|
104
104
|
// actually do rather than what it would do with different settings (#398).
|
|
105
105
|
runScaffoldWriteSteps(rehearsal.dir, projectType, actions, { force, commit: false, rehearsing: true, profile, autoFix, pruneConsumers });
|
|
106
106
|
} finally {
|
|
107
|
-
|
|
107
|
+
// #549: a cleanup failure is a sentence, not an exception. The report
|
|
108
|
+
// has already printed by now, and throwing here threw it away.
|
|
109
|
+
const leaked = discardRehearsal(rehearsal);
|
|
110
|
+
if (leaked) console.error(`WARNING: ${leaked}`);
|
|
108
111
|
}
|
|
109
112
|
}
|
|
110
113
|
|
|
111
114
|
// ── Report ─────────────────────────────────────────────────────
|
|
112
115
|
|
|
113
116
|
// A refusal that only prints is one nobody's CI notices (#216).
|
|
114
|
-
|
|
117
|
+
//
|
|
118
|
+
// `!fix` is the mode, read from the same flag the branch above dispatches on
|
|
119
|
+
// rather than from a second variable that could disagree with it (#642). The
|
|
120
|
+
// notice at the top of the run is not enough on its own: a report line is
|
|
121
|
+
// what a grep, a `| tail`, a scrolled terminal and an agent reading the last
|
|
122
|
+
// N lines of a tool result each receive, and without this every one of them
|
|
123
|
+
// was byte-identical to the line a run that really wrote the file prints.
|
|
124
|
+
if (reportScaffoldActions(actions, { rehearsed: !fix }) > 0) process.exit(1);
|
package/scripts/split-spec.ts
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
import { readFileSync, writeFileSync, mkdirSync } from "fs";
|
|
4
4
|
import { join, dirname } from "path";
|
|
5
|
+
import { localCalendarDay } from "../lib/local-calendar-day";
|
|
5
6
|
|
|
6
7
|
export interface SplitBoundary {
|
|
7
8
|
heading: string;
|
|
@@ -166,7 +167,7 @@ export function generateSplitFiles(
|
|
|
166
167
|
metadata: { owner: string; testable: boolean }
|
|
167
168
|
): SplitFile[] {
|
|
168
169
|
const lines = content.split("\n");
|
|
169
|
-
const now =
|
|
170
|
+
const now = localCalendarDay();
|
|
170
171
|
const groups = groupBoundaries(boundaries, lines.length);
|
|
171
172
|
|
|
172
173
|
return groups.map((group) => {
|