@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.
@@ -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
+ }
@@ -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[];