@vaultcompass/conductor 0.8.1 → 0.9.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.
@@ -117,6 +117,7 @@
117
117
  // product, which puts an end column in its own SARIF; see the note in
118
118
  // normalize.ts, which is where the omission would stop mattering if the
119
119
  // field were ever carried.
120
+ import { gateExitBlocks } from './exit-codes.js';
120
121
  import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
121
122
  import { INTENT_WARNING } from './normalize.js';
122
123
  import { POLICY_FILE_NAME } from './policy.js';
@@ -320,6 +321,18 @@ function toResult(finding, fallbackUri) {
320
321
  if (finding.fingerprint !== null) {
321
322
  entry.partialFingerprints = { [fingerprintKey(finding.fingerprint.scope)]: finding.fingerprint.value };
322
323
  }
324
+ // SARIF's own baselineState, only where the umbrella has a baseline to
325
+ // support it: an osv result from a compared pull-request run, `new` for
326
+ // introduced (including every finding in a lockfile the comparison was
327
+ // unavailable for) and `unchanged` for present-on-base. A run with no
328
+ // comparison sets no label, and so no state.
329
+ const baseline = finding.details.baseline;
330
+ if (baseline === 'introduced') {
331
+ entry.baselineState = 'new';
332
+ }
333
+ else if (baseline === 'present-on-base') {
334
+ entry.baselineState = 'unchanged';
335
+ }
323
336
  // Unconditional. The old code omitted the key when there was nothing
324
337
  // honest to say, and one such result makes GitHub reject the whole log.
325
338
  entry.locations = withFallbackLocation(locationsFor(finding), fallbackUri);
@@ -810,9 +823,17 @@ function unenforcedNotifications(result) {
810
823
  // this number answers is "what did the gate say", and the umbrella's
811
824
  // own findings are never the gate's answer.
812
825
  const blocking = gate.findings.filter((finding) => finding.blocking && finding.product !== UMBRELLA_DRIVER_NAME).length;
826
+ // Through gateExitBlocks, like every other reader of a non-zero child
827
+ // exit: under present-on-base: report an osv exit of 1 can be one that
828
+ // does not block, and saying only "exited 1" there would read as a
829
+ // block the exit code never had.
830
+ const exitBlocks = gateExitBlocks(gate);
813
831
  const what = gate.couldNotRun !== null
814
832
  ? `It could not run (${gate.couldNotRun.reason}), and nothing was checked by it.`
815
- : `It reported ${blocking} blocking finding(s) and exited ${gate.exitCode ?? -1}.`;
833
+ : `It reported ${blocking} blocking finding(s) and exited ${gate.exitCode ?? -1}` +
834
+ (exitBlocks || gate.baseComparison === undefined
835
+ ? '.'
836
+ : ', which does not block here: every finding was already on the base branch, under present-on-base: report.');
816
837
  return {
817
838
  id: 'conductor/gate-not-enforced',
818
839
  message: `The ${gate.role} gate (${gate.product}) has enforce: false, so its verdict did not ` +
@@ -823,10 +844,30 @@ function unenforcedNotifications(result) {
823
844
  enforced: false,
824
845
  couldNotRun: gate.couldNotRun === null ? null : gate.couldNotRun.reason,
825
846
  blockingFindings: blocking,
847
+ exitBlocks,
826
848
  },
827
849
  };
828
850
  });
829
851
  }
