@vaultcompass/conductor 0.5.0 → 0.7.0

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/dist/normalize.js CHANGED
@@ -114,13 +114,42 @@ function readDiagnostics(value, product, where) {
114
114
  };
115
115
  });
116
116
  }
117
- export function normalizeDepGuard(raw, version) {
117
+ function readOnlineInfo(value) {
118
+ if (!isRecord(value)) {
119
+ return null;
120
+ }
121
+ const info = {};
122
+ if (value.enabled !== undefined) {
123
+ if (typeof value.enabled !== 'boolean') {
124
+ return null;
125
+ }
126
+ info.enabled = value.enabled;
127
+ }
128
+ if (value.lookupsAttempted !== undefined) {
129
+ if (typeof value.lookupsAttempted !== 'number' || !Number.isFinite(value.lookupsAttempted)) {
130
+ return null;
131
+ }
132
+ info.lookupsAttempted = value.lookupsAttempted;
133
+ }
134
+ if (value.lookupsSkippedByDeadline !== undefined) {
135
+ if (typeof value.lookupsSkippedByDeadline !== 'number' ||
136
+ !Number.isFinite(value.lookupsSkippedByDeadline)) {
137
+ return null;
138
+ }
139
+ info.lookupsSkippedByDeadline = value.lookupsSkippedByDeadline;
140
+ }
141
+ return info;
142
+ }
143
+ export function normalizeDepGuard(raw, version,
144
+ /** Whether the umbrella passed --online to dep-guard, read from its own argv. */
145
+ onlineRequested = false) {
118
146
  const product = 'dep-guard';
119
147
  const root = needRecord(raw, product, 'the output');
120
148
  const run = needRecord(root.run, product, 'run');
121
149
  const threshold = optionalString(run.failOn, product, 'run.failOn') ?? null;
122
150
  const trustBase = readTrustBase(root.trustBase, product);
123
151
  const diagnostics = [];
152
+ const onlineInfo = readOnlineInfo(run.online);
124
153
  const findings = needArray(root.findings, product, 'findings').map((entry, index) => {
125
154
  const where = `findings[${index}]`;
126
155
  const source = needRecord(entry, product, where);
@@ -167,12 +196,34 @@ export function normalizeDepGuard(raw, version) {
167
196
  suppressed: typeof root.suppressed === 'number' ? root.suppressed : 0,
168
197
  ignored: typeof root.ignored === 'number' ? root.ignored : 0,
169
198
  // Diagnostics never move dep-guard's own exit code, so they stay out
170
- // of findings[] here too rather than becoming pseudo-findings.
199
+ // of findings[] here too rather than becoming pseudo-findings. An
200
+ // installed dep-guard old enough to have no `run.online` object, or
201
+ // one whose online object says the budget ran out, raises its own
202
+ // online-deadline-exceeded diagnostic here, and it is carried through
203
+ // unchanged rather than the umbrella minting a second note about the
204
+ // same event (issue #72 fix round: dep-guard's own diagnostic already
205
+ // names the count, so nothing here duplicates it).
171
206
  diagnostics: readDiagnostics(run.diagnostics, product, 'run.diagnostics'),
172
207
  details: {
173
208
  mode: run.mode ?? null,
174
209
  corpusBuiltAt: run.corpusBuiltAt ?? null,
175
210
  lockfileFormat: run.lockfileFormat ?? null,
211
+ // dep-guard's own `enabled` claim wins whenever the online object is
212
+ // present and valid: dep-guard can turn online checks on from
213
+ // ".dep-guard.json"'s own "online" key with no flag at all, so the
214
+ // umbrella's argv does not always know the true answer. Only when
215
+ // there is no trustworthy claim to read does this fall back to
216
+ // stating what the umbrella itself asked for, worded so it is never
217
+ // mistaken for a claim about what dep-guard actually did.
218
+ ...(onlineInfo?.enabled === undefined
219
+ ? { 'online-flag': onlineRequested ? 'passed' : 'not passed' }
220
+ : { online: onlineInfo.enabled }),
221
+ ...(onlineInfo?.lookupsAttempted === undefined
222
+ ? {}
223
+ : { lookups: onlineInfo.lookupsAttempted }),
224
+ ...(onlineInfo?.lookupsSkippedByDeadline === undefined
225
+ ? {}
226
+ : { 'skipped-by-deadline': onlineInfo.lookupsSkippedByDeadline }),
176
227
  },
177
228
  },
178
229
  diagnostics,
@@ -331,6 +382,57 @@ const DRIFT_SEVERITY = {
331
382
  info: 'low',
332
383
  proceed: 'info',
333
384
  };
385
+ /**
386
+ * intent-guard's own namespace for its advance-notice warnings, not the
387
+ * umbrella's: the umbrella never mints a `conductor/` id for this, because
388
+ * the statement being relayed is entirely intent-guard's own (see AGENTS.md
389
+ * on the umbrella's fixed set of ids).
390
+ */
391
+ export const INTENT_WARNING = 'intent-guard/warning';
392
+ /**
393
+ * intent-guard 1.7.0's own advance notice that a frozen contract's
394
+ * `protected_paths` or `allowed_paths` carries an entry no git path can
395
+ * ever match (a leading slash, an empty path segment, and the like), read
396
+ * from the optional `warnings` array. 1.7.0 warns about this; 2.0.0 turns it
397
+ * into a blocking reason (intent-guard's own budget-paths.ts).
398
+ *
399
+ * Tolerant on purpose, unlike everything else this file validates: this is
400
+ * reporting, never judgment, so a shape an installed intent-guard did not
401
+ * send correctly must never turn into a could-not-run for the gate. Absent
402
+ * (1.6.0 and earlier, which never sent this field) means none. A value that
403
+ * is not an array, or an array holding even one non-string entry, is
404
+ * ignored outright rather than partially read: half-reading it would print
405
+ * some warnings and silently drop others, which is worse than saying
406
+ * nothing until the shape is understood again.
407
+ */
408
+ function readIntentWarnings(raw) {
409
+ if (!Array.isArray(raw)) {
410
+ return [];
411
+ }
412
+ return raw.every((entry) => typeof entry === 'string') ? raw : [];
413
+ }
414
+ /**
415
+ * intent-guard 1.6.0 (issue #34) caps a constraint finding at advisory when
416
+ * its `source` is a prose rules file (CLAUDE.md, AGENTS.md, GEMINI.md,
417
+ * cursor rules): a strong match is still reported, but it never raises
418
+ * `constraint_violation`, `criticalViolated`, or the gate's own exit code.
419
+ *
420
+ * `finding_details` carries no field saying so. `strength` is "strong" for a
421
+ * capped prose match exactly the same as an uncapped one, and the
422
+ * constraint's `source` is never carried onto the finding at all. The ONLY
423
+ * surviving signal is this literal prefix, which intent-guard's own drift.ts
424
+ * puts on the message for this one case.
425
+ *
426
+ * THIS IS NOT A SAFETY NET. Nothing in this repository detects an upstream
427
+ * rewording of that prefix: there is no test against the live binary, only
428
+ * a static fixture capture, so a wording change in a future intent-guard
429
+ * release would silently stop matching here and a capped finding would go
430
+ * back to rendering as blocking with no warning anywhere in this report or
431
+ * in CI. Filed upstream as intent-guard #114, asking for a machine-readable
432
+ * per-finding field so this can stop keying on message text; this constant
433
+ * is the interim measure until that lands, not a substitute for it.
434
+ */
435
+ const ADVISORY_CONSTRAINT_PREFIX = 'advisory ';
334
436
  /**
335
437
  * The three ways the intent gate can block on the STATE of the contract
336
438
  * rather than on anything in the diff.
@@ -432,6 +534,7 @@ export function normalizeIntentGuard(raw, version) {
432
534
  fail(product, 'status', 'either "ok" or "blocked"');
433
535
  }
434
536
  const trustBase = readTrustBase(root.trustBase, product);
537
+ const warnings = readIntentWarnings(root.warnings);
435
538
  const findings = [];
436
539
  const budget = root.budget === undefined ? undefined : needRecord(root.budget, product, 'budget');
437
540
  const drift = root.drift === undefined ? undefined : needRecord(root.drift, product, 'drift');
@@ -486,6 +589,11 @@ export function normalizeIntentGuard(raw, version) {
486
589
  const where = `drift.finding_details[${index}]`;
487
590
  const detail = needRecord(rawDetail, product, where);
488
591
  const category = needString(detail.category, product, `${where}.category`);
592
+ const message = needString(detail.message, product, `${where}.message`);
593
+ // See ADVISORY_CONSTRAINT_PREFIX. A capped finding never contributed to
594
+ // driftAction, so it must not inherit that action's blocking flag or
595
+ // severity the way every other drift finding here does (issue #34).
596
+ const advisoryCapped = category === 'constraint_violation' && message.startsWith(ADVISORY_CONSTRAINT_PREFIX);
489
597
  findings.push({
490
598
  schemaVersion: 1,
491
599
  product,
@@ -494,10 +602,10 @@ export function normalizeIntentGuard(raw, version) {
494
602
  // rule id that contains a user's sentence is not a rule id. The full
495
603
  // value goes in details.
496
604
  ruleId: `intent-guard/drift.${category}`,
497
- severity: DRIFT_SEVERITY[driftAction] ?? 'info',
605
+ severity: advisoryCapped ? 'low' : (DRIFT_SEVERITY[driftAction] ?? 'info'),
498
606
  severityIsDerived: true,
499
- blocking: driftBlocks,
500
- message: needString(detail.message, product, `${where}.message`),
607
+ blocking: advisoryCapped ? false : driftBlocks,
608
+ message,
501
609
  // No paths subject: `matched` here is "tokens or paths", so treating
502
610
  // it as a path list would sometimes point at a file that does not
503
611
  // exist. It stays in details, where it is not claiming to be a location.
@@ -577,7 +685,10 @@ export function normalizeIntentGuard(raw, version) {
577
685
  failOn: null,
578
686
  suppressed: 0,
579
687
  ignored: 0,
580
- diagnostics: [],
688
+ // intent-guard's own advance-notice warnings (1.7.0's budget-path
689
+ // deprecation notes). Reporting, never a finding: no severity, no
690
+ // fingerprint, no blocking flag, and no effect on the exit code.
691
+ diagnostics: warnings.map((message) => ({ code: INTENT_WARNING, message })),
581
692
  details: {
582
693
  contractFound: root.contractFound ?? null,
583
694
  contractFrozen: root.contractFrozen ?? null,
@@ -823,9 +934,21 @@ function relativeToRoots(file, roots) {
823
934
  }
824
935
  return file;
825
936
  }
937
+ /**
938
+ * The vulnerabilities summary line's lockfile fact (issue #72): the count and
939
+ * names of the lockfiles the UMBRELLA handed osv-scanner with --lockfile,
940
+ * never osv-scanner's own results[], which 2.x prints only for a source with
941
+ * findings. A clean scan of one lockfile and a run that scanned none both
942
+ * have results: [], and only this list tells them apart.
943
+ */
944
+ function describeLockfiles(lockfiles) {
945
+ return lockfiles.length === 0 ? '0' : `${lockfiles.length} (${lockfiles.join(', ')})`;
946
+ }
826
947
  export function normalizeOsvScanner(raw, version, blocked,
827
948
  /** The scan root as a path osv-scanner may have printed it, in any spelling. */
828
- roots = []) {
949
+ roots = [],
950
+ /** The lockfiles the umbrella passed with --lockfile, repository-relative. */
951
+ lockfiles = []) {
829
952
  const product = 'osv-scanner';
830
953
  const top = needRecord(raw, product, 'the output');
831
954
  const results = needArray(top.results, product, 'results');
@@ -888,7 +1011,13 @@ roots = []) {
888
1011
  suppressed: 0,
889
1012
  ignored: 0,
890
1013
  diagnostics: [],
891
- details: { sources: results.length },
1014
+ details: {
1015
+ lockfiles: describeLockfiles(lockfiles),
1016
+ // Distinct from the old "sources" name on purpose: this counts only
1017
+ // the sources osv-scanner reported findings for, never how many were
1018
+ // scanned, and the old name read as the latter.
1019
+ 'sources-with-findings': results.length,
1020
+ },
892
1021
  },
893
1022
  diagnostics: [],
894
1023
  };
@@ -118,6 +118,7 @@
118
118
  // normalize.ts, which is where the omission would stop mattering if the
119
119
  // field were ever carried.
120
120
  import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
121
+ import { INTENT_WARNING } from './normalize.js';
121
122
  import { POLICY_FILE_NAME } from './policy.js';
122
123
  const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
123
124
  export const UMBRELLA_DRIVER_NAME = 'conductor';
@@ -499,6 +500,25 @@ function excludedNotifications(result) {
499
500
  details: { role: gate.role, product: gate.product },
500
501
  }));
501
502
  }
