@vaultcompass/conductor 0.18.1 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/git.js CHANGED
@@ -9,8 +9,15 @@
9
9
  // other. Outside pull-request mode this is plain `git`, found the way a
10
10
  // shell finds it.
11
11
  //
12
- // - REPLACE OBJECTS ARE IGNORED. GIT_NO_REPLACE_OBJECTS is set on every
13
- // call, so every read here sees the commit's own objects.
12
+ // - REPLACE OBJECTS, GRAFTS AND A COMMIT-GRAPH FILE ARE IGNORED. Every call
13
+ // passes core.useReplaceRefs=false and core.commitGraph=false on the
14
+ // command line (`PINNED_GIT_CONFIG`), where no configuration file and no
15
+ // GIT_CONFIG_COUNT entry can outrank them, and sets GIT_NO_REPLACE_OBJECTS
16
+ // as well, so every read here sees the commit's own objects. The variable
17
+ // alone is not enough: configuration can turn replacement back on over
18
+ // it. GIT_GRAFT_FILE names a path that cannot exist, so every read of a
19
+ // commit's parents sees the parents the commit itself records
20
+ // (`pinnedGitEnv`); git has no configuration key for a graft file.
14
21
  //
15
22
  // - NOTHING HERE DECIDES WHAT A FAILURE MEANS. The result carries the exit
16
23
  // status and the error, and each caller keeps "git said there is nothing
