@vaultcompass/conductor 0.13.2 → 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.
@@ -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
- let outcome;
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;