@vaultcompass/conductor 0.18.0 → 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 +204 -61
- 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 +36 -0
- package/dist/escape.js +49 -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/osv-coverage.js +6 -5
- 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-diff.d.ts +2 -9
- package/dist/policy-diff.js +4 -11
- package/dist/policy.d.ts +9 -0
- package/dist/policy.js +21 -3
- package/dist/rule-ids.d.ts +42 -0
- package/dist/rule-ids.js +100 -0
- package/dist/run.d.ts +80 -0
- package/dist/run.js +70 -3
- package/package.json +1 -1
package/dist/output-text.js
CHANGED
|
@@ -23,12 +23,14 @@
|
|
|
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 { existingFindingsLines } from './existing-findings.js';
|
|
26
27
|
import { CONDUCTOR_OWN_REASONS, cleanOutputLine, cleanPreviewLine, conductorStatedReason, resolutionPlace, versionCharacters, versionSkewRemedy, } from './gate-runner.js';
|
|
27
28
|
import { isLegacyContractPath, legacyChangedSentence } from './intent-prepare.js';
|
|
28
29
|
import { SPEC_DIR } from './intent-spec.js';
|
|
29
|
-
import { PRODUCT_FOR_ROLE } from './policy.js';
|
|
30
|
+
import { POLICY_FILE_NAME, PRODUCT_FOR_ROLE } from './policy.js';
|
|
31
|
+
import { summaryField } from './escape.js';
|
|
30
32
|
import { escapeNonAscii } from './policy-diff.js';
|
|
31
|
-
import { guardPreview } from './run.js';
|
|
33
|
+
import { TRUST_BASE_REFUSED_DETAIL, guardPreview, isProposal, ranProposedPolicy, } from './run.js';
|
|
32
34
|
// A file path in a finding is the head's choice on any pull-request run (a
|
|
33
35
|
// file named with a right-to-left override in it), so in the text report,
|
|
34
36
|
// and so in the pull-request comment, every path is printed with
|
|
@@ -317,14 +319,7 @@ function conventionLines(gate) {
|
|
|
317
319
|
(match.runnerUp === null ? '' : `, runner-up ${SPEC_DIR}/${match.runnerUp}`);
|
|
318
320
|
return { under, chosenBy };
|
|
319
321
|
}
|
|
320
|
-
function gateSection(gate, verbose
|
|
321
|
-
// A gate the refused trust base stopped, on a terminal: the refusal is at
|
|
322
|
-
// the top of the report once, so the section is one line and no more.
|
|
323
|
-
// Every other caller (a file, a pipe, a pull request comment) keeps the full
|
|
324
|
-
// section, byte for byte.
|
|
325
|
-
if (refusedOnTerminal) {
|
|
326
|
-
return [` ${gate.role} ${gate.product} did not run: the trust base was refused (above)`];
|
|
327
|
-
}
|
|
322
|
+
function gateSection(gate, verbose) {
|
|
328
323
|
const lines = ['', header(gate, verbose)];
|
|
329
324
|
// Under the header, on every outcome that carries it: gitleaks' own
|
|
330
325
|
// --timeout is not conductor's limit, and the gate-error it produces is the
|
|
@@ -596,9 +591,22 @@ function trustBaseLines(result) {
|
|
|
596
591
|
if (result.trustBase.notGiven === true) {
|
|
597
592
|
return [' pull-request mode: no trust base was given, so no rules were read.'];
|
|
598
593
|
}
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
594
|
+
// A refused ref gave no rules and no gate was asked what the pull request
|
|
595
|
+
// proposes, so neither "rules from <ref>" nor a proposal count is true.
|
|
596
|
+
if (result.trustBase.refusal !== null && result.trustBase.refusal !== undefined) {
|
|
597
|
+
return [' pull-request mode: the trust base was refused, so no rules were read.'];
|
|
598
|
+
}
|
|
599
|
+
// A run of the policy the pull request adds took no rule from the ref: it
|
|
600
|
+
// has none. The count that follows is of what the head wrote and this run
|
|
601
|
+
// did NOT apply, plus what the gates said was proposed.
|
|
602
|
+
const lines = ranProposedPolicy(result)
|
|
603
|
+
? [
|
|
604
|
+
` pull-request mode: no policy on ${result.trustBase.ref}; this run previews the policy this ` +
|
|
605
|
+
`pull request adds. ${proposalCount(result)}.`,
|
|
606
|
+
' only enabled, stage and enforce were taken from that policy; any other key it sets is ' +
|
|
607
|
+
'listed as proposed and was not applied.',
|
|
608
|
+
]
|
|
609
|
+
: [` pull-request mode: rules from ${result.trustBase.ref}. ${proposalCount(result)}.`];
|
|
602
610
|
for (const proposal of result.proposals) {
|
|
603
611
|
lines.push(` proposed ${proposal.product.padEnd(13)} ${proposal.line}`);
|
|
604
612
|
}
|
|
@@ -689,7 +697,9 @@ export function jobLogSummary(result) {
|
|
|
689
697
|
? `pull-request job with no trust base, no rules read: ${refusal.replace(/\.+\s*$/, '')}`
|
|
690
698
|
: `refused the trust base "${result.trustBase?.ref ?? ''}": ${refusal.replace(/\.+\s*$/, '')}`;
|
|
691
699
|
}
|
|
692
|
-
|
|
700
|
+
const counts = `${result.gates.length} gate(s), ${result.findings.length} finding(s)`;
|
|
701
|
+
// A proposal's counts must not read as an enforced run's.
|
|
702
|
+
return isProposal(result) ? `proposal, no policy on "${result.trustBase?.ref ?? ''}": ${counts}` : counts;
|
|
693
703
|
}
|
|
694
704
|
/**
|
|
695
705
|
* The proposal lines for a job log: the count sentence, then one line per
|
|
@@ -856,6 +866,261 @@ export function gateLogLines(result, options = {}) {
|
|
|
856
866
|
}
|
|
857
867
|
return lines;
|
|
858
868
|
}
|
|
869
|
+
/**
|
|
870
|
+
* A version as the summary lines print it: version characters only, since a
|
|
871
|
+
* probed version can carry anything after x.y.z, or the words for none.
|
|
872
|
+
*/
|
|
873
|
+
function summaryVersion(raw) {
|
|
874
|
+
const version = raw === null ? '' : versionCharacters(raw);
|
|
875
|
+
return version === '' ? 'version unknown' : version;
|
|
876
|
+
}
|
|
877
|
+
/**
|
|
878
|
+
* ONE LINE FOR ONE GATE, from its outcome alone (issue 105): ran, with the
|
|
879
|
+
* gate version, the exit code and the blocking count, or did not run, with
|
|
880
|
+
* the reason. The line the step summary and the pull request comment lead
|
|
881
|
+
* with, so a gate that did not run can never read as one that passed.
|
|
882
|
+
*
|
|
883
|
+
* A CLOSED SHAPE. Every word is conductor's own (a role, a product, a
|
|
884
|
+
* could-not-run reason) and every other field is a number or a version cut
|
|
885
|
+
* to version characters, so nothing a pull request or a gate printed reaches
|
|
886
|
+
* the line. action.yml and scripts/lib/pr-comment.mjs copy a line only when
|
|
887
|
+
* it matches that shape whole.
|
|
888
|
+
*
|
|
889
|
+
* The blocking count is the findings the report marks blocking, not the
|
|
890
|
+
* token's count: a gate that exited non-zero with none marked says "exit 1,
|
|
891
|
+
* 0 blocking", which is what happened. A gate whose resolved version is not
|
|
892
|
+
* the one the run expected is could-not-run (version-skew) since 0.13.0, so
|
|
893
|
+
* that line is the one that prints both versions.
|
|
894
|
+
*
|
|
895
|
+
* Describes, decides nothing: the exit code was composed before this is read.
|
|
896
|
+
*/
|
|
897
|
+
export function gateSummaryLine(gate) {
|
|
898
|
+
const head = `gate ${gate.role} (${gate.product} ${summaryVersion(gate.productVersion)}): `;
|
|
899
|
+
const enforcement = gate.enforce ? '' : ', not enforced';
|
|
900
|
+
if (gate.couldNotRun !== null) {
|
|
901
|
+
const refused = gate.couldNotRun.reason === 'preparation-failed' && gate.couldNotRun.detail.startsWith(TRUST_BASE_REFUSED_DETAIL);
|
|
902
|
+
if (refused) {
|
|
903
|
+
// Never spawned, so nobody asked it for a version: no version at all,
|
|
904
|
+
// as for a deferred or disabled gate. "version unknown" is kept for a
|
|
905
|
+
// gate that was asked and did not say.
|
|
906
|
+
return `gate ${gate.role} (${gate.product}): did not run (trust base refused)${enforcement}`;
|
|
907
|
+
}
|
|
908
|
+
const pinned = gate.versionSkew === undefined ? '' : `, the action pinned ${summaryVersion(gate.versionSkew.expected)}`;
|
|
909
|
+
return `${head}did not run (${gate.couldNotRun.reason})${pinned}${enforcement}`;
|
|
910
|
+
}
|
|
911
|
+
// AT MOST THREE DIGITS, which the closed shape in action.yml and
|
|
912
|
+
// scripts/lib/pr-comment.mjs relies on. A gate reaches this branch only
|
|
913
|
+
// when its exit code is one its product lists as clean or blocked
|
|
914
|
+
// (src/products.ts: 0, 1 and 3 today); any other status, a Windows
|
|
915
|
+
// 32-bit one or a signal's null included, is could-not-run in runGate
|
|
916
|
+
// and takes the branch above, which prints no exit code.
|
|
917
|
+
const exit = gate.exitCode === null ? 'no exit code' : `exit ${gate.exitCode}`;
|
|
918
|
+
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
919
|
+
const nothing = gateCheckedNothing(gate) ? ', checked nothing' : '';
|
|
920
|
+
return `${head}ran, ${exit}, ${blocking} blocking${nothing}${enforcement}`;
|
|
921
|
+
}
|
|
922
|
+
/**
|
|
923
|
+
* The per-gate lines of a run: one per gate that has an outcome, then one per
|
|
924
|
+
* enabled gate that was never spawned (in the job log's own words for why),
|
|
925
|
+
* then one per gate the policy file switches off. The same closed shape.
|
|
926
|
+
*/
|
|
927
|
+
export function gateSummaryLines(result) {
|
|
928
|
+
const notRun = (gate, what) => `gate ${gate.role} (${gate.product}): ${what}`;
|
|
929
|
+
return [
|
|
930
|
+
...result.gates.map(gateSummaryLine),
|
|
931
|
+
...result.deferred.map((gate) => notRun(gate, `skipped (deferred to stage ${gate.stage})`)),
|
|
932
|
+
...result.skipped.map((gate) => notRun(gate, `skipped (${skipWording(gate.reason).line})`)),
|
|
933
|
+
...result.excluded.map((gate) => notRun(gate, 'skipped (--gate did not name it)')),
|
|
934
|
+
...result.treeUnchanged.map((gate) => notRun(gate, 'skipped (head tree equals the base tree)')),
|
|
935
|
+
...(result.disabled ?? []).map((gate) => notRun(gate, 'disabled (enabled: false)')),
|
|
936
|
+
];
|
|
937
|
+
}
|
|
938
|
+
/**
|
|
939
|
+
* The two fixed lines for a run whose trust base gave no rules. They name no
|
|
940
|
+
* ref and carry none of the refusal's own text, which is printed once in the
|
|
941
|
+
* report under them.
|
|
942
|
+
*/
|
|
943
|
+
export const TRUST_BASE_LINES = [
|
|
944
|
+
'trust-base: refused, no rules were read and no gate ran',
|
|
945
|
+
'trust-base: not given on a pull-request job, no rules were read and no gate ran',
|
|
946
|
+
];
|
|
947
|
+
/**
|
|
948
|
+
* The fixed line of a PROPOSAL (issue 101): a run of the policy a pull
|
|
949
|
+
* request adds to a base that has none, which exits 0 and enforced nothing.
|
|
950
|
+
* One number and no other text that varies: no ref, no branch, no file. The
|
|
951
|
+
* number is the verdict token's, `wouldBlock`.
|
|
952
|
+
*/
|
|
953
|
+
export function proposalLine(wouldBlockCount) {
|
|
954
|
+
return (`proposal: no ${POLICY_FILE_NAME} on the base branch, so nothing here was enforced; ` +
|
|
955
|
+
`${wouldBlockCount} would block once this policy is on the base branch`);
|
|
956
|
+
}
|
|
957
|
+
/**
|
|
958
|
+
* The fixed line of a refused pull-request run where neither the base nor
|
|
959
|
+
* the pull request has a policy file, and of a run with no trust base that
|
|
960
|
+
* found no policy file at all (the CLI appends it to the Actions step
|
|
961
|
+
* summary there). The workflow is present and checks nothing: said in so
|
|
962
|
+
* many words, since a red step alone was read as a broken tool.
|
|
963
|
+
*/
|
|
964
|
+
export const NO_POLICY_LINE = `no-policy: this workflow checks nothing until ${POLICY_FILE_NAME} is on the base branch; ` +
|
|
965
|
+
'run conductor init and merge it';
|
|
966
|
+
/**
|
|
967
|
+
* The fixed line of a pull request that deletes the policy file from a base
|
|
968
|
+
* that has one. That run is the ordinary one under the base's rules, so
|
|
969
|
+
* without this line the deletion is one "proposed" line among gate output.
|
|
970
|
+
* What it says about afterwards is what the code does: with no policy on the
|
|
971
|
+
* base every pull-request run is refused, and a pull request that adds one
|
|
972
|
+
* back is refused too (src/adoption-proposal.ts#refuseAdoptionProposal, the
|
|
973
|
+
* first-parent history rule).
|
|
974
|
+
*/
|
|
975
|
+
export const POLICY_REMOVED_LINE = `policy-removed: this pull request deletes ${POLICY_FILE_NAME}; once merged, nothing is enforced on ` +
|
|
976
|
+
'the base branch and every pull-request run is refused until a policy is back on it';
|
|
977
|
+
/** The heading of the named findings on a proposal, in place of "findings". */
|
|
978
|
+
export const PROPOSAL_FINDINGS_HEADING = 'would block once the policy is on the base';
|
|
979
|
+
/** The headings `findingSummaryLines` is ever given: a closed set the two readers spell too. */
|
|
980
|
+
export const FINDINGS_HEADINGS = ['findings', PROPOSAL_FINDINGS_HEADING];
|
|
981
|
+
/**
|
|
982
|
+
* THE RUN-LEVEL SLOT: the fixed lines about the run as a whole, printed
|
|
983
|
+
* directly under the verdict token and above the per-gate lines. Each is a
|
|
984
|
+
* closed shape (a fixed sentence, or one with numbers in it), so the Action
|
|
985
|
+
* and the comment poster can copy them without reading anything a pull
|
|
986
|
+
* request wrote. A later line about the run is added here and to the two
|
|
987
|
+
* closed sets that read it, and nowhere else.
|
|
988
|
+
*
|
|
989
|
+
* The present-on-base line stays first and the intent-spec line second, the
|
|
990
|
+
* two positions an Action older than this slot reads, on every run such an
|
|
991
|
+
* Action can be handed. The proposal line and the no-policy line go above
|
|
992
|
+
* them, because each is the first thing to know about its run: an older
|
|
993
|
+
* Action never passes --adoption-proposal, so it never sees a proposal, and
|
|
994
|
+
* a refused run has neither of the two older lines. The policy-removed line
|
|
995
|
+
* is on an ordinary run, so it goes below them.
|
|
996
|
+
*/
|
|
997
|
+
export function runLevelLines(result) {
|
|
998
|
+
const reported = presentOnBaseReported(result);
|
|
999
|
+
const specLine = intentSpecLine(result);
|
|
1000
|
+
const refusal = result.trustBase?.refusal;
|
|
1001
|
+
const refused = refusal !== undefined && refusal !== null;
|
|
1002
|
+
// What this pull request introduced (issue 102, first cut), from the one
|
|
1003
|
+
// split conductor already computes: the vulnerabilities gate's comparison
|
|
1004
|
+
// with the base, which runs only when its head scan found something. The
|
|
1005
|
+
// line says which gate, because no other gate compares with the base and a
|
|
1006
|
+
// bare count would claim their findings were all split too. Absent when no
|
|
1007
|
+
// comparison ran. No second base scan is made for it.
|
|
1008
|
+
const compared = result.gates.flatMap((gate) => (gate.baseComparison === undefined ? [] : [gate.baseComparison]));
|
|
1009
|
+
const sum = (pick) => compared.reduce((total, comparison) => total + pick(comparison), 0);
|
|
1010
|
+
return [
|
|
1011
|
+
...(isProposal(result) ? [proposalLine(wouldBlock(result))] : []),
|
|
1012
|
+
...(refused && result.trustBase?.noPolicy === true ? [NO_POLICY_LINE] : []),
|
|
1013
|
+
...(reported === 0 ? [] : [`present-on-base: ${reported} reported, not blocking`]),
|
|
1014
|
+
...(specLine === null ? [] : [specLine]),
|
|
1015
|
+
...(refused ? [TRUST_BASE_LINES[result.trustBase?.notGiven === true ? 1 : 0]] : []),
|
|
1016
|
+
...(!refused && result.trustBase?.policyRemoved === true ? [POLICY_REMOVED_LINE] : []),
|
|
1017
|
+
...(compared.length === 0
|
|
1018
|
+
? []
|
|
1019
|
+
: [
|
|
1020
|
+
`new in this pull request: ${sum((c) => c.introduced)} (vulnerabilities gate; ` +
|
|
1021
|
+
`${sum((c) => c.presentOnBase)} already on the base)`,
|
|
1022
|
+
]),
|
|
1023
|
+
];
|
|
1024
|
+
}
|
|
1025
|
+
/** How many findings the head block and the job log name before "and M more". */
|
|
1026
|
+
export const FINDINGS_NAMED = 10;
|
|
1027
|
+
/** The longest a named-finding line can be: its fixed words plus the four field caps below. */
|
|
1028
|
+
export const FINDING_LINE_MAX = 520;
|
|
1029
|
+
/** Where a named finding is: the package and its version, the file and line, or the paths. */
|
|
1030
|
+
function namedSubject(entry) {
|
|
1031
|
+
const first = entry[0];
|
|
1032
|
+
const subject = first.subject;
|
|
1033
|
+
if (first.product === 'osv-scanner' && subject.kind === 'package') {
|
|
1034
|
+
return osvSubject(entry);
|
|
1035
|
+
}
|
|
1036
|
+
switch (subject.kind) {
|
|
1037
|
+
case 'package': {
|
|
1038
|
+
const version = typeof first.details.version === 'string' ? `@${first.details.version}` : '';
|
|
1039
|
+
return `${subject.name}${version} (${subject.manifest})`;
|
|
1040
|
+
}
|
|
1041
|
+
case 'location':
|
|
1042
|
+
return `${subject.file}:${subject.line}`;
|
|
1043
|
+
case 'paths': {
|
|
1044
|
+
const more = subject.paths.length - 3;
|
|
1045
|
+
return `${subject.paths.slice(0, 3).join(', ')}${more > 0 ? ` and ${more} more` : ''}`;
|
|
1046
|
+
}
|
|
1047
|
+
default:
|
|
1048
|
+
return subjectLabel(first);
|
|
1049
|
+
}
|
|
1050
|
+
}
|
|
1051
|
+
/**
|
|
1052
|
+
* THE BLOCKING FINDINGS, NAMED (issue 144): a count line over every finding,
|
|
1053
|
+
* then the first `limit` BLOCKING entries as gate, rule, where and the
|
|
1054
|
+
* reason, then "and M more blocking". A finding that does not block is
|
|
1055
|
+
* counted and not named: it is in the gate's section. When none blocks the
|
|
1056
|
+
* count line stands alone, with no colon and no list. "Blocking" is the
|
|
1057
|
+
* gate's own mark on the finding, whatever --advisory or enforce: false
|
|
1058
|
+
* then does with the exit code. For the head block of the text report, which the Action copies to
|
|
1059
|
+
* the step summary and the comment poster lifts above the collapsed report,
|
|
1060
|
+
* and for the job log. Empty when no gate that ran reported one.
|
|
1061
|
+
*
|
|
1062
|
+
* EVERY FIELD IS TEXT A PULL REQUEST CAN CHOOSE (a path, a package name, a
|
|
1063
|
+
* rule a user pattern named, a message), so each goes through summaryField
|
|
1064
|
+
* (src/escape.ts) and nothing else writes one: a line is one printable ASCII
|
|
1065
|
+
* line with no backtick, tag or workflow command, at most FINDING_LINE_MAX
|
|
1066
|
+
* long, and always starts with the fixed word "finding: ", so it can never
|
|
1067
|
+
* be read as a per-gate line or a verdict.
|
|
1068
|
+
*
|
|
1069
|
+
* Only gates that RAN are named. A gate that could not run carries the
|
|
1070
|
+
* umbrella's own finding about the gate, and its per-gate line already says
|
|
1071
|
+
* it did not run. An osv-scanner advisory is one entry however many lockfiles
|
|
1072
|
+
* carry it, as in the gate's section. The heading is a parameter because a
|
|
1073
|
+
* later run mode lists the same findings under different words.
|
|
1074
|
+
*/
|
|
1075
|
+
export function findingSummaryLines(result, options = {}) {
|
|
1076
|
+
const heading = options.heading ?? 'findings';
|
|
1077
|
+
const limit = options.limit ?? FINDINGS_NAMED;
|
|
1078
|
+
const entries = result.gates
|
|
1079
|
+
.filter((gate) => gate.couldNotRun === null)
|
|
1080
|
+
.flatMap(findingEntries)
|
|
1081
|
+
.sort((a, b) => compareFindings(a[0], b[0]));
|
|
1082
|
+
if (entries.length === 0) {
|
|
1083
|
+
return [];
|
|
1084
|
+
}
|
|
1085
|
+
// T and B count FINDINGS, as every other count on the report does. K and M
|
|
1086
|
+
// count the LINES below, which are entries: one osv advisory on one
|
|
1087
|
+
// package is one line however many lockfiles carry it. K and M are always
|
|
1088
|
+
// the same unit as each other.
|
|
1089
|
+
const total = entries.reduce((sum, entry) => sum + entry.length, 0);
|
|
1090
|
+
const blocking = entries.flat().filter((finding) => finding.blocking).length;
|
|
1091
|
+
const named = entries.filter((entry) => entry.some((finding) => finding.blocking));
|
|
1092
|
+
if (named.length === 0) {
|
|
1093
|
+
return [`${heading}: ${total} (0 blocking)`];
|
|
1094
|
+
}
|
|
1095
|
+
const shown = named.slice(0, limit);
|
|
1096
|
+
const more = named.length - shown.length;
|
|
1097
|
+
const lines = [`${heading}: ${total} (${blocking} blocking)${more > 0 ? `, the first ${shown.length}` : ''}:`];
|
|
1098
|
+
for (const entry of shown) {
|
|
1099
|
+
const first = entry[0];
|
|
1100
|
+
const subject = summaryField(namedSubject(entry), 160);
|
|
1101
|
+
lines.push(`finding: BLOCKING ${summaryField(first.product, 40)} ` +
|
|
1102
|
+
`${summaryField(first.ruleId, 80)}${subject === '' ? '' : ` ${subject}`}: ${summaryField(first.message, 200)}`);
|
|
1103
|
+
}
|
|
1104
|
+
if (more > 0) {
|
|
1105
|
+
lines.push(`and ${more} more blocking`);
|
|
1106
|
+
}
|
|
1107
|
+
return lines;
|
|
1108
|
+
}
|
|
1109
|
+
/**
|
|
1110
|
+
* The same lines for the job log, so a run whose report went to a file still
|
|
1111
|
+
* says what was found where its log is read (issue 144: a blocked run's log
|
|
1112
|
+
* said only "findings (36, 36 blocking)").
|
|
1113
|
+
*/
|
|
1114
|
+
export function findingLogLines(result) {
|
|
1115
|
+
return findingSummaryLines(result, findingsHeading(result)).map((line) => `conductor: ${line}`);
|
|
1116
|
+
}
|
|
1117
|
+
/**
|
|
1118
|
+
* The heading option for this run's named findings: on a proposal they are
|
|
1119
|
+
* what would block, never what did.
|
|
1120
|
+
*/
|
|
1121
|
+
function findingsHeading(result) {
|
|
1122
|
+
return isProposal(result) ? { heading: PROPOSAL_FINDINGS_HEADING } : {};
|
|
1123
|
+
}
|
|
859
1124
|
/** Where a skewed binary came from, in words. Never a machine path. */
|
|
860
1125
|
export function skewPlace(skew) {
|
|
861
1126
|
return resolutionPlace(skew.source);
|
|
@@ -947,6 +1212,14 @@ function blockingCount(gate) {
|
|
|
947
1212
|
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
948
1213
|
return blocking === 0 && gateExitBlocks(gate) ? 1 : blocking;
|
|
949
1214
|
}
|
|
1215
|
+
/**
|
|
1216
|
+
* N of `proposal (N)`: what would block once the proposed policy is on the
|
|
1217
|
+
* base branch. Counted exactly as `blocked (N)` is, over the gates the
|
|
1218
|
+
* proposed policy enforces, so a gate that could not run is never in it.
|
|
1219
|
+
*/
|
|
1220
|
+
function wouldBlock(result) {
|
|
1221
|
+
return result.gates.filter((gate) => gate.enforce).reduce((total, gate) => total + blockingCount(gate), 0);
|
|
1222
|
+
}
|
|
950
1223
|
/**
|
|
951
1224
|
* The verdict token: a label for the umbrella's OWN exit decision, in a
|
|
952
1225
|
* closed set, so a person or a script reading a report or a job summary gets
|
|
@@ -990,6 +1263,16 @@ export function verdictToken(result, advisory) {
|
|
|
990
1263
|
if (refused || (result.exitCode !== 0 && result.exitCode !== EXIT_BLOCKED)) {
|
|
991
1264
|
return 'could-not-run';
|
|
992
1265
|
}
|
|
1266
|
+
// A PROPOSAL (issue 101), after the refusal and before every other token:
|
|
1267
|
+
// exit 0 on a run that enforced nothing must never read as pass,
|
|
1268
|
+
// nothing-checked or any token an enforced run can have. `isProposal` is
|
|
1269
|
+
// true only at exit 0, so a run of a proposed policy in which an enforced
|
|
1270
|
+
// gate could not run took the could-not-run branch above.
|
|
1271
|
+
if (isProposal(result)) {
|
|
1272
|
+
return result.gates.length === 0 || result.gates.every(gateCheckedNothing)
|
|
1273
|
+
? 'proposal-nothing-checked'
|
|
1274
|
+
: `proposal (${wouldBlock(result)})`;
|
|
1275
|
+
}
|
|
993
1276
|
if (result.exitCode === EXIT_BLOCKED) {
|
|
994
1277
|
const count = result.gates
|
|
995
1278
|
.filter((gate) => gate.enforce)
|
|
@@ -1087,8 +1370,34 @@ function verdict(result, advisory) {
|
|
|
1087
1370
|
: `verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
|
|
1088
1371
|
'so no gate ran and nothing here is a result of any kind.';
|
|
1089
1372
|
}
|
|
1373
|
+
if (isProposal(result)) {
|
|
1374
|
+
return proposalVerdict(result);
|
|
1375
|
+
}
|
|
1090
1376
|
return verdictForRun(result, advisory);
|
|
1091
1377
|
}
|
|
1378
|
+
/**
|
|
1379
|
+
* The closing sentence of a proposal. Written rather than composed, as the
|
|
1380
|
+
* refusal's is: exit 0 here is not a count of anything, and no clause of
|
|
1381
|
+
* `verdictForRun` ("every enabled gate ran and none blocked") is true of a
|
|
1382
|
+
* run that enforced nothing. --advisory has nothing to say on it.
|
|
1383
|
+
*/
|
|
1384
|
+
function proposalVerdict(result) {
|
|
1385
|
+
const lead = `verdict: exit 0, proposal, not a verdict: there is no ${POLICY_FILE_NAME} on ` +
|
|
1386
|
+
`"${result.trustBase?.ref ?? ''}", so nothing here could be enforced.`;
|
|
1387
|
+
if (result.gates.length === 0) {
|
|
1388
|
+
return `${lead} The policy this pull request adds ran no gate, so nothing was checked.`;
|
|
1389
|
+
}
|
|
1390
|
+
if (result.gates.every(gateCheckedNothing)) {
|
|
1391
|
+
return (`${lead} Nothing was checked: ${result.gates.map(checkedNothingWording).join('; ')}.`);
|
|
1392
|
+
}
|
|
1393
|
+
// An unenforced gate that could not run changes no exit code, here as
|
|
1394
|
+
// anywhere, and is named so the count beside it is not read as complete.
|
|
1395
|
+
const broken = result.gates.filter((gate) => !gate.enforce && gate.couldNotRun !== null).map((gate) => gate.role);
|
|
1396
|
+
return (`${lead} ${wouldBlock(result)} would block once this policy is on the base branch.` +
|
|
1397
|
+
(broken.length === 0
|
|
1398
|
+
? ''
|
|
1399
|
+
: ` ${broken.join(', ')} could not run, and the proposed policy has enforce: false there.`));
|
|
1400
|
+
}
|
|
1092
1401
|
function verdictForRun(result, advisory) {
|
|
1093
1402
|
// Counted over ENFORCED gates only. The exit code came from those alone,
|
|
1094
1403
|
// so a count taken over all of them describes a different run from the one
|
|
@@ -1269,6 +1578,12 @@ function verdictForRun(result, advisory) {
|
|
|
1269
1578
|
* confusion this family exists to prevent.
|
|
1270
1579
|
*/
|
|
1271
1580
|
function isFullyClean(result) {
|
|
1581
|
+
// A run of the policy a pull request adds enforced nothing, and "clean,
|
|
1582
|
+
// nothing blocked" on one line would be the pass it is not. Always the
|
|
1583
|
+
// full report, with or without --verbose.
|
|
1584
|
+
if (result.trustBase?.proposal !== undefined) {
|
|
1585
|
+
return false;
|
|
1586
|
+
}
|
|
1272
1587
|
// Every gate that ran checked nothing is the nothing-checked token's state
|
|
1273
1588
|
// (audit finding F4), and a line opening "clean" would contradict it.
|
|
1274
1589
|
if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing) || result.gates.some(intentEmptyChangeSet)) {
|
|
@@ -1522,15 +1837,24 @@ function versionLine(version) {
|
|
|
1522
1837
|
return version === undefined ? [] : [`conductor ${version}`];
|
|
1523
1838
|
}
|
|
1524
1839
|
/**
|
|
1525
|
-
*
|
|
1526
|
-
*
|
|
1527
|
-
*
|
|
1528
|
-
*
|
|
1840
|
+
* THE HEAD BLOCK: the version line, the verdict-token line directly under it
|
|
1841
|
+
* (the first line without a version), then the run-level fixed lines, then
|
|
1842
|
+
* one line per gate, then the named findings. Contiguous, in that order. A
|
|
1843
|
+
* reader of the report (the Action, the comment poster) takes lines from the
|
|
1844
|
+
* third on for as long as each matches and stops at the first that does not.
|
|
1845
|
+
* Down to the last per-gate line every line is a closed shape: no text from
|
|
1846
|
+
* a gate or a pull request sits there. The named findings under them do
|
|
1847
|
+
* carry such text, each field escaped and capped by summaryField, each line
|
|
1848
|
+
* starting with a fixed word. The closing verdict sentence is a separate
|
|
1849
|
+
* thing and stays where it was.
|
|
1529
1850
|
*/
|
|
1530
1851
|
function headerLines(result, options) {
|
|
1531
1852
|
return [
|
|
1532
1853
|
...versionLine(options.version),
|
|
1533
1854
|
`verdict-token: ${verdictToken(result, Boolean(options.advisory))}`,
|
|
1855
|
+
...runLevelLines(result),
|
|
1856
|
+
...gateSummaryLines(result),
|
|
1857
|
+
...findingSummaryLines(result, findingsHeading(result)),
|
|
1534
1858
|
];
|
|
1535
1859
|
}
|
|
1536
1860
|
export function renderText(result, options = {}) {
|
|
@@ -1565,29 +1889,30 @@ export function renderText(result, options = {}) {
|
|
|
1565
1889
|
// question, what failed the run, and that one is enforced gates only. Two
|
|
1566
1890
|
// different questions, so two numbers, and the section headers and the
|
|
1567
1891
|
// "not enforced" lines are what connect them.
|
|
1568
|
-
// The
|
|
1569
|
-
//
|
|
1570
|
-
//
|
|
1571
|
-
//
|
|
1572
|
-
|
|
1573
|
-
//
|
|
1574
|
-
//
|
|
1575
|
-
//
|
|
1576
|
-
|
|
1892
|
+
// The head block carries the fixed lines the Action copies to the job
|
|
1893
|
+
// summary: the present-on-base line (osv design, section 4.4), the
|
|
1894
|
+
// intent-spec line, and one line per gate.
|
|
1895
|
+
//
|
|
1896
|
+
// A REFUSED RUN prints its refusal once, here, and no gate section: every
|
|
1897
|
+
// gate is already "did not run (trust base refused)" in the head block,
|
|
1898
|
+
// and a section per gate repeated the refusal in each header and again in
|
|
1899
|
+
// each gate's finding. Its count line counts nothing either: refusedTrustBase
|
|
1900
|
+
// fills result.gates and result.findings with one could-not-run outcome per
|
|
1901
|
+
// enabled gate, so "N gate(s), N finding(s)" described a run that did not
|
|
1902
|
+
// happen (the same defect jobLogSummary was fixed for, issue #46).
|
|
1903
|
+
const refused = refusal.length > 0;
|
|
1577
1904
|
const lines = [
|
|
1578
1905
|
...headerLines(result, options),
|
|
1579
|
-
...(reported === 0 ? [] : [`present-on-base: ${reported} reported, not blocking`]),
|
|
1580
|
-
...(specLine === null ? [] : [specLine]),
|
|
1581
1906
|
...refusal,
|
|
1582
|
-
...(
|
|
1583
|
-
|
|
1907
|
+
...(refused ? [''] : []),
|
|
1908
|
+
refused
|
|
1909
|
+
? 'conductor run: no gate ran and nothing was checked'
|
|
1910
|
+
: `conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
|
|
1584
1911
|
];
|
|
1585
|
-
|
|
1586
|
-
|
|
1587
|
-
|
|
1588
|
-
|
|
1589
|
-
for (const gate of result.gates) {
|
|
1590
|
-
lines.push(...gateSection(gate, Boolean(options.verbose), refusedOnTerminal));
|
|
1912
|
+
if (!refused) {
|
|
1913
|
+
for (const gate of result.gates) {
|
|
1914
|
+
lines.push(...gateSection(gate, Boolean(options.verbose)));
|
|
1915
|
+
}
|
|
1591
1916
|
}
|
|
1592
1917
|
const aside = [
|
|
1593
1918
|
...deferredLines(result),
|
|
@@ -1606,10 +1931,20 @@ export function renderText(result, options = {}) {
|
|
|
1606
1931
|
// A derived severity is marked with a trailing asterisk above; say what
|
|
1607
1932
|
// that means rather than leaving a reader to guess, and only when one is
|
|
1608
1933
|
// actually on screen.
|
|
1609
|
-
// A
|
|
1610
|
-
if (!
|
|
1934
|
+
// A refused run prints no finding line at all, so no asterisk.
|
|
1935
|
+
if (!refused && result.findings.some((finding) => finding.severityIsDerived)) {
|
|
1611
1936
|
lines.push('', '* severity assigned by the umbrella; that gate reports no per-finding severity.');
|
|
1612
1937
|
}
|
|
1938
|
+
// After the gates and before the verdict. Words only: it reads nothing the
|
|
1939
|
+
// verdict reads and changes none of it. Never on a trust-base run, and only
|
|
1940
|
+
// on a blocked run (exit 1 as composed, before any advisory mapping): a
|
|
1941
|
+
// run that could not run says that, not how old its findings are.
|
|
1942
|
+
if (result.existingFindings !== undefined &&
|
|
1943
|
+
result.trustBase === null &&
|
|
1944
|
+
!refused &&
|
|
1945
|
+
result.exitCode === EXIT_BLOCKED) {
|
|
1946
|
+
lines.push('', ...existingFindingsLines(result.existingFindings));
|
|
1947
|
+
}
|
|
1613
1948
|
lines.push('', verdict(result, Boolean(options.advisory)));
|
|
1614
1949
|
return withPreview(`${lines.join('\n')}\n`);
|
|
1615
1950
|
}
|
package/dist/policy-diff.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { escapeNonAscii } from './escape.js';
|
|
1
2
|
import type { GateRole, Policy } from './policy.js';
|
|
2
3
|
export interface PolicyKeyChange {
|
|
3
4
|
/** The gate role the key belongs to, or null for a key outside any gate. */
|
|
@@ -14,15 +15,7 @@ export declare const HEAD_POLICY_KEY = ".guardrails.yaml";
|
|
|
14
15
|
* file's. A null head (absent or unparseable) is one change that says so.
|
|
15
16
|
*/
|
|
16
17
|
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;
|
|
18
|
+
export { escapeNonAscii };
|
|
26
19
|
/** One proposal line for one changed key. */
|
|
27
20
|
export declare function policyChangeLine(change: PolicyKeyChange): string;
|
|
28
21
|
/**
|
package/dist/policy-diff.js
CHANGED
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
// verdict. The one place a head value goes further is `previewPolicy`, which
|
|
9
9
|
// takes only `enabled`, `stage` and `enforce` from it for the preview under
|
|
10
10
|
// the proposed rules, a run that decides nothing.
|
|
11
|
+
import { escapeNonAscii } from './escape.js';
|
|
11
12
|
import { GATE_ROLES, PRODUCT_FOR_ROLE, parsePolicy } from './policy.js';
|
|
12
13
|
export const HEAD_POLICY_KEY = '.guardrails.yaml';
|
|
13
14
|
const MAX_VALUE_LENGTH = 80;
|
|
@@ -92,17 +93,9 @@ export function diffPolicies(base, head) {
|
|
|
92
93
|
}
|
|
93
94
|
return changes;
|
|
94
95
|
}
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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
|
-
}
|
|
96
|
+
// escapeNonAscii lives in src/escape.ts, a dependency-free leaf; it is
|
|
97
|
+
// re-exported here so existing importers keep working unchanged.
|
|
98
|
+
export { escapeNonAscii };
|
|
106
99
|
function renderValue(value) {
|
|
107
100
|
if (value === undefined)
|
|
108
101
|
return '(absent)';
|
package/dist/policy.d.ts
CHANGED
|
@@ -112,6 +112,15 @@ export interface Policy {
|
|
|
112
112
|
export declare class PolicyError extends Error {
|
|
113
113
|
constructor(message: string);
|
|
114
114
|
}
|
|
115
|
+
/**
|
|
116
|
+
* There is no policy file on disk at all (ENOENT, and nothing else). A
|
|
117
|
+
* PolicyError, so every caller treats it as before; the run command reads
|
|
118
|
+
* the subclass to say, in the Actions step summary, that the workflow is
|
|
119
|
+
* present and checks nothing.
|
|
120
|
+
*/
|
|
121
|
+
export declare class MissingPolicyError extends PolicyError {
|
|
122
|
+
constructor(message: string);
|
|
123
|
+
}
|
|
115
124
|
/**
|
|
116
125
|
* Parses and validates policy YAML.
|
|
117
126
|
*
|
package/dist/policy.js
CHANGED
|
@@ -176,6 +176,18 @@ export class PolicyError extends Error {
|
|
|
176
176
|
this.name = 'PolicyError';
|
|
177
177
|
}
|
|
178
178
|
}
|
|
179
|
+
/**
|
|
180
|
+
* There is no policy file on disk at all (ENOENT, and nothing else). A
|
|
181
|
+
* PolicyError, so every caller treats it as before; the run command reads
|
|
182
|
+
* the subclass to say, in the Actions step summary, that the workflow is
|
|
183
|
+
* present and checks nothing.
|
|
184
|
+
*/
|
|
185
|
+
export class MissingPolicyError extends PolicyError {
|
|
186
|
+
constructor(message) {
|
|
187
|
+
super(message);
|
|
188
|
+
this.name = 'MissingPolicyError';
|
|
189
|
+
}
|
|
190
|
+
}
|
|
179
191
|
const SCHEMA_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'schema', 'guardrails.schema.json');
|
|
180
192
|
let validator;
|
|
181
193
|
function policyValidator() {
|
|
@@ -392,10 +404,16 @@ export function loadPolicy(repoRoot) {
|
|
|
392
404
|
try {
|
|
393
405
|
text = readFileSync(filePath, 'utf8');
|
|
394
406
|
}
|
|
395
|
-
catch {
|
|
396
|
-
|
|
407
|
+
catch (error) {
|
|
408
|
+
const message = `No ${POLICY_FILE_NAME} in ${repoRoot}. Run "conductor init" to write one. ` +
|
|
397
409
|
'The umbrella deliberately has no implicit default policy: a run that gates a commit ' +
|
|
398
|
-
'should be explainable from a file in the repository, not from a built-in.'
|
|
410
|
+
'should be explainable from a file in the repository, not from a built-in.';
|
|
411
|
+
// Only a file that is not there is "missing". One that is there and
|
|
412
|
+
// cannot be read (permissions, a directory at that name) keeps the same
|
|
413
|
+
// sentence and is not told to run init.
|
|
414
|
+
throw error?.code === 'ENOENT'
|
|
415
|
+
? new MissingPolicyError(message)
|
|
416
|
+
: new PolicyError(message);
|
|
399
417
|
}
|
|
400
418
|
return parsePolicy(text, POLICY_FILE_NAME);
|
|
401
419
|
}
|