@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/README.md +305 -32
- package/dist/cli.js +214 -50
- package/dist/gate-runner.js +12 -2
- package/dist/normalize.d.ts +13 -2
- package/dist/normalize.js +137 -8
- package/dist/output-sarif.js +58 -0
- package/dist/output-text.d.ts +33 -0
- package/dist/output-text.js +139 -22
- package/dist/products.d.ts +16 -0
- package/dist/products.js +9 -0
- package/dist/run.d.ts +40 -0
- package/dist/run.js +39 -1
- package/dist/trust-base.d.ts +68 -0
- package/dist/trust-base.js +152 -0
- package/package.json +4 -3
package/dist/normalize.js
CHANGED
|
@@ -114,13 +114,42 @@ function readDiagnostics(value, product, where) {
|
|
|
114
114
|
};
|
|
115
115
|
});
|
|
116
116
|
}
|
|
117
|
-
|
|
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
|
|
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
|
-
|
|
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: {
|
|
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
|
};
|
package/dist/output-sarif.js
CHANGED
|
@@ -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
|
package/dist/output-text.d.ts
CHANGED
|
@@ -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.
|
package/dist/output-text.js
CHANGED
|
@@ -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 &&
|
|
396
|
-
|
|
397
|
-
//
|
|
398
|
-
//
|
|
399
|
-
//
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
//
|
|
405
|
-
//
|
|
406
|
-
//
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
.join(', ');
|
|
413
|
-
|
|
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
|
-
...
|
|
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
|
-
...
|
|
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 = [
|
|
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
|
}
|
package/dist/products.d.ts
CHANGED
|
@@ -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) {
|