@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.
@@ -23,10 +23,13 @@ import { tmpdir } from 'node:os';
23
23
  import path from 'node:path';
24
24
  import { runGit } from './git.js';
25
25
  import { NormalizeError } from './envelope.js';
26
- import { normalizeDepGuard, normalizeFailedGate, normalizeGitleaks, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeOsvScanner, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
26
+ import { describeLockfiles, normalizeDepGuard, normalizeFailedGate, normalizeGitleaks, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeOsvScanner, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
27
27
  import { renderOptionFlags } from './policy.js';
28
+ import { NO_RESOLVE_OVERRIDDEN, emptiedLockfiles, noLongerScanned, nothingScannableMessage, notScannedDetail, selectOsvInputs, } from './osv-coverage.js';
29
+ import { compareWithBase, comparisonFailed, } from './osv-baseline.js';
28
30
  import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals, } from './external-config.js';
29
- import { profileFor } from './products.js';
31
+ import { osvLockfileKind, profileFor } from './products.js';
32
+ import { unreadManifestsNote } from './unread-manifests.js';
30
33
  import { atLeastVersion, refuseHeadControlledProgram } from './trust-base.js';
31
34
  import { ResolveError, candidateNames, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
32
35
  /** The longest excerpt of a gate's own reason that is carried. */
@@ -542,15 +545,55 @@ intentBase) {
542
545
  case 'osv-scanner': {
543
546
  // JSON goes to stdout and everything else to stderr, so no report
544
547
  // file. No directory walk: each tracked lockfile is named with
545
- // --lockfile (the runner lists them, src/products.ts
546
- // OSV_LOCKFILE_NAMES), because osv-scanner's own walk skips anything
547
- // .gitignore matches, tracked or not. With none there is nothing to
548
- // hand over, and the runner reports that without spawning the tool.
548
+ // --lockfile (the runner lists them, src/osv-coverage.ts), because
549
+ // osv-scanner's own walk skips anything .gitignore matches, tracked or
550
+ // not. With none there is nothing to hand over, and the runner reports
551
+ // that without spawning the tool.
549
552
  if (external.lockfiles === undefined || external.lockfiles.length === 0) {
550
553
  throw new Error('osv-scanner needs at least one lockfile: with none, nothing is spawned');
551
554
  }
552
- const lockfiles = external.lockfiles.flatMap((file) => ['--lockfile', file]);
553
- return ['--format', 'json', ...config, ...lockfiles, ...passthrough];
555
+ const isRequirements = (file) => osvLockfileKind(path.basename(file)) === 'requirements';
556
+ // A requirements variant (requirements-dev.txt) is handed in the
557
+ // parse-as form, because 2.4.0 does not recognise the bare name;
558
+ // requirements.txt itself and every exact lockfile name go bare
559
+ // (npm-shrinkwrap.json is not even a valid parse-as type in 2.4.0).
560
+ // The parse-as form splits on the first colon only, so a variant's own
561
+ // path is safe; a bare path with a colon is split and exits 127, which
562
+ // is a could-not-run, never a silent skip.
563
+ const lockfiles = external.lockfiles.flatMap((file) => [
564
+ '--lockfile',
565
+ isRequirements(file) && path.basename(file) !== 'requirements.txt' ? `requirements.txt:${file}` : file,
566
+ ]);
567
+ // --no-resolve on every invocation that carries a requirements file,
568
+ // and on the base run exactly when the head run had it (section 2.4):
569
+ // without a lockfile, a resolved transitive version is the registry's
570
+ // latest, not the installed one. Not overridable: a policy no-resolve
571
+ // is dropped from such an invocation (the runner says so), because
572
+ // no-resolve: false would render --no-no-resolve, which osv rejects.
573
+ const noResolve = external.noResolve ?? external.lockfiles.some(isRequirements);
574
+ const options = { ...gate.options };
575
+ if (noResolve) {
576
+ delete options['no-resolve'];
577
+ }
578
+ // On a pull-request run, call analysis is off for every language
579
+ // unless the base policy says otherwise (section 3.3, open question 6):
580
+ // the base copies carry no source, so call analysis could hide on the
581
+ // head what the base run reports, and the comparison would then not be
582
+ // a dependency fact. Off on both runs makes the head only gain
583
+ // findings. A policy that names either key keeps its own value, on
584
+ // both runs, through the passthrough.
585
+ const callAnalysis = trustBase !== undefined && !('call-analysis' in options) && !('no-call-analysis' in options)
586
+ ? ['--no-call-analysis=all']
587
+ : [];
588
+ return [
589
+ '--format',
590
+ 'json',
591
+ ...config,
592
+ ...lockfiles,
593
+ ...(noResolve ? ['--no-resolve'] : []),
594
+ ...callAnalysis,
595
+ ...renderOptionFlags(options),
596
+ ];
554
597
  }
555
598
  }
556
599
  }
