@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.
- package/README.md +263 -77
- package/dist/cli.js +152 -30
- package/dist/envelope.d.ts +8 -0
- package/dist/exit-codes.d.ts +52 -2
- package/dist/exit-codes.js +64 -14
- package/dist/external-config.d.ts +2 -1
- package/dist/external-config.js +33 -18
- package/dist/gate-runner.d.ts +141 -17
- package/dist/gate-runner.js +537 -83
- package/dist/git.d.ts +95 -0
- package/dist/git.js +244 -0
- package/dist/init-policy.js +38 -2
- package/dist/init.js +40 -3
- package/dist/intent-base.d.ts +35 -1
- package/dist/intent-base.js +124 -64
- package/dist/intent-prepare.d.ts +33 -2
- package/dist/intent-prepare.js +443 -34
- package/dist/intent-spec.d.ts +28 -0
- package/dist/intent-spec.js +22 -5
- package/dist/normalize.d.ts +11 -0
- package/dist/normalize.js +60 -6
- package/dist/osv-baseline.d.ts +84 -0
- package/dist/osv-baseline.js +325 -0
- package/dist/osv-coverage.d.ts +80 -0
- package/dist/osv-coverage.js +223 -0
- package/dist/output-sarif.js +55 -15
- package/dist/output-text.d.ts +53 -2
- package/dist/output-text.js +287 -27
- package/dist/policy.d.ts +10 -0
- package/dist/policy.js +21 -7
- package/dist/products.d.ts +32 -10
- package/dist/products.js +73 -9
- package/dist/requirements-pin.d.ts +47 -0
- package/dist/requirements-pin.js +256 -0
- package/dist/resolve.d.ts +1 -0
- package/dist/resolve.js +1 -1
- package/dist/run.d.ts +21 -0
- package/dist/run.js +74 -15
- package/dist/trust-base.d.ts +101 -20
- package/dist/trust-base.js +219 -73
- package/dist/unread-manifests.d.ts +14 -0
- package/dist/unread-manifests.js +69 -0
- package/package.json +1 -1
- package/schema/guardrails.schema.json +4 -0
package/dist/gate-runner.d.ts
CHANGED
|
@@ -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
|
|
31
|
-
* tools have a
|
|
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
|
|
61
|
-
* not
|
|
62
|
-
*
|
|
63
|
-
*
|
|
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
|
|
80
|
-
* not put into pull-request mode
|
|
81
|
-
*
|
|
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
|
|
89
|
-
*
|
|
90
|
-
*
|
|
91
|
-
*
|
|
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
|
|
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
|
-
/**
|
|
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
|
|
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";
|