@vaultcompass/conductor 0.2.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.
@@ -0,0 +1,564 @@
1
+ // The combined report as SARIF 2.1.0.
2
+ //
3
+ // SARIF is the family's published finding format; the envelope in
4
+ // envelope.ts is internal and never leaves this process. The mapping below
5
+ // is dep-guard's mapping, applied to all three gates from one place, which
6
+ // is the whole point: three hand-written emitters is how a family ends up
7
+ // with one tool emitting absolute paths and another omitting fingerprints
8
+ // entirely, and both of those really happened here.
9
+ //
10
+ // The rules, and why each is the way it is:
11
+ //
12
+ // - ONE RUN PER GATE. SARIF puts the tool name and version on the run, so
13
+ // a single run cannot honestly describe three tools. Each run's driver
14
+ // name and version come from that gate; a gate whose version could not
15
+ // be read gets no version field rather than a placeholder.
16
+ //
17
+ // - A GATE THAT NEVER RAN GETS NO RUN. The tempting alternative is an
18
+ // empty run named for the missing product, which would put that tool's
19
+ // name on something it never did. The umbrella's own findings about it
20
+ // (conductor/gate-missing) go into a final run whose driver IS the
21
+ // umbrella, which is the only honest owner of a statement about a tool
22
+ // that is not installed.
23
+ //
24
+ // - A STATEMENT ABOUT COVERAGE OR CONFIGURATION IS A NOTIFICATION, NOT A
25
+ // FINDING. A gate deferred to a later stage, a gate the policy told not
26
+ // to decide anything, and a branch with no contract to check against are
27
+ // statements about how much of the policy this run represents. They go in
28
+ // `invocations[0].toolExecutionNotifications` on the umbrella's run,
29
+ // keeping their rule ids as descriptor ids. As results they were
30
+ // fingerprint-less note alerts that reappeared on every run, so a
31
+ // repository on the adoption ramp accrued permanent alerts about this
32
+ // tool's own configuration.
33
+ //
34
+ // `conductor/gate-missing` and `conductor/gate-failed` are the deliberate
35
+ // exception and stay RESULTS. A gate that could not run is the
36
+ // fail-closed posture made visible: a class of problem went unlooked-for
37
+ // on this change, and a reviewer scanning a pull request's alerts has to
38
+ // meet that as an alert rather than as tool status.
39
+ //
40
+ // - `properties.blocking` is the gate's decision as reconciled in
41
+ // normalize.ts, never recomputed here from a severity ladder. A second
42
+ // copy of the gate living in the renderer would drift silently, and the
43
+ // report would say "blocking: false" about a finding that had just
44
+ // failed somebody's build.
45
+ //
46
+ // - `partialFingerprints` carries the product's own fingerprint, unhashed,
47
+ // under a key that names the product and a version. Hashing it together
48
+ // with anything would mint a second identity for every finding, one that
49
+ // moves when the first does not, and every alert would resurface on the
50
+ // next scan. The key is versioned so a future change to a product's
51
+ // fingerprint inputs ships as "/v2" and a consumer can tell the two
52
+ // apart instead of silently comparing hashes of different things.
53
+ //
54
+ // - A PATH IS ONLY PUT UNDER `%SRCROOT%` WHEN IT IS ACTUALLY UNDER IT.
55
+ // A uri with `%SRCROOT%` on it is a claim that the file sits inside the
56
+ // scanned source root, and a consumer resolves it that way. Two kinds of
57
+ // path are not:
58
+ //
59
+ // An ABSOLUTE path. One of the gates keeps a path absolute exactly when
60
+ // the file is outside the directory it scanned, so an absolute path is
61
+ // positive evidence the file is NOT under the source root. Stripping
62
+ // the leading slash off it, which is what this file used to do, does
63
+ // not make it relative to anything: it fabricates a source-root-
64
+ // relative path that points at a different file, or at no file, and
65
+ // %SRCROOT% then vouches for it. Those get a `file:` uri and no
66
+ // uriBaseId, which is the spec's own way of saying "elsewhere".
67
+ //
68
+ // A path that still contains a `..` segment after normalizing. It
69
+ // escapes the root and cannot be resolved without knowing where the
70
+ // root is, so the physical location is DROPPED and the raw path is kept
71
+ // in the properties bag instead. No location is honest; a wrong one is
72
+ // not, and is indistinguishable from a right one once uploaded.
73
+ //
74
+ // Everything genuinely inside keeps the relative, forward-slashed,
75
+ // `%SRCROOT%`-based spelling that GitHub code scanning wants.
76
+ //
77
+ // - A REGION ONLY WHEN A REAL POSITION IS KNOWN. One of the three gates
78
+ // reports a line and a column; the other two report no position at all.
79
+ // An invented startLine annotates an unrelated line of somebody's file
80
+ // and is indistinguishable from a true one once uploaded. No endColumn
81
+ // either, for the same reason: the secret scanner's JSON output leaves
82
+ // the match length off the match object, so the end of the match is
83
+ // unknown from the channel the umbrella reads. Not unknown to that
84
+ // product, which puts an end column in its own SARIF; see the note in
85
+ // normalize.ts, which is where the omission would stop mattering if the
86
+ // field were ever carried.
87
+ const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
88
+ export const UMBRELLA_DRIVER_NAME = 'conductor';
89
+ /**
90
+ * Total over Severity, not a lookup with a fallback: a level added to the
91
+ * union without an entry here is a compile error rather than a result that
92
+ * uploads with no level.
93
+ */
94
+ const SARIF_LEVELS = {
95
+ critical: 'error',
96
+ high: 'error',
97
+ medium: 'warning',
98
+ low: 'note',
99
+ info: 'note',
100
+ };
101
+ /** The partialFingerprints key for a product's own fingerprint. */
102
+ export function fingerprintKey(scope) {
103
+ return `${scope}/v1`;
104
+ }
105
+ /** Both spellings of absolute: a leading slash, and a Windows drive prefix. */
106
+ function isAbsolutePath(forwardSlashed) {
107
+ return forwardSlashed.startsWith('/') || /^[A-Za-z]:\//.test(forwardSlashed);
108
+ }
109
+ /**
110
+ * Decides how one path can honestly be named in SARIF.
111
+ *
112
+ * Exported so the rules above can be tested directly rather than only
113
+ * through a whole rendered log.
114
+ */
115
+ export function placeArtifact(rawPath) {
116
+ const forwardSlashed = rawPath.split('\\').join('/');
117
+ if (isAbsolutePath(forwardSlashed)) {
118
+ // Encode each segment, keeping the separators. A path can legitimately
119
+ // contain a space or a hash, and neither is legal raw in a uri.
120
+ const encoded = forwardSlashed
121
+ .split('/')
122
+ .map((segment) => encodeURIComponent(segment))
123
+ .join('/');
124
+ return {
125
+ placement: 'outside-root',
126
+ uri: forwardSlashed.startsWith('/') ? `file://${encoded}` : `file:///${encoded}`,
127
+ };
128
+ }
129
+ let uri = forwardSlashed;
130
+ while (uri.startsWith('./')) {
131
+ uri = uri.slice(2);
132
+ }
133
+ // A ".." segment escapes the root. Not "starts with", because "a/../../b"
134
+ // escapes too and only the second one is visible after normalizing.
135
+ const segments = uri.split('/').filter((segment) => segment !== '.' && segment !== '');
136
+ const resolved = [];
137
+ for (const segment of segments) {
138
+ if (segment !== '..') {
139
+ resolved.push(segment);
140
+ continue;
141
+ }
142
+ if (resolved.length === 0) {
143
+ return { placement: 'unresolvable' };
144
+ }
145
+ resolved.pop();
146
+ }
147
+ if (resolved.length === 0) {
148
+ return { placement: 'unresolvable' };
149
+ }
150
+ return { placement: 'in-root', uri: resolved.join('/') };
151
+ }
152
+ function artifact(rawPath) {
153
+ const placed = placeArtifact(rawPath);
154
+ switch (placed.placement) {
155
+ case 'in-root':
156
+ return { artifactLocation: { uri: placed.uri, uriBaseId: '%SRCROOT%' } };
157
+ case 'outside-root':
158
+ // No uriBaseId. Attaching %SRCROOT% to an absolute uri is a claim the
159
+ // file is inside the scanned root when the gate said the opposite.
160
+ return { artifactLocation: { uri: placed.uri } };
161
+ case 'unresolvable':
162
+ return null;
163
+ }
164
+ }
165
+ /** Paths this finding named that could not be placed honestly. */
166
+ function unplaceablePaths(finding) {
167
+ const subject = finding.subject;
168
+ const paths = subject.kind === 'package'
169
+ ? [subject.manifest]
170
+ : subject.kind === 'location'
171
+ ? [subject.file]
172
+ : subject.kind === 'paths'
173
+ ? subject.paths
174
+ : [];
175
+ return paths.filter((entry) => placeArtifact(entry).placement === 'unresolvable');
176
+ }
177
+ function locationsFor(finding) {
178
+ const subject = finding.subject;
179
+ switch (subject.kind) {
180
+ case 'package': {
181
+ // The manifest is a real file, so it gets a physical location, and
182
+ // the package itself is a logical one. No region: no rule in the
183
+ // dependency gate records a line number today, and guessing one would
184
+ // annotate an unrelated line of the user's manifest.
185
+ const logicalLocations = [{ kind: 'package', fullyQualifiedName: subject.name }];
186
+ const physicalLocation = artifact(subject.manifest);
187
+ // The package is still worth naming even when its manifest cannot be
188
+ // placed, so the logical location survives on its own.
189
+ return [physicalLocation === null ? { logicalLocations } : { physicalLocation, logicalLocations }];
190
+ }
191
+ case 'location': {
192
+ const physicalLocation = artifact(subject.file);
193
+ if (physicalLocation === null) {
194
+ return undefined;
195
+ }
196
+ const region = {
197
+ startLine: subject.line,
198
+ startColumn: subject.column,
199
+ };
200
+ if (subject.endColumn !== undefined) {
201
+ region.endColumn = subject.endColumn;
202
+ }
203
+ return [{ physicalLocation: { ...physicalLocation, region } }];
204
+ }
205
+ case 'paths': {
206
+ const placed = subject.paths
207
+ .map((entry) => artifact(entry))
208
+ .filter((entry) => entry !== null)
209
+ .map((physicalLocation) => ({ physicalLocation }));
210
+ return placed.length === 0 ? undefined : placed;
211
+ }
212
+ case 'contract':
213
+ return [
214
+ {
215
+ logicalLocations: [
216
+ {
217
+ kind: 'contract',
218
+ fullyQualifiedName: subject.category ?? 'intent-contract',
219
+ },
220
+ ],
221
+ },
222
+ ];
223
+ case 'none':
224
+ // No location at all. A missing location is honest; a fabricated one
225
+ // is worse than none and indistinguishable from a true one once the
226
+ // report is uploaded.
227
+ return undefined;
228
+ }
229
+ }
230
+ function toResult(finding) {
231
+ // A path that escapes the source root gets no physical location, so the
232
+ // path itself is carried here instead. Dropping a location is honest;
233
+ // dropping the information as well would just lose the finding's subject.
234
+ const unplaceable = unplaceablePaths(finding);
235
+ const entry = {
236
+ ruleId: finding.ruleId,
237
+ level: SARIF_LEVELS[finding.severity],
238
+ message: { text: finding.message },
239
+ properties: {
240
+ blocking: finding.blocking,
241
+ severity: finding.severity,
242
+ severityIsDerived: finding.severityIsDerived,
243
+ fingerprintStability: finding.fingerprint?.stability ?? 'none',
244
+ ...(unplaceable.length === 0 ? {} : { unresolvablePaths: unplaceable }),
245
+ // The details bag verbatim. Not reshaped, not filtered: it is where
246
+ // each gate puts what it actually established.
247
+ details: finding.details,
248
+ },
249
+ };
250
+ if (finding.fingerprint !== null) {
251
+ entry.partialFingerprints = { [fingerprintKey(finding.fingerprint.scope)]: finding.fingerprint.value };
252
+ }
253
+ const locations = locationsFor(finding);
254
+ if (locations !== undefined) {
255
+ entry.locations = locations;
256
+ }
257
+ return entry;
258
+ }
259
+ function ruleDeclarations(findings) {
260
+ const ids = [...new Set(findings.map((finding) => finding.ruleId))].sort();
261
+ return ids.map((id) => ({
262
+ id,
263
+ // The bare rule name, with the product namespace removed, so a
264
+ // consumer's rule list reads the way the product's own docs do.
265
+ name: id.slice(id.indexOf('/') + 1),
266
+ }));
267
+ }
268
+ function toNotification(notification) {
269
+ return {
270
+ // A reportingDescriptorReference. The id is the one this statement was
271
+ // filed under when it was a result, so a consumer that had rules for
272
+ // these still recognises them.
273
+ descriptor: { id: notification.id },
274
+ // Note, always. A statement about coverage is never an error about the
275
+ // code, and a notification that arrived as a warning would push these
276
+ // straight back into the alert list they were moved out of.
277
+ level: 'note',
278
+ message: { text: notification.message },
279
+ properties: { details: notification.details },
280
+ };
281
+ }
282
+ function notificationDeclarations(notifications) {
283
+ const ids = [...new Set(notifications.map((notification) => notification.id))].sort();
284
+ return ids.map((id) => ({ id, name: id.slice(id.indexOf('/') + 1) }));
285
+ }
286
+ function makeRun(name, version, findings, properties, invocation) {
287
+ const notifications = invocation?.notifications ?? [];
288
+ return {
289
+ tool: {
290
+ driver: {
291
+ name,
292
+ // No placeholder version. SARIF makes version optional, and an
293
+ // invented one would be a claim about which build produced the
294
+ // findings.
295
+ ...(version === null ? {} : { version }),
296
+ rules: ruleDeclarations(findings),
297
+ // Declared beside the rules, so a descriptor reference in the
298
+ // notifications below resolves to something rather than dangling.
299
+ ...(notifications.length === 0
300
+ ? {}
301
+ : { notifications: notificationDeclarations(notifications) }),
302
+ },
303
+ },
304
+ results: findings.map(toResult),
305
+ ...(invocation === undefined
306
+ ? {}
307
+ : {
308
+ invocations: [
309
+ {
310
+ executionSuccessful: invocation.executionSuccessful,
311
+ // The conditional half. An empty notification list is nothing
312
+ // to say, and an empty array says it at length.
313
+ ...(notifications.length === 0
314
+ ? {}
315
+ : { toolExecutionNotifications: notifications.map(toNotification) }),
316
+ },
317
+ ],
318
+ }),
319
+ ...(properties === undefined ? {} : { properties }),
320
+ };
321
+ }
322
+ /**
323
+ * The umbrella's own diagnostics, as SARIF results.
324
+ *
325
+ * These are not findings about the code, so they are note level, do not
326
+ * block, and carry no location. They still belong in the published log: a
327
+ * blocking-count mismatch means the umbrella and the gate disagree about
328
+ * what blocked, which is precisely the thing a consumer reading only the
329
+ * SARIF would otherwise never learn. They are synthesized here rather than
330
+ * added to the envelope's findings list, so they never count toward a
331
+ * summary or an exit code.
332
+ */
333
+ function diagnosticFindings(result) {
334
+ return result.gates.flatMap((gate) => gate.diagnostics.map((diagnostic) => ({
335
+ schemaVersion: 1,
336
+ product: UMBRELLA_DRIVER_NAME,
337
+ productVersion: null,
338
+ // The diagnostic codes are already umbrella-namespaced.
339
+ ruleId: diagnostic.code,
340
+ severity: 'info',
341
+ severityIsDerived: true,
342
+ blocking: false,
343
+ message: diagnostic.message,
344
+ subject: { kind: 'none' },
345
+ fingerprint: null,
346
+ // Which gate it is about. The run it lands in is the umbrella's, so
347
+ // without this a reader cannot tell which gate the disagreement was
348
+ // with.
349
+ details: { role: gate.role, product: gate.product },
350
+ })));
351
+ }
352
+ /**
353
+ * The gates the stage filter held back, as notifications.
354
+ *
355
+ * They follow the same rule as a gate that could not run: no tool output,
356
+ * so no run of their own, and the statement about them belongs to the
357
+ * umbrella. It is not silence either: a consumer reading only the SARIF can
358
+ * otherwise not tell a commit-stage log from a full one.
359
+ *
360
+ * A NOTIFICATION rather than a result, which is the whole of the change. A
361
+ * deferred gate is a statement about what this run covered, not a statement
362
+ * about anybody's code, and as a result it was a fingerprint-less note alert
363
+ * that reappeared on every run of a repository running the commit stage.
364
+ * Permanent alerts about the tool's own configuration are how a code
365
+ * scanning tab becomes something nobody reads.
366
+ */
367
+ function deferredNotifications(result) {
368
+ return result.deferred.map((gate) => ({
369
+ id: 'conductor/gate-deferred',
370
+ message: `The ${gate.role} gate (${gate.product}) did not run at this stage. ` +
371
+ `It runs from stage ${gate.stage} onwards.`,
372
+ details: { role: gate.role, product: gate.product, stage: gate.stage },
373
+ }));
374
+ }
375
+ /**
376
+ * The gates the --gate flag left out, as notifications.
377
+ *
378
+ * The discriminator at skippedNotifications below settles this one without a
379
+ * fresh judgment: how much of the policy a run covered is a statement about
380
+ * the run, so it is a notification. It is not a result, because nothing went
381
+ * wrong; it is not silence, because an uploaded log from a --gate run is
382
+ * otherwise indistinguishable from a full one, and that is the confusion the
383
+ * deferred notification already exists to prevent.
384
+ */
385
+ function excludedNotifications(result) {
386
+ return result.excluded.map((gate) => ({
387
+ id: 'conductor/gate-excluded',
388
+ message: `The ${gate.role} gate (${gate.product}) is enabled in the policy file but did not run: ` +
389
+ 'this run was restricted with --gate and did not name it.',
390
+ details: { role: gate.role, product: gate.product },
391
+ }));
392
+ }
393
+ /**
394
+ * The gates that had nothing to check, as notifications.
395
+ *
396
+ * The descriptor id is the GATE'S namespace rather than the umbrella's,
397
+ * because the statement is about that gate's coverage of this branch and a
398
+ * consumer filtering on `intent-guard/` should see it. The run it lands in is
399
+ * still the umbrella's, by the rule at the top of this file: a gate that
400
+ * produced no tool output gets no run of its own, whatever it says.
401
+ *
402
+ * The comment that used to sit here said this was kept consistent with
403
+ * gate-deferred and gate-not-enforced, and that whether the whole family
404
+ * should be notifications was one decision to take once rather than three.
405
+ * That decision has now been taken, for all three at once, and the rule it
406
+ * was taken on is written out here so the next case decides itself instead
407
+ * of going to somebody's judgment a fourth time:
408
+ *
409
+ * A statement about HOW MUCH OF THE POLICY A RUN COVERED is a
410
+ * NOTIFICATION. It is true of the configuration rather than of this
411
+ * change, so it is identical on every run until somebody edits the policy
412
+ * file, and on the adoption ramp it is deliberately true for weeks. A
413
+ * permanent alert is a dismissed alert, and it teaches the reader to
414
+ * dismiss the next one.
415
+ *
416
+ * A statement that SOMETHING WENT WRONG is a RESULT. It is about this run,
417
+ * it goes away when somebody fixes it, and a reviewer of this change is
418
+ * the person who should see it.
419
+ *
420
+ * That is why conductor/gate-missing and conductor/gate-failed stay results:
421
+ * a gate that could not run means a class of problem went unlooked-for on
422
+ * this change. It is also why the normalization diagnostics stay results:
423
+ * conductor/blocking-count-mismatch and conductor/blocking-threshold-unknown,
424
+ * the two codes reconcileBlocking raises in normalize.ts, are the umbrella
425
+ * saying its own report may disagree with the gate's own verdict, which is a
426
+ * defect in this run and not a property of anybody's configuration. Those two
427
+ * ids are the whole set; a conductor/blocking-mismatch was named here, in the
428
+ * text report and in the README for a while, and nothing ever emitted it. The
429
+ * same rule decides the text
430
+ * report's summary line, in isFullyClean in output-text.ts, and the two must
431
+ * keep answering it the same way.
432
+ */
433
+ function skippedNotifications(result) {
434
+ return result.skipped.map((gate) => ({
435
+ id: `${gate.product}/no-contract`,
436
+ message: `The ${gate.role} gate (${gate.product}) checked nothing on this branch. ${gate.detail}`,
437
+ details: { role: gate.role, product: gate.product, reason: gate.reason },
438
+ }));
439
+ }
440
+ /**
441
+ * The gates the policy file told not to decide anything, as notifications.
442
+ *
443
+ * These are written in TWO places on purpose, and neither one is redundant:
444
+ *
445
+ * - `properties.enforced` on the gate's own run. That is the natural owner
446
+ * of the fact, because enforcement is a property of the gate rather than
447
+ * of any one finding, and it sits where a consumer already looks to find
448
+ * out whose results these are. It is emitted for enforced gates too, so
449
+ * an absent property never has to be read as either answer.
450
+ *
451
+ * - a notification in the umbrella's run, always. The run-level property cannot
452
+ * carry the case that matters most: a gate that COULD NOT RUN produces
453
+ * no run of its own, by the rule at the top of this file, so the only
454
+ * place left to say "and it was not enforced, which is why this log
455
+ * reports exit 0 with a gate that verified nothing" is the umbrella's
456
+ * own run. Emitting the note only in that case would make it look like
457
+ * an error report rather than a statement about coverage, so it is
458
+ * emitted for every unenforced gate.
459
+ *
460
+ * What is deliberately NOT done: touching the results themselves. A
461
+ * critical finding stays critical, and `blocking` stays whatever the gate
462
+ * decided. Enforcement is this repository's policy about the exit code, and
463
+ * writing it into the field a code-scanning UI uses to describe the finding
464
+ * would make the finding lie about what the gate found.
465
+ */
466
+ function unenforcedNotifications(result) {
467
+ return result.gates
468
+ .filter((gate) => !gate.enforce)
469
+ .map((gate) => {
470
+ // The GATE'S own blocking findings, which is why the umbrella's are
471
+ // filtered out rather than counted. A gate that could not run carries
472
+ // the umbrella's own blocking gate-missing finding in this same list,
473
+ // and counting it made this object say the gate blocked one thing and
474
+ // also that it never ran, which are opposite claims. Filtering by
475
+ // product rather than special-casing couldNotRun, because the question
476
+ // this number answers is "what did the gate say", and the umbrella's
477
+ // own findings are never the gate's answer.
478
+ const blocking = gate.findings.filter((finding) => finding.blocking && finding.product !== UMBRELLA_DRIVER_NAME).length;
479
+ const what = gate.couldNotRun !== null
480
+ ? `It could not run (${gate.couldNotRun.reason}), and nothing was checked by it.`
481
+ : `It reported ${blocking} blocking finding(s) and exited ${gate.exitCode ?? -1}.`;
482
+ return {
483
+ id: 'conductor/gate-not-enforced',
484
+ message: `The ${gate.role} gate (${gate.product}) has enforce: false, so its verdict did not ` +
485
+ `reach the exit code. ${what}`,
486
+ details: {
487
+ role: gate.role,
488
+ product: gate.product,
489
+ enforced: false,
490
+ couldNotRun: gate.couldNotRun === null ? null : gate.couldNotRun.reason,
491
+ blockingFindings: blocking,
492
+ },
493
+ };
494
+ });
495
+ }
496
+ /**
497
+ * Renders a whole run as one SARIF log.
498
+ *
499
+ * `umbrellaVersion` names this package's own version, used only for the
500
+ * umbrella's own run. Passed in rather than read from disk so this module
501
+ * stays free of filesystem access.
502
+ */
503
+ export function renderSarif(result, umbrellaVersion) {
504
+ const runs = [];
505
+ for (const gate of result.gates) {
506
+ const own = gate.findings.filter((finding) => finding.product === gate.product);
507
+ // A gate that could not run produced no tool output; the only findings
508
+ // about it belong to the umbrella, and they go in the umbrella's run.
509
+ if (gate.couldNotRun !== null && own.length === 0) {
510
+ continue;
511
+ }
512
+ // The stage sits beside the enforcement flag because the two answer the
513
+ // same question about a published log: how much of the policy this run
514
+ // actually represents. Without it a commit-stage log and a full one are
515
+ // indistinguishable for any gate that appears in both.
516
+ // contractSource and baseRef sit beside the enforcement flag and the
517
+ // stage for the same reason those two do: they say what this run's
518
+ // results are ABOUT. A drift finding measured against an imported spec
519
+ // and one measured against a contract somebody approved by hand are
520
+ // different claims, and so are one over a branch diff and one over an
521
+ // index.
522
+ runs.push(makeRun(gate.product, gate.productVersion, own, {
523
+ enforced: gate.enforce,
524
+ stage: gate.stage,
525
+ ...(gate.intent === undefined
526
+ ? {}
527
+ : { contractSource: gate.intent.contractSource, baseRef: gate.intent.baseRef }),
528
+ }));
529
+ }
530
+ // Still RESULTS, deliberately, and the asymmetry with the three above is
531
+ // the point. gate-missing and gate-failed are the fail-closed posture made
532
+ // visible: a gate that could not run means a class of problem went
533
+ // unlooked-for on this change, and a reviewer scanning a pull request's
534
+ // alerts has to meet that as an alert rather than as tool status. The
535
+ // three below it are statements about how much of the policy this run
536
+ // represents, which is the tool describing itself.
537
+ const umbrellaFindings = [
538
+ ...result.gates
539
+ .flatMap((gate) => gate.findings)
540
+ .filter((finding) => finding.product === UMBRELLA_DRIVER_NAME),
541
+ ...diagnosticFindings(result),
542
+ ];
543
+ const notifications = [
544
+ ...deferredNotifications(result),
545
+ ...excludedNotifications(result),
546
+ ...skippedNotifications(result),
547
+ ...unenforcedNotifications(result),
548
+ ];
549
+ // Notifications earn the run on their own. Before this, the umbrella run
550
+ // existed only when it had findings and a deferred gate was one; without
551
+ // this clause a commit-stage log would say nothing whatever about the gate
552
+ // that did not run there.
553
+ if (umbrellaFindings.length > 0 || notifications.length > 0) {
554
+ runs.push(makeRun(UMBRELLA_DRIVER_NAME, umbrellaVersion, umbrellaFindings, undefined, {
555
+ // A claim about whether the analysis completed, taken from the gates
556
+ // rather than from the exit code: an unenforced gate that could not
557
+ // run leaves the run at exit 0, and nothing was checked by it either
558
+ // way. Written whenever this run is written, in both directions.
559
+ executionSuccessful: result.gates.every((gate) => gate.couldNotRun === null),
560
+ notifications,
561
+ }));
562
+ }
563
+ return JSON.stringify({ $schema: SARIF_SCHEMA, version: '2.1.0', runs }, null, 2);
564
+ }
@@ -0,0 +1,12 @@
1
+ import type { RunResult } from './run.js';
2
+ export interface TextOptions {
3
+ /**
4
+ * Print the full report even when the run is fully clean.
5
+ *
6
+ * A flag on the command line rather than a key in the policy file. The
7
+ * schema describes what a repository gates on, and how loud one developer
8
+ * wants their own terminal to be is not that.
9
+ */
10
+ verbose?: boolean;
11
+ }
12
+ export declare function renderText(result: RunResult, options?: TextOptions): string;