@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
@@ -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
  /**
@@ -27,8 +28,12 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
27
28
  | 'gate-program-refused'
28
29
  /**
29
30
  * The installed build is older than the oldest version whose command line
30
- * the umbrella speaks (`minVersion` in src/products.ts). Only the external
31
- * tools have a floor; nothing was run beyond the version probe.
31
+ * the umbrella speaks (`minVersion` in src/products.ts, which only the
32
+ * external tools have), or, on a run with a trust base, older than the
33
+ * first version that takes its rules from the base ref
34
+ * (`TRUST_BASE_MIN_VERSION`). The gate's check was not run. For an intent
35
+ * gate with an imported contract the preparation that stages that contract
36
+ * from the base ref has already run by then.
32
37
  */
33
38
  | 'gate-version-unsupported'
34
39
  /**
@@ -48,7 +53,55 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
48
53
  export interface CouldNotRun {
49
54
  reason: CouldNotRunReason;
50
55
  detail: string;
56
+ /**
57
+ * What the gate itself said about why it could not run: a short, bounded,
58
+ * sanitised excerpt of its own stderr (first line) or, failing that, of a
59
+ * `reason` field in its JSON output. Present only when the gate exited with
60
+ * a code the umbrella does not read as a verdict and said something. It is
61
+ * information for the reader and never an input to a decision: the exit
62
+ * code and `reason` above are decided before this is looked at.
63
+ */
64
+ gateSaid?: string;
51
65
  }
66
+ /** The longest excerpt of a gate's own reason that is carried. */
67
+ export declare const GATE_SAID_MAX_CHARS = 160;
68
+ /**
69
+ * Breaks up the two character sequences a CI log reader treats as a command
70
+ * ("##[" and "::") by putting a space inside them, so gate-printed text stays
71
+ * inert in a job log. Repeated until stable, so runs such as ":::" and "###["
72
+ * are covered too.
73
+ */
74
+ export declare function breakWorkflowMarkers(text: string): string;
75
+ /**
76
+ * The could-not-run reasons that are conductor's OWN decision, made before
77
+ * the gate was spawned (or instead of spawning it), as opposed to something
78
+ * the gate itself said or did.
79
+ */
80
+ export declare const CONDUCTOR_OWN_REASONS: ReadonlySet<CouldNotRunReason>;
81
+ /**
82
+ * conductor's own reason for a could-not-run, as a job-log excerpt: cleaned,
83
+ * one line, capped and with double quotes replaced, exactly like a gate's
84
+ * stated reason. Null when there is nothing to print.
85
+ */
86
+ export declare function conductorStatedReason(detail: string): string | null;
87
+ /**
88
+ * One line of raw gate output, made safe to print: control characters (escape
89
+ * included) become spaces and workflow-command markers are broken up. The
90
+ * content is otherwise left as it was.
91
+ */
92
+ export declare function cleanOutputLine(raw: string): string;
93
+ /**
94
+ * What a gate that exited with a non-verdict code said about why.
95
+ *
96
+ * TOTAL, and never a decision: the caller has already settled that this is a
97
+ * could-not-run, and nothing here can change that. The first non-empty stderr
98
+ * line is preferred, since that is where every gate in the family prints its
99
+ * reason on exit 2 (dep-guard, intent-guard and vault-guard all do). Failing
100
+ * that, stdout is parsed only for a gate whose output is JSON on stdout, and
101
+ * only a string `reason` field (top level, or on `run`) is read; anything else,
102
+ * including output that does not parse, is simply no excerpt.
103
+ */
104
+ export declare function gateStatedReason(stderr: string, stdout: string | null | undefined, stdoutIsJson: boolean): string | null;
52
105
  /**
53
106
  * The first version of each gate that understands `--trust-base`.
54
107
  *
@@ -57,10 +110,11 @@ export interface CouldNotRun {
57
110
  * against every combination in the meantime. A product missing from this
58
111
  * table has no pull-request mode yet and is never handed the flag; a product
59
112
  * in it is handed the flag only when the installed build says it is at least
60
- * this version. Both directions matter: handing an older build a flag it does
61
- * not parse makes it exit non-zero with no JSON, which the umbrella correctly
62
- * reports as could-not-run, so a wrong guess here turns a working repository's
63
- * pull requests red rather than merely leaving a gate un-hardened.
113
+ * this version, and on a run with a trust base a build below it is
114
+ * could-not-run rather than run without the flag, since without the flag it
115
+ * would take its rules from the tree being judged. The entries are the
116
+ * minimum the umbrella requires on a pull-request run, which can be later
117
+ * than the release the flag first appeared in.
64
118
  *
65
119
  * The umbrella is deliberately NOT the place a version pin lives otherwise
66
120
  * (nothing here imports any gate's package), and this is the one exception:
@@ -68,6 +122,22 @@ export interface CouldNotRun {
68
122
  * this package has to those tools.
69
123
  */
