@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.
@@ -30,20 +30,70 @@
30
30
  // maximum of the children's, and that is deliberate.
31
31
  //
32
32
  // The umbrella never overrules a gate's own blocking decision. A gate that
33
- // exited non-zero produces a non-zero composed code, full stop. The
34
- // per-finding `blocking` flag can only ADD to that, never subtract: it
35
- // exists so a gate whose exit code somehow said clean while its own report
36
- // carried a blocking finding still fails the run.
33
+ // exited non-zero produces a non-zero composed code, with exactly one
34
+ // exception, below. The per-finding `blocking` flag can only ADD to that,
35
+ // never subtract: it exists so a gate whose exit code somehow said clean
36
+ // while its own report carried a blocking finding still fails the run.
37
37
  //
38
- // The ONE exception, and it is the repository's own written decision rather
39
- // than a judgment made here: a gate carrying `enforce: false` in the policy
40
- // file is left out of this composition entirely. That is the adoption ramp,
41
- // so a gate can be switched on and read for a few weeks before it is
42
- // allowed to refuse anybody's commit. It is not a downgrade: the gate still
43
- // runs, its findings keep their own levels, its blocking flags are
44
- // untouched, and both output formats say plainly that it blocked and was
45
- // not enforced. Nothing here reads a gate's output and decides to ignore
46
- // it; it reads a line somebody wrote in their own policy file.
38
+ // Two written decisions change what reaches this composition, and both are
39
+ // the repository's own lines in its policy file rather than a judgment made
40
+ // here.
41
+ //
42
+ // First, a gate carrying `enforce: false` is left out of this composition
43
+ // entirely. That is the adoption ramp, so a gate can be switched on and read
44
+ // for a few weeks before it is allowed to refuse anybody's commit. It is not
45
+ // a downgrade: the gate still runs, its findings keep their own levels, its
46
+ // blocking flags are untouched, and both output formats say plainly that it
47
+ // blocked and was not enforced. Nothing here reads a gate's output and
48
+ // decides on its own judgment to ignore it.
49
+ //
50
+ // Second, the vulnerabilities gate under `present-on-base: report` (osv
51
+ // design, section 4.3): a non-zero osv-scanner exit does not block when ALL
52
+ // of (a) to (f) in `gateExitBlocks` hold, which is a compared pull-request
53
+ // run whose every parsed finding is also on the base branch, under a key the
54
+ // BASE policy wrote, with no non-advisory verdict in the output. That is a
55
+ // set difference of two runs of the same tool, not a judgment about any one
56
+ // finding, and the findings still print with their labels.
57
+ /**
58
+ * Whether this gate's own child exit blocks the run.
59
+ *
60
+ * Every "the child exited non-zero" decision goes through here: the composed
61
+ * exit code, the verdict token's count, the verdict sentence, the
62
+ * not-enforced note and the SARIF gate-not-enforced notification. A reader
63
+ * that compares the raw exit with 0 instead would say "blocked" on a run
64
+ * that exits 0 (tests/osv-exit.test.ts holds every reader to this).
65
+ *
66
+ * False for an exit of 0 (or no child). For a non-zero exit, true unless ALL
67
+ * of these hold:
68
+ * (a) the gate is the vulnerabilities gate, osv-scanner in that role;
69
+ * (b) its base policy said present-on-base: report;
70
+ * (c) a base comparison ran (it is carried on the outcome only then);
71
+ * (d) at least one finding was parsed, since exit 1 with nothing parsed
72
+ * is a verdict this umbrella cannot read;
73
+ * (e) every finding is labelled present-on-base. Redundant by
74
+ * construction: under report an introduced finding stays blocking,
75
+ * which blocks the run through `hasBlockingFinding` whatever this
76
+ * returns. Kept so the predicate states the whole rule;
77
+ * (f) the head output carried no verdict that is not an advisory: no
78
+ * license_violations, no deprecated package, no other unmapped
79
+ * package-level field. osv-scanner exits 1 for those too, and none of
80
+ * them is a finding here.
81
+ */
82
+ export function gateExitBlocks(gate) {
83
+ if ((gate.exitCode ?? 0) === 0) {
84
+ return false;
85
+ }
86
+ const comparison = gate.baseComparison;
87
+ const reportedNotBlocking = gate.role === 'vulnerabilities' &&
88
+ gate.product === 'osv-scanner' &&
89
+ comparison !== undefined &&
90
+ comparison.policy === 'report' &&
91
+ gate.couldNotRun === null &&
92
+ gate.findings.length > 0 &&
93
+ gate.findings.every((finding) => finding.details.baseline === 'present-on-base') &&
94
+ comparison.otherVerdicts.length === 0;
95
+ return !reportedNotBlocking;
96
+ }
47
97
  export const EXIT_OK = 0;
