@vaultcompass/conductor 0.7.0 → 0.8.1

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.
@@ -27,8 +27,12 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
27
27
  | 'gate-program-refused'
28
28
  /**
29
29
  * 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.
30
+ * the umbrella speaks (`minVersion` in src/products.ts, which only the
31
+ * external tools have), or, on a run with a trust base, older than the
32
+ * first version that takes its rules from the base ref
33
+ * (`TRUST_BASE_MIN_VERSION`). The gate's check was not run. For an intent
34
+ * gate with an imported contract the preparation that stages that contract
35
+ * from the base ref has already run by then.
32
36
  */
33
37
  | 'gate-version-unsupported'
34
38
  /**
@@ -36,11 +40,67 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
36
40
  * verdict to is not there. Only a tool whose output is a report file can
37
41
  * land here.
38
42
  */
39
- | 'report-missing';
43
+ | 'report-missing'
44
+ /**
45
+ * The gate reads git history and the checkout is shallow, so the history it
46
+ * would read is truncated (at depth 1 the pull request's merge commit is
47
+ * grafted, and base..HEAD holds one commit: a secret added and removed
48
+ * inside the pull request is never seen). Never unshallowed automatically:
49
+ * the remedy is a checkout setting, fetch-depth: 0.
50
+ */
51
+ | 'history-shallow';
40
52
  export interface CouldNotRun {
41
53
  reason: CouldNotRunReason;
42
54
  detail: string;
55
+ /**
56
+ * What the gate itself said about why it could not run: a short, bounded,
57
+ * sanitised excerpt of its own stderr (first line) or, failing that, of a
58
+ * `reason` field in its JSON output. Present only when the gate exited with
59
+ * a code the umbrella does not read as a verdict and said something. It is
60
+ * information for the reader and never an input to a decision: the exit
61
+ * code and `reason` above are decided before this is looked at.
62
+ */
63
+ gateSaid?: string;
43
64
  }
65
+ /** The longest excerpt of a gate's own reason that is carried. */
66
+ export declare const GATE_SAID_MAX_CHARS = 160;
67
+ /**
68
+ * Breaks up the two character sequences a CI log reader treats as a command
69
+ * ("##[" and "::") by putting a space inside them, so gate-printed text stays
70
+ * inert in a job log. Repeated until stable, so runs such as ":::" and "###["
71
+ * are covered too.
72
+ */
73
+ export declare function breakWorkflowMarkers(text: string): string;
74
+ /**
75
+ * 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.
78
+ */
79
+ export declare const CONDUCTOR_OWN_REASONS: ReadonlySet<CouldNotRunReason>;
80
+ /**
81
+ * conductor's own reason for a could-not-run, as a job-log excerpt: cleaned,
82
+ * one line, capped and with double quotes replaced, exactly like a gate's
83
+ * stated reason. Null when there is nothing to print.
84
+ */
85
+ export declare function conductorStatedReason(detail: string): string | null;
86
+ /**
87
+ * One line of raw gate output, made safe to print: control characters (escape
88
+ * included) become spaces and workflow-command markers are broken up. The
89
+ * content is otherwise left as it was.
90
+ */
91
+ export declare function cleanOutputLine(raw: string): string;
92
+ /**
93
+ * What a gate that exited with a non-verdict code said about why.
94
+ *
95
+ * 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.
102
+ */
103
+ export declare function gateStatedReason(stderr: string, stdout: string | null | undefined, stdoutIsJson: boolean): string | null;
44
104
  /**
45
105
  * The first version of each gate that understands `--trust-base`.
46
106
  *
@@ -49,10 +109,11 @@ export interface CouldNotRun {
49
109
  * against every combination in the meantime. A product missing from this
50
110
  * table has no pull-request mode yet and is never handed the flag; a product
51
111
  * in it is handed the flag only when the installed build says it is at least
52
- * this version. Both directions matter: handing an older build a flag it does
53
- * not parse makes it exit non-zero with no JSON, which the umbrella correctly
54
- * reports as could-not-run, so a wrong guess here turns a working repository's
55
- * pull requests red rather than merely leaving a gate un-hardened.
112
+ * this version, and on a run with a trust base a build below it is
113
+ * could-not-run rather than run without the flag, since without the flag it
114
+ * would take its rules from the tree being judged. The entries are the
115
+ * minimum the umbrella requires on a pull-request run, which can be later
116
+ * than the release the flag first appeared in.
56
117
  *
57
118
  * The umbrella is deliberately NOT the place a version pin lives otherwise
58
119
  * (nothing here imports any gate's package), and this is the one exception:
@@ -60,6 +121,22 @@ export interface CouldNotRun {
60
121
  * this package has to those tools.
61
122
  */
62
123
  export declare const TRUST_BASE_MIN_VERSION: Partial<Record<Product, string>>;
