@vaultcompass/conductor 0.2.2 → 0.2.3
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/README.md +37 -8
- package/dist/gate-runner.js +16 -5
- package/dist/init.d.ts +18 -2
- package/dist/init.js +241 -13
- package/dist/intent-prepare.d.ts +43 -2
- package/dist/intent-prepare.js +240 -19
- package/dist/normalize.d.ts +31 -3
- package/dist/normalize.js +63 -5
- package/dist/output-sarif.js +58 -0
- package/dist/output-text.js +5 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -220,6 +220,22 @@ that gate, for pointing at a build that is not installed anywhere.
|
|
|
220
220
|
`--adopt`: those hooks were never conductor's, and no flag here turns
|
|
221
221
|
somebody else's file into one this tool may overwrite.
|
|
222
222
|
|
|
223
|
+
Init recognises the hook manager already wired into the repository. husky is
|
|
224
|
+
redirected to the tracked hook it maintains rather than the generated
|
|
225
|
+
dispatcher git runs. lefthook and the pre-commit framework are refused, with
|
|
226
|
+
the stanza to add to their own config file. simple-git-hooks and yorkie are
|
|
227
|
+
refused too, and recognised from the declaration as well as from the hook
|
|
228
|
+
file, because the declaration is there on a fresh clone where the generated
|
|
229
|
+
hook is not yet: the `simple-git-hooks` or `gitHooks` key in package.json, or
|
|
230
|
+
any of the standalone config files simple-git-hooks reads. Their hook text
|
|
231
|
+
lives in package.json, which conductor does not write, so the guidance names
|
|
232
|
+
the entry to add and `--force` does not override the refusal.
|
|
233
|
+
|
|
234
|
+
That refusal applies only where git actually runs `.git/hooks`. Both managers
|
|
235
|
+
write that directory and neither reads `core.hooksPath`, so a repository that
|
|
236
|
+
has pointed git somewhere else has taken their file out of play, and init
|
|
237
|
+
proceeds normally without mentioning them.
|
|
238
|
+
|
|
223
239
|
`conductor run` runs every enabled gate and prints one report.
|
|
224
240
|
|
|
225
241
|
- `--staged` gates the git index against HEAD, which is what the hook does.
|
|
@@ -281,11 +297,24 @@ gate looks like. In Actions this is almost always a shallow checkout, so
|
|
|
281
297
|
outranks everything, and a path here that is not on disk is reported
|
|
282
298
|
rather than replaced: running a different contract than the one somebody
|
|
283
299
|
named is the wrong kindness.
|
|
284
|
-
2. `<repo>/.
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
user" without
|
|
300
|
+
2. `<repo>/.intent-guard/intent-contract.yaml`, when it is **frozen**, and
|
|
301
|
+
`<repo>/.conductor/intent-contract.yaml` after it. The native flow wins
|
|
302
|
+
wherever a team has done it. Frozen is the test rather than present: an
|
|
303
|
+
unfrozen contract is a draft somebody left behind, and running the gate
|
|
304
|
+
against it fails every pull request on "not frozen by user" without
|
|
305
|
+
checking anything.
|
|
306
|
+
|
|
307
|
+
The second path is the directory intent-guard used before 1.3.0, which
|
|
308
|
+
renamed it because `.conductor` had become the name of a different product
|
|
309
|
+
in this family. Both are read, so a repository on either version is
|
|
310
|
+
checked rather than blocked, and a run that used the old one says so: one
|
|
311
|
+
line on the gate's contract line in the text report, and an
|
|
312
|
+
`intent-guard/legacy-state-dir` notification in the SARIF log. If the
|
|
313
|
+
repository holds **both** directories, the gate does not run and says so,
|
|
314
|
+
naming both: that is the state intent-guard itself refuses every command
|
|
315
|
+
in, so the umbrella refuses on exactly the gate's rule rather than a
|
|
316
|
+
softer one. A `.conductor` holding nothing intent-guard wrote belongs to
|
|
317
|
+
something else and is ignored.
|
|
289
318
|
3. The **first** `Spec: <path>` line in the pull request body, read from the
|
|
290
319
|
event payload at `GITHUB_EVENT_PATH`. A path here that is not on disk, or
|
|
291
320
|
one that leaves the repository, falls through to the next rule.
|
|
@@ -319,9 +348,9 @@ and that includes a contributor from a fork.** On the ordinary path, where a
|
|
|
319
348
|
repository has no frozen contract of its own, `Spec: none` means the intent
|
|
320
349
|
gate does not run at all on that pull request, and budget breaches are the
|
|
321
350
|
thing this gate blocks on. The one thing a waiver cannot override is a frozen
|
|
322
|
-
|
|
323
|
-
wants the gate to be non-waivable freezes a native contract
|
|
324
|
-
committed.
|
|
351
|
+
native contract, under either of the two paths above, which is checked first:
|
|
352
|
+
a repository that wants the gate to be non-waivable freezes a native contract
|
|
353
|
+
and keeps it committed.
|
|
325
354
|
|
|
326
355
|
**What blocks is unchanged.** Blocking stays where intent-guard puts it:
|
|
327
356
|
budget breaches block, subject to `enforce`. Drift on its own is reported and
|
package/dist/gate-runner.js
CHANGED
|
@@ -199,7 +199,12 @@ export function runGate(gate, options) {
|
|
|
199
199
|
...progress,
|
|
200
200
|
durationMs: Date.now() - started,
|
|
201
201
|
couldNotRun: { reason: 'unparseable-output', detail },
|
|
202
|
-
|
|
202
|
+
// progress.stderr, because the comment on progress promises exactly
|
|
203
|
+
// this: it is kept current so an unexpected throw still reports which
|
|
204
|
+
// binary ran and what it printed. Leaving it off here made that
|
|
205
|
+
// promise false for the finding, which is the only part of it a
|
|
206
|
+
// published log ever sees.
|
|
207
|
+
findings: [normalizeUnparseableGate(gate.role, gate.product, detail, progress.stderr)],
|
|
203
208
|
run: EMPTY_RUN,
|
|
204
209
|
diagnostics: [],
|
|
205
210
|
};
|
|
@@ -276,7 +281,9 @@ function runGateInner(gate, options, started, progress) {
|
|
|
276
281
|
...withRun,
|
|
277
282
|
exitCode: null,
|
|
278
283
|
couldNotRun: { reason: 'spawn-failed', detail: child.error.message },
|
|
279
|
-
findings: [
|
|
284
|
+
findings: [
|
|
285
|
+
normalizeFailedGate(gate.role, gate.product, child.error.message, withRun.stderr),
|
|
286
|
+
],
|
|
280
287
|
run: EMPTY_RUN,
|
|
281
288
|
diagnostics: [],
|
|
282
289
|
};
|
|
@@ -294,7 +301,11 @@ function runGateInner(gate, options, started, progress) {
|
|
|
294
301
|
...withRun,
|
|
295
302
|
exitCode,
|
|
296
303
|
couldNotRun: { reason: 'gate-error', detail },
|
|
297
|
-
|
|
304
|
+
// The child's own stderr goes with it. The text report prints it from
|
|
305
|
+
// the outcome, but a gate that could not run gets no SARIF run of its
|
|
306
|
+
// own, so this finding is the only place a published log can say what
|
|
307
|
+
// the gate actually complained about.
|
|
308
|
+
findings: [normalizeFailedGate(gate.role, gate.product, detail, withRun.stderr)],
|
|
298
309
|
run: EMPTY_RUN,
|
|
299
310
|
diagnostics: [],
|
|
300
311
|
};
|
|
@@ -314,7 +325,7 @@ function runGateInner(gate, options, started, progress) {
|
|
|
314
325
|
...withRun,
|
|
315
326
|
exitCode,
|
|
316
327
|
couldNotRun: { reason: 'unparseable-output', detail },
|
|
317
|
-
findings: [normalizeUnparseableGate(gate.role, gate.product, detail)],
|
|
328
|
+
findings: [normalizeUnparseableGate(gate.role, gate.product, detail, withRun.stderr)],
|
|
318
329
|
run: EMPTY_RUN,
|
|
319
330
|
diagnostics: [],
|
|
320
331
|
};
|
|
@@ -346,7 +357,7 @@ function runGateInner(gate, options, started, progress) {
|
|
|
346
357
|
...withRun,
|
|
347
358
|
exitCode,
|
|
348
359
|
couldNotRun: { reason: 'unparseable-output', detail },
|
|
349
|
-
findings: [normalizeUnparseableGate(gate.role, gate.product, detail)],
|
|
360
|
+
findings: [normalizeUnparseableGate(gate.role, gate.product, detail, withRun.stderr)],
|
|
350
361
|
run: EMPTY_RUN,
|
|
351
362
|
diagnostics: [],
|
|
352
363
|
};
|
package/dist/init.d.ts
CHANGED
|
@@ -23,8 +23,24 @@ export declare const INTENT_GUARD_HOOK_MARKER = "conductor-managed-pre-commit";
|
|
|
23
23
|
* a flag, and this one detects it: the umbrella's whole job is to be run
|
|
24
24
|
* once in a repository somebody else already wired up.
|
|
25
25
|
*/
|
|
26
|
-
export type HookManager = 'native' | 'husky' | 'lefthook' | 'precommit';
|
|
27
|
-
|
|
26
|
+
export type HookManager = 'native' | 'husky' | 'lefthook' | 'precommit' | 'simple-git-hooks' | 'yorkie';
|
|
27
|
+
/**
|
|
28
|
+
* The two managers whose pre-commit TEXT lives in package.json rather than
|
|
29
|
+
* in a config file of their own or in the hook file.
|
|
30
|
+
*
|
|
31
|
+
* They are kept apart from lefthook and the pre-commit framework because
|
|
32
|
+
* the refusal is different: there is no manager-owned config file to point
|
|
33
|
+
* somebody at, only a key in the file conductor deliberately never writes.
|
|
34
|
+
*/
|
|
35
|
+
export type ManagedHookManager = 'simple-git-hooks' | 'yorkie';
|
|
36
|
+
export type ConflictReason = 'not-a-git-repository' | 'foreign-hook' | 'gate-hook' | 'generated-hook'
|
|
37
|
+
/**
|
|
38
|
+
* A manager whose hook text lives in package.json owns this file:
|
|
39
|
+
* simple-git-hooks or yorkie. Distinct from generated-hook because the
|
|
40
|
+
* remedy is different -- there is no config file of the manager's own to
|
|
41
|
+
* point at, only a key in package.json that conductor will not write.
|
|
42
|
+
*/
|
|
43
|
+
| 'managed-hooks' | 'hooks-path-outside-repository' | 'no-manifest' | 'manifest-unreadable' | 'changed-since-init' | 'write-failed';
|
|
28
44
|
export interface InitConflict {
|
|
29
45
|
path: string;
|
|
30
46
|
reason: ConflictReason;
|
package/dist/init.js
CHANGED
|
@@ -50,9 +50,22 @@
|
|
|
50
50
|
// points init at the repository root, and the second fails exactly
|
|
51
51
|
// after a `git clean -xdf` has removed the gitignored generated
|
|
52
52
|
// directory, which is the state this whole property exists to survive.
|
|
53
|
+
//
|
|
54
|
+
// 6. A MANAGER WHOSE HOOK TEXT LIVES IN package.json IS REFUSED, AND THE
|
|
55
|
+
// DECLARATION IS THE SIGNAL. simple-git-hooks and yorkie generate
|
|
56
|
+
// .git/hooks/pre-commit from a key in package.json and rewrite it on
|
|
57
|
+
// every install, and neither has a tracked file to write instead. What
|
|
58
|
+
// makes them different from lefthook is that the declaration is there
|
|
59
|
+
// BEFORE the manager has ever run: a fresh clone has no generated hook
|
|
60
|
+
// to read, and that is exactly the state somebody runs init in. So the
|
|
61
|
+
// package.json key is checked as well as the file, and either one alone
|
|
62
|
+
// is enough. Found by running this tool against two of the eight public
|
|
63
|
+
// repositories in a dogfood run: both would have taken the umbrella hook
|
|
64
|
+
// and lost it at the next install, with the manifest still recording it
|
|
65
|
+
// as installed. See detectManagedHook and declaredManagedHooks.
|
|
53
66
|
import { createHash } from 'node:crypto';
|
|
54
67
|
import { execFileSync } from 'node:child_process';
|
|
55
|
-
import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, rmdirSync, statSync, writeFileSync, } from 'node:fs';
|
|
68
|
+
import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, rmdirSync, statSync, writeFileSync, } from 'node:fs';
|
|
56
69
|
import path from 'node:path';
|
|
57
70
|
import { DEFAULT_STAGE_FOR_ROLE, GATE_ROLES, POLICY_FILE_NAME, PRODUCT_FOR_ROLE } from './policy.js';
|
|
58
71
|
import { CANDIDATES } from './resolve.js';
|
|
@@ -69,6 +82,21 @@ export const MANIFEST_RELATIVE_PATH = '.guardrails/manifest.json';
|
|
|
69
82
|
*/
|
|
70
83
|
export const DEP_GUARD_HOOK_MARKER = 'dep-guard-managed-hook: v1';
|
|
71
84
|
export const INTENT_GUARD_HOOK_MARKER = 'conductor-managed-pre-commit';
|
|
85
|
+
/**
|
|
86
|
+
* The standalone config files simple-git-hooks reads, exactly as its own
|
|
87
|
+
* README lists them. yorkie has no equivalent: its config is the
|
|
88
|
+
* `gitHooks` key and nothing else.
|
|
89
|
+
*/
|
|
90
|
+
const SIMPLE_GIT_HOOKS_CONFIG_FILES = [
|
|
91
|
+
'.simple-git-hooks.cjs',
|
|
92
|
+
'.simple-git-hooks.js',
|
|
93
|
+
'.simple-git-hooks.mjs',
|
|
94
|
+
'.simple-git-hooks.json',
|
|
95
|
+
'simple-git-hooks.cjs',
|
|
96
|
+
'simple-git-hooks.js',
|
|
97
|
+
'simple-git-hooks.mjs',
|
|
98
|
+
'simple-git-hooks.json',
|
|
99
|
+
];
|
|
72
100
|
/**
|
|
73
101
|
* The `.husky` directory whose generated subdirectory git has been pointed
|
|
74
102
|
* at, or null when this is not that arrangement.
|
|
@@ -168,6 +196,146 @@ function generatedHookGuidance(manager, relPath) {
|
|
|
168
196
|
`${owner}, ${stanza} in ${config}. Note that ${owner} owns the commit's exit code, so the ` +
|
|
169
197
|
"umbrella's 1 (a gate blocked) and 2 (a gate could not run) do not survive it.");
|
|
170
198
|
}
|
|
199
|
+
/**
|
|
200
|
+
* The manager that generated this hook, for the two whose hook text comes
|
|
201
|
+
* out of package.json. Checked against real installs, captured in
|
|
202
|
+
* tests/fixtures/hooks.
|
|
203
|
+
*
|
|
204
|
+
* simple-git-hooks is recognised by `SKIP_SIMPLE_GIT_HOOKS`, the opt-out
|
|
205
|
+
* variable its generated hook tests on its first line. Verified against
|
|
206
|
+
* 2.14.0 and 2.11.1.
|
|
207
|
+
*
|
|
208
|
+
* IT IS NOT IN EVERY VERSION, and that is the whole reason the package.json
|
|
209
|
+
* key below exists rather than being belt and braces. simple-git-hooks 2.8.0
|
|
210
|
+
* writes the shebang and the user's own command and nothing else: there is
|
|
211
|
+
* no string in that file belonging to simple-git-hooks, so no content rule
|
|
212
|
+
* can recognise it, at any price. A repository on that version is
|
|
213
|
+
* unrecognisable from its hook alone and would have had the umbrella hook
|
|
214
|
+
* written into a file the next install rewrites.
|
|
215
|
+
*
|
|
216
|
+
* yorkie is recognised by `yorkie/src/runner.js`, the script its generated
|
|
217
|
+
* hook invokes. Verified against 2.0.0, which writes it relative, and 1.0.2,
|
|
218
|
+
* which writes the same suffix under an absolute path, so the suffix is what
|
|
219
|
+
* both have in common. The `#yorkie ` version stamp on the second line is a
|
|
220
|
+
* second alternative and is present in both captures too; it is second
|
|
221
|
+
* because it is a comment, and a comment is the part of a generated file
|
|
222
|
+
* most likely to be reworded.
|
|
223
|
+
*/
|
|
224
|
+
function detectManagedHook(content) {
|
|
225
|
+
if (content.includes('SKIP_SIMPLE_GIT_HOOKS')) {
|
|
226
|
+
return 'simple-git-hooks';
|
|
227
|
+
}
|
|
228
|
+
if (content.includes('yorkie/src/runner.js') || content.includes('#yorkie ')) {
|
|
229
|
+
return 'yorkie';
|
|
230
|
+
}
|
|
231
|
+
return null;
|
|
232
|
+
}
|
|
233
|
+
function declaredManagedHooks(root) {
|
|
234
|
+
// A standalone config file counts as a declaration on its own. Taken
|
|
235
|
+
// verbatim from simple-git-hooks' own README, which says the config may
|
|
236
|
+
// live in ".simple-git-hooks.cjs, .simple-git-hooks.js,
|
|
237
|
+
// .simple-git-hooks.mjs, .simple-git-hooks.json, or
|
|
238
|
+
// simple-git-hooks.{cjs,js,mjs,json}". It is an EXACT list rather than a
|
|
239
|
+
// prefix or extension test, so a simple-git-hooks.yaml or a
|
|
240
|
+
// simple-git-hooks.md is what it looks like -- somebody's notes -- and not
|
|
241
|
+
// a reason to refuse an install.
|
|
242
|
+
//
|
|
243
|
+
// This is the third signal and the only one that fires for the repository
|
|
244
|
+
// that has all the others against it: a standalone config plus an older
|
|
245
|
+
// simple-git-hooks, whose generated hook carries no marker at all.
|
|
246
|
+
// Checked BEFORE package.json, and the order is the same one
|
|
247
|
+
// simple-git-hooks resolves in: it reads package.json last, so whichever
|
|
248
|
+
// of these exists is the file that actually decides the hook.
|
|
249
|
+
const configFile = SIMPLE_GIT_HOOKS_CONFIG_FILES.find((file) => isFile(path.join(root, file)));
|
|
250
|
+
if (configFile !== undefined) {
|
|
251
|
+
return { manager: 'simple-git-hooks', detectedIn: { kind: 'config-file', file: configFile } };
|
|
252
|
+
}
|
|
253
|
+
const raw = readIfExists(path.join(root, 'package.json'));
|
|
254
|
+
if (raw === undefined) {
|
|
255
|
+
return null;
|
|
256
|
+
}
|
|
257
|
+
let parsed;
|
|
258
|
+
try {
|
|
259
|
+
parsed = JSON.parse(raw);
|
|
260
|
+
}
|
|
261
|
+
catch {
|
|
262
|
+
return null;
|
|
263
|
+
}
|
|
264
|
+
if (typeof parsed !== 'object' || parsed === null) {
|
|
265
|
+
return null;
|
|
266
|
+
}
|
|
267
|
+
const manifest = parsed;
|
|
268
|
+
if (isPlainObject(manifest['simple-git-hooks'])) {
|
|
269
|
+
return { manager: 'simple-git-hooks', detectedIn: { kind: 'package.json' } };
|
|
270
|
+
}
|
|
271
|
+
if (isPlainObject(manifest.gitHooks)) {
|
|
272
|
+
return { manager: 'yorkie', detectedIn: { kind: 'package.json' } };
|
|
273
|
+
}
|
|
274
|
+
return null;
|
|
275
|
+
}
|
|
276
|
+
function isPlainObject(value) {
|
|
277
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
278
|
+
}
|
|
279
|
+
/**
|
|
280
|
+
* What init says when it finds one of those two, and why it says nothing
|
|
281
|
+
* else.
|
|
282
|
+
*
|
|
283
|
+
* The honest answer here is a refusal, not an offer. These managers have no
|
|
284
|
+
* tracked hook file to redirect into and no config file of their own to name:
|
|
285
|
+
* the only place the umbrella's command could go is a key in package.json,
|
|
286
|
+
* and init does not write package.json. That is not squeamishness. Init
|
|
287
|
+
* writes a hook, a policy file and a manifest, and the manifest is what
|
|
288
|
+
* makes --revert honest; an edit merged into somebody's package.json has no
|
|
289
|
+
* revert story that is not a guess about which of their later edits were
|
|
290
|
+
* theirs. So the guidance says exactly what to add and leaves the adding to
|
|
291
|
+
* the person whose file it is.
|
|
292
|
+
*
|
|
293
|
+
* The exit-code sentence differs between the two, and both halves are held
|
|
294
|
+
* against the captured fixtures rather than against anybody's memory:
|
|
295
|
+
* simple-git-hooks runs the entry as the last command of a plain `sh`
|
|
296
|
+
* script, so the umbrella's status is the hook's status, while yorkie wraps
|
|
297
|
+
* its runner in `|| { ...; exit 1; }` and turns every non-zero exit into 1.
|
|
298
|
+
*/
|
|
299
|
+
function managedHooksGuidance(manager, relPath, detectedIn) {
|
|
300
|
+
// WHERE THE ENTRY GOES IS WHERE THE DECLARATION ALREADY IS.
|
|
301
|
+
// simple-git-hooks reads package.json LAST, so while a standalone config
|
|
302
|
+
// file exists an entry added to package.json is precisely the one it
|
|
303
|
+
// ignores. Naming package.json there would send somebody to edit a file
|
|
304
|
+
// that will not be read, and leave them with the umbrella uninstalled and
|
|
305
|
+
// no error to explain it.
|
|
306
|
+
const home = detectedIn.kind === 'config-file' ? detectedIn.file : 'package.json';
|
|
307
|
+
const entry = detectedIn.kind === 'config-file'
|
|
308
|
+
? `the "pre-commit" entry in ${detectedIn.file}`
|
|
309
|
+
: manager === 'simple-git-hooks'
|
|
310
|
+
? 'the "pre-commit" entry under "simple-git-hooks" in package.json'
|
|
311
|
+
: 'the "pre-commit" entry under "gitHooks" in package.json';
|
|
312
|
+
const reinstall = manager === 'simple-git-hooks'
|
|
313
|
+
? 're-run "npx simple-git-hooks"'
|
|
314
|
+
: 're-run the install (yorkie rewrites its hooks on postinstall)';
|
|
315
|
+
const exitCodes = manager === 'simple-git-hooks'
|
|
316
|
+
? `${manager} runs that entry as the last command of the hook it generates, so the ` +
|
|
317
|
+
"umbrella's exit codes reach git unchanged: 1 means a gate blocked, 2 means a gate " +
|
|
318
|
+
'could not run.'
|
|
319
|
+
: `${manager}'s generated hook turns every non-zero exit into 1, so the umbrella's 2 ` +
|
|
320
|
+
'(a gate could not run, and nothing was checked) reaches git as 1 (a gate blocked). ' +
|
|
321
|
+
'Both still stop the commit.';
|
|
322
|
+
const lead = detectedIn.kind === 'hook'
|
|
323
|
+
? `${relPath} was generated by ${manager} from its own declaration, and is rewritten on ` +
|
|
324
|
+
'every install.'
|
|
325
|
+
: `${home} declares ${manager}, which generates ${relPath} from that declaration and ` +
|
|
326
|
+
'rewrites it on every install.';
|
|
327
|
+
return (`${lead} A hook written there is gone after the next install while ` +
|
|
328
|
+
`${MANIFEST_RELATIVE_PATH} still records it as installed, so the repository would report a ` +
|
|
329
|
+
'guardrail it no longer has. Nothing was changed, and --force does not override this: that ' +
|
|
330
|
+
`file was never conductor's to hold. To run the umbrella under ${manager}, set ${entry} ` +
|
|
331
|
+
'to "conductor run --staged --stage commit" yourself, and ' +
|
|
332
|
+
`${reinstall}. If something is already in that entry, put the umbrella LAST, as its own ` +
|
|
333
|
+
'command rather than chained behind && : a chain stops at the first failure, so an ' +
|
|
334
|
+
"umbrella in front of it hides the other command's verdict and one behind an && never " +
|
|
335
|
+
`runs at all once anything ahead of it fails. conductor does not edit ${home}, so it ` +
|
|
336
|
+
'cannot do that for you; a later release may offer to. ' +
|
|
337
|
+
exitCodes);
|
|
338
|
+
}
|
|
171
339
|
function detectGateHook(content) {
|
|
172
340
|
if (content.includes(DEP_GUARD_HOOK_MARKER)) {
|
|
173
341
|
return 'dep-guard';
|
|
@@ -293,11 +461,12 @@ function repoRootOf(cwd) {
|
|
|
293
461
|
function effectiveHooksDir(cwd, root) {
|
|
294
462
|
const gitDir = gitOutput(cwd, ['rev-parse', '--git-dir']);
|
|
295
463
|
const hooksPath = gitOutput(cwd, ['config', '--get', 'core.hooksPath']) ?? '';
|
|
464
|
+
// With no core.hooksPath, hooks live in the git DIRECTORY, which is not
|
|
465
|
+
// the working-tree root: for a linked worktree or a submodule it is
|
|
466
|
+
// somewhere else entirely, so this one resolves against gitDir.
|
|
467
|
+
const defaultDir = path.join(path.resolve(cwd, gitDir ?? '.git'), 'hooks');
|
|
296
468
|
if (hooksPath.length === 0) {
|
|
297
|
-
|
|
298
|
-
// the working-tree root: for a linked worktree or a submodule it is
|
|
299
|
-
// somewhere else entirely, so this one resolves against gitDir.
|
|
300
|
-
return { dir: path.join(path.resolve(cwd, gitDir ?? '.git'), 'hooks'), outside: false };
|
|
469
|
+
return { dir: defaultDir, outside: false, isDefault: true };
|
|
301
470
|
}
|
|
302
471
|
// A RELATIVE core.hooksPath resolves against the WORKING-TREE ROOT.
|
|
303
472
|
// Verified by experiment rather than by reading the documentation that
|
|
@@ -305,7 +474,31 @@ function effectiveHooksDir(cwd, root) {
|
|
|
305
474
|
const dir = path.isAbsolute(hooksPath) ? hooksPath : path.join(root, hooksPath);
|
|
306
475
|
const relative = path.relative(root, dir);
|
|
307
476
|
const outside = relative.startsWith('..') || path.isAbsolute(relative);
|
|
308
|
-
return { dir, outside };
|
|
477
|
+
return { dir, outside, isDefault: samePath(dir, defaultDir) };
|
|
478
|
+
}
|
|
479
|
+
/**
|
|
480
|
+
* Whether two paths name the same directory.
|
|
481
|
+
*
|
|
482
|
+
* Through `realpath`, not string comparison, because the two sides arrive by
|
|
483
|
+
* different routes: the default is built from the working directory the
|
|
484
|
+
* caller passed in, and a configured `core.hooksPath` resolves against the
|
|
485
|
+
* root git reported, which git has already resolved. On macOS the system
|
|
486
|
+
* temporary directory is a symlink, so those two spell the same directory
|
|
487
|
+
* two ways and a string compare answers "different" for a repository git
|
|
488
|
+
* treats as one place. Falls back to the resolved strings when a path does
|
|
489
|
+
* not exist yet, which is the ordinary case for a hooks directory init is
|
|
490
|
+
* about to create.
|
|
491
|
+
*/
|
|
492
|
+
function samePath(left, right) {
|
|
493
|
+
const real = (candidate) => {
|
|
494
|
+
try {
|
|
495
|
+
return realpathSync(candidate);
|
|
496
|
+
}
|
|
497
|
+
catch {
|
|
498
|
+
return path.resolve(candidate);
|
|
499
|
+
}
|
|
500
|
+
};
|
|
501
|
+
return real(left) === real(right);
|
|
309
502
|
}
|
|
310
503
|
function readIfExists(file) {
|
|
311
504
|
try {
|
|
@@ -524,16 +717,51 @@ export function planInit(options) {
|
|
|
524
717
|
// repository is still husky's).
|
|
525
718
|
const huskyDir = huskyDirectoryFor(hooks.dir);
|
|
526
719
|
const husky = huskyDir !== null;
|
|
527
|
-
if (!husky
|
|
528
|
-
const
|
|
529
|
-
if (
|
|
530
|
-
const
|
|
720
|
+
if (!husky) {
|
|
721
|
+
const rel = path.relative(root, executedHookPath).split(path.sep).join('/');
|
|
722
|
+
if (executedHook !== undefined) {
|
|
723
|
+
const generatedBy = detectGeneratedHook(executedHook);
|
|
724
|
+
if (generatedBy !== null) {
|
|
725
|
+
conflicts.push({
|
|
726
|
+
path: rel,
|
|
727
|
+
reason: 'generated-hook',
|
|
728
|
+
guidance: generatedHookGuidance(generatedBy, rel),
|
|
729
|
+
});
|
|
730
|
+
return { ...base, repoRoot: root, hookPath: executedHookPath, hookManager: generatedBy };
|
|
731
|
+
}
|
|
732
|
+
}
|
|
733
|
+
// The installed file first, then the declaration. The file says what is
|
|
734
|
+
// there now; the declaration says what the next install will put there,
|
|
735
|
+
// and on a fresh clone it is the only one of the two that exists. Either
|
|
736
|
+
// alone is enough, and the refusal is the same either way: only the
|
|
737
|
+
// opening sentence of the guidance changes, so a reader is told which of
|
|
738
|
+
// the two was actually seen.
|
|
739
|
+
//
|
|
740
|
+
// This is checked only on the native path, and only where git actually
|
|
741
|
+
// runs .git/hooks. BOTH conditions are about the same fact: these two
|
|
742
|
+
// managers write .git/hooks/pre-commit directly and neither one reads
|
|
743
|
+
// core.hooksPath. Under husky, and under any other configured hooks
|
|
744
|
+
// directory, the file they rewrite is not the file git runs, so the
|
|
745
|
+
// umbrella's hook is in no danger from them and a refusal would name a
|
|
746
|
+
// file the manager never touches while blocking an install that is
|
|
747
|
+
// perfectly safe.
|
|
748
|
+
const fromHook = executedHook === undefined ? null : detectManagedHook(executedHook);
|
|
749
|
+
const declared = fromHook === null
|
|
750
|
+
? declaredManagedHooks(root)
|
|
751
|
+
: { manager: fromHook, detectedIn: { kind: 'hook' } };
|
|
752
|
+
const managedBy = hooks.isDefault ? declared : null;
|
|
753
|
+
if (managedBy !== null) {
|
|
531
754
|
conflicts.push({
|
|
532
755
|
path: rel,
|
|
533
|
-
reason: '
|
|
534
|
-
guidance:
|
|
756
|
+
reason: 'managed-hooks',
|
|
757
|
+
guidance: managedHooksGuidance(managedBy.manager, rel, managedBy.detectedIn),
|
|
535
758
|
});
|
|
536
|
-
return {
|
|
759
|
+
return {
|
|
760
|
+
...base,
|
|
761
|
+
repoRoot: root,
|
|
762
|
+
hookPath: executedHookPath,
|
|
763
|
+
hookManager: managedBy.manager,
|
|
764
|
+
};
|
|
537
765
|
}
|
|
538
766
|
}
|
|
539
767
|
const hookManager = husky ? 'husky' : 'native';
|
package/dist/intent-prepare.d.ts
CHANGED
|
@@ -1,7 +1,40 @@
|
|
|
1
1
|
import type { ResolvedBinary } from './resolve.js';
|
|
2
2
|
/** Prefix of the per-run directory, exported so a test can count leaks. */
|
|
3
3
|
export declare const TEMP_PREFIX = "conductor-intent-";
|
|
4
|
-
|
|
4
|
+
/**
|
|
5
|
+
* Where intent-guard keeps a project's frozen contract, canonical first.
|
|
6
|
+
*
|
|
7
|
+
* intent-guard 1.3.0 renamed its per-project state directory from
|
|
8
|
+
* `.conductor` to `.intent-guard`, because `.conductor` had become the name
|
|
9
|
+
* of a DIFFERENT product in the same family: a repository adopting both
|
|
10
|
+
* showed `.conductor/` and `.guardrails/` side by side with nothing to say
|
|
11
|
+
* which tool owned which. The umbrella has to read both, because the two
|
|
12
|
+
* versions will be installed side by side across repositories for as long as
|
|
13
|
+
* anybody is slow to upgrade, and a gate whose contract the umbrella cannot
|
|
14
|
+
* find is a pull request blocked on nothing.
|
|
15
|
+
*
|
|
16
|
+
* THE ORDER IS THE RULE, and it is the same order intent-guard itself uses:
|
|
17
|
+
* canonical wins outright, and the legacy path is consulted only when the
|
|
18
|
+
* canonical one holds nothing. Reversing it would make a migrated repository
|
|
19
|
+
* keep reading the directory the migration left behind.
|
|
20
|
+
*/
|
|
21
|
+
export declare const STATE_DIR = ".intent-guard";
|
|
22
|
+
/** The pre-1.3.0 directory. Read as a fallback, never written to. */
|
|
23
|
+
export declare const LEGACY_STATE_DIR = ".conductor";
|
|
24
|
+
export declare const NATIVE_CONTRACT_PATH = ".intent-guard/intent-contract.yaml";
|
|
25
|
+
/** The pre-1.3.0 path. Read as a fallback, never written to. */
|
|
26
|
+
export declare const LEGACY_NATIVE_CONTRACT_PATH = ".conductor/intent-contract.yaml";
|
|
27
|
+
/** Both, canonical first, so no caller has to spell the order itself. */
|
|
28
|
+
export declare const NATIVE_CONTRACT_PATHS: readonly [".intent-guard/intent-contract.yaml", ".conductor/intent-contract.yaml"];
|
|
29
|
+
/**
|
|
30
|
+
* Whether a contract source path is the pre-1.3.0 one.
|
|
31
|
+
*
|
|
32
|
+
* A PREDICATE over the path rather than a flag carried beside it. The path is
|
|
33
|
+
* already the fact, and a boolean travelling next to it is a second copy that
|
|
34
|
+
* can disagree with the first -- the failure this repository has written down
|
|
35
|
+
* about recomputing a gate's decision in a renderer, in the same shape.
|
|
36
|
+
*/
|
|
37
|
+
export declare function isLegacyContractPath(contractPath: string): boolean;
|
|
5
38
|
export type ContractSource =
|
|
6
39
|
/** The repository's own frozen contract, used untouched. */
|
|
7
40
|
{
|
|
@@ -30,7 +63,15 @@ export interface IntentPreparation {
|
|
|
30
63
|
cleanup: () => void;
|
|
31
64
|
}
|
|
32
65
|
/** Which link of the chain broke. Carried into the report verbatim. */
|
|
33
|
-
export type PrepareStep = 'spec' | 'base'
|
|
66
|
+
export type PrepareStep = 'spec' | 'base'
|
|
67
|
+
/**
|
|
68
|
+
* The repository holds a frozen contract at BOTH the canonical and the
|
|
69
|
+
* legacy path, so which one the gate is about cannot be answered. Its own
|
|
70
|
+
* step because it happens before anything is spawned and before a spec is
|
|
71
|
+
* even looked for, and because the fix is in the repository rather than in
|
|
72
|
+
* anything conductor did.
|
|
73
|
+
*/
|
|
74
|
+
| 'contract-source' | 'import-spec' | 'write-contract' | 'freeze';
|
|
34
75
|
export type IntentPrepareResult = {
|
|
35
76
|
kind: 'ready';
|
|
36
77
|
preparation: IntentPreparation;
|
package/dist/intent-prepare.js
CHANGED
|
@@ -11,11 +11,12 @@
|
|
|
11
11
|
//
|
|
12
12
|
// Two rules keep that from being a lie:
|
|
13
13
|
//
|
|
14
|
-
// - NOTHING IS EVER WRITTEN UNDER
|
|
15
|
-
//
|
|
16
|
-
//
|
|
17
|
-
//
|
|
18
|
-
// it, and the second failure is
|
|
14
|
+
// - NOTHING IS EVER WRITTEN UNDER THE REPOSITORY'S OWN STATE DIRECTORY,
|
|
15
|
+
// under either of its two names. A contract is a committed artifact with
|
|
16
|
+
// an approver's name on it. A pull-request run that dropped one into the
|
|
17
|
+
// working tree would either be committed by accident or picked up by the
|
|
18
|
+
// next run as though a person had approved it, and the second failure is
|
|
19
|
+
// silent.
|
|
19
20
|
//
|
|
20
21
|
// - THE REPOSITORY'S OWN FROZEN CONTRACT ALWAYS WINS. Where a team has done
|
|
21
22
|
// the native flow, the native flow is what runs; the import is the
|
|
@@ -29,15 +30,54 @@
|
|
|
29
30
|
// distinguishes a shallow checkout from a spec the importer choked on is the
|
|
30
31
|
// sentence in the report.
|
|
31
32
|
import { spawnSync } from 'node:child_process';
|
|
32
|
-
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
|
|
33
|
+
import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
|
|
33
34
|
import os from 'node:os';
|
|
34
35
|
import path from 'node:path';
|
|
35
36
|
import { parse as parseYaml } from 'yaml';
|
|
36
37
|
import { changedPathsSince, currentBranch, resolveBaseRef } from './intent-base.js';
|
|
38
|
+
import { summariseStderr } from './normalize.js';
|
|
37
39
|
import { SPEC_DIR, discoverSpec, prBodyFromEvent } from './intent-spec.js';
|
|
38
40
|
/** Prefix of the per-run directory, exported so a test can count leaks. */
|
|
39
41
|
export const TEMP_PREFIX = 'conductor-intent-';
|
|
40
|
-
|
|
42
|
+
/**
|
|
43
|
+
* Where intent-guard keeps a project's frozen contract, canonical first.
|
|
44
|
+
*
|
|
45
|
+
* intent-guard 1.3.0 renamed its per-project state directory from
|
|
46
|
+
* `.conductor` to `.intent-guard`, because `.conductor` had become the name
|
|
47
|
+
* of a DIFFERENT product in the same family: a repository adopting both
|
|
48
|
+
* showed `.conductor/` and `.guardrails/` side by side with nothing to say
|
|
49
|
+
* which tool owned which. The umbrella has to read both, because the two
|
|
50
|
+
* versions will be installed side by side across repositories for as long as
|
|
51
|
+
* anybody is slow to upgrade, and a gate whose contract the umbrella cannot
|
|
52
|
+
* find is a pull request blocked on nothing.
|
|
53
|
+
*
|
|
54
|
+
* THE ORDER IS THE RULE, and it is the same order intent-guard itself uses:
|
|
55
|
+
* canonical wins outright, and the legacy path is consulted only when the
|
|
56
|
+
* canonical one holds nothing. Reversing it would make a migrated repository
|
|
57
|
+
* keep reading the directory the migration left behind.
|
|
58
|
+
*/
|
|
59
|
+
export const STATE_DIR = '.intent-guard';
|
|
60
|
+
/** The pre-1.3.0 directory. Read as a fallback, never written to. */
|
|
61
|
+
export const LEGACY_STATE_DIR = '.conductor';
|
|
62
|
+
export const NATIVE_CONTRACT_PATH = `${STATE_DIR}/intent-contract.yaml`;
|
|
63
|
+
/** The pre-1.3.0 path. Read as a fallback, never written to. */
|
|
64
|
+
export const LEGACY_NATIVE_CONTRACT_PATH = `${LEGACY_STATE_DIR}/intent-contract.yaml`;
|
|
65
|
+
/** Both, canonical first, so no caller has to spell the order itself. */
|
|
66
|
+
export const NATIVE_CONTRACT_PATHS = [
|
|
67
|
+
NATIVE_CONTRACT_PATH,
|
|
68
|
+
LEGACY_NATIVE_CONTRACT_PATH,
|
|
69
|
+
];
|
|
70
|
+
/**
|
|
71
|
+
* Whether a contract source path is the pre-1.3.0 one.
|
|
72
|
+
*
|
|
73
|
+
* A PREDICATE over the path rather than a flag carried beside it. The path is
|
|
74
|
+
* already the fact, and a boolean travelling next to it is a second copy that
|
|
75
|
+
* can disagree with the first -- the failure this repository has written down
|
|
76
|
+
* about recomputing a gate's decision in a renderer, in the same shape.
|
|
77
|
+
*/
|
|
78
|
+
export function isLegacyContractPath(contractPath) {
|
|
79
|
+
return contractPath === LEGACY_NATIVE_CONTRACT_PATH;
|
|
80
|
+
}
|
|
41
81
|
/**
|
|
42
82
|
* Whether a contract on disk has been approved.
|
|
43
83
|
*
|
|
@@ -52,10 +92,10 @@ export const NATIVE_CONTRACT_PATH = '.conductor/intent-contract.yaml';
|
|
|
52
92
|
* A file that cannot be parsed is treated as not frozen, which sends the run
|
|
53
93
|
* down the import path rather than handing the gate something it will reject.
|
|
54
94
|
*/
|
|
55
|
-
function
|
|
95
|
+
function contractIsFrozenAt(absolutePath) {
|
|
56
96
|
let parsed;
|
|
57
97
|
try {
|
|
58
|
-
parsed = parseYaml(readFileSync(
|
|
98
|
+
parsed = parseYaml(readFileSync(absolutePath, 'utf8'));
|
|
59
99
|
}
|
|
60
100
|
catch {
|
|
61
101
|
return false;
|
|
@@ -63,7 +103,127 @@ function nativeContractIsFrozen(repoRoot) {
|
|
|
63
103
|
if (parsed === null || typeof parsed !== 'object') {
|
|
64
104
|
return false;
|
|
65
105
|
}
|
|
66
|
-
|
|
106
|
+
// BOTH halves, because both halves are the gate's own test
|
|
107
|
+
// (`isContractFrozen`: frozen_by === "user" && approval != null), and its
|
|
108
|
+
// comment says frozen_by alone, hand-set in YAML, is not enough. This
|
|
109
|
+
// function reconstructs that judgment from the file rather than asking the
|
|
110
|
+
// gate, so reconstructing only half of it means calling a contract frozen
|
|
111
|
+
// that the gate will call unfrozen -- which skips the import and then
|
|
112
|
+
// blocks the pull request on "exists but is not frozen by user" without
|
|
113
|
+
// checking anything, the exact failure the surrounding rule exists to
|
|
114
|
+
// prevent. A real freeze on either version writes both, so requiring both
|
|
115
|
+
// excludes no contract either tool produced.
|
|
116
|
+
const contract = parsed;
|
|
117
|
+
return (contract.frozen_by === 'user' && contract.approval !== undefined && contract.approval !== null);
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Every state directory in this repository holding a FROZEN contract,
|
|
121
|
+
* canonical first.
|
|
122
|
+
*
|
|
123
|
+
* Zero is the ordinary case for a repository that has not done the native
|
|
124
|
+
* flow, one is the answer this exists to give, and two cannot reach here:
|
|
125
|
+
* `stateDirsConflict` below has already refused that repository, on a rule
|
|
126
|
+
* wider than this one.
|
|
127
|
+
*
|
|
128
|
+
* FROZEN is the test rather than EXISTS for the reason the single-path
|
|
129
|
+
* version of this already recorded: an unfrozen contract is a draft somebody
|
|
130
|
+
* left behind, and handing the gate one fails every pull request on "not
|
|
131
|
+
* frozen by user" without checking anything.
|
|
132
|
+
*/
|
|
133
|
+
function frozenNativeContracts(repoRoot) {
|
|
134
|
+
return NATIVE_CONTRACT_PATHS.filter((relative) => contractIsFrozenAt(path.join(repoRoot, relative)));
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* The files only intent-guard writes into its state directory.
|
|
138
|
+
*
|
|
139
|
+
* Copied from the gate's own `holdsIntentGuardState`, because the rule below
|
|
140
|
+
* has to be the gate's rule and not an approximation of it. A `.conductor`
|
|
141
|
+
* holding none of these belongs to something else, and neither tool touches
|
|
142
|
+
* it.
|
|
143
|
+
*/
|
|
144
|
+
const STATE_MARKERS = [
|
|
145
|
+
'config.yaml',
|
|
146
|
+
'intent-contract.yaml',
|
|
147
|
+
'index.md',
|
|
148
|
+
'drift-log.jsonl',
|
|
149
|
+
'contracts',
|
|
150
|
+
];
|
|
151
|
+
function isDirectory(candidate) {
|
|
152
|
+
try {
|
|
153
|
+
return statSync(candidate).isDirectory();
|
|
154
|
+
}
|
|
155
|
+
catch {
|
|
156
|
+
return false;
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* A real directory, not a symlink to one.
|
|
161
|
+
*
|
|
162
|
+
* `ln -s .intent-guard .conductor` is the obvious workaround for a script
|
|
163
|
+
* that still names the old path, and following it makes ONE directory look
|
|
164
|
+
* like two: the legacy path would hold state, the canonical path would
|
|
165
|
+
* exist, and the run would fail closed on a conflict that is not one. lstat
|
|
166
|
+
* does not follow the link, so a symlink is simply not a legacy state
|
|
167
|
+
* directory.
|
|
168
|
+
*
|
|
169
|
+
* THE ASYMMETRY WITH `isDirectory` ABOVE IS DELIBERATE AND IS THE GATE'S
|
|
170
|
+
* OWN: the canonical side follows symlinks and the legacy side does not.
|
|
171
|
+
* Making both sides lstat would be tidier and wrong, because a canonical
|
|
172
|
+
* directory reached through a symlink is still a canonical directory that
|
|
173
|
+
* intent-guard will read and write.
|
|
174
|
+
*/
|
|
175
|
+
function isRealDirectory(candidate) {
|
|
176
|
+
try {
|
|
177
|
+
return lstatSync(candidate).isDirectory();
|
|
178
|
+
}
|
|
179
|
+
catch {
|
|
180
|
+
return false;
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
function holdsIntentGuardState(dir) {
|
|
184
|
+
if (!isRealDirectory(dir)) {
|
|
185
|
+
return false;
|
|
186
|
+
}
|
|
187
|
+
return STATE_MARKERS.some((marker) => existsSync(path.join(dir, marker)));
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* Whether this repository is in the state intent-guard 1.3.0 refuses to run
|
|
191
|
+
* ANY command in.
|
|
192
|
+
*
|
|
193
|
+
* THIS MIRRORS THE GATE'S OWN CONFLICT RULE, deliberately and exactly
|
|
194
|
+
* (`inspectStateDir` in the gate's state-dir.ts): the canonical directory
|
|
195
|
+
* merely EXISTING, even empty, beside a legacy directory holding any state
|
|
196
|
+
* marker, frozen or not. Both halves are wider than they look and both
|
|
197
|
+
* matter.
|
|
198
|
+
*
|
|
199
|
+
* An earlier version of this file used a narrower rule -- both directories
|
|
200
|
+
* holding a FROZEN contract -- on the reasoning that a stale unfrozen draft
|
|
201
|
+
* beside a real contract has an obvious right answer and refusing would fail
|
|
202
|
+
* pull requests over a file nobody had looked at in months. That reasoning
|
|
203
|
+
* was about the wrong tool. The gate does not share it: in that exact state
|
|
204
|
+
* `stateDir` throws and every intent-guard command exits 1. So the narrower
|
|
205
|
+
* rule did not save those pull requests, it just moved where they broke --
|
|
206
|
+
* conductor handed the gate a repository the gate refuses to run in, the
|
|
207
|
+
* child exited non-zero with no JSON, and the run surfaced as
|
|
208
|
+
* gate-output-unparseable with a message about the umbrella being out of
|
|
209
|
+
* date. A guess about somebody else's tool is worth what the run that
|
|
210
|
+
* checked it is worth, and this one had not been checked.
|
|
211
|
+
*/
|
|
212
|
+
function stateDirsConflict(repoRoot) {
|
|
213
|
+
return (isDirectory(path.join(repoRoot, STATE_DIR)) &&
|
|
214
|
+
holdsIntentGuardState(path.join(repoRoot, LEGACY_STATE_DIR)));
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* The contract file inside a prepared temporary project, canonical first, or
|
|
218
|
+
* null when neither path holds one.
|
|
219
|
+
*
|
|
220
|
+
* EXISTS rather than FROZEN, unlike the repository-side lookup above, and the
|
|
221
|
+
* difference is deliberate: this asks whether the freeze step left a file
|
|
222
|
+
* where the gate will look for it, and reading `frozen_by` here would be the
|
|
223
|
+
* umbrella double-checking a decision it just asked intent-guard to make.
|
|
224
|
+
*/
|
|
225
|
+
function frozenContractIn(projectDir) {
|
|
226
|
+
return (NATIVE_CONTRACT_PATHS.find((relative) => existsSync(path.join(projectDir, relative))) ?? null);
|
|
67
227
|
}
|
|
68
228
|
/**
|
|
69
229
|
* The command line for one intent-guard subcommand.
|
|
@@ -96,10 +256,24 @@ function run(command, argv, cwd, timeoutMs) {
|
|
|
96
256
|
errorMessage: child.error === undefined ? null : child.error.message,
|
|
97
257
|
};
|
|
98
258
|
}
|
|
99
|
-
/**
|
|
259
|
+
/**
|
|
260
|
+
* Everything the child complained with, trimmed and capped.
|
|
261
|
+
*
|
|
262
|
+
* THIS USED TO BE THE FIRST LINE, and that was a real defect rather than a
|
|
263
|
+
* stylistic choice. The draft is written under the legacy directory name, so
|
|
264
|
+
* intent-guard 1.3.0 prints "reading project state from .conductor/, renamed
|
|
265
|
+
* to .intent-guard/ in 1.3.0" as line one of stderr on EVERY import-spec and
|
|
266
|
+
* EVERY freeze in a prepared project. Taking line one therefore reported the
|
|
267
|
+
* rename notice as the reason the step failed and discarded the sentence
|
|
268
|
+
* saying what was actually wrong, on every failure, on the version this
|
|
269
|
+
* release exists to support.
|
|
270
|
+
*
|
|
271
|
+
* The cap is the same one the gate-failed carry uses, and for the same
|
|
272
|
+
* reason: this string ends up in an uploaded report, and a child that dumps
|
|
273
|
+
* a stack must not grow it without a bound.
|
|
274
|
+
*/
|
|
100
275
|
function complaint(result) {
|
|
101
|
-
|
|
102
|
-
return text.split('\n')[0] ?? '';
|
|
276
|
+
return summariseStderr(result.stderr.trim() === '' ? result.stdout : result.stderr) ?? '';
|
|
103
277
|
}
|
|
104
278
|
/** The short commit the contract is attributed to, or a placeholder. */
|
|
105
279
|
function shortHead(repoRoot) {
|
|
@@ -135,12 +309,32 @@ export function prepareIntent(options) {
|
|
|
135
309
|
'A spec asked for by name is never replaced by a discovered one.',
|
|
136
310
|
};
|
|
137
311
|
}
|
|
312
|
+
// A repository holding both state directories stops the run before
|
|
313
|
+
// anything else is decided, INCLUDING before --spec is honoured. The flag
|
|
314
|
+
// would otherwise take the import path, which runs "import-spec --project ."
|
|
315
|
+
// in this same repository, where intent-guard 1.3.0 fails closed on the
|
|
316
|
+
// same conflict and reports it as an opaque non-zero exit from a
|
|
317
|
+
// subcommand. One sentence naming both directories beats that, and it is
|
|
318
|
+
// the same answer either way.
|
|
319
|
+
if (stateDirsConflict(repoRoot)) {
|
|
320
|
+
return {
|
|
321
|
+
kind: 'failed',
|
|
322
|
+
step: 'contract-source',
|
|
323
|
+
detail: `this repository has both ${STATE_DIR}/ and a ${LEGACY_STATE_DIR}/ holding ` +
|
|
324
|
+
`intent-guard state. ${LEGACY_STATE_DIR}/ is the pre-1.3 name for ${STATE_DIR}/, and ` +
|
|
325
|
+
'intent-guard reads one state directory and never merges two, so it refuses every ' +
|
|
326
|
+
`command here rather than guessing. Move ${LEGACY_STATE_DIR}/ aside, or move what ` +
|
|
327
|
+
`is still needed out of it into ${STATE_DIR}/, and re-run. Nothing was checked by ` +
|
|
328
|
+
'this gate.',
|
|
329
|
+
};
|
|
330
|
+
}
|
|
331
|
+
const nativeContract = frozenNativeContracts(repoRoot)[0] ?? null;
|
|
138
332
|
let source;
|
|
139
333
|
if (discovery.kind === 'flag') {
|
|
140
334
|
source = { kind: 'imported', spec: discovery.spec, plan: discovery.plan };
|
|
141
335
|
}
|
|
142
|
-
else if (
|
|
143
|
-
source = { kind: 'native', path:
|
|
336
|
+
else if (nativeContract !== null) {
|
|
337
|
+
source = { kind: 'native', path: nativeContract };
|
|
144
338
|
}
|
|
145
339
|
else if (discovery.kind === 'waived') {
|
|
146
340
|
// BELOW the native check, and the order is the whole meaning of the
|
|
@@ -152,7 +346,8 @@ export function prepareIntent(options) {
|
|
|
152
346
|
kind: 'skip',
|
|
153
347
|
reason: 'contract-waived',
|
|
154
348
|
detail: 'The pull request body waived the spec with a "Spec: none" line, so there was ' +
|
|
155
|
-
`nothing to import and no frozen ${
|
|
349
|
+
`nothing to import and no frozen ${NATIVE_CONTRACT_PATHS.join(' or ')} to fall ` +
|
|
350
|
+
'back on.',
|
|
156
351
|
};
|
|
157
352
|
}
|
|
158
353
|
else if (discovery.kind === 'none') {
|
|
@@ -165,7 +360,7 @@ export function prepareIntent(options) {
|
|
|
165
360
|
return {
|
|
166
361
|
kind: 'skip',
|
|
167
362
|
reason: 'no-contract',
|
|
168
|
-
detail: `No frozen ${
|
|
363
|
+
detail: `No frozen ${NATIVE_CONTRACT_PATHS.join(' or ')} and no spec under ${SPEC_DIR} matching ` +
|
|
169
364
|
`${branch === null ? 'this branch' : `branch "${branch}"`}. ` +
|
|
170
365
|
'Name one with a "Spec: <path>" line in the pull request body, or pass --spec.',
|
|
171
366
|
};
|
|
@@ -265,8 +460,17 @@ export function prepareIntent(options) {
|
|
|
265
460
|
rmSync(projectDir, { recursive: true, force: true });
|
|
266
461
|
};
|
|
267
462
|
try {
|
|
268
|
-
|
|
269
|
-
|
|
463
|
+
// The DRAFT goes to the legacy path, which is the one both versions can
|
|
464
|
+
// find. A 1.2.x intent-guard reads only that directory; a 1.3.0 one reads
|
|
465
|
+
// it as the legacy fallback and renames it to the canonical name on its
|
|
466
|
+
// first write, which the freeze below is. Writing the canonical name
|
|
467
|
+
// instead would work on 1.3.0 and leave 1.2.x freezing an empty project.
|
|
468
|
+
// This is a temporary directory the umbrella made two lines ago, so
|
|
469
|
+
// writing the old name here is not a migration anybody has to live with.
|
|
470
|
+
mkdirSync(path.join(projectDir, path.dirname(LEGACY_NATIVE_CONTRACT_PATH)), {
|
|
471
|
+
recursive: true,
|
|
472
|
+
});
|
|
473
|
+
writeFileSync(path.join(projectDir, LEGACY_NATIVE_CONTRACT_PATH), contractYaml);
|
|
270
474
|
}
|
|
271
475
|
catch (err) {
|
|
272
476
|
cleanup();
|
|
@@ -303,6 +507,23 @@ export function prepareIntent(options) {
|
|
|
303
507
|
`freeze exited ${freezeResult.status ?? -1}: ${complaint(freezeResult)}`,
|
|
304
508
|
};
|
|
305
509
|
}
|
|
510
|
+
// Exit 0 is not proof there is a contract to hand the gate. freeze writes
|
|
511
|
+
// through intent-guard's own state directory, so a 1.3.0 build has just
|
|
512
|
+
// renamed the directory this function created and a 1.2.x one has not, and
|
|
513
|
+
// the whole point of this release is that the umbrella cannot assume which.
|
|
514
|
+
// Looking for the file, canonical first, turns "the gate found no contract
|
|
515
|
+
// in a directory conductor prepared" into a named preparation failure here
|
|
516
|
+
// rather than a confusing verdict from the gate three steps later.
|
|
517
|
+
if (frozenContractIn(projectDir) === null) {
|
|
518
|
+
cleanup();
|
|
519
|
+
return {
|
|
520
|
+
kind: 'failed',
|
|
521
|
+
step: 'freeze',
|
|
522
|
+
detail: 'freeze reported success but left no contract in the prepared project: neither ' +
|
|
523
|
+
`${NATIVE_CONTRACT_PATHS.join(' nor ')} is there. That is a version of ` +
|
|
524
|
+
'intent-guard writing its state somewhere this umbrella does not know about.',
|
|
525
|
+
};
|
|
526
|
+
}
|
|
306
527
|
return {
|
|
307
528
|
kind: 'ready',
|
|
308
529
|
preparation: { ...common, contractSource: source, projectDir, cleanup },
|
package/dist/normalize.d.ts
CHANGED
|
@@ -53,6 +53,34 @@ export declare function normalizeMisconfiguredGate(role: GateRole, product: Prod
|
|
|
53
53
|
* filesystem path into a report that gets uploaded, and it would tell the
|
|
54
54
|
* user nothing they can act on.
|
|
55
55
|
*/
|
|
56
|
-
export declare function normalizeUnparseableGate(role: GateRole, product: Product, detail: string): Finding;
|
|
57
|
-
/**
|
|
58
|
-
|
|
56
|
+
export declare function normalizeUnparseableGate(role: GateRole, product: Product, detail: string, stderr?: string | null): Finding;
|
|
57
|
+
/**
|
|
58
|
+
* The gate's own last words, trimmed and capped, or null when it said
|
|
59
|
+
* nothing.
|
|
60
|
+
*
|
|
61
|
+
* The truncation is ANNOUNCED rather than silent, and says how much there
|
|
62
|
+
* was. A message that stops mid-sentence with no note reads as the gate's
|
|
63
|
+
* final word, which sends a reader looking for meaning in a cut.
|
|
64
|
+
*/
|
|
65
|
+
export declare function summariseStderr(stderr: string | null | undefined): string | null;
|
|
66
|
+
/**
|
|
67
|
+
* The finding raised when a gate could not be run or did not complete.
|
|
68
|
+
*
|
|
69
|
+
* `stderr` is what the child printed, and it is carried here because this
|
|
70
|
+
* finding is the ONLY place a published log can say why. A gate that could
|
|
71
|
+
* not run gets no SARIF run of its own, so without this the log held
|
|
72
|
+
* "the gate exited 2, which it uses for could not run" and nothing else,
|
|
73
|
+
* while the text report beside it printed the gate's own line naming the
|
|
74
|
+
* file and the reason. Found by running the umbrella against a repository
|
|
75
|
+
* with an unparseable lockfile.
|
|
76
|
+
*
|
|
77
|
+
* It is APPENDED to the umbrella's own sentence rather than replacing it.
|
|
78
|
+
* The generic half says which exit code was seen and what that gate uses it
|
|
79
|
+
* for, which the child's line does not, and a gate that exits 2 silently is
|
|
80
|
+
* a real case that has to keep reading sensibly.
|
|
81
|
+
*
|
|
82
|
+
* The fingerprint is unaffected: it is computed over the rule, the role and
|
|
83
|
+
* the product and never over the message, so a gate that reworded its error
|
|
84
|
+
* is the same alert rather than a new one every run.
|
|
85
|
+
*/
|
|
86
|
+
export declare function normalizeFailedGate(role: GateRole, product: Product, detail: string, stderr?: string | null): Finding;
|
package/dist/normalize.js
CHANGED
|
@@ -571,12 +571,70 @@ export function normalizeMisconfiguredGate(role, product, command, detail) {
|
|
|
571
571
|
* filesystem path into a report that gets uploaded, and it would tell the
|
|
572
572
|
* user nothing they can act on.
|
|
573
573
|
*/
|
|
574
|
-
export function normalizeUnparseableGate(role, product, detail) {
|
|
574
|
+
export function normalizeUnparseableGate(role, product, detail, stderr) {
|
|
575
|
+
// Carried for the same reason gate-failed carries it, and the case that
|
|
576
|
+
// found the gap is a good one: a gate refusing to run at all exits 1 with
|
|
577
|
+
// no JSON and says why on stderr, and this result is the only place a
|
|
578
|
+
// published log can repeat it.
|
|
579
|
+
const said = summariseStderr(stderr);
|
|
575
580
|
return gateProblem('conductor/gate-output-unparseable', role, product, `The "${role}" gate ran but the umbrella could not read its output: ${detail} ` +
|
|
576
581
|
'This is the umbrella being out of date with that gate, not a problem in your code. ' +
|
|
577
|
-
'Nothing was verified by this gate.'
|
|
582
|
+
'Nothing was verified by this gate.' +
|
|
583
|
+
(said === null ? '' : ` The gate wrote to stderr: ${said}`), { detail, stderr: said });
|
|
578
584
|
}
|
|
579
|
-
/**
|
|
580
|
-
|
|
581
|
-
|
|
585
|
+
/**
|
|
586
|
+
* How much of a failing gate's stderr goes into a published report.
|
|
587
|
+
*
|
|
588
|
+
* A gate that could not run may print a stack, a whole rejected config, or a
|
|
589
|
+
* file it could not parse, and this finding is uploaded to code scanning.
|
|
590
|
+
* The cap is generous enough for the shape that matters -- a line or two
|
|
591
|
+
* naming the file and the reason -- and small enough that nothing here can
|
|
592
|
+
* grow an alert without a bound.
|
|
593
|
+
*/
|
|
594
|
+
const STDERR_CAP = 2000;
|
|
595
|
+
/**
|
|
596
|
+
* The gate's own last words, trimmed and capped, or null when it said
|
|
597
|
+
* nothing.
|
|
598
|
+
*
|
|
599
|
+
* The truncation is ANNOUNCED rather than silent, and says how much there
|
|
600
|
+
* was. A message that stops mid-sentence with no note reads as the gate's
|
|
601
|
+
* final word, which sends a reader looking for meaning in a cut.
|
|
602
|
+
*/
|
|
603
|
+
export function summariseStderr(stderr) {
|
|
604
|
+
if (stderr === null || stderr === undefined) {
|
|
605
|
+
return null;
|
|
606
|
+
}
|
|
607
|
+
const trimmed = stderr.trim();
|
|
608
|
+
if (trimmed.length === 0) {
|
|
609
|
+
return null;
|
|
610
|
+
}
|
|
611
|
+
if (trimmed.length <= STDERR_CAP) {
|
|
612
|
+
return trimmed;
|
|
613
|
+
}
|
|
614
|
+
return `${trimmed.slice(0, STDERR_CAP)} [truncated, ${trimmed.length} characters in total]`;
|
|
615
|
+
}
|
|
616
|
+
/**
|
|
617
|
+
* The finding raised when a gate could not be run or did not complete.
|
|
618
|
+
*
|
|
619
|
+
* `stderr` is what the child printed, and it is carried here because this
|
|
620
|
+
* finding is the ONLY place a published log can say why. A gate that could
|
|
621
|
+
* not run gets no SARIF run of its own, so without this the log held
|
|
622
|
+
* "the gate exited 2, which it uses for could not run" and nothing else,
|
|
623
|
+
* while the text report beside it printed the gate's own line naming the
|
|
624
|
+
* file and the reason. Found by running the umbrella against a repository
|
|
625
|
+
* with an unparseable lockfile.
|
|
626
|
+
*
|
|
627
|
+
* It is APPENDED to the umbrella's own sentence rather than replacing it.
|
|
628
|
+
* The generic half says which exit code was seen and what that gate uses it
|
|
629
|
+
* for, which the child's line does not, and a gate that exits 2 silently is
|
|
630
|
+
* a real case that has to keep reading sensibly.
|
|
631
|
+
*
|
|
632
|
+
* The fingerprint is unaffected: it is computed over the rule, the role and
|
|
633
|
+
* the product and never over the message, so a gate that reworded its error
|
|
634
|
+
* is the same alert rather than a new one every run.
|
|
635
|
+
*/
|
|
636
|
+
export function normalizeFailedGate(role, product, detail, stderr) {
|
|
637
|
+
const said = summariseStderr(stderr);
|
|
638
|
+
return gateProblem('conductor/gate-failed', role, product, `The "${role}" gate did not complete: ${detail} Nothing was verified by this gate.` +
|
|
639
|
+
(said === null ? '' : ` The gate wrote to stderr: ${said}`), { detail, stderr: said });
|
|
582
640
|
}
|
package/dist/output-sarif.js
CHANGED
|
@@ -21,6 +21,20 @@
|
|
|
21
21
|
// umbrella, which is the only honest owner of a statement about a tool
|
|
22
22
|
// that is not installed.
|
|
23
23
|
//
|
|
24
|
+
// The rule is written for a gate that never ran, and it currently also
|
|
25
|
+
// covers a gate that RAN AND FAILED, which is a different thing: the
|
|
26
|
+
// SARIF-native shape for that one is its own run carrying
|
|
27
|
+
// invocations[0].executionSuccessful: false. That is deliberately not
|
|
28
|
+
// done here yet, because it changes the run list of every log with a
|
|
29
|
+
// failing gate in it and this release is a fix rather than a format
|
|
30
|
+
// change. The consequence is that conductor/gate-failed in the
|
|
31
|
+
// umbrella's run is the ONLY place such a log can say anything at all
|
|
32
|
+
// about the failure, which is why that finding carries the child's own
|
|
33
|
+
// stderr (normalizeFailedGate in normalize.ts). A dogfood run found the
|
|
34
|
+
// gap the other way round: the text report printed dep-guard naming an
|
|
35
|
+
// unparseable lockfile and the log beside it said only that the gate had
|
|
36
|
+
// exited 2.
|
|
37
|
+
//
|
|
24
38
|
// - A STATEMENT ABOUT COVERAGE OR CONFIGURATION IS A NOTIFICATION, NOT A
|
|
25
39
|
// FINDING. A gate deferred to a later stage, a gate the policy told not
|
|
26
40
|
// to decide anything, and a branch with no contract to check against are
|
|
@@ -84,6 +98,7 @@
|
|
|
84
98
|
// product, which puts an end column in its own SARIF; see the note in
|
|
85
99
|
// normalize.ts, which is where the omission would stop mattering if the
|
|
86
100
|
// field were ever carried.
|
|
101
|
+
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
87
102
|
const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
|
|
88
103
|
export const UMBRELLA_DRIVER_NAME = 'conductor';
|
|
89
104
|
/**
|
|
@@ -372,6 +387,48 @@ function deferredNotifications(result) {
|
|
|
372
387
|
details: { role: gate.role, product: gate.product, stage: gate.stage },
|
|
373
388
|
}));
|
|
374
389
|
}
|
|
390
|
+
/**
|
|
391
|
+
* The intent gate reading its contract from the pre-1.3 state directory.
|
|
392
|
+
*
|
|
393
|
+
* intent-guard 1.3.0 renamed `.conductor` to `.intent-guard`, and the
|
|
394
|
+
* umbrella reads both so a repository on either version is checked rather
|
|
395
|
+
* than blocked. That fallback is silent otherwise, and a silent fallback is
|
|
396
|
+
* how a repository ends up on the old layout for a year: the log should say
|
|
397
|
+
* which directory the verdict was actually about.
|
|
398
|
+
*
|
|
399
|
+
* A NOTIFICATION by the discriminator below, and it is worth saying why,
|
|
400
|
+
* because it is the closest call of the five. Nothing went wrong. The gate
|
|
401
|
+
* ran, the contract was read, the verdict is exactly what it would have been
|
|
402
|
+
* after the migration, and the run is complete. What this says is which of
|
|
403
|
+
* two layouts the run covered, it stays true on every run until somebody
|
|
404
|
+
* upgrades the gate, and as a result it would be a fingerprint-less alert
|
|
405
|
+
* reappearing on every pull request for as long as that takes -- the precise
|
|
406
|
+
* shape of permanent alert the notification rule exists to keep out.
|
|
407
|
+
*/
|
|
408
|
+
function legacyStateDirNotifications(result) {
|
|
409
|
+
return result.gates.flatMap((gate) => {
|
|
410
|
+
const source = gate.intent?.contractSource;
|
|
411
|
+
if (source === undefined || source.kind !== 'native' || !isLegacyContractPath(source.path)) {
|
|
412
|
+
return [];
|
|
413
|
+
}
|
|
414
|
+
return [
|
|
415
|
+
{
|
|
416
|
+
id: 'intent-guard/legacy-state-dir',
|
|
417
|
+
message: `The ${gate.role} gate (${gate.product}) read its frozen contract from ` +
|
|
418
|
+
`${source.path}, the state directory intent-guard used before 1.3.0. This run's ` +
|
|
419
|
+
`verdict is unaffected. 1.3.0 renamed that directory, reads the old one while it ` +
|
|
420
|
+
`is the only one there, and migrates it on its first write, after which the ` +
|
|
421
|
+
`contract is at ${NATIVE_CONTRACT_PATH}.`,
|
|
422
|
+
details: {
|
|
423
|
+
role: gate.role,
|
|
424
|
+
product: gate.product,
|
|
425
|
+
contractPath: source.path,
|
|
426
|
+
canonicalPath: NATIVE_CONTRACT_PATH,
|
|
427
|
+
},
|
|
428
|
+
},
|
|
429
|
+
];
|
|
430
|
+
});
|
|
431
|
+
}
|
|
375
432
|
/**
|
|
376
433
|
* The gates the --gate flag left out, as notifications.
|
|
377
434
|
*
|
|
@@ -551,6 +608,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
551
608
|
...excludedNotifications(result),
|
|
552
609
|
...skippedNotifications(result),
|
|
553
610
|
...unenforcedNotifications(result),
|
|
611
|
+
...legacyStateDirNotifications(result),
|
|
554
612
|
];
|
|
555
613
|
// Notifications earn the run on their own. Before this, the umbrella run
|
|
556
614
|
// existed only when it had findings and a deferred gate was one; without
|
package/dist/output-text.js
CHANGED
|
@@ -23,6 +23,7 @@
|
|
|
23
23
|
// everywhere is worth more here than a nicer-looking terminal.
|
|
24
24
|
import { compareFindings } from './envelope.js';
|
|
25
25
|
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN } from './exit-codes.js';
|
|
26
|
+
import { isLegacyContractPath } from './intent-prepare.js';
|
|
26
27
|
function subjectLabel(finding) {
|
|
27
28
|
const subject = finding.subject;
|
|
28
29
|
switch (subject.kind) {
|
|
@@ -96,7 +97,10 @@ function contractLine(gate) {
|
|
|
96
97
|
}
|
|
97
98
|
const source = gate.intent.contractSource;
|
|
98
99
|
const where = source.kind === 'native'
|
|
99
|
-
?
|
|
100
|
+
? // The path already names the directory, and the aside says what a
|
|
101
|
+
// reader who has not followed intent-guard's releases cannot get from
|
|
102
|
+
// the path alone: that this is the old name and a newer gate moves it.
|
|
103
|
+
`the repository's own frozen ${source.path}${isLegacyContractPath(source.path) ? ' (pre-1.3 directory, still read)' : ''}`
|
|
100
104
|
: source.kind === 'imported'
|
|
101
105
|
? `spec ${source.spec}${source.plan === null ? '' : ` plus plan ${source.plan}`}`
|
|
102
106
|
: 'none';
|