@vaultcompass/conductor 0.8.0 → 0.9.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.
Files changed (44) hide show
  1. package/README.md +263 -77
  2. package/dist/cli.js +152 -30
  3. package/dist/envelope.d.ts +8 -0
  4. package/dist/exit-codes.d.ts +52 -2
  5. package/dist/exit-codes.js +64 -14
  6. package/dist/external-config.d.ts +2 -1
  7. package/dist/external-config.js +33 -18
  8. package/dist/gate-runner.d.ts +141 -17
  9. package/dist/gate-runner.js +537 -83
  10. package/dist/git.d.ts +95 -0
  11. package/dist/git.js +244 -0
  12. package/dist/init-policy.js +38 -2
  13. package/dist/init.js +40 -3
  14. package/dist/intent-base.d.ts +35 -1
  15. package/dist/intent-base.js +124 -64
  16. package/dist/intent-prepare.d.ts +33 -2
  17. package/dist/intent-prepare.js +443 -34
  18. package/dist/intent-spec.d.ts +28 -0
  19. package/dist/intent-spec.js +22 -5
  20. package/dist/normalize.d.ts +11 -0
  21. package/dist/normalize.js +60 -6
  22. package/dist/osv-baseline.d.ts +84 -0
  23. package/dist/osv-baseline.js +325 -0
  24. package/dist/osv-coverage.d.ts +80 -0
  25. package/dist/osv-coverage.js +223 -0
  26. package/dist/output-sarif.js +55 -15
  27. package/dist/output-text.d.ts +53 -2
  28. package/dist/output-text.js +287 -27
  29. package/dist/policy.d.ts +10 -0
  30. package/dist/policy.js +21 -7
  31. package/dist/products.d.ts +32 -10
  32. package/dist/products.js +73 -9
  33. package/dist/requirements-pin.d.ts +47 -0
  34. package/dist/requirements-pin.js +256 -0
  35. package/dist/resolve.d.ts +1 -0
  36. package/dist/resolve.js +1 -1
  37. package/dist/run.d.ts +21 -0
  38. package/dist/run.js +74 -15
  39. package/dist/trust-base.d.ts +101 -20
  40. package/dist/trust-base.js +219 -73
  41. package/dist/unread-manifests.d.ts +14 -0
  42. package/dist/unread-manifests.js +69 -0
  43. package/package.json +1 -1
  44. package/schema/guardrails.schema.json +4 -0
@@ -21,13 +21,130 @@ import { spawnSync } from 'node:child_process';
21
21
  import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
22
22
  import { tmpdir } from 'node:os';
23
23
  import path from 'node:path';
24
+ import { runGit } from './git.js';
24
25
  import { NormalizeError } from './envelope.js';