852
+ /**
853
+ * A gate's run facts for its SARIF run, plus the base comparison when one
854
+ * ran (the vulnerabilities gate on a compared pull-request run): the ref, the
855
+ * two counts and the base policy's present-on-base value. not-scanned is in
856
+ * the gate's own run details already.
857
+ */
858
+ function runDetails(gate) {
859
+ const comparison = gate.baseComparison;
860
+ if (comparison === undefined) {
861
+ return gate.run.details;
862
+ }
863
+ return {
864
+ ...gate.run.details,
865
+ 'baseline-ref': comparison.ref,
866
+ introduced: comparison.introduced,
867
+ 'present-on-base': comparison.presentOnBase,
868
+ 'present-on-base-policy': comparison.policy,
869
+ };
870
+ }
830
871
  /**
831
872
  * Renders a whole run as one SARIF log.
832
873
  *
@@ -864,7 +905,7 @@ export function renderSarif(result, umbrellaVersion) {
864
905
  // same bag the text report renders as scalars. Carried verbatim and
865
906
  // only when there is something in it, so a gate that reports none of
866
907
  // this keeps the properties shape it had before.
867
- ...(Object.keys(gate.run.details).length === 0 ? {} : { details: gate.run.details }),
908
+ ...(Object.keys(runDetails(gate)).length === 0 ? {} : { details: runDetails(gate) }),
868
909
  }));
869
910
  }
870
911
  // Still RESULTS, deliberately, and the asymmetry with the three above is
@@ -79,8 +79,11 @@ export declare function versionSkewWarnings(result: RunResult): string[];
79
79
  * the state without parsing the verdict sentence.
80
80
  *
81
81
  * pass exit 0 and nothing was hidden by it
82
- * nothing-checked exit 0, but no gate ran at all (none enabled,
83
- * or every one deferred, tree-unchanged or skipped)
82
+ * nothing-checked exit 0, but nothing was checked: no gate ran at
83
+ * all (none enabled, or every one deferred,
84
+ * tree-unchanged or skipped), or every gate that
85
+ * ran checked nothing (nothing to scan, or no
86
+ * contract; audit finding F4)
84
87
  * advisory-blocked (N) exit 1 that --advisory turned into exit 0
85
88
  * unenforced-findings (N) exit 0, but enforce: false gates blocked or
86
89
  * could not run
@@ -22,7 +22,7 @@
22
22
  // CI logs, and in pasted issue reports, and the plainest thing that works
23
23
  // everywhere is worth more here than a nicer-looking terminal.
24
24
  import { compareFindings } from './envelope.js';
25
- import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN } from './exit-codes.js';
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
27
  import { isLegacyContractPath } from './intent-prepare.js';
28
28
  function subjectLabel(finding) {
@@ -44,9 +44,42 @@ function findingLines(finding) {
44
44
  const marker = finding.blocking ? 'BLOCKING' : ' report';
45
45
  const severity = finding.severityIsDerived ? `${finding.severity}*` : finding.severity;
46
46
  const subject = subjectLabel(finding);
47
- const head = ` ${marker} ${severity.padEnd(9)} ${finding.ruleId}${subject === '' ? '' : ` ${subject}`}`;
47
+ // The vulnerabilities gate's base-comparison label, on a compared
48
+ // pull-request run only: the label is set nowhere else.
49
+ const baseline = finding.details.baseline;
50
+ const label = baseline === 'introduced' || baseline === 'present-on-base' ? ` ${baseline}` : '';
51
+ const head = ` ${marker} ${severity.padEnd(9)} ${finding.ruleId}${subject === '' ? '' : ` ${subject}`}${label}`;
48
52
  return [head, ` ${finding.message}`];
49
53
  }
54
+ /**
55
+ * The base comparison under the vulnerabilities gate's threshold line: the
56
+ * ref, the two counts, the base policy and what it means here, then one line
57
+ * per lockfile the comparison was unavailable for. Nothing on a run with no
58
+ * comparison.
59
+ */
60
+ function baseComparisonLines(gate) {
61
+ const comparison = gate.baseComparison;
62
+ if (comparison === undefined) {
63
+ return [];
64
+ }
65
+ const meaning = comparison.policy === 'report' ? 'report (not blocking)' : 'block (blocking)';
66
+ return [
67
+ ` base comparison ${comparison.ref} introduced ${comparison.introduced} ` +
68
+ `present-on-base ${comparison.presentOnBase} present-on-base: ${meaning}`,
69
+ ...comparison.unavailable.map((entry) => ` base comparison unavailable for ${entry.path}: ${entry.reason}; counted as introduced`),
70
+ ];
71
+ }
72
+ /**
73
+ * How many present-on-base findings were reported and NOT blocking, across
74
+ * the gates: the vulnerabilities gate under present-on-base: report. The
75
+ * number on the report's third line and in the exit-0 verdict clause.
76
+ */
77
+ function presentOnBaseReported(result) {
78
+ return result.gates
79
+ .filter((gate) => gate.baseComparison?.policy === 'report')
80
+ .flatMap((gate) => gate.findings)
81
+ .filter((finding) => finding.details.baseline === 'present-on-base' && !finding.blocking).length;
82
+ }
50
83
  function header(gate) {
51
84
  const version = gate.productVersion === null ? '(version unknown)' : gate.productVersion;
52
85
  // On the header line rather than only at the bottom of the section: a
@@ -75,7 +108,7 @@ function enforcementNote(gate) {
75
108
  'so it is a note here rather than a failed run. Nothing was checked by it.');
76
109
  }
77
110
  const blocking = gate.findings.filter((finding) => finding.blocking).length;
