@vaultcompass/conductor 0.18.1 → 0.19.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 +200 -57
- package/dist/adoption-proposal.d.ts +36 -0
- package/dist/adoption-proposal.js +260 -0
- package/dist/cli.d.ts +25 -7
- package/dist/cli.js +181 -47
- package/dist/escape.d.ts +27 -0
- package/dist/escape.js +35 -0
- package/dist/existing-findings.d.ts +38 -0
- package/dist/existing-findings.js +206 -0
- package/dist/gate-runner.d.ts +13 -9
- package/dist/gate-runner.js +145 -37
- package/dist/git.d.ts +70 -0
- package/dist/git.js +141 -6
- package/dist/init.js +9 -0
- package/dist/intent-prepare.js +4 -0
- package/dist/output-sarif.js +52 -8
- package/dist/output-text.d.ts +117 -8
- package/dist/output-text.js +374 -39
- package/dist/policy.d.ts +9 -0
- package/dist/policy.js +21 -3
- package/dist/rule-ids.d.ts +1 -0
- package/dist/rule-ids.js +2 -0
- package/dist/run.d.ts +80 -0
- package/dist/run.js +70 -3
- package/package.json +1 -1
package/dist/run.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { type Finding } from './envelope.js';
|
|
2
|
+
import { type ExistingFindings } from './existing-findings.js';
|
|
2
3
|
import { type GateOutcome } from './gate-runner.js';
|
|
3
4
|
import type { SelectionMiss } from './intent-spec.js';
|
|
4
5
|
import type { GateRole, GateStage, Policy, Product } from './policy.js';
|
|
@@ -162,6 +163,30 @@ export interface RunTrustBase extends BaseTipForDisplay {
|
|
|
162
163
|
* were read, rather than naming a ref.
|
|
163
164
|
*/
|
|
164
165
|
notGiven?: boolean;
|
|
166
|
+
/**
|
|
167
|
+
* Set when this run's policy is the one the pull request ADDS, because the
|
|
168
|
+
* trust base has none (issue 101): `enabled`, `stage` and `enforce` from
|
|
169
|
+
* the HEAD blob, everything else the product default. Only
|
|
170
|
+
* `src/cli.ts#policyForRun` sets it, and only after
|
|
171
|
+
* `src/adoption-proposal.ts#refuseAdoptionProposal` returned null. Every
|
|
172
|
+
* pull-request protection still keys on the trust base being present, not
|
|
173
|
+
* on this. What this changes is the exit code (`asProposal`) and the words.
|
|
174
|
+
*/
|
|
175
|
+
proposal?: {
|
|
176
|
+
reason: 'no-policy-on-base';
|
|
177
|
+
};
|
|
178
|
+
/**
|
|
179
|
+
* True on a refusal where neither the trust base nor HEAD has a policy
|
|
180
|
+
* file: the workflow is there and nothing can be checked until a policy
|
|
181
|
+
* is. The reports add one fixed line saying so.
|
|
182
|
+
*/
|
|
183
|
+
noPolicy?: boolean;
|
|
184
|
+
/**
|
|
185
|
+
* True when the trust base has a policy and HEAD has no policy file: this
|
|
186
|
+
* pull request deletes it. The run is the ordinary one under the base's
|
|
187
|
+
* rules; the reports add one fixed line saying what merging it does.
|
|
188
|
+
*/
|
|
189
|
+
policyRemoved?: boolean;
|
|
165
190
|
}
|
|
166
191
|
/**
|
|
167
192
|
* A gate the policy file declares with `enabled: false`. Listed so an adopter
|
|
@@ -211,6 +236,13 @@ export interface RunResult {
|
|
|
211
236
|
bySeverity: Record<string, number>;
|
|
212
237
|
};
|
|
213
238
|
exitCode: number;
|
|
239
|
+
/**
|
|
240
|
+
* Facts for the "existing findings" message: present only on a run with no
|
|
241
|
+
* trust base where the history or vulnerabilities gate blocked. WORDS ONLY:
|
|
242
|
+
* computed after `exitCode` and `summary` are fixed, read by the text
|
|
243
|
+
* report, and never read back by anything that decides a verdict.
|
|
244
|
+
*/
|
|
245
|
+
existingFindings?: ExistingFindings;
|
|
214
246
|
/**
|
|
215
247
|
* The preview under the proposed rules: the roles whose `enabled` or
|
|
216
248
|
* `stage` the pull request changes, run once more under those keys. It
|
|
@@ -243,6 +275,11 @@ export interface RunPreview {
|
|
|
243
275
|
}
|
|
244
276
|
export interface RunOptions {
|
|
245
277
|
repoRoot: string;
|
|
278
|
+
/**
|
|
279
|
+
* A test hook: replaces the collection of the existing-findings facts, so a
|
|
280
|
+
* test can inject a throw or switch the collection off. No CLI path sets it.
|
|
281
|
+
*/
|
|
282
|
+
existingFindingsCollector?: (outcomes: readonly GateOutcome[], repoRoot: string) => ExistingFindings | null;
|
|
246
283
|
staged: boolean;
|
|
247
284
|
pathValue: string;
|
|
248
285
|
/**
|
|
@@ -298,6 +335,13 @@ export interface RunOptions {
|
|
|
298
335
|
/** A test hook: the preview's clock. No CLI path sets it; absent is Date.now. */
|
|
299
336
|
previewClock?: () => number;
|
|
300
337
|
}
|
|
338
|
+
/**
|
|
339
|
+
* How the could-not-run detail of every gate of a refused run starts. The
|
|
340
|
+
* per-gate summary line (src/output-text.ts, gateSummaryLine) reads it to say
|
|
341
|
+
* "trust base refused" from the outcome alone. Wording only: a gate carrying
|
|
342
|
+
* it is could-not-run either way.
|
|
343
|
+
*/
|
|
344
|
+
export declare const TRUST_BASE_REFUSED_DETAIL = "the trust base could not be used: ";
|
|
301
345
|
/**
|
|
302
346
|
* The run that never happened, because the trust base could not be judged
|
|
303
347
|
* against.
|
|
@@ -325,6 +369,7 @@ export declare function refusedTrustBase(policy: Policy, ref: string, detail: st
|
|
|
325
369
|
stage?: GateStage;
|
|
326
370
|
now?: () => Date;
|
|
327
371
|
notGiven?: boolean;
|
|
372
|
+
noPolicy?: boolean;
|
|
328
373
|
}): RunResult;
|
|
329
374
|
/**
|
|
330
375
|
* Runs `work`, and turns any throw into `fallback(message)`, the message
|
|
@@ -340,6 +385,41 @@ export declare function guardPreview<T>(work: () => T, fallback: (message: strin
|
|
|
340
385
|
*/
|
|
341
386
|
export declare function runPreview(policy: Policy, options: RunOptions): RunPreview;
|
|
342
387
|
export declare function runAll(policy: Policy, options: RunOptions): RunResult;
|
|
388
|
+
/**
|
|
389
|
+
* Whether this run's policy was the one the pull request adds (issue 101).
|
|
390
|
+
* A fact about where the rules came from, whatever the run then exited with.
|
|
391
|
+
*/
|
|
392
|
+
export declare function ranProposedPolicy(result: RunResult): boolean;
|
|
393
|
+
/**
|
|
394
|
+
* Whether this run is a PROPOSAL OUTCOME: it ran the policy the pull request
|
|
395
|
+
* adds, and exits 0 because nothing on the base could have been enforced.
|
|
396
|
+
* False for a run of a proposed policy in which an enforced gate could not
|
|
397
|
+
* run: that one is could-not-run, exit 2, like any other.
|
|
398
|
+
*/
|
|
399
|
+
export declare function isProposal(result: RunResult): boolean;
|
|
400
|
+
/**
|
|
401
|
+
* THE ONE PLACE A PROPOSAL'S EXIT CODE IS WRITTEN, applied by the CLI to the
|
|
402
|
+
* result of `runAll` on a run of the policy a pull request adds, exactly as
|
|
403
|
+
* `refusedTrustBase` writes its own.
|
|
404
|
+
*
|
|
405
|
+
* Two answers and no third:
|
|
406
|
+
*
|
|
407
|
+
* - 2 when any gate the proposed policy ENFORCES could not run (ruled
|
|
408
|
+
* 2026-11-10). A setup fault is what a red check is for, the adoption
|
|
409
|
+
* pull request is the cheapest place to fix it, and a named gate under a
|
|
410
|
+
* green check is in practice a silent pass. `composeExitCode` already
|
|
411
|
+
* said 2 for this; it is kept, never softened. Anything `runAll` returned
|
|
412
|
+
* that is not 0 or 1 is kept as could-not-run too.
|
|
413
|
+
* - 0 otherwise, whatever the gates found. The base has no policy, so
|
|
414
|
+
* nothing here could have been enforced, and a blocking finding is
|
|
415
|
+
* reported as what WOULD block once the policy is on the base branch.
|
|
416
|
+
*
|
|
417
|
+
* A gate with enforce: false that could not run does not change the code,
|
|
418
|
+
* as on every other run. Throws when handed a run that was not marked as a
|
|
419
|
+
* proposed policy, or was refused: turning any other run's exit code into 0
|
|
420
|
+
* is exactly what this must never do.
|
|
421
|
+
*/
|
|
422
|
+
export declare function asProposal(result: RunResult): RunResult;
|
|
343
423
|
/** The part of a trust base only the reports read. */
|
|
344
424
|
interface BaseTipForDisplay {
|
|
345
425
|
/**
|
package/dist/run.js
CHANGED
|
@@ -3,7 +3,8 @@ import { mkdtempSync, rmSync } from 'node:fs';
|
|
|
3
3
|
import os from 'node:os';
|
|
4
4
|
import path from 'node:path';
|
|
5
5
|
import { compareFindings } from './envelope.js';
|
|
6
|
-
import { EXIT_COULD_NOT_RUN, composeExitCode, gateExitBlocks } from './exit-codes.js';
|
|
6
|
+
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK, composeExitCode, gateExitBlocks } from './exit-codes.js';
|
|
7
|
+
import { collectExistingFindings } from './existing-findings.js';
|
|
7
8
|
import { cleanOutputLine, expectedVersionBeforePreparation, gateProgramRefused, preparationFailed, preparationTimedOut, refuseHeadControlledBinary, resolveTimeLimit, runGate, } from './gate-runner.js';
|
|
8
9
|
import { resolveBaseRef } from './intent-base.js';
|
|
9
10
|
import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
|
|
@@ -94,6 +95,13 @@ function disabledGates(policy) {
|
|
|
94
95
|
.filter((gate) => gate !== undefined && !gate.enabled && !gate.excludedByCli)
|
|
95
96
|
.map((gate) => ({ role: gate.role, product: gate.product }));
|
|
96
97
|
}
|
|
98
|
+
/**
|
|
99
|
+
* How the could-not-run detail of every gate of a refused run starts. The
|
|
100
|
+
* per-gate summary line (src/output-text.ts, gateSummaryLine) reads it to say
|
|
101
|
+
* "trust base refused" from the outcome alone. Wording only: a gate carrying
|
|
102
|
+
* it is could-not-run either way.
|
|
103
|
+
*/
|
|
104
|
+
export const TRUST_BASE_REFUSED_DETAIL = 'the trust base could not be used: ';
|
|
97
105
|
/**
|
|
98
106
|
* The run that never happened, because the trust base could not be judged
|
|
99
107
|
* against.
|
|
@@ -119,7 +127,7 @@ function disabledGates(policy) {
|
|
|
119
127
|
*/
|
|
120
128
|
export function refusedTrustBase(policy, ref, detail, options) {
|
|
121
129
|
const { gates, deferred, excluded } = partitionGates(policy, options.stage);
|
|
122
|
-
const outcomes = gates.map((gate) => preparationFailed({ ...gate, enforce: true },
|
|
130
|
+
const outcomes = gates.map((gate) => preparationFailed({ ...gate, enforce: true }, `${TRUST_BASE_REFUSED_DETAIL}${detail}`));
|
|
123
131
|
const findings = outcomes.flatMap((outcome) => outcome.findings).sort(compareFindings);
|
|
124
132
|
const byProduct = {};
|
|
125
133
|
const bySeverity = {};
|
|
@@ -147,6 +155,7 @@ export function refusedTrustBase(policy, ref, detail, options) {
|
|
|
147
155
|
policyChanged: false,
|
|
148
156
|
refusal: detail,
|
|
149
157
|
...(options.notGiven === true ? { notGiven: true } : {}),
|
|
158
|
+
...(options.noPolicy === true ? { noPolicy: true } : {}),
|
|
150
159
|
},
|
|
151
160
|
proposals: [],
|
|
152
161
|
summary: {
|
|
@@ -176,7 +185,10 @@ preparation = []) {
|
|
|
176
185
|
const proposals = [];
|
|
177
186
|
if (trustBase?.policyChanged === true) {
|
|
178
187
|
const changes = trustBase.policyChanges ?? [];
|
|
179
|
-
|
|
188
|
+
// On a proposal the list holds only the keys that were NOT applied
|
|
189
|
+
// (src/cli.ts#policyForRun). Empty then means every key the head wrote
|
|
190
|
+
// was applied, and there is no unapplied change to announce.
|
|
191
|
+
if (changes.length === 0 && trustBase.proposal === undefined) {
|
|
180
192
|
proposals.push({ product: 'conductor', role: null, line: POLICY_PROPOSAL_LINE });
|
|
181
193
|
}
|
|
182
194
|
for (const change of changes) {
|
|
@@ -518,6 +530,14 @@ export function runAll(policy, options) {
|
|
|
518
530
|
bySeverity,
|
|
519
531
|
};
|
|
520
532
|
const proposals = collectProposals(outcomes, options.trustBase, preparationProposals);
|
|
533
|
+
// Words only, and never on a pull-request run: counted after the exit code
|
|
534
|
+
// is fixed, so nothing it reads can move it.
|
|
535
|
+
// Only on a blocked run (exit 1 as composed); a could-not-run run says that.
|
|
536
|
+
// Guarded like the preview: a throw here is no section, never exit 2 and
|
|
537
|
+
// never a lost report.
|
|
538
|
+
const existing = options.trustBase === undefined && exitCode === EXIT_BLOCKED
|
|
539
|
+
? guardPreview(() => (options.existingFindingsCollector ?? collectExistingFindings)(outcomes, options.repoRoot), () => null)
|
|
540
|
+
: null;
|
|
521
541
|
// Before the preview too, so a preview of up to 300 s cannot move it.
|
|
522
542
|
const generatedAt = (options.now?.() ?? new Date()).toISOString();
|
|
523
543
|
// LAST, after outcomes, findings, summary, exitCode and proposals are
|
|
@@ -550,6 +570,53 @@ export function runAll(policy, options) {
|
|
|
550
570
|
proposals,
|
|
551
571
|
summary,
|
|
552
572
|
exitCode,
|
|
573
|
+
...(existing === null ? {} : { existingFindings: existing }),
|
|
553
574
|
...(preview === undefined ? {} : { preview }),
|
|
554
575
|
};
|
|
555
576
|
}
|
|
577
|
+
/**
|
|
578
|
+
* Whether this run's policy was the one the pull request adds (issue 101).
|
|
579
|
+
* A fact about where the rules came from, whatever the run then exited with.
|
|
580
|
+
*/
|
|
581
|
+
export function ranProposedPolicy(result) {
|
|
582
|
+
return result.trustBase?.proposal !== undefined && (result.trustBase.refusal ?? null) === null;
|
|
583
|
+
}
|
|
584
|
+
/**
|
|
585
|
+
* Whether this run is a PROPOSAL OUTCOME: it ran the policy the pull request
|
|
586
|
+
* adds, and exits 0 because nothing on the base could have been enforced.
|
|
587
|
+
* False for a run of a proposed policy in which an enforced gate could not
|
|
588
|
+
* run: that one is could-not-run, exit 2, like any other.
|
|
589
|
+
*/
|
|
590
|
+
export function isProposal(result) {
|
|
591
|
+
return ranProposedPolicy(result) && result.exitCode === EXIT_OK;
|
|
592
|
+
}
|
|
593
|
+
/**
|
|
594
|
+
* THE ONE PLACE A PROPOSAL'S EXIT CODE IS WRITTEN, applied by the CLI to the
|
|
595
|
+
* result of `runAll` on a run of the policy a pull request adds, exactly as
|
|
596
|
+
* `refusedTrustBase` writes its own.
|
|
597
|
+
*
|
|
598
|
+
* Two answers and no third:
|
|
599
|
+
*
|
|
600
|
+
* - 2 when any gate the proposed policy ENFORCES could not run (ruled
|
|
601
|
+
* 2026-11-10). A setup fault is what a red check is for, the adoption
|
|
602
|
+
* pull request is the cheapest place to fix it, and a named gate under a
|
|
603
|
+
* green check is in practice a silent pass. `composeExitCode` already
|
|
604
|
+
* said 2 for this; it is kept, never softened. Anything `runAll` returned
|
|
605
|
+
* that is not 0 or 1 is kept as could-not-run too.
|
|
606
|
+
* - 0 otherwise, whatever the gates found. The base has no policy, so
|
|
607
|
+
* nothing here could have been enforced, and a blocking finding is
|
|
608
|
+
* reported as what WOULD block once the policy is on the base branch.
|
|
609
|
+
*
|
|
610
|
+
* A gate with enforce: false that could not run does not change the code,
|
|
611
|
+
* as on every other run. Throws when handed a run that was not marked as a
|
|
612
|
+
* proposed policy, or was refused: turning any other run's exit code into 0
|
|
613
|
+
* is exactly what this must never do.
|
|
614
|
+
*/
|
|
615
|
+
export function asProposal(result) {
|
|
616
|
+
if (!ranProposedPolicy(result)) {
|
|
617
|
+
throw new Error('asProposal was handed a run that is not a run of a proposed policy');
|
|
618
|
+
}
|
|
619
|
+
const couldNotRun = (result.exitCode !== EXIT_OK && result.exitCode !== EXIT_BLOCKED) ||
|
|
620
|
+
result.gates.some((gate) => gate.enforce && gate.couldNotRun !== null);
|
|
621
|
+
return { ...result, exitCode: couldNotRun ? EXIT_COULD_NOT_RUN : EXIT_OK };
|
|
622
|
+
}
|