@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/run.js
CHANGED
|
@@ -11,15 +11,21 @@ import { POLICY_PROPOSAL_LINE } from './trust-base.js';
|
|
|
11
11
|
/**
|
|
12
12
|
* Whether this run is the pull-request shaped one.
|
|
13
13
|
*
|
|
14
|
-
* The whole intent-at-pull-request flow engages on a
|
|
15
|
-
* explicit `--spec`, and on nothing else. Without one of
|
|
16
|
-
* gate keeps exactly the command line v0.1 gave it: a
|
|
17
|
-
* `conductor run` on their own machine has not asked for a
|
|
18
|
-
* imported, and importing one anyway would change what a
|
|
19
|
-
* without anybody having written that down.
|
|
14
|
+
* The whole intent-at-pull-request flow engages on a trust base, a resolved
|
|
15
|
+
* base ref or an explicit `--spec`, and on nothing else. Without one of
|
|
16
|
+
* those, the intent gate keeps exactly the command line v0.1 gave it: a
|
|
17
|
+
* developer running `conductor run` on their own machine has not asked for a
|
|
18
|
+
* contract to be imported, and importing one anyway would change what a
|
|
19
|
+
* local run means without anybody having written that down.
|
|
20
|
+
*
|
|
21
|
+
* A TRUST BASE ALWAYS MAKES THE RUN PULL-REQUEST SHAPED, with or without a
|
|
22
|
+
* base ref or GITHUB_BASE_REF (merge_group, workflow_dispatch and any CLI
|
|
23
|
+
* run that passes --trust-base alone). A run with a trust base is always
|
|
24
|
+
* judged as a pull request against that base: the change set is measured
|
|
25
|
+
* from it.
|
|
20
26
|
*/
|
|
21
27
|
function isPullRequestShaped(options, env) {
|
|
22
|
-
if (options.spec !== undefined) {
|
|
28
|
+
if (options.spec !== undefined || options.trustBase !== undefined) {
|
|
23
29
|
return true;
|
|
24
30
|
}
|
|
25
31
|
return resolveBaseRef({ ...(options.base === undefined ? {} : { base: options.base }), env }) !== null;
|
|
@@ -124,7 +130,12 @@ export function refusedTrustBase(policy, ref, detail, options) {
|
|
|
124
130
|
// thing that could not be read. False rather than a third state, because
|
|
125
131
|
// no proposal is reported on a run where nothing was judged. The refusal
|
|
126
132
|
// itself is carried, and it is what both renderers lead with.
|
|
127
|
-
trustBase: {
|
|
133
|
+
trustBase: {
|
|
134
|
+
ref,
|
|
135
|
+
policyChanged: false,
|
|
136
|
+
refusal: detail,
|
|
137
|
+
...(options.notGiven === true ? { notGiven: true } : {}),
|
|
138
|
+
},
|
|
128
139
|
proposals: [],
|
|
129
140
|
summary: {
|
|
130
141
|
blocking: findings.filter((finding) => finding.blocking).length,
|
|
@@ -142,11 +153,19 @@ export function refusedTrustBase(policy, ref, detail, options) {
|
|
|
142
153
|
* proposing to change which gates run at all, and reading that after a gate's
|
|
143
154
|
* own contract line would bury it.
|
|
144
155
|
*/
|
|
145
|
-
function collectProposals(outcomes, trustBase
|
|
156
|
+
function collectProposals(outcomes, trustBase,
|
|
157
|
+
/**
|
|
158
|
+
* The intent gate's own control files this pull request adds or changes,
|
|
159
|
+
* observed while preparing it from the base ref (a contract or spec the
|
|
160
|
+
* base does not carry yet, an edit to the imported spec). They arrive here
|
|
161
|
+
* whether the gate then ran or was skipped.
|
|
162
|
+
*/
|
|
163
|
+
preparation = []) {
|
|
146
164
|
const proposals = [];
|
|
147
165
|
if (trustBase?.policyChanged === true) {
|
|
148
166
|
proposals.push({ product: 'conductor', role: null, line: POLICY_PROPOSAL_LINE });
|
|
149
167
|
}
|
|
168
|
+
proposals.push(...preparation);
|
|
150
169
|
for (const outcome of outcomes) {
|
|
151
170
|
for (const line of outcome.trustBase?.proposals ?? []) {
|
|
152
171
|
proposals.push({ product: outcome.product, role: outcome.role, line });
|
|
@@ -198,11 +217,32 @@ function splitOnTreeUnchanged(gates, trustBase) {
|
|
|
198
217
|
}
|
|
199
218
|
return { toRun, treeUnchanged };
|
|
200
219
|
}
|
|
220
|
+
/**
|
|
221
|
+
* The environment variables the Action sets to say which version of each
|
|
222
|
+
* family gate it pinned, read only to warn when a gate resolved from PATH
|
|
223
|
+
* reports a different one. Not a control input: nothing about resolution or
|
|
224
|
+
* the verdict reads them, so a run that sets them wrongly gets a wrong warning
|
|
225
|
+
* and nothing else.
|
|
226
|
+
*/
|
|
227
|
+
const EXPECTED_VERSION_ENV = {
|
|
228
|
+
'dep-guard': 'CONDUCTOR_EXPECTED_DEP_GUARD_VERSION',
|
|
229
|
+
'vault-guard': 'CONDUCTOR_EXPECTED_VAULT_GUARD_VERSION',
|
|
230
|
+
'intent-guard': 'CONDUCTOR_EXPECTED_INTENT_GUARD_VERSION',
|
|
231
|
+
};
|
|
232
|
+
/** The `expectedVersion` option for one gate, or nothing. Exact versions only. */
|
|
233
|
+
function expectedVersionOption(product, env) {
|
|
234
|
+
const name = EXPECTED_VERSION_ENV[product];
|
|
235
|
+
const value = name === undefined ? undefined : env[name];
|
|
236
|
+
return value !== undefined && /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.test(value)
|
|
237
|
+
? { expectedVersion: value }
|
|
238
|
+
: {};
|
|
239
|
+
}
|
|
201
240
|
export function runAll(policy, options) {
|
|
202
241
|
const { gates: partitioned, deferred, excluded } = partitionGates(policy, options.stage);
|
|
203
242
|
const { toRun: gates, treeUnchanged } = splitOnTreeUnchanged(partitioned, options.trustBase);
|
|
204
243
|
const env = options.env ?? {};
|
|
205
244
|
const skipped = [];
|
|
245
|
+
const preparationProposals = [];
|
|
206
246
|
const cleanups = [];
|
|
207
247
|
// Sequential, not concurrent. Three Node process starts is real overhead
|
|
208
248
|
// in a pre-commit hook and running them at once would hide most of it,
|
|
@@ -243,7 +283,16 @@ export function runAll(policy, options) {
|
|
|
243
283
|
...(options.spec === undefined ? {} : { spec: options.spec }),
|
|
244
284
|
...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
|
|
245
285
|
...(options.tempRoot === undefined ? {} : { tempRoot: options.tempRoot }),
|
|
286
|
+
...(trustBaseRef === undefined ? {} : { trustBase: trustBaseRef }),
|
|
246
287
|
});
|
|
288
|
+
const proposed = prepared.kind === 'skip'
|
|
289
|
+
? prepared.proposals
|
|
290
|
+
: prepared.kind === 'ready'
|
|
291
|
+
? prepared.preparation.proposals
|
|
292
|
+
: undefined;
|
|
293
|
+
for (const line of proposed ?? []) {
|
|
294
|
+
preparationProposals.push({ product: gate.product, role: gate.role, line });
|
|
295
|
+
}
|
|
247
296
|
if (prepared.kind === 'skip') {
|
|
248
297
|
skipped.push({
|
|
249
298
|
role: gate.role,
|
|
@@ -275,15 +324,16 @@ export function runAll(policy, options) {
|
|
|
275
324
|
pathValue: options.pathValue,
|
|
276
325
|
...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
|
|
277
326
|
...(intent === undefined ? {} : { intent }),
|
|
327
|
+
...expectedVersionOption(gate.product, env),
|
|
278
328
|
// For a run with no preparation: which contract the child will read
|
|
279
329
|
// out of the repository itself. Looked up only for the gate it is
|
|
280
330
|
// about, so no other gate pays for the two stat calls.
|
|
281
331
|
...(intent !== undefined || gate.role !== 'intent'
|
|
282
332
|
? {}
|
|
283
333
|
: nativeContractOption(options.repoRoot)),
|
|
284
|
-
// Offered to every child. runGate decides which ones
|
|
285
|
-
//
|
|
286
|
-
//
|
|
334
|
+
// Offered to every child. runGate decides which ones take it: a
|
|
335
|
+
// gate below its pull-request-mode minimum is could-not-run, and a
|
|
336
|
+
// gate it is withheld from carries the reason on the outcome.
|
|
287
337
|
...(options.trustBase === undefined ? {} : { trustBase: options.trustBase.ref }),
|
|
288
338
|
// Where an external gate's working directory goes (its report file,
|
|
289
339
|
// its config from the base ref). The runner removes what it makes.
|
|
@@ -324,7 +374,7 @@ export function runAll(policy, options) {
|
|
|
324
374
|
treeUnchanged,
|
|
325
375
|
findings,
|
|
326
376
|
trustBase: options.trustBase ?? null,
|
|
327
|
-
proposals: collectProposals(outcomes, options.trustBase),
|
|
377
|
+
proposals: collectProposals(outcomes, options.trustBase, preparationProposals),
|
|
328
378
|
summary: {
|
|
329
379
|
blocking: findings.filter((finding) => finding.blocking).length,
|
|
330
380
|
byProduct,
|
package/dist/trust-base.d.ts
CHANGED
|
@@ -6,19 +6,38 @@
|
|
|
6
6
|
* otherwise choose the commit the rules are read from.
|
|
7
7
|
*/
|
|
8
8
|
export declare const PRIVATE_TRUST_BASE_REF = "refs/conductor/trust-base";
|
|
9
|
+
/** What a fully spelled ref names: nothing, an object, or an answer git could not give. */
|
|
10
|
+
export type RefLookup = {
|
|
11
|
+
kind: 'absent';
|
|
12
|
+
} | {
|
|
13
|
+
kind: 'ref';
|
|
14
|
+
oid: string;
|
|
15
|
+
} | {
|
|
16
|
+
kind: 'error';
|
|
17
|
+
detail: string;
|
|
18
|
+
};
|
|
19
|
+
/**
|
|
20
|
+
* The object a fully spelled ref EXACTLY names, keeping "no such ref" apart
|
|
21
|
+
* from "git could not answer". `show-ref --verify` looks at that ref and
|
|
22
|
+
* nothing else: it does not run git's name-resolution rules, so a tag stored
|
|
23
|
+
* as refs/tags/refs/conductor/trust-base is never taken for
|
|
24
|
+
* refs/conductor/trust-base. With --quiet it exits 1 for a ref that is not
|
|
25
|
+
* there and something else for a failure, which is the split this needs.
|
|
26
|
+
*/
|
|
27
|
+
export declare function exactRefLookup(repoRoot: string, fullRef: string): RefLookup;
|
|
9
28
|
/**
|
|
10
29
|
* The object id a fully spelled ref EXACTLY names, or null when there is no
|
|
11
|
-
* such ref
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
* refs/conductor/trust-base.
|
|
30
|
+
* such ref or it cannot be read. For callers where both mean "cannot use
|
|
31
|
+
* it"; a caller that would fall back to something else on absence uses
|
|
32
|
+
* `exactRefLookup` instead, so an unreadable ref never takes that fallback.
|
|
15
33
|
*/
|
|
16
34
|
export declare function exactRefObject(repoRoot: string, fullRef: string): string | null;
|
|
17
35
|
/**
|
|
18
36
|
* A caller-given trust base that starts with "-", or null. Git allows a tag
|
|
19
37
|
* named refs/tags/--output=x, and such a name handed to git as an argument is
|
|
20
|
-
* read as an option, not a revision. Refused before any git call sees it;
|
|
21
|
-
* git
|
|
38
|
+
* read as an option, not a revision. Refused before any git call sees it; each
|
|
39
|
+
* git-calling function below refuses one again itself, so no caller can skip
|
|
40
|
+
* the check.
|
|
22
41
|
*/
|
|
23
42
|
export declare function refuseDashLeadingRef(ref: string): string | null;
|
|
24
43
|
/** A full 40- or 64-hex object id: never subject to ref name resolution. */
|
|
@@ -129,15 +148,43 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
|
|
|
129
148
|
*/
|
|
130
149
|
export declare function refuseTrustBaseForPullRequest(repoRoot: string, ref: string, githubBaseRef: string | undefined): string | null;
|
|
131
150
|
/**
|
|
132
|
-
*
|
|
151
|
+
* How a control file that cannot be read at the base is cleared, as one
|
|
152
|
+
* sentence for every refusal that names one. The pull request that fixes the
|
|
153
|
+
* file is judged against the same base, so it cannot pass this check itself.
|
|
154
|
+
*/
|
|
155
|
+
export declare function unreadableBaseRemedy(relativePath: string): string;
|
|
156
|
+
/** One file at a ref: not there, its text, or a read this run could not make. */
|
|
157
|
+
export type FileAtRef = {
|
|
158
|
+
kind: 'absent';
|
|
159
|
+
} | {
|
|
160
|
+
kind: 'file';
|
|
161
|
+
text: string;
|
|
162
|
+
} | {
|
|
163
|
+
kind: 'error';
|
|
164
|
+
detail: string;
|
|
165
|
+
};
|
|
166
|
+
/**
|
|
167
|
+
* One file's contents at a ref, with absent, present and unreadable kept
|
|
168
|
+
* apart. THE ONE READER for every file the umbrella takes from a ref.
|
|
133
169
|
*
|
|
134
|
-
* `git
|
|
135
|
-
* tree
|
|
136
|
-
*
|
|
137
|
-
*
|
|
138
|
-
*
|
|
170
|
+
* Two steps. `git ls-tree <ref> -- ./<path>` looks the path up in the ref's
|
|
171
|
+
* tree: a listing that succeeds and names nothing is ABSENT, and a listing
|
|
172
|
+
* that fails is an ERROR. The entry must be a regular file; a symlink, a
|
|
173
|
+
* directory or a submodule at the path, or at any directory above it, is an
|
|
174
|
+
* ERROR, never read as its link target or as nothing. Then
|
|
175
|
+
* `git cat-file blob <id>` reads the blob by the id the listing named, and a
|
|
176
|
+
* failure there is an ERROR too. The path is only ever a path and the
|
|
177
|
+
* revision only ever a revision, so a file name can never be read as part of
|
|
178
|
+
* a revision, and absent, present and unreadable are three separate answers.
|
|
179
|
+
*
|
|
180
|
+
* No caller turns an ERROR into empty text or into a default. An error is
|
|
181
|
+
* could-not-run: the trusted file exists, or may, and nothing was judged
|
|
182
|
+
* against it.
|
|
183
|
+
*
|
|
184
|
+
* The `./` makes git resolve the path relative to the working directory,
|
|
185
|
+
* which is the repository root here.
|
|
139
186
|
*/
|
|
140
|
-
export declare function
|
|
187
|
+
export declare function readFileAtRef(repoRoot: string, ref: string, relativePath: string): FileAtRef;
|
|
141
188
|
/**
|
|
142
189
|
* Whether two policy files differ in what they SAY.
|
|
143
190
|
*
|
|
@@ -148,7 +195,7 @@ export declare function readPolicyAtRef(repoRoot: string, ref: string): string |
|
|
|
148
195
|
* compared instead, which is the fail-closed direction: an unparseable head
|
|
149
196
|
* policy is reported as a change rather than quietly matching.
|
|
150
197
|
*
|
|
151
|
-
* BOTH SIDES COME FROM `
|
|
198
|
+
* BOTH SIDES COME FROM `readFileAtRef`, base and head alike, and that is not an
|
|
152
199
|
* accident of implementation. intent-guard read its head side from the
|
|
153
200
|
* working tree with a call that follows symlinks, so a pull request that
|
|
154
201
|
* replaced a control file with a link compared equal to the base and was
|
|
@@ -159,19 +206,34 @@ export declare function readPolicyAtRef(repoRoot: string, ref: string): string |
|
|
|
159
206
|
export declare function policyDiffers(base: string | null, head: string | null): boolean;
|
|
160
207
|
/** The one line the report prints when the head proposes a different policy. */
|
|
161
208
|
export declare const POLICY_PROPOSAL_LINE = "policy changed in this pull request";
|
|
209
|
+
/** One path's tree entry at a ref: not there, the entry, or a listing that failed. */
|
|
210
|
+
export type TreeEntry = {
|
|
211
|
+
kind: 'absent';
|
|
212
|
+
} | {
|
|
213
|
+
kind: 'entry';
|
|
214
|
+
mode: string;
|
|
215
|
+
type: string;
|
|
216
|
+
sha: string;
|
|
217
|
+
} | {
|
|
218
|
+
kind: 'error';
|
|
219
|
+
detail: string;
|
|
220
|
+
};
|
|
162
221
|
/**
|
|
163
|
-
* One path's tree entry at a ref,
|
|
222
|
+
* One path's tree entry at a ref, keeping "the ref has no such path" apart
|
|
223
|
+
* from "git could not list it".
|
|
164
224
|
*
|
|
165
225
|
* `ls-tree` rather than `git show`, because the BLOB ID is the thing being
|
|
166
226
|
* compared and `show` prints contents without telling you what kind of entry
|
|
167
227
|
* produced them. The mode comes with it, so a regular file can be told from a
|
|
168
228
|
* symlink, a submodule or a directory in the same read.
|
|
229
|
+
*
|
|
230
|
+
* Only a listing that SUCCEEDS and names nothing is absent. ls-tree exiting
|
|
231
|
+
* non-zero (a ref that will not resolve, a tree it cannot read) is a read
|
|
232
|
+
* this run cannot make, and so is a path with a symlink or a submodule at
|
|
233
|
+
* any directory above it in the ref's tree: what the path means there is
|
|
234
|
+
* decided outside the tree, so it is an error, never absent.
|
|
169
235
|
*/
|
|
170
|
-
export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string):
|
|
171
|
-
mode: string;
|
|
172
|
-
type: string;
|
|
173
|
-
sha: string;
|
|
174
|
-
} | null;
|
|
236
|
+
export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): TreeEntry;
|
|
175
237
|
/**
|
|
176
238
|
* Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
|
|
177
239
|
*
|