78
- if (blocking > 0 || (gate.exitCode ?? 0) !== 0) {
111
+ if (blocking > 0 || gateExitBlocks(gate)) {
79
112
  return (` not enforced: this gate reported ${blocking} blocking finding(s) and exited ` +
80
113
  `${gate.exitCode ?? '?'}, and enforce is false for it in .guardrails.yaml, so the commit ` +
81
114
  'proceeds. Set enforce: true there to make it block.');
@@ -143,6 +176,7 @@ function gateSection(gate) {
143
176
  ? 'ignored not reported'
144
177
  : `ignored ${gate.run.ignored}`;
145
178
  lines.push(` ${threshold} suppressed ${gate.run.suppressed} ${ignored}`);
179
+ lines.push(...baseComparisonLines(gate));
146
180
  // The gate's own run facts: what it scanned, with what, against what.
147
181
  // These were being collected and then dropped.
148
182
  //
@@ -225,6 +259,13 @@ function skipWording(reason) {
225
259
  function excludedLines(result) {
226
260
  return result.excluded.map((gate) => ` excluded ${gate.role} ${gate.product} did not run here; --gate did not name it`);
227
261
  }
262
+ /**
263
+ * One line per gate the policy file switches off with enabled: false, so an
264
+ * adopter sees what is not running at all. Absent when none is.
265
+ */
266
+ function disabledLines(result) {
267
+ return (result.disabled ?? []).map((gate) => ` disabled ${gate.role} ${gate.product} enabled: false in .guardrails.yaml; it did not run`);
268
+ }
228
269
  /**
229
270
  * One line per gate skipped because the head tree equals the trust base's
230
271
  * (issue #69).
@@ -348,7 +389,7 @@ function unenforcedClauses(result) {
348
389
  // blocking finding" reports the same gate as having blocked AND as having
349
390
  // failed to run, which are opposite claims.
350
391
  const blocked = unenforced.filter((gate) => gate.couldNotRun === null &&
351
- ((gate.exitCode ?? 0) !== 0 || gate.findings.some((finding) => finding.blocking)));
392
+ (gateExitBlocks(gate) || gate.findings.some((finding) => finding.blocking)));
352
393
  const broken = unenforced.filter((gate) => gate.couldNotRun !== null);
353
394
  const clauses = [];
354
395
  if (blocked.length > 0) {
@@ -516,7 +557,7 @@ function blockingCount(gate) {
516
557
  return 0;
517
558
  }
518
559
  const blocking = gate.findings.filter((finding) => finding.blocking).length;
519
- return blocking === 0 && (gate.exitCode ?? 0) !== 0 ? 1 : blocking;
560
+ return blocking === 0 && gateExitBlocks(gate) ? 1 : blocking;
520
561
  }
521
562
  /**
522
563
  * The verdict token: a label for the umbrella's OWN exit decision, in a
@@ -524,8 +565,11 @@ function blockingCount(gate) {
524
565
  * the state without parsing the verdict sentence.
525
566
  *
526
567
  * pass exit 0 and nothing was hidden by it
527
- * nothing-checked exit 0, but no gate ran at all (none enabled,
528
- * or every one deferred, tree-unchanged or skipped)
568
+ * nothing-checked exit 0, but nothing was checked: no gate ran at
569
+ * all (none enabled, or every one deferred,
570
+ * tree-unchanged or skipped), or every gate that
571
+ * ran checked nothing (nothing to scan, or no
572
+ * contract; audit finding F4)
529
573
  * advisory-blocked (N) exit 1 that --advisory turned into exit 0
530
574
  * unenforced-findings (N) exit 0, but enforce: false gates blocked or
531
575
  * could not run
@@ -574,7 +618,49 @@ export function verdictToken(result, advisory) {
574
618
  const unenforced = result.gates
575
619
  .filter((gate) => !gate.enforce)
576
620
  .reduce((total, gate) => total + (gate.couldNotRun !== null ? 1 : blockingCount(gate)), 0);
577
- return unenforced > 0 ? `unenforced-findings (${unenforced})` : 'pass';
621
+ if (unenforced > 0) {
622
+ return `unenforced-findings (${unenforced})`;
623
+ }
624
+ // Exit 0 where every gate that RAN checked nothing (audit finding F4): the
625
+ // vulnerabilities gate with no lockfile it reads, an intent gate with no
626
+ // contract. Gates ran, so the rule above does not fire, but nothing was
627
+ // examined, and a pass here is the same false statement as a pass with no
628
+ // gate at all. Same token, same exit code (0), same predicate the verdict
629
+ // sentence uses, so the two cannot disagree.
630
+ return result.gates.every(gateCheckedNothing) ? 'nothing-checked' : 'pass';
631
+ }
632
+ /**
633
+ * A gate that ran and examined nothing: osv-scanner with nothing to scan,
634
+ * osv-scanner whose every handed lockfile parsed to no packages (exit 128,
635
+ * marked `packages-read 0`; a sole lockfile rewritten to {} is exactly the
636
+ * same news as no lockfile), or an intent gate that found no contract to
637
+ * check against. The one predicate behind both the verdict token and the
638
+ * verdict sentence's list of what was not checked.
639
+ *
640
+ * NOT the partial-empty case: `conductor/lockfiles-empty` is also raised
641
+ * when osv-scanner read packages from other lockfiles (audit finding F2),
642
+ * and that gate checked something. Only the `packages-read` marker, which
643
+ * the exit-128 branch alone writes, tells the two apart.
644
+ */
645
+ function readNoPackages(gate) {
646
+ return gate.run.details['packages-read'] === 0;
647
+ }
648
+ function gateCheckedNothing(gate) {
649
+ if (gate.couldNotRun !== null) {
650
+ return false;
651
+ }
652
+ return (gate.diagnostics.some((d) => d.code === 'conductor/nothing-to-scan') ||
653
+ readNoPackages(gate) ||
654
+ (gate.role === 'intent' && gate.run.details.contractFound === false));
655
+ }
656
+ /** How the verdict sentence names a gate that ran and checked nothing. */
657
+ function checkedNothingWording(gate) {
658
+ if (gate.role === 'intent') {
659
+ return `${gate.role} ran but found no contract to check against`;
660
+ }
661
+ return readNoPackages(gate)
662
+ ? `${gate.role} read no packages from its lockfiles`
663
+ : `${gate.role} had nothing to scan`;
578
664
  }
579
665
  function verdict(result, advisory) {
580
666
  const refusal = result.trustBase?.refusal;
@@ -685,7 +771,7 @@ function verdictForRun(result, advisory) {
685
771
  // explicitly says there is none of, so it gets its own, narrower
686
772
  // wording that is true here and says nothing about findings at all.
687
773
  const names = enforcedGates
688
- .filter((gate) => (gate.exitCode ?? 0) !== 0)
774
+ .filter((gate) => gateExitBlocks(gate))
689
775
  .map((gate) => `${gate.role} (exit ${gate.exitCode ?? '?'})`)
690
776
  .join(', ');
691
777
  const base = `and no finding here is marked blocking. Enforced gate(s) that exited ` +
@@ -695,19 +781,52 @@ function verdictForRun(result, advisory) {
695
781
  ? `verdict: exit 0, ${base} This run was advisory, so exit 1 became exit 0.`
696
782
  : `verdict: exit 1, ${base}`;
697
783
  }
698
- const base = `${blocking} blocking finding(s) across ${enforcedGates.length} gate(s).${aside}`;
784
+ // Gates that blocked out of gates that could have, not a bare count of
785
+ // the enforced ones, which read as if every one of them had blocked.
786
+ const blockedGates = enforcedGates.filter((gate) => blockingCount(gate) > 0).length;
787
+ const base = `${blocking} blocking finding(s) in ${blockedGates} of ${enforcedGates.length} ` +
788
+ `enforced gate(s).${aside}`;
699
789
  return advisory
700
790
  ? `verdict: exit 0, ${base} Findings were advisory and did not block, so this run exits 0 rather than 1.`
701
791
  : `verdict: exit 1, ${base}`;
702
792
  }
793
+ // Known advisories already on the base branch, reported and not blocking
794
+ // (the vulnerabilities gate under present-on-base: report). Said on the
795
+ // exit-0 verdict, so a pass that carries them never reads as spotless.
796
+ const reported = presentOnBaseReported(result);
797
+ const presentClause = reported === 0
798
+ ? ''
799
+ : `; ${reported} known ${reported === 1 ? 'vulnerability' : 'vulnerabilities'} already on the ` +
800
+ `base ${reported === 1 ? 'was' : 'were'} reported, not blocking (vulnerabilities: present-on-base: report)`;
703
801
  // Exit 0 with red on the screen above it. The verdict is the one line
704
802
  // somebody reads when they read nothing else, so it is the line that has
705
803
  // to carry the reason rather than leaving it to the sections.
706
804
  if (clauses.length > 0) {
707
- return (`verdict: exit 0, but ${clauses.join(' and ')}. ` +
805
+ return (`verdict: exit 0, but ${clauses.join(' and ')}${presentClause}. ` +
708
806
  'Those gates have enforce: false in .guardrails.yaml, so nothing here failed the run.');
709
807
  }
710
- return `verdict: exit 0, every enabled gate ran and none blocked.`;
808
+ // "Every enabled gate ran" is only true when each one actually checked
809
+ // something. A gate that was held back, left out, skipped, or found nothing
810
+ // to scan did not, and the sentence a reader reads alone must say so.
811
+ const unchecked = [
812
+ ...result.deferred.map((gate) => `${gate.role} deferred to stage ${gate.stage}`),
813
+ ...result.excluded.map((gate) => `${gate.role} left out by --gate`),
814
+ ...result.treeUnchanged.map((gate) => `${gate.role} skipped, head tree equals the base tree`),
815
+ ...result.skipped.map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`),
816
+ // A gate with nothing to scan, or the intent gate with require-frozen:
817
+ // false running with no contract: it ran and checked nothing.
818
+ ...result.gates.filter(gateCheckedNothing).map(checkedNothingWording),
819
+ ];
820
+ // Every gate that ran checked nothing: the token is nothing-checked (audit
821
+ // finding F4), and the sentence says what the token says.
822
+ if (result.gates.every(gateCheckedNothing)) {
823
+ return `verdict: exit 0, nothing was checked: ${unchecked.join('; ')}.`;
824
+ }
825
+ if (unchecked.length > 0) {
826
+ return ('verdict: exit 0, no gate blocked, but not every enabled gate checked something: ' +
827
+ `${unchecked.join('; ')}${presentClause}.`);
828
+ }
829
+ return `verdict: exit 0, every enabled gate ran and none blocked${presentClause}.`;
711
830
  }
712
831
  /**
713
832
  * Whether this run has nothing at all to report.
@@ -739,7 +858,9 @@ function verdictForRun(result, advisory) {
739
858
  * confusion this family exists to prevent.
740
859
  */
741
860
  function isFullyClean(result) {
742
- if (result.exitCode !== 0 || result.gates.length === 0) {
861
+ // Every gate that ran checked nothing is the nothing-checked token's state
862
+ // (audit finding F4), and a line opening "clean" would contradict it.
863
+ if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing)) {
743
864
  return false;
744
865
  }
745
866
  return result.gates.every((gate) => gate.couldNotRun === null &&
@@ -842,6 +963,13 @@ function summaryLine(result) {
842
963
  else {
843
964
  parts.push('0 gate(s) not enforced.');
844
965
  }
966
+ // Gates the policy file switches off. Only when there are some: a count of
967
+ // zero here would be noise on the line a hook prints on every commit.
968
+ const disabled = result.disabled ?? [];
969
+ if (disabled.length > 0) {
970
+ const names = disabled.map((gate) => `${gate.role} (${gate.product})`).join(', ');
971
+ parts.push(`Disabled (enabled: false in .guardrails.yaml): ${names}.`);
972
+ }
845
973
  // Non-blocking findings are counted rather than hidden, for the same reason
846
974
  // the full report prints the suppressed and ignored counts at zero: they
847
975
  // are things the gates actually said, and a summary that omitted them would
@@ -937,8 +1065,14 @@ export function renderText(result, options = {}) {
937
1065
  // question, what failed the run, and that one is enforced gates only. Two
938
1066
  // different questions, so two numbers, and the section headers and the
939
1067
  // "not enforced" lines are what connect them.
1068
+ // The fixed third line (osv design, section 4.4), printed only when known
1069
+ // advisories were reported and not blocking. The Action copies it to the
1070
+ // job summary when, and only when, line 3 is exactly this shape, so a pass
1071
+ // that carries them does not read as spotless there either.
1072
+ const reported = presentOnBaseReported(result);
940
1073
  const lines = [
941
1074
  ...headerLines(result, options),
1075
+ ...(reported === 0 ? [] : [`present-on-base: ${reported} reported, not blocking`]),
942
1076
  ...refusal,
943
1077
  ...(refusal.length === 0 ? [] : ['']),
944
1078
  `conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
@@ -951,6 +1085,7 @@ export function renderText(result, options = {}) {
951
1085
  ...skippedLines(result),
952
1086
  ...excludedLines(result),
953
1087
  ...treeUnchangedLines(result),
1088
+ ...disabledLines(result),
954
1089
  ];
955
1090
  if (aside.length > 0) {
956
1091
  lines.push('', ...aside);
package/dist/policy.d.ts CHANGED
@@ -83,7 +83,17 @@ export interface GatePolicy {
83
83
  args?: string[];
84
84
  /** Handed to the gate unchanged. */
85
85
  options: Record<string, OptionValue>;
86
+ /**
87
+ * The vulnerabilities gate only, and always set there: whether a finding
88
+ * that is also on the base branch blocks (`block`, the default when the key
89
+ * is absent) or is reported without blocking (`report`). Gate-level beside
90
+ * `enforce`, never under `options`, which are a pure passthrough. Absent on
91
+ * every other gate; a reader of an absent value treats it as `block`.
92
+ */
93
+ presentOnBase?: PresentOnBase;
86
94
  }
95
+ /** The two values of the vulnerabilities gate's present-on-base key. */
96
+ export type PresentOnBase = 'block' | 'report';
87
97
  export interface Policy {
88
98
  version: 1;
89
99
  gates: Partial<Record<GateRole, GatePolicy>>;
package/dist/policy.js CHANGED
@@ -315,6 +315,15 @@ export function parsePolicy(text, source) {
315
315
  reservedReason(product, key));
316
316
  }
317
317
  }
318
+ // Only the vulnerabilities gate has a base comparison to apply the key to.
319
+ // On another gate it would read as a promise nothing keeps, so it is
320
+ // refused rather than ignored.
321
+ const presentOnBase = entry['present-on-base'];
322
+ if (presentOnBase !== undefined && role !== 'vulnerabilities') {
323
+ throw new PolicyError(`${source}: gates.${role}.present-on-base is set, but only the vulnerabilities gate ` +
324
+ '(osv-scanner) compares a pull request with its base, so the key has nothing to decide ' +
325
+ `on the ${role} gate. Remove it there.`);
326
+ }
318
327
  const command = entry.command;
319
328
  if (command !== undefined && !path.isAbsolute(command)) {
320
329
  throw new PolicyError(`${source}: gates.${role}.command must be an absolute path, got "${command}". ` +
@@ -338,6 +347,9 @@ export function parsePolicy(text, source) {
338
347
  ...(command === undefined ? {} : { command }),
339
348
  ...(entry.args === undefined ? {} : { args: entry.args }),
340
349
  options,
350
+ // Absent means block: a policy written before the key existed blocks
351
+ // on every known vulnerability, so no policy is loosened by an upgrade.
352
+ ...(role === 'vulnerabilities' ? { presentOnBase: presentOnBase ?? 'block' } : {}),
341
353
  };
342
354
  }
343
355
  return {
@@ -56,11 +56,13 @@ export interface ProductProfile {
56
56
  */
57
57
  stderrError: RegExp | null;
58
58
  /**
59
- * File names the tool is handed one by one, from the repository's tracked
60
- * files, instead of being pointed at a directory to walk. Null for a tool
61
- * that is not handed files.
59
+ * Which tracked files the tool is handed one by one, by base name, instead
60
+ * of being pointed at a directory to walk, and how: `bare` as the path
61
+ * itself, `requirements` as a pip requirements file that must first pass
62
+ * the pin check (src/requirements-pin.ts). Null for a tool that is not
63
+ * handed files.
62
64
  */
63
- lockfileNames: readonly string[] | null;
65
+ lockfileMatcher: ((file: string) => LockfileKind | null) | null;
64
66
  /**
65
67
  * The config can name another file (`[extend] path`) that the tool reads
66
68
  * relative to its working directory. On a pull request every such file is
@@ -84,20 +86,40 @@ export interface ProductProfile {
84
86
  */
85
87
  readsHistory: boolean;
86
88
  }
89
+ /** How a matched file is handed over: as its own path, or as a requirements file. */
90
+ export type LockfileKind = 'bare' | 'requirements';
87
91
  /**
88
- * The lockfiles osv-scanner is handed, matched by base name at any depth
89
- * among the repository's TRACKED files (`git ls-files`).
92
+ * The lockfiles osv-scanner is handed as a bare path, matched by base name at
93
+ * any depth among the repository's TRACKED files (`git ls-files`).
90
94
  *
91
95
  * By name, not by walking the tree, for three reasons: osv-scanner's own walk
92
96
  * skips anything .gitignore matches, tracked or not, so a pull request could
93
97
  * hide a committed lockfile from it with one ignore line; the walk can reach
94
98
  * into node_modules; and an untracked lockfile is not part of what is being
95
- * judged. Only the npm family is listed, because that is the ecosystem this
96
- * family's own dependency gate knows (npm, pnpm, yarn, bun); osv-scanner
97
- * supports more, and a repository whose only lockfile is another ecosystem's
98
- * gets nothing-to-scan until a name is added here.
99
+ * judged.
100
+ *
101
+ * Every name here was handed to osv-scanner 2.4.0 with --lockfile and read
102
+ * (the 2026-10-11 osv design under docs/superpowers/specs, section 2.1). go.sum is deliberately absent: 2.4.0
103
+ * rejects it ("could not determine extractor", exit 127), which would make
104
+ * every Go pull request could-not-run, and go.mod is what it reads for Go.
105
+ *
106
+ * The second group was added on 2026-10-13 (audit finding F3: a tracked
107
+ * mix.lock was neither scanned nor named), each measured the same way
108
+ * against 2.4.0 and read with one or more packages. Measured and NOT added,
109
+ * because 2.4.0 exits 127 on them: Podfile.lock and deno.lock (both are
110
+ * named by the unread-manifests note instead). gradle's
111
+ * verification-metadata.xml is read only inside a `gradle` directory and is
112
+ * matched by `osvLockfileKind` rather than listed here.
99
113
  */
100
114
  export declare const OSV_LOCKFILE_NAMES: readonly string[];
115
+ /**
116
+ * What osv-scanner is handed for a tracked file, or null. Takes the
117
+ * repository-relative path (a bare base name works for every name but one):
118
+ * gradle's verification-metadata.xml is read by osv-scanner 2.4.0 only when
119
+ * its parent directory is `gradle`, and anywhere else it exits 127, so the
120
+ * parent is part of the match for that one file.
121
+ */
122
+ export declare function osvLockfileKind(file: string): LockfileKind | null;
101
123
  /**
102
124
  * The npm gates print a bare version. No capture group on purpose: the runner
103
125
  * has always reported the whole first line minus a leading v, prerelease
package/dist/products.js CHANGED
@@ -8,17 +8,27 @@
8
8
  // did before profiles existed; changing one of them changes a gate that
9
9
  // adopters already run.
10
10
  /**
11
- * The lockfiles osv-scanner is handed, matched by base name at any depth
12
- * among the repository's TRACKED files (`git ls-files`).
11
+ * The lockfiles osv-scanner is handed as a bare path, matched by base name at
12
+ * any depth among the repository's TRACKED files (`git ls-files`).
13
13
  *
14
14
  * By name, not by walking the tree, for three reasons: osv-scanner's own walk
15
15
  * skips anything .gitignore matches, tracked or not, so a pull request could
16
16
  * hide a committed lockfile from it with one ignore line; the walk can reach
17
17
  * into node_modules; and an untracked lockfile is not part of what is being
18
- * judged. Only the npm family is listed, because that is the ecosystem this
19
- * family's own dependency gate knows (npm, pnpm, yarn, bun); osv-scanner
20
- * supports more, and a repository whose only lockfile is another ecosystem's
21
- * gets nothing-to-scan until a name is added here.
18
+ * judged.
19
+ *
20
+ * Every name here was handed to osv-scanner 2.4.0 with --lockfile and read
21
+ * (the 2026-10-11 osv design under docs/superpowers/specs, section 2.1). go.sum is deliberately absent: 2.4.0
22
+ * rejects it ("could not determine extractor", exit 127), which would make
23
+ * every Go pull request could-not-run, and go.mod is what it reads for Go.
24
+ *
25
+ * The second group was added on 2026-10-13 (audit finding F3: a tracked
26
+ * mix.lock was neither scanned nor named), each measured the same way
27
+ * against 2.4.0 and read with one or more packages. Measured and NOT added,
28
+ * because 2.4.0 exits 127 on them: Podfile.lock and deno.lock (both are
29
+ * named by the unread-manifests note instead). gradle's
30
+ * verification-metadata.xml is read only inside a `gradle` directory and is
31
+ * matched by `osvLockfileKind` rather than listed here.
22
32
  */
23
33
  export const OSV_LOCKFILE_NAMES = [
24
34
  'package-lock.json',
@@ -26,7 +36,61 @@ export const OSV_LOCKFILE_NAMES = [
26
36
  'pnpm-lock.yaml',
27
37
  'yarn.lock',
28
38
  'bun.lock',
39
+ 'go.mod',
40
+ 'poetry.lock',
41
+ 'Pipfile.lock',
42
+ 'uv.lock',
43
+ 'pdm.lock',
44
+ 'Cargo.lock',
45
+ 'Gemfile.lock',
46
+ 'composer.lock',
47
+ 'gradle.lockfile',
48
+ 'packages.lock.json',
49
+ 'mix.lock',
50
+ 'pubspec.lock',
51
+ 'Package.resolved',
52
+ 'conan.lock',
53
+ 'renv.lock',
54
+ 'packages.config',
55
+ 'buildscript-gradle.lockfile',
56
+ 'gems.locked',
57
+ 'pylock.toml',
58
+ 'cabal.project.freeze',
59
+ 'stack.yaml.lock',
60
+ ];
61
+ /** gradle's dependency verification file, which 2.4.0 reads only under a `gradle` directory. */
62
+ const GRADLE_VERIFICATION_METADATA = 'verification-metadata.xml';
63
+ /**
64
+ * pip requirements files, by base name: requirements.txt itself,
65
+ * requirements-dev.txt and its _ and . spellings, and dev-requirements.txt.
66
+ * Not requirements.in (pip-tools input, unpinned by design), not constraints
67
+ * files, and not a file under a requirements/ directory whose own name does
68
+ * not match. A requirements file is handed over only when every requirement
69
+ * in it, and in every file it includes, is pinned with == (the pin check).
70
+ */
71
+ const REQUIREMENTS_PATTERNS = [
72
+ /^requirements\.txt$/,
73
+ /^requirements[-_.][A-Za-z0-9._-]+\.txt$/,
74
+ /^[A-Za-z0-9._-]+[-_]requirements\.txt$/,
29
75
  ];
76
+ /**
77
+ * What osv-scanner is handed for a tracked file, or null. Takes the
78
+ * repository-relative path (a bare base name works for every name but one):
79
+ * gradle's verification-metadata.xml is read by osv-scanner 2.4.0 only when
80
+ * its parent directory is `gradle`, and anywhere else it exits 127, so the
81
+ * parent is part of the match for that one file.
82
+ */
83
+ export function osvLockfileKind(file) {
84
+ const segments = file.split('/');
85
+ const basename = segments[segments.length - 1] ?? '';
86
+ if (basename === GRADLE_VERIFICATION_METADATA) {
87
+ return segments[segments.length - 2] === 'gradle' ? 'bare' : null;
88
+ }
89
+ if (OSV_LOCKFILE_NAMES.includes(basename)) {
90
+ return 'bare';
91
+ }
92
+ return REQUIREMENTS_PATTERNS.some((pattern) => pattern.test(basename)) ? 'requirements' : null;
93
+ }
30
94
  /**
31
95
  * The npm gates print a bare version. No capture group on purpose: the runner
32
96
  * has always reported the whole first line minus a leading v, prerelease
@@ -55,7 +119,7 @@ function managedProfile(product) {
55
119
  ignoreFile: null,
56
120
  remedy: managedRemedy(product),
57
121
  stderrError: null,
58
- lockfileNames: null,
122
+ lockfileMatcher: null,
59
123
  followsConfigExtend: false,
60
124
  readsHistory: false,
61
125
  };
@@ -93,7 +157,7 @@ const PROFILES = {
93
157
  // gitleaks 8.30.1 swallows a git failure: it logs "<time> ERR [git]
94
158
  // fatal: ..." and exits 0 with an empty report (tests/fixtures/README.md).
95
159
  stderrError: /^\S+\s+ERR\s/,
96
- lockfileNames: null,
160
+ lockfileMatcher: null,
97
161
  followsConfigExtend: true,
98
162
  // gitleaks reads git history (--log-opts), never the tree, which is
99
163
  // exactly what makes it the one gate an equal-tree pull request does not
@@ -120,7 +184,7 @@ const PROFILES = {
120
184
  // osv-scanner's exit codes separate an error (127) from a verdict, and
121
185
  // its stderr is progress chatter, so the exit is taken at its word.
122
186
  stderrError: null,
123
- lockfileNames: OSV_LOCKFILE_NAMES,
187
+ lockfileMatcher: osvLockfileKind,
124
188
  followsConfigExtend: false,
125
189
  // osv-scanner reads the tracked lockfiles it is handed, which are the
126
190
  // tree being judged, not history.
@@ -0,0 +1,47 @@
1
+ /** One file the check asked for: its text, or why there is none. */
2
+ export type IncludeRead = {
3
+ kind: 'file';
4
+ text: string;
5
+ } | {
6
+ kind: 'missing';
7
+ why: string;
8
+ };
9
+ export interface PinProblem {
10
+ /** The file the problem is in, repository-relative. */
11
+ file: string;
12
+ /** The physical line a logical line starts on; null for a problem with an include itself. */
13
+ line: number | null;
14
+ /** The logical line as written, cleaned for printing; for an include, the path as written. */
15
+ text: string;
16
+ kind: 'unpinned' | 'arbitrary-equality' | 'unrecognised' | 'include';
17
+ /** For an include: why it cannot be read ("which is outside the repository"). */
18
+ why?: string;
19
+ }
20
+ export interface PinCheck {
21
+ pinned: boolean;
22
+ /** Every file read, the top file first, repository-relative. */
23
+ files: string[];
24
+ /** Direct references (-e, paths, URLs, name @ url) left out of the check. */
25
+ excluded: number;
26
+ problems: PinProblem[];
27
+ /** Why the top file itself could not be read, or null when it was. */
28
+ topMissing: string | null;
29
+ }
30
+ /** The deepest include chain followed. A deeper one leaves the top file unscanned. */
31
+ export declare const MAX_INCLUDE_DEPTH = 8;
32
+ /**
33
+ * Checks one requirements file and everything it includes.
34
+ *
35
+ * `read` is asked for each file by repository-relative path and decides what
36
+ * "there" means: on the head, a tracked regular file on disk; on the base,
37
+ * the blob at the trust base. Every problem is collected, not only the first,
38
+ * so the ratchet's diagnostic can name each unpinned line; `pinned` is true
39
+ * only when there are none.
40
+ */
41
+ export declare function checkRequirementsPins(top: string, read: (file: string) => IncludeRead): PinCheck;
42
+ /**
43
+ * One problem as the reason clause of a diagnostic about `top`, with no
44
+ * trailing full stop: `line 4 "flask>=2.0" is not pinned with ==, so any
45
+ * version osv-scanner reported would be a guess`.
46
+ */
47
+ export declare function describePinProblem(top: string, problem: PinProblem): string;