@@ -1031,8 +1074,18 @@ function spawnAndRead(ctx) {
1031
1074
  // removing or renaming one is visible in the diff, so there is nothing for
1032
1075
  // a base-ref read to protect. A listing that fails is not "no lockfiles".
1033
1076
  const nestedProposals = [];
1034
- if (profile.lockfileNames !== null) {
1035
- const names = new Set(profile.lockfileNames);
1077
+ // What the osv gate's selection said beside the list it handed over: the
1078
+ // umbrella's own diagnostics (a requirements file left out, or scanned
1079
+ // under the ratchet, a passthrough option dropped) and the per-file run
1080
+ // notes. Carried onto every outcome from here on that reports a scan.
1081
+ let selection = null;
1082
+ const selectionDiagnostics = [];
1083
+ // Tracked manifests this gate was NOT handed, when it was handed others
1084
+ // (review of 1b.2, item 5): a run note, so a Podfile.lock beside a scanned
1085
+ // mix.lock is named without pushing a clean run off its one-line summary.
1086
+ // The nothing-to-scan branch below names them in its own diagnostic.
1087
+ let unreadNote = null;
1088
+ if (profile.lockfileMatcher !== null) {
1036
1089
  const listing = runGit(options.repoRoot, ['ls-files', '-z'], { maxBuffer: 64 * 1024 * 1024 });
1037
1090
  if (listing.error !== undefined || listing.status !== 0) {
1038
1091
  const detail = `the repository's tracked files could not be listed, so ${gate.product} had no ` +
@@ -1071,15 +1124,29 @@ function spawnAndRead(ctx) {
1071
1124
  };
1072
1125
  }
1073
1126
  }
1074
- external.lockfiles = tracked
1075
- // Never a vendored copy under node_modules: that is a dependency's own
1076
- // lockfile, not a statement about what this repository resolves.
1077
- .filter((file) => !file.split('/').includes('node_modules'))
1078
- .filter((file) => names.has(path.posix.basename(file)))
1079
- .sort();
1127
+ // The pin check reads the head copies on disk and, on a pull request, the
1128
+ // base copies through the one reader; both are selection, not verdicts.
1129
+ selection = selectOsvInputs({
1130
+ repoRoot: options.repoRoot,
1131
+ tracked,
1132
+ ...(decidedRef === undefined ? {} : { decidedRef }),
1133
+ });
1134
+ external.lockfiles = selection.handed;
1135
+ selectionDiagnostics.push(...selection.diagnostics);
1136
+ if (decidedRef !== undefined) {
1137
+ selectionDiagnostics.push(...noLongerScanned(options.repoRoot, decidedRef, new Set(tracked)));
1138
+ }
1139
+ if (external.lockfiles.length > 0) {
1140
+ const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
1141
+ unreadNote = unread === null ? null : { code: 'conductor/manifests-not-handed', message: unread };
1142
+ }
1080
1143
  if (external.lockfiles.length === 0) {
1081
1144
  // Nothing to scan, reported the same way as osv-scanner's own 128 below,
1082
- // without spawning it.
1145
+ // without spawning it. The verdict is unchanged (clean); what changes is
1146
+ // what is said: which requirements files the pin check left out, and
1147
+ // which tracked manifests were not handed to this scanner.
1148
+ const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
1149
+ const cleanBecause = 'the verdict is clean because there was nothing to read, not because a scan found nothing.';
1083
1150
  return {
1084
1151
  ...base,
1085
1152
  productVersion: version,
@@ -1091,13 +1158,21 @@ function spawnAndRead(ctx) {
1091
1158
  findings: [],
1092
1159
  run: EMPTY_RUN,
1093
1160
  diagnostics: [
1161
+ ...selectionDiagnostics,
1094
1162
  {
1095
1163
  code: 'conductor/nothing-to-scan',
1096
- message: `${gate.product} found nothing to scan (no tracked lockfile); treated as clean.`,
1164
+ message: (selection.notScanned.length > 0
1165
+ ? `${nothingScannableMessage(selection.notScanned)} T${cleanBecause.slice(1)}`
1166
+ : `${gate.product} read no lockfile, so nothing was scanned; ${cleanBecause}`) +
1167
+ (unread === null ? '' : ` ${unread}`),
1097
1168
  },
1098
1169
  ],
1099
1170
  };
1100
1171
  }
1172
+ external.noResolve = external.lockfiles.some((file) => osvLockfileKind(path.posix.basename(file)) === 'requirements');
1173
+ if (external.noResolve && 'no-resolve' in gate.options) {
1174
+ selectionDiagnostics.push({ code: 'conductor/option-overridden', message: NO_RESOLVE_OVERRIDDEN });
1175
+ }
1101
1176
  }
1102
1177
  // On a pull request, the tool's config and ignore file come from the base
1103
1178
  // ref (or a neutral stand-in), never from the head it would otherwise
@@ -1237,13 +1312,28 @@ function spawnAndRead(ctx) {
1237
1312
  // request in a docs-only repository; read as a verdict it would claim a
1238
1313
  // scan that did not happen. So it is clean, and the report says why.
1239
1314
  if (exitCode !== null && profile.exit.nothingToScan.includes(exitCode)) {
1315
+ const handedAll = external.lockfiles ?? [];
1240
1316
  return {
1241
1317
  ...withRun,
1242
1318
  exitCode: 0,
1243
1319
  couldNotRun: null,
1244
1320
  findings: [],
1245
- run: EMPTY_RUN,
1321
+ // Every handed lockfile parsed to nothing: `packages-read 0` is the
1322
+ // marker that this gate read NOTHING (the verdict token's
1323
+ // nothing-checked rule reads it), which the partial-empty note further
1324
+ // down shares a diagnostic code with but never carries.
1325
+ run: handedAll.length === 0
1326
+ ? EMPTY_RUN
1327
+ : {
1328
+ ...EMPTY_RUN,
1329
+ diagnostics: unreadNote === null ? [] : [unreadNote],
1330
+ details: {
1331
+ lockfiles: describeLockfiles(handedAll, new Set(handedAll)),
1332
+ 'packages-read': 0,
1333
+ },
1334
+ },
1246
1335
  diagnostics: [
1336
+ ...selectionDiagnostics,
1247
1337
  // When lockfiles WERE handed over, this exit means they parsed to no
1248
1338
  // packages at all, which is different news from "no lockfile": a
1249
1339
  // lockfile the tool could not read anything from deserves a look.
@@ -1255,7 +1345,8 @@ function spawnAndRead(ctx) {
1255
1345
  }
1256
1346
  : {
1257
1347
  code: 'conductor/nothing-to-scan',
1258
- message: `${gate.product} found nothing to scan (exit ${exitCode}); treated as clean.`,
1348
+ message: `${gate.product} read no lockfile (exit ${exitCode}), so nothing was scanned; the ` +
1349
+ `verdict is clean because there was nothing to read, not because a scan found nothing.`,
1259
1350
  },
1260
1351
  ],
1261
1352
  };
@@ -1369,13 +1460,108 @@ function spawnAndRead(ctx) {
1369
1460
  online: argv.includes('--online'),
1370
1461
  lockfiles: external.lockfiles ?? [],
1371
1462
  });
1463
+ // The base comparison (osv design, section 3.1): only on a decided trust
1464
+ // base, only when the head run exited blocked and produced a finding. A
1465
+ // clean head, nothing to scan, empty lockfiles and every could-not-run
1466
+ // returned before this, so none of them costs anything new. Its own
1467
+ // try: a comparison that throws labels every finding introduced and is
1468
+ // never a could-not-run, unlike the normalizer failure the catch below
1469
+ // is for.
1470
+ let findings = normalized.findings;
1471
+ let baseComparison;
1472
+ const comparisonDiagnostics = [];
1473
+ if (gate.product === 'osv-scanner' &&
1474
+ decidedRef !== undefined &&
1475
+ workDir !== null &&
1476
+ blocked &&
1477
+ findings.length > 0) {
1478
+ const compareArgs = {
1479
+ repoRoot: options.repoRoot,
1480
+ ref: decidedRef,
1481
+ workDir,
1482
+ policy: gate.presentOnBase ?? 'block',
1483
+ version,
1484
+ headFindings: findings,
1485
+ headLockfiles: external.lockfiles ?? [],
1486
+ closures: selection?.closures ?? new Map(),
1487
+ otherVerdicts: normalized.otherVerdicts ?? [],
1488
+ headArgv: argv,
1489
+ baseArgv: (copies) => [
1490
+ ...binary.argvPrefix,
1491
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: copies }),
1492
+ ],
1493
+ spawn: (baseArgv, cwd) => {
1494
+ const baseChild = spawnSync(binary.command, [...baseArgv], {
1495
+ cwd,
1496
+ encoding: 'utf8',
1497
+ timeout: timeoutMs,
1498
+ maxBuffer: 64 * 1024 * 1024,
1499
+ });
1500
+ return { status: baseChild.status, stdout: baseChild.stdout ?? '', error: baseChild.error };
1501
+ },
1502
+ rootSpellings,
1503
+ };
1504
+ let compared;
1505
+ try {
1506
+ compared = compareWithBase(compareArgs);
1507
+ }
1508
+ catch (err) {
1509
+ compared = comparisonFailed(compareArgs, `the comparison failed (${messageOf(err)})`);
1510
+ }
1511
+ findings = compared.findings;
1512
+ baseComparison = compared.comparison;
1513
+ comparisonDiagnostics.push(...compared.diagnostics);
1514
+ }
1515
+ // A handed lockfile osv-scanner read no packages from, while it read
1516
+ // packages from another (audit finding F2). Exit 128 above covers only
1517
+ // the all-empty case; this is the rest, named on the coverage line and
1518
+ // in a diagnostic, so an emptied lockfile's advisories never vanish
1519
+ // without a word. Annotation only: the verdict is osv-scanner's.
1520
+ const emptied = gate.product === 'osv-scanner'
1521
+ ? emptiedLockfiles(withRun.stderr, external.lockfiles ?? [], spawnCwd)
1522
+ : [];
1523
+ const emptyDiagnostics = emptied.length === 0
1524
+ ? []
1525
+ : [
1526
+ {
1527
+ code: 'conductor/lockfiles-empty',
1528
+ message: `${gate.product} read no packages from ${emptied.join(', ')} while it read packages ` +
1529
+ 'from the other lockfiles, so nothing in the named file(s) was checked. A lockfile ' +
1530
+ 'emptied in this change hides every advisory it carried; look at its diff.',
1531
+ },
1532
+ ];
1533
+ const run = selection === null
1534
+ ? normalized.run
1535
+ : {
1536
+ ...normalized.run,
1537
+ diagnostics: [
1538
+ ...normalized.run.diagnostics,
1539
+ ...selection.notes,
1540
+ ...(unreadNote === null ? [] : [unreadNote]),
1541
+ ],
1542
+ details: {
1543
+ ...normalized.run.details,
1544
+ ...(emptied.length === 0
1545
+ ? {}
1546
+ : { lockfiles: describeLockfiles(external.lockfiles ?? [], new Set(emptied)) }),
1547
+ ...(selection.notScanned.length === 0
1548
+ ? {}
1549
+ : { 'not-scanned': notScannedDetail(selection.notScanned) }),
1550
+ },
1551
+ };
1372
1552
  return {
1373
1553
  ...withRun,
1374
1554
  exitCode,
1375
1555
  couldNotRun: null,
1376
- findings: normalized.findings,
1377
- run: normalized.run,
1378
- diagnostics: normalized.diagnostics,
1556
+ findings,
1557
+ run,
1558
+ diagnostics: [
1559
+ ...normalized.diagnostics,
1560
+ ...selectionDiagnostics,
1561
+ ...emptyDiagnostics,
1562
+ ...comparisonDiagnostics,
1563
+ ],
1564
+ ...(baseComparison === undefined ? {} : { baseComparison }),
1379
1565
  // The gate's own answer about the control inputs, folded onto the
1380
1566
  // decision the umbrella made before spawning it. A gate that was NOT
1381
1567
  // put into pull-request mode reports no proposals, and its trustBase
package/dist/git.d.ts CHANGED
@@ -15,7 +15,22 @@ export declare function useGitProgram(program: string): void;
15
15
  /** Runs one git command in `cwd`, reading stdout as UTF-8. Never throws. */
16
16
  export declare function runGit(cwd: string, args: readonly string[], options?: {
17
17
  maxBuffer?: number;
18
+ input?: string;
18
19
  }): GitResult;
20
+ /**
21
+ * Runs one git command in `cwd` and keeps stdout as BYTES. For a blob that is
22
+ * copied out byte for byte (the osv gate's base copies): decoding it as UTF-8
23
+ * would rewrite a file with invalid bytes before anything read it. Same
24
+ * program, same environment and same never-throws contract as runGit.
25
+ */
26
+ export declare function runGitBytes(cwd: string, args: readonly string[], options?: {
27
+ maxBuffer?: number;
28
+ }): {
29
+ status: number | null;
30
+ stdout: Buffer;
31
+ stderr: string;
32
+ error: Error | undefined;
33
+ };
19
34
  /**
20
35
  * A PATH with every entry that would resolve against the working directory
21
36
  * removed: an empty entry (which means the current directory) and a relative
package/dist/git.js CHANGED
@@ -38,6 +38,7 @@ export function runGit(cwd, args, options = {}) {
38
38
  encoding: 'utf8',
39
39
  maxBuffer: options.maxBuffer ?? 32 * 1024 * 1024,
40
40
  env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' },
41
+ ...(options.input === undefined ? {} : { input: options.input }),
41
42
  });
42
43
  return {
43
44
  status: child.status,
@@ -46,6 +47,25 @@ export function runGit(cwd, args, options = {}) {
46
47
  error: child.error,
47
48
  };
48
49
  }
50
+ /**
51
+ * Runs one git command in `cwd` and keeps stdout as BYTES. For a blob that is
52
+ * copied out byte for byte (the osv gate's base copies): decoding it as UTF-8
53
+ * would rewrite a file with invalid bytes before anything read it. Same
54
+ * program, same environment and same never-throws contract as runGit.
55
+ */
56
+ export function runGitBytes(cwd, args, options = {}) {
57
+ const child = spawnSync(gitProgram, [...args], {
58
+ cwd,
59
+ maxBuffer: options.maxBuffer ?? 64 * 1024 * 1024,
60
+ env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' },
61
+ });
62
+ return {
63
+ status: child.status,
64
+ stdout: Buffer.isBuffer(child.stdout) ? child.stdout : Buffer.alloc(0),
65
+ stderr: Buffer.isBuffer(child.stderr) ? child.stderr.toString('utf8') : '',
66
+ error: child.error,
67
+ };
68
+ }
49
69
  /**
50
70
  * A PATH with every entry that would resolve against the working directory
51
71
  * removed: an empty entry (which means the current directory) and a relative
@@ -112,6 +112,7 @@ export function renderPolicy(detected, frozenContractPath) {
112
112
  // ramp is already climbed and enforcing from the start is what stops a
113
113
  // frozen contract's protected paths from producing findings that never
114
114
  // fail the check (issue #57).
115
+ let unfrozenIntent = false;
115
116
  if (role === 'intent') {
116
117
  if (frozenContractPath !== null) {
117
118
  lines.push(` # A frozen contract already exists at ${frozenContractPath}, so this gate`);
@@ -119,6 +120,7 @@ export function renderPolicy(detected, frozenContractPath) {
119
120
  lines.push(' enforce: true');
120
121
  }
121
122
  else {
123
+ unfrozenIntent = true;
122
124
  lines.push(` # No frozen contract yet (${NATIVE_CONTRACT_PATH}), so this gate runs`);
123
125
  lines.push(' # and reports without failing the run. Once a contract is frozen,');
124
126
  lines.push(' # set this to true by hand: conductor init never rewrites this file');
@@ -129,9 +131,43 @@ export function renderPolicy(detected, frozenContractPath) {
129
131
  else {
130
132
  lines.push(' enforce: true');
131
133
  }
134
+ // Only the vulnerabilities gate compares a pull request with its base.
135
+ // Written as report for a fresh repository, so an existing backlog does
136
+ // not block every pull request from the first one; a parser default of
137
+ // block keeps every policy written before the key existed as strict as
138
+ // it was.
139
+ if (role === 'vulnerabilities') {
140
+ lines.push(' # On a pull request, findings already on the base branch are reported');
141
+ lines.push(' # and do not block; only advisories the pull request introduces do.');
142
+ lines.push(' # Set present-on-base: block to block on every known vulnerability.');
143
+ lines.push(' present-on-base: report');
144
+ }
132
145
  lines.push(' # Handed to this gate unchanged. Keys are its own long flags,');
133
- lines.push(' # without the leading dashes. Example: fail-on: high');
134
- lines.push(' options: {}');
146
+ lines.push(' # without the leading dashes.');
147
+ if (role === 'secrets-history') {
148
+ lines.push(' # gitleaks has no severity floor. Tune its rules in .gitleaks.toml and');
149
+ lines.push(' # accept an old finding in .gitleaksignore, not here.');
150
+ }
151
+ else if (role === 'vulnerabilities') {
152
+ lines.push(' # osv-scanner has no severity floor. Tune what it reports in');
153
+ lines.push(' # osv-scanner.toml, not here.');
154
+ }
155
+ else if (role === 'intent') {
156
+ lines.push(' # require-frozen: false lets the gate run and not block when no contract exists.');
157
+ }
158
+ else {
159
+ lines.push(' # Example: fail-on: high');
160
+ }
161
+ if (unfrozenIntent) {
162
+ // intent-guard blocks on a missing contract when require-frozen is true,
163
+ // its default. Without this key a full run prints a BLOCKING critical
164
+ // finding for the very state the unenforced ramp above exists for.
165
+ lines.push(' options:');
166
+ lines.push(' require-frozen: false');
167
+ }
168
+ else {
169
+ lines.push(' options: {}');
170
+ }
135
171
  }
136
172
  lines.push('', 'report:', ' format: text', '');
137
173
  return lines.join('\n');
@@ -48,6 +48,17 @@ export declare function normalizeIntentGuard(raw: unknown, version: string | nul
48
48
  export declare function normalizeGitleaks(raw: unknown, version: string | null, blocked: boolean): NormalizedGateOutput;
49
49
  /** CVSS base score onto the shared four-level ladder, by the CVSS v3 bands. */
50
50
  export declare function cvssToSeverity(score: number | null): Severity;
51
+ /**
52
+ * The vulnerabilities summary line's lockfile fact (issue #72): the count and
53
+ * names of the lockfiles the UMBRELLA handed osv-scanner with --lockfile,
54
+ * never osv-scanner's own results[], which 2.x prints only for a source with
55
+ * findings. A clean scan of one lockfile and a run that scanned none both
56
+ * have results: [], and only this list tells them apart.
57
+ *
58
+ * A file in `emptied` (osv-scanner read no packages from it, audit finding
59
+ * F2) is marked in place, so the count never reads as that many files read.
60
+ */
61
+ export declare function describeLockfiles(lockfiles: readonly string[], emptied?: ReadonlySet<string>): string;
51
62
  export declare function normalizeOsvScanner(raw: unknown, version: string | null, blocked: boolean,
52
63
  /** The scan root as a path osv-scanner may have printed it, in any spelling. */
53
64
  roots?: readonly string[],
package/dist/normalize.js CHANGED
@@ -943,9 +943,13 @@ function relativeToRoots(file, roots) {
943
943
  * never osv-scanner's own results[], which 2.x prints only for a source with
944
944
  * findings. A clean scan of one lockfile and a run that scanned none both
945
945
  * have results: [], and only this list tells them apart.
946
+ *
947
+ * A file in `emptied` (osv-scanner read no packages from it, audit finding
948
+ * F2) is marked in place, so the count never reads as that many files read.
946
949
  */
947
- function describeLockfiles(lockfiles) {
948
- return lockfiles.length === 0 ? '0' : `${lockfiles.length} (${lockfiles.join(', ')})`;
950
+ export function describeLockfiles(lockfiles, emptied = new Set()) {
951
+ const named = lockfiles.map((file) => (emptied.has(file) ? `${file} [no packages read]` : file));
952
+ return lockfiles.length === 0 ? '0' : `${lockfiles.length} (${named.join(', ')})`;
949
953
  }
950
954
  export function normalizeOsvScanner(raw, version, blocked,
951
955
  /** The scan root as a path osv-scanner may have printed it, in any spelling. */
@@ -956,6 +960,7 @@ lockfiles = []) {
956
960
  const top = needRecord(raw, product, 'the output');
957
961
  const results = needArray(top.results, product, 'results');
958
962
  const findings = [];
963
+ const otherVerdicts = [];
959
964
  for (const [ri, rawResult] of results.entries()) {
960
965
  const resultWhere = `results[${ri}]`;
961
966
  const result = needRecord(rawResult, product, resultWhere);
@@ -969,6 +974,7 @@ lockfiles = []) {
969
974
  const name = needString(pkg.name, product, `${packageWhere}.package.name`);
970
975
  const installed = optionalString(pkg.version, product, `${packageWhere}.package.version`) ?? '';
971
976
  const ecosystem = optionalString(pkg.ecosystem, product, `${packageWhere}.package.ecosystem`);
977
+ otherVerdicts.push(...osvOtherVerdicts(entry, pkg, `${name}@${installed}`));
972
978
  const groups = (entry.groups === undefined ? [] : needArray(entry.groups, product, `${packageWhere}.groups`)).filter(isRecord);
973
979
  const vulns = entry.vulnerabilities === undefined
974
980
  ? []
@@ -1023,8 +1029,54 @@ lockfiles = []) {
1023
1029
  },
1024
1030
  },
1025
1031
  diagnostics: [],
1032
+ otherVerdicts,
1026
1033
  };
1027
1034
  }
1035
+ /**
1036
+ * The package-level keys of an osv-scanner result this normalizer knows:
1037
+ * the package itself, its advisories, their groups, and the licences it was
1038
+ * found to carry. `license_violations` is deliberately NOT here: it is a
1039
+ * verdict (osv-scanner exits 1 for it, measured on 2.4.0 with --licenses).
1040
+ */
1041
+ const OSV_KNOWN_PACKAGE_KEYS = new Set(['package', 'vulnerabilities', 'groups', 'licenses']);
1042
+ function isEmptyValue(value) {
1043
+ if (value === undefined || value === null || value === false || value === '') {
1044
+ return true;
1045
+ }
1046
+ if (Array.isArray(value)) {
1047
+ return value.length === 0;
1048
+ }
1049
+ return isRecord(value) && Object.keys(value).length === 0;
1050
+ }
1051
+ /**
1052
+ * Every verdict on one package that is not an advisory, one line each.
1053
+ *
1054
+ * Two shapes, both measured on osv-scanner 2.4.0. `license_violations` beside
1055
+ * `vulnerabilities` (--licenses), and `package.deprecated: true` INSIDE the
1056
+ * package object (--experimental-flag-deprecated-packages; a deprecated
1057
+ * package with no advisory exits 1 too). Beyond those, any other non-empty
1058
+ * PACKAGE-level key this normalizer does not map counts the same, so a
1059
+ * verdict field a later osv-scanner adds fails closed rather than open.
1060
+ * Top-level keys (license_summary, experimental_config) and result-level ones
1061
+ * (source) are summaries and settings, not verdicts on a package, and are
1062
+ * not read.
1063
+ *
1064
+ * KNOWN GAP: inside the package object only `deprecated` is read. A future
1065
+ * verdict field osv-scanner writes INSIDE `package` (a `yanked` flag, say)
1066
+ * is not seen by the catch-all, which looks at package-level keys only.
1067
+ */
1068
+ function osvOtherVerdicts(entry, pkg, label) {
1069
+ const out = [];
1070
+ for (const [key, value] of Object.entries(entry)) {
1071
+ if (!OSV_KNOWN_PACKAGE_KEYS.has(key) && !isEmptyValue(value)) {
1072
+ out.push(`${key} (${label})`);
1073
+ }
1074
+ }
1075
+ if (!isEmptyValue(pkg.deprecated)) {
1076
+ out.push(`deprecated (${label})`);
1077
+ }
1078
+ return out;
1079
+ }
1028
1080
  function gateProblem(ruleId, role, product, message, details) {
1029
1081
  return {
1030
1082
  schemaVersion: 1,
@@ -0,0 +1,84 @@
1
+ import type { Diagnostic, Finding } from './envelope.js';
2
+ import type { PresentOnBase } from './policy.js';
3
+ export type BaselineLabel = 'introduced' | 'present-on-base';
4
+ /**
5
+ * What the comparison did, carried on the gate's outcome so a report (and the
6
+ * exit-code exception) never needs the policy file to explain itself.
7
+ * Present only when a comparison ran (section 3.1).
8
+ */
9
+ export interface BaseComparison {
10
+ /** The trust base the copies were read from. */
11
+ ref: string;
12
+ /** The base policy's present-on-base value, block when it said nothing. */
13
+ policy: PresentOnBase;
14
+ introduced: number;
15
+ presentOnBase: number;
16
+ /** Lockfiles whose findings all count as introduced because no comparison was possible, with why. */
17
+ unavailable: Array<{
18
+ path: string;
19
+ reason: string;
20
+ }>;
21
+ /**
22
+ * Verdicts in the head run's raw output that are not advisories (licence
23
+ * violations, deprecated packages, any unmapped package-level field). Read
24
+ * by condition (f) of gateExitBlocks.
25
+ */
26
+ otherVerdicts: string[];
27
+ }
28
+ /** The comparison key: advisory id, ecosystem, package, installed version, lockfile path. */
29
+ export declare function comparisonKey(finding: Finding): string | null;
30
+ /**
31
+ * Labels head findings against base findings. Pure, so the comparison can be
32
+ * tested without spawning anything.
33
+ *
34
+ * A finding in a lockfile in `unchanged` (byte-equal to the base, its whole
35
+ * include closure too) is present-on-base without a base scan: identical
36
+ * input, config and database. A finding in a lockfile in `unavailable` is
37
+ * introduced whatever the base said. Otherwise it is present-on-base exactly
38
+ * when a base finding has the same key.
39
+ */
40
+ export declare function labelAgainstBase(head: readonly Finding[], base: readonly Finding[], unavailable: ReadonlySet<string>, unchanged: ReadonlySet<string>): Finding[];
41
+ export interface BaseSpawnResult {
42
+ status: number | null;
43
+ stdout: string;
44
+ error: Error | undefined;
45
+ }
46
+ export interface CompareArgs {
47
+ repoRoot: string;
48
+ ref: string;
49
+ workDir: string;
50
+ policy: PresentOnBase;
51
+ version: string | null;
52
+ headFindings: readonly Finding[];
53
+ /** Every file the head run was handed, repository-relative. */
54
+ headLockfiles: readonly string[];
55
+ /** For each requirements file, the head include closure when the head copy passed the pin check. */
56
+ closures: ReadonlyMap<string, readonly string[] | null>;
57
+ otherVerdicts: readonly string[];
58
+ /** The head run's full argv. */
59
+ headArgv: readonly string[];
60
+ /** The base run's full argv for these absolute copy paths, built by the same gateArgs. */
61
+ baseArgv: (copies: readonly string[]) => string[];
62
+ /** Runs the same binary, with the same timeout, from `cwd`. */
63
+ spawn: (argv: readonly string[], cwd: string) => BaseSpawnResult;
64
+ /** Every spelling of a directory a child could print it in. */
65
+ rootSpellings: (dir: string) => string[];
66
+ }
67
+ export interface CompareResult {
68
+ findings: Finding[];
69
+ comparison: BaseComparison;
70
+ diagnostics: Diagnostic[];
71
+ }
72
+ /**
73
+ * The result when the comparison itself failed in a way compareWithBase did
74
+ * not anticipate: every lockfile with findings is unavailable and every
75
+ * finding is introduced. Never could-not-run.
76
+ */
77
+ export declare function comparisonFailed(args: CompareArgs, reason: string): CompareResult;
78
+ /**
79
+ * Runs the comparison. Assumes the caller has established section 3.1: a
80
+ * decided trust base, a head run that exited blocked, at least one finding.
81
+ * Never throws for anything it anticipated; the caller still wraps it, and
82
+ * any throw becomes "every finding introduced", never could-not-run.
83
+ */
84
+ export declare function compareWithBase(args: CompareArgs): CompareResult;