rungate 0.2.1 → 0.4.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/bin/rungate.ts +70 -0
- package/lib/aes-calculator.ts +66 -0
- package/lib/agent-audit.ts +139 -0
- package/lib/agent-brief-validation.ts +359 -0
- package/lib/agents-md-refs.ts +90 -0
- package/lib/bash-file-read.ts +197 -0
- package/lib/behavioral-cache.ts +78 -0
- package/lib/branch-cleanup.ts +234 -0
- package/lib/brief-context-parser.ts +35 -0
- package/lib/brief-precedence.ts +114 -0
- package/lib/canary.ts +117 -0
- package/lib/check-registry.ts +226 -0
- package/lib/ci-checkout.ts +426 -0
- package/lib/cli-commands.ts +137 -0
- package/lib/compliance-backfill.ts +232 -0
- package/lib/compliance-report.ts +605 -0
- package/lib/compliance.ts +361 -0
- package/lib/config-loader.ts +255 -0
- package/lib/config-readers.ts +86 -0
- package/lib/conformity.ts +2161 -137
- package/lib/container-provenance.ts +230 -0
- package/lib/create-brief.ts +150 -0
- package/lib/create-sc.ts +267 -0
- package/lib/decomposition-waves.ts +197 -0
- package/lib/deep-merge.ts +69 -0
- package/lib/dev-liveness.ts +214 -0
- package/lib/directive-extractor.ts +210 -0
- package/lib/distribution-standing.ts +113 -0
- package/lib/doc-hygiene.ts +238 -0
- package/lib/eval-criteria.ts +6 -0
- package/lib/evidence-portability.ts +123 -0
- package/lib/evidence-prevalidator.ts +390 -0
- package/lib/evidence-required.ts +150 -0
- package/lib/evidence-satisfiability.ts +288 -0
- package/lib/frontmatter.ts +163 -0
- package/lib/gap-scanner.ts +348 -0
- package/lib/gate-check-audit.ts +190 -0
- package/lib/gate-enforcement.ts +366 -0
- package/lib/generators/agent-briefs.ts +136 -0
- package/lib/generators/agents-md.ts +511 -0
- package/lib/generators/code-map.ts +60 -0
- package/lib/generators/types.ts +184 -0
- package/lib/git-ref-normalizer.ts +107 -0
- package/lib/github.ts +539 -0
- package/lib/harness-identity.ts +63 -0
- package/lib/hill-climb.ts +164 -0
- package/lib/instruction-effectiveness.ts +131 -0
- package/lib/issue-closure-audit.ts +225 -0
- package/lib/issue-create-override.ts +343 -0
- package/lib/issue-extraction.ts +368 -0
- package/lib/js-top-level-code.ts +250 -0
- package/lib/liveness-contradiction.ts +149 -0
- package/lib/organize.ts +505 -0
- package/lib/paths.ts +197 -6
- package/lib/phase2-decomposition.ts +270 -0
- package/lib/post-fix-verify.ts +157 -0
- package/lib/prior-branch.ts +512 -0
- package/lib/project-state-shape.ts +166 -0
- package/lib/promote-outputs.ts +156 -0
- package/lib/prove-label-gate.ts +128 -0
- package/lib/reachability.ts +302 -0
- package/lib/release-preflight.ts +288 -0
- package/lib/rule-health-pipeline.ts +264 -0
- package/lib/rule-health-trend.ts +161 -0
- package/lib/rule-provenance.ts +149 -0
- package/lib/rule-registry.ts +128 -0
- package/lib/rungate-schema.ts +127 -5
- package/lib/sc-claim-forms.ts +179 -0
- package/lib/sc-cover.ts +150 -0
- package/lib/sc-guard.ts +157 -0
- package/lib/sc-ids.ts +344 -0
- package/lib/scaffold/defaults.ts +165 -0
- package/lib/scaffold/managed-workflow.ts +370 -0
- package/lib/scaffold/owned-files.ts +265 -0
- package/lib/scaffold/pre-push-hook.ts +165 -0
- package/lib/scaffold/steps.ts +2621 -0
- package/lib/scanner.ts +701 -0
- package/lib/scope-denylist.ts +258 -0
- package/lib/screenshot-upload.ts +73 -0
- package/lib/secret-patterns.ts +112 -0
- package/lib/security-verdict.ts +616 -0
- package/lib/signal-phrases.ts +1 -0
- package/lib/spec-change-conformity.ts +80 -0
- package/lib/spec-files.ts +62 -0
- package/lib/spec-registry.ts +133 -0
- package/lib/spec-updater.ts +96 -0
- package/lib/stale-cleanup.ts +224 -0
- package/lib/stale-issue-scanner.ts +36 -0
- package/lib/strip-js-comments.ts +269 -0
- package/lib/suite-measurement.ts +228 -0
- package/lib/task-completion-checks.ts +224 -0
- package/lib/test-suite-lock.ts +1136 -0
- package/lib/transcript-checker.ts +1140 -0
- package/lib/typescript-project.ts +233 -0
- package/lib/validators/spec-validators.ts +171 -0
- package/lib/verdict-capture.ts +73 -0
- package/lib/verified-push.ts +535 -0
- package/lib/workflow-security.ts +174 -0
- package/lib/worktree-cleanup.ts +432 -0
- package/lib/worktree-collect.ts +283 -0
- package/lib/worktree-isolation.ts +82 -0
- package/lib/worktree-repo.ts +300 -0
- package/package.json +27 -3
- package/prompts/ac-adversary.md +14 -2
- package/prompts/aditi.md +5 -0
- package/prompts/blast-radius.md +5 -0
- package/prompts/container-verify.md +5 -0
- package/prompts/discovery.md +4 -0
- package/prompts/environment.md +5 -0
- package/prompts/evidence-hierarchy.md +5 -0
- package/prompts/evidence-validator.md +11 -0
- package/prompts/marcus.md +5 -0
- package/prompts/prevention.md +5 -0
- package/prompts/prove-reproducer.md +12 -0
- package/prompts/quinn-decision-tree.md +5 -0
- package/prompts/quinn-ui-brief.md +5 -0
- package/prompts/quinn.md +5 -0
- package/prompts/rca.md +5 -0
- package/prompts/read-before-write.md +4 -0
- package/prompts/regression.md +5 -0
- package/prompts/serena.md +5 -0
- package/scripts/audit-specs.ts +464 -0
- package/scripts/convert-spec.ts +293 -0
- package/scripts/create-sc.ts +92 -0
- package/scripts/create-spec.ts +166 -0
- package/scripts/extract-constraints.ts +4 -3
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/scaffold-project.ts +138 -1426
- package/scripts/sync-spec-tests.ts +211 -126
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether a release may be cut, and whether one actually was (#364).
|
|
3
|
+
*
|
|
4
|
+
* `rungate` has been published twice ever — `0.2.0` and `0.2.1`. `main` is
|
|
5
|
+
* 741 commits past the second. A consumer installing from npm receives a
|
|
6
|
+
* harness without any of the gate, collector or claim-audit work that
|
|
7
|
+
* `SUCCESS.md` cites as evidence, which is why #366 made the file say so and
|
|
8
|
+
* why this file exists to stop it drifting again.
|
|
9
|
+
*
|
|
10
|
+
* ## The failure this is built around
|
|
11
|
+
*
|
|
12
|
+
* The issue named it, and it is the shape `.claude/rules/checks-must-be-able-
|
|
13
|
+
* to-fail.md` opens with:
|
|
14
|
+
*
|
|
15
|
+
* > A publish job that exits 0 because npm rejected a duplicate version is
|
|
16
|
+
* > exactly the "could not measure reads as nothing wrong" shape, and it is
|
|
17
|
+
* > the most likely way this fix ships broken.
|
|
18
|
+
*
|
|
19
|
+
* A release pipeline has an unusually quiet way of doing nothing. The publish
|
|
20
|
+
* step can be skipped by an `if:` that stopped matching, swallowed by a
|
|
21
|
+
* `continue-on-error`, or rejected by the registry as a duplicate — and in
|
|
22
|
+
* every case the job is green and the tag exists. Nothing downstream can tell
|
|
23
|
+
* "we shipped 0.2.3" from "we tagged 0.2.3 and shipped nothing".
|
|
24
|
+
*
|
|
25
|
+
* ## Two readings, before and after
|
|
26
|
+
*
|
|
27
|
+
* So the guard is not one check but two, taken at different times, and
|
|
28
|
+
* neither is sufficient alone:
|
|
29
|
+
*
|
|
30
|
+
* - **Preflight** — the tree's version must NOT be on the registry yet. This
|
|
31
|
+
* is what makes a duplicate publish a red run rather than a no-op.
|
|
32
|
+
* - **Postflight** — after the publish step, the registry's `latest` must BE
|
|
33
|
+
* the tree's version. This is what makes a *skipped* publish a red run.
|
|
34
|
+
*
|
|
35
|
+
* Preflight alone passes a pipeline whose publish step never ran. Postflight
|
|
36
|
+
* alone passes a pipeline that republished nothing because the version was
|
|
37
|
+
* already there from last month. The pair is the same "two numbers, not one"
|
|
38
|
+
* argument `lib/distribution-standing.ts` makes about `SUCCESS.md`, applied
|
|
39
|
+
* to the act rather than to the record.
|
|
40
|
+
*/
|
|
41
|
+
|
|
42
|
+
/** What the registry currently holds for a package. */
|
|
43
|
+
export interface RegistryState {
|
|
44
|
+
/** Every published version, in no particular order. */
|
|
45
|
+
versions: string[];
|
|
46
|
+
/** The `latest` dist-tag, or `null` for a package that has never shipped. */
|
|
47
|
+
latest: string | null;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Read the registry.
|
|
52
|
+
*
|
|
53
|
+
* The packument, not `/latest`: "has 0.2.2 ever been published" cannot be
|
|
54
|
+
* answered by a dist-tag, because `latest` moves on and leaves older versions
|
|
55
|
+
* installable behind it. `distributionViolations` asks a different question
|
|
56
|
+
* and is right to use `/latest`; this one needs the whole list.
|
|
57
|
+
*
|
|
58
|
+
* Deliberately not the `npm` CLI — the registry's JSON endpoint needs no npm
|
|
59
|
+
* on the path and no lockfile, so it measures the same thing on a laptop and
|
|
60
|
+
* on CI.
|
|
61
|
+
*
|
|
62
|
+
* A 404 is a real answer: the package has never been published, so every
|
|
63
|
+
* version is available. Any other failure THROWS rather than returning an
|
|
64
|
+
* empty state, because an unreachable registry would otherwise read as "no
|
|
65
|
+
* version conflicts" and wave a duplicate straight through.
|
|
66
|
+
*/
|
|
67
|
+
export const NPM_REGISTRY = "https://registry.npmjs.org";
|
|
68
|
+
|
|
69
|
+
export async function registryState(
|
|
70
|
+
pkg: string,
|
|
71
|
+
fetchImpl: typeof fetch = fetch,
|
|
72
|
+
base: string = NPM_REGISTRY,
|
|
73
|
+
): Promise<RegistryState> {
|
|
74
|
+
const res = await fetchImpl(`${base}/${pkg}`);
|
|
75
|
+
if (res.status === 404) return { versions: [], latest: null };
|
|
76
|
+
if (!res.ok) throw new Error(`registry returned ${res.status} for ${pkg}`);
|
|
77
|
+
const body = (await res.json()) as {
|
|
78
|
+
versions?: Record<string, unknown>;
|
|
79
|
+
"dist-tags"?: { latest?: unknown };
|
|
80
|
+
};
|
|
81
|
+
const versions = body.versions ? Object.keys(body.versions) : [];
|
|
82
|
+
const latest = body["dist-tags"]?.latest;
|
|
83
|
+
return { versions, latest: typeof latest === "string" ? latest : null };
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** `1.2.3`, `1.2.3-rc.1`, `1.2.3+build` — npm's shape, not a full semver parser. */
|
|
87
|
+
const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* Does `version` satisfy a `^x.y.z` range, by npm's rules? (#364)
|
|
91
|
+
*
|
|
92
|
+
* Exists because the scaffold pins consumers to a caret floored at the
|
|
93
|
+
* harness's own minor, and whether that range can ever resolve decided
|
|
94
|
+
* whether a release could be cut at all. A tree carrying an unpublished
|
|
95
|
+
* minor emits a range nothing satisfies — `0.3.0` emits `^0.3.0` while the
|
|
96
|
+
* registry's newest is `0.2.1` — and `release.yml` runs the suite before
|
|
97
|
+
* publishing, so a check wanting the tree's version already on npm cannot
|
|
98
|
+
* pass on the run that would put it there.
|
|
99
|
+
*
|
|
100
|
+
* The caret's 0.x behaviour is the whole point and is the part hand-rolled
|
|
101
|
+
* comparisons get wrong: below 1.0.0 a caret is pinned to the MINOR, not the
|
|
102
|
+
* major, so `^0.3.0` excludes `0.4.0`. Getting that backwards would make
|
|
103
|
+
* this answer `true` for every bump and the guard would certify nothing.
|
|
104
|
+
*
|
|
105
|
+
* Deliberately narrow: `harnessDevDepRange` only ever emits `^x.y.0`, so
|
|
106
|
+
* this handles carets and refuses anything else rather than pretending to be
|
|
107
|
+
* a semver range parser.
|
|
108
|
+
*/
|
|
109
|
+
export function satisfiesCaret(version: string, range: string): boolean {
|
|
110
|
+
const r = /^\^(\d+)\.(\d+)\.(\d+)$/.exec(range);
|
|
111
|
+
const v = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version);
|
|
112
|
+
if (!r || !v) return false;
|
|
113
|
+
const [rMaj, rMin, rPat] = r.slice(1, 4).map(Number);
|
|
114
|
+
const [vMaj, vMin, vPat] = v.slice(1, 4).map(Number);
|
|
115
|
+
|
|
116
|
+
// Lower bound: the version must be at or above the floor.
|
|
117
|
+
const atOrAbove =
|
|
118
|
+
vMaj > rMaj ||
|
|
119
|
+
(vMaj === rMaj && (vMin > rMin || (vMin === rMin && vPat >= rPat)));
|
|
120
|
+
if (!atOrAbove) return false;
|
|
121
|
+
|
|
122
|
+
// Upper bound, and the 0.x special case is the reason this function exists.
|
|
123
|
+
if (rMaj > 0) return vMaj === rMaj;
|
|
124
|
+
if (rMin > 0) return vMaj === 0 && vMin === rMin;
|
|
125
|
+
return vMaj === 0 && vMin === 0 && vPat === rPat;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* The single place that decides whether a release may be cut. `null` allows.
|
|
130
|
+
*
|
|
131
|
+
* One exported function so there is one binding to mutate. `tag` is the git
|
|
132
|
+
* ref the workflow fired on, with any `refs/tags/` prefix already stripped;
|
|
133
|
+
* pass `null` for a run that is not tag-triggered.
|
|
134
|
+
*
|
|
135
|
+
* The tag comparison is here and not left to the workflow because a tag that
|
|
136
|
+
* disagrees with `package.json` publishes the version in `package.json` while
|
|
137
|
+
* every human reads the tag. That is not a release, it is two releases with
|
|
138
|
+
* one set of notes.
|
|
139
|
+
*/
|
|
140
|
+
export function preflightRefusal(
|
|
141
|
+
treeVersion: string,
|
|
142
|
+
tag: string | null,
|
|
143
|
+
state: RegistryState,
|
|
144
|
+
): string | null {
|
|
145
|
+
if (!SEMVER.test(treeVersion)) {
|
|
146
|
+
return `package.json version ${JSON.stringify(treeVersion)} is not a version npm will accept`;
|
|
147
|
+
}
|
|
148
|
+
if (tag !== null && tag !== `v${treeVersion}`) {
|
|
149
|
+
return (
|
|
150
|
+
`tag ${tag} does not name the version being published — package.json says ` +
|
|
151
|
+
`${treeVersion}, so the tag would describe a release that is not the one cut`
|
|
152
|
+
);
|
|
153
|
+
}
|
|
154
|
+
if (state.versions.includes(treeVersion)) {
|
|
155
|
+
return (
|
|
156
|
+
`rungate@${treeVersion} is already on the registry — publishing it again is ` +
|
|
157
|
+
`rejected by npm, and a job that treats that rejection as success reports a ` +
|
|
158
|
+
`release nobody can install. Bump package.json.`
|
|
159
|
+
);
|
|
160
|
+
}
|
|
161
|
+
return null;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/**
|
|
165
|
+
* The single place that decides whether a release actually happened. `null`
|
|
166
|
+
* allows.
|
|
167
|
+
*
|
|
168
|
+
* Run AFTER the publish step, against a freshly read registry. This is the
|
|
169
|
+
* half that cannot be satisfied by doing nothing: a skipped, swallowed or
|
|
170
|
+
* silently-failed publish leaves `latest` where it was.
|
|
171
|
+
*/
|
|
172
|
+
export function postflightRefusal(treeVersion: string, latestAfter: string | null): string | null {
|
|
173
|
+
if (latestAfter === null) {
|
|
174
|
+
return (
|
|
175
|
+
`the registry has no latest version for rungate after the publish step — ` +
|
|
176
|
+
`the release did not happen, whatever the job's exit code says`
|
|
177
|
+
);
|
|
178
|
+
}
|
|
179
|
+
if (latestAfter !== treeVersion) {
|
|
180
|
+
return (
|
|
181
|
+
`the registry's latest is ${latestAfter}, not the ${treeVersion} this run was ` +
|
|
182
|
+
`cutting — the publish step did not take effect`
|
|
183
|
+
);
|
|
184
|
+
}
|
|
185
|
+
return null;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/** What a postflight poll saw, and how hard it had to look (#407). */
|
|
189
|
+
export interface PostflightReading {
|
|
190
|
+
/** The `latest` dist-tag on the final read. */
|
|
191
|
+
latest: string | null;
|
|
192
|
+
/** Reads performed. 1 means the registry had it immediately. */
|
|
193
|
+
attempts: number;
|
|
194
|
+
/** Time spent sleeping between reads, in ms. */
|
|
195
|
+
waitedMs: number;
|
|
196
|
+
/** The refusal, or `null` to allow. */
|
|
197
|
+
refusal: string | null;
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/** Defaults sized for npm's observed read-after-write lag: up to ~30s. */
|
|
201
|
+
export const POSTFLIGHT_ATTEMPTS = 10;
|
|
202
|
+
export const POSTFLIGHT_DELAY_MS = 3_000;
|
|
203
|
+
|
|
204
|
+
/**
|
|
205
|
+
* Poll the registry until it serves `treeVersion`, or give up and refuse (#407).
|
|
206
|
+
*
|
|
207
|
+
* `v0.3.0` published cleanly and the release job still went red: the
|
|
208
|
+
* postflight read `registry.npmjs.org/rungate` about a second after `npm
|
|
209
|
+
* publish` returned, and that document is CDN-fronted and eventually
|
|
210
|
+
* consistent, so it was still serving `0.2.1`. The publish was fine. The check
|
|
211
|
+
* was wrong.
|
|
212
|
+
*
|
|
213
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` is about checks that cannot
|
|
214
|
+
* fail. This is the inverse and it costs the same thing, because the message
|
|
215
|
+
* is wrong either way — and a red job over a green release is how a gate
|
|
216
|
+
* teaches people to stop reading it.
|
|
217
|
+
*
|
|
218
|
+
* ## The bound is the point
|
|
219
|
+
*
|
|
220
|
+
* Retrying until it goes green would turn this into the defect in the other
|
|
221
|
+
* direction. The loop is bounded, a publish that never lands still refuses,
|
|
222
|
+
* and the refusal says how long it waited — otherwise "it refused" and "it
|
|
223
|
+
* did not wait long enough" are indistinguishable to whoever reads the log.
|
|
224
|
+
*
|
|
225
|
+
* ## Why an intermediate throw retries and the last one does not
|
|
226
|
+
*
|
|
227
|
+
* A transient network error is exactly what polling is for, so a read that
|
|
228
|
+
* throws with attempts remaining is retried. The FINAL one rethrows, because
|
|
229
|
+
* `registryState` throws rather than returning an empty state precisely so
|
|
230
|
+
* that "could not measure" cannot read as "nothing wrong" — and swallowing
|
|
231
|
+
* the last throw here would put that fail-open back.
|
|
232
|
+
*
|
|
233
|
+
* `sleep` is injectable so the exhaustion case can be driven in a test without
|
|
234
|
+
* spending 30 seconds of wall clock on it.
|
|
235
|
+
*/
|
|
236
|
+
export async function awaitRegistryServes(
|
|
237
|
+
pkg: string,
|
|
238
|
+
treeVersion: string,
|
|
239
|
+
opts: {
|
|
240
|
+
fetchImpl?: typeof fetch;
|
|
241
|
+
base?: string;
|
|
242
|
+
attempts?: number;
|
|
243
|
+
delayMs?: number;
|
|
244
|
+
sleep?: (ms: number) => Promise<void>;
|
|
245
|
+
} = {},
|
|
246
|
+
): Promise<PostflightReading> {
|
|
247
|
+
const attempts = opts.attempts ?? POSTFLIGHT_ATTEMPTS;
|
|
248
|
+
const delayMs = opts.delayMs ?? POSTFLIGHT_DELAY_MS;
|
|
249
|
+
// A zero-attempt poll reads nothing and would fall out of the loop with no
|
|
250
|
+
// refusal — a check that never runs, reported as a check that passed.
|
|
251
|
+
if (!Number.isInteger(attempts) || attempts < 1) {
|
|
252
|
+
throw new Error(`postflight needs at least one attempt, got ${opts.attempts}`);
|
|
253
|
+
}
|
|
254
|
+
const sleep = opts.sleep ?? ((ms: number) => new Promise(r => setTimeout(r, ms)));
|
|
255
|
+
|
|
256
|
+
let waitedMs = 0;
|
|
257
|
+
let latest: string | null = null;
|
|
258
|
+
let refusal: string | null = null;
|
|
259
|
+
|
|
260
|
+
for (let attempt = 1; attempt <= attempts; attempt++) {
|
|
261
|
+
const last = attempt === attempts;
|
|
262
|
+
try {
|
|
263
|
+
const state = await registryState(pkg, opts.fetchImpl ?? fetch, opts.base);
|
|
264
|
+
latest = state.latest;
|
|
265
|
+
refusal = postflightRefusal(treeVersion, latest);
|
|
266
|
+
} catch (e) {
|
|
267
|
+
if (last) throw e;
|
|
268
|
+
refusal = `could not read the registry: ${(e as Error).message}`;
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
if (refusal === null) return { latest, attempts: attempt, waitedMs, refusal: null };
|
|
272
|
+
if (last) {
|
|
273
|
+
return {
|
|
274
|
+
latest,
|
|
275
|
+
attempts: attempt,
|
|
276
|
+
waitedMs,
|
|
277
|
+
refusal:
|
|
278
|
+
`${refusal} — read ${attempt} times over ${Math.round(waitedMs / 1000)}s, ` +
|
|
279
|
+
`which is long enough that this is not the registry catching up`,
|
|
280
|
+
};
|
|
281
|
+
}
|
|
282
|
+
await sleep(delayMs);
|
|
283
|
+
waitedMs += delayMs;
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
/* c8 ignore next */
|
|
287
|
+
throw new Error("unreachable: the loop returns on its last attempt");
|
|
288
|
+
}
|
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Rule health pipeline — merges agnix findings with auditor verdicts,
|
|
3
|
+
* generates improvement plans, and rescores after rewrites.
|
|
4
|
+
*
|
|
5
|
+
* Deep module: 3 exports (mergeFindings, generateImprovementPlan, rescoreAfterRewrite),
|
|
6
|
+
* simple interface hiding join logic, factor analysis, and rescore mechanics.
|
|
7
|
+
*
|
|
8
|
+
* AC-2: mergeFindings export
|
|
9
|
+
* AC-3: generateImprovementPlan export
|
|
10
|
+
* AC-4: rescoreAfterRewrite export
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { basename } from "path";
|
|
14
|
+
import type { InstructionFinding } from "./compliance.js";
|
|
15
|
+
import type { AgentAuditResult } from "./agent-audit.js";
|
|
16
|
+
import { COMPLIANCE_FACTORS, type ComplianceFactor } from "./hill-climb.js";
|
|
17
|
+
|
|
18
|
+
// ── Types ───────────────────────────────────────────────
|
|
19
|
+
|
|
20
|
+
export interface RuleHealthEntry {
|
|
21
|
+
ruleId: string;
|
|
22
|
+
file: string;
|
|
23
|
+
line: number;
|
|
24
|
+
agnixSeverity: "HIGH" | "MEDIUM" | "LOW" | null;
|
|
25
|
+
agnixMessage: string | null;
|
|
26
|
+
agnixSuggestion: string | null;
|
|
27
|
+
auditVerdict: "FOLLOWED" | "IGNORED" | null;
|
|
28
|
+
auditEvidence: string | null;
|
|
29
|
+
auditWeight: number | null;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export interface ImprovementRecommendation {
|
|
33
|
+
ruleId: string;
|
|
34
|
+
file: string;
|
|
35
|
+
line: number;
|
|
36
|
+
factors: ComplianceFactor[];
|
|
37
|
+
recommendations: string[];
|
|
38
|
+
priority: "HIGH" | "MEDIUM" | "LOW";
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export interface ImprovementPlan {
|
|
42
|
+
timestamp: string;
|
|
43
|
+
recommendations: ImprovementRecommendation[];
|
|
44
|
+
totalEntries: number;
|
|
45
|
+
actionableCount: number;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export interface FileScoreDelta {
|
|
49
|
+
before: number;
|
|
50
|
+
after: number;
|
|
51
|
+
delta: number;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
export interface RescoreDelta {
|
|
55
|
+
timestamp: string;
|
|
56
|
+
files: Record<string, FileScoreDelta>;
|
|
57
|
+
totalDelta: number;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
// ── AC-2: mergeFindings ─────────────────────────────────
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Join agnix InstructionFinding array with auditor rule verdicts
|
|
64
|
+
* on matching rule ID, producing unified RuleHealthEntry records.
|
|
65
|
+
*
|
|
66
|
+
* Unmatched agnix findings get null audit fields.
|
|
67
|
+
* Unmatched audit rules get null agnix fields.
|
|
68
|
+
*/
|
|
69
|
+
export function mergeFindings(
|
|
70
|
+
agnixFindings: InstructionFinding[],
|
|
71
|
+
auditRules: AgentAuditResult["rules"],
|
|
72
|
+
): RuleHealthEntry[] {
|
|
73
|
+
const entries: RuleHealthEntry[] = [];
|
|
74
|
+
const matchedAuditIds = new Set<string>();
|
|
75
|
+
|
|
76
|
+
// Match agnix findings to audit rules by rule ID
|
|
77
|
+
for (const finding of agnixFindings) {
|
|
78
|
+
const matchingRule = auditRules.find((r) => r.id === finding.rule);
|
|
79
|
+
if (matchingRule) {
|
|
80
|
+
matchedAuditIds.add(matchingRule.id);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
entries.push({
|
|
84
|
+
ruleId: finding.rule,
|
|
85
|
+
file: finding.file,
|
|
86
|
+
line: finding.line,
|
|
87
|
+
agnixSeverity: finding.severity,
|
|
88
|
+
agnixMessage: finding.message,
|
|
89
|
+
agnixSuggestion: finding.suggestion,
|
|
90
|
+
auditVerdict: matchingRule?.verdict ?? null,
|
|
91
|
+
auditEvidence: matchingRule?.evidence ?? null,
|
|
92
|
+
auditWeight: matchingRule?.weight ?? null,
|
|
93
|
+
});
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
// Add unmatched audit rules
|
|
97
|
+
for (const rule of auditRules) {
|
|
98
|
+
if (!matchedAuditIds.has(rule.id)) {
|
|
99
|
+
entries.push({
|
|
100
|
+
ruleId: rule.id,
|
|
101
|
+
file: "",
|
|
102
|
+
line: 0,
|
|
103
|
+
agnixSeverity: null,
|
|
104
|
+
agnixMessage: null,
|
|
105
|
+
agnixSuggestion: null,
|
|
106
|
+
auditVerdict: rule.verdict,
|
|
107
|
+
auditEvidence: rule.evidence,
|
|
108
|
+
auditWeight: rule.weight,
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
return entries;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
// ── AC-3: generateImprovementPlan ───────────────────────
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Read merged findings and produce an improvement plan with per-rule
|
|
120
|
+
* rewrite recommendations using the 7 compliance factors.
|
|
121
|
+
*
|
|
122
|
+
* Only generates recommendations for rules with IGNORED audit verdict
|
|
123
|
+
* or HIGH agnix severity.
|
|
124
|
+
*/
|
|
125
|
+
export function generateImprovementPlan(
|
|
126
|
+
entries: RuleHealthEntry[],
|
|
127
|
+
): ImprovementPlan {
|
|
128
|
+
const recommendations: ImprovementRecommendation[] = [];
|
|
129
|
+
|
|
130
|
+
for (const entry of entries) {
|
|
131
|
+
// Skip rules that are already followed and have no agnix issues
|
|
132
|
+
if (entry.auditVerdict === "FOLLOWED" && entry.agnixSeverity !== "HIGH") {
|
|
133
|
+
continue;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
const factors: ComplianceFactor[] = [];
|
|
137
|
+
const recs: string[] = [];
|
|
138
|
+
|
|
139
|
+
// Position: rule is too far down in the file
|
|
140
|
+
if (entry.line > 30) {
|
|
141
|
+
factors.push("position");
|
|
142
|
+
recs.push(`Move rule ${entry.ruleId} from L${entry.line} to top section`);
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
// Language: if agnix flagged weak language
|
|
146
|
+
if (entry.agnixMessage?.toLowerCase().includes("vague") ||
|
|
147
|
+
entry.agnixMessage?.toLowerCase().includes("weak") ||
|
|
148
|
+
entry.agnixMessage?.toLowerCase().includes("ambiguous")) {
|
|
149
|
+
factors.push("language");
|
|
150
|
+
recs.push(`Strengthen language: ${entry.agnixSuggestion || "add MUST/MANDATORY"}`);
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
// Specificity: missing specific target
|
|
154
|
+
if (entry.agnixMessage?.toLowerCase().includes("specific") ||
|
|
155
|
+
entry.agnixSuggestion?.toLowerCase().includes("specific")) {
|
|
156
|
+
factors.push("specificity");
|
|
157
|
+
recs.push("Make target more specific with exact file paths");
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
// Section: rule not in a strong section
|
|
161
|
+
if (entry.auditVerdict === "IGNORED") {
|
|
162
|
+
factors.push("section");
|
|
163
|
+
recs.push("Move to Context or Always Do section for higher compliance");
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
// Evidence: no verification command associated
|
|
167
|
+
if (entry.auditVerdict === "IGNORED" && entry.auditWeight && entry.auditWeight >= 10) {
|
|
168
|
+
factors.push("evidence");
|
|
169
|
+
recs.push("Add verification command to make compliance mechanically checkable");
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
// If we still have no factors but the rule is IGNORED, add language as default
|
|
173
|
+
if (factors.length === 0 && entry.auditVerdict === "IGNORED") {
|
|
174
|
+
factors.push("language");
|
|
175
|
+
recs.push("Strengthen language to improve compliance");
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
// Only add HIGH agnix entries that are already FOLLOWED
|
|
179
|
+
if (factors.length === 0 && entry.agnixSeverity === "HIGH") {
|
|
180
|
+
factors.push("language");
|
|
181
|
+
recs.push(`Address HIGH severity finding: ${entry.agnixMessage}`);
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
if (factors.length > 0) {
|
|
185
|
+
const priority = entry.agnixSeverity === "HIGH" || entry.auditVerdict === "IGNORED"
|
|
186
|
+
? (entry.auditWeight && entry.auditWeight >= 15 ? "HIGH" : "MEDIUM")
|
|
187
|
+
: "LOW";
|
|
188
|
+
|
|
189
|
+
recommendations.push({
|
|
190
|
+
ruleId: entry.ruleId,
|
|
191
|
+
file: entry.file,
|
|
192
|
+
line: entry.line,
|
|
193
|
+
factors,
|
|
194
|
+
recommendations: recs,
|
|
195
|
+
priority,
|
|
196
|
+
});
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
return {
|
|
201
|
+
timestamp: new Date().toISOString(),
|
|
202
|
+
recommendations,
|
|
203
|
+
totalEntries: entries.length,
|
|
204
|
+
actionableCount: recommendations.length,
|
|
205
|
+
};
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
// ── AC-4: rescoreAfterRewrite ───────────────────────────
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* Re-run agnix on modified files and return a before-after delta object
|
|
212
|
+
* with per-file score changes.
|
|
213
|
+
*
|
|
214
|
+
* Uses simple word-count heuristic when agnix is not available,
|
|
215
|
+
* counting directive keywords (MUST, NEVER, ALWAYS, MANDATORY).
|
|
216
|
+
*/
|
|
217
|
+
export function rescoreAfterRewrite(
|
|
218
|
+
modifiedFiles: string[],
|
|
219
|
+
beforeScores: Record<string, number>,
|
|
220
|
+
): RescoreDelta {
|
|
221
|
+
const files: Record<string, FileScoreDelta> = {};
|
|
222
|
+
let totalDelta = 0;
|
|
223
|
+
|
|
224
|
+
for (const filePath of modifiedFiles) {
|
|
225
|
+
const fileName = basename(filePath);
|
|
226
|
+
const before = beforeScores[fileName] ?? 0;
|
|
227
|
+
|
|
228
|
+
// Try agnix, fall back to heuristic word count
|
|
229
|
+
let after = 0;
|
|
230
|
+
try {
|
|
231
|
+
const result = Bun.spawnSync(["agnix", filePath, "--format", "json"], {
|
|
232
|
+
timeout: 10_000,
|
|
233
|
+
});
|
|
234
|
+
const stdout = result.stdout.toString().trim();
|
|
235
|
+
if (stdout) {
|
|
236
|
+
const parsed = JSON.parse(stdout);
|
|
237
|
+
after = (parsed.diagnostics || []).length;
|
|
238
|
+
}
|
|
239
|
+
} catch {
|
|
240
|
+
// Heuristic fallback: count directive keywords in file
|
|
241
|
+
try {
|
|
242
|
+
const { readFileSync } = require("fs");
|
|
243
|
+
const content = readFileSync(filePath, "utf-8");
|
|
244
|
+
const keywords = ["MUST", "NEVER", "ALWAYS", "MANDATORY", "BEFORE"];
|
|
245
|
+
after = keywords.reduce((count, kw) => {
|
|
246
|
+
const regex = new RegExp(`\\b${kw}\\b`, "gi");
|
|
247
|
+
return count + (content.match(regex) || []).length;
|
|
248
|
+
}, 0);
|
|
249
|
+
} catch {
|
|
250
|
+
after = 0;
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
const delta = after - before;
|
|
255
|
+
files[fileName] = { before, after, delta };
|
|
256
|
+
totalDelta += delta;
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
return {
|
|
260
|
+
timestamp: new Date().toISOString(),
|
|
261
|
+
files,
|
|
262
|
+
totalDelta,
|
|
263
|
+
};
|
|
264
|
+
}
|