@vaultcompass/conductor 0.13.0 → 0.14.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 +72 -13
- package/dist/cli.d.ts +38 -0
- package/dist/cli.js +77 -6
- package/dist/gate-runner.d.ts +86 -4
- package/dist/gate-runner.js +350 -78
- package/dist/output-sarif.d.ts +2 -2
- package/dist/output-sarif.js +47 -2
- package/dist/output-text.d.ts +37 -1
- package/dist/output-text.js +111 -21
- package/dist/policy-diff.d.ts +34 -0
- package/dist/policy-diff.js +173 -0
- package/dist/run.d.ts +63 -0
- package/dist/run.js +164 -22
- package/package.json +1 -1
- package/schema/guardrails.schema.json +1 -1
package/dist/output-sarif.js
CHANGED
|
@@ -118,10 +118,13 @@
|
|
|
118
118
|
// normalize.ts, which is where the omission would stop mattering if the
|
|
119
119
|
// field were ever carried.
|
|
120
120
|
import { gateExitBlocks } from './exit-codes.js';
|
|
121
|
+
import { cleanOutputLine } from './gate-runner.js';
|
|
121
122
|
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
122
123
|
import { INTENT_WARNING } from './normalize.js';
|
|
123
|
-
import { skewFound, skewPlace } from './output-text.js';
|
|
124
|
+
import { gateOutcomeWords, skewFound, skewPlace } from './output-text.js';
|
|
124
125
|
import { POLICY_FILE_NAME } from './policy.js';
|
|
126
|
+
import { policyChangeLine } from './policy-diff.js';
|
|
127
|
+
import { guardPreview } from './run.js';
|
|
125
128
|
const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
|
|
126
129
|
export const UMBRELLA_DRIVER_NAME = 'conductor';
|
|
127
130
|
/**
|
|
@@ -363,6 +366,16 @@ function notificationDeclarations(notifications) {
|
|
|
363
366
|
const ids = [...new Set(notifications.map((notification) => notification.id))].sort();
|
|
364
367
|
return ids.map((id) => ({ id, name: id.slice(id.indexOf('/') + 1) }));
|
|
365
368
|
}
|
|
369
|
+
/**
|
|
370
|
+
* The trust base as the log carries it: the per-key changes become their
|
|
371
|
+
* rendered lines (escaped and truncated), never the raw head values.
|
|
372
|
+
*/
|
|
373
|
+
function sarifTrustBase(trustBase) {
|
|
374
|
+
const { policyChanges, ...rest } = trustBase;
|
|
375
|
+
return policyChanges === undefined
|
|
376
|
+
? rest
|
|
377
|
+
: { ...rest, policyChanges: policyChanges.map(policyChangeLine) };
|
|
378
|
+
}
|
|
366
379
|
function makeRun(name, version, findings,
|
|
367
380
|
/** The artifact a result with no location of its own is filed against. */
|
|
368
381
|
fallbackUri, properties, invocation) {
|
|
@@ -695,6 +708,31 @@ function proposalNotifications(result) {
|
|
|
695
708
|
},
|
|
696
709
|
}));
|
|
697
710
|
}
|
|
711
|
+
/**
|
|
712
|
+
* The preview under the proposed rules, one note per preview gate.
|
|
713
|
+
*
|
|
714
|
+
* NOTES ONLY, and never a result, a rule, a fingerprint or a run: the
|
|
715
|
+
* preview decides nothing, so nothing of it may reach the alert list or the
|
|
716
|
+
* code scanning tab's identity for a finding. The caller appends these only
|
|
717
|
+
* to a notification list that is non-empty without them, so a preview never
|
|
718
|
+
* creates the umbrella's run, and executionSuccessful still reads only the
|
|
719
|
+
* primary gates. A throw here yields no preview notification at all.
|
|
720
|
+
*/
|
|
721
|
+
function previewNotifications(result) {
|
|
722
|
+
const preview = result.preview;
|
|
723
|
+
if (preview === undefined) {
|
|
724
|
+
return [];
|
|
725
|
+
}
|
|
726
|
+
return guardPreview(() => preview.gates.map((gate) => {
|
|
727
|
+
const outcome = cleanOutputLine(gateOutcomeWords(gate));
|
|
728
|
+
return {
|
|
729
|
+
id: 'conductor/preview-under-proposed-rules',
|
|
730
|
+
message: 'Preview under the proposed rules, which does not affect the verdict: ' +
|
|
731
|
+
`${gate.role} (${gate.product}) ${outcome}, ${gate.findings.length} finding(s).`,
|
|
732
|
+
details: { role: gate.role, product: gate.product, outcome, findings: gate.findings.length },
|
|
733
|
+
};
|
|
734
|
+
}), () => []);
|
|
735
|
+
}
|
|
698
736
|
/**
|
|
699
737
|
* The trust base the umbrella refused, when it refused one.
|
|
700
738
|
*
|
|
@@ -1043,6 +1081,11 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
1043
1081
|
...intentWarningNotifications(result),
|
|
1044
1082
|
...gateOwnOptionNotifications(result),
|
|
1045
1083
|
];
|
|
1084
|
+
// Only onto a list that is already non-empty: the preview never earns the
|
|
1085
|
+
// umbrella's run on its own.
|
|
1086
|
+
if (notifications.length > 0) {
|
|
1087
|
+
notifications.push(...previewNotifications(result));
|
|
1088
|
+
}
|
|
1046
1089
|
// Notifications earn the run on their own. Before this, the umbrella run
|
|
1047
1090
|
// existed only when it had findings and a deferred gate was one; without
|
|
1048
1091
|
// this clause a commit-stage log would say nothing whatever about the gate
|
|
@@ -1063,7 +1106,9 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
1063
1106
|
// fact about the whole run: every gate that could take the flag was
|
|
1064
1107
|
// handed this same ref. A consumer reading only the log can then tell
|
|
1065
1108
|
// a pull-request run from an ordinary one without parsing sentences.
|
|
1066
|
-
result.trustBase === null
|
|
1109
|
+
result.trustBase === null
|
|
1110
|
+
? undefined
|
|
1111
|
+
: { trustBase: sarifTrustBase(result.trustBase) }, {
|
|
1067
1112
|
// A claim about whether the analysis completed, taken from the
|
|
1068
1113
|
// gates rather than from the exit code: an unenforced gate that
|
|
1069
1114
|
// could not run leaves the run at exit 0, and nothing was checked
|
package/dist/output-text.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { type GateOutcome } from './gate-runner.js';
|
|
2
2
|
import type { ReportedMatch } from './intent-prepare.js';
|
|
3
|
-
import type
|
|
3
|
+
import { type RunResult } from './run.js';
|
|
4
4
|
/**
|
|
5
5
|
* How many entries a section prints before it rolls the rest up into one
|
|
6
6
|
* line, unless --verbose. A full-history gitleaks scan or an osv-scanner run
|
|
@@ -56,6 +56,42 @@ export declare function proposalCount(result: RunResult): string;
|
|
|
56
56
|
* not change.
|
|
57
57
|
*/
|
|
58
58
|
export declare function jobLogSummary(result: RunResult): string;
|
|
59
|
+
/**
|
|
60
|
+
* The proposal lines for a job log: the count sentence, then one line per
|
|
61
|
+
* proposed control change. Empty outside pull-request mode, and empty when
|
|
62
|
+
* the trust base was refused or never given, because no rules were read and
|
|
63
|
+
* there is nothing proposed to count. Each line goes through
|
|
64
|
+
* cleanOutputLine, since a proposal carries text a gate printed.
|
|
65
|
+
*/
|
|
66
|
+
export declare function proposalLogLines(result: RunResult): string[];
|
|
67
|
+
/**
|
|
68
|
+
* A gate's outcome in the job log's words: `ok`, `findings (N, M blocking)`
|
|
69
|
+
* with dep-guard's deadline clause when it said so, `could-not-run (reason)`
|
|
70
|
+
* or `missing (reason)`. Shared by the per-gate lines and the preview's.
|
|
71
|
+
*/
|
|
72
|
+
export declare function gateOutcomeWords(gate: GateOutcome): string;
|
|
73
|
+
/**
|
|
74
|
+
* The header the preview block starts with, in the report and the comment.
|
|
75
|
+
* scripts/lib/pr-comment.mjs spells it too, to cut the preview first from a
|
|
76
|
+
* comment over the limit, and action.yml stops its summary scan at it.
|
|
77
|
+
*/
|
|
78
|
+
export declare const PREVIEW_HEADER = "Preview under the proposed rules (does not affect the verdict)";
|
|
79
|
+
/**
|
|
80
|
+
* The preview under the proposed rules, as report lines: empty without a
|
|
81
|
+
* preview, otherwise a blank line, the header, the fixed-shape count line,
|
|
82
|
+
* one gate section per preview gate, then the deferred, over-budget, threw
|
|
83
|
+
* and advisory lines. Printed only AFTER the verdict line, and read by
|
|
84
|
+
* nothing that decides one. Every line goes through cleanOutputLine: a
|
|
85
|
+
* preview runs under head-proposed keys, so its gate text is not trusted to
|
|
86
|
+
* be free of a workflow command.
|
|
87
|
+
*/
|
|
88
|
+
export declare function previewLines(result: RunResult, verbose: boolean): string[];
|
|
89
|
+
/**
|
|
90
|
+
* The preview's job log lines: one per preview gate in the per-gate lines'
|
|
91
|
+
* outcome words, one per over-budget role, and one for a deferred intent
|
|
92
|
+
* gate. Empty without a preview. Each line goes through cleanOutputLine.
|
|
93
|
+
*/
|
|
94
|
+
export declare function previewLogLines(result: RunResult): string[];
|
|
59
95
|
/**
|
|
60
96
|
* One plain line per gate, for the job log: which gate, which version, what
|
|
61
97
|
* happened, and the exit code. Written to stderr by cli.ts on EVERY run, so
|
package/dist/output-text.js
CHANGED
|
@@ -26,6 +26,8 @@ import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, gateExitBlocks } from './exit-codes.j
|
|
|
26
26
|
import { CONDUCTOR_OWN_REASONS, cleanOutputLine, conductorStatedReason, resolutionPlace, versionCharacters, versionSkewRemedy, } from './gate-runner.js';
|
|
27
27
|
import { isLegacyContractPath, legacyChangedSentence } from './intent-prepare.js';
|
|
28
28
|
import { SPEC_DIR } from './intent-spec.js';
|
|
29
|
+
import { PRODUCT_FOR_ROLE } from './policy.js';
|
|
30
|
+
import { guardPreview } from './run.js';
|
|
29
31
|
function subjectLabel(finding) {
|
|
30
32
|
const subject = finding.subject;
|
|
31
33
|
switch (subject.kind) {
|
|
@@ -666,6 +668,107 @@ export function jobLogSummary(result) {
|
|
|
666
668
|
}
|
|
667
669
|
return `${result.gates.length} gate(s), ${result.findings.length} finding(s)`;
|
|
668
670
|
}
|
|
671
|
+
/**
|
|
672
|
+
* The proposal lines for a job log: the count sentence, then one line per
|
|
673
|
+
* proposed control change. Empty outside pull-request mode, and empty when
|
|
674
|
+
* the trust base was refused or never given, because no rules were read and
|
|
675
|
+
* there is nothing proposed to count. Each line goes through
|
|
676
|
+
* cleanOutputLine, since a proposal carries text a gate printed.
|
|
677
|
+
*/
|
|
678
|
+
export function proposalLogLines(result) {
|
|
679
|
+
const trust = result.trustBase;
|
|
680
|
+
if (trust === null || trust.notGiven === true || (trust.refusal !== null && trust.refusal !== undefined)) {
|
|
681
|
+
return [];
|
|
682
|
+
}
|
|
683
|
+
return [
|
|
684
|
+
cleanOutputLine(`conductor: ${proposalCount(result)}.`),
|
|
685
|
+
...result.proposals.map((proposal) => cleanOutputLine(`conductor: proposed ${proposal.product} ${proposal.line}`)),
|
|
686
|
+
];
|
|
687
|
+
}
|
|
688
|
+
/**
|
|
689
|
+
* A gate's outcome in the job log's words: `ok`, `findings (N, M blocking)`
|
|
690
|
+
* with dep-guard's deadline clause when it said so, `could-not-run (reason)`
|
|
691
|
+
* or `missing (reason)`. Shared by the per-gate lines and the preview's.
|
|
692
|
+
*/
|
|
693
|
+
export function gateOutcomeWords(gate) {
|
|
694
|
+
if (gate.couldNotRun !== null) {
|
|
695
|
+
const reason = gate.couldNotRun.reason;
|
|
696
|
+
return reason === 'binary-missing' || reason === 'configured-command-missing'
|
|
697
|
+
? `missing (${reason})`
|
|
698
|
+
: `could-not-run (${reason})`;
|
|
699
|
+
}
|
|
700
|
+
const total = gate.findings.length;
|
|
701
|
+
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
702
|
+
let outcome = total === 0 && (gate.exitCode ?? 0) === 0 ? 'ok' : `findings (${total}, ${blocking} blocking)`;
|
|
703
|
+
// Only when the gate said so; the outcome word above is unchanged.
|
|
704
|
+
const coverage = deadlineCoverage(gate);
|
|
705
|
+
if (coverage !== null) {
|
|
706
|
+
outcome += `, ${coverage}`;
|
|
707
|
+
}
|
|
708
|
+
return outcome;
|
|
709
|
+
}
|
|
710
|
+
/**
|
|
711
|
+
* The header the preview block starts with, in the report and the comment.
|
|
712
|
+
* scripts/lib/pr-comment.mjs spells it too, to cut the preview first from a
|
|
713
|
+
* comment over the limit, and action.yml stops its summary scan at it.
|
|
714
|
+
*/
|
|
715
|
+
export const PREVIEW_HEADER = 'Preview under the proposed rules (does not affect the verdict)';
|
|
716
|
+
/**
|
|
717
|
+
* The preview under the proposed rules, as report lines: empty without a
|
|
718
|
+
* preview, otherwise a blank line, the header, the fixed-shape count line,
|
|
719
|
+
* one gate section per preview gate, then the deferred, over-budget, threw
|
|
720
|
+
* and advisory lines. Printed only AFTER the verdict line, and read by
|
|
721
|
+
* nothing that decides one. Every line goes through cleanOutputLine: a
|
|
722
|
+
* preview runs under head-proposed keys, so its gate text is not trusted to
|
|
723
|
+
* be free of a workflow command.
|
|
724
|
+
*/
|
|
725
|
+
export function previewLines(result, verbose) {
|
|
726
|
+
const preview = result.preview;
|
|
727
|
+
if (preview === undefined) {
|
|
728
|
+
return [];
|
|
729
|
+
}
|
|
730
|
+
const body = guardPreview(() => {
|
|
731
|
+
const couldNotRun = preview.gates.filter((gate) => gate.couldNotRun !== null).length;
|
|
732
|
+
const lines = [
|
|
733
|
+
`preview: ${preview.gates.length} gate(s), ${preview.findings.length} finding(s), ${couldNotRun} could-not-run`,
|
|
734
|
+
...preview.gates.flatMap((gate) => gateSection(gate, verbose)),
|
|
735
|
+
...preview.skipped.map((skip) => `preview: ${skip.role} (${skip.product}) would not run: ${skip.reason}`),
|
|
736
|
+
];
|
|
737
|
+
if (preview.deferred.includes('intent')) {
|
|
738
|
+
lines.push('preview: intent (intent-guard) deferred, the preview does not prepare the intent gate');
|
|
739
|
+
}
|
|
740
|
+
if (preview.overBudget.length > 0) {
|
|
741
|
+
lines.push(`preview skipped: over budget (${preview.overBudget
|
|
742
|
+
.map((role) => `${role} (${PRODUCT_FOR_ROLE[role]})`)
|
|
743
|
+
.join(', ')})`);
|
|
744
|
+
}
|
|
745
|
+
if (preview.threw !== null) {
|
|
746
|
+
lines.push(`preview: could not be completed (${preview.threw})`);
|
|
747
|
+
}
|
|
748
|
+
if (couldNotRun > 0) {
|
|
749
|
+
lines.push(' a could-not-run in the preview is advisory: it does not change the exit code.');
|
|
750
|
+
}
|
|
751
|
+
return lines;
|
|
752
|
+
}, (message) => [`preview: could not be completed (${message})`]);
|
|
753
|
+
return ['', PREVIEW_HEADER, ...body].map(cleanOutputLine);
|
|
754
|
+
}
|
|
755
|
+
/**
|
|
756
|
+
* The preview's job log lines: one per preview gate in the per-gate lines'
|
|
757
|
+
* outcome words, one per over-budget role, and one for a deferred intent
|
|
758
|
+
* gate. Empty without a preview. Each line goes through cleanOutputLine.
|
|
759
|
+
*/
|
|
760
|
+
export function previewLogLines(result) {
|
|
761
|
+
const preview = result.preview;
|
|
762
|
+
if (preview === undefined) {
|
|
763
|
+
return [];
|
|
764
|
+
}
|
|
765
|
+
const lines = guardPreview(() => [
|
|
766
|
+
...preview.gates.map((gate) => `conductor: preview ${gate.role} (${gate.product}) ${gateOutcomeWords(gate)}`),
|
|
767
|
+
...preview.overBudget.map((role) => `conductor: preview ${role} (${PRODUCT_FOR_ROLE[role]}) over budget`),
|
|
768
|
+
...(preview.deferred.includes('intent') ? ['conductor: preview intent (intent-guard) deferred'] : []),
|
|
769
|
+
], (message) => [`conductor: preview could not be completed (${message})`]);
|
|
770
|
+
return lines.map(cleanOutputLine);
|
|
771
|
+
}
|
|
669
772
|
/**
|
|
670
773
|
* One plain line per gate, for the job log: which gate, which version, what
|
|
671
774
|
* happened, and the exit code. Written to stderr by cli.ts on EVERY run, so
|
|
@@ -699,25 +802,7 @@ export function gateLogLines(result, options = {}) {
|
|
|
699
802
|
for (const gate of result.gates) {
|
|
700
803
|
const version = gate.productVersion === null ? 'version unknown' : gate.productVersion;
|
|
701
804
|
const exit = gate.exitCode === null ? 'no exit code' : `exit ${gate.exitCode}`;
|
|
702
|
-
|
|
703
|
-
if (gate.couldNotRun !== null) {
|
|
704
|
-
const reason = gate.couldNotRun.reason;
|
|
705
|
-
outcome =
|
|
706
|
-
reason === 'binary-missing' || reason === 'configured-command-missing'
|
|
707
|
-
? `missing (${reason})`
|
|
708
|
-
: `could-not-run (${reason})`;
|
|
709
|
-
}
|
|
710
|
-
else {
|
|
711
|
-
const total = gate.findings.length;
|
|
712
|
-
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
713
|
-
outcome =
|
|
714
|
-
total === 0 && (gate.exitCode ?? 0) === 0 ? 'ok' : `findings (${total}, ${blocking} blocking)`;
|
|
715
|
-
// Only when the gate said so; the outcome word above is unchanged.
|
|
716
|
-
const coverage = deadlineCoverage(gate);
|
|
717
|
-
if (coverage !== null) {
|
|
718
|
-
outcome += `, ${coverage}`;
|
|
719
|
-
}
|
|
720
|
-
}
|
|
805
|
+
const outcome = gateOutcomeWords(gate);
|
|
721
806
|
// conductor's own refusals (a git below the floor, a path list it cannot
|
|
722
807
|
// pass, a PATH or git-directory failure, a gate below its minimum) carry
|
|
723
808
|
// their reason the same way, since no gate said anything for them.
|
|
@@ -1407,8 +1492,13 @@ export function renderText(result, options = {}) {
|
|
|
1407
1492
|
];
|
|
1408
1493
|
return `${lines.join('\n')}\n`;
|
|
1409
1494
|
}
|
|
1495
|
+
// The preview, when there is one, goes after everything else: after the
|
|
1496
|
+
// one-line summary here and after the verdict line below, so every report
|
|
1497
|
+
// line above it is byte for byte the same run's without one.
|
|
1498
|
+
const preview = previewLines(result, Boolean(options.verbose));
|
|
1499
|
+
const withPreview = (report) => preview.length === 0 ? report : `${report}${preview.join('\n')}\n`;
|
|
1410
1500
|
if (refusal.length === 0 && !options.verbose && isFullyClean(result)) {
|
|
1411
|
-
return `${summaryLine(result)}\n
|
|
1501
|
+
return withPreview(`${summaryLine(result)}\n`);
|
|
1412
1502
|
}
|
|
1413
1503
|
// Counted over EVERY gate, unenforced ones included, and deliberately not
|
|
1414
1504
|
// the same number the verdict prints. This line is an inventory of what
|
|
@@ -1464,5 +1554,5 @@ export function renderText(result, options = {}) {
|
|
|
1464
1554
|
lines.push('', '* severity assigned by the umbrella; that gate reports no per-finding severity.');
|
|
1465
1555
|
}
|
|
1466
1556
|
lines.push('', verdict(result, Boolean(options.advisory)));
|
|
1467
|
-
return `${lines.join('\n')}\n
|
|
1557
|
+
return withPreview(`${lines.join('\n')}\n`);
|
|
1468
1558
|
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import type { GateRole, Policy } from './policy.js';
|
|
2
|
+
export interface PolicyKeyChange {
|
|
3
|
+
/** The gate role the key belongs to, or null for a key outside any gate. */
|
|
4
|
+
role: GateRole | null;
|
|
5
|
+
/** The key in the file's own spelling, without the `gates.<role>.` prefix. */
|
|
6
|
+
key: string;
|
|
7
|
+
old: unknown;
|
|
8
|
+
new: unknown;
|
|
9
|
+
}
|
|
10
|
+
export declare const HEAD_POLICY_KEY = ".guardrails.yaml";
|
|
11
|
+
/**
|
|
12
|
+
* Every key whose value differs, gates in GATE_ROLES order and `report.format`
|
|
13
|
+
* last. `excludedByCli` is never compared: it is the run's own flag, not the
|
|
14
|
+
* file's. A null head (absent or unparseable) is one change that says so.
|
|
15
|
+
*/
|
|
16
|
+
export declare function diffPolicies(base: Policy, head: Policy | null): PolicyKeyChange[];
|
|
17
|
+
/** One proposal line for one changed key. */
|
|
18
|
+
export declare function policyChangeLine(change: PolicyKeyChange): string;
|
|
19
|
+
/**
|
|
20
|
+
* The roles a preview under the proposed rules runs: every role with an
|
|
21
|
+
* `enabled` or `stage` change, in GATE_ROLES order. A role whose only changes
|
|
22
|
+
* are `enforce` or keys the preview takes from the base would preview as the
|
|
23
|
+
* primary run again, so it is left out, and so is `report.format`.
|
|
24
|
+
*/
|
|
25
|
+
export declare function previewRoles(changes: PolicyKeyChange[]): GateRole[];
|
|
26
|
+
/**
|
|
27
|
+
* The policy a preview runs under. Only `enabled`, `stage` and `enforce` come
|
|
28
|
+
* from the head: `command`, `args`, `options`, `timeout-seconds` and
|
|
29
|
+
* `present-on-base` come from the base role, or, for a role only the head
|
|
30
|
+
* has, from what the policy file gives for its product alone. A role the head
|
|
31
|
+
* removed is the base role switched off. Only the roles in `roles` are held,
|
|
32
|
+
* with the base `report`.
|
|
33
|
+
*/
|
|
34
|
+
export declare function previewPolicy(base: Policy, head: Policy, roles: GateRole[]): Policy;
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
// The per-key difference between the base policy and the head policy.
|
|
2
|
+
//
|
|
3
|
+
// Pull-request mode reports a changed `.guardrails.yaml` as a proposal and
|
|
4
|
+
// never acts on it. This file only turns "it differs" into "these keys
|
|
5
|
+
// differ", so a reader sees which gate, which key, and the old and new value
|
|
6
|
+
// without opening the diff. Both arguments are parsed documents; the head is
|
|
7
|
+
// parsed for this comparison and never reaches the run that decides the
|
|
8
|
+
// verdict. The one place a head value goes further is `previewPolicy`, which
|
|
9
|
+
// takes only `enabled`, `stage` and `enforce` from it for the preview under
|
|
10
|
+
// the proposed rules, a run that decides nothing.
|
|
11
|
+
import { GATE_ROLES, PRODUCT_FOR_ROLE, parsePolicy } from './policy.js';
|
|
12
|
+
export const HEAD_POLICY_KEY = '.guardrails.yaml';
|
|
13
|
+
const MAX_VALUE_LENGTH = 80;
|
|
14
|
+
/** The keys of one gate in the order they are compared and reported. */
|
|
15
|
+
function gateKeys(gate, optionNames) {
|
|
16
|
+
const get = (key) => {
|
|
17
|
+
if (gate === undefined)
|
|
18
|
+
return undefined;
|
|
19
|
+
switch (key) {
|
|
20
|
+
case 'product':
|
|
21
|
+
return gate.product;
|
|
22
|
+
case 'enabled':
|
|
23
|
+
return gate.enabled;
|
|
24
|
+
case 'stage':
|
|
25
|
+
return gate.stage;
|
|
26
|
+
case 'enforce':
|
|
27
|
+
return gate.enforce;
|
|
28
|
+
case 'command':
|
|
29
|
+
return gate.command;
|
|
30
|
+
case 'args':
|
|
31
|
+
return gate.args;
|
|
32
|
+
case 'present-on-base':
|
|
33
|
+
return gate.presentOnBase;
|
|
34
|
+
case 'timeout-seconds':
|
|
35
|
+
return gate.timeoutSeconds;
|
|
36
|
+
default:
|
|
37
|
+
{
|
|
38
|
+
const name = key.slice('options.'.length);
|
|
39
|
+
return Object.hasOwn(gate.options, name) ? gate.options[name] : undefined;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
};
|
|
43
|
+
const keys = [
|
|
44
|
+
'product',
|
|
45
|
+
'enabled',
|
|
46
|
+
'stage',
|
|
47
|
+
'enforce',
|
|
48
|
+
'command',
|
|
49
|
+
'args',
|
|
50
|
+
...optionNames.map((name) => `options.${name}`),
|
|
51
|
+
'present-on-base',
|
|
52
|
+
'timeout-seconds',
|
|
53
|
+
];
|
|
54
|
+
return keys.map((key) => [key, get(key)]);
|
|
55
|
+
}
|
|
56
|
+
function same(a, b) {
|
|
57
|
+
return JSON.stringify(a) === JSON.stringify(b);
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Every key whose value differs, gates in GATE_ROLES order and `report.format`
|
|
61
|
+
* last. `excludedByCli` is never compared: it is the run's own flag, not the
|
|
62
|
+
* file's. A null head (absent or unparseable) is one change that says so.
|
|
63
|
+
*/
|
|
64
|
+
export function diffPolicies(base, head) {
|
|
65
|
+
if (head === null) {
|
|
66
|
+
return [{ role: null, key: HEAD_POLICY_KEY, old: 'present', new: null }];
|
|
67
|
+
}
|
|
68
|
+
const changes = [];
|
|
69
|
+
for (const role of GATE_ROLES) {
|
|
70
|
+
const b = base.gates[role];
|
|
71
|
+
const h = head.gates[role];
|
|
72
|
+
if (b === undefined && h === undefined)
|
|
73
|
+
continue;
|
|
74
|
+
const names = [
|
|
75
|
+
...new Set([...Object.keys(b?.options ?? {}), ...Object.keys(h?.options ?? {})]),
|
|
76
|
+
].sort();
|
|
77
|
+
const baseKeys = gateKeys(b, names);
|
|
78
|
+
const headKeys = gateKeys(h, names);
|
|
79
|
+
baseKeys.forEach(([key, oldValue], i) => {
|
|
80
|
+
const newValue = headKeys[i]?.[1];
|
|
81
|
+
if (!same(oldValue, newValue))
|
|
82
|
+
changes.push({ role, key, old: oldValue, new: newValue });
|
|
83
|
+
});
|
|
84
|
+
}
|
|
85
|
+
if (base.report.format !== head.report.format) {
|
|
86
|
+
changes.push({
|
|
87
|
+
role: null,
|
|
88
|
+
key: 'report.format',
|
|
89
|
+
old: base.report.format,
|
|
90
|
+
new: head.report.format,
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
return changes;
|
|
94
|
+
}
|
|
95
|
+
function renderValue(value) {
|
|
96
|
+
if (value === undefined)
|
|
97
|
+
return '(absent)';
|
|
98
|
+
const text = JSON.stringify(value) ?? '(absent)';
|
|
99
|
+
// Every character outside printable ASCII becomes a \uXXXX escape (an
|
|
100
|
+
// astral character as its two surrogate escapes), so a head option value
|
|
101
|
+
// cannot smuggle a bidi override or a zero-width character into the report.
|
|
102
|
+
const escaped = text.replace(/[^\x20-\x7e]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
|
|
103
|
+
if (escaped.length <= MAX_VALUE_LENGTH)
|
|
104
|
+
return escaped;
|
|
105
|
+
// Keep whole tokens up to 77 characters, so no escape sequence is split.
|
|
106
|
+
let kept = '';
|
|
107
|
+
for (const token of escaped.match(/\\u[0-9a-f]{4}|\\.|[^\\]/g) ?? []) {
|
|
108
|
+
if (kept.length + token.length > MAX_VALUE_LENGTH - 3)
|
|
109
|
+
break;
|
|
110
|
+
kept += token;
|
|
111
|
+
}
|
|
112
|
+
return `${kept}...`;
|
|
113
|
+
}
|
|
114
|
+
/** One proposal line for one changed key. */
|
|
115
|
+
export function policyChangeLine(change) {
|
|
116
|
+
if (change.key === HEAD_POLICY_KEY) {
|
|
117
|
+
// One text for every case where the head's keys cannot be read: the file
|
|
118
|
+
// is absent, it is not YAML, it parses as YAML but fails policy
|
|
119
|
+
// validation, or git could not read it at all.
|
|
120
|
+
return `policy: the head ${HEAD_POLICY_KEY} is absent or does not parse, so its changes are not known`;
|
|
121
|
+
}
|
|
122
|
+
const where = change.role === null ? change.key : `gates.${change.role}.${change.key}`;
|
|
123
|
+
return `policy: ${where} ${renderValue(change.old)} -> ${renderValue(change.new)}`;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* The roles a preview under the proposed rules runs: every role with an
|
|
127
|
+
* `enabled` or `stage` change, in GATE_ROLES order. A role whose only changes
|
|
128
|
+
* are `enforce` or keys the preview takes from the base would preview as the
|
|
129
|
+
* primary run again, so it is left out, and so is `report.format`.
|
|
130
|
+
*/
|
|
131
|
+
export function previewRoles(changes) {
|
|
132
|
+
const wanted = new Set(changes
|
|
133
|
+
.filter((change) => change.role !== null && (change.key === 'enabled' || change.key === 'stage'))
|
|
134
|
+
.map((change) => change.role));
|
|
135
|
+
return GATE_ROLES.filter((role) => wanted.has(role));
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* The policy a preview runs under. Only `enabled`, `stage` and `enforce` come
|
|
139
|
+
* from the head: `command`, `args`, `options`, `timeout-seconds` and
|
|
140
|
+
* `present-on-base` come from the base role, or, for a role only the head
|
|
141
|
+
* has, from what the policy file gives for its product alone. A role the head
|
|
142
|
+
* removed is the base role switched off. Only the roles in `roles` are held,
|
|
143
|
+
* with the base `report`.
|
|
144
|
+
*/
|
|
145
|
+
export function previewPolicy(base, head, roles) {
|
|
146
|
+
const gates = {};
|
|
147
|
+
for (const role of GATE_ROLES) {
|
|
148
|
+
if (!roles.includes(role))
|
|
149
|
+
continue;
|
|
150
|
+
const b = base.gates[role];
|
|
151
|
+
const h = head.gates[role];
|
|
152
|
+
if (h === undefined) {
|
|
153
|
+
if (b !== undefined)
|
|
154
|
+
gates[role] = { ...b, enabled: false };
|
|
155
|
+
continue;
|
|
156
|
+
}
|
|
157
|
+
const from = b ?? productDefault(role);
|
|
158
|
+
gates[role] = { ...from, enabled: h.enabled, stage: h.stage, enforce: h.enforce };
|
|
159
|
+
}
|
|
160
|
+
return { version: 1, gates, report: base.report };
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* The gate parsePolicy gives for `product: <product>` alone, built by
|
|
164
|
+
* parsePolicy itself so its defaults have one source. The product is
|
|
165
|
+
* PRODUCT_FOR_ROLE's, which parsePolicy already required the head to match.
|
|
166
|
+
*/
|
|
167
|
+
function productDefault(role) {
|
|
168
|
+
const gate = parsePolicy(`version: 1\ngates:\n ${role}:\n product: ${PRODUCT_FOR_ROLE[role]}\n`, 'the preview default').gates[role];
|
|
169
|
+
if (gate === undefined) {
|
|
170
|
+
throw new Error(`no default gate for the ${role} role`);
|
|
171
|
+
}
|
|
172
|
+
return gate;
|
|
173
|
+
}
|
package/dist/run.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ import { type Finding } from './envelope.js';
|
|
|
2
2
|
import { type GateOutcome } from './gate-runner.js';
|
|
3
3
|
import type { SelectionMiss } from './intent-spec.js';
|
|
4
4
|
import type { GateRole, GateStage, Policy, Product } from './policy.js';
|
|
5
|
+
import type { PolicyKeyChange } from './policy-diff.js';
|
|
5
6
|
/**
|
|
6
7
|
* An enabled gate the stage filter held back.
|
|
7
8
|
*
|
|
@@ -113,6 +114,15 @@ export interface RunTrustBase {
|
|
|
113
114
|
ref: string;
|
|
114
115
|
/** Whether the head commit's own policy file differs from that one. */
|
|
115
116
|
policyChanged: boolean;
|
|
117
|
+
/**
|
|
118
|
+
* The keys that differ, when `policyChanged` is true: one entry per key,
|
|
119
|
+
* computed from the parsed base and head files before any CLI override.
|
|
120
|
+
* Empty or absent on a changed policy means no effective key differs (a
|
|
121
|
+
* default spelled out, or the YAML reordered), and the report falls back to
|
|
122
|
+
* the one-line POLICY_PROPOSAL_LINE. A head whose keys are not known is not
|
|
123
|
+
* an empty list: it is the single not-known entry.
|
|
124
|
+
*/
|
|
125
|
+
policyChanges?: PolicyKeyChange[];
|
|
116
126
|
/**
|
|
117
127
|
* Why this ref could not be used at all, or null when it was.
|
|
118
128
|
*
|
|
@@ -201,6 +211,35 @@ export interface RunResult {
|
|
|
201
211
|
bySeverity: Record<string, number>;
|
|
202
212
|
};
|
|
203
213
|
exitCode: number;
|
|
214
|
+
/**
|
|
215
|
+
* The preview under the proposed rules: the roles whose `enabled` or
|
|
216
|
+
* `stage` the pull request changes, run once more under those keys. It
|
|
217
|
+
* decides nothing: computed after every field above is fixed, and never
|
|
218
|
+
* read back by any of them. Absent, not empty, when the run was not asked
|
|
219
|
+
* for one.
|
|
220
|
+
*/
|
|
221
|
+
preview?: RunPreview;
|
|
222
|
+
}
|
|
223
|
+
/** The whole preview's hard deadline (spec 5.2, finding 2). */
|
|
224
|
+
export declare const PREVIEW_BUDGET_MS = 300000;
|
|
225
|
+
/** A preview role that did not run, and why: the run's --stage, enabled: false, or --gate. */
|
|
226
|
+
export interface PreviewSkipped {
|
|
227
|
+
role: GateRole;
|
|
228
|
+
product: Product;
|
|
229
|
+
reason: 'stage' | 'disabled' | 'excluded';
|
|
230
|
+
}
|
|
231
|
+
/** What the preview under the proposed rules did. */
|
|
232
|
+
export interface RunPreview {
|
|
233
|
+
gates: GateOutcome[];
|
|
234
|
+
/** Every preview finding, ordered as the primary run's are. */
|
|
235
|
+
findings: Finding[];
|
|
236
|
+
skipped: PreviewSkipped[];
|
|
237
|
+
/** The intent role, when enabled: the preview never prepares it (finding 9). */
|
|
238
|
+
deferred: GateRole[];
|
|
239
|
+
/** The gate reached with no budget left, and every gate after it. */
|
|
240
|
+
overBudget: GateRole[];
|
|
241
|
+
/** The preview threw: its message, cleaned and cut to 200 characters. */
|
|
242
|
+
threw: string | null;
|
|
204
243
|
}
|
|
205
244
|
export interface RunOptions {
|
|
206
245
|
repoRoot: string;
|
|
@@ -247,6 +286,17 @@ export interface RunOptions {
|
|
|
247
286
|
* IntentPrepareOptions.tempRoot.
|
|
248
287
|
*/
|
|
249
288
|
tempRoot?: string;
|
|
289
|
+
/**
|
|
290
|
+
* The preview under the proposed rules, run after the primary result is
|
|
291
|
+
* fixed. Its policy is built by the caller (`previewPolicy`, which takes
|
|
292
|
+
* only `enabled`, `stage` and `enforce` from the head). Absent means no
|
|
293
|
+
* preview, which is every run without --preview.
|
|
294
|
+
*/
|
|
295
|
+
preview?: {
|
|
296
|
+
policy: Policy;
|
|
297
|
+
};
|
|
298
|
+
/** A test hook: the preview's clock. No CLI path sets it; absent is Date.now. */
|
|
299
|
+
previewClock?: () => number;
|
|
250
300
|
}
|
|
251
301
|
/**
|
|
252
302
|
* The run that never happened, because the trust base could not be judged
|
|
@@ -276,4 +326,17 @@ export declare function refusedTrustBase(policy: Policy, ref: string, detail: st
|
|
|
276
326
|
now?: () => Date;
|
|
277
327
|
notGiven?: boolean;
|
|
278
328
|
}): RunResult;
|
|
329
|
+
/**
|
|
330
|
+
* Runs `work`, and turns any throw into `fallback(message)`, the message
|
|
331
|
+
* cleaned for a log line and cut to 200 characters. Never rethrows: nothing
|
|
332
|
+
* the preview does may reach the verdict, and a throw would (spec 5.2,
|
|
333
|
+
* finding 3).
|
|
334
|
+
*/
|
|
335
|
+
export declare function guardPreview<T>(work: () => T, fallback: (message: string) => T): T;
|
|
336
|
+
/**
|
|
337
|
+
* The preview under the proposed rules: each role of `policy` run once more,
|
|
338
|
+
* with the primary run's own options, trust base included, under one hard
|
|
339
|
+
* deadline. The intent role is deferred and never prepared.
|
|
340
|
+
*/
|
|
341
|
+
export declare function runPreview(policy: Policy, options: RunOptions): RunPreview;
|
|
279
342
|
export declare function runAll(policy: Policy, options: RunOptions): RunResult;
|