70
124
  export declare const TRUST_BASE_MIN_VERSION: Partial<Record<Product, string>>;
125
+ /**
126
+ * The first intent-guard whose own `--base` can carry any change set: it
127
+ * reads the paths from git NUL-separated (1.8.0) and lists a moved submodule
128
+ * pointer with --ignore-submodules=none and ends the range with "--" (the
129
+ * release after 1.8.0). For a native contract on this version or later the
130
+ * runner hands the gate `--base` instead of `--paths`, so a changed path
131
+ * that `--paths` cannot carry (a comma, a backslash, edge whitespace, a
132
+ * leading "-") is judged rather than refused.
133
+ *
134
+ * It equals the intent-guard entry in `TRUST_BASE_MIN_VERSION`, so on a run
135
+ * with a trust base every intent gate that runs is new enough, and the
136
+ * `--paths` refusal for a native contract is reached only on a run without
137
+ * one (an explicit `--base`). Kept as its own constant because the two
138
+ * answer different questions and the floor may move without it.
139
+ */
140
+ export declare const INTENT_BASE_CHANNEL_MIN_VERSION = "1.8.1";
71
141
  /**
72
142
  * Pull-request mode as it applied to ONE gate.
73
143
  *
@@ -76,24 +146,27 @@ export declare const TRUST_BASE_MIN_VERSION: Partial<Record<Product, string>>;
76
146
  * from the other: whether this gate was actually put into pull-request mode,
77
147
  * and what it said about the control inputs the head proposes to change.
78
148
  *
79
- * `withheld` is the half that must never be silent. A gate the umbrella could
80
- * not put into pull-request mode read its own control inputs out of the tree
81
- * under judgment, which is the whole hole this release exists to close, and a
82
- * run where that happened must not look like a run where it did not.
149
+ * `withheld` is the half that must never be silent. A gate the umbrella did
150
+ * not put into pull-request mode was not handed the base ref, and a run where
151
+ * that happened must not look like a run where it did not.
83
152
  */
84
153
  export interface GateTrustBase {
85
154
  /** The ref the umbrella took its own policy from, and offered to this gate. */
86
155
  ref: string;
87
156
  /**
88
- * Null when the flag was passed; otherwise the reason it was not, for a
89
- * gate that was never going to be inside the boundary in the first place.
90
- * The run continues: that gate read its own control inputs from the tree
91
- * being judged, and the report says so.
157
+ * Null when the flag was passed; otherwise the reason it was not. Only two
158
+ * cases withhold: a product with no pull-request mode at all (none today,
159
+ * every product is in `TRUST_BASE_MIN_VERSION`), and an intent gate judging
160
+ * a contract imported for this run, whose project is a temporary directory
161
+ * with no repository in it (the contract itself was read from the base).
162
+ * A gate below its minimum is never withheld; it is `refused`.
92
163
  */
93
164
  withheld: string | null;
94
165
  /**
95
166
  * Set when the umbrella could not ESTABLISH that this gate would be in
96
- * pull-request mode, which is could-not-run rather than a downgrade.
167
+ * pull-request mode (its version did not read), or established that it
168
+ * would not be (its version is below the minimum), which is could-not-run
169
+ * rather than a downgrade.
97
170
  *
98
171
  * The distinction is the whole point and it is not symmetry with
99
172
  * `withheld`. A gate outside the table was never going to get the flag, so
@@ -155,6 +228,7 @@ export interface GateOutcome {
155
228
  intent?: {
156
229
  contractSource: ContractSource;
157
230
  baseRef: string | null;
231
+ note?: string;
158
232
  };
159
233
  /**
160
234
  * Present only on a pull-request run. Whether this gate was put into
@@ -172,8 +246,35 @@ export interface GateOutcome {
172
246
  * nowhere. Repository-relative because it reaches a published log.
173
247
  */
174
248
  nodeModulesSkipped?: string;
249
+ /**
250
+ * Present only when this gate was resolved from PATH, the version it
251
+ * reported differs from the one the run was told to expect (the Action's
252
+ * pin, handed over as an environment variable), and both are known. A
253
+ * statement for a warning, never an input to a decision: resolution,
254
+ * trust-base handling and the exit code are all settled without it.
255
+ */
256
+ versionSkew?: {
257
+ expected: string;
258
+ found: string;
259
+ path: string;
260
+ };
261
+ /**
262
+ * The vulnerabilities gate only, and only when a base comparison ran (a
263
+ * pull-request run whose head scan blocked with at least one finding): the
264
+ * ref, the base policy's present-on-base value, the counts, the lockfiles
265
+ * the comparison was unavailable for, and any non-advisory verdict in the
266
+ * head output. Carried here, like `enforce`, so a report and the exit
267
+ * decision (gateExitBlocks) never need the policy file.
268
+ */
269
+ baseComparison?: BaseComparison;
175
270
  }