25
- import { normalizeDepGuard, normalizeFailedGate, normalizeGitleaks, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeOsvScanner, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
26
+ import { describeLockfiles, normalizeDepGuard, normalizeFailedGate, normalizeGitleaks, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeOsvScanner, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
26
27
  import { renderOptionFlags } from './policy.js';
28
+ import { NO_RESOLVE_OVERRIDDEN, emptiedLockfiles, noLongerScanned, nothingScannableMessage, notScannedDetail, selectOsvInputs, } from './osv-coverage.js';
29
+ import { compareWithBase, comparisonFailed, } from './osv-baseline.js';
27
30
  import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals, } from './external-config.js';
28
- import { profileFor } from './products.js';
31
+ import { osvLockfileKind, profileFor } from './products.js';
32
+ import { unreadManifestsNote } from './unread-manifests.js';
29
33
  import { atLeastVersion, refuseHeadControlledProgram } from './trust-base.js';
30
34
  import { ResolveError, candidateNames, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
35
+ /** The longest excerpt of a gate's own reason that is carried. */
36
+ export const GATE_SAID_MAX_CHARS = 160;
37
+ /**
38
+ * A short, plain excerpt of one line of gate output.
39
+ *
40
+ * ASCII only and one line, because the excerpt lands in a job log line, in the
41
+ * text report and in a pull-request comment: control characters, escape
42
+ * sequences and anything a terminal would interpret are replaced, whitespace is
43
+ * collapsed, workflow-command markers are broken up, double quotes become
44
+ * single quotes (the excerpt is shown inside double quotes), and the result is
45
+ * cut at GATE_SAID_MAX_CHARS.
46
+ */
47
+ function sanitizeGateSaid(raw) {
48
+ const flat = breakWorkflowMarkers(stripAnsi(raw)
49
+ .replace(/[^\x20-\x7e]/g, ' ')
50
+ .replace(/\s+/g, ' ')
51
+ .trim()).replace(/"/g, "'");
52
+ if (flat === '') {
53
+ return null;
54
+ }
55
+ return flat.length > GATE_SAID_MAX_CHARS ? `${flat.slice(0, GATE_SAID_MAX_CHARS - 3)}...` : flat;
56
+ }
57
+ /**
58
+ * Breaks up the two character sequences a CI log reader treats as a command
59
+ * ("##[" and "::") by putting a space inside them, so gate-printed text stays
60
+ * inert in a job log. Repeated until stable, so runs such as ":::" and "###["
61
+ * are covered too.
62
+ */
63
+ export function breakWorkflowMarkers(text) {
64
+ let out = text;
65
+ for (;;) {
66
+ const next = out.replace(/#(?=#\[)/g, '# ').replace(/:(?=:)/g, ': ');
67
+ if (next === out) {
68
+ return out;
69
+ }
70
+ out = next;
71
+ }
72
+ }
73
+ /**
74
+ * The could-not-run reasons that are conductor's OWN decision, made before
75
+ * the gate was spawned (or instead of spawning it), as opposed to something
76
+ * the gate itself said or did.
77
+ */
78
+ export const CONDUCTOR_OWN_REASONS = new Set([
79
+ 'preparation-failed',
80
+ 'trust-base-unverified',
81
+ 'gate-program-refused',
82
+ 'gate-version-unsupported',
83
+ 'history-shallow',
84
+ ]);
85
+ /**
86
+ * conductor's own reason for a could-not-run, as a job-log excerpt: cleaned,
87
+ * one line, capped and with double quotes replaced, exactly like a gate's
88
+ * stated reason. Null when there is nothing to print.
89
+ */
90
+ export function conductorStatedReason(detail) {
91
+ return sanitizeGateSaid(detail);
92
+ }
93
+ /**
94
+ * One line of raw gate output, made safe to print: control characters (escape
95
+ * included) become spaces and workflow-command markers are broken up. The
96
+ * content is otherwise left as it was.
97
+ */
98
+ export function cleanOutputLine(raw) {
99
+ return breakWorkflowMarkers(raw.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' '));
100
+ }
101
+ /**
102
+ * What a gate that exited with a non-verdict code said about why.
103
+ *
104
+ * TOTAL, and never a decision: the caller has already settled that this is a
105
+ * could-not-run, and nothing here can change that. The first non-empty stderr
106
+ * line is preferred, since that is where every gate in the family prints its
107
+ * reason on exit 2 (dep-guard, intent-guard and vault-guard all do). Failing
108
+ * that, stdout is parsed only for a gate whose output is JSON on stdout, and
109
+ * only a string `reason` field (top level, or on `run`) is read; anything else,
110
+ * including output that does not parse, is simply no excerpt.
111
+ */
112
+ export function gateStatedReason(stderr, stdout, stdoutIsJson) {
113
+ try {
114
+ const firstLine = stripAnsi(stderr)
115
+ .split('\n')
116
+ .map((line) => sanitizeGateSaid(line))
117
+ .find((line) => line !== null);
118
+ if (firstLine !== undefined && firstLine !== null) {
119
+ return firstLine;
120
+ }
121
+ if (!stdoutIsJson || typeof stdout !== 'string' || !stdout.trimStart().startsWith('{')) {
122
+ return null;
123
+ }
124
+ const parsed = JSON.parse(stdout);
125
+ if (typeof parsed !== 'object' || parsed === null) {
126
+ return null;
127
+ }
128
+ const record = parsed;
129
+ const run = record.run;
130
+ const candidates = [
131
+ record.reason,
132
+ typeof run === 'object' && run !== null ? run.reason : undefined,
133
+ ];
134
+ for (const candidate of candidates) {
135
+ if (typeof candidate === 'string') {
136
+ const excerpt = sanitizeGateSaid(candidate);
137
+ if (excerpt !== null) {
138
+ return excerpt;
139
+ }
140
+ }
141
+ }
142
+ return null;
143
+ }
144
+ catch {
145
+ return null;
146
+ }
147
+ }
31
148
  /**
32
149
  * The first version of each gate that understands `--trust-base`.
33
150
  *
@@ -36,10 +153,11 @@ import { ResolveError, candidateNames, nodeModulesCandidate, resolveGateBinary,
36
153
  * against every combination in the meantime. A product missing from this
37
154
  * table has no pull-request mode yet and is never handed the flag; a product
38
155
  * in it is handed the flag only when the installed build says it is at least
39
- * this version. Both directions matter: handing an older build a flag it does
40
- * not parse makes it exit non-zero with no JSON, which the umbrella correctly
41
- * reports as could-not-run, so a wrong guess here turns a working repository's
42
- * pull requests red rather than merely leaving a gate un-hardened.
156
+ * this version, and on a run with a trust base a build below it is
157
+ * could-not-run rather than run without the flag, since without the flag it
158
+ * would take its rules from the tree being judged. The entries are the
159
+ * minimum the umbrella requires on a pull-request run, which can be later
160
+ * than the release the flag first appeared in.
43
161
  *
44
162
  * The umbrella is deliberately NOT the place a version pin lives otherwise
45
163
  * (nothing here imports any gate's package), and this is the one exception:
@@ -47,9 +165,9 @@ import { ResolveError, candidateNames, nodeModulesCandidate, resolveGateBinary,
47
165
  * this package has to those tools.
48
166
  */
49
167
  export const TRUST_BASE_MIN_VERSION = {
50
- 'intent-guard': '1.4.0',
51
- 'vault-guard': '1.7.0',
52
- 'dep-guard': '0.6.0',
168
+ 'intent-guard': '1.8.1',
169
+ 'vault-guard': '1.9.1',
170
+ 'dep-guard': '0.10.1',
53
171
  // The two external tools have no --trust-base and are never handed one.
54
172
  // For them the umbrella itself provides pull-request mode: it scopes the
55
173
  // history to base..HEAD and hands over the config (and gitleaks' ignore
@@ -64,6 +182,48 @@ export const TRUST_BASE_MIN_VERSION = {
64
182
  // branch below is what keeps that gate from being handed a flag it would
65
183
  // reject.
66
184
  };
185
+ /**
186
+ * The first intent-guard whose own `--base` can carry any change set: it
187
+ * reads the paths from git NUL-separated (1.8.0) and lists a moved submodule
188
+ * pointer with --ignore-submodules=none and ends the range with "--" (the
189
+ * release after 1.8.0). For a native contract on this version or later the
190
+ * runner hands the gate `--base` instead of `--paths`, so a changed path
191
+ * that `--paths` cannot carry (a comma, a backslash, edge whitespace, a
192
+ * leading "-") is judged rather than refused.
193
+ *
194
+ * It equals the intent-guard entry in `TRUST_BASE_MIN_VERSION`, so on a run
195
+ * with a trust base every intent gate that runs is new enough, and the
196
+ * `--paths` refusal for a native contract is reached only on a run without
197
+ * one (an explicit `--base`). Kept as its own constant because the two
198
+ * answer different questions and the floor may move without it.
199
+ */
200
+ export const INTENT_BASE_CHANNEL_MIN_VERSION = '1.8.1';
201
+ /**
202
+ * How the intent gate is handed the change set on a prepared run: its own
203
+ * `--base` (native contract, gate new enough), `--paths`, or not at all,
204
+ * with the reason, when `--paths` cannot carry it and `--base` is not
205
+ * available.
206
+ */
207
+ function intentChangeChannel(gate, intent, version) {
208
+ if (gate.product !== 'intent-guard' || intent === undefined || intent.paths === null) {
209
+ return { kind: 'paths' };
210
+ }
211
+ if (intent.contractSource.kind === 'native' &&
212
+ intent.baseRef !== null &&
213
+ atLeastVersion(version, INTENT_BASE_CHANNEL_MIN_VERSION)) {
214
+ return { kind: 'base', ref: intent.baseRef };
215
+ }
216
+ if (intent.pathsRefusal !== undefined) {
217
+ return {
218
+ kind: 'refused',
219
+ detail: `${intent.pathsRefusal} intent-guard ${version ?? 'of an unreadable version'} takes the ` +
220
+ 'change set only as that list, so nothing was checked by this gate. To clear it, ' +
221
+ `upgrade intent-guard to ${INTENT_BASE_CHANNEL_MIN_VERSION} or later, which reads the ` +
222
+ 'change set from git itself for a contract frozen in the repository.',
223
+ };
224
+ }
225
+ return { kind: 'paths' };
226
+ }
67
227
  /**
68
228
  * Whether this gate can be handed `--trust-base`, and why not when it cannot.
69
229
  *
@@ -94,11 +254,6 @@ export function decideTrustBase(gate, intent, trustBase, productVersion) {
94
254
  refused: reason,
95
255
  proposals: [],
96
256
  });
97
- if (intent !== undefined && intent.contractSource.kind !== 'native') {
98
- return withheld('the intent gate is running against a contract imported for this run, which lives in a ' +
99
- 'temporary directory with no repository in it, so there is no ref there to read control ' +
100
- 'inputs from. The contract it is judging against came from a spec in the head tree.');
101
- }
102
257
  const minimum = TRUST_BASE_MIN_VERSION[gate.product];
103
258
  if (minimum === undefined) {
104
259
  return withheld(`${gate.product} has no pull-request mode yet, so it read its own configuration from the ` +
@@ -117,10 +272,25 @@ export function decideTrustBase(gate, intent, trustBase, productVersion) {
117
272
  'its rules from the base ref. Nothing was checked by it. Running it anyway would put it ' +
118
273
  'quietly outside the trust boundary on exactly the runs where something is already wrong.');
119
274
  }
275
+ // A version BELOW the minimum is refused too, never withheld: running it
276
+ // without the flag would let it take its rules from the tree being judged
277
+ // on a run whose whole promise is that every rule comes from the base ref.
120
278
  if (!atLeastVersion(productVersion, minimum)) {
121
- return withheld(`${gate.product} ${productVersion} does not understand --trust-base, which arrived in ` +
122
- `${minimum}, so it read its own control inputs from the tree being judged. Upgrade it to ` +
123
- 'put this gate into pull-request mode.');
279
+ return refused(`${gate.product} did not run: the installed ${productVersion} is older than ${minimum}, the ` +
280
+ 'first version that takes its rules from the base ref on a pull-request run, so nothing ' +
281
+ `was checked by it. Fix: install ${gate.product} ${minimum} or newer, or remove an ` +
282
+ 'explicit older version pin.');
283
+ }
284
+ // AFTER the version checks, so an imported contract cannot let an older
285
+ // gate run: this withholding is about where --project points, not about
286
+ // what the gate understands, and the contract itself came from the base.
287
+ if (intent !== undefined && intent.contractSource.kind !== 'native') {
288
+ const from = intent.contractSource.kind === 'imported' && intent.contractSource.ref !== undefined
289
+ ? `came from the spec on "${intent.contractSource.ref}"`
290
+ : 'came from a spec in the head tree';
291
+ return withheld('the intent gate is running against a contract imported for this run, which lives in a ' +
292
+ 'temporary directory with no repository in it, so there is no ref there to read control ' +
293
+ `inputs from. The contract it is judging against ${from}.`);
124
294
  }
125
295
  return { ref: trustBase, withheld: null, refused: null, proposals: [] };
126
296
  }
@@ -241,7 +411,12 @@ export function gateArgs(gate, staged, intent,
241
411
  */
242
412
  trustBase,
243
413
  /** Paths the runner owns for an external tool; the npm gates ignore them. */
244
- external = {}) {
414
+ external = {},
415
+ /**
416
+ * For the intent gate on a prepared run: hand it this base with its own
417
+ * `--base` in place of `--paths`. Decided by `intentChangeChannel`.
418
+ */
419
+ intentBase) {
245
420
  const passthrough = renderOptionFlags(gate.options);
246
421
  const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
247
422
  const config = external.configPath === undefined ? [] : ['--config', external.configPath];
@@ -275,9 +450,12 @@ external = {}) {
275
450
  // a passthrough value being read as the positional.
276
451
  //
277
452
  // `scan` takes --trust-base from 1.7.0. On exit 2 it prints a line on
278
- // stderr and may also write a JSON document (it can on a staged run);
279
- // conductor never parses stdout on exit 2, so the could-not-run path
280
- // above handles both before JSON.parse is reached.
453
+ // stderr and may also write a JSON document (it can on a staged run, and
454
+ // from 1.9.1 on a scan that skipped files). conductor never reads a
455
+ // verdict out of stdout on exit 2: the could-not-run branch in
456
+ // spawnAndRead, below, returns before the verdict JSON.parse is reached.
457
+ // That branch does read the stderr first line, or a reason field in the
458
+ // JSON, as a bounded excerpt for the reader (gateStatedReason).
281
459
  return [...(staged ? ['--staged'] : []), '-f', 'json', ...trust, ...passthrough];
282
460
  case 'intent-guard': {
283
461
  if (intent === undefined) {
@@ -305,7 +483,9 @@ external = {}) {
305
483
  ? staged
306
484
  ? ['--staged']
307
485
  : []
308
- : ['--paths', intent.paths.join(',')]),
486
+ : intentBase !== undefined
487
+ ? ['--base', intentBase]
488
+ : ['--paths', intent.paths.join(',')]),
309
489
  // Beside --paths on purpose, and they are independent: --trust-base
310
490
  // says where the RULES come from, --paths says which paths are
311
491
  // judged. A pull-request run passes both.
@@ -365,15 +545,55 @@ external = {}) {
365
545
  case 'osv-scanner': {
366
546
  // JSON goes to stdout and everything else to stderr, so no report
367
547
  // file. No directory walk: each tracked lockfile is named with
368
- // --lockfile (the runner lists them, src/products.ts
369
- // OSV_LOCKFILE_NAMES), because osv-scanner's own walk skips anything
370
- // .gitignore matches, tracked or not. With none there is nothing to
371
- // hand over, and the runner reports that without spawning the tool.
548
+ // --lockfile (the runner lists them, src/osv-coverage.ts), because
549
+ // osv-scanner's own walk skips anything .gitignore matches, tracked or
550
+ // not. With none there is nothing to hand over, and the runner reports
551
+ // that without spawning the tool.
372
552
  if (external.lockfiles === undefined || external.lockfiles.length === 0) {
373
553
  throw new Error('osv-scanner needs at least one lockfile: with none, nothing is spawned');
374
554
  }
375
- const lockfiles = external.lockfiles.flatMap((file) => ['--lockfile', file]);
376
- return ['--format', 'json', ...config, ...lockfiles, ...passthrough];
555
+ const isRequirements = (file) => osvLockfileKind(path.basename(file)) === 'requirements';
556
+ // A requirements variant (requirements-dev.txt) is handed in the
557
+ // parse-as form, because 2.4.0 does not recognise the bare name;
558
+ // requirements.txt itself and every exact lockfile name go bare
559
+ // (npm-shrinkwrap.json is not even a valid parse-as type in 2.4.0).
560
+ // The parse-as form splits on the first colon only, so a variant's own
561
+ // path is safe; a bare path with a colon is split and exits 127, which
562
+ // is a could-not-run, never a silent skip.
563
+ const lockfiles = external.lockfiles.flatMap((file) => [
564
+ '--lockfile',
565
+ isRequirements(file) && path.basename(file) !== 'requirements.txt' ? `requirements.txt:${file}` : file,
566
+ ]);
567
+ // --no-resolve on every invocation that carries a requirements file,
568
+ // and on the base run exactly when the head run had it (section 2.4):
569
+ // without a lockfile, a resolved transitive version is the registry's
570
+ // latest, not the installed one. Not overridable: a policy no-resolve
571
+ // is dropped from such an invocation (the runner says so), because
572
+ // no-resolve: false would render --no-no-resolve, which osv rejects.
573
+ const noResolve = external.noResolve ?? external.lockfiles.some(isRequirements);
574
+ const options = { ...gate.options };
575
+ if (noResolve) {
576
+ delete options['no-resolve'];
577
+ }
578
+ // On a pull-request run, call analysis is off for every language
579
+ // unless the base policy says otherwise (section 3.3, open question 6):
580
+ // the base copies carry no source, so call analysis could hide on the
581
+ // head what the base run reports, and the comparison would then not be
582
+ // a dependency fact. Off on both runs makes the head only gain
583
+ // findings. A policy that names either key keeps its own value, on
584
+ // both runs, through the passthrough.
585
+ const callAnalysis = trustBase !== undefined && !('call-analysis' in options) && !('no-call-analysis' in options)
586
+ ? ['--no-call-analysis=all']
587
+ : [];
588
+ return [
589
+ '--format',
590
+ 'json',
591
+ ...config,
592
+ ...lockfiles,
593
+ ...(noResolve ? ['--no-resolve'] : []),
594
+ ...callAnalysis,
595
+ ...renderOptionFlags(options),
596
+ ];
377
597
  }
378
598
  }
379
599
  }
@@ -525,6 +745,7 @@ export function runGate(gate, options) {
525
745
  intent: {
526
746
  contractSource: options.intent.contractSource,
527
747
  baseRef: options.intent.baseRef,
748
+ ...(options.intent.note === undefined ? {} : { note: options.intent.note }),
528
749
  },
529
750
  }
530
751
  : options.intentContract === undefined
@@ -568,12 +789,20 @@ export function runGate(gate, options) {
568
789
  * than a clear "true" (no git, an old git that does not know the flag) is
569
790
  * not shallow: those runs have their own failure paths.
570
791
  */
792
+ /** The oldest git a history gate runs under on a pull-request run. */
793
+ export const HISTORY_GIT_FLOOR = '2.31.0';
794
+ /** git's own version ("git version 2.39.3 (Apple Git-145)" reads 2.39.3), or null. */
795
+ function probeGitVersion(repoRoot) {
796
+ const probe = runGit(repoRoot, ['--version']);
797
+ if (probe.error !== undefined || probe.status !== 0) {
798
+ return null;
799
+ }
800
+ const match = /git version (\d+\.\d+\.\d+)/.exec(probe.stdout);
801
+ return match === null ? null : match[1];
802
+ }
571
803
  function isShallowRepository(repoRoot) {
572
- const probe = spawnSync('git', ['rev-parse', '--is-shallow-repository'], {
573
- cwd: repoRoot,
574
- encoding: 'utf8',
575
- });
576
- return probe.status === 0 && typeof probe.stdout === 'string' && probe.stdout.trim() === 'true';
804
+ const probe = runGit(repoRoot, ['rev-parse', '--is-shallow-repository']);
805
+ return probe.status === 0 && probe.stdout.trim() === 'true';
577
806
  }
578
807
  function runGateInner(gate, options, started, progress) {
579
808
  const timeoutMs = options.timeoutMs ?? profileFor(gate.product).timeoutMs;
@@ -660,13 +889,41 @@ function runGateInner(gate, options, started, progress) {
660
889
  };
661
890
  }
662
891
  }
892
+ // THE GIT FLOOR, on a pull-request run, for a gate that reads history. The
893
+ // newest git option this umbrella relies on is the one it hands gitleaks,
894
+ // "git log --diff-merges=first-parent" (git 2.31, per git's release notes);
895
+ // every other option conductor itself passes is older (rev-parse
896
+ // --is-shallow-repository is git 2.15). An older git would make that gate
897
+ // log a git error rather than say why, so the version is asked once, here,
898
+ // and an older one is a named could-not-run. Only where the option is used:
899
+ // a run with no history gate never pays for the probe or meets the floor.
900
+ if (profileFor(gate.product).readsHistory && options.trustBase !== undefined) {
901
+ const gitVersion = probeGitVersion(options.repoRoot);
902
+ if (gitVersion === null || !atLeastVersion(gitVersion, HISTORY_GIT_FLOOR)) {
903
+ const found = gitVersion === null
904
+ ? `the git version could not be read, so git is not known to be ${HISTORY_GIT_FLOOR} or later`
905
+ : `git ${gitVersion} is older than ${HISTORY_GIT_FLOOR}`;
906
+ const detail = `${found}, which ${gate.product} needs on a pull-request run: conductor hands it ` +
907
+ '"git log --diff-merges=first-parent", which arrived in git 2.31. Upgrade git, then run ' +
908
+ 'again. Nothing was checked by this gate.';
909
+ return {
910
+ ...base,
911
+ enforce: true,
912
+ durationMs: Date.now() - started,
913
+ couldNotRun: { reason: 'preparation-failed', detail },
914
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
915
+ run: EMPTY_RUN,
916
+ diagnostics: [],
917
+ };
918
+ }
919
+ }
663
920
  // A history gate cannot vouch for history it was not given. Checked before
664
921
  // the version probe so nothing is executed for a run that cannot be honest.
665
922
  if (profileFor(gate.product).readsHistory && isShallowRepository(options.repoRoot)) {
666
- const detail = `this checkout is shallow, so the git history ${gate.product} reads is truncated: ` +
667
- 'with the default actions/checkout depth of 1 the range from the base to HEAD holds a ' +
668
- 'single grafted commit, and a secret added and then removed inside the pull request ' +
669
- 'would never be seen. Check out with fetch-depth: 0 (actions/checkout) or run ' +
923
+ const detail = `${gate.product} did not run, because this checkout is shallow and the git history it reads ` +
924
+ 'is truncated: with the default actions/checkout depth of 1 the range from the base to HEAD ' +
925
+ 'holds a single grafted commit, and a secret added and then removed inside the pull ' +
926
+ 'request would never be seen. Fix: check out with fetch-depth: 0 (actions/checkout) or run ' +
670
927
  'git fetch --unshallow, then run again. conductor does not deepen the checkout itself.';
671
928
  return {
672
929
  ...base,
@@ -682,6 +939,17 @@ function runGateInner(gate, options, started, progress) {
682
939
  };
683
940
  }
684
941
  const version = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
942
+ // A PATH binary at a different version than the run was told to expect: a
943
+ // fact for a warning and nothing else. It sits on `progress` (which `base`
944
+ // is) so every outcome from here on carries it, and no branch below reads it.
945
+ if (options.expectedVersion !== undefined &&
946
+ version !== null &&
947
+ binary.source === 'path' &&
948
+ version !== options.expectedVersion) {
949
+ Object.assign(progress, {
950
+ versionSkew: { expected: options.expectedVersion, found: version, path: binary.program },
951
+ });
952
+ }
685
953
  // The command-line floor. Only the external tools have one: the umbrella
686
954
  // writes flags they grew at a known release (gitleaks' git subcommand,
687
955
  // osv-scanner's scan source), and an older build would reject the command
@@ -692,8 +960,9 @@ function runGateInner(gate, options, started, progress) {
692
960
  if (profile.minVersion !== null &&
693
961
  version !== null &&
694
962
  !atLeastVersion(version, profile.minVersion)) {
695
- const detail = `${gate.product} ${version} is older than ${profile.minVersion}, the oldest version whose ` +
696
- `command line this umbrella speaks. Upgrade it to ${profile.minVersion} or later.`;
963
+ const detail = `${gate.product} did not run: the installed ${version} is older than ${profile.minVersion}, ` +
964
+ 'the oldest version whose command line this umbrella speaks. ' +
965
+ `Fix: upgrade it to ${profile.minVersion} or later.`;
697
966
  return {
698
967
  ...base,
699
968
  productVersion: version,
@@ -707,9 +976,8 @@ function runGateInner(gate, options, started, progress) {
707
976
  }
708
977
  // AFTER the version probe and BEFORE the command line is built, because the
709
978
  // decision reads the version. That ordering is the whole capability gate:
710
- // an intent-guard older than 1.4.0 must not be handed a flag it would
711
- // reject, and a gate IN the table whose version could not be read is
712
- // refused rather than run outside the boundary.
979
+ // a gate IN the table whose version is below its minimum, or could not be
980
+ // read, is refused rather than run outside the boundary.
713
981
  const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version);
714
982
  if (trustBase !== undefined && trustBase.refused !== null) {
715
983
  return {
@@ -722,23 +990,42 @@ function runGateInner(gate, options, started, progress) {
722
990
  // a decision about, and this is the umbrella saying it could not
723
991
  // establish that the gate was inside the boundary.
724
992
  //
725
- // Reachable now only as a PACKAGING problem, not as an attack: the
726
- // program check above runs first, and with its directory-subtree rule a
727
- // pull request can no longer put a program here whose version probe it
728
- // controls. Before that rule it could, through the wrapper shape: a
729
- // head-replaced inner script exiting 3 on --version landed exactly
730
- // here, with enforce false and exit 0. A packaging quirk that
731
- // fails a build loudly is the better failure: the alternative is a
732
- // boundary that quietly downgrades itself on the runs where something
733
- // is already wrong, which is the shape of every bug in this file.
993
+ // Reachable as an installation problem (a gate older than its minimum)
994
+ // or a packaging one (a version that does not read), not as an attack:
995
+ // the program check above runs first, and with its directory-subtree
996
+ // rule a pull request cannot put a program here whose version probe it
997
+ // controls. A build that fails loudly is the better failure: the
998
+ // alternative is a boundary that quietly downgrades itself.
734
999
  enforce: true,
735
1000
  trustBase,
736
- couldNotRun: { reason: 'trust-base-unverified', detail: trustBase.refused },
1001
+ // decideTrustBase refuses for exactly two reasons: a version it could
1002
+ // not read, and a version it read that is below the minimum.
1003
+ couldNotRun: {
1004
+ reason: version === null ? 'trust-base-unverified' : 'gate-version-unsupported',
1005
+ detail: trustBase.refused,
1006
+ },
737
1007
  findings: [normalizeFailedGate(gate.role, gate.product, trustBase.refused)],
738
1008
  run: EMPTY_RUN,
739
1009
  diagnostics: [],
740
1010
  };
741
1011
  }
1012
+ const channel = intentChangeChannel(gate, options.intent, version);
1013
+ if (channel.kind === 'refused') {
1014
+ return {
1015
+ ...base,
1016
+ productVersion: version,
1017
+ binary,
1018
+ durationMs: Date.now() - started,
1019
+ // Enforced under a trust base: the gate produced nothing for
1020
+ // enforce: false to be a decision about.
1021
+ enforce: options.trustBase !== undefined ? true : gate.enforce,
1022
+ ...(trustBase === undefined ? {} : { trustBase }),
1023
+ couldNotRun: { reason: 'preparation-failed', detail: channel.detail },
1024
+ findings: [normalizeFailedGate(gate.role, gate.product, channel.detail)],
1025
+ run: EMPTY_RUN,
1026
+ diagnostics: [],
1027
+ };
1028
+ }
742
1029
  // A directory of the runner's own for an external tool's working files: the
743
1030
  // report gitleaks writes. Made under the caller's temporary root when there
744
1031
  // is one, and removed whatever happens, so a run leaves nothing behind. The
@@ -787,14 +1074,20 @@ function spawnAndRead(ctx) {
787
1074
  // removing or renaming one is visible in the diff, so there is nothing for
788
1075
  // a base-ref read to protect. A listing that fails is not "no lockfiles".
789
1076
  const nestedProposals = [];
790
- if (profile.lockfileNames !== null) {
791
- const names = new Set(profile.lockfileNames);
792
- const listing = spawnSync('git', ['ls-files', '-z'], {
793
- cwd: options.repoRoot,
794
- encoding: 'utf8',
795
- maxBuffer: 64 * 1024 * 1024,
796
- });
797
- if (listing.status !== 0 || typeof listing.stdout !== 'string') {
1077
+ // What the osv gate's selection said beside the list it handed over: the
1078
+ // umbrella's own diagnostics (a requirements file left out, or scanned
1079
+ // under the ratchet, a passthrough option dropped) and the per-file run
1080
+ // notes. Carried onto every outcome from here on that reports a scan.
1081
+ let selection = null;
1082
+ const selectionDiagnostics = [];
1083
+ // Tracked manifests this gate was NOT handed, when it was handed others
1084
+ // (review of 1b.2, item 5): a run note, so a Podfile.lock beside a scanned
1085
+ // mix.lock is named without pushing a clean run off its one-line summary.
1086
+ // The nothing-to-scan branch below names them in its own diagnostic.
1087
+ let unreadNote = null;
1088
+ if (profile.lockfileMatcher !== null) {
1089
+ const listing = runGit(options.repoRoot, ['ls-files', '-z'], { maxBuffer: 64 * 1024 * 1024 });
1090
+ if (listing.error !== undefined || listing.status !== 0) {
798
1091
  const detail = `the repository's tracked files could not be listed, so ${gate.product} had no ` +
799
1092
  'lockfiles to be handed.';
800
1093
  return {
@@ -811,17 +1104,49 @@ function spawnAndRead(ctx) {
811
1104
  }
812
1105
  const tracked = listing.stdout.split('\0').filter((file) => file !== '');
813
1106
  if (decidedRef !== undefined && profile.configFile !== null) {
814
- nestedProposals.push(...nestedConfigProposals(options.repoRoot, decidedRef, tracked, profile.configFile));
1107
+ try {
1108
+ nestedProposals.push(...nestedConfigProposals(options.repoRoot, decidedRef, tracked, profile.configFile));
1109
+ }
1110
+ catch (err) {
1111
+ if (!(err instanceof ExternalConfigError)) {
1112
+ throw err;
1113
+ }
1114
+ return {
1115
+ ...base,
1116
+ productVersion: version,
1117
+ binary,
1118
+ durationMs: Date.now() - started,
1119
+ ...(trustBase === undefined ? {} : { trustBase }),
1120
+ couldNotRun: { reason: 'preparation-failed', detail: err.message },
1121
+ findings: [normalizeFailedGate(gate.role, gate.product, err.message)],
1122
+ run: EMPTY_RUN,
1123
+ diagnostics: [],
1124
+ };
1125
+ }
1126
+ }
1127
+ // The pin check reads the head copies on disk and, on a pull request, the
1128
+ // base copies through the one reader; both are selection, not verdicts.
1129
+ selection = selectOsvInputs({
1130
+ repoRoot: options.repoRoot,
1131
+ tracked,
1132
+ ...(decidedRef === undefined ? {} : { decidedRef }),
1133
+ });
1134
+ external.lockfiles = selection.handed;
1135
+ selectionDiagnostics.push(...selection.diagnostics);
1136
+ if (decidedRef !== undefined) {
1137
+ selectionDiagnostics.push(...noLongerScanned(options.repoRoot, decidedRef, new Set(tracked)));
1138
+ }
1139
+ if (external.lockfiles.length > 0) {
1140
+ const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
1141
+ unreadNote = unread === null ? null : { code: 'conductor/manifests-not-handed', message: unread };
815
1142
  }
816
- external.lockfiles = tracked
817
- // Never a vendored copy under node_modules: that is a dependency's own
818
- // lockfile, not a statement about what this repository resolves.
819
- .filter((file) => !file.split('/').includes('node_modules'))
820
- .filter((file) => names.has(path.posix.basename(file)))
821
- .sort();
822
1143
  if (external.lockfiles.length === 0) {
823
1144
  // Nothing to scan, reported the same way as osv-scanner's own 128 below,
824
- // without spawning it.
1145
+ // without spawning it. The verdict is unchanged (clean); what changes is
1146
+ // what is said: which requirements files the pin check left out, and
1147
+ // which tracked manifests were not handed to this scanner.
1148
+ const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
1149
+ const cleanBecause = 'the verdict is clean because there was nothing to read, not because a scan found nothing.';
825
1150
  return {
826
1151
  ...base,
827
1152
  productVersion: version,
@@ -833,13 +1158,21 @@ function spawnAndRead(ctx) {
833
1158
  findings: [],
834
1159
  run: EMPTY_RUN,
835
1160
  diagnostics: [
1161
+ ...selectionDiagnostics,
836
1162
  {
837
1163
  code: 'conductor/nothing-to-scan',
838
- message: `${gate.product} found nothing to scan (no tracked lockfile); treated as clean.`,
1164
+ message: (selection.notScanned.length > 0
1165
+ ? `${nothingScannableMessage(selection.notScanned)} T${cleanBecause.slice(1)}`
1166
+ : `${gate.product} read no lockfile, so nothing was scanned; ${cleanBecause}`) +
1167
+ (unread === null ? '' : ` ${unread}`),
839
1168
  },
840
1169
  ],
841
1170
  };
842
1171
  }
1172
+ external.noResolve = external.lockfiles.some((file) => osvLockfileKind(path.posix.basename(file)) === 'requirements');
1173
+ if (external.noResolve && 'no-resolve' in gate.options) {
1174
+ selectionDiagnostics.push({ code: 'conductor/option-overridden', message: NO_RESOLVE_OVERRIDDEN });
1175
+ }
843
1176
  }
844
1177
  // On a pull request, the tool's config and ignore file come from the base
845
1178
  // ref (or a neutral stand-in), never from the head it would otherwise
@@ -897,11 +1230,8 @@ function spawnAndRead(ctx) {
897
1230
  }
898
1231
  }
899
1232
  if (profile.ignoreFile?.alsoLoadedFromScanRoot === true) {
900
- const gitDir = spawnSync('git', ['rev-parse', '--absolute-git-dir'], {
901
- cwd: options.repoRoot,
902
- encoding: 'utf8',
903
- });
904
- const resolved = typeof gitDir.stdout === 'string' ? gitDir.stdout.trim() : '';
1233
+ const gitDir = runGit(options.repoRoot, ['rev-parse', '--absolute-git-dir']);
1234
+ const resolved = gitDir.stdout.trim();
905
1235
  if (gitDir.status !== 0 || resolved === '') {
906
1236
  // No git directory means no history to scan and nowhere safe to scan
907
1237
  // it from. Not a clean result.
@@ -925,9 +1255,13 @@ function spawnAndRead(ctx) {
925
1255
  const trustBaseOut = trustBase === undefined || configProposals.length === 0
926
1256
  ? trustBase
927
1257
  : { ...trustBase, proposals: [...trustBase.proposals, ...configProposals] };
1258
+ // Decided again here from the same inputs rather than threaded through:
1259
+ // intentChangeChannel is pure, and runGateInner already returned on the one
1260
+ // outcome that does not spawn.
1261
+ const channel = intentChangeChannel(gate, options.intent, version);
928
1262
  const argv = [
929
1263
  ...binary.argvPrefix,
930
- ...gateArgs(gate, options.staged, options.intent, decidedRef, external),
1264
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, external, channel.kind === 'base' ? channel.ref : undefined),
931
1265
  ];
932
1266
  const child = spawnSync(binary.command, argv, {
933
1267
  cwd: spawnCwd,
@@ -954,8 +1288,7 @@ function spawnAndRead(ctx) {
954
1288
  // Carried on every return path below, the failures included: WHETHER
955
1289
  // this gate was in pull-request mode is exactly as interesting when it
956
1290
  // could not run as when it could, and the withheld reason is the only
957
- // place a report can say a gate read its own rules out of the tree under
958
- // judgment.
1291
+ // place a report can say a gate was not handed the base ref.
959
1292
  ...(trustBaseOut === undefined ? {} : { trustBase: trustBaseOut }),
960
1293
  };
961
1294
  // Keep the backstop's view current, so an unexpected throw below still
@@ -979,13 +1312,28 @@ function spawnAndRead(ctx) {
979
1312
  // request in a docs-only repository; read as a verdict it would claim a
980
1313
  // scan that did not happen. So it is clean, and the report says why.
981
1314
  if (exitCode !== null && profile.exit.nothingToScan.includes(exitCode)) {
1315
+ const handedAll = external.lockfiles ?? [];
982
1316
  return {
983
1317
  ...withRun,
984
1318
  exitCode: 0,
985
1319
  couldNotRun: null,
986
1320
  findings: [],
987
- run: EMPTY_RUN,
1321
+ // Every handed lockfile parsed to nothing: `packages-read 0` is the
1322
+ // marker that this gate read NOTHING (the verdict token's
1323
+ // nothing-checked rule reads it), which the partial-empty note further
1324
+ // down shares a diagnostic code with but never carries.
1325
+ run: handedAll.length === 0
1326
+ ? EMPTY_RUN
1327
+ : {
1328
+ ...EMPTY_RUN,
1329
+ diagnostics: unreadNote === null ? [] : [unreadNote],
1330
+ details: {
1331
+ lockfiles: describeLockfiles(handedAll, new Set(handedAll)),
1332
+ 'packages-read': 0,
1333
+ },
1334
+ },
988
1335
  diagnostics: [
1336
+ ...selectionDiagnostics,
989
1337
  // When lockfiles WERE handed over, this exit means they parsed to no
990
1338
  // packages at all, which is different news from "no lockfile": a
991
1339
  // lockfile the tool could not read anything from deserves a look.
@@ -997,7 +1345,8 @@ function spawnAndRead(ctx) {
997
1345
  }
998
1346
  : {
999
1347
  code: 'conductor/nothing-to-scan',
1000
- message: `${gate.product} found nothing to scan (exit ${exitCode}); treated as clean.`,
1348
+ message: `${gate.product} read no lockfile (exit ${exitCode}), so nothing was scanned; the ` +
1349
+ `verdict is clean because there was nothing to read, not because a scan found nothing.`,
1001
1350
  },
1002
1351
  ],
1003
1352
  };
@@ -1012,10 +1361,20 @@ function spawnAndRead(ctx) {
1012
1361
  const detail = exitCode === null
1013
1362
  ? 'the gate did not exit normally (killed, or timed out).'
1014
1363
  : `the gate exited ${exitCode}, which it uses for "could not run".`;
1364
+ // WHY, in the gate's own words, when it said. Read here and nowhere
1365
+ // earlier: the exit code has already been judged above, and this only
1366
+ // annotates the result. It never reads stdout for a verdict.
1367
+ const gateSaid = exitCode === null
1368
+ ? null
1369
+ : gateStatedReason(withRun.stderr, child.stdout, profile.output.kind === 'stdout');
1015
1370
  return {
1016
1371
  ...withRun,
1017
1372
  exitCode,
1018
- couldNotRun: { reason: 'gate-error', detail },
1373
+ couldNotRun: {
1374
+ reason: 'gate-error',
1375
+ detail,
1376
+ ...(gateSaid === null ? {} : { gateSaid }),
1377
+ },
1019
1378
  // The child's own stderr goes with it. The text report prints it from
1020
1379
  // the outcome, but a gate that could not run gets no SARIF run of its
1021
1380
  // own, so this finding is the only place a published log can say what
@@ -1101,13 +1460,108 @@ function spawnAndRead(ctx) {
1101
1460
  online: argv.includes('--online'),
1102
1461
  lockfiles: external.lockfiles ?? [],
1103
1462
  });
1463
+ // The base comparison (osv design, section 3.1): only on a decided trust
1464
+ // base, only when the head run exited blocked and produced a finding. A
1465
+ // clean head, nothing to scan, empty lockfiles and every could-not-run
1466
+ // returned before this, so none of them costs anything new. Its own
1467
+ // try: a comparison that throws labels every finding introduced and is
1468
+ // never a could-not-run, unlike the normalizer failure the catch below
1469
+ // is for.
1470
+ let findings = normalized.findings;
1471
+ let baseComparison;
1472
+ const comparisonDiagnostics = [];
1473
+ if (gate.product === 'osv-scanner' &&
1474
+ decidedRef !== undefined &&
1475
+ workDir !== null &&
1476
+ blocked &&
1477
+ findings.length > 0) {
1478
+ const compareArgs = {
1479
+ repoRoot: options.repoRoot,
1480
+ ref: decidedRef,
1481
+ workDir,
1482
+ policy: gate.presentOnBase ?? 'block',
1483
+ version,
1484
+ headFindings: findings,
1485
+ headLockfiles: external.lockfiles ?? [],
1486
+ closures: selection?.closures ?? new Map(),
1487
+ otherVerdicts: normalized.otherVerdicts ?? [],
1488
+ headArgv: argv,
1489
+ baseArgv: (copies) => [
1490
+ ...binary.argvPrefix,
1491
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: copies }),
1492
+ ],
1493
+ spawn: (baseArgv, cwd) => {
1494
+ const baseChild = spawnSync(binary.command, [...baseArgv], {
1495
+ cwd,
1496
+ encoding: 'utf8',
1497
+ timeout: timeoutMs,
1498
+ maxBuffer: 64 * 1024 * 1024,
1499
+ });
1500
+ return { status: baseChild.status, stdout: baseChild.stdout ?? '', error: baseChild.error };
1501
+ },
1502
+ rootSpellings,
1503
+ };
1504
+ let compared;
1505
+ try {
1506
+ compared = compareWithBase(compareArgs);
1507
+ }
1508
+ catch (err) {
1509
+ compared = comparisonFailed(compareArgs, `the comparison failed (${messageOf(err)})`);
1510
+ }
1511
+ findings = compared.findings;
1512
+ baseComparison = compared.comparison;
1513
+ comparisonDiagnostics.push(...compared.diagnostics);
1514
+ }
1515
+ // A handed lockfile osv-scanner read no packages from, while it read
1516
+ // packages from another (audit finding F2). Exit 128 above covers only
1517
+ // the all-empty case; this is the rest, named on the coverage line and
1518
+ // in a diagnostic, so an emptied lockfile's advisories never vanish
1519
+ // without a word. Annotation only: the verdict is osv-scanner's.
1520
+ const emptied = gate.product === 'osv-scanner'
1521
+ ? emptiedLockfiles(withRun.stderr, external.lockfiles ?? [], spawnCwd)
1522
+ : [];
1523
+ const emptyDiagnostics = emptied.length === 0
1524
+ ? []
1525
+ : [
1526
+ {
1527
+ code: 'conductor/lockfiles-empty',
1528
+ message: `${gate.product} read no packages from ${emptied.join(', ')} while it read packages ` +
1529
+ 'from the other lockfiles, so nothing in the named file(s) was checked. A lockfile ' +
1530
+ 'emptied in this change hides every advisory it carried; look at its diff.',
1531
+ },
1532
+ ];
1533
+ const run = selection === null
1534
+ ? normalized.run
1535
+ : {
1536
+ ...normalized.run,
1537
+ diagnostics: [
1538
+ ...normalized.run.diagnostics,
1539
+ ...selection.notes,
1540
+ ...(unreadNote === null ? [] : [unreadNote]),
1541
+ ],
1542
+ details: {
1543
+ ...normalized.run.details,
1544
+ ...(emptied.length === 0
1545
+ ? {}
1546
+ : { lockfiles: describeLockfiles(external.lockfiles ?? [], new Set(emptied)) }),
1547
+ ...(selection.notScanned.length === 0
1548
+ ? {}
1549
+ : { 'not-scanned': notScannedDetail(selection.notScanned) }),
1550
+ },
1551
+ };
1104
1552
  return {
1105
1553
  ...withRun,
1106
1554
  exitCode,
1107
1555
  couldNotRun: null,
1108
- findings: normalized.findings,
1109
- run: normalized.run,
1110
- diagnostics: normalized.diagnostics,
1556
+ findings,
1557
+ run,
1558
+ diagnostics: [
1559
+ ...normalized.diagnostics,
1560
+ ...selectionDiagnostics,
1561
+ ...emptyDiagnostics,
1562
+ ...comparisonDiagnostics,
1563
+ ],
1564
+ ...(baseComparison === undefined ? {} : { baseComparison }),
1111
1565
  // The gate's own answer about the control inputs, folded onto the
1112
1566
  // decision the umbrella made before spawning it. A gate that was NOT
1113
1567
  // put into pull-request mode reports no proposals, and its trustBase