@vaultcompass/conductor 0.2.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/LICENSE +21 -0
- package/README.md +412 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.js +231 -0
- package/dist/envelope.d.ts +105 -0
- package/dist/envelope.js +75 -0
- package/dist/exit-codes.d.ts +30 -0
- package/dist/exit-codes.js +67 -0
- package/dist/gate-runner.d.ts +97 -0
- package/dist/gate-runner.js +354 -0
- package/dist/init.d.ts +138 -0
- package/dist/init.js +973 -0
- package/dist/intent-base.d.ts +54 -0
- package/dist/intent-base.js +135 -0
- package/dist/intent-prepare.d.ts +57 -0
- package/dist/intent-prepare.js +297 -0
- package/dist/intent-spec.d.ts +62 -0
- package/dist/intent-spec.js +268 -0
- package/dist/normalize.d.ts +58 -0
- package/dist/normalize.js +582 -0
- package/dist/output-sarif.d.ts +34 -0
- package/dist/output-sarif.js +564 -0
- package/dist/output-text.d.ts +12 -0
- package/dist/output-text.js +448 -0
- package/dist/policy.d.ts +126 -0
- package/dist/policy.js +328 -0
- package/dist/resolve.d.ts +52 -0
- package/dist/resolve.js +207 -0
- package/dist/run.d.ts +100 -0
- package/dist/run.js +147 -0
- package/package.json +43 -0
- package/schema/guardrails.schema.json +88 -0
|
@@ -0,0 +1,448 @@
|
|
|
1
|
+
// The combined report, for a terminal.
|
|
2
|
+
//
|
|
3
|
+
// One section per gate in gate order, findings within a gate ordered
|
|
4
|
+
// blocking-first, and a one-line verdict at the end. Three things are in
|
|
5
|
+
// here deliberately rather than for completeness:
|
|
6
|
+
//
|
|
7
|
+
// - Each gate's own threshold is printed in its own section, because
|
|
8
|
+
// there is no shared one and printing a single number would imply there
|
|
9
|
+
// was.
|
|
10
|
+
//
|
|
11
|
+
// - The suppressed and ignored counts are printed even when they are
|
|
12
|
+
// zero. Those numbers are the user's own earlier decisions, and hiding
|
|
13
|
+
// them makes a repository with two hundred baselined findings read as
|
|
14
|
+
// clean.
|
|
15
|
+
//
|
|
16
|
+
// - A gate that could not run gets a loud section rather than an empty
|
|
17
|
+
// one. An empty section and a clean section look identical at a glance,
|
|
18
|
+
// and that is exactly the confusion that lets a switched-on gate sit
|
|
19
|
+
// uninstalled for months.
|
|
20
|
+
//
|
|
21
|
+
// No colour and no unicode. This output is read in a pre-commit hook, in
|
|
22
|
+
// CI logs, and in pasted issue reports, and the plainest thing that works
|
|
23
|
+
// everywhere is worth more here than a nicer-looking terminal.
|
|
24
|
+
import { compareFindings } from './envelope.js';
|
|
25
|
+
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN } from './exit-codes.js';
|
|
26
|
+
function subjectLabel(finding) {
|
|
27
|
+
const subject = finding.subject;
|
|
28
|
+
switch (subject.kind) {
|
|
29
|
+
case 'package':
|
|
30
|
+
return `${subject.name} (${subject.manifest})`;
|
|
31
|
+
case 'location':
|
|
32
|
+
return `${subject.file}:${subject.line}:${subject.column}`;
|
|
33
|
+
case 'paths':
|
|
34
|
+
return subject.paths.join(', ');
|
|
35
|
+
case 'contract':
|
|
36
|
+
return subject.category === undefined ? 'intent contract' : `contract: ${subject.category}`;
|
|
37
|
+
case 'none':
|
|
38
|
+
return '';
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
function findingLines(finding) {
|
|
42
|
+
const marker = finding.blocking ? 'BLOCKING' : ' report';
|
|
43
|
+
const severity = finding.severityIsDerived ? `${finding.severity}*` : finding.severity;
|
|
44
|
+
const subject = subjectLabel(finding);
|
|
45
|
+
const head = ` ${marker} ${severity.padEnd(9)} ${finding.ruleId}${subject === '' ? '' : ` ${subject}`}`;
|
|
46
|
+
return [head, ` ${finding.message}`];
|
|
47
|
+
}
|
|
48
|
+
function header(gate) {
|
|
49
|
+
const version = gate.productVersion === null ? '(version unknown)' : gate.productVersion;
|
|
50
|
+
// On the header line rather than only at the bottom of the section: a
|
|
51
|
+
// reader scanning headers for the gate that refused their commit has to
|
|
52
|
+
// be able to see, in the same glance, that this one did not.
|
|
53
|
+
const enforcement = gate.enforce ? '' : ' [not enforced]';
|
|
54
|
+
if (gate.couldNotRun !== null) {
|
|
55
|
+
return `${gate.role} ${gate.product} ${version} DID NOT RUN (${gate.couldNotRun.reason})${enforcement}`;
|
|
56
|
+
}
|
|
57
|
+
const source = gate.binary === null ? '' : ` via ${gate.binary.candidate} on ${gate.binary.source}`;
|
|
58
|
+
return `${gate.role} ${gate.product} ${version} exit ${gate.exitCode ?? '?'} ${gate.durationMs}ms${source}${enforcement}`;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* The line that keeps a green exit from being a surprise.
|
|
62
|
+
*
|
|
63
|
+
* A report with BLOCKING on it and exit 0 at the bottom reads as a bug in
|
|
64
|
+
* the umbrella unless the reason is on the same screen, in words rather
|
|
65
|
+
* than in a flag somebody has to go and look up in the policy file.
|
|
66
|
+
*/
|
|
67
|
+
function enforcementNote(gate) {
|
|
68
|
+
if (gate.enforce) {
|
|
69
|
+
return null;
|
|
70
|
+
}
|
|
71
|
+
if (gate.couldNotRun !== null) {
|
|
72
|
+
return (` not enforced: this gate could not run, and enforce is false for it in .guardrails.yaml, ` +
|
|
73
|
+
'so it is a note here rather than a failed run. Nothing was checked by it.');
|
|
74
|
+
}
|
|
75
|
+
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
76
|
+
if (blocking > 0 || (gate.exitCode ?? 0) !== 0) {
|
|
77
|
+
return (` not enforced: this gate reported ${blocking} blocking finding(s) and exited ` +
|
|
78
|
+
`${gate.exitCode ?? '?'}, and enforce is false for it in .guardrails.yaml, so the commit ` +
|
|
79
|
+
'proceeds. Set enforce: true there to make it block.');
|
|
80
|
+
}
|
|
81
|
+
return ' not enforced: enforce is false for this gate in .guardrails.yaml. It found nothing to block on here.';
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Where the intent gate's contract came from, and what it measured against.
|
|
85
|
+
*
|
|
86
|
+
* Both halves are on one line and both are always printed when there is a
|
|
87
|
+
* prepared run, including the base. A reader looking at a drift finding has
|
|
88
|
+
* to be able to tell "checked the branch against main using the spec" from
|
|
89
|
+
* "checked the index against a contract in the repository" without opening
|
|
90
|
+
* the policy file or the CI configuration, because those are two different
|
|
91
|
+
* claims and only one of them is about the pull request.
|
|
92
|
+
*/
|
|
93
|
+
function contractLine(gate) {
|
|
94
|
+
if (gate.intent === undefined) {
|
|
95
|
+
return null;
|
|
96
|
+
}
|
|
97
|
+
const source = gate.intent.contractSource;
|
|
98
|
+
const where = source.kind === 'native'
|
|
99
|
+
? `the repository's own frozen ${source.path}`
|
|
100
|
+
: source.kind === 'imported'
|
|
101
|
+
? `spec ${source.spec}${source.plan === null ? '' : ` plus plan ${source.plan}`}`
|
|
102
|
+
: 'none';
|
|
103
|
+
const base = gate.intent.baseRef === null ? 'base: none, the git index' : `base: ${gate.intent.baseRef}`;
|
|
104
|
+
return ` contract: ${where} ${base}`;
|
|
105
|
+
}
|
|
106
|
+
function gateSection(gate) {
|
|
107
|
+
const lines = ['', header(gate)];
|
|
108
|
+
const contract = contractLine(gate);
|
|
109
|
+
if (contract !== null) {
|
|
110
|
+
lines.push(contract);
|
|
111
|
+
}
|
|
112
|
+
if (gate.couldNotRun !== null) {
|
|
113
|
+
lines.push(` ${gate.couldNotRun.detail}`);
|
|
114
|
+
if (gate.stderr.trim().length > 0) {
|
|
115
|
+
for (const line of gate.stderr.trim().split('\n')) {
|
|
116
|
+
lines.push(` | ${line}`);
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
// Sorted here rather than relying on the order the gate happened to emit:
|
|
121
|
+
// blocking first, then by severity. A section whose first line is a low
|
|
122
|
+
// finding buries the one that just refused a commit.
|
|
123
|
+
for (const finding of [...gate.findings].sort(compareFindings)) {
|
|
124
|
+
lines.push(...findingLines(finding));
|
|
125
|
+
}
|
|
126
|
+
if (gate.couldNotRun === null) {
|
|
127
|
+
const threshold = gate.run.failOn === null ? 'threshold not reported' : `threshold ${gate.run.failOn}`;
|
|
128
|
+
// "ignored 0" would state a fact the gate never stated for a gate that
|
|
129
|
+
// drops ignored files before they reach its output, and it reads as
|
|
130
|
+
// "nothing was ignored". The normalizer records which is which.
|
|
131
|
+
const ignored = gate.run.details.ignoredReported === false
|
|
132
|
+
? 'ignored not reported'
|
|
133
|
+
: `ignored ${gate.run.ignored}`;
|
|
134
|
+
lines.push(` ${threshold} suppressed ${gate.run.suppressed} ${ignored}`);
|
|
135
|
+
// The gate's own run facts: what it scanned, with what, against what.
|
|
136
|
+
// These were being collected and then dropped.
|
|
137
|
+
//
|
|
138
|
+
// Scalars only. String() on an object gives "[object Object]", and on an
|
|
139
|
+
// empty array gives nothing at all, so a naive render produced both a
|
|
140
|
+
// line of noise and a key with no value. The structured members of this
|
|
141
|
+
// bag (a category breakdown, a reason list) are already in the SARIF
|
|
142
|
+
// details and, for the reasons, in a finding of their own; a terminal
|
|
143
|
+
// summary line is not where they belong.
|
|
144
|
+
const facts = Object.entries(gate.run.details)
|
|
145
|
+
.filter(([key, value]) =>
|
|
146
|
+
// ignoredReported drives the line above rather than being a fact
|
|
147
|
+
// about the run, so it is not printed twice.
|
|
148
|
+
key !== 'ignoredReported' &&
|
|
149
|
+
(typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') &&
|
|
150
|
+
value !== '')
|
|
151
|
+
.map(([key, value]) => `${key} ${String(value)}`);
|
|
152
|
+
if (facts.length > 0) {
|
|
153
|
+
lines.push(` ${facts.join(' ')}`);
|
|
154
|
+
}
|
|
155
|
+
for (const diagnostic of gate.run.diagnostics) {
|
|
156
|
+
lines.push(` note ${diagnostic.code}: ${diagnostic.message}`);
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
for (const diagnostic of gate.diagnostics) {
|
|
160
|
+
lines.push(` ! ${diagnostic.code}: ${diagnostic.message}`);
|
|
161
|
+
}
|
|
162
|
+
// Last in the section, so it is the line under the findings it explains.
|
|
163
|
+
const enforcement = enforcementNote(gate);
|
|
164
|
+
if (enforcement !== null) {
|
|
165
|
+
lines.push(enforcement);
|
|
166
|
+
}
|
|
167
|
+
return lines;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* One line per gate the stage filter held back.
|
|
171
|
+
*
|
|
172
|
+
* Deliberately not a section: nothing ran, so there is no header, no exit
|
|
173
|
+
* code and no duration to put in one. It still has to be on screen, because
|
|
174
|
+
* a run at the commit stage otherwise reads exactly like a run that checked
|
|
175
|
+
* everything, and the whole point of a stage is that some gates did not.
|
|
176
|
+
*/
|
|
177
|
+
function deferredLines(result) {
|
|
178
|
+
return result.deferred.map((gate) => ` deferred ${gate.role} ${gate.product} did not run here; it runs from stage ${gate.stage} onwards`);
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* One line per gate that had nothing to check.
|
|
182
|
+
*
|
|
183
|
+
* A line rather than silence, and a line rather than a finding. Silence makes
|
|
184
|
+
* a branch with no spec read as a branch that passed the intent gate, which
|
|
185
|
+
* is the confusion this family exists to prevent. A finding would put the
|
|
186
|
+
* absence of a spec on the same footing as a drift, and it is not one: it is
|
|
187
|
+
* the ordinary state of most branches in a repository that has not adopted
|
|
188
|
+
* the flow yet.
|
|
189
|
+
*/
|
|
190
|
+
function skippedLines(result) {
|
|
191
|
+
return result.skipped.map((gate) => ` skipped ${gate.role} ${gate.product} no contract: ${gate.detail}`);
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* One line per gate the --gate flag left out.
|
|
195
|
+
*
|
|
196
|
+
* The same reasoning as the deferred lines above, with the one difference
|
|
197
|
+
* that there is no later stage to name: this gate is on in the policy file
|
|
198
|
+
* and did not run because of how this one command was typed. Without the
|
|
199
|
+
* line, a --gate run and a full run produce the same report.
|
|
200
|
+
*/
|
|
201
|
+
function excludedLines(result) {
|
|
202
|
+
return result.excluded.map((gate) => ` excluded ${gate.role} ${gate.product} did not run here; --gate did not name it`);
|
|
203
|
+
}
|
|
204
|
+
/**
|
|
205
|
+
* What an unenforced gate did, as clauses for a verdict line.
|
|
206
|
+
*
|
|
207
|
+
* Shared by the exit 0 and exit 1 branches: an unenforced gate is left out
|
|
208
|
+
* of the count and out of the reason either way, but it still gets a
|
|
209
|
+
* sentence. A gate that verified nothing is worth a line whatever the exit
|
|
210
|
+
* code turned out to be.
|
|
211
|
+
*/
|
|
212
|
+
function unenforcedClauses(result) {
|
|
213
|
+
const unenforced = result.gates.filter((gate) => !gate.enforce);
|
|
214
|
+
// A gate that could not run is only that. Its findings list carries the
|
|
215
|
+
// umbrella's own blocking gate-missing finding, so a naive test for "has a
|
|
216
|
+
// blocking finding" reports the same gate as having blocked AND as having
|
|
217
|
+
// failed to run, which are opposite claims.
|
|
218
|
+
const blocked = unenforced.filter((gate) => gate.couldNotRun === null &&
|
|
219
|
+
((gate.exitCode ?? 0) !== 0 || gate.findings.some((finding) => finding.blocking)));
|
|
220
|
+
const broken = unenforced.filter((gate) => gate.couldNotRun !== null);
|
|
221
|
+
const clauses = [];
|
|
222
|
+
if (blocked.length > 0) {
|
|
223
|
+
clauses.push(`${blocked.map((gate) => gate.role).join(', ')} blocked`);
|
|
224
|
+
}
|
|
225
|
+
if (broken.length > 0) {
|
|
226
|
+
clauses.push(`${broken.map((gate) => gate.role).join(', ')} could not run`);
|
|
227
|
+
}
|
|
228
|
+
return clauses;
|
|
229
|
+
}
|
|
230
|
+
function verdict(result) {
|
|
231
|
+
// Counted over ENFORCED gates only. The exit code came from those alone,
|
|
232
|
+
// so a count taken over all of them describes a different run from the one
|
|
233
|
+
// the number at the front of the line is about, and the umbrella's own
|
|
234
|
+
// findings about an unenforced broken gate inflate it further.
|
|
235
|
+
const enforcedGates = result.gates.filter((gate) => gate.enforce);
|
|
236
|
+
const blocking = enforcedGates
|
|
237
|
+
.flatMap((gate) => gate.findings)
|
|
238
|
+
.filter((finding) => finding.blocking).length;
|
|
239
|
+
if (result.gates.length === 0 && result.deferred.length > 0) {
|
|
240
|
+
// Distinct from "none is enabled" below. A policy file with everything
|
|
241
|
+
// switched off and a stage with nothing to do at it are two different
|
|
242
|
+
// states, and telling somebody to set enabled: true is the wrong advice
|
|
243
|
+
// for the second one.
|
|
244
|
+
const names = result.deferred.map((gate) => `${gate.role} at stage ${gate.stage}`).join(', ');
|
|
245
|
+
return `verdict: exit 0, nothing ran at this stage: every enabled gate is deferred (${names}).`;
|
|
246
|
+
}
|
|
247
|
+
if (result.gates.length === 0 && result.skipped.length > 0) {
|
|
248
|
+
// A third distinct state, and telling somebody to switch a gate on is
|
|
249
|
+
// wrong advice here too: the gate IS on, it ran, and it had nothing to
|
|
250
|
+
// check. The fix is a spec, which the skipped line above names.
|
|
251
|
+
const names = result.skipped.map((gate) => gate.role).join(', ');
|
|
252
|
+
return `verdict: exit 0, nothing was checked: ${names} had no contract to check against.`;
|
|
253
|
+
}
|
|
254
|
+
if (result.gates.length === 0) {
|
|
255
|
+
// Exit 0 with an empty report is indistinguishable from a clean run at a
|
|
256
|
+
// glance, and a policy file with every gate switched off is exactly the
|
|
257
|
+
// state somebody needs told about. Still 0: nothing was asked for and
|
|
258
|
+
// nothing failed, so this is not the umbrella's decision to overturn.
|
|
259
|
+
return ('verdict: exit 0, no gate ran because none is enabled. ' +
|
|
260
|
+
'Nothing was checked. Set enabled: true on a gate in .guardrails.yaml.');
|
|
261
|
+
}
|
|
262
|
+
const clauses = unenforcedClauses(result);
|
|
263
|
+
const aside = clauses.length === 0
|
|
264
|
+
? ''
|
|
265
|
+
: ` ${clauses.join(' and ')}, but those gates have enforce: false in .guardrails.yaml, ` +
|
|
266
|
+
'so that is not why.';
|
|
267
|
+
if (result.exitCode === EXIT_COULD_NOT_RUN) {
|
|
268
|
+
// Only the ENFORCED gates. An unenforced gate that could not run is not
|
|
269
|
+
// why this run failed, and naming it here sends somebody off to install
|
|
270
|
+
// a gate that would not have changed the answer.
|
|
271
|
+
const names = enforcedGates
|
|
272
|
+
.filter((gate) => gate.couldNotRun !== null)
|
|
273
|
+
.map((gate) => gate.role)
|
|
274
|
+
.join(', ');
|
|
275
|
+
return `verdict: exit 2, a gate could not run (${names}), so nothing here is a clean result.${aside}`;
|
|
276
|
+
}
|
|
277
|
+
if (result.exitCode === EXIT_BLOCKED) {
|
|
278
|
+
// Exit 1 with nothing on screen marked blocking. The sibling of the exit 0
|
|
279
|
+
// clause below, and it exists for the same reason: composeExitCode returns
|
|
280
|
+
// 1 for a non-zero gate exit code OR a blocking finding, and both branches
|
|
281
|
+
// of reconcileBlocking in normalize.ts drop every blocking flag to false
|
|
282
|
+
// while the gate's own non-zero exit still stands. "0 blocking finding(s)"
|
|
283
|
+
// on the one line somebody reads when they read nothing else contradicts
|
|
284
|
+
// the exit code printed beside it, and sends a reader looking for a
|
|
285
|
+
// finding that this report deliberately does not claim.
|
|
286
|
+
if (blocking === 0) {
|
|
287
|
+
const names = enforcedGates
|
|
288
|
+
.filter((gate) => (gate.exitCode ?? 0) !== 0)
|
|
289
|
+
.map((gate) => `${gate.role} (exit ${gate.exitCode ?? '?'})`)
|
|
290
|
+
.join(', ');
|
|
291
|
+
return (`verdict: exit 1, and no finding here is marked blocking. Enforced gate(s) that exited ` +
|
|
292
|
+
`non-zero: ${names}. The umbrella could not reconcile a blocking count with what those ` +
|
|
293
|
+
`gates reported, so the gate exit code decided the run.${aside}`);
|
|
294
|
+
}
|
|
295
|
+
return `verdict: exit 1, ${blocking} blocking finding(s) across ${enforcedGates.length} gate(s).${aside}`;
|
|
296
|
+
}
|
|
297
|
+
// Exit 0 with red on the screen above it. The verdict is the one line
|
|
298
|
+
// somebody reads when they read nothing else, so it is the line that has
|
|
299
|
+
// to carry the reason rather than leaving it to the sections.
|
|
300
|
+
if (clauses.length > 0) {
|
|
301
|
+
return (`verdict: exit 0, but ${clauses.join(' and ')}. ` +
|
|
302
|
+
'Those gates have enforce: false in .guardrails.yaml, so nothing here failed the run.');
|
|
303
|
+
}
|
|
304
|
+
return `verdict: exit 0, every enabled gate ran and none blocked.`;
|
|
305
|
+
}
|
|
306
|
+
/**
|
|
307
|
+
* Whether this run has nothing at all to report.
|
|
308
|
+
*
|
|
309
|
+
* Three conditions, and the second and third are why this is not just a test
|
|
310
|
+
* of the exit code. A gate with enforce: false is left out of the composed
|
|
311
|
+
* code entirely, so a run where such a gate blocked, or could not run at
|
|
312
|
+
* all, still exits 0; collapsing those to one "clean" line would silently
|
|
313
|
+
* swallow the only report of them anybody sees.
|
|
314
|
+
*
|
|
315
|
+
* A GATE'S OWN NOTES ARE NOT IN HERE; THE UMBRELLA'S OWN DIAGNOSTICS ARE.
|
|
316
|
+
* The two are printed with different markers in the full report and the
|
|
317
|
+
* difference is real. A statement about how much of the policy a run covered
|
|
318
|
+
* is a notification: the standing note that pnpm lockfiles do not record
|
|
319
|
+
* install-script metadata is a permanent property of that file format, true
|
|
320
|
+
* on every run forever, and forcing a screenful over it would make the
|
|
321
|
+
* summary line useless in the repositories that most need it. A statement
|
|
322
|
+
* that something went wrong is a result: conductor/blocking-count-mismatch
|
|
323
|
+
* and conductor/blocking-threshold-unknown, the two codes reconcileBlocking
|
|
324
|
+
* raises in normalize.ts, are the umbrella saying its own report may disagree
|
|
325
|
+
* with the gate's own verdict about what blocked, which is a defect in THIS
|
|
326
|
+
* run and cannot be reported as a number on a line that also says "clean,
|
|
327
|
+
* nothing blocked".
|
|
328
|
+
*
|
|
329
|
+
* A run where no gate ran at all is not clean either, whatever the exit code
|
|
330
|
+
* says. "No gate ran because none is enabled", "every gate was deferred" and
|
|
331
|
+
* "nothing had a contract to check" are three distinct states somebody needs
|
|
332
|
+
* telling about, and a summary line that named no gates would be the exact
|
|
333
|
+
* confusion this family exists to prevent.
|
|
334
|
+
*/
|
|
335
|
+
function isFullyClean(result) {
|
|
336
|
+
if (result.exitCode !== 0 || result.gates.length === 0) {
|
|
337
|
+
return false;
|
|
338
|
+
}
|
|
339
|
+
return result.gates.every((gate) => gate.couldNotRun === null &&
|
|
340
|
+
(gate.exitCode ?? 0) === 0 &&
|
|
341
|
+
gate.diagnostics.length === 0 &&
|
|
342
|
+
!gate.findings.some((finding) => finding.blocking));
|
|
343
|
+
}
|
|
344
|
+
/**
|
|
345
|
+
* The gates' own notes, and only those.
|
|
346
|
+
*
|
|
347
|
+
* The umbrella's own diagnostics are deliberately not added in. They force
|
|
348
|
+
* the full report instead, by the rule on isFullyClean above, so a count of
|
|
349
|
+
* them here would be a count of something that can never be on this line.
|
|
350
|
+
*/
|
|
351
|
+
function noteCount(result) {
|
|
352
|
+
return result.gates.reduce((total, gate) => total + gate.run.diagnostics.length, 0);
|
|
353
|
+
}
|
|
354
|
+
/**
|
|
355
|
+
* The whole report of a clean run, on one line.
|
|
356
|
+
*
|
|
357
|
+
* The v0.2 design constraint is that the gates must not slow development
|
|
358
|
+
* down, and the cost it names is ceremony rather than runtime. Twelve lines
|
|
359
|
+
* of per-gate detail on a commit that found nothing is that cost, paid on
|
|
360
|
+
* every commit, and it is what makes a team switch a hook off. What it must
|
|
361
|
+
* still carry: which gates actually ran, which ones did not run here, and
|
|
362
|
+
* that there is more to read. Everything else waits for --verbose.
|
|
363
|
+
*/
|
|
364
|
+
function summaryLine(result) {
|
|
365
|
+
const ran = result.gates.map((gate) => `${gate.role} (${gate.product})`).join(', ');
|
|
366
|
+
const parts = [`conductor: clean, nothing blocked. ${result.gates.length} gate(s) ran: ${ran}.`];
|
|
367
|
+
if (result.deferred.length > 0) {
|
|
368
|
+
const names = result.deferred
|
|
369
|
+
.map((gate) => `${gate.role} (${gate.product}) from stage ${gate.stage}`)
|
|
370
|
+
.join(', ');
|
|
371
|
+
parts.push(`Deferred to a later stage: ${names}.`);
|
|
372
|
+
}
|
|
373
|
+
// Same reasoning as the deferred clause. A gate that ran and had nothing to
|
|
374
|
+
// check covered none of this commit, and silence there makes a branch with
|
|
375
|
+
// no spec read as a branch that passed the intent gate.
|
|
376
|
+
if (result.skipped.length > 0) {
|
|
377
|
+
const names = result.skipped.map((gate) => `${gate.role} (${gate.product})`).join(', ');
|
|
378
|
+
parts.push(`Nothing to check against: ${names}.`);
|
|
379
|
+
}
|
|
380
|
+
// Same reasoning again, for the gates the command line left out. This one
|
|
381
|
+
// is the easiest of the three to lose: a --gate run is usually somebody
|
|
382
|
+
// narrowing a run on purpose, and a log of it that says nothing about the
|
|
383
|
+
// narrowing is the log that gets uploaded and read as a full run later.
|
|
384
|
+
if (result.excluded.length > 0) {
|
|
385
|
+
const names = result.excluded.map((gate) => `${gate.role} (${gate.product})`).join(', ');
|
|
386
|
+
parts.push(`Left out by --gate: ${names}.`);
|
|
387
|
+
}
|
|
388
|
+
// A gate that ran with enforce: false could not have failed this run
|
|
389
|
+
// whatever it found. Naming it among the gates that ran and then saying
|
|
390
|
+
// nothing more makes a repository on the adoption ramp read as fully
|
|
391
|
+
// gated, and being fully gated is exactly what the ramp is not yet. The
|
|
392
|
+
// full report says this in the line under that gate's findings; on a clean
|
|
393
|
+
// run there are no findings, so the summary line is the only place left to
|
|
394
|
+
// say it.
|
|
395
|
+
const unenforced = result.gates.filter((gate) => !gate.enforce);
|
|
396
|
+
if (unenforced.length > 0) {
|
|
397
|
+
const names = unenforced.map((gate) => `${gate.role} (${gate.product})`).join(', ');
|
|
398
|
+
parts.push(`Could not have blocked, enforce: false in .guardrails.yaml: ${names}.`);
|
|
399
|
+
}
|
|
400
|
+
// Non-blocking findings are counted rather than hidden, for the same reason
|
|
401
|
+
// the full report prints the suppressed and ignored counts at zero: they
|
|
402
|
+
// are things the gates actually said, and a summary that omitted them would
|
|
403
|
+
// let a repository accumulate them unread.
|
|
404
|
+
const counts = [];
|
|
405
|
+
if (result.findings.length > 0) {
|
|
406
|
+
counts.push(`${result.findings.length} non-blocking finding(s)`);
|
|
407
|
+
}
|
|
408
|
+
const notes = noteCount(result);
|
|
409
|
+
if (notes > 0) {
|
|
410
|
+
counts.push(`${notes} note(s)`);
|
|
411
|
+
}
|
|
412
|
+
if (counts.length > 0) {
|
|
413
|
+
parts.push(`${counts.join(', ')}.`);
|
|
414
|
+
}
|
|
415
|
+
parts.push('Re-run with --verbose for the full report.');
|
|
416
|
+
return parts.join(' ');
|
|
417
|
+
}
|
|
418
|
+
export function renderText(result, options = {}) {
|
|
419
|
+
if (!options.verbose && isFullyClean(result)) {
|
|
420
|
+
return `${summaryLine(result)}\n`;
|
|
421
|
+
}
|
|
422
|
+
// Counted over EVERY gate, unenforced ones included, and deliberately not
|
|
423
|
+
// the same number the verdict prints. This line is an inventory of what
|
|
424
|
+
// follows it: a reader counting the finding lines on screen has to arrive
|
|
425
|
+
// at this number, and narrowing it to the enforced gates would make the
|
|
426
|
+
// header disagree with the report under it. The verdict is the other
|
|
427
|
+
// question, what failed the run, and that one is enforced gates only. Two
|
|
428
|
+
// different questions, so two numbers, and the section headers and the
|
|
429
|
+
// "not enforced" lines are what connect them.
|
|
430
|
+
const lines = [
|
|
431
|
+
`conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
|
|
432
|
+
];
|
|
433
|
+
for (const gate of result.gates) {
|
|
434
|
+
lines.push(...gateSection(gate));
|
|
435
|
+
}
|
|
436
|
+
const aside = [...deferredLines(result), ...skippedLines(result), ...excludedLines(result)];
|
|
437
|
+
if (aside.length > 0) {
|
|
438
|
+
lines.push('', ...aside);
|
|
439
|
+
}
|
|
440
|
+
// A derived severity is marked with a trailing asterisk above; say what
|
|
441
|
+
// that means rather than leaving a reader to guess, and only when one is
|
|
442
|
+
// actually on screen.
|
|
443
|
+
if (result.findings.some((finding) => finding.severityIsDerived)) {
|
|
444
|
+
lines.push('', '* severity assigned by the umbrella; that gate reports no per-finding severity.');
|
|
445
|
+
}
|
|
446
|
+
lines.push('', verdict(result));
|
|
447
|
+
return `${lines.join('\n')}\n`;
|
|
448
|
+
}
|
package/dist/policy.d.ts
ADDED
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
export declare const POLICY_FILE_NAME = ".guardrails.yaml";
|
|
2
|
+
export declare const GATE_ROLES: readonly ["dependencies", "secrets", "intent"];
|
|
3
|
+
export type GateRole = (typeof GATE_ROLES)[number];
|
|
4
|
+
export declare const PRODUCTS: readonly ["dep-guard", "vault-guard", "intent-guard"];
|
|
5
|
+
export type Product = (typeof PRODUCTS)[number];
|
|
6
|
+
/**
|
|
7
|
+
* When a gate runs, in order, earliest first.
|
|
8
|
+
*
|
|
9
|
+
* Stages are CUMULATIVE: a gate runs at its own stage and at every later
|
|
10
|
+
* one, so a run at `ci` runs everything that is enabled. The order of this
|
|
11
|
+
* array is the whole rule, which is why it is one array rather than three
|
|
12
|
+
* booleans: adding a fourth stopping point is an entry here and nothing
|
|
13
|
+
* else.
|
|
14
|
+
*/
|
|
15
|
+
export declare const GATE_STAGES: readonly ["commit", "push", "ci"];
|
|
16
|
+
export type GateStage = (typeof GATE_STAGES)[number];
|
|
17
|
+
/**
|
|
18
|
+
* Where each gate sits when the policy file does not say.
|
|
19
|
+
*
|
|
20
|
+
* Runtime is not what decides this. All three gates together take under a
|
|
21
|
+
* second on a staged commit; the cost is CEREMONY, and only the intent gate
|
|
22
|
+
* has any, because it wants a contract approved before the work starts.
|
|
23
|
+
* The other two are silent until they find something, and a secret that
|
|
24
|
+
* reaches a pull request is already on a remote, so the earliest stage is
|
|
25
|
+
* the only honest place for them.
|
|
26
|
+
*/
|
|
27
|
+
export declare const DEFAULT_STAGE_FOR_ROLE: Record<GateRole, GateStage>;
|
|
28
|
+
/** Whether a gate at `gateStage` runs during a run asked for at `requested`. */
|
|
29
|
+
export declare function runsAtStage(gateStage: GateStage, requested: GateStage): boolean;
|
|
30
|
+
/**
|
|
31
|
+
* Which product fills which role today. Enforced on load: a policy that
|
|
32
|
+
* puts dep-guard in the `secrets` role is a mistake with a confusing
|
|
33
|
+
* failure mode (the secrets section of the report would carry dependency
|
|
34
|
+
* findings), so it is rejected at parse time instead.
|
|
35
|
+
*
|
|
36
|
+
* This map is the single place a rename lands. It is not the same thing as
|
|
37
|
+
* the roles being closed forever: a role gains a product by gaining an
|
|
38
|
+
* entry here and an adapter, and nothing else in the schema moves.
|
|
39
|
+
*/
|
|
40
|
+
export declare const PRODUCT_FOR_ROLE: Record<GateRole, Product>;
|
|
41
|
+
/**
|
|
42
|
+
* Flags the umbrella supplies itself, per product. A policy that also sets
|
|
43
|
+
* one would put two writers on the same flag, and which one won would
|
|
44
|
+
* depend on that CLI's argument parser rather than on anything the user
|
|
45
|
+
* could read in their own policy file.
|
|
46
|
+
*/
|
|
47
|
+
export declare const RESERVED_OPTIONS: Record<Product, readonly string[]>;
|
|
48
|
+
export type OptionValue = string | number | boolean | Array<string | number>;
|
|
49
|
+
export interface GatePolicy {
|
|
50
|
+
role: GateRole;
|
|
51
|
+
product: Product;
|
|
52
|
+
enabled: boolean;
|
|
53
|
+
/** Resolved, never absent: the file's own value or this role's default. */
|
|
54
|
+
stage: GateStage;
|
|
55
|
+
/**
|
|
56
|
+
* Whether this gate's verdict reaches the composed exit code. Defaults to
|
|
57
|
+
* true. An unenforced gate runs, reports, and appears in both output
|
|
58
|
+
* formats exactly as an enforced one does; the only thing it cannot do is
|
|
59
|
+
* change the exit code.
|
|
60
|
+
*/
|
|
61
|
+
enforce: boolean;
|
|
62
|
+
/**
|
|
63
|
+
* Whether `--gate` switched this gate off, as opposed to the policy file.
|
|
64
|
+
*
|
|
65
|
+
* The two are different facts about a run and only one of them is news. A
|
|
66
|
+
* gate the file disables is a standing decision somebody wrote down; a gate
|
|
67
|
+
* `--gate` left out was on in the file and did not run this once, and
|
|
68
|
+
* without this flag nothing downstream can tell them apart. That is what
|
|
69
|
+
* made an uploaded log from a `--gate` run indistinguishable from a full
|
|
70
|
+
* one, which is exactly the confusion the deferred notification exists to
|
|
71
|
+
* prevent.
|
|
72
|
+
*/
|
|
73
|
+
excludedByCli: boolean;
|
|
74
|
+
/** Absolute path to the gate's executable, overriding resolution. */
|
|
75
|
+
command?: string;
|
|
76
|
+
/** Argument prefix used with `command` when it cannot be inferred. */
|
|
77
|
+
args?: string[];
|
|
78
|
+
/** Handed to the gate unchanged. */
|
|
79
|
+
options: Record<string, OptionValue>;
|
|
80
|
+
}
|
|
81
|
+
export interface Policy {
|
|
82
|
+
version: 1;
|
|
83
|
+
gates: Partial<Record<GateRole, GatePolicy>>;
|
|
84
|
+
report: {
|
|
85
|
+
format: 'text' | 'sarif';
|
|
86
|
+
};
|
|
87
|
+
}
|
|
88
|
+
export declare class PolicyError extends Error {
|
|
89
|
+
constructor(message: string);
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Parses and validates policy YAML.
|
|
93
|
+
*
|
|
94
|
+
* `source` is only used in error messages, so the same function serves the
|
|
95
|
+
* file loader and the tests without either needing a temporary directory.
|
|
96
|
+
*/
|
|
97
|
+
export declare function parsePolicy(text: string, source: string): Policy;
|
|
98
|
+
/** Reads the policy file at a repository root. */
|
|
99
|
+
export declare function loadPolicy(repoRoot: string): Policy;
|
|
100
|
+
export interface CliOverrides {
|
|
101
|
+
/** Restrict the run to these roles, whatever the policy enabled. */
|
|
102
|
+
gates?: GateRole[];
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Layer three of the precedence chain.
|
|
106
|
+
*
|
|
107
|
+
* Layer one is each product's own config file, which the umbrella never
|
|
108
|
+
* writes or reads. Layer two is this policy file, delivered to the child as
|
|
109
|
+
* command-line flags, which every one of the three treats as higher
|
|
110
|
+
* precedence than its own config. Layer three is a flag on the umbrella's
|
|
111
|
+
* own command line, and in v0.1 that is exactly one thing: restricting the
|
|
112
|
+
* run to named roles. There is deliberately no umbrella flag that rewrites
|
|
113
|
+
* a gate's threshold, because a threshold means something different in each
|
|
114
|
+
* product and a single flag would have to pick one meaning silently.
|
|
115
|
+
*/
|
|
116
|
+
export declare function applyCliOverrides(policy: Policy, overrides: CliOverrides): Policy;
|
|
117
|
+
/** Enabled gates in role order, so a report's section order never depends on file order. */
|
|
118
|
+
export declare function enabledGates(policy: Policy): GatePolicy[];
|
|
119
|
+
/**
|
|
120
|
+
* Renders a passthrough option bag as child-process arguments.
|
|
121
|
+
*
|
|
122
|
+
* Keys are sorted so two policy files that differ only in key order produce
|
|
123
|
+
* the same command line, which is what makes a run reproducible and a
|
|
124
|
+
* report diffable.
|
|
125
|
+
*/
|
|
126
|
+
export declare function renderOptionFlags(options: Record<string, OptionValue>): string[];
|