503
+ /**
504
+ * The gates skipped because the head tree equals the trust base's tree, as
505
+ * notifications (issue #69).
506
+ *
507
+ * Same discriminator as excludedNotifications just above: how much of the
508
+ * policy this run covered is a statement about the run, not about anybody's
509
+ * code, so it is a NOTE and never a result. Reachable only on the one
510
+ * accepted equal-tree shape (a merge commit whose first parent is the trust
511
+ * base; see trust-base.ts), where every enabled gate whose profile does not
512
+ * say readsHistory is recorded here instead of being spawned.
513
+ */
514
+ function treeUnchangedNotifications(result) {
515
+ return result.treeUnchanged.map((gate) => ({
516
+ id: 'conductor/tree-unchanged',
517
+ message: `The ${gate.role} gate (${gate.product}) did not run: the head tree is identical to the ` +
518
+ 'base tree, so there is no change for this gate to judge.',
519
+ details: { role: gate.role, product: gate.product },
520
+ }));
521
+ }
502
522
  /**
503
523
  * The gates that had nothing to check, as notifications.
504
524
  *
@@ -552,6 +572,36 @@ function skippedNotifications(result) {
552
572
  details: { role: gate.role, product: gate.product, reason: gate.reason },
553
573
  }));
554
574
  }
575
+ /**
576
+ * intent-guard 1.7.0's own advance-notice warnings, as notifications.
577
+ *
578
+ * A frozen contract's protected_paths or allowed_paths entry that no git
579
+ * path can ever match is a statement about that contract's own
580
+ * configuration, in the same sense skippedNotifications above already
581
+ * describes: nothing went wrong with this commit, nobody's code is at
582
+ * fault, and the statement is true of every run against this contract until
583
+ * it is edited. As a result it belongs beside no-contract and the rest, a
584
+ * notification rather than a result, so it never gains a severity, a
585
+ * fingerprint, or a place in the exit code.
586
+ *
587
+ * Read off `run.diagnostics` rather than `diagnostics`, deliberately: this
588
+ * repository's `diagnostics` field is the umbrella's OWN fixed set of ids
589
+ * (see AGENTS.md), and intent-guard/warning is not one of them. It is the
590
+ * gate's own statement, carried through unchanged, the same way
591
+ * dep-guard's online-deadline-exceeded diagnostic already prints under the
592
+ * gate in the text report; this is the SARIF half of that same channel,
593
+ * scoped to intent-guard's own warning code so a future run-diagnostic on
594
+ * another gate does not silently start appearing here too.
595
+ */
596
+ function intentWarningNotifications(result) {
597
+ return result.gates.flatMap((gate) => gate.run.diagnostics
598
+ .filter((diagnostic) => diagnostic.code === INTENT_WARNING)
599
+ .map((diagnostic) => ({
600
+ id: diagnostic.code,
601
+ message: diagnostic.message,
602
+ details: { role: gate.role, product: gate.product },
603
+ })));
604
+ }
555
605
  /**
556
606
  * The control inputs this pull request proposes to change, as notifications.
557
607
  *
@@ -810,6 +860,12 @@ export function renderSarif(result, umbrellaVersion) {
810
860
  ...(gate.intent === undefined
811
861
  ? {}
812
862
  : { contractSource: gate.intent.contractSource, baseRef: gate.intent.baseRef }),
863
+ // The gate's own run facts (issue #72: the lockfiles the umbrella
864
+ // handed osv-scanner, and dep-guard's online-lookup reporting), the
865
+ // same bag the text report renders as scalars. Carried verbatim and
866
+ // only when there is something in it, so a gate that reports none of
867
+ // this keeps the properties shape it had before.
868
+ ...(Object.keys(gate.run.details).length === 0 ? {} : { details: gate.run.details }),
813
869
  }));
814
870
  }
815
871
  // Still RESULTS, deliberately, and the asymmetry with the three above is
@@ -828,6 +884,7 @@ export function renderSarif(result, umbrellaVersion) {
828
884
  const notifications = [
829
885
  ...deferredNotifications(result),
830
886
  ...excludedNotifications(result),
887
+ ...treeUnchangedNotifications(result),
831
888
  ...skippedNotifications(result),
832
889
  ...unenforcedNotifications(result),
833
890
  ...legacyStateDirNotifications(result),
@@ -836,6 +893,7 @@ export function renderSarif(result, umbrellaVersion) {
836
893
  ...proposalNotifications(result),
837
894
  ...trustBaseWithheldNotifications(result),
838
895
  ...nodeModulesSkippedNotifications(result),
896
+ ...intentWarningNotifications(result),
839
897
  ];
840
898
  // Notifications earn the run on their own. Before this, the umbrella run
841
899
  // existed only when it had findings and a deferred gate was one; without
@@ -25,6 +25,39 @@ import type { RunResult } from './run.js';
25
25
  * not change.
26
26
  */
