@vaultcompass/conductor 0.8.0 → 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.
Files changed (44) hide show
  1. package/README.md +263 -77
  2. package/dist/cli.js +152 -30
  3. package/dist/envelope.d.ts +8 -0
  4. package/dist/exit-codes.d.ts +52 -2
  5. package/dist/exit-codes.js +64 -14
  6. package/dist/external-config.d.ts +2 -1
  7. package/dist/external-config.js +33 -18
  8. package/dist/gate-runner.d.ts +141 -17
  9. package/dist/gate-runner.js +537 -83
  10. package/dist/git.d.ts +95 -0
  11. package/dist/git.js +244 -0
  12. package/dist/init-policy.js +38 -2
  13. package/dist/init.js +40 -3
  14. package/dist/intent-base.d.ts +35 -1
  15. package/dist/intent-base.js +124 -64
  16. package/dist/intent-prepare.d.ts +33 -2
  17. package/dist/intent-prepare.js +443 -34
  18. package/dist/intent-spec.d.ts +28 -0
  19. package/dist/intent-spec.js +22 -5
  20. package/dist/normalize.d.ts +11 -0
  21. package/dist/normalize.js +60 -6
  22. package/dist/osv-baseline.d.ts +84 -0
  23. package/dist/osv-baseline.js +325 -0
  24. package/dist/osv-coverage.d.ts +80 -0
  25. package/dist/osv-coverage.js +223 -0
  26. package/dist/output-sarif.js +55 -15
  27. package/dist/output-text.d.ts +53 -2
  28. package/dist/output-text.js +287 -27
  29. package/dist/policy.d.ts +10 -0
  30. package/dist/policy.js +21 -7
  31. package/dist/products.d.ts +32 -10
  32. package/dist/products.js +73 -9
  33. package/dist/requirements-pin.d.ts +47 -0
  34. package/dist/requirements-pin.js +256 -0
  35. package/dist/resolve.d.ts +1 -0
  36. package/dist/resolve.js +1 -1
  37. package/dist/run.d.ts +21 -0
  38. package/dist/run.js +74 -15
  39. package/dist/trust-base.d.ts +101 -20
  40. package/dist/trust-base.js +219 -73
  41. package/dist/unread-manifests.d.ts +14 -0
  42. package/dist/unread-manifests.js +69 -0
  43. package/package.json +1 -1
  44. package/schema/guardrails.schema.json +4 -0
