@vaultcompass/conductor 0.13.2 → 0.15.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 +145 -20
- package/dist/cli.d.ts +38 -0
- package/dist/cli.js +77 -6
- package/dist/gate-runner.d.ts +83 -4
- package/dist/gate-runner.js +288 -49
- package/dist/output-sarif.d.ts +2 -2
- package/dist/output-sarif.js +47 -2
- package/dist/output-text.d.ts +37 -1
- package/dist/output-text.js +125 -27
- package/dist/policy-diff.d.ts +43 -0
- package/dist/policy-diff.js +181 -0
- package/dist/resolve.d.ts +68 -0
- package/dist/resolve.js +156 -2
- package/dist/run.d.ts +63 -0
- package/dist/run.js +142 -21
- package/dist/trust-base.d.ts +34 -0
- package/dist/trust-base.js +83 -1
- package/package.json +1 -1
- package/schema/guardrails.schema.json +1 -1
package/dist/output-text.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { type GateOutcome } from './gate-runner.js';
|
|
2
2
|
import type { ReportedMatch } from './intent-prepare.js';
|
|
3
|
-
import type
|
|
3
|
+
import { type RunResult } from './run.js';
|
|
4
4
|
/**
|
|
5
5
|
* How many entries a section prints before it rolls the rest up into one
|
|
6
6
|
* line, unless --verbose. A full-history gitleaks scan or an osv-scanner run
|
|
@@ -56,6 +56,42 @@ export declare function proposalCount(result: RunResult): string;
|
|
|
56
56
|
* not change.
|
|
57
57
|
*/
|
|
58
58
|
export declare function jobLogSummary(result: RunResult): string;
|
|
59
|
+
/**
|
|
60
|
+
* The proposal lines for a job log: the count sentence, then one line per
|
|
61
|
+
* proposed control change. Empty outside pull-request mode, and empty when
|
|
62
|
+
* the trust base was refused or never given, because no rules were read and
|
|
63
|
+
* there is nothing proposed to count. Each line goes through
|
|
64
|
+
* cleanOutputLine, since a proposal carries text a gate printed.
|
|
65
|
+
*/
|
|
66
|
+
export declare function proposalLogLines(result: RunResult): string[];
|
|
67
|
+
/**
|
|
68
|
+
* A gate's outcome in the job log's words: `ok`, `findings (N, M blocking)`
|
|
69
|
+
* with dep-guard's deadline clause when it said so, `could-not-run (reason)`
|
|
70
|
+
* or `missing (reason)`. Shared by the per-gate lines and the preview's.
|
|
71
|
+
*/
|
|
72
|
+
export declare function gateOutcomeWords(gate: GateOutcome): string;
|
|
73
|
+
/**
|
|
74
|
+
* The header the preview block starts with, in the report and the comment.
|
|
75
|
+
* scripts/lib/pr-comment.mjs spells it too, to cut the preview first from a
|
|
76
|
+
* comment over the limit, and action.yml stops its summary scan at it.
|
|
77
|
+
*/
|
|
78
|
+
export declare const PREVIEW_HEADER = "Preview under the proposed rules (does not affect the verdict)";
|
|
79
|
+
/**
|
|
80
|
+
* The preview under the proposed rules, as report lines: empty without a
|
|
81
|
+
* preview, otherwise a blank line, the header, the fixed-shape count line,
|
|
82
|
+
* one gate section per preview gate, then the deferred, over-budget, threw
|
|
83
|
+
* and advisory lines. Printed only AFTER the verdict line, and read by
|
|
84
|
+
* nothing that decides one. Every line goes through cleanOutputLine: a
|
|
85
|
+
* preview runs under head-proposed keys, so its gate text is not trusted to
|
|
86
|
+
* be free of a workflow command.
|
|
87
|
+
*/
|
|
88
|
+
export declare function previewLines(result: RunResult, verbose: boolean): string[];
|
|
89
|
+
/**
|
|
90
|
+
* The preview's job log lines: one per preview gate in the per-gate lines'
|
|
91
|
+
* outcome words, one per over-budget role, and one for a deferred intent
|
|
92
|
+
* gate. Empty without a preview. Each line goes through cleanOutputLine.
|
|
93
|
+
*/
|
|
94
|
+
export declare function previewLogLines(result: RunResult): string[];
|
|
59
95
|
/**
|
|
60
96
|
* One plain line per gate, for the job log: which gate, which version, what
|
|
61
97
|
* happened, and the exit code. Written to stderr by cli.ts on EVERY run, so
|
package/dist/output-text.js
CHANGED
|
@@ -23,18 +23,26 @@
|
|
|
23
23
|
// everywhere is worth more here than a nicer-looking terminal.
|
|
24
24
|
import { compareFindings } from './envelope.js';
|
|
25
25
|
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, gateExitBlocks } from './exit-codes.js';
|
|
26
|
-
import { CONDUCTOR_OWN_REASONS, cleanOutputLine, conductorStatedReason, resolutionPlace, versionCharacters, versionSkewRemedy, } from './gate-runner.js';
|
|
26
|
+
import { CONDUCTOR_OWN_REASONS, cleanOutputLine, cleanPreviewLine, 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 { escapeNonAscii } from './policy-diff.js';
|
|
31
|
+
import { guardPreview } from './run.js';
|
|
32
|
+
// A file path in a finding is the head's choice on any pull-request run (a
|
|
33
|
+
// file named with a right-to-left override in it), so in the text report,
|
|
34
|
+
// and so in the pull-request comment, every path is printed with
|
|
35
|
+
// escapeNonAscii (audit 2026-10-27 fix round, N3). SARIF keeps the real path:
|
|
36
|
+
// code scanning has to find the file.
|
|
29
37
|
function subjectLabel(finding) {
|
|
30
38
|
const subject = finding.subject;
|
|
31
39
|
switch (subject.kind) {
|
|
32
40
|
case 'package':
|
|
33
|
-
return `${subject.name} (${subject.manifest})`;
|
|
41
|
+
return `${subject.name} (${escapeNonAscii(subject.manifest)})`;
|
|
34
42
|
case 'location':
|
|
35
|
-
return `${subject.file}:${subject.line}:${subject.column}`;
|
|
43
|
+
return `${escapeNonAscii(subject.file)}:${subject.line}:${subject.column}`;
|
|
36
44
|
case 'paths':
|
|
37
|
-
return subject.paths.join(', ');
|
|
45
|
+
return subject.paths.map(escapeNonAscii).join(', ');
|
|
38
46
|
case 'contract':
|
|
39
47
|
return subject.category === undefined ? 'intent contract' : `contract: ${subject.category}`;
|
|
40
48
|
case 'none':
|
|
@@ -81,7 +89,7 @@ function osvSubject(entry) {
|
|
|
81
89
|
const name = first.subject.kind === 'package' ? first.subject.name : '';
|
|
82
90
|
const installed = typeof first.details.version === 'string' ? first.details.version : '';
|
|
83
91
|
const where = entry.length === 1 && first.subject.kind === 'package'
|
|
84
|
-
? `(${first.subject.manifest})`
|
|
92
|
+
? `(${escapeNonAscii(first.subject.manifest)})`
|
|
85
93
|
: `${entry.length} lockfiles`;
|
|
86
94
|
const fixed = typeof first.details.fixedVersion === 'string' ? `fix ${first.details.fixedVersion}` : 'no fix listed';
|
|
87
95
|
const dev = entry.filter(isDev).length;
|
|
@@ -148,7 +156,7 @@ function findingLines(entry, verbose, shortProblem) {
|
|
|
148
156
|
lines.push(...gitleaksLines(finding));
|
|
149
157
|
}
|
|
150
158
|
if (verbose && entry.length > 1) {
|
|
151
|
-
const manifests = entry.map((each) => (each.subject.kind === 'package' ? each.subject.manifest : ''));
|
|
159
|
+
const manifests = entry.map((each) => (each.subject.kind === 'package' ? escapeNonAscii(each.subject.manifest) : ''));
|
|
152
160
|
lines.push(` lockfiles: ${manifests.join(', ')}`);
|
|
153
161
|
}
|
|
154
162
|
return lines;
|
|
@@ -666,6 +674,109 @@ export function jobLogSummary(result) {
|
|
|
666
674
|
}
|
|
667
675
|
return `${result.gates.length} gate(s), ${result.findings.length} finding(s)`;
|
|
668
676
|
}
|
|
677
|
+
/**
|
|
678
|
+
* The proposal lines for a job log: the count sentence, then one line per
|
|
679
|
+
* proposed control change. Empty outside pull-request mode, and empty when
|
|
680
|
+
* the trust base was refused or never given, because no rules were read and
|
|
681
|
+
* there is nothing proposed to count. Each line goes through
|
|
682
|
+
* cleanOutputLine, since a proposal carries text a gate printed.
|
|
683
|
+
*/
|
|
684
|
+
export function proposalLogLines(result) {
|
|
685
|
+
const trust = result.trustBase;
|
|
686
|
+
if (trust === null || trust.notGiven === true || (trust.refusal !== null && trust.refusal !== undefined)) {
|
|
687
|
+
return [];
|
|
688
|
+
}
|
|
689
|
+
return [
|
|
690
|
+
cleanOutputLine(`conductor: ${proposalCount(result)}.`),
|
|
691
|
+
...result.proposals.map((proposal) => cleanOutputLine(`conductor: proposed ${proposal.product} ${proposal.line}`)),
|
|
692
|
+
];
|
|
693
|
+
}
|
|
694
|
+
/**
|
|
695
|
+
* A gate's outcome in the job log's words: `ok`, `findings (N, M blocking)`
|
|
696
|
+
* with dep-guard's deadline clause when it said so, `could-not-run (reason)`
|
|
697
|
+
* or `missing (reason)`. Shared by the per-gate lines and the preview's.
|
|
698
|
+
*/
|
|
699
|
+
export function gateOutcomeWords(gate) {
|
|
700
|
+
if (gate.couldNotRun !== null) {
|
|
701
|
+
const reason = gate.couldNotRun.reason;
|
|
702
|
+
return reason === 'binary-missing' || reason === 'configured-command-missing'
|
|
703
|
+
? `missing (${reason})`
|
|
704
|
+
: `could-not-run (${reason})`;
|
|
705
|
+
}
|
|
706
|
+
const total = gate.findings.length;
|
|
707
|
+
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
708
|
+
let outcome = total === 0 && (gate.exitCode ?? 0) === 0 ? 'ok' : `findings (${total}, ${blocking} blocking)`;
|
|
709
|
+
// Only when the gate said so; the outcome word above is unchanged.
|
|
710
|
+
const coverage = deadlineCoverage(gate);
|
|
711
|
+
if (coverage !== null) {
|
|
712
|
+
outcome += `, ${coverage}`;
|
|
713
|
+
}
|
|
714
|
+
return outcome;
|
|
715
|
+
}
|
|
716
|
+
/**
|
|
717
|
+
* The header the preview block starts with, in the report and the comment.
|
|
718
|
+
* scripts/lib/pr-comment.mjs spells it too, to cut the preview first from a
|
|
719
|
+
* comment over the limit, and action.yml stops its summary scan at it.
|
|
720
|
+
*/
|
|
721
|
+
export const PREVIEW_HEADER = 'Preview under the proposed rules (does not affect the verdict)';
|
|
722
|
+
/**
|
|
723
|
+
* The preview under the proposed rules, as report lines: empty without a
|
|
724
|
+
* preview, otherwise a blank line, the header, the fixed-shape count line,
|
|
725
|
+
* one gate section per preview gate, then the deferred, over-budget, threw
|
|
726
|
+
* and advisory lines. Printed only AFTER the verdict line, and read by
|
|
727
|
+
* nothing that decides one. Every line goes through cleanOutputLine: a
|
|
728
|
+
* preview runs under head-proposed keys, so its gate text is not trusted to
|
|
729
|
+
* be free of a workflow command.
|
|
730
|
+
*/
|
|
731
|
+
export function previewLines(result, verbose) {
|
|
732
|
+
const preview = result.preview;
|
|
733
|
+
if (preview === undefined) {
|
|
734
|
+
return [];
|
|
735
|
+
}
|
|
736
|
+
const body = guardPreview(() => {
|
|
737
|
+
const couldNotRun = preview.gates.filter((gate) => gate.couldNotRun !== null).length;
|
|
738
|
+
const lines = [
|
|
739
|
+
`preview: ${preview.gates.length} gate(s), ${preview.findings.length} finding(s), ${couldNotRun} could-not-run`,
|
|
740
|
+
...preview.gates.flatMap((gate) => gateSection(gate, verbose)),
|
|
741
|
+
...preview.skipped.map((skip) => `preview: ${skip.role} (${skip.product}) would not run: ${skip.reason}`),
|
|
742
|
+
];
|
|
743
|
+
if (preview.deferred.includes('intent')) {
|
|
744
|
+
lines.push('preview: intent (intent-guard) deferred, the preview does not prepare the intent gate');
|
|
745
|
+
}
|
|
746
|
+
if (preview.overBudget.length > 0) {
|
|
747
|
+
lines.push(`preview skipped: over budget (${preview.overBudget
|
|
748
|
+
.map((role) => `${role} (${PRODUCT_FOR_ROLE[role]})`)
|
|
749
|
+
.join(', ')})`);
|
|
750
|
+
}
|
|
751
|
+
if (preview.threw !== null) {
|
|
752
|
+
lines.push(`preview: could not be completed (${preview.threw})`);
|
|
753
|
+
}
|
|
754
|
+
if (couldNotRun > 0) {
|
|
755
|
+
lines.push(' a could-not-run in the preview is advisory: it does not change the exit code.');
|
|
756
|
+
}
|
|
757
|
+
return lines;
|
|
758
|
+
}, (message) => [`preview: could not be completed (${message})`]);
|
|
759
|
+
// cleanPreviewLine, not cleanOutputLine: a head .vault-guard.json can name
|
|
760
|
+
// a pattern id with a right-to-left override in it (audit 2026-10-27, N3).
|
|
761
|
+
return ['', PREVIEW_HEADER, ...body].map(cleanPreviewLine);
|
|
762
|
+
}
|
|
763
|
+
/**
|
|
764
|
+
* The preview's job log lines: one per preview gate in the per-gate lines'
|
|
765
|
+
* outcome words, one per over-budget role, and one for a deferred intent
|
|
766
|
+
* gate. Empty without a preview. Each line goes through cleanOutputLine.
|
|
767
|
+
*/
|
|
768
|
+
export function previewLogLines(result) {
|
|
769
|
+
const preview = result.preview;
|
|
770
|
+
if (preview === undefined) {
|
|
771
|
+
return [];
|
|
772
|
+
}
|
|
773
|
+
const lines = guardPreview(() => [
|
|
774
|
+
...preview.gates.map((gate) => `conductor: preview ${gate.role} (${gate.product}) ${gateOutcomeWords(gate)}`),
|
|
775
|
+
...preview.overBudget.map((role) => `conductor: preview ${role} (${PRODUCT_FOR_ROLE[role]}) over budget`),
|
|
776
|
+
...(preview.deferred.includes('intent') ? ['conductor: preview intent (intent-guard) deferred'] : []),
|
|
777
|
+
], (message) => [`conductor: preview could not be completed (${message})`]);
|
|
778
|
+
return lines.map(cleanPreviewLine);
|
|
779
|
+
}
|
|
669
780
|
/**
|
|
670
781
|
* One plain line per gate, for the job log: which gate, which version, what
|
|
671
782
|
* happened, and the exit code. Written to stderr by cli.ts on EVERY run, so
|
|
@@ -699,25 +810,7 @@ export function gateLogLines(result, options = {}) {
|
|
|
699
810
|
for (const gate of result.gates) {
|
|
700
811
|
const version = gate.productVersion === null ? 'version unknown' : gate.productVersion;
|
|
701
812
|
const exit = gate.exitCode === null ? 'no exit code' : `exit ${gate.exitCode}`;
|
|
702
|
-
|
|
703
|
-
if (gate.couldNotRun !== null) {
|
|
704
|
-
const reason = gate.couldNotRun.reason;
|
|
705
|
-
outcome =
|
|
706
|
-
reason === 'binary-missing' || reason === 'configured-command-missing'
|
|
707
|
-
? `missing (${reason})`
|
|
708
|
-
: `could-not-run (${reason})`;
|
|
709
|
-
}
|
|
710
|
-
else {
|
|
711
|
-
const total = gate.findings.length;
|
|
712
|
-
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
713
|
-
outcome =
|
|
714
|
-
total === 0 && (gate.exitCode ?? 0) === 0 ? 'ok' : `findings (${total}, ${blocking} blocking)`;
|
|
715
|
-
// Only when the gate said so; the outcome word above is unchanged.
|
|
716
|
-
const coverage = deadlineCoverage(gate);
|
|
717
|
-
if (coverage !== null) {
|
|
718
|
-
outcome += `, ${coverage}`;
|
|
719
|
-
}
|
|
720
|
-
}
|
|
813
|
+
const outcome = gateOutcomeWords(gate);
|
|
721
814
|
// conductor's own refusals (a git below the floor, a path list it cannot
|
|
722
815
|
// pass, a PATH or git-directory failure, a gate below its minimum) carry
|
|
723
816
|
// their reason the same way, since no gate said anything for them.
|
|
@@ -1407,8 +1500,13 @@ export function renderText(result, options = {}) {
|
|
|
1407
1500
|
];
|
|
1408
1501
|
return `${lines.join('\n')}\n`;
|
|
1409
1502
|
}
|
|
1503
|
+
// The preview, when there is one, goes after everything else: after the
|
|
1504
|
+
// one-line summary here and after the verdict line below, so every report
|
|
1505
|
+
// line above it is byte for byte the same run's without one.
|
|
1506
|
+
const preview = previewLines(result, Boolean(options.verbose));
|
|
1507
|
+
const withPreview = (report) => preview.length === 0 ? report : `${report}${preview.join('\n')}\n`;
|
|
1410
1508
|
if (refusal.length === 0 && !options.verbose && isFullyClean(result)) {
|
|
1411
|
-
return `${summaryLine(result)}\n
|
|
1509
|
+
return withPreview(`${summaryLine(result)}\n`);
|
|
1412
1510
|
}
|
|
1413
1511
|
// Counted over EVERY gate, unenforced ones included, and deliberately not
|
|
1414
1512
|
// the same number the verdict prints. This line is an inventory of what
|
|
@@ -1464,5 +1562,5 @@ export function renderText(result, options = {}) {
|
|
|
1464
1562
|
lines.push('', '* severity assigned by the umbrella; that gate reports no per-finding severity.');
|
|
1465
1563
|
}
|
|
1466
1564
|
lines.push('', verdict(result, Boolean(options.advisory)));
|
|
1467
|
-
return `${lines.join('\n')}\n
|
|
1565
|
+
return withPreview(`${lines.join('\n')}\n`);
|
|
1468
1566
|
}
|
|
@@ -0,0 +1,43 @@
|
|
|
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
|
+
/**
|
|
18
|
+
* Every character outside printable ASCII as a \uXXXX escape (an astral
|
|
19
|
+
* character as its two surrogate escapes), so head-chosen text cannot smuggle
|
|
20
|
+
* a bidi override or a zero-width character into the report. Used for a head
|
|
21
|
+
* policy value here, and for every preview line (cleanPreviewLine,
|
|
22
|
+
* src/gate-runner.ts), whose gate text the head's own control files can
|
|
23
|
+
* choose (audit 2026-10-27, N3).
|
|
24
|
+
*/
|
|
25
|
+
export declare function escapeNonAscii(text: string): string;
|
|
26
|
+
/** One proposal line for one changed key. */
|
|
27
|
+
export declare function policyChangeLine(change: PolicyKeyChange): string;
|
|
28
|
+
/**
|
|
29
|
+
* The roles a preview under the proposed rules runs: every role with an
|
|
30
|
+
* `enabled` or `stage` change, in GATE_ROLES order. A role whose only changes
|
|
31
|
+
* are `enforce` or keys the preview takes from the base would preview as the
|
|
32
|
+
* primary run again, so it is left out, and so is `report.format`.
|
|
33
|
+
*/
|
|
34
|
+
export declare function previewRoles(changes: PolicyKeyChange[]): GateRole[];
|
|
35
|
+
/**
|
|
36
|
+
* The policy a preview runs under. Only `enabled`, `stage` and `enforce` come
|
|
37
|
+
* from the head: `command`, `args`, `options`, `timeout-seconds` and
|
|
38
|
+
* `present-on-base` come from the base role, or, for a role only the head
|
|
39
|
+
* has, from what the policy file gives for its product alone. A role the head
|
|
40
|
+
* removed is the base role switched off. Only the roles in `roles` are held,
|
|
41
|
+
* with the base `report`.
|
|
42
|
+
*/
|
|
43
|
+
export declare function previewPolicy(base: Policy, head: Policy, roles: GateRole[]): Policy;
|
|
@@ -0,0 +1,181 @@
|
|
|
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
|
+
/**
|
|
96
|
+
* Every character outside printable ASCII as a \uXXXX escape (an astral
|
|
97
|
+
* character as its two surrogate escapes), so head-chosen text cannot smuggle
|
|
98
|
+
* a bidi override or a zero-width character into the report. Used for a head
|
|
99
|
+
* policy value here, and for every preview line (cleanPreviewLine,
|
|
100
|
+
* src/gate-runner.ts), whose gate text the head's own control files can
|
|
101
|
+
* choose (audit 2026-10-27, N3).
|
|
102
|
+
*/
|
|
103
|
+
export function escapeNonAscii(text) {
|
|
104
|
+
return text.replace(/[^\x20-\x7e]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
|
|
105
|
+
}
|
|
106
|
+
function renderValue(value) {
|
|
107
|
+
if (value === undefined)
|
|
108
|
+
return '(absent)';
|
|
109
|
+
const text = JSON.stringify(value) ?? '(absent)';
|
|
110
|
+
const escaped = escapeNonAscii(text);
|
|
111
|
+
if (escaped.length <= MAX_VALUE_LENGTH)
|
|
112
|
+
return escaped;
|
|
113
|
+
// Keep whole tokens up to 77 characters, so no escape sequence is split.
|
|
114
|
+
let kept = '';
|
|
115
|
+
for (const token of escaped.match(/\\u[0-9a-f]{4}|\\.|[^\\]/g) ?? []) {
|
|
116
|
+
if (kept.length + token.length > MAX_VALUE_LENGTH - 3)
|
|
117
|
+
break;
|
|
118
|
+
kept += token;
|
|
119
|
+
}
|
|
120
|
+
return `${kept}...`;
|
|
121
|
+
}
|
|
122
|
+
/** One proposal line for one changed key. */
|
|
123
|
+
export function policyChangeLine(change) {
|
|
124
|
+
if (change.key === HEAD_POLICY_KEY) {
|
|
125
|
+
// One text for every case where the head's keys cannot be read: the file
|
|
126
|
+
// is absent, it is not YAML, it parses as YAML but fails policy
|
|
127
|
+
// validation, or git could not read it at all.
|
|
128
|
+
return `policy: the head ${HEAD_POLICY_KEY} is absent or does not parse, so its changes are not known`;
|
|
129
|
+
}
|
|
130
|
+
const where = change.role === null ? change.key : `gates.${change.role}.${change.key}`;
|
|
131
|
+
return `policy: ${where} ${renderValue(change.old)} -> ${renderValue(change.new)}`;
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* The roles a preview under the proposed rules runs: every role with an
|
|
135
|
+
* `enabled` or `stage` change, in GATE_ROLES order. A role whose only changes
|
|
136
|
+
* are `enforce` or keys the preview takes from the base would preview as the
|
|
137
|
+
* primary run again, so it is left out, and so is `report.format`.
|
|
138
|
+
*/
|
|
139
|
+
export function previewRoles(changes) {
|
|
140
|
+
const wanted = new Set(changes
|
|
141
|
+
.filter((change) => change.role !== null && (change.key === 'enabled' || change.key === 'stage'))
|
|
142
|
+
.map((change) => change.role));
|
|
143
|
+
return GATE_ROLES.filter((role) => wanted.has(role));
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* The policy a preview runs under. Only `enabled`, `stage` and `enforce` come
|
|
147
|
+
* from the head: `command`, `args`, `options`, `timeout-seconds` and
|
|
148
|
+
* `present-on-base` come from the base role, or, for a role only the head
|
|
149
|
+
* has, from what the policy file gives for its product alone. A role the head
|
|
150
|
+
* removed is the base role switched off. Only the roles in `roles` are held,
|
|
151
|
+
* with the base `report`.
|
|
152
|
+
*/
|
|
153
|
+
export function previewPolicy(base, head, roles) {
|
|
154
|
+
const gates = {};
|
|
155
|
+
for (const role of GATE_ROLES) {
|
|
156
|
+
if (!roles.includes(role))
|
|
157
|
+
continue;
|
|
158
|
+
const b = base.gates[role];
|
|
159
|
+
const h = head.gates[role];
|
|
160
|
+
if (h === undefined) {
|
|
161
|
+
if (b !== undefined)
|
|
162
|
+
gates[role] = { ...b, enabled: false };
|
|
163
|
+
continue;
|
|
164
|
+
}
|
|
165
|
+
const from = b ?? productDefault(role);
|
|
166
|
+
gates[role] = { ...from, enabled: h.enabled, stage: h.stage, enforce: h.enforce };
|
|
167
|
+
}
|
|
168
|
+
return { version: 1, gates, report: base.report };
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* The gate parsePolicy gives for `product: <product>` alone, built by
|
|
172
|
+
* parsePolicy itself so its defaults have one source. The product is
|
|
173
|
+
* PRODUCT_FOR_ROLE's, which parsePolicy already required the head to match.
|
|
174
|
+
*/
|
|
175
|
+
function productDefault(role) {
|
|
176
|
+
const gate = parsePolicy(`version: 1\ngates:\n ${role}:\n product: ${PRODUCT_FOR_ROLE[role]}\n`, 'the preview default').gates[role];
|
|
177
|
+
if (gate === undefined) {
|
|
178
|
+
throw new Error(`no default gate for the ${role} role`);
|
|
179
|
+
}
|
|
180
|
+
return gate;
|
|
181
|
+
}
|
package/dist/resolve.d.ts
CHANGED
|
@@ -34,6 +34,20 @@ export interface ResolvedBinary {
|
|
|
34
34
|
program: string;
|
|
35
35
|
/** Arguments placed before the ones the umbrella adds. */
|
|
36
36
|
argvPrefix: string[];
|
|
37
|
+
/**
|
|
38
|
+
* Every file or directory the policy's own `args:` names on disk, as an
|
|
39
|
+
* absolute path, with every loadable sibling of each (`argumentCandidates`),
|
|
40
|
+
* in args order. Empty when the policy has no `args:`.
|
|
41
|
+
*
|
|
42
|
+
* Carried because an interpreter `command:` hands the program to run as an
|
|
43
|
+
* ARGUMENT: with `command: /usr/bin/node` and `args: [tools/gate/run.mjs]`
|
|
44
|
+
* the script is what judges, not Node, and the pull-request provenance check
|
|
45
|
+
* has to vet it the way it vets `program` (audit 2026-10-27, B1). Only the
|
|
46
|
+
* policy's args, never a candidate's built-in prefix (`scan`, `source`):
|
|
47
|
+
* those are subcommands this package wrote, and a directory of the same
|
|
48
|
+
* name in somebody's repository is not a program.
|
|
49
|
+
*/
|
|
50
|
+
argumentPaths: string[];
|
|
37
51
|
source: ResolutionSource;
|
|
38
52
|
/** The candidate name this matched, for the report's gate header. */
|
|
39
53
|
candidate: string;
|
|
@@ -89,3 +103,57 @@ export declare function nodeModulesCandidate(gate: GatePolicy, repoRoot: string)
|
|
|
89
103
|
export declare function resolveGateBinary(gate: GatePolicy, repoRoot: string, pathValue: string, options?: ResolveOptions): ResolvedBinary | null;
|
|
90
104
|
/** Every name resolution would try, for the missing-gate finding's message. */
|
|
91
105
|
export declare function candidateNames(product: Product): string[];
|
|
106
|
+
/**
|
|
107
|
+
* Whether the policy's `command:` is itself the gate program, so its `args:`
|
|
108
|
+
* are that gate's own argv rather than something an interpreter will load.
|
|
109
|
+
*
|
|
110
|
+
* True when the command's name is a candidate name (`vault-guard`,
|
|
111
|
+
* `intent-guard.js`), and for a non-executable `.js` command, which this
|
|
112
|
+
* package runs through its own Node with the script as the program. False
|
|
113
|
+
* for anything else, an interpreter such as `node` or `python3` above all.
|
|
114
|
+
* Only then are the product's subcommand words (`scan`, `source`) exempt
|
|
115
|
+
* from being read as paths: an interpreter handed `scan` runs `scan.js` or
|
|
116
|
+
* `scan/index.js`, so for it the word is a path like any other (audit
|
|
117
|
+
* 2026-10-27 fix round, MB3).
|
|
118
|
+
*/
|
|
119
|
+
export declare function commandIsGateProgram(gate: GatePolicy): boolean;
|
|
120
|
+
/**
|
|
121
|
+
* Every path an interpreter could load for one `args:` entry, as absolute
|
|
122
|
+
* paths, in the order checked; empty when the entry names nothing on disk
|
|
123
|
+
* (audit 2026-10-27, B1, and its fix round).
|
|
124
|
+
*
|
|
125
|
+
* Relative entries are resolved against `repoRoot`. That is the working
|
|
126
|
+
* directory of the version probe and of the gate's own spawn for every
|
|
127
|
+
* product except one whose base config can name further files
|
|
128
|
+
* (`followsConfigExtend`): on a pull request that gate runs from a temporary
|
|
129
|
+
* directory holding the base ref's copies (src/gate-runner.ts, spawnCwd), so
|
|
130
|
+
* a relative script there resolves against base copies or not at all, never
|
|
131
|
+
* against the head tree. The rules, in order:
|
|
132
|
+
*
|
|
133
|
+
* - An option with no `=` (`--json`, `-r`) names nothing. An option with one
|
|
134
|
+
* (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
|
|
135
|
+
* after the first `=`, since that is where an interpreter takes a file to
|
|
136
|
+
* load and a gate takes a file to read its rules from.
|
|
137
|
+
* - When `exemptSubcommands` is true (the command is the gate program
|
|
138
|
+
* itself, commandIsGateProgram), a bare word that is one of the product's
|
|
139
|
+
* own subcommands (`scan`, `git`, `source`, `check`) names nothing, even
|
|
140
|
+
* when a directory of that name exists. For an interpreter nothing is
|
|
141
|
+
* exempt.
|
|
142
|
+
* - The entry as written, when it exists as a file, a directory or a
|
|
143
|
+
* symlink, without following the symlink, so the caller can refuse an
|
|
144
|
+
* in-tree link on its own entry.
|
|
145
|
+
* - Then every `<entry>.js`, `.mjs`, `.cjs`, `.json` and `.node` that exists,
|
|
146
|
+
* slash or not, and whether or not the entry itself exists: Node tries
|
|
147
|
+
* those before a directory of the same name, and a bare `run` runs
|
|
148
|
+
* `run.js`. A sibling the head ADDED is listed too, which is what refuses
|
|
149
|
+
* it: the base does not track it.
|
|
150
|
+
*
|
|
151
|
+
* A directory's contents are covered by the caller's tree comparison, so
|
|
152
|
+
* `index.js` and `package.json` inside it are not listed separately; a
|
|
153
|
+
* `main` that points outside the directory is not vetted, the same limit as
|
|
154
|
+
* a program's directory. Everything else, a Python `-m` module name, a bare
|
|
155
|
+
* package specifier an interpreter resolves for itself, code passed as a
|
|
156
|
+
* string (`node -e`, `bash -c`), is not recognised as a path. The README says
|
|
157
|
+
* so.
|
|
158
|
+
*/
|
|
159
|
+
export declare function argumentCandidates(arg: string, repoRoot: string, product: Product, exemptSubcommands: boolean): string[];
|