@@ -31,13 +38,141 @@ export function currentGitProgram() {
31
38
  export function useGitProgram(program) {
32
39
  gitProgram = program;
33
40
  }
41
+ /**
42
+ * A graft file path that cannot exist: /dev/null is not a directory, so
43
+ * nothing can be created under it. The same value the Action's fetch step
44
+ * exports (action.yml, "Fetch the trust base"). git reads a missing graft
45
+ * file as no grafts, without a warning.
46
+ */
47
+ export const NO_GRAFT_FILE = '/dev/null/conductor-no-grafts';
48
+ /**
49
+ * git loads a commit-graph file when GIT_TEST_COMMIT_GRAPH is true, over
50
+ * core.commitGraph=false on the command line and in GIT_CONFIG_PARAMETERS.
51
+ * The environments conductor builds do not pass the variable on. A value
52
+ * that is absent stays absent. The caller's object is never changed.
53
+ */
54
+ function withoutCommitGraphTestVariable(env) {
55
+ if (!Object.prototype.hasOwnProperty.call(env, 'GIT_TEST_COMMIT_GRAPH')) {
56
+ return env;
57
+ }
58
+ const copy = { ...env };
59
+ delete copy.GIT_TEST_COMMIT_GRAPH;
60
+ return copy;
61
+ }
62
+ /**
63
+ * The environment of every git call conductor makes itself: the caller's
64
+ * own, with replace objects off and the graft file pointed at nothing.
65
+ *
66
+ * A replace ref swaps one object for another and a graft gives a commit
67
+ * other parents, both from files in the git directory that no commit
68
+ * records. The trees were always read without the first. The second matters
69
+ * since the adoption proposal (issue 101), which asks what the merge bases
70
+ * of two commits are and what the base branch's own first-parent history
71
+ * touched: both answers are read from parents, and a graft would rewrite
72
+ * them. Set last, so a value already in the environment never wins.
73
+ */
74
+ export function pinnedGitEnv(env = process.env) {
75
+ return { ...withoutCommitGraphTestVariable(env), GIT_NO_REPLACE_OBJECTS: '1', GIT_GRAFT_FILE: NO_GRAFT_FILE };
76
+ }
77
+ /**
78
+ * Configuration set on the command line of every git call conductor makes
79
+ * itself, ahead of the subcommand. The command line outranks every other
80
+ * place git reads configuration from: the system, global and repository
81
+ * files, anything they include, and GIT_CONFIG_COUNT in the environment.
82
+ *
83
+ * - core.useReplaceRefs=false. GIT_NO_REPLACE_OBJECTS is NOT enough on its
84
+ * own: the same key set to true in any configuration git reads turns
85
+ * replacement back on over the variable (seen on git 2.39.3), and a
86
+ * replace ref can then swap the base commit for one with another tree and
87
+ * other parents. The variable stays as well, for a git where it is the
88
+ * one that counts.
89
+ * - core.commitGraph=false. A commit-graph file in the git directory holds
90
+ * each commit's parents and root tree, and no commit records it, so every
91
+ * read takes both from the commit object itself.
92
+ */
93
+ export const PINNED_GIT_CONFIG = [
94
+ '-c',
95
+ 'core.useReplaceRefs=false',
96
+ '-c',
97
+ 'core.commitGraph=false',
98
+ ];
99
+ /**
100
+ * GIT_CONFIG_COUNT as git reads it (strtoul, base 10): leading white space,
101
+ * an optional sign, then digits and nothing after them. The number of
102
+ * entries, or null when git itself refuses the value: something after the
103
+ * digits, a negative number other than zero, or more than a 32-bit int
104
+ * holds. Unset and empty are both zero entries.
105
+ */
106
+ function configCountAsGitReadsIt(raw) {
107
+ if (raw === undefined || raw === '') {
108
+ return 0;
109
+ }
110
+ const read = raw.match(/^[ \t\n\v\f\r]*([+-]?)([0-9]+)$/);
111
+ if (read === null) {
112
+ return null;
113
+ }
114
+ const count = Number(read[2]);
115
+ if (!Number.isSafeInteger(count) || count > 2147483646 || (read[1] === '-' && count !== 0)) {
116
+ return null;
117
+ }
118
+ return count;
119
+ }
120
+ /**
121
+ * The environment of a gate conductor starts: `env`, plus the pins below.
122
+ * GIT_TEST_COMMIT_GRAPH is not passed on. A `-c` the gate itself adds is
123
+ * not something this function can outrank.
124
+ *
125
+ * conductor cannot put anything on the command line of a git call a gate
126
+ * makes itself. What it can give the gate is the two environment channels
127
+ * git reads configuration from. Numbered GIT_CONFIG_COUNT pairs are read
128
+ * after every configuration file, so an entry there outranks
129
+ * core.useReplaceRefs=true in the repository's configuration or a global
130
+ * one. GIT_CONFIG_PARAMETERS is read after those numbered entries, so it
131
+ * outranks them and the files. GIT_NO_REPLACE_OBJECTS does not: such a
132
+ * setting turns replacement back on over it. A -c the gate passes on its
133
+ * own git command line is read after GIT_CONFIG_PARAMETERS and still wins;
134
+ * none of the spawns here pass one.
135
+ *
136
+ * The numbered entry is APPENDED, at the index the caller's own count ends
137
+ * on, never written at index 0: the caller's entries are kept (an Action's
138
+ * authentication header is one), and of two entries for one key git takes
139
+ * the later. It is core.useReplaceRefs=false only. The same value, and
140
+ * core.commitGraph=false, are appended to GIT_CONFIG_PARAMETERS after
141
+ * exactly one space. When the caller's value is unset or the empty string
142
+ * the two pins are the whole value, with no leading space. The caller's
143
+ * value is not trimmed, parsed or repaired.
144
+ *
145
+ * A count git refuses is left exactly as it is and nothing is appended to
146
+ * the numbered entries. The parameters pins are still set on that branch,
147
+ * so there is no branch where they are absent. With a count git refuses,
148
+ * every git call fails, and a failed read is a refusal everywhere here;
149
+ * rewriting the count to make git work again would be conductor deciding
150
+ * what the caller meant. Returns a new object and never changes `env`.
151
+ */
152
+ export function gateChildEnv(env = process.env) {
153
+ const source = withoutCommitGraphTestVariable(env);
154
+ const pins = "'core.useReplaceRefs=false' 'core.commitGraph=false'";
155
+ const caller = source.GIT_CONFIG_PARAMETERS;
156
+ const parameters = caller === undefined || caller === '' ? pins : `${caller} ${pins}`;
157
+ const count = configCountAsGitReadsIt(source.GIT_CONFIG_COUNT);
158
+ if (count === null) {
159
+ return { ...source, GIT_CONFIG_PARAMETERS: parameters };
160
+ }
161
+ return {
162
+ ...source,
163
+ GIT_CONFIG_COUNT: String(count + 1),
164
+ [`GIT_CONFIG_KEY_${count}`]: 'core.useReplaceRefs',
165
+ [`GIT_CONFIG_VALUE_${count}`]: 'false',
166
+ GIT_CONFIG_PARAMETERS: parameters,
167
+ };
168
+ }
34
169
  /** Runs one git command in `cwd`, reading stdout as UTF-8. Never throws. */
35
170
  export function runGit(cwd, args, options = {}) {
36
- const child = spawnSync(gitProgram, [...args], {
171
+ const child = spawnSync(gitProgram, [...PINNED_GIT_CONFIG, ...args], {
37
172
  cwd,
38
173
  encoding: 'utf8',
39
174
  maxBuffer: options.maxBuffer ?? 32 * 1024 * 1024,
40
- env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' },
175
+ env: pinnedGitEnv(),
41
176
  ...(options.input === undefined ? {} : { input: options.input }),
42
177
  });
43
178
  return {
@@ -54,10 +189,10 @@ export function runGit(cwd, args, options = {}) {
54
189
  * program, same environment and same never-throws contract as runGit.
55
190
  */
56
191
  export function runGitBytes(cwd, args, options = {}) {
57
- const child = spawnSync(gitProgram, [...args], {
192
+ const child = spawnSync(gitProgram, [...PINNED_GIT_CONFIG, ...args], {
58
193
  cwd,
59
194
  maxBuffer: options.maxBuffer ?? 64 * 1024 * 1024,
60
- env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' },
195
+ env: pinnedGitEnv(),
61
196
  });
62
197
  return {
63
198
  status: child.status,
package/dist/init.js CHANGED
@@ -542,6 +542,15 @@ function finishPlan(options, root, policyPath, base, actions, writes, records, h
542
542
  `job without ${one ? 'it' : 'them'} gets conductor/gate-missing and exit 2; set enabled: ` +
543
543
  `false in ${POLICY_FILE_NAME} if that is not wanted.`);
544
544
  }
545
+ // What the first run will show, said once at the point the history gate is
546
+ // switched on. Words only: it changes no policy key and no verdict.
547
+ if (detected.has('secrets-history')) {
548
+ notes.push(`Note: the first conductor run with no base judges all of git history${detected.has('vulnerabilities') ? ' and every lockfile' : ''}; a pull request judges only its own change.`);
549
+ if (gitOutput(root, ['rev-parse', '--is-shallow-repository']) === 'true') {
550
+ notes.push('Note: this checkout is shallow, so the history gate will not run here until it is unshallowed ' +
551
+ '(git fetch --unshallow), and CI needs fetch-depth: 0 on actions/checkout. The gate stays enabled.');
552
+ }
553
+ }
545
554
  }
546
555
  else {
547
556
  // Never rewritten. The policy file is the one artifact a user edits by
@@ -30,6 +30,7 @@
30
30
  // distinguishes a shallow checkout from a spec the importer choked on is the
31
31
  // sentence in the report.
32
32
  import { spawnSync } from 'node:child_process';
33
+ import { gateChildEnv } from './git.js';
33
34
  import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
34
35
  import os from 'node:os';
35
36
  import path from 'node:path';
@@ -356,6 +357,9 @@ function run(command, argv, cwd, timeoutMs) {
356
357
  encoding: 'utf8',
357
358
  timeout: timeoutMs,
358
359
  maxBuffer: 64 * 1024 * 1024,
360
+ // The same pin as every other gate spawn. conductor cannot put it on
361
+ // the command line of a git call this binary makes itself.
362
+ env: gateChildEnv(process.env),
359
363
  });
360
364
  return {
361
365
  status: child.status,
@@ -124,7 +124,7 @@ import { INTENT_WARNING } from './normalize.js';
124
124
  import { baseMovedSentences, gateOutcomeWords, intentEmptyChangeSet, intentNothingWording, intentCheckedNothing, intentSkipReason, skewFound, skewPlace, } from './output-text.js';
125
125
  import { POLICY_FILE_NAME } from './policy.js';
126
126
  import { policyChangeLine } from './policy-diff.js';
127
- import { guardPreview } from './run.js';
127
+ import { guardPreview, isProposal, ranProposedPolicy } from './run.js';
128
128
  const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
129
129
  export const UMBRELLA_DRIVER_NAME = 'conductor';
130
130
  /**
@@ -302,7 +302,7 @@ function withFallbackLocation(locations, fallbackUri) {
302
302
  }
303
303
  return locations.map((location) => location.physicalLocation === undefined ? { ...location, physicalLocation } : location);
304
304
  }
305
- function toResult(finding, fallbackUri) {
305
+ function toResult(finding, fallbackUri, proposal = false) {
306
306
  // A path that escapes the source root gets no physical location, so the
307
307
  // path itself is carried here instead. Dropping a location is honest;
308
308
  // dropping the information as well would just lose the finding's subject.
@@ -316,6 +316,11 @@ function toResult(finding, fallbackUri) {
316
316
  severity: finding.severity,
317
317
  severityIsDerived: finding.severityIsDerived,
318
318
  fingerprintStability: finding.fingerprint?.stability ?? 'none',
319
+ // On a run of the policy a pull request adds (issue 101): `blocking`
320
+ // above is what the proposed policy WOULD do, and nothing was enforced.
321
+ // On the result itself, so a consumer that reads results and never the
322
+ // run's properties still cannot take it for an enforced verdict.
323
+ ...(proposal ? { proposal: true } : {}),
319
324
  ...(unplaceable.length === 0 ? {} : { unresolvablePaths: unplaceable }),
320
325
  // The details bag verbatim. Not reshaped, not filtered: it is where
321
326
  // each gate puts what it actually established.
@@ -378,7 +383,9 @@ function sarifTrustBase(trustBase) {
378
383
  }
379
384
  function makeRun(name, version, findings,
380
385
  /** The artifact a result with no location of its own is filed against. */
381
- fallbackUri, properties, invocation) {
386
+ fallbackUri, properties, invocation,
387
+ /** Whether this is a run of the policy a pull request adds (issue 101). */
388
+ proposal = false) {
382
389
  const notifications = invocation?.notifications ?? [];
383
390
  return {
384
391
  tool: {
@@ -396,7 +403,7 @@ fallbackUri, properties, invocation) {
396
403
  : { notifications: notificationDeclarations(notifications) }),
397
404
  },
398
405
  },
399
- results: findings.map((finding) => toResult(finding, fallbackUri)),
406
+ results: findings.map((finding) => toResult(finding, fallbackUri, proposal)),
400
407
  ...(invocation === undefined
401
408
  ? {}
402
409
  : {
@@ -715,11 +722,16 @@ function intentWarningNotifications(result) {
715
722
  * gate that raised each line is in the details.
716
723
  */
717
724
  function proposalNotifications(result) {
725
+ // On a run of the policy the pull request adds, no rule came from the ref:
726
+ // it has no policy. What did not take effect is said without that claim.
727
+ const source = ranProposedPolicy(result)
728
+ ? `There is no policy on ${result.trustBase?.ref ?? 'the base ref'}, and this run took only ` +
729
+ 'enabled, stage and enforce from the policy this pull request adds'
730
+ : `The rules came from ${result.trustBase?.ref ?? 'the base ref'}`;
718
731
  return result.proposals.map((proposal) => ({
719
732
  id: 'conductor/control-change-proposed',
720
733
  message: `This pull request proposes a control change that did NOT take effect for this run: ` +
721
- `${proposal.line} (${proposal.product}). The rules came from ` +
722
- `${result.trustBase?.ref ?? 'the base ref'}; the proposed change decides what runs once ` +
734
+ `${proposal.line} (${proposal.product}). ${source}; the proposed change decides what runs once ` +
723
735
  'it is on the base branch.',
724
736
  details: {
725
737
  product: proposal.product,
@@ -769,6 +781,37 @@ function previewNotifications(result) {
769
781
  * inventory named sit beside it in the same run and carry the same sentence,
770
782
  * so a consumer that reads only results still learns that nothing ran.
771
783
  */
784
+ /**
785
+ * A run of the policy a pull request adds to a base that has none (issue
786
+ * 101), said once on the umbrella's run.
787
+ *
788
+ * WARNING level, between the notes and the refusal's error: this is not a
789
+ * coverage statement about one gate, it is that NOTHING in this log was
790
+ * enforced, and a consumer reading only the log has to be able to tell that
791
+ * from an enforced run. Not an error, because nothing failed. It always
792
+ * exists on such a run, so the umbrella's run, and with it
793
+ * `properties.trustBase.proposal`, is always written.
794
+ */
795
+ function proposalRunNotifications(result) {
796
+ if (!ranProposedPolicy(result)) {
797
+ return [];
798
+ }
799
+ const ref = result.trustBase?.ref ?? '';
800
+ return [
801
+ {
802
+ id: 'conductor/proposal-run',
803
+ level: 'warning',
804
+ message: `There is no ${POLICY_FILE_NAME} on "${ref}", so NOTHING IN THIS LOG WAS ENFORCED. This run ` +
805
+ 'took enabled, stage and enforce from the policy this pull request adds and every other ' +
806
+ 'setting from the product defaults. Each result is what would be reported once that policy ' +
807
+ 'is on the base branch' +
808
+ (isProposal(result)
809
+ ? ', and the run exits 0 whatever they say.'
810
+ : '. A gate the proposed policy enforces could not run, so the run is could-not-run.'),
811
+ details: { ref, reason: 'no-policy-on-base', exitCode: result.exitCode },
812
+ },
813
+ ];
814
+ }
772
815
  function trustBaseRefusedNotifications(result) {
773
816
  const refusal = result.trustBase?.refusal;
774
817
  if (refusal === undefined || refusal === null) {
@@ -1070,7 +1113,7 @@ export function renderSarif(result, umbrellaVersion) {
1070
1113
  // only when there is something in it, so a gate that reports none of
1071
1114
  // this keeps the properties shape it had before.
1072
1115
  ...(Object.keys(runDetails(gate)).length === 0 ? {} : { details: runDetails(gate) }),
1073
- }));
1116
+ }, undefined, ranProposedPolicy(result)));
1074
1117
  }
1075
1118
  // Still RESULTS, deliberately, and the asymmetry with the three above is
1076
1119
  // the point. gate-missing and gate-failed are the fail-closed posture made
@@ -1094,6 +1137,7 @@ export function renderSarif(result, umbrellaVersion) {
1094
1137
  ...legacyStateDirNotifications(result),
1095
1138
  ...weakMatchNotifications(result),
1096
1139
  ...trustBaseRefusedNotifications(result),
1140
+ ...proposalRunNotifications(result),
1097
1141
  ...programRefusedNotifications(result),
1098
1142
  ...proposalNotifications(result),
1099
1143
  ...trustBaseWithheldNotifications(result),
@@ -1142,7 +1186,7 @@ export function renderSarif(result, umbrellaVersion) {
1142
1186
  executionSuccessful: (result.trustBase?.refusal ?? null) === null &&
1143
1187
  result.gates.every((gate) => gate.couldNotRun === null),
1144
1188
  notifications,
1145
- }));
1189
+ }, ranProposedPolicy(result)));
1146
1190
  }
1147
1191
  return JSON.stringify({ $schema: SARIF_SCHEMA, version: '2.1.0', runs }, null, 2);
1148
1192
  }
@@ -113,6 +113,123 @@ export declare function previewLogLines(result: RunResult): string[];
113
113
  export declare function gateLogLines(result: RunResult, options?: {
114
114
  terminal?: boolean;
115
115
  }): string[];
116
+ /**
117
+ * ONE LINE FOR ONE GATE, from its outcome alone (issue 105): ran, with the
118
+ * gate version, the exit code and the blocking count, or did not run, with
119
+ * the reason. The line the step summary and the pull request comment lead
120
+ * with, so a gate that did not run can never read as one that passed.
121
+ *
122
+ * A CLOSED SHAPE. Every word is conductor's own (a role, a product, a
123
+ * could-not-run reason) and every other field is a number or a version cut
124
+ * to version characters, so nothing a pull request or a gate printed reaches
125
+ * the line. action.yml and scripts/lib/pr-comment.mjs copy a line only when
126
+ * it matches that shape whole.
127
+ *
128
+ * The blocking count is the findings the report marks blocking, not the
129
+ * token's count: a gate that exited non-zero with none marked says "exit 1,
130
+ * 0 blocking", which is what happened. A gate whose resolved version is not
131
+ * the one the run expected is could-not-run (version-skew) since 0.13.0, so
132
+ * that line is the one that prints both versions.
133
+ *
134
+ * Describes, decides nothing: the exit code was composed before this is read.
135
+ */
136
+ export declare function gateSummaryLine(gate: GateOutcome): string;
137
+ /**
138
+ * The per-gate lines of a run: one per gate that has an outcome, then one per
139
+ * enabled gate that was never spawned (in the job log's own words for why),
140
+ * then one per gate the policy file switches off. The same closed shape.
141
+ */
142
+ export declare function gateSummaryLines(result: RunResult): string[];
143
+ /**
144
+ * The two fixed lines for a run whose trust base gave no rules. They name no
145
+ * ref and carry none of the refusal's own text, which is printed once in the
146
+ * report under them.
147
+ */
148
+ export declare const TRUST_BASE_LINES: readonly ["trust-base: refused, no rules were read and no gate ran", "trust-base: not given on a pull-request job, no rules were read and no gate ran"];
149
+ /**
150
+ * The fixed line of a PROPOSAL (issue 101): a run of the policy a pull
151
+ * request adds to a base that has none, which exits 0 and enforced nothing.
152
+ * One number and no other text that varies: no ref, no branch, no file. The
153
+ * number is the verdict token's, `wouldBlock`.
154
+ */
155
+ export declare function proposalLine(wouldBlockCount: number): string;
156
+ /**
157
+ * The fixed line of a refused pull-request run where neither the base nor
158
+ * the pull request has a policy file, and of a run with no trust base that
159
+ * found no policy file at all (the CLI appends it to the Actions step
160
+ * summary there). The workflow is present and checks nothing: said in so
161
+ * many words, since a red step alone was read as a broken tool.
162
+ */
163
+ export declare const NO_POLICY_LINE: string;
164
+ /**
165
+ * The fixed line of a pull request that deletes the policy file from a base
166
+ * that has one. That run is the ordinary one under the base's rules, so
167
+ * without this line the deletion is one "proposed" line among gate output.
168
+ * What it says about afterwards is what the code does: with no policy on the
169
+ * base every pull-request run is refused, and a pull request that adds one
170
+ * back is refused too (src/adoption-proposal.ts#refuseAdoptionProposal, the
171
+ * first-parent history rule).
172
+ */
173
+ export declare const POLICY_REMOVED_LINE: string;
174
+ /** The heading of the named findings on a proposal, in place of "findings". */
175
+ export declare const PROPOSAL_FINDINGS_HEADING = "would block once the policy is on the base";
176
+ /** The headings `findingSummaryLines` is ever given: a closed set the two readers spell too. */
177
+ export declare const FINDINGS_HEADINGS: readonly ["findings", "would block once the policy is on the base"];
178
+ /**
179
+ * THE RUN-LEVEL SLOT: the fixed lines about the run as a whole, printed
180
+ * directly under the verdict token and above the per-gate lines. Each is a
181
+ * closed shape (a fixed sentence, or one with numbers in it), so the Action
182
+ * and the comment poster can copy them without reading anything a pull
183
+ * request wrote. A later line about the run is added here and to the two
184
+ * closed sets that read it, and nowhere else.
185
+ *
186
+ * The present-on-base line stays first and the intent-spec line second, the
187
+ * two positions an Action older than this slot reads, on every run such an
188
+ * Action can be handed. The proposal line and the no-policy line go above
189
+ * them, because each is the first thing to know about its run: an older
190
+ * Action never passes --adoption-proposal, so it never sees a proposal, and
191
+ * a refused run has neither of the two older lines. The policy-removed line
192
+ * is on an ordinary run, so it goes below them.
193
+ */
194
+ export declare function runLevelLines(result: RunResult): string[];
195
+ /** How many findings the head block and the job log name before "and M more". */
196
+ export declare const FINDINGS_NAMED = 10;
197
+ /** The longest a named-finding line can be: its fixed words plus the four field caps below. */
198
+ export declare const FINDING_LINE_MAX = 520;
199
+ /**
200
+ * THE BLOCKING FINDINGS, NAMED (issue 144): a count line over every finding,
201
+ * then the first `limit` BLOCKING entries as gate, rule, where and the
202
+ * reason, then "and M more blocking". A finding that does not block is
203
+ * counted and not named: it is in the gate's section. When none blocks the
204
+ * count line stands alone, with no colon and no list. "Blocking" is the
205
+ * gate's own mark on the finding, whatever --advisory or enforce: false
206
+ * then does with the exit code. For the head block of the text report, which the Action copies to
207
+ * the step summary and the comment poster lifts above the collapsed report,
208
+ * and for the job log. Empty when no gate that ran reported one.
209
+ *
210
+ * EVERY FIELD IS TEXT A PULL REQUEST CAN CHOOSE (a path, a package name, a
211
+ * rule a user pattern named, a message), so each goes through summaryField
212
+ * (src/escape.ts) and nothing else writes one: a line is one printable ASCII
213
+ * line with no backtick, tag or workflow command, at most FINDING_LINE_MAX
214
+ * long, and always starts with the fixed word "finding: ", so it can never
215
+ * be read as a per-gate line or a verdict.
216
+ *
217
+ * Only gates that RAN are named. A gate that could not run carries the
218
+ * umbrella's own finding about the gate, and its per-gate line already says
219
+ * it did not run. An osv-scanner advisory is one entry however many lockfiles
220
+ * carry it, as in the gate's section. The heading is a parameter because a
221
+ * later run mode lists the same findings under different words.
222
+ */
223
+ export declare function findingSummaryLines(result: RunResult, options?: {
224
+ heading?: string;
225
+ limit?: number;
226
+ }): string[];
227
+ /**
228
+ * The same lines for the job log, so a run whose report went to a file still
229
+ * says what was found where its log is read (issue 144: a blocked run's log
230
+ * said only "findings (36, 36 blocking)").
231
+ */
232
+ export declare function findingLogLines(result: RunResult): string[];
116
233
  type VersionSkew = NonNullable<GateOutcome['versionSkew']>;
117
234
  /** Where a skewed binary came from, in words. Never a machine path. */
118
235
  export declare function skewPlace(skew: VersionSkew): string;
@@ -244,14 +361,6 @@ export interface TextOptions {
244
361
  * that did not block, never about a gate that did not run.
245
362
  */
246
363
  advisory?: boolean;
247
- /**
248
- * The report is going straight to a terminal (cli.ts: stdout is a TTY and
249
- * no --output). Only one thing reads it: a refused trust base prints its
250
- * refusal once at the top and one line per gate, rather than the refusal
251
- * again in every gate's section and again in every gate's finding. A file,
252
- * a pipe and a pull request comment never set it and are unchanged.
253
- */
254
- terminal?: boolean;
255
364
  }
256
365
  /**
257
366
  * The intent-spec header line: a CLOSED SET of four strings, in precedence