@vaultcompass/conductor 0.8.1 → 0.10.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.
@@ -23,10 +23,13 @@ import { tmpdir } from 'node:os';
23
23
  import path from 'node:path';
24
24
  import { runGit } from './git.js';
25
25
  import { NormalizeError } from './envelope.js';
26
- 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';
27
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';
28
30
  import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals, } from './external-config.js';
29
- import { profileFor } from './products.js';
31
+ import { osvLockfileKind, profileFor } from './products.js';
32
+ import { unreadManifestsNote } from './unread-manifests.js';
30
33
  import { atLeastVersion, refuseHeadControlledProgram } from './trust-base.js';
31
34
  import { ResolveError, candidateNames, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
32
35
  /** The longest excerpt of a gate's own reason that is carried. */
@@ -69,8 +72,8 @@ export function breakWorkflowMarkers(text) {
69
72
  }
70
73
  /**
71
74
  * The could-not-run reasons that are conductor's OWN decision, made before
72
- * the gate was spawned (or instead of spawning it), as opposed to something
73
- * the gate itself said or did.
75
+ * the gate was spawned (or instead of spawning it), or the umbrella stopping
76
+ * it, as opposed to something the gate itself said or did.
74
77
  */
75
78
  export const CONDUCTOR_OWN_REASONS = new Set([
76
79
  'preparation-failed',
@@ -78,7 +81,101 @@ export const CONDUCTOR_OWN_REASONS = new Set([
78
81
  'gate-program-refused',
79
82
  'gate-version-unsupported',
80
83
  'history-shallow',
84
+ 'timed-out',
81
85
  ]);
86
+ /**
87
+ * A gate's time limit, and where it came from. THE ONE PLACE the precedence
88
+ * is written: the test hook (`RunGateOptions.timeoutMs`, which no CLI path
89
+ * sets), then the policy's `timeout-seconds`, then the product's default.
90
+ * runGate and the intent gate's preparation in run.ts both call this, so the
91
+ * two cannot disagree about a gate's limit.
92
+ */
93
+ export function resolveTimeLimit(gate, override) {
94
+ if (override !== undefined) {
95
+ return { ms: override, source: 'override' };
96
+ }
97
+ if (gate.timeoutSeconds !== undefined) {
98
+ return { ms: gate.timeoutSeconds * 1000, source: 'policy' };
99
+ }
100
+ return { ms: profileFor(gate.product).timeoutMs, source: 'default' };
101
+ }
102
+ /**
103
+ * Classifies a spawnSync result that carries an error. PURE, so it is tested
104
+ * on hand-built results.
105
+ *
106
+ * THE ERROR CODE ALONE decides it. ETIMEDOUT is timed-out and nothing else
107
+ * is. No status or signal condition belongs here: a child that traps SIGTERM,
108
+ * or ignores it and exits on its own, comes back with status 0 (or its
109
+ * blocked code) and signal null, and ENOBUFS arrives with the same SIGTERM a
110
+ * timeout does. The signal is recorded for the report and never classifies.
111
+ */
112
+ export function spawnFailure(child) {
113
+ if (child.error === undefined) {
114
+ return null;
115
+ }
116
+ if (child.error.code === 'ETIMEDOUT') {
117
+ return { reason: 'timed-out', signal: child.signal ?? null };
118
+ }
119
+ return { reason: 'spawn-failed', message: child.error.message };
120
+ }
121
+ /** "(the default for this gate)", or where the policy value came from. */
122
+ function limitSourcePhrase(gate, source, trustBase) {
123
+ if (source === 'policy') {
124
+ return trustBase === undefined
125
+ ? `gates.${gate.role}.timeout-seconds`
126
+ : `gates.${gate.role}.timeout-seconds on ${trustBase}`;
127
+ }
128
+ return source === 'default' ? 'the default for this gate' : 'set by the caller';
129
+ }
130
+ /**
131
+ * The note for `options.timeout` on the secrets-history gate, which is
132
+ * gitleaks' own --timeout and not conductor's limit. Null when the key is not
133
+ * set or the gate is not gitleaks.
134
+ */
135
+ function gateOwnTimeoutNote(gate, limit, trustBase) {
136
+ if (gate.product !== 'gitleaks' || gate.options.timeout === undefined) {
137
+ return null;
138
+ }
139
+ return (`options.timeout is gitleaks' own --timeout (${String(gate.options.timeout)} s); conductor stops the ` +
140
+ `gate at ${Math.round(limit.ms / 1000)} s (${limitSourcePhrase(gate, limit.source, trustBase)}).`);
141
+ }
142
+ /** The could-not-run detail for a gate stopped at its limit, by step. */
143
+ function timedOutDetail(gate, step, limit, elapsedMs, trustBase) {
144
+ const limitSeconds = Math.round(limit.ms / 1000);
145
+ const elapsedSeconds = Math.round(elapsedMs / 1000);
146
+ const where = limitSourcePhrase(gate, limit.source, trustBase);
147
+ const own = gateOwnTimeoutNote(gate, limit, trustBase);
148
+ const remedies = profileFor(gate.product).timeoutRemedies(gate.role);
149
+ if (step === 'version-probe') {
150
+ return (`the version probe of ${gate.product} was stopped at ${limitSeconds} s (${where}), so the gate ` +
151
+ 'was not run and nothing was checked by it.');
152
+ }
153
+ const what = step === 'scan'
154
+ ? `${gate.product} was stopped after ${elapsedSeconds} s, at its ${limitSeconds} s limit (${where}), ` +
155
+ 'so nothing was checked by it.'
156
+ : `the intent gate's ${step} step was stopped after ${elapsedSeconds} s, at its ${limitSeconds} s ` +
157
+ `limit (${where}), so the gate was not run and nothing was checked by it.`;
158
+ return `${what} ${remedies}${own === null ? '' : ` ${own}`}`;
159
+ }
160
+ function timedOutRecord(step, limit, elapsedMs, signal) {
161
+ return {
162
+ step,
163
+ limitSeconds: Math.round(limit.ms / 1000),
164
+ elapsedSeconds: Math.round(elapsedMs / 1000),
165
+ limitSource: limit.source,
166
+ signal,
167
+ };
168
+ }
169
+ /** The `conductor/gate-failed` finding for a timed-out gate, with the timing in its details. */
170
+ function timedOutFinding(gate, detail, timedOut, stderr) {
171
+ return normalizeFailedGate(gate.role, gate.product, detail, stderr, {
172
+ timedOut: {
173
+ limitSeconds: timedOut.limitSeconds,
174
+ elapsedSeconds: timedOut.elapsedSeconds,
175
+ limitSource: timedOut.limitSource,
176
+ },
177
+ });
178
+ }
82
179
  /**
83
180
  * conductor's own reason for a could-not-run, as a job-log excerpt: cleaned,
84
181
  * one line, capped and with double quotes replaced, exactly like a gate's
@@ -95,25 +192,89 @@ export function conductorStatedReason(detail) {
95
192
  export function cleanOutputLine(raw) {
96
193
  return breakWorkflowMarkers(raw.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' '));
97
194
  }
195
+ /** A zerolog line at one level: gitleaks' "<time> ERR ..." shape. */
196
+ const ZEROLOG_ERR = /^\S+\s+ERR\s/;
197
+ const ZEROLOG_WRN = /^\S+\s+WRN\s/;
198
+ function plainLine(raw) {
199
+ return raw.replace(/[^\x20-\x7e]/g, ' ').replace(/\s+/g, ' ').trim();
200
+ }
201
+ /**
202
+ * The stderr half of the stated-reason rule: the line a gate marks as its
203
+ * failure, else the first line that is not informational, else nothing.
204
+ *
205
+ * 1. Lines are split after stripAnsi. Whitespace tests (blank, indented)
206
+ * are made there, before sanitizing, because a colour code can come
207
+ * before the indentation; markers are matched on the sanitized text, so
208
+ * a leading emoji or colour code does not hide one.
209
+ * 2. Informational lines are never chosen: a `note:` line and every
210
+ * following indented line (a BLANK line ends the note block, so an
211
+ * indented reason after it is not swallowed), and gitleaks' two
212
+ * rename-detection warnings.
213
+ * 3. A marker wins: the first remaining INCOMPLETE: or zerolog ERR line,
214
+ * joined with the indented lines after it, skipping blank lines, up to
215
+ * the first non-blank line that is not indented.
216
+ * 4. No marker: the first remaining line.
217
+ */
218
+ function statedReasonFromStderr(stderr) {
219
+ const lines = stripAnsi(stderr)
220
+ .split('\n')
221
+ .map((raw) => {
222
+ const blank = raw.trim() === '';
223
+ return { blank, indented: !blank && /^\s/.test(raw), text: plainLine(raw), informational: false };
224
+ });
225
+ for (let i = 0; i < lines.length; i++) {
226
+ const line = lines[i];
227
+ if (/^note:/i.test(line.text)) {
228
+ line.informational = true;
229
+ for (let j = i + 1; j < lines.length && lines[j].indented; j++) {
230
+ lines[j].informational = true;
231
+ }
232
+ }
233
+ else if (ZEROLOG_WRN.test(line.text) &&
234
+ (line.text.includes('rename detection was skipped') || line.text.includes('diff.renameLimit'))) {
235
+ line.informational = true;
236
+ }
237
+ }
238
+ const candidate = (line) => !line.blank && !line.informational && line.text !== '';
239
+ const markerAt = lines.findIndex((line) => candidate(line) && (line.text.startsWith('INCOMPLETE:') || ZEROLOG_ERR.test(line.text)));
240
+ if (markerAt >= 0) {
241
+ const block = [lines[markerAt].text];
242
+ for (let k = markerAt + 1; k < lines.length; k++) {
243
+ const next = lines[k];
244
+ if (next.blank) {
245
+ continue;
246
+ }
247
+ if (!next.indented) {
248
+ break;
249
+ }
250
+ if (next.text !== '') {
251
+ block.push(next.text);
252
+ }
253
+ }
254
+ return sanitizeGateSaid(block.join(' '));
255
+ }
256
+ const first = lines.find(candidate);
257
+ return first === undefined ? null : sanitizeGateSaid(first.text);
258
+ }
98
259
  /**
99
260
  * What a gate that exited with a non-verdict code said about why.
100
261
  *
101
262
  * TOTAL, and never a decision: the caller has already settled that this is a
102
- * could-not-run, and nothing here can change that. The first non-empty stderr
103
- * line is preferred, since that is where every gate in the family prints its
104
- * reason on exit 2 (dep-guard, intent-guard and vault-guard all do). Failing
105
- * that, stdout is parsed only for a gate whose output is JSON on stdout, and
106
- * only a string `reason` field (top level, or on `run`) is read; anything else,
107
- * including output that does not parse, is simply no excerpt.
263
+ * could-not-run, and nothing here can change that. stderr is preferred, since
264
+ * that is where every gate in the family prints its reason on exit 2
265
+ * (dep-guard, intent-guard and vault-guard all do), read by the rule in
266
+ * `statedReasonFromStderr`: the line the gate marks as the failure, never an
267
+ * informational line. Failing that, stdout is parsed only for a gate whose
268
+ * output is JSON on stdout, and only a string `reason` field (top level, or
269
+ * on `run`) is read; anything else, including output that does not parse, is
270
+ * simply no excerpt. An absent excerpt is better than quoting a warning as
271
+ * the cause; the full stderr is still printed in the text report.
108
272
  */
109
273
  export function gateStatedReason(stderr, stdout, stdoutIsJson) {
110
274
  try {
111
- const firstLine = stripAnsi(stderr)
112
- .split('\n')
113
- .map((line) => sanitizeGateSaid(line))
114
- .find((line) => line !== null);
115
- if (firstLine !== undefined && firstLine !== null) {
116
- return firstLine;
275
+ const fromStderr = statedReasonFromStderr(stderr);
276
+ if (fromStderr !== null) {
277
+ return fromStderr;
117
278
  }
118
279
  if (!stdoutIsJson || typeof stdout !== 'string' || !stdout.trimStart().startsWith('{')) {
119
280
  return null;
@@ -318,6 +479,33 @@ export function preparationFailed(gate, detail) {
318
479
  diagnostics: [],
319
480
  };
320
481
  }
482
+ /**
483
+ * The intent gate whose preparation step (import-spec or freeze) was stopped
484
+ * at the gate's time limit. Shaped like `preparationFailed`, with the
485
+ * timed-out reason, so it composes the same way; the caller decides
486
+ * `enforce` under the same rule it applies to a failed preparation.
487
+ */
488
+ export function preparationTimedOut(gate, stopped) {
489
+ const detail = timedOutDetail(gate, stopped.step, stopped.limit, stopped.elapsedMs, stopped.trustBase);
490
+ const timedOut = timedOutRecord(stopped.step, stopped.limit, stopped.elapsedMs, stopped.signal);
491
+ return {
492
+ role: gate.role,
493
+ product: gate.product,
494
+ stage: gate.stage,
495
+ enforce: gate.enforce,
496
+ productVersion: null,
497
+ argv: [],
498
+ binary: null,
499
+ exitCode: null,
500
+ durationMs: stopped.elapsedMs,
501
+ stderr: '',
502
+ timeLimit: stopped.limit,
503
+ couldNotRun: { reason: 'timed-out', detail, timedOut },
504
+ findings: [timedOutFinding(gate, detail, timedOut)],
505
+ run: EMPTY_RUN,
506
+ diagnostics: [],
507
+ };
508
+ }
321
509
  const EMPTY_RUN = {
322
510
  failOn: null,
323
511
  suppressed: 0,
@@ -542,37 +730,77 @@ intentBase) {
542
730
  case 'osv-scanner': {
543
731
  // JSON goes to stdout and everything else to stderr, so no report
544
732
  // file. No directory walk: each tracked lockfile is named with
545
- // --lockfile (the runner lists them, src/products.ts
546
- // OSV_LOCKFILE_NAMES), because osv-scanner's own walk skips anything
547
- // .gitignore matches, tracked or not. With none there is nothing to
548
- // hand over, and the runner reports that without spawning the tool.
733
+ // --lockfile (the runner lists them, src/osv-coverage.ts), because
734
+ // osv-scanner's own walk skips anything .gitignore matches, tracked or
735
+ // not. With none there is nothing to hand over, and the runner reports
736
+ // that without spawning the tool.
549
737
  if (external.lockfiles === undefined || external.lockfiles.length === 0) {
550
738
  throw new Error('osv-scanner needs at least one lockfile: with none, nothing is spawned');
551
739
  }
552
- const lockfiles = external.lockfiles.flatMap((file) => ['--lockfile', file]);
553
- return ['--format', 'json', ...config, ...lockfiles, ...passthrough];
740
+ const isRequirements = (file) => osvLockfileKind(path.basename(file)) === 'requirements';
741
+ // A requirements variant (requirements-dev.txt) is handed in the
742
+ // parse-as form, because 2.4.0 does not recognise the bare name;
743
+ // requirements.txt itself and every exact lockfile name go bare
744
+ // (npm-shrinkwrap.json is not even a valid parse-as type in 2.4.0).
745
+ // The parse-as form splits on the first colon only, so a variant's own
746
+ // path is safe; a bare path with a colon is split and exits 127, which
747
+ // is a could-not-run, never a silent skip.
748
+ const lockfiles = external.lockfiles.flatMap((file) => [
749
+ '--lockfile',
750
+ isRequirements(file) && path.basename(file) !== 'requirements.txt' ? `requirements.txt:${file}` : file,
751
+ ]);
752
+ // --no-resolve on every invocation that carries a requirements file,
753
+ // and on the base run exactly when the head run had it (section 2.4):
754
+ // without a lockfile, a resolved transitive version is the registry's
755
+ // latest, not the installed one. Not overridable: a policy no-resolve
756
+ // is dropped from such an invocation (the runner says so), because
757
+ // no-resolve: false would render --no-no-resolve, which osv rejects.
758
+ const noResolve = external.noResolve ?? external.lockfiles.some(isRequirements);
759
+ const options = { ...gate.options };
760
+ if (noResolve) {
761
+ delete options['no-resolve'];
762
+ }
763
+ // On a pull-request run, call analysis is off for every language
764
+ // unless the base policy says otherwise (section 3.3, open question 6):
765
+ // the base copies carry no source, so call analysis could hide on the
766
+ // head what the base run reports, and the comparison would then not be
767
+ // a dependency fact. Off on both runs makes the head only gain
768
+ // findings. A policy that names either key keeps its own value, on
769
+ // both runs, through the passthrough.
770
+ const callAnalysis = trustBase !== undefined && !('call-analysis' in options) && !('no-call-analysis' in options)
771
+ ? ['--no-call-analysis=all']
772
+ : [];
773
+ return [
774
+ '--format',
775
+ 'json',
776
+ ...config,
777
+ ...lockfiles,
778
+ ...(noResolve ? ['--no-resolve'] : []),
779
+ ...callAnalysis,
780
+ ...renderOptionFlags(options),
781
+ ];
554
782
  }
555
783
  }
556
784
  }
557
- /**
558
- * Asks a binary for its version.
559
- *
560
- * Never called for a binary the candidate table marks unsafe to ask: the
561
- * per-command binaries ignore --version and run the gate instead, so a
562
- * probe there would have side effects on the user's repository.
563
- */
564
785
  function probeVersion(binary, product, repoRoot, timeoutMs) {
565
786
  const spec = profileFor(product).versionProbe;
566
787
  if (binary.versionProbe === null || spec === null) {
567
- return null;
788
+ return { kind: 'unreadable' };
568
789
  }
790
+ const probeStarted = Date.now();
569
791
  const probe = spawnSync(binary.versionProbe.command, binary.versionProbe.argv, {
570
792
  cwd: repoRoot,
571
793
  encoding: 'utf8',
572
794
  timeout: timeoutMs,
573
795
  });
796
+ // FIRST, before the status: a probe that handled SIGTERM can exit 0 with a
797
+ // version on stdout, and it was still stopped at the limit.
798
+ const failure = spawnFailure(probe);
799
+ if (failure !== null && failure.reason === 'timed-out') {
800
+ return { kind: 'timed-out', elapsedMs: Date.now() - probeStarted, signal: failure.signal };
801
+ }
574
802
  if (probe.status !== 0 || typeof probe.stdout !== 'string') {
575
- return null;
803
+ return { kind: 'unreadable' };
576
804
  }
577
805
  // Take the first line and accept it only if the product's pattern matches,
578
806
  // so a future help banner does not end up in a SARIF driver's version
@@ -581,7 +809,7 @@ function probeVersion(binary, product, repoRoot, timeoutMs) {
581
809
  // a capture group that takes the number alone.
582
810
  const first = probe.stdout.trim().split('\n')[0]?.trim() ?? '';
583
811
  const match = spec.pattern.exec(first);
584
- return match === null ? null : (match[1] ?? match[0]).replace(/^v/, '');
812
+ return match === null ? { kind: 'unreadable' } : { kind: 'version', value: (match[1] ?? match[0]).replace(/^v/, '') };
585
813
  }
586
814
  /**
587
815
  * `context.blocked` is whether the gate's exit said it blocked. The npm gates
@@ -605,7 +833,7 @@ function normalizeFor(product, parsed, version, context) {
605
833
  case 'gitleaks':
606
834
  return normalizeGitleaks(parsed, version, context.blocked);
607
835
  case 'osv-scanner':
608
- return normalizeOsvScanner(parsed, version, context.blocked, context.roots, context.lockfiles);
836
+ return normalizeOsvScanner(parsed, version, context.blocked, context.roots, context.lockfiles, context.stderr);
609
837
  }
610
838
  }
611
839
  /**
@@ -762,7 +990,19 @@ function isShallowRepository(repoRoot) {
762
990
  return probe.status === 0 && probe.stdout.trim() === 'true';
763
991
  }
764
992
  function runGateInner(gate, options, started, progress) {
765
- const timeoutMs = options.timeoutMs ?? profileFor(gate.product).timeoutMs;
993
+ // Every spawn of this gate gets the FULL limit, not a share of it: the
994
+ // version probe, the scan and, on a compared pull request, osv-scanner's
995
+ // base run. Onto `progress` so every outcome from here on carries it.
996
+ const timeLimit = resolveTimeLimit(gate, options.timeoutMs);
997
+ const timeoutMs = timeLimit.ms;
998
+ Object.assign(progress, { timeLimit });
999
+ const ownOption = gateOwnTimeoutNote(gate, timeLimit, options.trustBase);
1000
+ if (ownOption !== null) {
1001
+ // Before any spawn, the way nodeModulesSkipped is, so every return path
1002
+ // from here on carries it, the gate-error of gitleaks' own deadline
1003
+ // included.
1004
+ Object.assign(progress, { gateOwnOption: ownOption });
1005
+ }
766
1006
  // ONE PLACE DECIDES WHAT PULL-REQUEST MODE IS, and it is the presence of a
767
1007
  // trust base. resolve.ts knows nothing about refs, so it is told rather than
768
1008
  // asked.
@@ -895,7 +1135,29 @@ function runGateInner(gate, options, started, progress) {
895
1135
  diagnostics: [],
896
1136
  };
897
1137
  }
898
- const version = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
1138
+ const probed = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
1139
+ if (probed.kind === 'timed-out') {
1140
+ // Stopped here, before the version floor and before decideTrustBase: a
1141
+ // timed-out probe is not an unreadable version (which on a pull request
1142
+ // would read as trust-base-unverified, a packaging problem that does not
1143
+ // exist), and a local run does not go on to scan with the version
1144
+ // unknown. Enforced under a trust base, like trust-base-unverified: the
1145
+ // gate could not be placed inside the boundary.
1146
+ const detail = timedOutDetail(gate, 'version-probe', timeLimit, probed.elapsedMs, options.trustBase);
1147
+ const timedOut = timedOutRecord('version-probe', timeLimit, probed.elapsedMs, probed.signal);
1148
+ return {
1149
+ ...base,
1150
+ binary,
1151
+ enforce: options.trustBase !== undefined ? true : gate.enforce,
1152
+ durationMs: Date.now() - started,
1153
+ exitCode: null,
1154
+ couldNotRun: { reason: 'timed-out', detail, timedOut },
1155
+ findings: [timedOutFinding(gate, detail, timedOut)],
1156
+ run: EMPTY_RUN,
1157
+ diagnostics: [],
1158
+ };
1159
+ }
1160
+ const version = probed.kind === 'version' ? probed.value : null;
899
1161
  // A PATH binary at a different version than the run was told to expect: a
900
1162
  // fact for a warning and nothing else. It sits on `progress` (which `base`
901
1163
  // is) so every outcome from here on carries it, and no branch below reads it.
@@ -1003,7 +1265,7 @@ function runGateInner(gate, options, started, progress) {
1003
1265
  version,
1004
1266
  trustBase,
1005
1267
  profile,
1006
- timeoutMs,
1268
+ timeLimit,
1007
1269
  workDir,
1008
1270
  });
1009
1271
  }
@@ -1019,7 +1281,8 @@ function stripAnsi(text) {
1019
1281
  }
1020
1282
  /** Builds the command line, runs the gate, and reads what it said. */
1021
1283
  function spawnAndRead(ctx) {
1022
- const { gate, options, started, progress, base, binary, version, trustBase, profile, timeoutMs, workDir } = ctx;
1284
+ const { gate, options, started, progress, base, binary, version, trustBase, profile, timeLimit, workDir } = ctx;
1285
+ const timeoutMs = timeLimit.ms;
1023
1286
  const external = {};
1024
1287
  if (profile.output.kind === 'report-file' && workDir !== null) {
1025
1288
  external.reportPath = path.join(workDir, `${gate.product}-report${profile.output.extension}`);
@@ -1031,8 +1294,18 @@ function spawnAndRead(ctx) {
1031
1294
  // removing or renaming one is visible in the diff, so there is nothing for
1032
1295
  // a base-ref read to protect. A listing that fails is not "no lockfiles".
1033
1296
  const nestedProposals = [];
1034
- if (profile.lockfileNames !== null) {
1035
- const names = new Set(profile.lockfileNames);
1297
+ // What the osv gate's selection said beside the list it handed over: the
1298
+ // umbrella's own diagnostics (a requirements file left out, or scanned
1299
+ // under the ratchet, a passthrough option dropped) and the per-file run
1300
+ // notes. Carried onto every outcome from here on that reports a scan.
1301
+ let selection = null;
1302
+ const selectionDiagnostics = [];
1303
+ // Tracked manifests this gate was NOT handed, when it was handed others
1304
+ // (review of 1b.2, item 5): a run note, so a Podfile.lock beside a scanned
1305
+ // mix.lock is named without pushing a clean run off its one-line summary.
1306
+ // The nothing-to-scan branch below names them in its own diagnostic.
1307
+ let unreadNote = null;
1308
+ if (profile.lockfileMatcher !== null) {
1036
1309
  const listing = runGit(options.repoRoot, ['ls-files', '-z'], { maxBuffer: 64 * 1024 * 1024 });
1037
1310
  if (listing.error !== undefined || listing.status !== 0) {
1038
1311
  const detail = `the repository's tracked files could not be listed, so ${gate.product} had no ` +
@@ -1071,15 +1344,29 @@ function spawnAndRead(ctx) {
1071
1344
  };
1072
1345
  }
1073
1346
  }
1074
- external.lockfiles = tracked
1075
- // Never a vendored copy under node_modules: that is a dependency's own
1076
- // lockfile, not a statement about what this repository resolves.
1077
- .filter((file) => !file.split('/').includes('node_modules'))
1078
- .filter((file) => names.has(path.posix.basename(file)))
1079
- .sort();
1347
+ // The pin check reads the head copies on disk and, on a pull request, the
1348
+ // base copies through the one reader; both are selection, not verdicts.
1349
+ selection = selectOsvInputs({
1350
+ repoRoot: options.repoRoot,
1351
+ tracked,
1352
+ ...(decidedRef === undefined ? {} : { decidedRef }),
1353
+ });
1354
+ external.lockfiles = selection.handed;
1355
+ selectionDiagnostics.push(...selection.diagnostics);
1356
+ if (decidedRef !== undefined) {
1357
+ selectionDiagnostics.push(...noLongerScanned(options.repoRoot, decidedRef, new Set(tracked)));
1358
+ }
1359
+ if (external.lockfiles.length > 0) {
1360
+ const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
1361
+ unreadNote = unread === null ? null : { code: 'conductor/manifests-not-handed', message: unread };
1362
+ }
1080
1363
  if (external.lockfiles.length === 0) {
1081
1364
  // Nothing to scan, reported the same way as osv-scanner's own 128 below,
1082
- // without spawning it.
1365
+ // without spawning it. The verdict is unchanged (clean); what changes is
1366
+ // what is said: which requirements files the pin check left out, and
1367
+ // which tracked manifests were not handed to this scanner.
1368
+ const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
1369
+ const cleanBecause = 'the verdict is clean because there was nothing to read, not because a scan found nothing.';
1083
1370
  return {
1084
1371
  ...base,
1085
1372
  productVersion: version,
@@ -1091,13 +1378,21 @@ function spawnAndRead(ctx) {
1091
1378
  findings: [],
1092
1379
  run: EMPTY_RUN,
1093
1380
  diagnostics: [
1381
+ ...selectionDiagnostics,
1094
1382
  {
1095
1383
  code: 'conductor/nothing-to-scan',
1096
- message: `${gate.product} found nothing to scan (no tracked lockfile); treated as clean.`,
1384
+ message: (selection.notScanned.length > 0
1385
+ ? `${nothingScannableMessage(selection.notScanned)} T${cleanBecause.slice(1)}`
1386
+ : `${gate.product} read no lockfile, so nothing was scanned; ${cleanBecause}`) +
1387
+ (unread === null ? '' : ` ${unread}`),
1097
1388
  },
1098
1389
  ],
1099
1390
  };
1100
1391
  }
1392
+ external.noResolve = external.lockfiles.some((file) => osvLockfileKind(path.posix.basename(file)) === 'requirements');
1393
+ if (external.noResolve && 'no-resolve' in gate.options) {
1394
+ selectionDiagnostics.push({ code: 'conductor/option-overridden', message: NO_RESOLVE_OVERRIDDEN });
1395
+ }
1101
1396
  }
1102
1397
  // On a pull request, the tool's config and ignore file come from the base
1103
1398
  // ref (or a neutral stand-in), never from the head it would otherwise
@@ -1188,6 +1483,9 @@ function spawnAndRead(ctx) {
1188
1483
  ...binary.argvPrefix,
1189
1484
  ...gateArgs(gate, options.staged, options.intent, decidedRef, external, channel.kind === 'base' ? channel.ref : undefined),
1190
1485
  ];
1486
+ // Taken just before the call, so a timed-out message's elapsed time is the
1487
+ // scan's own and not resolution plus the version probe.
1488
+ const spawnStarted = Date.now();
1191
1489
  const child = spawnSync(binary.command, argv, {
1192
1490
  cwd: spawnCwd,
1193
1491
  encoding: 'utf8',
@@ -1219,14 +1517,34 @@ function spawnAndRead(ctx) {
1219
1517
  // Keep the backstop's view current, so an unexpected throw below still
1220
1518
  // reports which binary ran and what it printed.
1221
1519
  Object.assign(progress, withRun);
1222
- if (child.error !== undefined) {
1520
+ // THE FIRST THING READ after spawnSync returns, ahead of every status,
1521
+ // signal, report and stdout check, and it returns for every error. A child
1522
+ // stopped at the limit that handled SIGTERM can come back with status 0, or
1523
+ // its blocked code, and a complete clean report or clean JSON on stdout;
1524
+ // only this order keeps that from reading as a verdict. The outcome's
1525
+ // exitCode is null whatever child.status says: a status from a child that
1526
+ // was told to stop is not a verdict. Nothing on this path reads the report
1527
+ // file, parses stdout or calls a normalizer.
1528
+ const failure = spawnFailure(child);
1529
+ if (failure !== null) {
1530
+ if (failure.reason === 'timed-out') {
1531
+ const elapsedMs = Date.now() - spawnStarted;
1532
+ const detail = timedOutDetail(gate, 'scan', timeLimit, elapsedMs, options.trustBase);
1533
+ const timedOut = timedOutRecord('scan', timeLimit, elapsedMs, failure.signal);
1534
+ return {
1535
+ ...withRun,
1536
+ exitCode: null,
1537
+ couldNotRun: { reason: 'timed-out', detail, timedOut },
1538
+ findings: [timedOutFinding(gate, detail, timedOut, withRun.stderr)],
1539
+ run: EMPTY_RUN,
1540
+ diagnostics: [],
1541
+ };
1542
+ }
1223
1543
  return {
1224
1544
  ...withRun,
1225
1545
  exitCode: null,
1226
- couldNotRun: { reason: 'spawn-failed', detail: child.error.message },
1227
- findings: [
1228
- normalizeFailedGate(gate.role, gate.product, child.error.message, withRun.stderr),
1229
- ],
1546
+ couldNotRun: { reason: 'spawn-failed', detail: failure.message },
1547
+ findings: [normalizeFailedGate(gate.role, gate.product, failure.message, withRun.stderr)],
1230
1548
  run: EMPTY_RUN,
1231
1549
  diagnostics: [],
1232
1550
  };
@@ -1237,13 +1555,28 @@ function spawnAndRead(ctx) {
1237
1555
  // request in a docs-only repository; read as a verdict it would claim a
1238
1556
  // scan that did not happen. So it is clean, and the report says why.
1239
1557
  if (exitCode !== null && profile.exit.nothingToScan.includes(exitCode)) {
1558
+ const handedAll = external.lockfiles ?? [];
1240
1559
  return {
1241
1560
  ...withRun,
1242
1561
  exitCode: 0,
1243
1562
  couldNotRun: null,
1244
1563
  findings: [],
1245
- run: EMPTY_RUN,
1564
+ // Every handed lockfile parsed to nothing: `packages-read 0` is the
1565
+ // marker that this gate read NOTHING (the verdict token's
1566
+ // nothing-checked rule reads it), which the partial-empty note further
1567
+ // down shares a diagnostic code with but never carries.
1568
+ run: handedAll.length === 0
1569
+ ? EMPTY_RUN
1570
+ : {
1571
+ ...EMPTY_RUN,
1572
+ diagnostics: unreadNote === null ? [] : [unreadNote],
1573
+ details: {
1574
+ lockfiles: describeLockfiles(handedAll, new Set(handedAll)),
1575
+ 'packages-read': 0,
1576
+ },
1577
+ },
1246
1578
  diagnostics: [
1579
+ ...selectionDiagnostics,
1247
1580
  // When lockfiles WERE handed over, this exit means they parsed to no
1248
1581
  // packages at all, which is different news from "no lockfile": a
1249
1582
  // lockfile the tool could not read anything from deserves a look.
@@ -1255,7 +1588,8 @@ function spawnAndRead(ctx) {
1255
1588
  }
1256
1589
  : {
1257
1590
  code: 'conductor/nothing-to-scan',
1258
- message: `${gate.product} found nothing to scan (exit ${exitCode}); treated as clean.`,
1591
+ message: `${gate.product} read no lockfile (exit ${exitCode}), so nothing was scanned; the ` +
1592
+ `verdict is clean because there was nothing to read, not because a scan found nothing.`,
1259
1593
  },
1260
1594
  ],
1261
1595
  };
@@ -1263,12 +1597,13 @@ function spawnAndRead(ctx) {
1263
1597
  // The profile says which exits are verdicts. For the npm gates that is 0
1264
1598
  // and 1, exactly as before profiles existed: dep-guard's 2 means "could not
1265
1599
  // run the checks at all" and it prints no JSON. gitleaks is handed
1266
- // --exit-code 3, so its 1 is left meaning an error. A signal-killed child
1267
- // or a timeout lands here too, and none of those are a clean result.
1600
+ // --exit-code 3, so its 1 is left meaning an error. A child killed by
1601
+ // something other than the umbrella lands here too (a timeout returned
1602
+ // above), and none of those are a clean result.
1268
1603
  const blocked = exitCode !== null && profile.exit.blocked.includes(exitCode);
1269
1604
  if (exitCode === null || (!blocked && !profile.exit.clean.includes(exitCode))) {
1270
1605
  const detail = exitCode === null
1271
- ? 'the gate did not exit normally (killed, or timed out).'
1606
+ ? `the gate was killed by signal ${child.signal ?? 'unknown'} before it exited.`
1272
1607
  : `the gate exited ${exitCode}, which it uses for "could not run".`;
1273
1608
  // WHY, in the gate's own words, when it said. Read here and nowhere
1274
1609
  // earlier: the exit code has already been judged above, and this only
@@ -1368,14 +1703,110 @@ function spawnAndRead(ctx) {
1368
1703
  // not off gate.options: the argv is what dep-guard was actually told.
1369
1704
  online: argv.includes('--online'),
1370
1705
  lockfiles: external.lockfiles ?? [],
1706
+ stderr: withRun.stderr,
1371
1707
  });
1708
+ // The base comparison (osv design, section 3.1): only on a decided trust
1709
+ // base, only when the head run exited blocked and produced a finding. A
1710
+ // clean head, nothing to scan, empty lockfiles and every could-not-run
1711
+ // returned before this, so none of them costs anything new. Its own
1712
+ // try: a comparison that throws labels every finding introduced and is
1713
+ // never a could-not-run, unlike the normalizer failure the catch below
1714
+ // is for.
1715
+ let findings = normalized.findings;
1716
+ let baseComparison;
1717
+ const comparisonDiagnostics = [];
1718
+ if (gate.product === 'osv-scanner' &&
1719
+ decidedRef !== undefined &&
1720
+ workDir !== null &&
1721
+ blocked &&
1722
+ findings.length > 0) {
1723
+ const compareArgs = {
1724
+ repoRoot: options.repoRoot,
1725
+ ref: decidedRef,
1726
+ workDir,
1727
+ policy: gate.presentOnBase ?? 'block',
1728
+ version,
1729
+ headFindings: findings,
1730
+ headLockfiles: external.lockfiles ?? [],
1731
+ closures: selection?.closures ?? new Map(),
1732
+ otherVerdicts: normalized.otherVerdicts ?? [],
1733
+ headArgv: argv,
1734
+ baseArgv: (copies) => [
1735
+ ...binary.argvPrefix,
1736
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: copies }),
1737
+ ],
1738
+ spawn: (baseArgv, cwd) => {
1739
+ const baseChild = spawnSync(binary.command, [...baseArgv], {
1740
+ cwd,
1741
+ encoding: 'utf8',
1742
+ timeout: timeoutMs,
1743
+ maxBuffer: 64 * 1024 * 1024,
1744
+ });
1745
+ return { status: baseChild.status, stdout: baseChild.stdout ?? '', error: baseChild.error };
1746
+ },
1747
+ rootSpellings,
1748
+ };
1749
+ let compared;
1750
+ try {
1751
+ compared = compareWithBase(compareArgs);
1752
+ }
1753
+ catch (err) {
1754
+ compared = comparisonFailed(compareArgs, `the comparison failed (${messageOf(err)})`);
1755
+ }
1756
+ findings = compared.findings;
1757
+ baseComparison = compared.comparison;
1758
+ comparisonDiagnostics.push(...compared.diagnostics);
1759
+ }
1760
+ // A handed lockfile osv-scanner read no packages from, while it read
1761
+ // packages from another (audit finding F2). Exit 128 above covers only
1762
+ // the all-empty case; this is the rest, named on the coverage line and
1763
+ // in a diagnostic, so an emptied lockfile's advisories never vanish
1764
+ // without a word. Annotation only: the verdict is osv-scanner's.
1765
+ const emptied = gate.product === 'osv-scanner'
1766
+ ? emptiedLockfiles(withRun.stderr, external.lockfiles ?? [], spawnCwd)
1767
+ : [];
1768
+ const emptyDiagnostics = emptied.length === 0
1769
+ ? []
1770
+ : [
1771
+ {
1772
+ code: 'conductor/lockfiles-empty',
1773
+ message: `${gate.product} read no packages from ${emptied.join(', ')} while it read packages ` +
1774
+ 'from the other lockfiles, so nothing in the named file(s) was checked. A lockfile ' +
1775
+ 'emptied in this change hides every advisory it carried; look at its diff.',
1776
+ },
1777
+ ];
1778
+ const run = selection === null
1779
+ ? normalized.run
1780
+ : {
1781
+ ...normalized.run,
1782
+ diagnostics: [
1783
+ ...normalized.run.diagnostics,
1784
+ ...selection.notes,
1785
+ ...(unreadNote === null ? [] : [unreadNote]),
1786
+ ],
1787
+ details: {
1788
+ ...normalized.run.details,
1789
+ ...(emptied.length === 0
1790
+ ? {}
1791
+ : { lockfiles: describeLockfiles(external.lockfiles ?? [], new Set(emptied)) }),
1792
+ ...(selection.notScanned.length === 0
1793
+ ? {}
1794
+ : { 'not-scanned': notScannedDetail(selection.notScanned) }),
1795
+ },
1796
+ };
1372
1797
  return {
1373
1798
  ...withRun,
1374
1799
  exitCode,
1375
1800
  couldNotRun: null,
1376
- findings: normalized.findings,
1377
- run: normalized.run,
1378
- diagnostics: normalized.diagnostics,
1801
+ findings,
1802
+ run,
1803
+ diagnostics: [
1804
+ ...normalized.diagnostics,
1805
+ ...selectionDiagnostics,
1806
+ ...emptyDiagnostics,
1807
+ ...comparisonDiagnostics,
1808
+ ],
1809
+ ...(baseComparison === undefined ? {} : { baseComparison }),
1379
1810
  // The gate's own answer about the control inputs, folded onto the
1380
1811
  // decision the umbrella made before spawning it. A gate that was NOT
1381
1812
  // put into pull-request mode reports no proposals, and its trustBase