@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,582 @@
1
+ // Turning each gate's own JSON into the internal envelope.
2
+ //
3
+ // Three separate functions rather than one table-driven mapper, because the
4
+ // three shapes disagree in ways a table would have to paper over: one is a
5
+ // flat findings array, one is nested by file, and the third is two
6
+ // different streams (a change-budget evaluation and a scored drift rubric)
7
+ // plus a gate status that can block for neither reason.
8
+ //
9
+ // What every one of them refuses to do, in one place so it is reviewable:
10
+ // invent a line number, invent a fingerprint, re-derive a severity a
11
+ // product already stated, or claim a finding is blocking when the gate's
12
+ // own reported count says otherwise.
13
+ import { createHash } from 'node:crypto';
14
+ import { NormalizeError, atOrAboveThreshold, } from './envelope.js';
15
+ const BLOCKING_MISMATCH = 'conductor/blocking-count-mismatch';
16
+ const THRESHOLD_UNKNOWN = 'conductor/blocking-threshold-unknown';
17
+ function isRecord(value) {
18
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
19
+ }
20
+ // Element-level validation.
21
+ //
22
+ // A top-level shape check is not enough, and that was a real defect rather
23
+ // than a hypothetical: `{"findings": [null]}` passed the old check that
24
+ // findings was an array, and then reading a property off null threw a
25
+ // TypeError, which is not a NormalizeError, so it escaped the gate runner,
26
+ // escaped the run, and reached the user as a stack trace carrying a local
27
+ // path, with exit 1 -- which the hook reports as "a gate blocked" -- and the
28
+ // remaining gates never ran.
29
+ //
30
+ // So every field the mapping actually reads is checked before it is read,
31
+ // and every failure is a NormalizeError naming the product and the path to
32
+ // the offending field. Fields the mapping only passes through are NOT
33
+ // required: rejecting output because a gate stopped emitting a field nobody
34
+ // maps would turn a harmless upstream change into a blocked commit.
35
+ function fail(product, where, wanted) {
36
+ throw new NormalizeError(`${product} output did not have the shape the umbrella knows: ${where} should be ${wanted}.`);
37
+ }
38
+ function needRecord(value, product, where) {
39
+ return isRecord(value) ? value : fail(product, where, 'an object');
40
+ }
41
+ function needArray(value, product, where) {
42
+ return Array.isArray(value) ? value : fail(product, where, 'an array');
43
+ }
44
+ function needString(value, product, where) {
45
+ return typeof value === 'string' ? value : fail(product, where, 'a string');
46
+ }
47
+ function needNumber(value, product, where) {
48
+ return typeof value === 'number' && Number.isFinite(value)
49
+ ? value
50
+ : fail(product, where, 'a number');
51
+ }
52
+ function optionalString(value, product, where) {
53
+ return value === undefined ? undefined : needString(value, product, where);
54
+ }
55
+ function optionalDetails(value, product, where) {
56
+ return value === undefined ? {} : needRecord(value, product, where);
57
+ }
58
+ /** A string array, used for the two products that report matched path lists. */
59
+ function needStringArray(value, product, where) {
60
+ return needArray(value, product, where).map((entry, index) => needString(entry, product, `${where}[${index}]`));
61
+ }
62
+ /**
63
+ * Reconciles per-finding blocking against the count the gate reported.
64
+ *
65
+ * Neither dep-guard nor vault-guard marks a finding as blocking; each
66
+ * reports the threshold it used and how many findings met it. So the
67
+ * per-finding flag is reconstructed from that threshold and then checked
68
+ * against that count. When the two disagree, the gate wins: every flag
69
+ * drops to false and a diagnostic says why, because the alternative is the
70
+ * report telling a user a finding blocked their commit when the tool that
71
+ * blocks commits disagrees.
72
+ */
73
+ function reconcileBlocking(findings, reportedBlocking, threshold, product, diagnostics) {
74
+ if (threshold === null) {
75
+ for (const finding of findings) {
76
+ finding.blocking = false;
77
+ }
78
+ diagnostics.push({
79
+ code: THRESHOLD_UNKNOWN,
80
+ message: `${product} did not report the threshold it gated on, so no finding is marked blocking. ` +
81
+ 'The gate exit code still decides the run.',
82
+ });
83
+ return;
84
+ }
85
+ for (const finding of findings) {
86
+ finding.blocking = atOrAboveThreshold(finding.severity, threshold);
87
+ }
88
+ const derived = findings.filter((finding) => finding.blocking).length;
89
+ if (reportedBlocking !== undefined && derived !== reportedBlocking) {
90
+ for (const finding of findings) {
91
+ finding.blocking = false;
92
+ }
93
+ diagnostics.push({
94
+ code: BLOCKING_MISMATCH,
95
+ message: `${product} reported ${reportedBlocking} blocking finding(s) at threshold "${threshold}" ` +
96
+ `but the umbrella reconstructed ${derived}. No finding is marked blocking; the gate own ` +
97
+ 'exit code still decides the run. This means the gate output shape has moved.',
98
+ });
99
+ }
100
+ }
101
+ // -- dep-guard ------------------------------------------------------------
102
+ /** Diagnostics from a gate, validated element by element like everything else. */
103
+ function readDiagnostics(value, product, where) {
104
+ if (value === undefined) {
105
+ return [];
106
+ }
107
+ return needArray(value, product, where).map((entry, index) => {
108
+ const record = needRecord(entry, product, `${where}[${index}]`);
109
+ return {
110
+ code: needString(record.code, product, `${where}[${index}].code`),
111
+ message: needString(record.message, product, `${where}[${index}].message`),
112
+ };
113
+ });
114
+ }
115
+ export function normalizeDepGuard(raw, version) {
116
+ const product = 'dep-guard';
117
+ const root = needRecord(raw, product, 'the output');
118
+ const run = needRecord(root.run, product, 'run');
119
+ const threshold = optionalString(run.failOn, product, 'run.failOn') ?? null;
120
+ const diagnostics = [];
121
+ const findings = needArray(root.findings, product, 'findings').map((entry, index) => {
122
+ const where = `findings[${index}]`;
123
+ const source = needRecord(entry, product, where);
124
+ return {
125
+ schemaVersion: 1,
126
+ product,
127
+ productVersion: version,
128
+ ruleId: `dep-guard/${needString(source.ruleId, product, `${where}.ruleId`)}`,
129
+ // dep-guard's four levels are the shared ladder exactly, so this is
130
+ // identity and nothing is derived.
131
+ severity: needString(source.severity, product, `${where}.severity`),
132
+ severityIsDerived: false,
133
+ blocking: false,
134
+ message: needString(source.message, product, `${where}.message`),
135
+ subject: {
136
+ kind: 'package',
137
+ name: needString(source.packageName, product, `${where}.packageName`),
138
+ manifest: needString(source.manifestPath, product, `${where}.manifestPath`),
139
+ ...(source.lockfilePath === undefined
140
+ ? {}
141
+ : { lockfile: needString(source.lockfilePath, product, `${where}.lockfilePath`) }),
142
+ },
143
+ fingerprint: {
144
+ value: needString(source.fingerprint, product, `${where}.fingerprint`),
145
+ scope: product,
146
+ // dep-guard hashes the rule id, the package name, the manifest path,
147
+ // and the signal. Position-free, so an unrelated edit above a finding
148
+ // does not mint a new one.
149
+ stability: 'stable',
150
+ },
151
+ details: optionalDetails(source.details, product, `${where}.details`),
152
+ };
153
+ });
154
+ reconcileBlocking(findings, typeof run.blockingMatches === 'number' ? run.blockingMatches : undefined, threshold, product, diagnostics);
155
+ return {
156
+ findings,
157
+ run: {
158
+ failOn: threshold,
159
+ suppressed: typeof root.suppressed === 'number' ? root.suppressed : 0,
160
+ ignored: typeof root.ignored === 'number' ? root.ignored : 0,
161
+ // Diagnostics never move dep-guard's own exit code, so they stay out
162
+ // of findings[] here too rather than becoming pseudo-findings.
163
+ diagnostics: readDiagnostics(run.diagnostics, product, 'run.diagnostics'),
164
+ details: {
165
+ mode: run.mode ?? null,
166
+ corpusBuiltAt: run.corpusBuiltAt ?? null,
167
+ lockfileFormat: run.lockfileFormat ?? null,
168
+ },
169
+ },
170
+ diagnostics,
171
+ };
172
+ }
173
+ // -- vault-guard ----------------------------------------------------------
174
+ export function normalizeVaultGuard(raw, version) {
175
+ const product = 'vault-guard';
176
+ const root = needRecord(raw, product, 'the output');
177
+ const run = root.run === undefined ? {} : needRecord(root.run, product, 'run');
178
+ // run.blocking_matches, never summary.secrets. vault-guard's own type
179
+ // documentation says integrators gating a build must read the former,
180
+ // because the latter ignores the threshold. A sibling tool in this family
181
+ // read summary.secrets and that is the bug not to copy.
182
+ const threshold = optionalString(run.fail_on, product, 'run.fail_on') ?? null;
183
+ const diagnostics = [];
184
+ const findings = [];
185
+ const results = needArray(root.results, product, 'results');
186
+ for (const [fileIndex, rawEntry] of results.entries()) {
187
+ const entryWhere = `results[${fileIndex}]`;
188
+ const entry = needRecord(rawEntry, product, entryWhere);
189
+ const file = needString(entry.file, product, `${entryWhere}.file`);
190
+ const matches = entry.matches === undefined
191
+ ? []
192
+ : needArray(entry.matches, product, `${entryWhere}.matches`);
193
+ for (const [matchIndex, rawMatch] of matches.entries()) {
194
+ const where = `${entryWhere}.matches[${matchIndex}]`;
195
+ const match = needRecord(rawMatch, product, where);
196
+ const type = needString(match.type, product, `${where}.type`);
197
+ const severity = needString(match.severity, product, `${where}.severity`);
198
+ const line = needNumber(match.line, product, `${where}.line`);
199
+ const column = needNumber(match.column, product, `${where}.column`);
200
+ const known = ['critical', 'high', 'medium', 'low'].includes(severity);
201
+ findings.push({
202
+ schemaVersion: 1,
203
+ product,
204
+ productVersion: version,
205
+ // `type` is an open vocabulary: a user's own extra_patterns choose
206
+ // their own ids, which is exactly why the namespace is not optional.
207
+ ruleId: `vault-guard/${type}`,
208
+ // Unknown levels land on info rather than being passed through, so
209
+ // a downstream consumer never sees a level outside the union. An
210
+ // unrecognised level is the umbrella's guess, hence derived.
211
+ severity: known ? severity : 'info',
212
+ severityIsDerived: !known,
213
+ blocking: false,
214
+ // The JSON output carries no message at all. This is vault-guard's
215
+ // own SARIF template, so the wording comes from the product rather
216
+ // than from here.
217
+ message: `Possible secret of type '${type}'`,
218
+ subject: {
219
+ kind: 'location',
220
+ file,
221
+ line,
222
+ // The JSON column is 0-based and the envelope's is 1-based. The
223
+ // product's own SARIF does the same conversion; doing it here too
224
+ // is what makes one shared mapping possible.
225
+ column: column + 1,
226
+ // No endColumn. vault-guard DOES know the match length: it hashes
227
+ // it into the fingerprint and puts an end column in its own SARIF.
228
+ // What it omits is matchLength on the match object in the JSON
229
+ // output, which is the channel the umbrella reads. So the end of
230
+ // the match is unknown from THIS CHANNEL rather than unknown to
231
+ // the product, which makes it a fixable upstream ask (carry
232
+ // matchLength on the match) rather than a permanent limitation.
233
+ // Until it is carried, it is not guessed.
234
+ },
235
+ fingerprint: {
236
+ value: needString(match.fingerprint, product, `${where}.fingerprint`),
237
+ scope: product,
238
+ // Hashed over the relative path, the type, the line, the offset,
239
+ // and the match length. Inserting an unrelated line above a
240
+ // secret changes it, so a baseline entry expires on the next edit.
241
+ stability: 'positional',
242
+ },
243
+ // The passthrough half. These are not required: they are carried,
244
+ // not mapped, so a gate that stops emitting one should not turn
245
+ // into a blocked commit.
246
+ details: {
247
+ type,
248
+ severity,
249
+ line,
250
+ // Spelled with its base in the key. This bag is carried, not
251
+ // mapped, so the number stays the gate's own 0-based one; calling
252
+ // it "column" put it next to a 1-based SARIF startColumn in the
253
+ // same result, where it read as an off-by-one in this tool rather
254
+ // than as two different conventions side by side. Renaming the key
255
+ // says which is which without rewriting a gate's own output into
256
+ // units that gate never used.
257
+ columnZeroBased: column,
258
+ offset: match.offset ?? null,
259
+ // Already redacted at the source, so it is safe to carry.
260
+ value: match.value ?? null,
261
+ },
262
+ });
263
+ }
264
+ }
265
+ reconcileBlocking(findings, typeof run.blocking_matches === 'number' ? run.blocking_matches : undefined, threshold, product, diagnostics);
266
+ return {
267
+ findings,
268
+ run: {
269
+ failOn: threshold,
270
+ suppressed: typeof run.baseline_suppressed === 'number' ? run.baseline_suppressed : 0,
271
+ // vault-guard does not report an ignore count separately; ignored
272
+ // files never reach the output at all. Reporting 0 here would claim a
273
+ // fact the gate did not state, so the report says "not reported"
274
+ // instead, driven by this null.
275
+ ignored: 0,
276
+ // vault-guard's diagnostics carry a context object rather than a
277
+ // message, so the context is rendered as one. Validated the same way
278
+ // as everything else, since a malformed entry here would otherwise
279
+ // reach String() and produce "[object Object]" in a report.
280
+ diagnostics: root.diagnostics === undefined
281
+ ? []
282
+ : needArray(root.diagnostics, product, 'diagnostics').map((entry, index) => {
283
+ const where = `diagnostics[${index}]`;
284
+ const record = needRecord(entry, product, where);
285
+ return {
286
+ code: needString(record.code, product, `${where}.code`),
287
+ message: JSON.stringify(record.ctx ?? {}),
288
+ };
289
+ }),
290
+ details: {
291
+ filesScanned: run.files_scanned ?? null,
292
+ patternsActive: run.patterns_active ?? null,
293
+ ignoredReported: false,
294
+ },
295
+ },
296
+ diagnostics,
297
+ };
298
+ }
299
+ // -- intent-guard ---------------------------------------------------------
300
+ /**
301
+ * intent-guard has no per-finding severity, so every level below is the
302
+ * umbrella's invention and every finding it produces carries
303
+ * severityIsDerived: true. The product's own action string is kept in
304
+ * `details` so a consumer can ignore this mapping entirely.
305
+ */
306
+ const BUDGET_SEVERITY = {
307
+ hard_block: 'critical',
308
+ soft_block: 'high',
309
+ };
310
+ const DRIFT_SEVERITY = {
311
+ hard_block: 'critical',
312
+ soft_block: 'high',
313
+ warn: 'medium',
314
+ info: 'low',
315
+ proceed: 'info',
316
+ };
317
+ /**
318
+ * The three ways the intent gate can block on the STATE of the contract
319
+ * rather than on anything in the diff.
320
+ *
321
+ * These matter because the gate pushes them into the same `reasons` array as
322
+ * its budget and drift reasons, and exposes no structured field saying which
323
+ * is which. So a run with an unfrozen contract AND a budget violation used
324
+ * to report only the budget violation: the reason the commit could not be
325
+ * fixed by editing the diff was in neither report.
326
+ *
327
+ * The prefixes are copied from intent-guard's own gate.ts. They are matched
328
+ * as prefixes rather than whole strings because one of the three
329
+ * interpolates an error message, and they are enumerated in a test against
330
+ * the real strings, so an upstream rewording turns that test red instead of
331
+ * silently dropping a reason out of every report.
332
+ */
333
+ export const GATE_STATE_REASON_KINDS = [
334
+ 'contract-invalid',
335
+ 'contract-missing',
336
+ 'contract-unfrozen',
337
+ ];
338
+ const GATE_STATE_REASON_PREFIXES = [
339
+ ['Intent contract is invalid:', 'contract-invalid'],
340
+ ['No .conductor/intent-contract.yaml found', 'contract-missing'],
341
+ ['Intent contract exists but is not frozen', 'contract-unfrozen'],
342
+ ];
343
+ /** Which gate-state reason this is, or null when it is a budget or drift reason. */
344
+ export function classifyGateStateReason(reason) {
345
+ for (const [prefix, kind] of GATE_STATE_REASON_PREFIXES) {
346
+ if (reason.startsWith(prefix)) {
347
+ return kind;
348
+ }
349
+ }
350
+ return null;
351
+ }
352
+ export function normalizeIntentGuard(raw, version) {
353
+ const product = 'intent-guard';
354
+ const root = needRecord(raw, product, 'the output');
355
+ if (root.status !== 'blocked' && root.status !== 'ok') {
356
+ fail(product, 'status', 'either "ok" or "blocked"');
357
+ }
358
+ const findings = [];
359
+ const budget = root.budget === undefined ? undefined : needRecord(root.budget, product, 'budget');
360
+ const drift = root.drift === undefined ? undefined : needRecord(root.drift, product, 'drift');
361
+ // Budget violations. The gate raises one reason per violation and blocks
362
+ // when it has any reason at all, so every violation is blocking. That is
363
+ // read off the gate's own composition rule, not off a severity ladder.
364
+ const violations = budget?.violations === undefined
365
+ ? []
366
+ : needArray(budget.violations, product, 'budget.violations');
367
+ for (const [index, rawViolation] of violations.entries()) {
368
+ const where = `budget.violations[${index}]`;
369
+ const violation = needRecord(rawViolation, product, where);
370
+ const rule = needString(violation.rule, product, `${where}.rule`);
371
+ const severity = needString(violation.severity, product, `${where}.severity`);
372
+ const matched = violation.matched === undefined
373
+ ? []
374
+ : needStringArray(violation.matched, product, `${where}.matched`);
375
+ findings.push({
376
+ schemaVersion: 1,
377
+ product,
378
+ productVersion: version,
379
+ ruleId: `intent-guard/budget.${rule}`,
380
+ severity: BUDGET_SEVERITY[severity] ?? 'info',
381
+ severityIsDerived: true,
382
+ blocking: true,
383
+ message: needString(violation.message, product, `${where}.message`),
384
+ subject: { kind: 'paths', paths: matched },
385
+ fingerprint: {
386
+ value: needString(violation.fingerprint, product, `${where}.fingerprint`),
387
+ scope: product,
388
+ // Hashed over the contract id, the rule, and the sorted normalized
389
+ // matched paths. Order-independent and position-free.
390
+ stability: 'stable',
391
+ },
392
+ details: { rule, severity, matched },
393
+ });
394
+ }
395
+ // Drift findings. 1.2.0 gave these stable fingerprints and a bounded
396
+ // rule_id, which is what makes one finding per entry honest; before that
397
+ // they were bare prose strings and the only truthful rendering was a
398
+ // single synthetic finding for the whole run.
399
+ //
400
+ // The blocking decision is the SCORE's, not the finding's: the gate
401
+ // raises one drift reason for the overall action and none per finding, so
402
+ // a finding is blocking exactly when the overall action blocks.
403
+ const driftAction = optionalString(drift?.action, product, 'drift.action') ?? 'proceed';
404
+ const driftBlocks = driftAction === 'soft_block' || driftAction === 'hard_block';
405
+ const driftDetails = drift?.finding_details === undefined
406
+ ? []
407
+ : needArray(drift.finding_details, product, 'drift.finding_details');
408
+ for (const [index, rawDetail] of driftDetails.entries()) {
409
+ const where = `drift.finding_details[${index}]`;
410
+ const detail = needRecord(rawDetail, product, where);
411
+ const category = needString(detail.category, product, `${where}.category`);
412
+ findings.push({
413
+ schemaVersion: 1,
414
+ product,
415
+ productVersion: version,
416
+ // The category, not rule_id: rule_id can carry contract prose, and a
417
+ // rule id that contains a user's sentence is not a rule id. The full
418
+ // value goes in details.
419
+ ruleId: `intent-guard/drift.${category}`,
420
+ severity: DRIFT_SEVERITY[driftAction] ?? 'info',
421
+ severityIsDerived: true,
422
+ blocking: driftBlocks,
423
+ message: needString(detail.message, product, `${where}.message`),
424
+ // No paths subject: `matched` here is "tokens or paths", so treating
425
+ // it as a path list would sometimes point at a file that does not
426
+ // exist. It stays in details, where it is not claiming to be a location.
427
+ subject: { kind: 'contract', category },
428
+ fingerprint: {
429
+ value: needString(detail.fingerprint, product, `${where}.fingerprint`),
430
+ scope: product,
431
+ stability: 'stable',
432
+ },
433
+ details: {
434
+ ruleId: detail.rule_id ?? null,
435
+ category,
436
+ matched: detail.matched ?? [],
437
+ },
438
+ });
439
+ }
440
+ // The gate can block for a reason that is neither a budget violation nor
441
+ // drift: no contract, an unfrozen contract, an unreadable one. Those
442
+ // arrive only as prose in `reasons`, mixed in with the budget and drift
443
+ // reasons and with no structured field separating them.
444
+ //
445
+ // One finding PER gate-state reason, and always, not only when nothing
446
+ // else blocked. The old rule ("only when nothing else is blocking") meant
447
+ // a run with both an unfrozen contract and a budget violation reported
448
+ // only the budget violation, hiding the one problem the user could not fix
449
+ // by editing the diff.
450
+ const reasons = root.reasons === undefined ? [] : needStringArray(root.reasons, product, 'reasons');
451
+ function gateBlocked(message, kind) {
452
+ return {
453
+ schemaVersion: 1,
454
+ product,
455
+ productVersion: version,
456
+ ruleId: 'intent-guard/gate-blocked',
457
+ severity: 'critical',
458
+ severityIsDerived: true,
459
+ blocking: true,
460
+ message,
461
+ subject: { kind: 'none' },
462
+ // No fingerprint: the product mints none for a gate-state block, and
463
+ // inventing one would produce an id no baseline anywhere contains.
464
+ fingerprint: null,
465
+ details: {
466
+ kind,
467
+ reasons,
468
+ contractFound: root.contractFound ?? null,
469
+ contractFrozen: root.contractFrozen ?? null,
470
+ },
471
+ };
472
+ }
473
+ if (root.status === 'blocked') {
474
+ const gateStateReasons = reasons
475
+ .map((reason) => ({ reason, kind: classifyGateStateReason(reason) }))
476
+ .filter((entry) => entry.kind !== null);
477
+ for (const entry of gateStateReasons) {
478
+ findings.push(gateBlocked(entry.reason, entry.kind));
479
+ }
480
+ // The backstop, unchanged in spirit: a blocked gate with nothing blocking
481
+ // in the report reads as a bug in the umbrella and hides the one thing
482
+ // the user needs to see. It fires only when no gate-state reason was
483
+ // recognised AND nothing else blocked, so it never doubles up with the
484
+ // findings above, and it never invents a contract complaint the gate did
485
+ // not make (a contract left unfrozen under --no-require-frozen is not a
486
+ // reason, and must not become one here).
487
+ if (gateStateReasons.length === 0 && !findings.some((finding) => finding.blocking)) {
488
+ findings.push(gateBlocked(reasons.length > 0
489
+ ? reasons.join(' ')
490
+ : 'The intent gate blocked without stating a reason.', 'unattributed'));
491
+ }
492
+ }
493
+ return {
494
+ findings,
495
+ run: {
496
+ // intent-guard has no threshold flag and no reported threshold: its
497
+ // drift thresholds live in its own config file and its budget rules
498
+ // have no threshold at all.
499
+ failOn: null,
500
+ suppressed: 0,
501
+ ignored: 0,
502
+ diagnostics: [],
503
+ details: {
504
+ contractFound: root.contractFound ?? null,
505
+ contractFrozen: root.contractFrozen ?? null,
506
+ driftOverall: typeof drift?.overall === 'number' ? drift.overall : null,
507
+ driftAction,
508
+ driftCategories: drift?.categories ?? null,
509
+ budgetAction: budget?.action ?? null,
510
+ reasons,
511
+ },
512
+ },
513
+ diagnostics: [],
514
+ };
515
+ }
516
+ function gateProblem(ruleId, role, product, message, details) {
517
+ return {
518
+ schemaVersion: 1,
519
+ product: 'conductor',
520
+ productVersion: null,
521
+ ruleId,
522
+ severity: 'critical',
523
+ severityIsDerived: true,
524
+ blocking: true,
525
+ message,
526
+ // No location: none of these is somewhere in the tree.
527
+ subject: { kind: 'none' },
528
+ fingerprint: {
529
+ // Deterministic over the rule, the role, and the product, and NOT over
530
+ // the message: a repeat run is the same alert rather than a new one
531
+ // every commit, and a reworded detail is not a new problem.
532
+ value: createHash('sha256').update(`${ruleId}|${role}|${product}`).digest('hex'),
533
+ scope: 'conductor',
534
+ stability: 'stable',
535
+ },
536
+ details: { role, product, ...details },
537
+ };
538
+ }
539
+ /**
540
+ * The finding raised when an ENABLED gate's binary cannot be found.
541
+ *
542
+ * A gate that is switched on and silently does not run is the failure this
543
+ * whole family exists to prevent: the report reads clean because nothing
544
+ * looked. So it is a finding, it blocks, and it says which names were
545
+ * tried, so the fix is in the message rather than in a support thread.
546
+ */
547
+ export function normalizeMissingGate(role, product, candidates) {
548
+ return gateProblem('conductor/gate-missing', role, product, `The "${role}" gate is enabled but no ${product} binary was found. ` +
549
+ `Looked for: ${candidates.join(', ')}. Install it, point the gate at a build with an ` +
550
+ `absolute "command:", or set enabled: false to switch the gate off on purpose.`, { candidates });
551
+ }
552
+ /**
553
+ * The finding raised when a gate's `command:` names a file that is not
554
+ * there.
555
+ *
556
+ * It names ONLY that path. The candidate list belongs to resolution, and
557
+ * resolution never happened here: the user pointed at one specific file, so
558
+ * listing the names the umbrella would otherwise have searched for suggests
559
+ * it looked for them and implies the fix is to install one of them, when
560
+ * the fix is in their policy file.
561
+ */
562
+ export function normalizeMisconfiguredGate(role, product, command, detail) {
563
+ return gateProblem('conductor/gate-missing', role, product, `The "${role}" gate points at "${command}", which the umbrella could not run: ${detail}`, { command });
564
+ }
565
+ /**
566
+ * The finding raised when a gate answered but the umbrella could not read
567
+ * the answer: invalid JSON, a shape the normalizer does not know, or any
568
+ * unexpected error thrown while normalizing.
569
+ *
570
+ * `detail` is an error MESSAGE, never a stack. A stack would put a local
571
+ * filesystem path into a report that gets uploaded, and it would tell the
572
+ * user nothing they can act on.
573
+ */
574
+ export function normalizeUnparseableGate(role, product, detail) {
575
+ return gateProblem('conductor/gate-output-unparseable', role, product, `The "${role}" gate ran but the umbrella could not read its output: ${detail} ` +
576
+ 'This is the umbrella being out of date with that gate, not a problem in your code. ' +
577
+ 'Nothing was verified by this gate.', { detail });
578
+ }
579
+ /** The finding raised when a gate could not be run or did not complete. */
580
+ export function normalizeFailedGate(role, product, detail) {
581
+ return gateProblem('conductor/gate-failed', role, product, `The "${role}" gate did not complete: ${detail} Nothing was verified by this gate.`, { detail });
582
+ }
@@ -0,0 +1,34 @@
1
+ import type { RunResult } from './run.js';
2
+ export declare const UMBRELLA_DRIVER_NAME = "conductor";
3
+ /** The partialFingerprints key for a product's own fingerprint. */
4
+ export declare function fingerprintKey(scope: string): string;
5
+ export type ArtifactPlacement =
6
+ /** Inside the source root: relative uri under %SRCROOT%. */
7
+ {
8
+ placement: 'in-root';
9
+ uri: string;
10
+ }
11
+ /** Known to be elsewhere: an absolute file uri with no uriBaseId. */
12
+ | {
13
+ placement: 'outside-root';
14
+ uri: string;
15
+ }
16
+ /** Unresolvable from here: no physical location at all. */
17
+ | {
18
+ placement: 'unresolvable';
19
+ };
20
+ /**
21
+ * Decides how one path can honestly be named in SARIF.
22
+ *
23
+ * Exported so the rules above can be tested directly rather than only
24
+ * through a whole rendered log.
25
+ */
26
+ export declare function placeArtifact(rawPath: string): ArtifactPlacement;
27
+ /**
28
+ * Renders a whole run as one SARIF log.
29
+ *
30
+ * `umbrellaVersion` names this package's own version, used only for the
31
+ * umbrella's own run. Passed in rather than read from disk so this module
32
+ * stays free of filesystem access.
33
+ */
34
+ export declare function renderSarif(result: RunResult, umbrellaVersion: string): string;