@vaultcompass/conductor 0.2.1 → 0.2.3
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 +98 -6
- package/dist/cli.js +49 -6
- package/dist/gate-runner.js +16 -5
- package/dist/init.d.ts +18 -2
- package/dist/init.js +241 -13
- package/dist/intent-prepare.d.ts +68 -4
- package/dist/intent-prepare.js +253 -19
- package/dist/intent-spec.d.ts +13 -0
- package/dist/intent-spec.js +21 -0
- package/dist/normalize.d.ts +31 -3
- package/dist/normalize.js +63 -5
- package/dist/output-sarif.js +65 -1
- package/dist/output-text.js +44 -8
- package/dist/run.d.ts +21 -7
- package/dist/run.js +1 -0
- package/package.json +1 -1
package/dist/output-sarif.js
CHANGED
|
@@ -21,6 +21,20 @@
|
|
|
21
21
|
// umbrella, which is the only honest owner of a statement about a tool
|
|
22
22
|
// that is not installed.
|
|
23
23
|
//
|
|
24
|
+
// The rule is written for a gate that never ran, and it currently also
|
|
25
|
+
// covers a gate that RAN AND FAILED, which is a different thing: the
|
|
26
|
+
// SARIF-native shape for that one is its own run carrying
|
|
27
|
+
// invocations[0].executionSuccessful: false. That is deliberately not
|
|
28
|
+
// done here yet, because it changes the run list of every log with a
|
|
29
|
+
// failing gate in it and this release is a fix rather than a format
|
|
30
|
+
// change. The consequence is that conductor/gate-failed in the
|
|
31
|
+
// umbrella's run is the ONLY place such a log can say anything at all
|
|
32
|
+
// about the failure, which is why that finding carries the child's own
|
|
33
|
+
// stderr (normalizeFailedGate in normalize.ts). A dogfood run found the
|
|
34
|
+
// gap the other way round: the text report printed dep-guard naming an
|
|
35
|
+
// unparseable lockfile and the log beside it said only that the gate had
|
|
36
|
+
// exited 2.
|
|
37
|
+
//
|
|
24
38
|
// - A STATEMENT ABOUT COVERAGE OR CONFIGURATION IS A NOTIFICATION, NOT A
|
|
25
39
|
// FINDING. A gate deferred to a later stage, a gate the policy told not
|
|
26
40
|
// to decide anything, and a branch with no contract to check against are
|
|
@@ -84,6 +98,7 @@
|
|
|
84
98
|
// product, which puts an end column in its own SARIF; see the note in
|
|
85
99
|
// normalize.ts, which is where the omission would stop mattering if the
|
|
86
100
|
// field were ever carried.
|
|
101
|
+
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
87
102
|
const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
|
|
88
103
|
export const UMBRELLA_DRIVER_NAME = 'conductor';
|
|
89
104
|
/**
|
|
@@ -372,6 +387,48 @@ function deferredNotifications(result) {
|
|
|
372
387
|
details: { role: gate.role, product: gate.product, stage: gate.stage },
|
|
373
388
|
}));
|
|
374
389
|
}
|
|
390
|
+
/**
|
|
391
|
+
* The intent gate reading its contract from the pre-1.3 state directory.
|
|
392
|
+
*
|
|
393
|
+
* intent-guard 1.3.0 renamed `.conductor` to `.intent-guard`, and the
|
|
394
|
+
* umbrella reads both so a repository on either version is checked rather
|
|
395
|
+
* than blocked. That fallback is silent otherwise, and a silent fallback is
|
|
396
|
+
* how a repository ends up on the old layout for a year: the log should say
|
|
397
|
+
* which directory the verdict was actually about.
|
|
398
|
+
*
|
|
399
|
+
* A NOTIFICATION by the discriminator below, and it is worth saying why,
|
|
400
|
+
* because it is the closest call of the five. Nothing went wrong. The gate
|
|
401
|
+
* ran, the contract was read, the verdict is exactly what it would have been
|
|
402
|
+
* after the migration, and the run is complete. What this says is which of
|
|
403
|
+
* two layouts the run covered, it stays true on every run until somebody
|
|
404
|
+
* upgrades the gate, and as a result it would be a fingerprint-less alert
|
|
405
|
+
* reappearing on every pull request for as long as that takes -- the precise
|
|
406
|
+
* shape of permanent alert the notification rule exists to keep out.
|
|
407
|
+
*/
|
|
408
|
+
function legacyStateDirNotifications(result) {
|
|
409
|
+
return result.gates.flatMap((gate) => {
|
|
410
|
+
const source = gate.intent?.contractSource;
|
|
411
|
+
if (source === undefined || source.kind !== 'native' || !isLegacyContractPath(source.path)) {
|
|
412
|
+
return [];
|
|
413
|
+
}
|
|
414
|
+
return [
|
|
415
|
+
{
|
|
416
|
+
id: 'intent-guard/legacy-state-dir',
|
|
417
|
+
message: `The ${gate.role} gate (${gate.product}) read its frozen contract from ` +
|
|
418
|
+
`${source.path}, the state directory intent-guard used before 1.3.0. This run's ` +
|
|
419
|
+
`verdict is unaffected. 1.3.0 renamed that directory, reads the old one while it ` +
|
|
420
|
+
`is the only one there, and migrates it on its first write, after which the ` +
|
|
421
|
+
`contract is at ${NATIVE_CONTRACT_PATH}.`,
|
|
422
|
+
details: {
|
|
423
|
+
role: gate.role,
|
|
424
|
+
product: gate.product,
|
|
425
|
+
contractPath: source.path,
|
|
426
|
+
canonicalPath: NATIVE_CONTRACT_PATH,
|
|
427
|
+
},
|
|
428
|
+
},
|
|
429
|
+
];
|
|
430
|
+
});
|
|
431
|
+
}
|
|
375
432
|
/**
|
|
376
433
|
* The gates the --gate flag left out, as notifications.
|
|
377
434
|
*
|
|
@@ -432,7 +489,13 @@ function excludedNotifications(result) {
|
|
|
432
489
|
*/
|
|
433
490
|
function skippedNotifications(result) {
|
|
434
491
|
return result.skipped.map((gate) => ({
|
|
435
|
-
id
|
|
492
|
+
// The reason IS the second half of the id, which keeps
|
|
493
|
+
// intent-guard/no-contract exactly where consumers already have it and
|
|
494
|
+
// gives the waiver its own id rather than filing two different facts
|
|
495
|
+
// under one. A waiver is a statement about configuration in the purest
|
|
496
|
+
// form the rule above describes: a person wrote it in the pull request
|
|
497
|
+
// body on purpose, so it is a notification and never a result.
|
|
498
|
+
id: `${gate.product}/${gate.reason}`,
|
|
436
499
|
message: `The ${gate.role} gate (${gate.product}) checked nothing on this branch. ${gate.detail}`,
|
|
437
500
|
details: { role: gate.role, product: gate.product, reason: gate.reason },
|
|
438
501
|
}));
|
|
@@ -545,6 +608,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
545
608
|
...excludedNotifications(result),
|
|
546
609
|
...skippedNotifications(result),
|
|
547
610
|
...unenforcedNotifications(result),
|
|
611
|
+
...legacyStateDirNotifications(result),
|
|
548
612
|
];
|
|
549
613
|
// Notifications earn the run on their own. Before this, the umbrella run
|
|
550
614
|
// existed only when it had findings and a deferred gate was one; without
|
package/dist/output-text.js
CHANGED
|
@@ -23,6 +23,7 @@
|
|
|
23
23
|
// everywhere is worth more here than a nicer-looking terminal.
|
|
24
24
|
import { compareFindings } from './envelope.js';
|
|
25
25
|
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN } from './exit-codes.js';
|
|
26
|
+
import { isLegacyContractPath } from './intent-prepare.js';
|
|
26
27
|
function subjectLabel(finding) {
|
|
27
28
|
const subject = finding.subject;
|
|
28
29
|
switch (subject.kind) {
|
|
@@ -96,7 +97,10 @@ function contractLine(gate) {
|
|
|
96
97
|
}
|
|
97
98
|
const source = gate.intent.contractSource;
|
|
98
99
|
const where = source.kind === 'native'
|
|
99
|
-
?
|
|
100
|
+
? // The path already names the directory, and the aside says what a
|
|
101
|
+
// reader who has not followed intent-guard's releases cannot get from
|
|
102
|
+
// the path alone: that this is the old name and a newer gate moves it.
|
|
103
|
+
`the repository's own frozen ${source.path}${isLegacyContractPath(source.path) ? ' (pre-1.3 directory, still read)' : ''}`
|
|
100
104
|
: source.kind === 'imported'
|
|
101
105
|
? `spec ${source.spec}${source.plan === null ? '' : ` plus plan ${source.plan}`}`
|
|
102
106
|
: 'none';
|
|
@@ -188,7 +192,20 @@ function deferredLines(result) {
|
|
|
188
192
|
* the flow yet.
|
|
189
193
|
*/
|
|
190
194
|
function skippedLines(result) {
|
|
191
|
-
return result.skipped.map((gate) => ` skipped ${gate.role} ${gate.product}
|
|
195
|
+
return result.skipped.map((gate) => ` skipped ${gate.role} ${gate.product} ${skipWording(gate.reason).line}: ${gate.detail}`);
|
|
196
|
+
}
|
|
197
|
+
function skipWording(reason) {
|
|
198
|
+
return reason === 'contract-waived'
|
|
199
|
+
? {
|
|
200
|
+
line: 'spec waived',
|
|
201
|
+
verdict: 'had its spec waived by the pull request body',
|
|
202
|
+
summary: 'Spec waived by the pull request body',
|
|
203
|
+
}
|
|
204
|
+
: {
|
|
205
|
+
line: 'no contract',
|
|
206
|
+
verdict: 'had no contract to check against',
|
|
207
|
+
summary: 'Nothing to check against',
|
|
208
|
+
};
|
|
192
209
|
}
|
|
193
210
|
/**
|
|
194
211
|
* One line per gate the --gate flag left out.
|
|
@@ -247,9 +264,14 @@ function verdict(result) {
|
|
|
247
264
|
if (result.gates.length === 0 && result.skipped.length > 0) {
|
|
248
265
|
// A third distinct state, and telling somebody to switch a gate on is
|
|
249
266
|
// wrong advice here too: the gate IS on, it ran, and it had nothing to
|
|
250
|
-
// check.
|
|
251
|
-
|
|
252
|
-
|
|
267
|
+
// check. What to do about that is NOT the same in both cases, which is
|
|
268
|
+
// why the clause comes from the skip reason rather than being written
|
|
269
|
+
// here: for a missing spec the fix is to write one, and for a waiver
|
|
270
|
+
// there is nothing to fix, because a person decided it.
|
|
271
|
+
const clauses = result.skipped
|
|
272
|
+
.map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`)
|
|
273
|
+
.join(', ');
|
|
274
|
+
return `verdict: exit 0, nothing was checked: ${clauses}.`;
|
|
253
275
|
}
|
|
254
276
|
if (result.gates.length === 0) {
|
|
255
277
|
// Exit 0 with an empty report is indistinguishable from a clean run at a
|
|
@@ -373,9 +395,23 @@ function summaryLine(result) {
|
|
|
373
395
|
// Same reasoning as the deferred clause. A gate that ran and had nothing to
|
|
374
396
|
// check covered none of this commit, and silence there makes a branch with
|
|
375
397
|
// no spec read as a branch that passed the intent gate.
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
398
|
+
//
|
|
399
|
+
// One clause per REASON, not one clause for all of them. This line is the
|
|
400
|
+
// whole report on a clean run, which is what a pre-commit hook and a pull
|
|
401
|
+
// request comment print, so a shared "nothing to check against" would hide
|
|
402
|
+
// the difference between nobody having written a spec and somebody having
|
|
403
|
+
// decided there is none exactly where most readers stop reading. Grouped in
|
|
404
|
+
// first-seen order so the sentence does not reorder itself between runs.
|
|
405
|
+
const skippedByWording = new Map();
|
|
406
|
+
for (const gate of result.skipped) {
|
|
407
|
+
const lead = skipWording(gate.reason).summary;
|
|
408
|
+
skippedByWording.set(lead, [
|
|
409
|
+
...(skippedByWording.get(lead) ?? []),
|
|
410
|
+
`${gate.role} (${gate.product})`,
|
|
411
|
+
]);
|
|
412
|
+
}
|
|
413
|
+
for (const [lead, names] of skippedByWording) {
|
|
414
|
+
parts.push(`${lead}: ${names.join(', ')}.`);
|
|
379
415
|
}
|
|
380
416
|
// Same reasoning again, for the gates the command line left out. This one
|
|
381
417
|
// is the easiest of the three to lose: a --gate run is usually somebody
|
package/dist/run.d.ts
CHANGED
|
@@ -34,17 +34,24 @@ export interface ExcludedGate {
|
|
|
34
34
|
/**
|
|
35
35
|
* An enabled gate that had nothing to check.
|
|
36
36
|
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
37
|
+
* Two things produce this today, both of them an intent gate with no frozen
|
|
38
|
+
* contract: a branch with no spec to import (`no-contract`), and a pull
|
|
39
|
+
* request body that waived the spec with a `Spec: none` line
|
|
40
|
+
* (`contract-waived`). Neither is a deferred gate (nobody asked for a
|
|
41
|
+
* different stage), neither is a could-not-run (nothing broke), and neither
|
|
42
|
+
* must ever reach the exit code, enforced or not. A branch that has no spec
|
|
43
|
+
* is a branch this gate has no opinion about, and turning that into a failed
|
|
44
|
+
* build is how a gate gets switched off repository-wide.
|
|
45
|
+
*
|
|
46
|
+
* The reason is carried rather than flattened because the two ask different
|
|
47
|
+
* things of a reader: one wants a spec written, the other says a person
|
|
48
|
+
* already decided there is none. It is also the second half of the
|
|
49
|
+
* notification id in the SARIF log.
|
|
43
50
|
*/
|
|
44
51
|
export interface SkippedGate {
|
|
45
52
|
role: GateRole;
|
|
46
53
|
product: Product;
|
|
47
|
-
reason: 'no-contract';
|
|
54
|
+
reason: 'no-contract' | 'contract-waived';
|
|
48
55
|
detail: string;
|
|
49
56
|
}
|
|
50
57
|
export interface RunResult {
|
|
@@ -96,5 +103,12 @@ export interface RunOptions {
|
|
|
96
103
|
env?: NodeJS.ProcessEnv;
|
|
97
104
|
/** Injected in tests so a run's output is comparable between runs. */
|
|
98
105
|
now?: () => Date;
|
|
106
|
+
/**
|
|
107
|
+
* Where the intent gate's per-run temporary project is created. Injected
|
|
108
|
+
* in tests so the one that counts leaked directories counts its own and
|
|
109
|
+
* not another jest worker's; nothing in production passes it. See
|
|
110
|
+
* IntentPrepareOptions.tempRoot.
|
|
111
|
+
*/
|
|
112
|
+
tempRoot?: string;
|
|
99
113
|
}
|
|
100
114
|
export declare function runAll(policy: Policy, options: RunOptions): RunResult;
|
package/dist/run.js
CHANGED
|
@@ -79,6 +79,7 @@ export function runAll(policy, options) {
|
|
|
79
79
|
...(options.base === undefined ? {} : { base: options.base }),
|
|
80
80
|
...(options.spec === undefined ? {} : { spec: options.spec }),
|
|
81
81
|
...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
|
|
82
|
+
...(options.tempRoot === undefined ? {} : { tempRoot: options.tempRoot }),
|
|
82
83
|
});
|
|
83
84
|
if (prepared.kind === 'skip') {
|
|
84
85
|
skipped.push({
|