@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.
@@ -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, refusedOnTerminal = false) {
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
- const lines = [
600
- ` pull-request mode: rules from ${result.trustBase.ref}. ${proposalCount(result)}.`,
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
- return `${result.gates.length} gate(s), ${result.findings.length} finding(s)`;
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
- * The version line, then the verdict-token line directly under it: the first
1526
- * two lines of every report that carries a token. Without a version the
1527
- * token is the first line. The closing verdict sentence is a separate thing
1528
- * and stays where it was.
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 fixed third line (osv design, section 4.4), printed only when known
1569
- // advisories were reported and not blocking. The Action copies it to the
1570
- // job summary when, and only when, line 3 is exactly this shape, so a pass
1571
- // that carries them does not read as spotless there either.
1572
- const reported = presentOnBaseReported(result);
1573
- // The intent-spec line follows it, so the present-on-base line, when
1574
- // present, stays line 3 and every report without an intent-spec line keeps
1575
- // the shape the Action already reads.
1576
- const specLine = intentSpecLine(result);
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
- ...(refusal.length === 0 ? [] : ['']),
1583
- `conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
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
- const refusedOnTerminal = options.terminal === true && refusal.length > 0;
1586
- if (refusedOnTerminal && result.gates.length > 0) {
1587
- lines.push('');
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 compact terminal refusal prints no finding line at all, so no asterisk.
1610
- if (!refusedOnTerminal && result.findings.some((finding) => finding.severityIsDerived)) {
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.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
- throw new PolicyError(`No ${POLICY_FILE_NAME} in ${repoRoot}. Run "conductor init" to write one. ` +
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
  }
@@ -23,6 +23,7 @@ export declare const BASE_MOVED = "conductor/base-moved";
23
23
  export declare const CONTROL_CHANGE_PROPOSED = "conductor/control-change-proposed";
24
24
  export declare const PREVIEW_UNDER_PROPOSED_RULES = "conductor/preview-under-proposed-rules";
25
25
  export declare const TRUST_BASE_REFUSED = "conductor/trust-base-refused";
26
+ export declare const PROPOSAL_RUN = "conductor/proposal-run";
26
27
  export declare const TRUST_BASE_NOT_PASSED = "conductor/trust-base-not-passed";
27
28
  export declare const GATE_PROGRAM_REFUSED = "conductor/gate-program-refused";
28
29
  export declare const NODE_MODULES_SKIPPED = "conductor/node-modules-skipped";
package/dist/rule-ids.js CHANGED
@@ -44,6 +44,7 @@ export const BASE_MOVED = 'conductor/base-moved';
44
44
  export const CONTROL_CHANGE_PROPOSED = 'conductor/control-change-proposed';
45
45
  export const PREVIEW_UNDER_PROPOSED_RULES = 'conductor/preview-under-proposed-rules';
46
46
  export const TRUST_BASE_REFUSED = 'conductor/trust-base-refused';
47
+ export const PROPOSAL_RUN = 'conductor/proposal-run';
47
48
  export const TRUST_BASE_NOT_PASSED = 'conductor/trust-base-not-passed';
48
49
  export const GATE_PROGRAM_REFUSED = 'conductor/gate-program-refused';
49
50
  export const NODE_MODULES_SKIPPED = 'conductor/node-modules-skipped';
@@ -84,6 +85,7 @@ export const RULE_IDS = [
84
85
  { id: CONTROL_CHANGE_PROPOSED, class: 'notification' },
85
86
  { id: PREVIEW_UNDER_PROPOSED_RULES, class: 'notification' },
86
87
  { id: TRUST_BASE_REFUSED, class: 'notification' },
88
+ { id: PROPOSAL_RUN, class: 'notification' },
87
89
  { id: TRUST_BASE_NOT_PASSED, class: 'notification' },
88
90
  { id: GATE_PROGRAM_REFUSED, class: 'notification' },
89
91
  { id: NODE_MODULES_SKIPPED, class: 'notification' },