@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.
@@ -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
- return reason === 'contract-waived'
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 that was found on PATH at a version other than the one
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 only: it names where the binary was found, and an absolute
684
- * path has no business in a published SARIF log or a pull request comment, so
685
- * this is never part of either report. A warning and nothing more. Resolution
686
- * is unchanged and the gate ran (or was refused) exactly as it would have
687
- * without it.
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 PATH reports version ${gate.versionSkew.found}, ` +
694
- `but this run expects ${gate.versionSkew.expected} (the version the action pinned). ` +
695
- `It was found at ${gate.versionSkew.path}. Resolution is unchanged and that binary was used. ` +
696
- `Fix: remove the other ${gate.product} from PATH, or install ${gate.versionSkew.expected}.`,
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
- reason: 'no-contract' | 'contract-waived';
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
@@ -309,6 +309,7 @@ export function runAll(policy, options) {
309
309
  product: gate.product,
310
310
  reason: prepared.reason,
311
311
  detail: prepared.detail,
312
+ ...(prepared.selection === undefined ? {} : { selection: prepared.selection }),
312
313
  });
313
314
  continue;
314
315
  }
@@ -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']);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.10.0",
3
+ "version": "0.12.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [