@vaultcompass/conductor 0.8.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.
- package/README.md +127 -50
- package/dist/cli.js +151 -29
- package/dist/external-config.d.ts +2 -1
- package/dist/external-config.js +33 -18
- package/dist/gate-runner.d.ts +119 -16
- package/dist/gate-runner.js +328 -60
- package/dist/git.d.ts +80 -0
- package/dist/git.js +224 -0
- 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.js +6 -4
- package/dist/output-sarif.js +12 -13
- package/dist/output-text.d.ts +48 -0
- package/dist/output-text.js +139 -14
- package/dist/policy.js +9 -7
- package/dist/resolve.d.ts +1 -0
- package/dist/resolve.js +1 -1
- package/dist/run.d.ts +8 -0
- package/dist/run.js +63 -13
- package/dist/trust-base.d.ts +82 -20
- package/dist/trust-base.js +190 -73
- package/package.json +1 -1
package/dist/external-config.js
CHANGED
|
@@ -15,9 +15,9 @@
|
|
|
15
15
|
// head's file on its own. A head-side difference is not an error: it is
|
|
16
16
|
// reported as a proposal, which takes effect once it merges and the base
|
|
17
17
|
// carries it.
|
|
18
|
-
import { spawnSync } from 'node:child_process';
|
|
19
18
|
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
20
19
|
import path from 'node:path';
|
|
20
|
+
import { readFileAtRef, unreadableBaseRemedy } from './trust-base.js';
|
|
21
21
|
/** The base ref's config cannot be materialised; the gate cannot run safely. */
|
|
22
22
|
export class ExternalConfigError extends Error {
|
|
23
23
|
constructor(message) {
|
|
@@ -60,26 +60,38 @@ export function extendPath(config) {
|
|
|
60
60
|
}
|
|
61
61
|
return null;
|
|
62
62
|
}
|
|
63
|
-
/**
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
63
|
+
/**
|
|
64
|
+
* A file's contents at the base ref, or null when the base does not carry
|
|
65
|
+
* it. A read git could not make THROWS: it is never null, because null
|
|
66
|
+
* selects the neutral config, and a trusted file that exists but could not
|
|
67
|
+
* be read must not be replaced by a default (src/trust-base.ts,
|
|
68
|
+
* readFileAtRef).
|
|
69
|
+
*/
|
|
70
|
+
function baseCopy(repoRoot, ref, file) {
|
|
71
|
+
const read = readFileAtRef(repoRoot, ref, file);
|
|
72
|
+
if (read.kind === 'error') {
|
|
73
|
+
throw new ExternalConfigError(`${file} could not be read from the base ref: ${read.detail}. Nothing was checked by this ` +
|
|
74
|
+
`gate. ${unreadableBaseRemedy(file)}`);
|
|
67
75
|
}
|
|
68
|
-
|
|
69
|
-
cwd: repoRoot,
|
|
70
|
-
encoding: 'utf8',
|
|
71
|
-
});
|
|
72
|
-
return child.status === 0 && typeof child.stdout === 'string' ? child.stdout : null;
|
|
76
|
+
return read.kind === 'file' ? read.text : null;
|
|
73
77
|
}
|
|
74
78
|
function headCopy(repoRoot, file) {
|
|
75
79
|
const full = path.join(repoRoot, file);
|
|
76
80
|
return existsSync(full) ? readFileSync(full, 'utf8') : null;
|
|
77
81
|
}
|
|
78
|
-
|
|
82
|
+
/**
|
|
83
|
+
* The proposal line for a head-side difference, or null. It says which copy
|
|
84
|
+
* was actually used: the base's own, or, when the base carries none, the
|
|
85
|
+
* stand-in the umbrella wrote. Saying "the base's copy" for a stand-in would
|
|
86
|
+
* claim a file the base does not have.
|
|
87
|
+
*/
|
|
88
|
+
function differs(file, base, head, standIn = "conductor's neutral stand-in") {
|
|
79
89
|
if (head === null || head === base) {
|
|
80
90
|
return null;
|
|
81
91
|
}
|
|
82
|
-
return
|
|
92
|
+
return base === null
|
|
93
|
+
? `${file} is not on the base ref; ${standIn} was used and this file takes effect after merge.`
|
|
94
|
+
: `${file} differs from the base ref; the base's copy was used and this change takes effect after merge.`;
|
|
83
95
|
}
|
|
84
96
|
/**
|
|
85
97
|
* Copies one relative file from the base ref into the run directory, at the
|
|
@@ -93,7 +105,7 @@ function materializeRelative(repoRoot, trustBase, cwd, file, what) {
|
|
|
93
105
|
throw new ExternalConfigError(`${what} ${file} is not a path inside the repository, so conductor cannot read it from ` +
|
|
94
106
|
'the base ref; name it relative to the repository root.');
|
|
95
107
|
}
|
|
96
|
-
const base =
|
|
108
|
+
const base = baseCopy(repoRoot, trustBase, path.relative(cwd, target).split(path.sep).join('/'));
|
|
97
109
|
if (base === null) {
|
|
98
110
|
throw new ExternalConfigError(`${what} ${file} does not exist on the base ref ${trustBase}, so there is no approved copy ` +
|
|
99
111
|
'to read; commit it to the base branch or remove the reference.');
|
|
@@ -110,12 +122,13 @@ function materializeRelative(repoRoot, trustBase, cwd, file, what) {
|
|
|
110
122
|
* a nested file added or edited by the pull request has no effect on the run
|
|
111
123
|
* (measured against 2.6.0: a nested file ignoring lodash passes without
|
|
112
124
|
* --config and blocks with it). It is still a change to how the tool behaves
|
|
113
|
-
* once merged, so it is reported the way the root config is.
|
|
125
|
+
* once merged, so it is reported the way the root config is. A base copy git
|
|
126
|
+
* could not read throws ExternalConfigError, like every other base read here.
|
|
114
127
|
*/
|
|
115
128
|
export function nestedConfigProposals(repoRoot, trustBase, trackedFiles, configFile) {
|
|
116
129
|
return trackedFiles
|
|
117
130
|
.filter((file) => file !== configFile && path.posix.basename(file) === configFile)
|
|
118
|
-
.map((file) => differs(file,
|
|
131
|
+
.map((file) => differs(file, baseCopy(repoRoot, trustBase, file), headCopy(repoRoot, file), 'the root config'))
|
|
119
132
|
.filter((proposal) => proposal !== null);
|
|
120
133
|
}
|
|
121
134
|
export function materializeExternalConfig(args) {
|
|
@@ -123,7 +136,9 @@ export function materializeExternalConfig(args) {
|
|
|
123
136
|
if (profile.configFile === null) {
|
|
124
137
|
return null;
|
|
125
138
|
}
|
|
126
|
-
|
|
139
|
+
// Only an ABSENT base config selects the neutral one. An unreadable one has
|
|
140
|
+
// already thrown, so the tool never runs under a default in its place.
|
|
141
|
+
const base = baseCopy(repoRoot, trustBase, profile.configFile);
|
|
127
142
|
const ext = path.extname(profile.configFile) || '.toml';
|
|
128
143
|
const out = path.join(tempRoot, `${profile.product}-config${ext}`);
|
|
129
144
|
writeFileSync(out, base ?? profile.neutralConfig ?? '');
|
|
@@ -158,13 +173,13 @@ export function materializeExternalConfig(args) {
|
|
|
158
173
|
let ignore = null;
|
|
159
174
|
if (profile.ignoreFile !== null) {
|
|
160
175
|
const name = profile.ignoreFile.name;
|
|
161
|
-
const baseIgnore =
|
|
176
|
+
const baseIgnore = baseCopy(repoRoot, trustBase, name);
|
|
162
177
|
const dir = path.join(tempRoot, `${profile.product}-ignore`);
|
|
163
178
|
mkdirSync(dir, { recursive: true });
|
|
164
179
|
// An empty file when the base has none, for the reason the neutral
|
|
165
180
|
// config exists: pointing the tool anywhere else lets it find the head's.
|
|
166
181
|
writeFileSync(path.join(dir, name), baseIgnore ?? '');
|
|
167
|
-
ignore = { dir, proposal: differs(name, baseIgnore, headCopy(repoRoot, name)) };
|
|
182
|
+
ignore = { dir, proposal: differs(name, baseIgnore, headCopy(repoRoot, name), 'an empty one') };
|
|
168
183
|
}
|
|
169
184
|
return {
|
|
170
185
|
path: out,
|
package/dist/gate-runner.d.ts
CHANGED
|
@@ -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
|
|
31
|
-
* tools have a
|
|
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
|
/**
|
|
@@ -48,7 +52,55 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
|
|
|
48
52
|
export interface CouldNotRun {
|
|
49
53
|
reason: CouldNotRunReason;
|
|
50
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;
|
|
51
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;
|
|
52
104
|
/**
|
|
53
105
|
* The first version of each gate that understands `--trust-base`.
|
|
54
106
|
*
|
|
@@ -57,10 +109,11 @@ export interface CouldNotRun {
|
|
|
57
109
|
* against every combination in the meantime. A product missing from this
|
|
58
110
|
* table has no pull-request mode yet and is never handed the flag; a product
|
|
59
111
|
* in it is handed the flag only when the installed build says it is at least
|
|
60
|
-
* this version
|
|
61
|
-
* not
|
|
62
|
-
*
|
|
63
|
-
*
|
|
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.
|
|
64
117
|
*
|
|
65
118
|
* The umbrella is deliberately NOT the place a version pin lives otherwise
|
|
66
119
|
* (nothing here imports any gate's package), and this is the one exception:
|
|
@@ -68,6 +121,22 @@ export interface CouldNotRun {
|
|
|
68
121
|
* this package has to those tools.
|
|
69
122
|
*/
|
|
70
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";
|
|
71
140
|
/**
|
|
72
141
|
* Pull-request mode as it applied to ONE gate.
|
|
73
142
|
*
|
|
@@ -76,24 +145,27 @@ export declare const TRUST_BASE_MIN_VERSION: Partial<Record<Product, string>>;
|
|
|
76
145
|
* from the other: whether this gate was actually put into pull-request mode,
|
|
77
146
|
* and what it said about the control inputs the head proposes to change.
|
|
78
147
|
*
|
|
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.
|
|
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.
|
|
83
151
|
*/
|
|
84
152
|
export interface GateTrustBase {
|
|
85
153
|
/** The ref the umbrella took its own policy from, and offered to this gate. */
|
|
86
154
|
ref: string;
|
|
87
155
|
/**
|
|
88
|
-
* Null when the flag was passed; otherwise the reason it was not
|
|
89
|
-
*
|
|
90
|
-
*
|
|
91
|
-
*
|
|
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`.
|
|
92
162
|
*/
|
|
93
163
|
withheld: string | null;
|
|
94
164
|
/**
|
|
95
165
|
* Set when the umbrella could not ESTABLISH that this gate would be in
|
|
96
|
-
* pull-request mode
|
|
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.
|
|
97
169
|
*
|
|
98
170
|
* The distinction is the whole point and it is not symmetry with
|
|
99
171
|
* `withheld`. A gate outside the table was never going to get the flag, so
|
|
@@ -155,6 +227,7 @@ export interface GateOutcome {
|
|
|
155
227
|
intent?: {
|
|
156
228
|
contractSource: ContractSource;
|
|
157
229
|
baseRef: string | null;
|
|
230
|
+
note?: string;
|
|
158
231
|
};
|
|
159
232
|
/**
|
|
160
233
|
* Present only on a pull-request run. Whether this gate was put into
|
|
@@ -172,8 +245,26 @@ export interface GateOutcome {
|
|
|
172
245
|
* nowhere. Repository-relative because it reaches a published log.
|
|
173
246
|
*/
|
|
174
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
|
+
};
|
|
175
260
|
}
|
|
176
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;
|
|
177
268
|
repoRoot: string;
|
|
178
269
|
staged: boolean;
|
|
179
270
|
/** PATH to search. Injected so tests never depend on the machine. */
|
|
@@ -289,7 +380,12 @@ export declare function gateArgs(gate: GatePolicy, staged: boolean, intent: Inte
|
|
|
289
380
|
*/
|
|
290
381
|
trustBase?: string,
|
|
291
382
|
/** Paths the runner owns for an external tool; the npm gates ignore them. */
|
|
292
|
-
external?: ExternalArgs
|
|
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[];
|
|
293
389
|
/**
|
|
294
390
|
* Runs one gate. TOTAL: this never throws.
|
|
295
391
|
*
|
|
@@ -301,3 +397,10 @@ external?: ExternalArgs): string[];
|
|
|
301
397
|
* a finding of the umbrella's own saying so.
|
|
302
398
|
*/
|
|
303
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";
|