@vaultcompass/conductor 0.5.0 → 0.6.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/README.md +212 -23
- package/dist/cli.js +169 -40
- package/dist/gate-runner.js +12 -2
- package/dist/normalize.d.ts +13 -2
- package/dist/normalize.js +137 -8
- package/dist/output-sarif.js +58 -0
- package/dist/output-text.js +59 -20
- package/dist/products.d.ts +16 -0
- package/dist/products.js +9 -0
- package/dist/run.d.ts +40 -0
- package/dist/run.js +39 -1
- package/dist/trust-base.d.ts +68 -0
- package/dist/trust-base.js +152 -0
- package/package.json +4 -3
package/dist/cli.js
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
// decisions be tested without a subprocess.
|
|
8
8
|
import { Command, CommanderError } from 'commander';
|
|
9
9
|
import { execFileSync } from 'node:child_process';
|
|
10
|
-
import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
|
|
10
|
+
import { readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
|
|
11
11
|
import path from 'node:path';
|
|
12
12
|
import { fileURLToPath } from 'node:url';
|
|
13
13
|
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
|
|
@@ -16,7 +16,7 @@ import { renderSarif } from './output-sarif.js';
|
|
|
16
16
|
import { jobLogSummary, renderText } from './output-text.js';
|
|
17
17
|
import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
|
|
18
18
|
import { refusedTrustBase, runAll } from './run.js';
|
|
19
|
-
import { policyDiffers, readPolicyAtRef, refuseTrustBaseRef } from './trust-base.js';
|
|
19
|
+
import { headTreeEqualsBase, policyDiffers, readPolicyAtRef, refuseTrustBaseForPullRequest, refuseTrustBaseRef, } from './trust-base.js';
|
|
20
20
|
const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
|
|
21
21
|
const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
|
|
22
22
|
/**
|
|
@@ -39,6 +39,30 @@ const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
|
|
|
39
39
|
* one line on stderr with no stack and the could-not-run exit code, so
|
|
40
40
|
* nothing here has to know about either.
|
|
41
41
|
*/
|
|
42
|
+
/**
|
|
43
|
+
* True when `cwd` is itself a `.git` directory (or another directory git
|
|
44
|
+
* manages as one, such as a worktree's own git dir), rather than a working
|
|
45
|
+
* tree with no repository at all.
|
|
46
|
+
*
|
|
47
|
+
* Only consulted once `--show-toplevel` has already failed, so the extra
|
|
48
|
+
* spawn is on an error path already about to fail the whole command, never
|
|
49
|
+
* on the path every ordinary run takes. Both failure shapes exit non-zero,
|
|
50
|
+
* so this is what tells "point conductor at a .git directory" apart from
|
|
51
|
+
* "point conductor at a plain, ungoverned directory" without guessing from
|
|
52
|
+
* the path's spelling.
|
|
53
|
+
*/
|
|
54
|
+
function isGitDirectory(cwd) {
|
|
55
|
+
try {
|
|
56
|
+
return (execFileSync('git', ['rev-parse', '--is-inside-git-dir'], {
|
|
57
|
+
cwd,
|
|
58
|
+
encoding: 'utf8',
|
|
59
|
+
stdio: ['ignore', 'pipe', 'ignore'],
|
|
60
|
+
}).trim() === 'true');
|
|
61
|
+
}
|
|
62
|
+
catch {
|
|
63
|
+
return false;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
42
66
|
function repoRoot(cwd) {
|
|
43
67
|
try {
|
|
44
68
|
return execFileSync('git', ['rev-parse', '--show-toplevel'], {
|
|
@@ -56,6 +80,10 @@ function repoRoot(cwd) {
|
|
|
56
80
|
// git ran and refused. The directory is named because it is the one
|
|
57
81
|
// thing the reader has to check, and it is the directory they typed
|
|
58
82
|
// the command in rather than anything internal to this tool.
|
|
83
|
+
if (isGitDirectory(cwd)) {
|
|
84
|
+
throw new Error(`${cwd} is a git directory, not a working tree. Point conductor at the repository's ` +
|
|
85
|
+
'working tree instead of at its .git directory.');
|
|
86
|
+
}
|
|
59
87
|
throw new Error(`not a git repository: ${cwd}. conductor anchors every gate at the working-tree ` +
|
|
60
88
|
'root, so run it inside a checkout.');
|
|
61
89
|
}
|
|
@@ -65,6 +93,54 @@ function repoRoot(cwd) {
|
|
|
65
93
|
throw new Error(`git could not be run to find the repository root: ${err.message}`);
|
|
66
94
|
}
|
|
67
95
|
}
|
|
96
|
+
/**
|
|
97
|
+
* The repository root for one command, from --project when it was given and
|
|
98
|
+
* from the working directory otherwise (issue #55).
|
|
99
|
+
*
|
|
100
|
+
* --project changes WHERE the repository is, never WHAT is trusted: once
|
|
101
|
+
* resolved, the root it names goes through the exact same discovery as the
|
|
102
|
+
* working directory always has, `repoRoot`'s own `git rev-parse
|
|
103
|
+
* --show-toplevel`, so a subdirectory of a repository resolves to that
|
|
104
|
+
* repository's top level exactly as a bare `conductor init` or `conductor
|
|
105
|
+
* run` from that subdirectory already does. Nothing downstream of this
|
|
106
|
+
* function -- the trust-base checks, the node_modules/.bin skip on a
|
|
107
|
+
* pull-request run, the program-vetting rules -- reads the working directory
|
|
108
|
+
* again; every one of them takes this root explicitly.
|
|
109
|
+
*
|
|
110
|
+
* A relative value resolves against the working directory, never against
|
|
111
|
+
* anything already discovered, so this has to run before any git call. A
|
|
112
|
+
* path that does not exist, is not a directory, or is not inside a git
|
|
113
|
+
* repository is a usage error naming the path, never a silent fall back to
|
|
114
|
+
* the working directory: guessing which repository a scripted caller meant
|
|
115
|
+
* is how a CI job ends up gating the wrong tree while reporting a clean run
|
|
116
|
+
* of nothing.
|
|
117
|
+
*/
|
|
118
|
+
function resolveProjectRoot(cwd, project) {
|
|
119
|
+
if (project === undefined) {
|
|
120
|
+
return repoRoot(cwd);
|
|
121
|
+
}
|
|
122
|
+
const resolved = path.resolve(cwd, project);
|
|
123
|
+
let stat;
|
|
124
|
+
try {
|
|
125
|
+
stat = statSync(resolved);
|
|
126
|
+
}
|
|
127
|
+
catch {
|
|
128
|
+
throw new Error(`--project ${project}: no such directory (resolved to ${resolved}).`);
|
|
129
|
+
}
|
|
130
|
+
if (!stat.isDirectory()) {
|
|
131
|
+
throw new Error(`--project ${project}: not a directory (resolved to ${resolved}).`);
|
|
132
|
+
}
|
|
133
|
+
// repoRoot names `resolved` in its own "not a git repository" sentence,
|
|
134
|
+
// which is what makes that refusal name the path here too, without a
|
|
135
|
+
// second, separately-worded check that could drift from the one bare `cwd`
|
|
136
|
+
// already goes through.
|
|
137
|
+
return repoRoot(resolved);
|
|
138
|
+
}
|
|
139
|
+
const PROJECT_OPTION_HELP = 'run against this directory instead of the current one, resolved to its repository root ' +
|
|
140
|
+
'the same way the current directory already is: a subdirectory resolves to the top of that ' +
|
|
141
|
+
'repository. Relative values resolve against the current directory. A path that does not ' +
|
|
142
|
+
'exist, is not a directory, or is not inside a git repository is a usage error (exit 2) ' +
|
|
143
|
+
'naming the path, never a silent fall back to the current directory.';
|
|
68
144
|
/**
|
|
69
145
|
* The process exit code for a run, with --advisory applied.
|
|
70
146
|
*
|
|
@@ -127,11 +203,22 @@ function inventoryFromHead(root, overrides) {
|
|
|
127
203
|
return { version: 1, gates: {}, report: { format: 'text' } };
|
|
128
204
|
}
|
|
129
205
|
}
|
|
130
|
-
function policyForRun(root, trustBase, overrides) {
|
|
206
|
+
function policyForRun(root, trustBase, overrides, githubBaseRef) {
|
|
131
207
|
if (trustBase === undefined) {
|
|
132
208
|
return { kind: 'policy', policy: applyCliOverrides(loadPolicy(root), overrides) };
|
|
133
209
|
}
|
|
134
|
-
|
|
210
|
+
// DEFENCE IN DEPTH, ISSUE #58. action.yml's validate step already refuses
|
|
211
|
+
// an explicit trust-base input outright on a pull_request event; this is
|
|
212
|
+
// the same rule for anyone invoking the CLI directly in CI, bypassing that
|
|
213
|
+
// step. Checked BEFORE refuseTrustBaseRef and deliberately narrower than
|
|
214
|
+
// it: it says nothing about HEAD or about tree equality, only about
|
|
215
|
+
// whether the given ref agrees with origin/<GITHUB_BASE_REF>, which is
|
|
216
|
+
// exactly what the composite action itself always passes. So on an
|
|
217
|
+
// ordinary pull-request run this returns null immediately and
|
|
218
|
+
// refuseTrustBaseRef runs its own checks unchanged, the equal-tree
|
|
219
|
+
// first-parent exception (issue #69/#73) included.
|
|
220
|
+
const pullRequestRefusal = refuseTrustBaseForPullRequest(root, trustBase, githubBaseRef);
|
|
221
|
+
const refusal = pullRequestRefusal ?? refuseTrustBaseRef(root, trustBase);
|
|
135
222
|
if (refusal !== null) {
|
|
136
223
|
return {
|
|
137
224
|
kind: 'refused',
|
|
@@ -191,6 +278,12 @@ function policyForRun(root, trustBase, overrides) {
|
|
|
191
278
|
ref: trustBase,
|
|
192
279
|
policyChanged: policyDiffers(baseText, headText),
|
|
193
280
|
refusal: null,
|
|
281
|
+
// Computed AFTER refuseTrustBaseRef has already returned null, on the
|
|
282
|
+
// one shape that check accepts despite an identical tree: a merge
|
|
283
|
+
// commit whose first parent is this ref (issue #69). runAll reads this
|
|
284
|
+
// to run only the gates whose profile says readsHistory and to report
|
|
285
|
+
// every other enabled gate as tree-unchanged instead of spawning it.
|
|
286
|
+
treeUnchanged: headTreeEqualsBase(root, trustBase),
|
|
194
287
|
},
|
|
195
288
|
};
|
|
196
289
|
}
|
|
@@ -254,50 +347,84 @@ export function buildProgram() {
|
|
|
254
347
|
.option('--force', 'act on a file that has changed since init wrote it: replace a managed hook somebody has ' +
|
|
255
348
|
'edited (needs --hook), or with --revert remove one and restore any adopted hook')
|
|
256
349
|
.option('--json', 'print the result as JSON')
|
|
350
|
+
.option('--project <dir>', PROJECT_OPTION_HELP)
|
|
257
351
|
.exitOverride()
|
|
258
352
|
.action((options) => {
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
353
|
+
try {
|
|
354
|
+
// options.project === undefined takes the EXACT path main always
|
|
355
|
+
// did: process.cwd() straight through, with no resolveProjectRoot
|
|
356
|
+
// call at all. planInit and revertInit already do their own
|
|
357
|
+
// repoRootOf(options.cwd) and report a non-repository as a
|
|
358
|
+
// structured conflict (not-a-git-repository, JSON under --json,
|
|
359
|
+
// exit 2 through the ordinary result.ok branch below) rather than
|
|
360
|
+
// throwing, and planInit checks flag-requires-hook (--adopt or
|
|
361
|
+
// --force without --hook) BEFORE it ever asks whether it is in a
|
|
362
|
+
// repository at all. Calling resolveProjectRoot unconditionally
|
|
363
|
+
// here used to short-circuit both of those: it threw its own
|
|
364
|
+
// differently-worded, JSON-less error before planInit ever ran, so
|
|
365
|
+
// a plain "conductor init" outside a repository stopped matching
|
|
366
|
+
// main, and "--adopt" without "--hook" outside a repository
|
|
367
|
+
// reported the wrong conflict. Only an EXPLICIT --project goes
|
|
368
|
+
// through resolveProjectRoot, whose own usage errors (a path that
|
|
369
|
+
// does not exist, is not a directory, or is not inside a git
|
|
370
|
+
// repository) are new behaviour this flag introduces on purpose.
|
|
371
|
+
const cwd = options.project === undefined
|
|
372
|
+
? process.cwd()
|
|
373
|
+
: resolveProjectRoot(process.cwd(), options.project);
|
|
374
|
+
const shared = { cwd, pathValue: process.env.PATH ?? '' };
|
|
375
|
+
if (options.revert) {
|
|
376
|
+
const result = revertInit({
|
|
377
|
+
...shared,
|
|
378
|
+
force: Boolean(options.force),
|
|
379
|
+
dryRun: Boolean(options.dryRun),
|
|
380
|
+
});
|
|
381
|
+
const rendered = `${renderRevertHuman(result)}\n`;
|
|
382
|
+
if (options.json) {
|
|
383
|
+
process.stdout.write(`${JSON.stringify(result)}\n`);
|
|
384
|
+
}
|
|
385
|
+
else if (result.ok) {
|
|
386
|
+
process.stdout.write(rendered);
|
|
387
|
+
}
|
|
388
|
+
else {
|
|
389
|
+
// A partial revert left something behind, so it is not success
|
|
390
|
+
// output. Writing it to stdout would let a script pipe it past a
|
|
391
|
+
// reader who needed to see it.
|
|
392
|
+
process.stderr.write(rendered);
|
|
393
|
+
}
|
|
394
|
+
process.exitCode = result.ok ? 0 : EXIT_COULD_NOT_RUN;
|
|
395
|
+
return;
|
|
396
|
+
}
|
|
397
|
+
const initOptions = {
|
|
263
398
|
...shared,
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
399
|
+
...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
|
|
400
|
+
...(options.hook === undefined ? {} : { hook: options.hook }),
|
|
401
|
+
...(options.adopt === undefined ? {} : { adopt: options.adopt }),
|
|
402
|
+
...(options.force === undefined ? {} : { force: options.force }),
|
|
403
|
+
};
|
|
404
|
+
const result = applyInit(planInit(initOptions), initOptions);
|
|
268
405
|
if (options.json) {
|
|
269
406
|
process.stdout.write(`${JSON.stringify(result)}\n`);
|
|
270
407
|
}
|
|
271
408
|
else if (result.ok) {
|
|
272
|
-
process.stdout.write(
|
|
409
|
+
process.stdout.write(`${renderInitHuman(result)}\n`);
|
|
273
410
|
}
|
|
274
411
|
else {
|
|
275
|
-
|
|
276
|
-
// output. Writing it to stdout would let a script pipe it past a
|
|
277
|
-
// reader who needed to see it.
|
|
278
|
-
process.stderr.write(rendered);
|
|
412
|
+
process.stderr.write(`${renderInitHuman(result)}\n`);
|
|
279
413
|
}
|
|
280
414
|
process.exitCode = result.ok ? 0 : EXIT_COULD_NOT_RUN;
|
|
281
|
-
return;
|
|
282
415
|
}
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
else if (result.ok) {
|
|
295
|
-
process.stdout.write(`${renderInitHuman(result)}\n`);
|
|
296
|
-
}
|
|
297
|
-
else {
|
|
298
|
-
process.stderr.write(`${renderInitHuman(result)}\n`);
|
|
416
|
+
catch (err) {
|
|
417
|
+
// planInit, applyInit and revertInit report every ordinary
|
|
418
|
+
// conflict as a structured result rather than throwing, exactly as
|
|
419
|
+
// they did before this flag existed, so in practice only an
|
|
420
|
+
// explicit --project's own usage error reaches here. But this is
|
|
421
|
+
// not narrowed to that: any throw from this block lands here and
|
|
422
|
+
// gets the same one-line, no-stack treatment main's own outer catch
|
|
423
|
+
// gives an uncaught error, which is what this local catch replaces
|
|
424
|
+
// for the init command, the same shape "run"'s own catch below
|
|
425
|
+
// uses for the same kind of failure.
|
|
426
|
+
process.exitCode = fail(`conductor: ${err instanceof Error ? err.message : String(err)}`);
|
|
299
427
|
}
|
|
300
|
-
process.exitCode = result.ok ? 0 : EXIT_COULD_NOT_RUN;
|
|
301
428
|
});
|
|
302
429
|
program
|
|
303
430
|
.command('run')
|
|
@@ -313,21 +440,23 @@ export function buildProgram() {
|
|
|
313
440
|
.option('--compact-on-refusal', 'when the trust base was refused and no gate ran, print a short body instead of the full refusal report: the version, the verdict, and the refusal reason (with its remedy, when one applies), never the full per-gate report. Built for the pull-request-comment step; every other run is unaffected, whatever --verbose says. Text output only; SARIF is unaffected.')
|
|
314
441
|
.option('--gate <role>', 'restrict the run to this role; repeatable', (value, previous = []) => [...previous, value])
|
|
315
442
|
.option('--advisory', 'maps exit 1 (every enabled gate ran and at least one blocked) to exit 0, so a blocking finding never fails this run. A gate that could not run is unaffected and still exits 2: advisory changes what a FINDING does, never what a broken gate does. The report is unchanged and a blocking finding still prints as BLOCKING; only the process exit code and the verdict line, which says findings were advisory, are different.')
|
|
443
|
+
.option('--project <dir>', PROJECT_OPTION_HELP)
|
|
316
444
|
.exitOverride()
|
|
317
445
|
.action((options) => {
|
|
318
446
|
const cwd = process.cwd();
|
|
319
447
|
try {
|
|
320
|
-
// Inside the try, because
|
|
321
|
-
// and the catch below is what turns
|
|
322
|
-
// one line on stderr and the could-not-run
|
|
323
|
-
|
|
448
|
+
// Inside the try, because resolveProjectRoot (like repoRoot before
|
|
449
|
+
// it) reports rather than guesses, and the catch below is what turns
|
|
450
|
+
// any of its sentences into one line on stderr and the could-not-run
|
|
451
|
+
// exit code.
|
|
452
|
+
const root = resolveProjectRoot(cwd, options.project);
|
|
324
453
|
const overrides = {
|
|
325
454
|
...(parseRoles(options.gate) === undefined
|
|
326
455
|
? {}
|
|
327
456
|
: { gates: parseRoles(options.gate) }),
|
|
328
457
|
};
|
|
329
458
|
const stage = parseStage(options.stage);
|
|
330
|
-
const source = policyForRun(root, options.trustBase, overrides);
|
|
459
|
+
const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF);
|
|
331
460
|
const policy = source.kind === 'policy' ? source.policy : source.inventory;
|
|
332
461
|
const format = parseFormat(options.format ?? policy.report.format);
|
|
333
462
|
const result = source.kind === 'refused'
|
package/dist/gate-runner.js
CHANGED
|
@@ -409,11 +409,17 @@ function probeVersion(binary, product, repoRoot, timeoutMs) {
|
|
|
409
409
|
* `context.blocked` is whether the gate's exit said it blocked. The npm gates
|
|
410
410
|
* carry that in their own JSON and ignore it; the external tools' reports do
|
|
411
411
|
* not, so their normalizers take it from here.
|
|
412
|
+
*
|
|
413
|
+
* `context.online` and `context.lockfiles` are read from the umbrella's OWN
|
|
414
|
+
* constructed argv, never from a gate's JSON (issue #72): whether --online
|
|
415
|
+
* was passed and which lockfiles were handed over with --lockfile are
|
|
416
|
+
* questions about what this run asked for, which the umbrella already knows
|
|
417
|
+
* before the child ever answers.
|
|
412
418
|
*/
|
|
413
419
|
function normalizeFor(product, parsed, version, context) {
|
|
414
420
|
switch (product) {
|
|
415
421
|
case 'dep-guard':
|
|
416
|
-
return normalizeDepGuard(parsed, version);
|
|
422
|
+
return normalizeDepGuard(parsed, version, context.online);
|
|
417
423
|
case 'vault-guard':
|
|
418
424
|
return normalizeVaultGuard(parsed, version);
|
|
419
425
|
case 'intent-guard':
|
|
@@ -421,7 +427,7 @@ function normalizeFor(product, parsed, version, context) {
|
|
|
421
427
|
case 'gitleaks':
|
|
422
428
|
return normalizeGitleaks(parsed, version, context.blocked);
|
|
423
429
|
case 'osv-scanner':
|
|
424
|
-
return normalizeOsvScanner(parsed, version, context.blocked, context.roots);
|
|
430
|
+
return normalizeOsvScanner(parsed, version, context.blocked, context.roots, context.lockfiles);
|
|
425
431
|
}
|
|
426
432
|
}
|
|
427
433
|
/**
|
|
@@ -1046,6 +1052,10 @@ function spawnAndRead(ctx) {
|
|
|
1046
1052
|
const normalized = normalizeFor(gate.product, parsed, version, {
|
|
1047
1053
|
blocked,
|
|
1048
1054
|
roots: rootSpellings(options.repoRoot),
|
|
1055
|
+
// The literal flag, read off the argv this run actually spawned with,
|
|
1056
|
+
// not off gate.options: the argv is what dep-guard was actually told.
|
|
1057
|
+
online: argv.includes('--online'),
|
|
1058
|
+
lockfiles: external.lockfiles ?? [],
|
|
1049
1059
|
});
|
|
1050
1060
|
return {
|
|
1051
1061
|
...withRun,
|
package/dist/normalize.d.ts
CHANGED
|
@@ -1,7 +1,16 @@
|
|
|
1
1
|
import { type Finding, type NormalizedGateOutput, type Severity } from './envelope.js';
|
|
2
2
|
import type { GateRole, Product } from './policy.js';
|
|
3
|
-
export declare function normalizeDepGuard(raw: unknown, version: string | null
|
|
3
|
+
export declare function normalizeDepGuard(raw: unknown, version: string | null,
|
|
4
|
+
/** Whether the umbrella passed --online to dep-guard, read from its own argv. */
|
|
5
|
+
onlineRequested?: boolean): NormalizedGateOutput;
|
|
4
6
|
export declare function normalizeVaultGuard(raw: unknown, version: string | null): NormalizedGateOutput;
|
|
7
|
+
/**
|
|
8
|
+
* intent-guard's own namespace for its advance-notice warnings, not the
|
|
9
|
+
* umbrella's: the umbrella never mints a `conductor/` id for this, because
|
|
10
|
+
* the statement being relayed is entirely intent-guard's own (see AGENTS.md
|
|
11
|
+
* on the umbrella's fixed set of ids).
|
|
12
|
+
*/
|
|
13
|
+
export declare const INTENT_WARNING = "intent-guard/warning";
|
|
5
14
|
/**
|
|
6
15
|
* The three ways the intent gate can block on the STATE of the contract
|
|
7
16
|
* rather than on anything in the diff.
|
|
@@ -41,7 +50,9 @@ export declare function normalizeGitleaks(raw: unknown, version: string | null,
|
|
|
41
50
|
export declare function cvssToSeverity(score: number | null): Severity;
|
|
42
51
|
export declare function normalizeOsvScanner(raw: unknown, version: string | null, blocked: boolean,
|
|
43
52
|
/** The scan root as a path osv-scanner may have printed it, in any spelling. */
|
|
44
|
-
roots?: readonly string[]
|
|
53
|
+
roots?: readonly string[],
|
|
54
|
+
/** The lockfiles the umbrella passed with --lockfile, repository-relative. */
|
|
55
|
+
lockfiles?: readonly string[]): NormalizedGateOutput;
|
|
45
56
|
export type GateProblemRule = 'conductor/gate-missing' | 'conductor/gate-output-unparseable' | 'conductor/gate-failed';
|
|
46
57
|
/**
|
|
47
58
|
* The finding raised when an ENABLED gate's binary cannot be found.
|
package/dist/normalize.js
CHANGED
|
@@ -114,13 +114,42 @@ function readDiagnostics(value, product, where) {
|
|
|
114
114
|
};
|
|
115
115
|
});
|
|
116
116
|
}
|
|
117
|
-
|
|
117
|
+
function readOnlineInfo(value) {
|
|
118
|
+
if (!isRecord(value)) {
|
|
119
|
+
return null;
|
|
120
|
+
}
|
|
121
|
+
const info = {};
|
|
122
|
+
if (value.enabled !== undefined) {
|
|
123
|
+
if (typeof value.enabled !== 'boolean') {
|
|
124
|
+
return null;
|
|
125
|
+
}
|
|
126
|
+
info.enabled = value.enabled;
|
|
127
|
+
}
|
|
128
|
+
if (value.lookupsAttempted !== undefined) {
|
|
129
|
+
if (typeof value.lookupsAttempted !== 'number' || !Number.isFinite(value.lookupsAttempted)) {
|
|
130
|
+
return null;
|
|
131
|
+
}
|
|
132
|
+
info.lookupsAttempted = value.lookupsAttempted;
|
|
133
|
+
}
|
|
134
|
+
if (value.lookupsSkippedByDeadline !== undefined) {
|
|
135
|
+
if (typeof value.lookupsSkippedByDeadline !== 'number' ||
|
|
136
|
+
!Number.isFinite(value.lookupsSkippedByDeadline)) {
|
|
137
|
+
return null;
|
|
138
|
+
}
|
|
139
|
+
info.lookupsSkippedByDeadline = value.lookupsSkippedByDeadline;
|
|
140
|
+
}
|
|
141
|
+
return info;
|
|
142
|
+
}
|
|
143
|
+
export function normalizeDepGuard(raw, version,
|
|
144
|
+
/** Whether the umbrella passed --online to dep-guard, read from its own argv. */
|
|
145
|
+
onlineRequested = false) {
|
|
118
146
|
const product = 'dep-guard';
|
|
119
147
|
const root = needRecord(raw, product, 'the output');
|
|
120
148
|
const run = needRecord(root.run, product, 'run');
|
|
121
149
|
const threshold = optionalString(run.failOn, product, 'run.failOn') ?? null;
|
|
122
150
|
const trustBase = readTrustBase(root.trustBase, product);
|
|
123
151
|
const diagnostics = [];
|
|
152
|
+
const onlineInfo = readOnlineInfo(run.online);
|
|
124
153
|
const findings = needArray(root.findings, product, 'findings').map((entry, index) => {
|
|
125
154
|
const where = `findings[${index}]`;
|
|
126
155
|
const source = needRecord(entry, product, where);
|
|
@@ -167,12 +196,34 @@ export function normalizeDepGuard(raw, version) {
|
|
|
167
196
|
suppressed: typeof root.suppressed === 'number' ? root.suppressed : 0,
|
|
168
197
|
ignored: typeof root.ignored === 'number' ? root.ignored : 0,
|
|
169
198
|
// Diagnostics never move dep-guard's own exit code, so they stay out
|
|
170
|
-
// of findings[] here too rather than becoming pseudo-findings.
|
|
199
|
+
// of findings[] here too rather than becoming pseudo-findings. An
|
|
200
|
+
// installed dep-guard old enough to have no `run.online` object, or
|
|
201
|
+
// one whose online object says the budget ran out, raises its own
|
|
202
|
+
// online-deadline-exceeded diagnostic here, and it is carried through
|
|
203
|
+
// unchanged rather than the umbrella minting a second note about the
|
|
204
|
+
// same event (issue #72 fix round: dep-guard's own diagnostic already
|
|
205
|
+
// names the count, so nothing here duplicates it).
|
|
171
206
|
diagnostics: readDiagnostics(run.diagnostics, product, 'run.diagnostics'),
|
|
172
207
|
details: {
|
|
173
208
|
mode: run.mode ?? null,
|
|
174
209
|
corpusBuiltAt: run.corpusBuiltAt ?? null,
|
|
175
210
|
lockfileFormat: run.lockfileFormat ?? null,
|
|
211
|
+
// dep-guard's own `enabled` claim wins whenever the online object is
|
|
212
|
+
// present and valid: dep-guard can turn online checks on from
|
|
213
|
+
// ".dep-guard.json"'s own "online" key with no flag at all, so the
|
|
214
|
+
// umbrella's argv does not always know the true answer. Only when
|
|
215
|
+
// there is no trustworthy claim to read does this fall back to
|
|
216
|
+
// stating what the umbrella itself asked for, worded so it is never
|
|
217
|
+
// mistaken for a claim about what dep-guard actually did.
|
|
218
|
+
...(onlineInfo?.enabled === undefined
|
|
219
|
+
? { 'online-flag': onlineRequested ? 'passed' : 'not passed' }
|
|
220
|
+
: { online: onlineInfo.enabled }),
|
|
221
|
+
...(onlineInfo?.lookupsAttempted === undefined
|
|
222
|
+
? {}
|
|
223
|
+
: { lookups: onlineInfo.lookupsAttempted }),
|
|
224
|
+
...(onlineInfo?.lookupsSkippedByDeadline === undefined
|
|
225
|
+
? {}
|
|
226
|
+
: { 'skipped-by-deadline': onlineInfo.lookupsSkippedByDeadline }),
|
|
176
227
|
},
|
|
177
228
|
},
|
|
178
229
|
diagnostics,
|
|
@@ -331,6 +382,57 @@ const DRIFT_SEVERITY = {
|
|
|
331
382
|
info: 'low',
|
|
332
383
|
proceed: 'info',
|
|
333
384
|
};
|
|
385
|
+
/**
|
|
386
|
+
* intent-guard's own namespace for its advance-notice warnings, not the
|
|
387
|
+
* umbrella's: the umbrella never mints a `conductor/` id for this, because
|
|
388
|
+
* the statement being relayed is entirely intent-guard's own (see AGENTS.md
|
|
389
|
+
* on the umbrella's fixed set of ids).
|
|
390
|
+
*/
|
|
391
|
+
export const INTENT_WARNING = 'intent-guard/warning';
|
|
392
|
+
/**
|
|
393
|
+
* intent-guard 1.7.0's own advance notice that a frozen contract's
|
|
394
|
+
* `protected_paths` or `allowed_paths` carries an entry no git path can
|
|
395
|
+
* ever match (a leading slash, an empty path segment, and the like), read
|
|
396
|
+
* from the optional `warnings` array. 1.7.0 warns about this; 2.0.0 turns it
|
|
397
|
+
* into a blocking reason (intent-guard's own budget-paths.ts).
|
|
398
|
+
*
|
|
399
|
+
* Tolerant on purpose, unlike everything else this file validates: this is
|
|
400
|
+
* reporting, never judgment, so a shape an installed intent-guard did not
|
|
401
|
+
* send correctly must never turn into a could-not-run for the gate. Absent
|
|
402
|
+
* (1.6.0 and earlier, which never sent this field) means none. A value that
|
|
403
|
+
* is not an array, or an array holding even one non-string entry, is
|
|
404
|
+
* ignored outright rather than partially read: half-reading it would print
|
|
405
|
+
* some warnings and silently drop others, which is worse than saying
|
|
406
|
+
* nothing until the shape is understood again.
|
|
407
|
+
*/
|
|
408
|
+
function readIntentWarnings(raw) {
|
|
409
|
+
if (!Array.isArray(raw)) {
|
|
410
|
+
return [];
|
|
411
|
+
}
|
|
412
|
+
return raw.every((entry) => typeof entry === 'string') ? raw : [];
|
|
413
|
+
}
|
|
414
|
+
/**
|
|
415
|
+
* intent-guard 1.6.0 (issue #34) caps a constraint finding at advisory when
|
|
416
|
+
* its `source` is a prose rules file (CLAUDE.md, AGENTS.md, GEMINI.md,
|
|
417
|
+
* cursor rules): a strong match is still reported, but it never raises
|
|
418
|
+
* `constraint_violation`, `criticalViolated`, or the gate's own exit code.
|
|
419
|
+
*
|
|
420
|
+
* `finding_details` carries no field saying so. `strength` is "strong" for a
|
|
421
|
+
* capped prose match exactly the same as an uncapped one, and the
|
|
422
|
+
* constraint's `source` is never carried onto the finding at all. The ONLY
|
|
423
|
+
* surviving signal is this literal prefix, which intent-guard's own drift.ts
|
|
424
|
+
* puts on the message for this one case.
|
|
425
|
+
*
|
|
426
|
+
* THIS IS NOT A SAFETY NET. Nothing in this repository detects an upstream
|
|
427
|
+
* rewording of that prefix: there is no test against the live binary, only
|
|
428
|
+
* a static fixture capture, so a wording change in a future intent-guard
|
|
429
|
+
* release would silently stop matching here and a capped finding would go
|
|
430
|
+
* back to rendering as blocking with no warning anywhere in this report or
|
|
431
|
+
* in CI. Filed upstream as intent-guard #114, asking for a machine-readable
|
|
432
|
+
* per-finding field so this can stop keying on message text; this constant
|
|
433
|
+
* is the interim measure until that lands, not a substitute for it.
|
|
434
|
+
*/
|
|
435
|
+
const ADVISORY_CONSTRAINT_PREFIX = 'advisory ';
|
|
334
436
|
/**
|
|
335
437
|
* The three ways the intent gate can block on the STATE of the contract
|
|
336
438
|
* rather than on anything in the diff.
|
|
@@ -432,6 +534,7 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
432
534
|
fail(product, 'status', 'either "ok" or "blocked"');
|
|
433
535
|
}
|
|
434
536
|
const trustBase = readTrustBase(root.trustBase, product);
|
|
537
|
+
const warnings = readIntentWarnings(root.warnings);
|
|
435
538
|
const findings = [];
|
|
436
539
|
const budget = root.budget === undefined ? undefined : needRecord(root.budget, product, 'budget');
|
|
437
540
|
const drift = root.drift === undefined ? undefined : needRecord(root.drift, product, 'drift');
|
|
@@ -486,6 +589,11 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
486
589
|
const where = `drift.finding_details[${index}]`;
|
|
487
590
|
const detail = needRecord(rawDetail, product, where);
|
|
488
591
|
const category = needString(detail.category, product, `${where}.category`);
|
|
592
|
+
const message = needString(detail.message, product, `${where}.message`);
|
|
593
|
+
// See ADVISORY_CONSTRAINT_PREFIX. A capped finding never contributed to
|
|
594
|
+
// driftAction, so it must not inherit that action's blocking flag or
|
|
595
|
+
// severity the way every other drift finding here does (issue #34).
|
|
596
|
+
const advisoryCapped = category === 'constraint_violation' && message.startsWith(ADVISORY_CONSTRAINT_PREFIX);
|
|
489
597
|
findings.push({
|
|
490
598
|
schemaVersion: 1,
|
|
491
599
|
product,
|
|
@@ -494,10 +602,10 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
494
602
|
// rule id that contains a user's sentence is not a rule id. The full
|
|
495
603
|
// value goes in details.
|
|
496
604
|
ruleId: `intent-guard/drift.${category}`,
|
|
497
|
-
severity: DRIFT_SEVERITY[driftAction] ?? 'info',
|
|
605
|
+
severity: advisoryCapped ? 'low' : (DRIFT_SEVERITY[driftAction] ?? 'info'),
|
|
498
606
|
severityIsDerived: true,
|
|
499
|
-
blocking: driftBlocks,
|
|
500
|
-
message
|
|
607
|
+
blocking: advisoryCapped ? false : driftBlocks,
|
|
608
|
+
message,
|
|
501
609
|
// No paths subject: `matched` here is "tokens or paths", so treating
|
|
502
610
|
// it as a path list would sometimes point at a file that does not
|
|
503
611
|
// exist. It stays in details, where it is not claiming to be a location.
|
|
@@ -577,7 +685,10 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
577
685
|
failOn: null,
|
|
578
686
|
suppressed: 0,
|
|
579
687
|
ignored: 0,
|
|
580
|
-
|
|
688
|
+
// intent-guard's own advance-notice warnings (1.7.0's budget-path
|
|
689
|
+
// deprecation notes). Reporting, never a finding: no severity, no
|
|
690
|
+
// fingerprint, no blocking flag, and no effect on the exit code.
|
|
691
|
+
diagnostics: warnings.map((message) => ({ code: INTENT_WARNING, message })),
|
|
581
692
|
details: {
|
|
582
693
|
contractFound: root.contractFound ?? null,
|
|
583
694
|
contractFrozen: root.contractFrozen ?? null,
|
|
@@ -823,9 +934,21 @@ function relativeToRoots(file, roots) {
|
|
|
823
934
|
}
|
|
824
935
|
return file;
|
|
825
936
|
}
|
|
937
|
+
/**
|
|
938
|
+
* The vulnerabilities summary line's lockfile fact (issue #72): the count and
|
|
939
|
+
* names of the lockfiles the UMBRELLA handed osv-scanner with --lockfile,
|
|
940
|
+
* never osv-scanner's own results[], which 2.x prints only for a source with
|
|
941
|
+
* findings. A clean scan of one lockfile and a run that scanned none both
|
|
942
|
+
* have results: [], and only this list tells them apart.
|
|
943
|
+
*/
|
|
944
|
+
function describeLockfiles(lockfiles) {
|
|
945
|
+
return lockfiles.length === 0 ? '0' : `${lockfiles.length} (${lockfiles.join(', ')})`;
|
|
946
|
+
}
|
|
826
947
|
export function normalizeOsvScanner(raw, version, blocked,
|
|
827
948
|
/** The scan root as a path osv-scanner may have printed it, in any spelling. */
|
|
828
|
-
roots = []
|
|
949
|
+
roots = [],
|
|
950
|
+
/** The lockfiles the umbrella passed with --lockfile, repository-relative. */
|
|
951
|
+
lockfiles = []) {
|
|
829
952
|
const product = 'osv-scanner';
|
|
830
953
|
const top = needRecord(raw, product, 'the output');
|
|
831
954
|
const results = needArray(top.results, product, 'results');
|
|
@@ -888,7 +1011,13 @@ roots = []) {
|
|
|
888
1011
|
suppressed: 0,
|
|
889
1012
|
ignored: 0,
|
|
890
1013
|
diagnostics: [],
|
|
891
|
-
details: {
|
|
1014
|
+
details: {
|
|
1015
|
+
lockfiles: describeLockfiles(lockfiles),
|
|
1016
|
+
// Distinct from the old "sources" name on purpose: this counts only
|
|
1017
|
+
// the sources osv-scanner reported findings for, never how many were
|
|
1018
|
+
// scanned, and the old name read as the latter.
|
|
1019
|
+
'sources-with-findings': results.length,
|
|
1020
|
+
},
|
|
892
1021
|
},
|
|
893
1022
|
diagnostics: [],
|
|
894
1023
|
};
|