124
+ /**
125
+ * The first intent-guard whose own `--base` can carry any change set: it
126
+ * reads the paths from git NUL-separated (1.8.0) and lists a moved submodule
127
+ * pointer with --ignore-submodules=none and ends the range with "--" (the
128
+ * release after 1.8.0). For a native contract on this version or later the
129
+ * runner hands the gate `--base` instead of `--paths`, so a changed path
130
+ * that `--paths` cannot carry (a comma, a backslash, edge whitespace, a
131
+ * leading "-") is judged rather than refused.
132
+ *
133
+ * It equals the intent-guard entry in `TRUST_BASE_MIN_VERSION`, so on a run
134
+ * with a trust base every intent gate that runs is new enough, and the
135
+ * `--paths` refusal for a native contract is reached only on a run without
136
+ * one (an explicit `--base`). Kept as its own constant because the two
137
+ * answer different questions and the floor may move without it.
138
+ */
139
+ export declare const INTENT_BASE_CHANNEL_MIN_VERSION = "1.8.1";
63
140
  /**
64
141
  * Pull-request mode as it applied to ONE gate.
65
142
  *
@@ -68,24 +145,27 @@ export declare const TRUST_BASE_MIN_VERSION: Partial<Record<Product, string>>;
68
145
  * from the other: whether this gate was actually put into pull-request mode,
69
146
  * and what it said about the control inputs the head proposes to change.
70
147
  *
71
- * `withheld` is the half that must never be silent. A gate the umbrella could
72
- * not put into pull-request mode read its own control inputs out of the tree
73
- * under judgment, which is the whole hole this release exists to close, and a
74
- * run where that happened must not look like a run where it did not.
148
+ * `withheld` is the half that must never be silent. A gate the umbrella did
149
+ * not put into pull-request mode was not handed the base ref, and a run where
150
+ * that happened must not look like a run where it did not.
75
151
  */
76
152
  export interface GateTrustBase {
77
153
  /** The ref the umbrella took its own policy from, and offered to this gate. */
78
154
  ref: string;
79
155
  /**
80
- * Null when the flag was passed; otherwise the reason it was not, for a
81
- * gate that was never going to be inside the boundary in the first place.
82
- * The run continues: that gate read its own control inputs from the tree
83
- * being judged, and the report says so.
156
+ * Null when the flag was passed; otherwise the reason it was not. Only two
157
+ * cases withhold: a product with no pull-request mode at all (none today,
158
+ * every product is in `TRUST_BASE_MIN_VERSION`), and an intent gate judging
159
+ * a contract imported for this run, whose project is a temporary directory
160
+ * with no repository in it (the contract itself was read from the base).
161
+ * A gate below its minimum is never withheld; it is `refused`.
84
162
  */
85
163
  withheld: string | null;
86
164
  /**
87
165
  * Set when the umbrella could not ESTABLISH that this gate would be in
88
- * pull-request mode, which is could-not-run rather than a downgrade.
166
+ * pull-request mode (its version did not read), or established that it
167
+ * would not be (its version is below the minimum), which is could-not-run
168
+ * rather than a downgrade.
89
169
  *
90
170
  * The distinction is the whole point and it is not symmetry with
91
171
  * `withheld`. A gate outside the table was never going to get the flag, so
@@ -147,6 +227,7 @@ export interface GateOutcome {
147
227
  intent?: {
148
228
  contractSource: ContractSource;
149
229
  baseRef: string | null;
230
+ note?: string;
150
231
  };
151
232
  /**
152
233
  * Present only on a pull-request run. Whether this gate was put into
@@ -164,8 +245,26 @@ export interface GateOutcome {
164
245
  * nowhere. Repository-relative because it reaches a published log.
165
246
  */
166
247
  nodeModulesSkipped?: string;
248
+ /**
249
+ * Present only when this gate was resolved from PATH, the version it
250
+ * reported differs from the one the run was told to expect (the Action's
251
+ * pin, handed over as an environment variable), and both are known. A
252
+ * statement for a warning, never an input to a decision: resolution,
253
+ * trust-base handling and the exit code are all settled without it.
254
+ */
255
+ versionSkew?: {
256
+ expected: string;
257
+ found: string;
258
+ path: string;
259
+ };
167
260
  }
168
261
  export interface RunGateOptions {
262
+ /**
263
+ * The version this run expects of the gate, when something says so (the
264
+ * Action passes its pin). Compared with what the PATH binary reports, for a
265
+ * warning only. Absent means no expectation, which is every local run.
266
+ */
267
+ expectedVersion?: string;
169
268
  repoRoot: string;
170
269
  staged: boolean;
171
270
  /** PATH to search. Injected so tests never depend on the machine. */
@@ -281,7 +380,12 @@ export declare function gateArgs(gate: GatePolicy, staged: boolean, intent: Inte
281
380
  */
282
381
  trustBase?: string,
283
382
  /** Paths the runner owns for an external tool; the npm gates ignore them. */
284
- external?: ExternalArgs): string[];
383
+ external?: ExternalArgs,
384
+ /**
385
+ * For the intent gate on a prepared run: hand it this base with its own
386
+ * `--base` in place of `--paths`. Decided by `intentChangeChannel`.
387
+ */
388
+ intentBase?: string): string[];
285
389
  /**
286
390
  * Runs one gate. TOTAL: this never throws.
287
391
  *
@@ -293,3 +397,10 @@ external?: ExternalArgs): string[];
293
397
  * a finding of the umbrella's own saying so.
294
398
  */
295
399
  export declare function runGate(gate: GatePolicy, options: RunGateOptions): GateOutcome;
400
+ /**
401
+ * Whether git says the repository at `repoRoot` is shallow. Anything other
402
+ * than a clear "true" (no git, an old git that does not know the flag) is
403
+ * not shallow: those runs have their own failure paths.
404
+ */
405
+ /** The oldest git a history gate runs under on a pull-request run. */
406
+ export declare const HISTORY_GIT_FLOOR = "2.31.0";