@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.
@@ -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: `${gate.product}/no-contract`,
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
@@ -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
- ? `the repository's own frozen ${source.path}`
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} no contract: ${gate.detail}`);
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. The fix is a spec, which the skipped line above names.
251
- const names = result.skipped.map((gate) => gate.role).join(', ');
252
- return `verdict: exit 0, nothing was checked: ${names} had no contract to check against.`;
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
- if (result.skipped.length > 0) {
377
- const names = result.skipped.map((gate) => `${gate.role} (${gate.product})`).join(', ');
378
- parts.push(`Nothing to check against: ${names}.`);
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
- * Exactly one thing produces this today: an intent gate on a branch with no
38
- * frozen contract and no spec to import. It is not a deferred gate (nobody
39
- * asked for a different stage), it is not a could-not-run (nothing broke),
40
- * and it must never reach the exit code, enforced or not. A branch that has
41
- * no spec is a branch this gate has no opinion about, and turning that into
42
- * a failed build is how a gate gets switched off repository-wide.
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({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "license": "MIT",