27
27
  export declare function jobLogSummary(result: RunResult): string;
28
+ /**
29
+ * The verdict token: a label for the umbrella's OWN exit decision, in a
30
+ * closed set, so a person or a script reading a report or a job summary gets
31
+ * the state without parsing the verdict sentence.
32
+ *
33
+ * pass exit 0 and nothing was hidden by it
34
+ * advisory-blocked (N) exit 1 that --advisory turned into exit 0
35
+ * unenforced-findings (N) exit 0, but enforce: false gates blocked or
36
+ * could not run
37
+ * blocked (N) exit 1
38
+ * could-not-run exit 2, a refused trust base included
39
+ *
40
+ * PRECEDENCE, when several apply: could-not-run, then blocked or
41
+ * advisory-blocked, then unenforced-findings, then pass. So an advisory run
42
+ * whose only blocking findings sit on an unenforced gate is
43
+ * unenforced-findings and never advisory-blocked: --advisory did nothing
44
+ * there, and saying it did would be a false statement of what was hidden.
45
+ *
46
+ * This decides nothing. Every branch reads the exit code composeExitCode
47
+ * already produced (result.exitCode) and the enforce flags already on the
48
+ * gates; the only counting is over what those gates said. It never
49
+ * overrules a gate. It is also the same `advisory` boolean cli.ts hands to
50
+ * applyAdvisory, so the label and the process exit code cannot disagree.
51
+ *
52
+ * A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
53
+ * than result.gates, is neither a blocking finding nor a could-not-run, and
54
+ * so does not by itself move the token off pass. The verdict sentence is
55
+ * where "nothing was checked" is said.
56
+ *
57
+ * Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
58
+ * not a pass.
59
+ */
60
+ export declare function verdictToken(result: RunResult, advisory: boolean): string;
28
61
  export interface TextOptions {
29
62
  /**
30
63
  * Print the full report even when the run is fully clean.
@@ -218,6 +218,18 @@ function skipWording(reason) {
218
218
  function excludedLines(result) {
219
219
  return result.excluded.map((gate) => ` excluded ${gate.role} ${gate.product} did not run here; --gate did not name it`);
220
220
  }
221
+ /**
222
+ * One line per gate skipped because the head tree equals the trust base's
223
+ * (issue #69).
224
+ *
225
+ * Modeled on deferredLines and excludedLines just above: nothing ran for
226
+ * these gates either, so there is no header, no exit code and no duration to
227
+ * put in a section, and the reason has to be on screen or a run in this shape
228
+ * reads exactly like a run that judged every enabled gate's tree.
229
+ */
230
+ function treeUnchangedLines(result) {
231
+ return result.treeUnchanged.map((gate) => ` tree-unchanged ${gate.role} ${gate.product} did not run: the head tree is identical to the base tree, so there is no change for this gate to judge`);
232
+ }
221
233
  /**
222
234
  * The one sentence the whole of pull-request mode has to fit into.
223
235
  *
@@ -370,6 +382,72 @@ export function jobLogSummary(result) {
370
382
  }
371
383
  return `${result.gates.length} gate(s), ${result.findings.length} finding(s)`;
372
384
  }
385
+ /**
386
+ * How many blocking findings one gate that RAN is carrying, for the token.
387
+ *
388
+ * A gate that exited non-zero with nothing on screen marked blocking (the
389
+ * mismatch shape the verdict sentence already has its own wording for) counts
390
+ * as one, so a state that is not a pass never prints a count of zero. A gate
391
+ * that could not run is not counted here at all: its findings list carries
392
+ * the umbrella's own blocking gate-missing finding, and counting that as well
393
+ * would report one broken gate as two things.
394
+ */
395
+ function blockingCount(gate) {
396
+ if (gate.couldNotRun !== null) {
397
+ return 0;
398
+ }
399
+ const blocking = gate.findings.filter((finding) => finding.blocking).length;
400
+ return blocking === 0 && (gate.exitCode ?? 0) !== 0 ? 1 : blocking;
401
+ }
402
+ /**
403
+ * The verdict token: a label for the umbrella's OWN exit decision, in a
404
+ * closed set, so a person or a script reading a report or a job summary gets
405
+ * the state without parsing the verdict sentence.
406
+ *
407
+ * pass exit 0 and nothing was hidden by it
408
+ * advisory-blocked (N) exit 1 that --advisory turned into exit 0
409
+ * unenforced-findings (N) exit 0, but enforce: false gates blocked or
410
+ * could not run
411
+ * blocked (N) exit 1
412
+ * could-not-run exit 2, a refused trust base included
413
+ *
414
+ * PRECEDENCE, when several apply: could-not-run, then blocked or
415
+ * advisory-blocked, then unenforced-findings, then pass. So an advisory run
416
+ * whose only blocking findings sit on an unenforced gate is
417
+ * unenforced-findings and never advisory-blocked: --advisory did nothing
418
+ * there, and saying it did would be a false statement of what was hidden.
419
+ *
420
+ * This decides nothing. Every branch reads the exit code composeExitCode
421
+ * already produced (result.exitCode) and the enforce flags already on the
422
+ * gates; the only counting is over what those gates said. It never
423
+ * overrules a gate. It is also the same `advisory` boolean cli.ts hands to
424
+ * applyAdvisory, so the label and the process exit code cannot disagree.
425
+ *
426
+ * A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
427
+ * than result.gates, is neither a blocking finding nor a could-not-run, and
428
+ * so does not by itself move the token off pass. The verdict sentence is
429
+ * where "nothing was checked" is said.
430
+ *
431
+ * Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
432
+ * not a pass.
433
+ */
434
+ export function verdictToken(result, advisory) {
435
+ const refusal = result.trustBase?.refusal;
436
+ const refused = refusal !== undefined && refusal !== null;
437
+ if (refused || (result.exitCode !== 0 && result.exitCode !== EXIT_BLOCKED)) {
438
+ return 'could-not-run';
439
+ }
440
+ if (result.exitCode === EXIT_BLOCKED) {
441
+ const count = result.gates
442
+ .filter((gate) => gate.enforce)
443
+ .reduce((total, gate) => total + blockingCount(gate), 0);
444
+ return advisory ? `advisory-blocked (${count})` : `blocked (${count})`;
445
+ }
446
+ const unenforced = result.gates
447
+ .filter((gate) => !gate.enforce)
448
+ .reduce((total, gate) => total + (gate.couldNotRun !== null ? 1 : blockingCount(gate)), 0);
449
+ return unenforced > 0 ? `unenforced-findings (${unenforced})` : 'pass';
450
+ }
373
451
  function verdict(result, advisory) {
374
452
  const refusal = result.trustBase?.refusal;
375
453
  if (refusal !== undefined && refusal !== null) {
@@ -392,25 +470,40 @@ function verdictForRun(result, advisory) {
392
470
  const blocking = enforcedGates
393
471
  .flatMap((gate) => gate.findings)
394
472
  .filter((finding) => finding.blocking).length;
395
- if (result.gates.length === 0 && result.deferred.length > 0) {
396
- // Distinct from "none is enabled" below. A policy file with everything
397
- // switched off and a stage with nothing to do at it are two different
398
- // states, and telling somebody to set enabled: true is the wrong advice
399
- // for the second one.
400
- const names = result.deferred.map((gate) => `${gate.role} at stage ${gate.stage}`).join(', ');
401
- return `verdict: exit 0, nothing ran at this stage: every enabled gate is deferred (${names}).`;
402
- }
403
- if (result.gates.length === 0 && result.skipped.length > 0) {
404
- // A third distinct state, and telling somebody to switch a gate on is
405
- // wrong advice here too: the gate IS on, it ran, and it had nothing to
406
- // check. What to do about that is NOT the same in both cases, which is
407
- // why the clause comes from the skip reason rather than being written
408
- // here: for a missing spec the fix is to write one, and for a waiver
409
- // there is nothing to fix, because a person decided it.
410
- const clauses = result.skipped
411
- .map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`)
412
- .join(', ');
413
- return `verdict: exit 0, nothing was checked: ${clauses}.`;
473
+ if (result.gates.length === 0 &&
474
+ (result.deferred.length > 0 || result.treeUnchanged.length > 0 || result.skipped.length > 0)) {
475
+ // Three distinct states can each leave result.gates empty, and a run can
476
+ // land in more than one of them at once: a stage that deferred one gate
477
+ // while another was tree-unchanged (issue #69) is a real shape, not a
478
+ // hypothetical, so this names EVERY one that applies rather than the
479
+ // first one found. Naming only "every enabled gate is deferred" when a
480
+ // tree-unchanged gate was also in the mix would be false: not every gate
481
+ // was deferred, some had nothing to judge for a different reason. All
482
+ // three are also distinct from "none is enabled" below, and each needs
483
+ // its own fix: set enabled: true is wrong for all three of them, since
484
+ // every gate named here IS enabled.
485
+ const clauses = [];
486
+ if (result.deferred.length > 0) {
487
+ // Never "every enabled gate is deferred" here: that claim is only true
488
+ // when nothing else in this branch fired, and a mix with a
489
+ // tree-unchanged or skipped gate makes it false.
490
+ const names = result.deferred.map((gate) => `${gate.role} at stage ${gate.stage}`).join(', ');
491
+ clauses.push(`deferred to a later stage (${names})`);
492
+ }
493
+ if (result.treeUnchanged.length > 0) {
494
+ // The head tree is identical to the trust base's, so there is nothing
495
+ // for these gates to judge (issue #69).
496
+ const names = result.treeUnchanged.map((gate) => gate.role).join(', ');
497
+ clauses.push(`the head tree is identical to the base tree, so there is no change for these gates to judge (${names})`);
498
+ }
499
+ if (result.skipped.length > 0) {
500
+ // What to do about this is NOT the same for every reason, which is why
501
+ // the clause comes from the skip reason rather than being written
502
+ // here: for a missing spec the fix is to write one, and for a waiver
503
+ // there is nothing to fix, because a person decided it.
504
+ clauses.push(result.skipped.map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`).join(', '));
505
+ }
506
+ return `verdict: exit 0, nothing was checked: ${clauses.join('; ')}.`;
414
507
  }
415
508
  if (result.gates.length === 0) {
416
509
  // Exit 0 with an empty report is indistinguishable from a clean run at a
@@ -552,6 +645,13 @@ function summaryLine(result) {
552
645
  .join(', ');
553
646
  parts.push(`Deferred to a later stage: ${names}.`);
554
647
  }
648
+ // Same reasoning as the deferred clause, for the equal-tree shape
649
+ // (issue #69): these gates are enabled and did not run, so a clean run in
650
+ // this shape must not read like a run that judged their tree too.
651
+ if (result.treeUnchanged.length > 0) {
652
+ const names = result.treeUnchanged.map((gate) => `${gate.role} (${gate.product})`).join(', ');
653
+ parts.push(`Tree unchanged from the trust base, skipped: ${names}.`);
654
+ }
555
655
  // Same reasoning as the deferred clause. A gate that ran and had nothing to
556
656
  // check covered none of this commit, and silence there makes a branch with
557
657
  // no spec read as a branch that passed the intent gate.
@@ -664,6 +764,18 @@ function summaryLine(result) {
664
764
  function versionLine(version) {
665
765
  return version === undefined ? [] : [`conductor ${version}`];
666
766
  }
767
+ /**
768
+ * The version line, then the verdict-token line directly under it: the first
769
+ * two lines of every report that carries a token. Without a version the
770
+ * token is the first line. The closing verdict sentence is a separate thing
771
+ * and stays where it was.
772
+ */
773
+ function headerLines(result, options) {
774
+ return [
775
+ ...versionLine(options.version),
776
+ `verdict-token: ${verdictToken(result, Boolean(options.advisory))}`,
777
+ ];
778
+ }
667
779
  export function renderText(result, options = {}) {
668
780
  const refusal = refusalLines(result);
669
781
  if (options.compact === true && refusal.length > 0) {
@@ -674,7 +786,7 @@ export function renderText(result, options = {}) {
674
786
  // proposal) as part of the same sentence. Nothing here points at a step
675
787
  // log: the reason has to be readable on the comment itself.
676
788
  const lines = [
677
- ...versionLine(options.version),
789
+ ...headerLines(result, options),
678
790
  verdict(result, Boolean(options.advisory)),
679
791
  ...refusal,
680
792
  ];
@@ -692,7 +804,7 @@ export function renderText(result, options = {}) {
692
804
  // different questions, so two numbers, and the section headers and the
693
805
  // "not enforced" lines are what connect them.
694
806
  const lines = [
695
- ...versionLine(options.version),
807
+ ...headerLines(result, options),
696
808
  ...refusal,
697
809
  ...(refusal.length === 0 ? [] : ['']),
698
810
  `conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
@@ -700,7 +812,12 @@ export function renderText(result, options = {}) {
700
812
  for (const gate of result.gates) {
701
813
  lines.push(...gateSection(gate));
702
814
  }
703
- const aside = [...deferredLines(result), ...skippedLines(result), ...excludedLines(result)];
815
+ const aside = [
816
+ ...deferredLines(result),
817
+ ...skippedLines(result),
818
+ ...excludedLines(result),
819
+ ...treeUnchangedLines(result),
820
+ ];
704
821
  if (aside.length > 0) {
705
822
  lines.push('', ...aside);
706
823
  }
@@ -67,6 +67,22 @@ export interface ProductProfile {
67
67
  * materialised from the base ref and the tool is run from that directory.
68
68
  */
69
69
  followsConfigExtend: boolean;
70
+ /**
71
+ * Whether this gate's INPUT is git history rather than the tree being
72
+ * judged.
73
+ *
74
+ * True only for gitleaks. Every other gate here reads the tree (vault-guard
75
+ * and dep-guard scan files, intent-guard reads a diff of paths) or a
76
+ * lockfile in it (osv-scanner), so when the head tree is byte-identical to
77
+ * the trust base's -- issue #69's shape, a value committed and then backed
78
+ * out inside one pull request -- those gates have nothing to judge that the
79
+ * base ref did not already judge, and the umbrella skips them rather than
80
+ * reporting a clean scan of a change that is not there. gitleaks' report is
81
+ * about commits between the base and HEAD, not about either tree, so it is
82
+ * the one gate an equal tree does not blind: see `decideTrustBase` and the
83
+ * equal-tree branch in `runAll` (src/run.ts).
84
+ */
85
+ readsHistory: boolean;
70
86
  }
71
87
  /**
72
88
  * The lockfiles osv-scanner is handed, matched by base name at any depth
package/dist/products.js CHANGED
@@ -57,6 +57,7 @@ function managedProfile(product) {
57
57
  stderrError: null,
58
58
  lockfileNames: null,
59
59
  followsConfigExtend: false,
60
+ readsHistory: false,
60
61
  };
61
62
  }
62
63
  const PROFILES = {
@@ -94,6 +95,11 @@ const PROFILES = {
94
95
  stderrError: /^\S+\s+ERR\s/,
95
96
  lockfileNames: null,
96
97
  followsConfigExtend: true,
98
+ // gitleaks reads git history (--log-opts), never the tree, which is
99
+ // exactly what makes it the one gate an equal-tree pull request does not
100
+ // blind (issue #69): the history between the base and HEAD still holds
101
+ // whatever was committed and backed out, even when the two trees match.
102
+ readsHistory: true,
97
103
  },
98
104
  'osv-scanner': {
99
105
  product: 'osv-scanner',
@@ -116,6 +122,9 @@ const PROFILES = {
116
122
  stderrError: null,
117
123
  lockfileNames: OSV_LOCKFILE_NAMES,
118
124
  followsConfigExtend: false,
125
+ // osv-scanner reads the tracked lockfiles it is handed, which are the
126
+ // tree being judged, not history.
127
+ readsHistory: false,
119
128
  },
120
129
  };
121
130
  export function profileFor(product) {