176
271
  export interface RunGateOptions {
272
+ /**
273
+ * The version this run expects of the gate, when something says so (the
274
+ * Action passes its pin). Compared with what the PATH binary reports, for a
275
+ * warning only. Absent means no expectation, which is every local run.
276
+ */
277
+ expectedVersion?: string;
177
278
  repoRoot: string;
178
279
  staged: boolean;
179
280
  /** PATH to search. Injected so tests never depend on the machine. */
@@ -263,8 +364,19 @@ export interface ExternalArgs {
263
364
  * .gitleaksignore at its root for gitleaks to load on its own.
264
365
  */
265
366
  scanRoot?: string;
266
- /** The tracked lockfiles osv-scanner is handed, repository-relative. */
367
+ /**
368
+ * The files osv-scanner is handed: repository-relative on the head run,
369
+ * absolute copies under the work directory on the base run.
370
+ */
267
371
  lockfiles?: readonly string[];
372
+ /**
373
+ * Whether this invocation gets --no-resolve. Decided once, from the HEAD
374
+ * run's list (any requirements file), and handed to the base run as is, so
375
+ * the two command lines cannot differ in resolution mode because the base
376
+ * run scans a different subset (osv design, section 2.4). Absent means
377
+ * "decide from `lockfiles`".
378
+ */
379
+ noResolve?: boolean;
268
380
  }
269
381
  /**
270
382
  * The arguments the umbrella adds, per product.
@@ -289,7 +401,12 @@ export declare function gateArgs(gate: GatePolicy, staged: boolean, intent: Inte
289
401
  */
290
402
  trustBase?: string,
291
403
  /** Paths the runner owns for an external tool; the npm gates ignore them. */
292
- external?: ExternalArgs): string[];
404
+ external?: ExternalArgs,
405
+ /**
406
+ * For the intent gate on a prepared run: hand it this base with its own
407
+ * `--base` in place of `--paths`. Decided by `intentChangeChannel`.
408
+ */
409
+ intentBase?: string): string[];
293
410
  /**
294
411
  * Runs one gate. TOTAL: this never throws.
295
412
  *
@@ -301,3 +418,10 @@ external?: ExternalArgs): string[];
301
418
  * a finding of the umbrella's own saying so.
302
419
  */
303
420
  export declare function runGate(gate: GatePolicy, options: RunGateOptions): GateOutcome;
421
+ /**
422
+ * Whether git says the repository at `repoRoot` is shallow. Anything other
423
+ * than a clear "true" (no git, an old git that does not know the flag) is
424
+ * not shallow: those runs have their own failure paths.
425
+ */
426
+ /** The oldest git a history gate runs under on a pull-request run. */
427
+ export declare const HISTORY_GIT_FLOOR = "2.31.0";