@vaultcompass/conductor 0.10.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +131 -21
- package/dist/cli.js +27 -2
- package/dist/envelope.d.ts +7 -1
- package/dist/gate-runner.d.ts +36 -10
- package/dist/gate-runner.js +202 -19
- package/dist/intent-prepare.d.ts +33 -1
- package/dist/intent-prepare.js +137 -33
- package/dist/intent-spec.d.ts +108 -22
- package/dist/intent-spec.js +226 -55
- package/dist/normalize.js +28 -3
- package/dist/osv-baseline.d.ts +65 -0
- package/dist/osv-baseline.js +105 -1
- package/dist/osv-coverage.d.ts +18 -2
- package/dist/osv-coverage.js +47 -10
- package/dist/output-sarif.js +90 -1
- package/dist/output-text.d.ts +39 -7
- package/dist/output-text.js +205 -19
- package/dist/run.d.ts +9 -1
- package/dist/run.js +1 -0
- package/dist/unread-manifests.js +4 -0
- package/package.json +1 -1
package/dist/output-text.js
CHANGED
|
@@ -24,7 +24,8 @@
|
|
|
24
24
|
import { compareFindings } from './envelope.js';
|
|
25
25
|
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, gateExitBlocks } from './exit-codes.js';
|
|
26
26
|
import { CONDUCTOR_OWN_REASONS, cleanOutputLine, conductorStatedReason, } from './gate-runner.js';
|
|
27
|
-
import { isLegacyContractPath } from './intent-prepare.js';
|
|
27
|
+
import { isLegacyContractPath, legacyChangedSentence } from './intent-prepare.js';
|
|
28
|
+
import { SPEC_DIR } from './intent-spec.js';
|
|
28
29
|
function subjectLabel(finding) {
|
|
29
30
|
const subject = finding.subject;
|
|
30
31
|
switch (subject.kind) {
|
|
@@ -254,6 +255,52 @@ function contractLine(gate) {
|
|
|
254
255
|
const base = gate.intent.baseRef === null ? 'base: none, the git index' : `base: ${gate.intent.baseRef}`;
|
|
255
256
|
return ` contract: ${where} ${base}`;
|
|
256
257
|
}
|
|
258
|
+
/** The convention match behind a gate's contract, when the branch name chose it. */
|
|
259
|
+
export function conventionMatch(gate) {
|
|
260
|
+
const source = gate.intent?.contractSource;
|
|
261
|
+
return source?.kind === 'imported' && source.match !== undefined ? source.match : null;
|
|
262
|
+
}
|
|
263
|
+
/**
|
|
264
|
+
* The weak-match line, printed under the contract line in every report.
|
|
265
|
+
*
|
|
266
|
+
* The shared words are charset-restricted tokens (isSignificant in
|
|
267
|
+
* intent-spec.ts), so nothing the branch was called beyond them reaches this
|
|
268
|
+
* line, and the runner-up is a filename the specs directory listed.
|
|
269
|
+
*/
|
|
270
|
+
function weakMatchLine(match) {
|
|
271
|
+
const words = (list) => list.map((word) => `"${word}"`).join(', ');
|
|
272
|
+
const why = match.weakBecause.includes('length-tiebreak') && match.runnerUp !== null
|
|
273
|
+
? `the branch name shares ${words(match.shared)} with this spec and ` +
|
|
274
|
+
`${words(match.runnerUpShared)} with ${SPEC_DIR}/${match.runnerUp}; the longer word decided it.`
|
|
275
|
+
: `the branch name shares only ${words(match.shared)} with this spec's name.`;
|
|
276
|
+
const remedy = match.remedy === 'pr-body'
|
|
277
|
+
? 'To be sure this is the right contract, add a "Spec: <path>" line to the pull request body ' +
|
|
278
|
+
"or rename the branch to the spec's name."
|
|
279
|
+
: "To be sure this is the right contract, pass --spec <path> or rename the branch to the spec's name.";
|
|
280
|
+
return ` match: weak, ${why} ${remedy}`;
|
|
281
|
+
}
|
|
282
|
+
/**
|
|
283
|
+
* The lines a convention match adds to the gate block: the weak line and the
|
|
284
|
+
* changed-winner note, printed in every report, and the chosen-by line,
|
|
285
|
+
* printed for every strength under --verbose so a strong or exact choice is
|
|
286
|
+
* visible too.
|
|
287
|
+
*/
|
|
288
|
+
function conventionLines(gate) {
|
|
289
|
+
const match = conventionMatch(gate);
|
|
290
|
+
if (match === null) {
|
|
291
|
+
return { under: [], chosenBy: null };
|
|
292
|
+
}
|
|
293
|
+
const under = [];
|
|
294
|
+
if (match.strength === 'weak') {
|
|
295
|
+
under.push(weakMatchLine(match));
|
|
296
|
+
}
|
|
297
|
+
if (match.legacy !== null) {
|
|
298
|
+
under.push(` note: ${legacyChangedSentence(match.legacy)}`);
|
|
299
|
+
}
|
|
300
|
+
const chosenBy = ` chosen by: branch name, ${match.strength}, shared: ${match.shared.join(' ')}` +
|
|
301
|
+
(match.runnerUp === null ? '' : `, runner-up ${SPEC_DIR}/${match.runnerUp}`);
|
|
302
|
+
return { under, chosenBy };
|
|
303
|
+
}
|
|
257
304
|
function gateSection(gate, verbose, refusedOnTerminal = false) {
|
|
258
305
|
// A gate the refused trust base stopped, on a terminal: the refusal is at
|
|
259
306
|
// the top of the report once, so the section is one line and no more.
|
|
@@ -269,12 +316,25 @@ function gateSection(gate, verbose, refusedOnTerminal = false) {
|
|
|
269
316
|
if (gate.gateOwnOption !== undefined) {
|
|
270
317
|
lines.push(` note conductor/option-is-gate-own: ${gate.gateOwnOption}`);
|
|
271
318
|
}
|
|
319
|
+
// Under the header too: the header names the version and the location,
|
|
320
|
+
// and this says that version is not the one the run was pinned to.
|
|
321
|
+
const skew = versionSkewLine(gate);
|
|
322
|
+
if (skew !== null) {
|
|
323
|
+
lines.push(skew);
|
|
324
|
+
}
|
|
272
325
|
const contract = contractLine(gate);
|
|
273
326
|
if (contract !== null) {
|
|
274
327
|
lines.push(contract);
|
|
328
|
+
// The weak line and the changed-winner note sit directly under the
|
|
329
|
+
// contract line; the chosen-by line, --verbose only, after any other note.
|
|
330
|
+
const convention = conventionLines(gate);
|
|
331
|
+
lines.push(...convention.under);
|
|
275
332
|
if (gate.intent?.note !== undefined) {
|
|
276
333
|
lines.push(` note: ${gate.intent.note}`);
|
|
277
334
|
}
|
|
335
|
+
if (verbose && convention.chosenBy !== null) {
|
|
336
|
+
lines.push(convention.chosenBy);
|
|
337
|
+
}
|
|
278
338
|
}
|
|
279
339
|
if (gate.couldNotRun !== null) {
|
|
280
340
|
lines.push(` ${gate.couldNotRun.detail}`);
|
|
@@ -375,17 +435,27 @@ function skippedLines(result) {
|
|
|
375
435
|
return result.skipped.map((gate) => ` skipped ${gate.role} ${gate.product} ${skipWording(gate.reason).line}: ${gate.detail}`);
|
|
376
436
|
}
|
|
377
437
|
function skipWording(reason) {
|
|
378
|
-
|
|
379
|
-
|
|
438
|
+
if (reason === 'contract-waived') {
|
|
439
|
+
return {
|
|
380
440
|
line: 'spec waived',
|
|
381
441
|
verdict: 'had its spec waived by the pull request body',
|
|
382
442
|
summary: 'Spec waived by the pull request body',
|
|
383
|
-
}
|
|
384
|
-
: {
|
|
385
|
-
line: 'no contract',
|
|
386
|
-
verdict: 'had no contract to check against',
|
|
387
|
-
summary: 'Nothing to check against',
|
|
388
443
|
};
|
|
444
|
+
}
|
|
445
|
+
if (reason === 'spec-ambiguous') {
|
|
446
|
+
// A spec exists; two or more matched equally. Never "nothing to check
|
|
447
|
+
// against", which tells a reader to go and write one.
|
|
448
|
+
return {
|
|
449
|
+
line: 'spec ambiguous',
|
|
450
|
+
verdict: 'matched two or more specs equally, so none was chosen',
|
|
451
|
+
summary: 'No spec chosen, two or more matched the branch equally',
|
|
452
|
+
};
|
|
453
|
+
}
|
|
454
|
+
return {
|
|
455
|
+
line: 'no contract',
|
|
456
|
+
verdict: 'had no contract to check against',
|
|
457
|
+
summary: 'Nothing to check against',
|
|
458
|
+
};
|
|
389
459
|
}
|
|
390
460
|
/**
|
|
391
461
|
* One line per gate the --gate flag left out.
|
|
@@ -676,26 +746,96 @@ export function gateLogLines(result, options = {}) {
|
|
|
676
746
|
}
|
|
677
747
|
return lines;
|
|
678
748
|
}
|
|
749
|
+
/** Where a skewed binary came from, in words. Never a machine path. */
|
|
750
|
+
export function skewPlace(skew) {
|
|
751
|
+
return skew.source === 'node_modules'
|
|
752
|
+
? 'node_modules/.bin'
|
|
753
|
+
: skew.source === 'path'
|
|
754
|
+
? 'PATH'
|
|
755
|
+
: 'the policy command';
|
|
756
|
+
}
|
|
757
|
+
/**
|
|
758
|
+
* The reported version as it may be printed. The probe for the family gates
|
|
759
|
+
* accepts anything after x.y.z on the first line, and this text reaches a
|
|
760
|
+
* workflow command and the step summary, so only version characters are
|
|
761
|
+
* kept.
|
|
762
|
+
*/
|
|
763
|
+
export function skewFound(skew) {
|
|
764
|
+
return skew.found.replace(/[^0-9A-Za-z.+-]/g, '').slice(0, 64);
|
|
765
|
+
}
|
|
766
|
+
/** The remedy, which depends on where the binary came from. */
|
|
767
|
+
function skewFix(product, skew) {
|
|
768
|
+
if (skew.source === 'node_modules') {
|
|
769
|
+
return (`Fix: bump or remove the repository's own ${product} devDependency. node_modules/.bin outranks ` +
|
|
770
|
+
"PATH outside a pull request, so on a push run it shadows the action's install.");
|
|
771
|
+
}
|
|
772
|
+
if (skew.source === 'path') {
|
|
773
|
+
return `Fix: remove the other ${product} from PATH, or install ${skew.expected}.`;
|
|
774
|
+
}
|
|
775
|
+
return `Fix: point the policy command at ${product} ${skew.expected}, or remove the command override.`;
|
|
776
|
+
}
|
|
679
777
|
/**
|
|
680
|
-
* One warning per gate
|
|
681
|
-
* this run expected (the Action's pin)
|
|
778
|
+
* One warning per gate whose resolved binary reported a version other than
|
|
779
|
+
* the one this run expected (the Action's pin), wherever it was found:
|
|
780
|
+
* node_modules/.bin, PATH or a policy command.
|
|
682
781
|
*
|
|
683
|
-
* For the job log
|
|
684
|
-
*
|
|
685
|
-
*
|
|
686
|
-
*
|
|
687
|
-
*
|
|
782
|
+
* For the job log: it names the file the binary was found at, which for PATH
|
|
783
|
+
* is an absolute machine path, so this exact line is never part of a report.
|
|
784
|
+
* The reports carry the same fact without that path (gateSection here, the
|
|
785
|
+
* conductor/version-skew notification in SARIF). A warning and nothing more.
|
|
786
|
+
* Resolution is unchanged and the gate ran (or was refused) exactly as it
|
|
787
|
+
* would have without it.
|
|
688
788
|
*/
|
|
689
789
|
export function versionSkewWarnings(result) {
|
|
690
790
|
return result.gates.flatMap((gate) => gate.versionSkew === undefined
|
|
691
791
|
? []
|
|
692
792
|
: [
|
|
693
|
-
`conductor: warning: ${gate.product} resolved from
|
|
694
|
-
|
|
695
|
-
`It was found at ${gate.versionSkew.path}. Resolution is unchanged and that binary
|
|
696
|
-
`
|
|
793
|
+
`conductor: warning: ${gate.product} resolved from ${skewPlace(gate.versionSkew)} reports version ` +
|
|
794
|
+
`${skewFound(gate.versionSkew)}, but this run expects ${gate.versionSkew.expected} (the version the ` +
|
|
795
|
+
`action pinned). It was found at ${gate.versionSkew.path}. Resolution is unchanged and that binary ` +
|
|
796
|
+
`was used. ${skewFix(gate.product, gate.versionSkew)}`,
|
|
797
|
+
]);
|
|
798
|
+
}
|
|
799
|
+
/** A workflow-command message: `%`, CR and LF escaped, as the runner requires. */
|
|
800
|
+
function workflowCommandData(text) {
|
|
801
|
+
return text.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
|
|
802
|
+
}
|
|
803
|
+
/**
|
|
804
|
+
* The same warnings as GitHub Actions `::warning::` annotations, so a skew
|
|
805
|
+
* shows on the run's summary page without anybody opening the log. No
|
|
806
|
+
* machine path: the location is named in words.
|
|
807
|
+
*/
|
|
808
|
+
export function versionSkewAnnotations(result) {
|
|
809
|
+
return result.gates.flatMap((gate) => gate.versionSkew === undefined
|
|
810
|
+
? []
|
|
811
|
+
: [
|
|
812
|
+
'::warning title=conductor version skew::' +
|
|
813
|
+
workflowCommandData(`${gate.product} resolved from ${skewPlace(gate.versionSkew)} reports version ` +
|
|
814
|
+
`${skewFound(gate.versionSkew)}, but this run expects ${gate.versionSkew.expected} (the version ` +
|
|
815
|
+
`the action pinned). Resolution is unchanged and that binary was used. ` +
|
|
816
|
+
skewFix(gate.product, gate.versionSkew)),
|
|
697
817
|
]);
|
|
698
818
|
}
|
|
819
|
+
/** The step-summary lines for the same warnings, one paragraph each. */
|
|
820
|
+
export function versionSkewSummaryLines(result) {
|
|
821
|
+
return result.gates.flatMap((gate) => gate.versionSkew === undefined
|
|
822
|
+
? []
|
|
823
|
+
: [
|
|
824
|
+
`conductor warning: ${gate.product} ${skewFound(gate.versionSkew)} ran from ` +
|
|
825
|
+
`${skewPlace(gate.versionSkew)}, but this run expects ${gate.versionSkew.expected} (the version ` +
|
|
826
|
+
`the action pinned). ${skewFix(gate.product, gate.versionSkew)}`,
|
|
827
|
+
]);
|
|
828
|
+
}
|
|
829
|
+
/** The gate-block line of the text report. Repository-relative paths only. */
|
|
830
|
+
function versionSkewLine(gate) {
|
|
831
|
+
const skew = gate.versionSkew;
|
|
832
|
+
if (skew === undefined) {
|
|
833
|
+
return null;
|
|
834
|
+
}
|
|
835
|
+
const from = skew.source === 'node_modules' ? skew.path : skewPlace(skew);
|
|
836
|
+
return (` ! conductor/version-skew: ${gate.product} ${skewFound(skew)} ran, from ${from}, but this run expects ` +
|
|
837
|
+
`${skew.expected} (the version the action pinned). Resolution is unchanged. ${skewFix(gate.product, skew)}`);
|
|
838
|
+
}
|
|
699
839
|
/**
|
|
700
840
|
* How many blocking findings one gate that RAN is carrying, for the token.
|
|
701
841
|
*
|
|
@@ -1017,14 +1157,55 @@ function isFullyClean(result) {
|
|
|
1017
1157
|
if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing)) {
|
|
1018
1158
|
return false;
|
|
1019
1159
|
}
|
|
1160
|
+
// A tie the convention refused to guess, or a skip whose branch 0.10.0
|
|
1161
|
+
// bound to a spec, carries a sentence the one-line summary would drop.
|
|
1162
|
+
if (result.skipped.some((gate) => gate.reason === 'spec-ambiguous' || (gate.selection?.legacy ?? null) !== null)) {
|
|
1163
|
+
return false;
|
|
1164
|
+
}
|
|
1020
1165
|
return result.gates.every((gate) => gate.couldNotRun === null &&
|
|
1021
1166
|
(gate.exitCode ?? 0) === 0 &&
|
|
1022
1167
|
gate.diagnostics.length === 0 &&
|
|
1023
1168
|
// A note about an input this run did not use is never folded into the
|
|
1024
1169
|
// one-line summary, where nobody would see it.
|
|
1025
1170
|
gate.intent?.note === undefined &&
|
|
1171
|
+
// Nor a weak convention match, or a winner that changed this release.
|
|
1172
|
+
conventionMatch(gate)?.strength !== 'weak' &&
|
|
1173
|
+
(conventionMatch(gate)?.legacy ?? null) === null &&
|
|
1026
1174
|
!gate.findings.some((finding) => finding.blocking));
|
|
1027
1175
|
}
|
|
1176
|
+
/**
|
|
1177
|
+
* The intent-spec header line: a CLOSED SET of four strings, in precedence
|
|
1178
|
+
* order, naming no branch, no file and no token. The Action copies one to the
|
|
1179
|
+
* step summary only on a whole-line match, so nothing the repository or the
|
|
1180
|
+
* head branch carries can reach that summary through it.
|
|
1181
|
+
*/
|
|
1182
|
+
export const INTENT_SPEC_LINES = [
|
|
1183
|
+
'intent-spec: none chosen, two or more specs matched the branch equally',
|
|
1184
|
+
'intent-spec: none chosen, this branch chose a spec before conductor 0.11.0',
|
|
1185
|
+
'intent-spec: a different spec chosen than before conductor 0.11.0, see the report',
|
|
1186
|
+
'intent-spec: weak match, see the intent gate in the report',
|
|
1187
|
+
];
|
|
1188
|
+
/** The first of the four lines that applies to this run, or null. */
|
|
1189
|
+
function intentSpecLine(result) {
|
|
1190
|
+
const misses = result.skipped.flatMap((gate) => (gate.selection === undefined ? [] : [gate.selection]));
|
|
1191
|
+
const matches = result.gates.flatMap((gate) => {
|
|
1192
|
+
const match = conventionMatch(gate);
|
|
1193
|
+
return match === null ? [] : [match];
|
|
1194
|
+
});
|
|
1195
|
+
if (misses.some((miss) => miss.why === 'ambiguous')) {
|
|
1196
|
+
return INTENT_SPEC_LINES[0];
|
|
1197
|
+
}
|
|
1198
|
+
if (misses.some((miss) => miss.legacy !== null)) {
|
|
1199
|
+
return INTENT_SPEC_LINES[1];
|
|
1200
|
+
}
|
|
1201
|
+
if (matches.some((match) => match.legacy !== null)) {
|
|
1202
|
+
return INTENT_SPEC_LINES[2];
|
|
1203
|
+
}
|
|
1204
|
+
if (matches.some((match) => match.strength === 'weak')) {
|
|
1205
|
+
return INTENT_SPEC_LINES[3];
|
|
1206
|
+
}
|
|
1207
|
+
return null;
|
|
1208
|
+
}
|
|
1028
1209
|
/**
|
|
1029
1210
|
* dep-guard's own diagnostic code for an online budget that ran out before
|
|
1030
1211
|
* every lookup was made (dep-guard core, online/deadline.ts,
|
|
@@ -1258,9 +1439,14 @@ export function renderText(result, options = {}) {
|
|
|
1258
1439
|
// job summary when, and only when, line 3 is exactly this shape, so a pass
|
|
1259
1440
|
// that carries them does not read as spotless there either.
|
|
1260
1441
|
const reported = presentOnBaseReported(result);
|
|
1442
|
+
// The intent-spec line follows it, so the present-on-base line, when
|
|
1443
|
+
// present, stays line 3 and every report without an intent-spec line keeps
|
|
1444
|
+
// the shape the Action already reads.
|
|
1445
|
+
const specLine = intentSpecLine(result);
|
|
1261
1446
|
const lines = [
|
|
1262
1447
|
...headerLines(result, options),
|
|
1263
1448
|
...(reported === 0 ? [] : [`present-on-base: ${reported} reported, not blocking`]),
|
|
1449
|
+
...(specLine === null ? [] : [specLine]),
|
|
1264
1450
|
...refusal,
|
|
1265
1451
|
...(refusal.length === 0 ? [] : ['']),
|
|
1266
1452
|
`conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
|
package/dist/run.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { type Finding } from './envelope.js';
|
|
2
2
|
import { type GateOutcome } from './gate-runner.js';
|
|
3
|
+
import type { SelectionMiss } from './intent-spec.js';
|
|
3
4
|
import type { GateRole, GateStage, Policy, Product } from './policy.js';
|
|
4
5
|
/**
|
|
5
6
|
* An enabled gate the stage filter held back.
|
|
@@ -69,8 +70,15 @@ export interface TreeUnchangedGate {
|
|
|
69
70
|
export interface SkippedGate {
|
|
70
71
|
role: GateRole;
|
|
71
72
|
product: Product;
|
|
72
|
-
|
|
73
|
+
/**
|
|
74
|
+
* `spec-ambiguous` is the third: two or more specs matched the branch name
|
|
75
|
+
* equally, so the convention chose none. Advisory exactly like the other
|
|
76
|
+
* two, and for the same reason.
|
|
77
|
+
*/
|
|
78
|
+
reason: 'no-contract' | 'contract-waived' | 'spec-ambiguous';
|
|
73
79
|
detail: string;
|
|
80
|
+
/** What the branch-name convention said, for the SARIF details bag. */
|
|
81
|
+
selection?: SelectionMiss;
|
|
74
82
|
}
|
|
75
83
|
/**
|
|
76
84
|
* One control input this pull request proposes to change.
|
package/dist/run.js
CHANGED
package/dist/unread-manifests.js
CHANGED
|
@@ -30,6 +30,10 @@ const EXACT_NAMES = new Set([
|
|
|
30
30
|
'deno.lock',
|
|
31
31
|
'mix.exs',
|
|
32
32
|
'pubspec.yaml',
|
|
33
|
+
// Added 2026-10-18 (audit finding N8): dep's lockfile, which osv-scanner
|
|
34
|
+
// 2.4.0 has no extractor for ("could not determine extractor suitable to
|
|
35
|
+
// this file", measured), so it is never handed over.
|
|
36
|
+
'Gopkg.lock',
|
|
33
37
|
]);
|
|
34
38
|
const MAX_LISTED = 12;
|
|
35
39
|
const SKIPPED_DIRS = new Set(['node_modules', 'vendor', 'testdata']);
|