@@ -154,7 +154,7 @@ function exists(repoRoot, relative) {
154
154
  * the failure actually had: "superpowers" beat
155
155
  * "1.2.1-base-and-superpowers" by being shorter and vaguer.
156
156
  */
157
- function bestMatch(names, target) {
157
+ export function bestMatch(names, target) {
158
158
  return names
159
159
  .filter((name) => stemMatches(normalizeStem(name), target))
160
160
  .sort((a, b) => {
@@ -192,7 +192,18 @@ function planFor(repoRoot, specPath) {
192
192
  const specStem = normalizeStem(path.basename(specPath));
193
193
  const matches = markdownFilesIn(repoRoot, PLAN_DIR).filter((name) => normalizeStem(name) === specStem);
194
194
  const newest = matches[matches.length - 1];
195
- return newest === undefined ? null : `${PLAN_DIR}/${newest}`;
195
+ if (newest === undefined) {
196
+ return { plan: null };
197
+ }
198
+ const plan = `${PLAN_DIR}/${newest}`;
199
+ // Held to the repository like the convention spec: a plans directory
200
+ // linked out of the checkout is refused, never read and never dropped.
201
+ return resolvesInsideRoot(repoRoot, plan) ? { plan } : { escaped: plan };
202
+ }
203
+ /** A found spec with its plan, or the refusal for a plan that escapes. */
204
+ function withPlan(repoRoot, kind, spec) {
205
+ const found = planFor(repoRoot, spec);
206
+ return 'escaped' in found ? { kind: 'escaped', path: found.escaped } : { kind, spec, plan: found.plan };
196
207
  }
197
208
  /** Normalizes a user-supplied path to a repository-relative one. */
198
209
  function relativeToRoot(repoRoot, candidate) {
@@ -253,7 +264,7 @@ export function discoverSpec(options) {
253
264
  if (!exists(repoRoot, relative)) {
254
265
  return { kind: 'missing-flag', spec: relative };
255
266
  }
256
- return { kind: 'flag', spec: relative, plan: planFor(repoRoot, relative) };
267
+ return withPlan(repoRoot, 'flag', relative);
257
268
  }
258
269
  if (options.prBody !== undefined) {
259
270
  const named = specFromPrBody(options.prBody);
@@ -274,7 +285,7 @@ export function discoverSpec(options) {
274
285
  // Containment subsumes existence here, since a path that does not
275
286
  // resolve is not contained.
276
287
  if (resolvesInsideRoot(repoRoot, relative)) {
277
- return { kind: 'pr-body', spec: relative, plan: planFor(repoRoot, relative) };
288
+ return withPlan(repoRoot, 'pr-body', relative);
278
289
  }
279
290
  }
280
291
  }
@@ -282,7 +293,13 @@ export function discoverSpec(options) {
282
293
  const best = bestMatch(markdownFilesIn(repoRoot, SPEC_DIR), branchSlug(options.branch));
283
294
  if (best !== undefined) {
284
295
  const relative = `${SPEC_DIR}/${best}`;
285
- return { kind: 'convention', spec: relative, plan: planFor(repoRoot, relative) };
296
+ // The convention spec is held to the repository too: a specs directory
297
+ // linked out of the checkout is refused, never imported. Only --spec is
298
+ // exempt, as a path a person typed.
299
+ if (!resolvesInsideRoot(repoRoot, relative)) {
300
+ return { kind: 'escaped', path: relative };
301
+ }
302
+ return withPlan(repoRoot, 'convention', relative);
286
303
  }
287
304
  }
288
305
  return { kind: 'none' };
@@ -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
@@ -337,10 +337,12 @@ export function normalizeVaultGuard(raw, version) {
337
337
  run: {
338
338
  failOn: threshold,
339
339
  suppressed: typeof run.baseline_suppressed === 'number' ? run.baseline_suppressed : 0,
340
- // vault-guard does not report an ignore count separately; ignored
341
- // files never reach the output at all. Reporting 0 here would claim a
342
- // fact the gate did not state, so the report says "not reported"
343
- // instead, driven by this null.
340
+ // This normalizer reads no ignore count out of vault-guard's run object
341
+ // (which does carry config_ignored_files; it is not mapped here), so 0
342
+ // is a placeholder and not a claim that nothing was ignored. What makes
343
+ // the report say "ignored not reported" is not this number: it is
344
+ // `ignoredReported: false` in `details` below, which output-text.ts and
345
+ // the summary line read in its place.
344
346
  ignored: 0,
345
347
  // vault-guard's diagnostics carry a context object rather than a
346
348
  // message, so the context is rendered as one. Validated the same way
@@ -941,9 +943,13 @@ function relativeToRoots(file, roots) {
941
943
  * never osv-scanner's own results[], which 2.x prints only for a source with
942
944
  * findings. A clean scan of one lockfile and a run that scanned none both
943
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.
944
949
  */
945
- function describeLockfiles(lockfiles) {
946
- 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(', ')})`;
947
953
  }
948
954
  export function normalizeOsvScanner(raw, version, blocked,
949
955
  /** The scan root as a path osv-scanner may have printed it, in any spelling. */
@@ -954,6 +960,7 @@ lockfiles = []) {
954
960
  const top = needRecord(raw, product, 'the output');
955
961
  const results = needArray(top.results, product, 'results');
956
962
  const findings = [];
963
+ const otherVerdicts = [];
957
964
  for (const [ri, rawResult] of results.entries()) {
958
965
  const resultWhere = `results[${ri}]`;
959
966
  const result = needRecord(rawResult, product, resultWhere);
@@ -967,6 +974,7 @@ lockfiles = []) {
967
974
  const name = needString(pkg.name, product, `${packageWhere}.package.name`);
968
975
  const installed = optionalString(pkg.version, product, `${packageWhere}.package.version`) ?? '';
969
976
  const ecosystem = optionalString(pkg.ecosystem, product, `${packageWhere}.package.ecosystem`);
977
+ otherVerdicts.push(...osvOtherVerdicts(entry, pkg, `${name}@${installed}`));
970
978
  const groups = (entry.groups === undefined ? [] : needArray(entry.groups, product, `${packageWhere}.groups`)).filter(isRecord);
971
979
  const vulns = entry.vulnerabilities === undefined
972
980
  ? []
@@ -1021,8 +1029,54 @@ lockfiles = []) {
1021
1029
  },
1022
1030
  },
1023
1031
  diagnostics: [],
1032
+ otherVerdicts,
1024
1033
  };
1025
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
+ }
1026
1080
  function gateProblem(ruleId, role, product, message, details) {
1027
1081
  return {
1028
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;
@@ -0,0 +1,325 @@
1
+ // The vulnerabilities gate's base comparison (osv design, item 1.3, section 3).
2
+ //
3
+ // On a pull-request run whose head scan blocked, osv-scanner is also run on
4
+ // the BASE copies of the lockfiles that carry findings, and each head finding
5
+ // is labelled `introduced` or `present-on-base` by a key that names the
6
+ // advisory, the ecosystem, the package, the installed version and the
7
+ // repository-relative lockfile path. The vulnerabilities gate's own policy
8
+ // key (present-on-base, read from the base policy) then decides whether a
9
+ // present-on-base finding blocks.
10
+ //
11
+ // Every failure here labels toward `introduced`: an unreadable base, a base
12
+ // run that did not finish, output that would not parse, a path that cannot be
13
+ // made relative. The base run never makes the gate could-not-run and never
14
+ // removes a head finding. Nothing the pull request controls can move a
15
+ // finding from introduced to present-on-base except making the head lockfile
16
+ // byte-equal to the base's at the same path, in which case the label is true.
17
+ import { mkdirSync, realpathSync, writeFileSync } from 'node:fs';
18
+ import path from 'node:path';
19
+ import { realPathInside, runGit } from './git.js';
20
+ import { normalizeOsvScanner } from './normalize.js';
21
+ import { ABSENT_ON_BASE, baseReader } from './osv-coverage.js';
22
+ import { osvLockfileKind } from './products.js';
23
+ import { checkRequirementsPins } from './requirements-pin.js';
24
+ import { readFileAtRefBytes, treeEntryAt } from './trust-base.js';
25
+ /** The comparison key: advisory id, ecosystem, package, installed version, lockfile path. */
26
+ export function comparisonKey(finding) {
27
+ if (finding.subject.kind !== 'package') {
28
+ return null;
29
+ }
30
+ const id = finding.ruleId.startsWith('osv-scanner/') ? finding.ruleId.slice('osv-scanner/'.length) : finding.ruleId;
31
+ const ecosystem = typeof finding.details.ecosystem === 'string' ? finding.details.ecosystem : '';
32
+ const version = typeof finding.details.version === 'string' ? finding.details.version : '';
33
+ return JSON.stringify([id, ecosystem, finding.subject.name, version, finding.subject.manifest]);
34
+ }
35
+ /**
36
+ * Labels head findings against base findings. Pure, so the comparison can be
37
+ * tested without spawning anything.
38
+ *
39
+ * A finding in a lockfile in `unchanged` (byte-equal to the base, its whole
40
+ * include closure too) is present-on-base without a base scan: identical
41
+ * input, config and database. A finding in a lockfile in `unavailable` is
42
+ * introduced whatever the base said. Otherwise it is present-on-base exactly
43
+ * when a base finding has the same key.
44
+ */
45
+ export function labelAgainstBase(head, base, unavailable, unchanged) {
46
+ const baseKeys = new Set(base.map(comparisonKey).filter((key) => key !== null));
47
+ return head.map((finding) => {
48
+ const manifest = finding.subject.kind === 'package' ? finding.subject.manifest : null;
49
+ let label = 'introduced';
50
+ if (manifest !== null && !unavailable.has(manifest)) {
51
+ const key = comparisonKey(finding);
52
+ if (unchanged.has(manifest) || (key !== null && baseKeys.has(key))) {
53
+ label = 'present-on-base';
54
+ }
55
+ }
56
+ return { ...finding, details: { ...finding.details, baseline: label } };
57
+ });
58
+ }
59
+ /** The argv with every --lockfile pair removed, for the symmetry check. */
60
+ function withoutLockfiles(argv) {
61
+ const out = [];
62
+ for (let i = 0; i < argv.length; i += 1) {
63
+ if (argv[i] === '--lockfile') {
64
+ i += 1;
65
+ continue;
66
+ }
67
+ out.push(argv[i]);
68
+ }
69
+ return out;
70
+ }
71
+ /** The first token where two argvs differ, for the unavailable note. */
72
+ function firstDifference(a, b) {
73
+ const length = Math.max(a.length, b.length);
74
+ for (let i = 0; i < length; i += 1) {
75
+ if (a[i] !== b[i]) {
76
+ return a[i] ?? b[i] ?? '(end)';
77
+ }
78
+ }
79
+ return '(none)';
80
+ }
81
+ /**
82
+ * Head object ids for files on disk, with filters OFF: a clean filter comes
83
+ * from the head's own .gitattributes, so a filtered id would let the head
84
+ * decide what "equal to the base" means. One git call for all of them. Null
85
+ * when git could not answer, which disables the shortcut and never enables it.
86
+ */
87
+ function headObjectIds(repoRoot, files) {
88
+ if (files.length === 0) {
89
+ return new Map();
90
+ }
91
+ const out = runGit(repoRoot, ['hash-object', '--no-filters', '--stdin-paths'], {
92
+ input: `${files.join('\n')}\n`,
93
+ });
94
+ if (out.error !== undefined || out.status !== 0) {
95
+ return null;
96
+ }
97
+ const ids = out.stdout.split('\n').filter((line) => line !== '');
98
+ if (ids.length !== files.length) {
99
+ return null;
100
+ }
101
+ return new Map(files.map((file, i) => [file, ids[i]]));
102
+ }
103
+ /** Writes one base copy under `dir`, refusing an absolute or climbing path. */
104
+ function placeCopy(dir, file, bytes) {
105
+ const target = path.resolve(dir, file);
106
+ if (path.isAbsolute(file) || !target.startsWith(`${dir}${path.sep}`)) {
107
+ throw new Error(`${file} is not a path inside the repository`);
108
+ }
109
+ mkdirSync(path.dirname(target), { recursive: true });
110
+ writeFileSync(target, bytes);
111
+ return target;
112
+ }
113
+ function unavailableNotes(unavailable) {
114
+ const byReason = new Map();
115
+ for (const entry of unavailable) {
116
+ byReason.set(entry.reason, [...(byReason.get(entry.reason) ?? []), entry.path]);
117
+ }
118
+ return [...byReason].map(([reason, paths]) => ({
119
+ code: 'conductor/base-comparison-unavailable',
120
+ message: `base comparison unavailable for ${paths.join(', ')}: ${reason}; every finding there counts ` +
121
+ 'as introduced.',
122
+ }));
123
+ }
124
+ /**
125
+ * The result when the comparison itself failed in a way compareWithBase did
126
+ * not anticipate: every lockfile with findings is unavailable and every
127
+ * finding is introduced. Never could-not-run.
128
+ */
129
+ export function comparisonFailed(args, reason) {
130
+ const unavailable = [
131
+ ...new Set(args.headFindings
132
+ .map((finding) => (finding.subject.kind === 'package' ? finding.subject.manifest : null))
133
+ .filter((manifest) => manifest !== null)),
134
+ ]
135
+ .sort()
136
+ .map((file) => ({ path: file, reason }));
137
+ const findings = labelAgainstBase(args.headFindings, [], new Set(unavailable.map((u) => u.path)), new Set());
138
+ return {
139
+ findings,
140
+ comparison: {
141
+ ref: args.ref,
142
+ policy: args.policy,
143
+ introduced: findings.length,
144
+ presentOnBase: 0,
145
+ unavailable,
146
+ otherVerdicts: [...args.otherVerdicts],
147
+ },
148
+ diagnostics: unavailableNotes(unavailable),
149
+ };
150
+ }
151
+ /**
152
+ * Runs the comparison. Assumes the caller has established section 3.1: a
153
+ * decided trust base, a head run that exited blocked, at least one finding.
154
+ * Never throws for anything it anticipated; the caller still wraps it, and
155
+ * any throw becomes "every finding introduced", never could-not-run.
156
+ */
157
+ export function compareWithBase(args) {
158
+ const unavailable = [];
159
+ const unchanged = new Set();
160
+ const handed = new Set(args.headLockfiles);
161
+ const withFindings = [
162
+ ...new Set(args.headFindings
163
+ .map((finding) => (finding.subject.kind === 'package' ? finding.subject.manifest : null))
164
+ .filter((manifest) => manifest !== null && handed.has(manifest))),
165
+ ].sort();
166
+ const baseDir = path.join(args.workDir, 'osv-base');
167
+ let baseFindings = [];
168
+ const finish = () => {
169
+ const unavailablePaths = new Set(unavailable.map((entry) => entry.path));
170
+ const labelled = labelAgainstBase(args.headFindings, baseFindings, unavailablePaths, unchanged).map((finding) => args.policy === 'report' && finding.details.baseline === 'present-on-base'
171
+ ? { ...finding, blocking: false }
172
+ : finding);
173
+ const present = labelled.filter((finding) => finding.details.baseline === 'present-on-base').length;
174
+ return {
175
+ findings: labelled,
176
+ comparison: {
177
+ ref: args.ref,
178
+ policy: args.policy,
179
+ introduced: labelled.length - present,
180
+ presentOnBase: present,
181
+ unavailable,
182
+ otherVerdicts: [...args.otherVerdicts],
183
+ },
184
+ diagnostics: unavailableNotes(unavailable),
185
+ };
186
+ };
187
+ // The work directory must be outside the repository, or a base copy would
188
+ // sit inside the tree being judged (a TMPDIR set inside the checkout).
189
+ if (realPathInside(args.repoRoot, args.workDir)) {
190
+ for (const file of withFindings) {
191
+ unavailable.push({
192
+ path: file,
193
+ reason: 'the temporary directory is inside the repository, so no base copy can be kept outside ' +
194
+ 'the tree being judged',
195
+ });
196
+ }
197
+ return finish();
198
+ }
199
+ // 1. The unchanged shortcut: object ids, filters off, the whole closure.
200
+ const closureOf = (file) => osvLockfileKind(path.posix.basename(file)) === 'requirements' ? (args.closures.get(file) ?? null) : [file];
201
+ const shortcutFiles = [
202
+ ...new Set(withFindings.flatMap((file) => closureOf(file) ?? [])),
203
+ ].sort();
204
+ const headIds = headObjectIds(args.repoRoot, shortcutFiles);
205
+ const toCopy = [];
206
+ for (const file of withFindings) {
207
+ const closure = closureOf(file);
208
+ if (closure !== null && headIds !== null) {
209
+ const same = closure.every((member) => {
210
+ const entry = treeEntryAt(args.repoRoot, args.ref, member);
211
+ return (entry.kind === 'entry' &&
212
+ entry.type === 'blob' &&
213
+ (entry.mode === '100644' || entry.mode === '100755') &&
214
+ entry.sha === headIds.get(member));
215
+ });
216
+ if (same) {
217
+ unchanged.add(file);
218
+ continue;
219
+ }
220
+ }
221
+ toCopy.push(file);
222
+ }
223
+ // 2 to 4. Absent, unreadable, or copied byte for byte from the base.
224
+ const copies = [];
225
+ const copied = [];
226
+ for (const file of toCopy) {
227
+ const kind = osvLockfileKind(file);
228
+ if (kind === 'requirements') {
229
+ const bytes = new Map();
230
+ const check = checkRequirementsPins(file, baseReader(args.repoRoot, args.ref, bytes));
231
+ if (check.topMissing === ABSENT_ON_BASE) {
232
+ continue;
233
+ }
234
+ if (!check.pinned) {
235
+ unavailable.push({
236
+ path: file,
237
+ reason: 'its base copy, or a file it includes there, is not pinned with == or cannot be read, so ' +
238
+ 'it cannot be compared',
239
+ });
240
+ continue;
241
+ }
242
+ try {
243
+ for (const member of check.files) {
244
+ placeCopy(baseDir, member, bytes.get(member));
245
+ }
246
+ }
247
+ catch (err) {
248
+ unavailable.push({ path: file, reason: err instanceof Error ? err.message : String(err) });
249
+ continue;
250
+ }
251
+ }
252
+ else {
253
+ const read = readFileAtRefBytes(args.repoRoot, args.ref, file);
254
+ if (read.kind === 'absent') {
255
+ continue;
256
+ }
257
+ if (read.kind === 'error') {
258
+ unavailable.push({ path: file, reason: `the base copy cannot be read (${read.detail})` });
259
+ continue;
260
+ }
261
+ try {
262
+ placeCopy(baseDir, file, read.bytes);
263
+ }
264
+ catch (err) {
265
+ unavailable.push({ path: file, reason: err instanceof Error ? err.message : String(err) });
266
+ continue;
267
+ }
268
+ }
269
+ copies.push(path.join(baseDir, file));
270
+ copied.push(file);
271
+ }
272
+ if (copies.length === 0) {
273
+ return finish();
274
+ }
275
+ const failAll = (reason) => {
276
+ for (const file of copied) {
277
+ unavailable.push({ path: file, reason });
278
+ }
279
+ baseFindings = [];
280
+ return finish();
281
+ };
282
+ // The symmetry check: the base command line is the head's with only the
283
+ // lockfile arguments replaced. Any other difference (a resolution mode, a
284
+ // call-analysis flag, a config) would compare two different scans.
285
+ const baseArgv = args.baseArgv(copies);
286
+ const headRest = withoutLockfiles(args.headArgv);
287
+ const baseRest = withoutLockfiles(baseArgv);
288
+ if (JSON.stringify(headRest) !== JSON.stringify(baseRest)) {
289
+ return failAll(`the base run's command line would differ from the head run's at ${firstDifference(headRest, baseRest)}`);
290
+ }
291
+ const child = args.spawn(baseArgv, baseDir);
292
+ if (child.error !== undefined || child.status === null) {
293
+ return failAll('osv-scanner did not finish on the base copies (it timed out, was killed or could not start)');
294
+ }
295
+ if (child.status === 128) {
296
+ // The copies parsed to no packages: nothing on the base to match.
297
+ baseFindings = [];
298
+ return finish();
299
+ }
300
+ if (child.status !== 0 && child.status !== 1) {
301
+ return failAll(`osv-scanner exited ${child.status} on the base copies`);
302
+ }
303
+ let parsed;
304
+ try {
305
+ parsed = JSON.parse(child.stdout);
306
+ }
307
+ catch {
308
+ return failAll('osv-scanner printed no valid JSON for the base copies');
309
+ }
310
+ try {
311
+ let roots;
312
+ try {
313
+ roots = args.rootSpellings(realpathSync(baseDir));
314
+ }
315
+ catch {
316
+ roots = [];
317
+ }
318
+ roots = [...new Set([...args.rootSpellings(baseDir), ...roots])];
319
+ baseFindings = normalizeOsvScanner(parsed, args.version, child.status === 1, roots, copied).findings;
320
+ }
321
+ catch (err) {
322
+ return failAll(`the base output could not be read (${err instanceof Error ? err.message : String(err)})`);
323
+ }
324
+ return finish();
325
+ }
@@ -0,0 +1,80 @@
1
+ import type { Diagnostic } from './envelope.js';
2
+ import { type IncludeRead } from './requirements-pin.js';
3
+ export interface OsvSelection {
4
+ /** Every file handed over, repository-relative, sorted. */
5
+ handed: string[];
6
+ /** Requirements files left out, in candidate order. */
7
+ notScanned: string[];
8
+ /** The umbrella's own diagnostics: not-scanned and not-pinned. */
9
+ diagnostics: Diagnostic[];
10
+ /** Run notes, one per scanned requirements file: direct requirements only. */
11
+ notes: Diagnostic[];
12
+ /**
13
+ * For each scanned requirements file, the head include closure when the
14
+ * head copy passed the pin check, else null. The unchanged shortcut
15
+ * (section 3.2) compares the whole closure, and a head closure that did
16
+ * not pass is never taken as complete.
17
+ */
18
+ closures: Map<string, string[] | null>;
19
+ }
20
+ /**
21
+ * A reader over the head: a TRACKED regular file on disk. On disk because
22
+ * that is the copy osv-scanner reads; tracked because an untracked file is
23
+ * not part of what is being judged.
24
+ */
25
+ export declare function headReader(repoRoot: string, tracked: ReadonlySet<string>): (file: string) => IncludeRead;
26
+ /** Why a base reader found nothing: the base tree has no such path. */
27
+ export declare const ABSENT_ON_BASE = "does not exist on the base";
28
+ /**
29
+ * A reader over the trust base, through the one reader (readFileAtRef's byte
30
+ * variant). Every byte it hands out is kept in `bytes`, so a base copy that is
31
+ * written out later is exactly the blob that was checked, never a re-read.
32
+ */
33
+ export declare function baseReader(repoRoot: string, ref: string, bytes?: Map<string, Buffer>): (file: string) => IncludeRead;
34
+ /**
35
+ * Picks what osv-scanner is handed from the tracked files.
36
+ *
37
+ * `decidedRef` is the trust base on a pull-request run, and switches the
38
+ * ratchet on (section 2.3): a requirements file whose head copy fails the pin
39
+ * check is still handed over when its base copy, and the base include
40
+ * closure, passes. A base copy that exists and cannot be read is handed over
41
+ * too: leaving it out would let an unreadable base drop a file from the scan,
42
+ * which is the direction this gate does not fail in.
43
+ */
44
+ export declare function selectOsvInputs(args: {
45
+ repoRoot: string;
46
+ tracked: readonly string[];
47
+ decidedRef?: string;
48
+ }): OsvSelection;
49
+ /**
50
+ * Notes for every basename-matched file tracked on the base and absent from
51
+ * the head (section 3.2): deleted, moved, or renamed to a name the matcher
52
+ * does not take. Such a file is not scanned on either side, and saying so is
53
+ * all this does: it never blocks. A base listing git could not make yields no
54
+ * note rather than a guess.
55
+ */
56
+ export declare function noLongerScanned(repoRoot: string, ref: string, tracked: ReadonlySet<string>): Diagnostic[];
57
+ /** The nothing-to-scan sentence when every candidate was a requirements file left out. */
58
+ export declare function nothingScannableMessage(notScanned: readonly string[]): string;
59
+ /** The run detail beside `lockfiles`: how many requirements files were left out, and which. */
60
+ export declare function notScannedDetail(notScanned: readonly string[]): string;
61
+ /**
62
+ * The handed lockfiles osv-scanner said it found 0 packages in (audit
63
+ * finding F2). Its exit 128 covers only the case where EVERY handed file
64
+ * parsed to nothing, and its JSON lists only sources with findings, so a
65
+ * lockfile rewritten to `{}` beside a healthy one is otherwise
66
+ * indistinguishable from a clean one: listed as scanned, with every advisory
67
+ * it carried gone.
68
+ *
69
+ * Read from osv-scanner's stderr, which is annotation, never a verdict: this
70
+ * only adds a note. `handed` are the repository-relative paths the umbrella
71
+ * passed (the parse-as prefix is not part of them), and `cwd` is where the
72
+ * child ran. A path is compared in its written and its resolved spelling on
73
+ * both sides, so a temp directory reached through a symlink still matches,
74
+ * and by whole path, so two files with one base name never stand in for each
75
+ * other. A file with no count line is not named: that is a limit (a policy
76
+ * that lowers osv-scanner's verbosity hides every line), not a finding.
77
+ */
78
+ export declare function emptiedLockfiles(stderr: string, handed: readonly string[], cwd: string): string[];
79
+ /** The note when a policy's no-resolve was dropped from an invocation. */
80
+ export declare const NO_RESOLVE_OVERRIDDEN: string;