48
98
  export const EXIT_BLOCKED = 1;
49
99
  export const EXIT_COULD_NOT_RUN = 2;
@@ -52,7 +102,7 @@ export function composeExitCode(gates) {
52
102
  if (enforced.some((gate) => gate.couldNotRun !== null)) {
53
103
  return EXIT_COULD_NOT_RUN;
54
104
  }
55
- if (enforced.some((gate) => (gate.exitCode ?? 0) !== 0 || gate.hasBlockingFinding)) {
105
+ if (enforced.some((gate) => gate.exitBlocks || gate.hasBlockingFinding)) {
56
106
  return EXIT_BLOCKED;
57
107
  }
58
108
  return EXIT_OK;
@@ -1,6 +1,7 @@
1
1
  import type { Diagnostic, Finding, RunSummary } from './envelope.js';
2
2
  import type { ContractSource, IntentPreparation } from './intent-prepare.js';
3
3
  import type { GatePolicy, GateRole, GateStage, Product } from './policy.js';
4
+ import { type BaseComparison } from './osv-baseline.js';
4
5
  import type { ResolvedBinary } from './resolve.js';
5
6
  export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing' | 'spawn-failed' | 'gate-error' | 'unparseable-output'
6
7
  /**
@@ -48,10 +49,37 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
48
49
  * inside the pull request is never seen). Never unshallowed automatically:
49
50
  * the remedy is a checkout setting, fetch-depth: 0.
50
51
  */
51
- | 'history-shallow';
52
+ | 'history-shallow'
53
+ /**
54
+ * conductor stopped the gate at its time limit (`timeout-seconds` in the
55
+ * policy, else the product's default). Decided by the spawn error code
56
+ * ETIMEDOUT alone, never by the signal or the status: a child that handled
57
+ * SIGTERM can return status 0, or its blocked code, with a clean report.
58
+ * Raised for the version probe, the scan, and the intent gate's
59
+ * preparation steps; `timedOut.step` says which spawn was stopped.
60
+ */
61
+ | 'timed-out';
62
+ /** Where a gate's time limit came from: the test hook, the policy, or the product default. */
63
+ export type TimeLimitSource = 'override' | 'policy' | 'default';
64
+ export interface TimeLimit {
65
+ ms: number;
66
+ source: TimeLimitSource;
67
+ }
68
+ /** Which of a gate's spawns was stopped at the limit. The intent gate's check is `scan`. */
69
+ export type TimedOutStep = 'version-probe' | 'scan' | 'import-spec' | 'freeze';
70
+ export interface TimedOut {
71
+ step: TimedOutStep;
72
+ limitSeconds: number;
73
+ elapsedSeconds: number;
74
+ limitSource: TimeLimitSource;
75
+ /** What spawnSync reported; null when the child handled SIGTERM and exited itself. Never used to classify. */
76
+ signal: string | null;
77
+ }
52
78
  export interface CouldNotRun {
53
79
  reason: CouldNotRunReason;
54
80
  detail: string;
81
+ /** Present only for `timed-out`. */
82
+ timedOut?: TimedOut;
55
83
  /**
56
84
  * What the gate itself said about why it could not run: a short, bounded,
57
85
  * sanitised excerpt of its own stderr (first line) or, failing that, of a
@@ -73,10 +101,41 @@ export declare const GATE_SAID_MAX_CHARS = 160;
73
101
  export declare function breakWorkflowMarkers(text: string): string;
74
102
  /**
75
103
  * The could-not-run reasons that are conductor's OWN decision, made before
76
- * the gate was spawned (or instead of spawning it), as opposed to something
77
- * the gate itself said or did.
104
+ * the gate was spawned (or instead of spawning it), or the umbrella stopping
105
+ * it, as opposed to something the gate itself said or did.
78
106
  */
79
107
  export declare const CONDUCTOR_OWN_REASONS: ReadonlySet<CouldNotRunReason>;
108
+ /**
109
+ * A gate's time limit, and where it came from. THE ONE PLACE the precedence
110
+ * is written: the test hook (`RunGateOptions.timeoutMs`, which no CLI path
111
+ * sets), then the policy's `timeout-seconds`, then the product's default.
112
+ * runGate and the intent gate's preparation in run.ts both call this, so the
113
+ * two cannot disagree about a gate's limit.
114
+ */
115
+ export declare function resolveTimeLimit(gate: GatePolicy, override: number | undefined): TimeLimit;
116
+ /** What a spawn error was: the umbrella's deadline, or anything else. */
117
+ export type SpawnFailure = {
118
+ reason: 'timed-out';
119
+ signal: string | null;
120
+ } | {
121
+ reason: 'spawn-failed';
122
+ message: string;
123
+ };
124
+ /**
125
+ * Classifies a spawnSync result that carries an error. PURE, so it is tested
126
+ * on hand-built results.
127
+ *
128
+ * THE ERROR CODE ALONE decides it. ETIMEDOUT is timed-out and nothing else
129
+ * is. No status or signal condition belongs here: a child that traps SIGTERM,
130
+ * or ignores it and exits on its own, comes back with status 0 (or its
131
+ * blocked code) and signal null, and ENOBUFS arrives with the same SIGTERM a
132
+ * timeout does. The signal is recorded for the report and never classifies.
133
+ */
134
+ export declare function spawnFailure(child: {
135
+ error?: Error | undefined;
136
+ status?: number | null;
137
+ signal?: NodeJS.Signals | string | null;
138
+ }): SpawnFailure | null;
80
139
  /**
81
140
  * conductor's own reason for a could-not-run, as a job-log excerpt: cleaned,
82
141
  * one line, capped and with double quotes replaced, exactly like a gate's
@@ -93,12 +152,15 @@ export declare function cleanOutputLine(raw: string): string;
93
152
  * What a gate that exited with a non-verdict code said about why.
94
153
  *
95
154
  * TOTAL, and never a decision: the caller has already settled that this is a
96
- * could-not-run, and nothing here can change that. The first non-empty stderr
97
- * line is preferred, since that is where every gate in the family prints its
98
- * reason on exit 2 (dep-guard, intent-guard and vault-guard all do). Failing
99
- * that, stdout is parsed only for a gate whose output is JSON on stdout, and
100
- * only a string `reason` field (top level, or on `run`) is read; anything else,
101
- * including output that does not parse, is simply no excerpt.
155
+ * could-not-run, and nothing here can change that. stderr is preferred, since
156
+ * that is where every gate in the family prints its reason on exit 2
157
+ * (dep-guard, intent-guard and vault-guard all do), read by the rule in
158
+ * `statedReasonFromStderr`: the line the gate marks as the failure, never an
159
+ * informational line. Failing that, stdout is parsed only for a gate whose
160
+ * output is JSON on stdout, and only a string `reason` field (top level, or
161
+ * on `run`) is read; anything else, including output that does not parse, is
162
+ * simply no excerpt. An absent excerpt is better than quoting a warning as
163
+ * the cause; the full stderr is still printed in the text report.
102
164
  */
103
165
  export declare function gateStatedReason(stderr: string, stdout: string | null | undefined, stdoutIsJson: boolean): string | null;
104
166
  /**
@@ -257,6 +319,30 @@ export interface GateOutcome {
257
319
  found: string;
258
320
  path: string;
259
321
  };
322
+ /**
323
+ * The vulnerabilities gate only, and only when a base comparison ran (a
324
+ * pull-request run whose head scan blocked with at least one finding): the
325
+ * ref, the base policy's present-on-base value, the counts, the lockfiles
326
+ * the comparison was unavailable for, and any non-advisory verdict in the
327
+ * head output. Carried here, like `enforce`, so a report and the exit
328
+ * decision (gateExitBlocks) never need the policy file.
329
+ */
330
+ baseComparison?: BaseComparison;
331
+ /**
332
+ * The time limit this gate ran under and where it came from, carried like
333
+ * `enforce` so the report and the timed-out message never need the policy
334
+ * file. Set on every outcome runGate builds once the limit is resolved.
335
+ */
336
+ timeLimit?: TimeLimit;
337
+ /**
338
+ * The `conductor/option-is-gate-own` note: set when the secrets-history
339
+ * gate's options carry `timeout`, which is gitleaks' own --timeout and not
340
+ * conductor's limit. On the OUTCOME rather than in `run.diagnostics`,
341
+ * because every could-not-run outcome carries an empty run, and the
342
+ * gate-error that gitleaks' own deadline produces is exactly the outcome
343
+ * that needs the note. Information only; nothing decides on it.
344
+ */
345
+ gateOwnOption?: string;
260
346
  }
261
347
  export interface RunGateOptions {
262
348
  /**
@@ -269,7 +355,10 @@ export interface RunGateOptions {
269
355
  staged: boolean;
270
356
  /** PATH to search. Injected so tests never depend on the machine. */
271
357
  pathValue: string;
272
- /** Wall-clock limit per gate. */
358
+ /**
359
+ * A test hook: the time limit for every spawn of this gate, outranking the
360
+ * policy's timeout-seconds. No CLI path sets it. See `resolveTimeLimit`.
361
+ */
273
362
  timeoutMs?: number;
274
363
  /** The contract and change set prepared for the intent gate, when there is one. */
275
364
  intent?: IntentPreparation;
@@ -307,6 +396,19 @@ export interface RunGateOptions {
307
396
  * would have to learn about.
308
397
  */
309
398
  export declare function preparationFailed(gate: GatePolicy, detail: string): GateOutcome;
399
+ /**
400
+ * The intent gate whose preparation step (import-spec or freeze) was stopped
401
+ * at the gate's time limit. Shaped like `preparationFailed`, with the
402
+ * timed-out reason, so it composes the same way; the caller decides
403
+ * `enforce` under the same rule it applies to a failed preparation.
404
+ */
405
+ export declare function preparationTimedOut(gate: GatePolicy, stopped: {
406
+ step: 'import-spec' | 'freeze';
407
+ elapsedMs: number;
408
+ signal: string | null;
409
+ limit: TimeLimit;
410
+ trustBase?: string;
411
+ }): GateOutcome;
310
412
  /**
311
413
  * EVERY program this binary would spawn, vetted against the trust base.
312
414
  *
@@ -354,8 +456,19 @@ export interface ExternalArgs {
354
456
  * .gitleaksignore at its root for gitleaks to load on its own.
355
457
  */
356
458
  scanRoot?: string;
357
- /** The tracked lockfiles osv-scanner is handed, repository-relative. */
459
+ /**
460
+ * The files osv-scanner is handed: repository-relative on the head run,
461
+ * absolute copies under the work directory on the base run.
462
+ */
358
463
  lockfiles?: readonly string[];
464
+ /**
465
+ * Whether this invocation gets --no-resolve. Decided once, from the HEAD
466
+ * run's list (any requirements file), and handed to the base run as is, so
467
+ * the two command lines cannot differ in resolution mode because the base
468
+ * run scans a different subset (osv design, section 2.4). Absent means
469
+ * "decide from `lockfiles`".
470
+ */
471
+ noResolve?: boolean;
359
472
  }
360
473
  /**
361
474
  * The arguments the umbrella adds, per product.