@vaultcompass/conductor 0.8.1 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/policy.js CHANGED
@@ -107,6 +107,17 @@ export const PRODUCT_FOR_ROLE = {
107
107
  * depend on that CLI's argument parser rather than on anything the user
108
108
  * could read in their own policy file.
109
109
  */
110
+ //
111
+ // Two keys are reserved for a different reason: they name conductor's OWN
112
+ // setting, written in the wrong place. `timeout-seconds` is the gate-level
113
+ // time limit, beside `enforce`; no tool has a --timeout-seconds flag, so the
114
+ // only way to write it under options is to mean conductor's key. `timeout`
115
+ // is reserved on the four tools that have no --timeout flag (each rejects
116
+ // it, so no working policy can contain it), and NOT on gitleaks, whose
117
+ // --timeout is its own deadline and works: reserving it there would refuse
118
+ // policies that pass it today. Neither reservation is a trust control: they
119
+ // match exact option keys only, and on a pull request only the base policy is
120
+ // read anyway.
110
121
  export const RESERVED_OPTIONS = {
111
122
  // `trust-base` is reserved for all three products, and the umbrella now
112
123
  // writes it for all three. It was reserved here before dep-guard's own
@@ -115,8 +126,8 @@ export const RESERVED_OPTIONS = {
115
126
  // have broken repositories on an upgrade nobody asked for. The flag it
116
127
  // names is the one that decides where a gate reads its rules from, which
117
128
  // is the last place to leave a window open.
118
- 'dep-guard': ['format', 'staged', 'base', 'trust-base'],
119
- 'vault-guard': ['format', 'f', 'staged', 'trust-base'],
129
+ 'dep-guard': ['format', 'staged', 'base', 'trust-base', 'timeout-seconds', 'timeout'],
130
+ 'vault-guard': ['format', 'f', 'staged', 'trust-base', 'timeout-seconds', 'timeout'],
120
131
  // `base` is reserved even though the umbrella never passes it to this gate,
121
132
  // and that is the point. The umbrella works the changed-path set out itself
122
133
  // and hands over `--paths`, because `--project` may be a temporary
@@ -132,7 +143,7 @@ export const RESERVED_OPTIONS = {
132
143
  // out. It is also the one flag where two writers would be a security
133
144
  // problem rather than a confusion, since the loser decides where the gate
134
145
  // reads its rules from.
135
- 'intent-guard': ['json', 'staged', 'project', 'paths', 'base', 'trust-base'],
146
+ 'intent-guard': ['json', 'staged', 'project', 'paths', 'base', 'trust-base', 'timeout-seconds', 'timeout'],
136
147
  // The umbrella writes every one of these for gitleaks: the report goes to a
137
148
  // file it owns, the exit code for a leak is moved off 1 so an error and a
138
149
  // leak stop sharing a number, history is scoped by --log-opts so one
@@ -149,12 +160,16 @@ export const RESERVED_OPTIONS = {
149
160
  'redact',
150
161
  'no-banner',
151
162
  'log-level',
163
+ // Conductor's own setting; `timeout` stays a passthrough here (see above).
164
+ 'timeout-seconds',
152
165
  ],
153
166
  // osv-scanner: the umbrella owns the format (json to stdout), the config on
154
167
  // a pull-request run, and which lockfiles are scanned (every tracked one,
155
168
  // by name; there is no directory walk and so no --recursive).
156
- 'osv-scanner': ['format', 'config', 'lockfile'],
169
+ 'osv-scanner': ['format', 'config', 'lockfile', 'timeout-seconds', 'timeout'],
157
170
  };
171
+ /** The keys reserved under options because they name conductor's own time limit. */
172
+ const CONDUCTOR_SETTING_KEYS = new Set(['timeout-seconds', 'timeout']);
158
173
  export class PolicyError extends Error {
159
174
  constructor(message) {
160
175
  super(message);
@@ -205,7 +220,14 @@ function describeErrors(errors, source) {
205
220
  * runs and the general sentence would send somebody looking for a flag that
206
221
  * is not on the command line of the run they are debugging.
207
222
  */
208
- function reservedReason(product, key) {
223
+ function reservedReason(product, role, key) {
224
+ if (CONDUCTOR_SETTING_KEYS.has(key)) {
225
+ return key === 'timeout-seconds'
226
+ ? "timeout-seconds is conductor's own limit for this gate. Set it beside enforce, as " +
227
+ `gates.${role}.timeout-seconds, not under options.`
228
+ : "This gate has no --timeout flag; conductor's own limit is " +
229
+ `gates.${role}.timeout-seconds, beside enforce.`;
230
+ }
209
231
  if (key === 'trust-base') {
210
232
  return ('That flag says where a gate reads its rules from, and on a pull-request run the umbrella ' +
211
233
  'writes it itself, pointing at the base ref it read its own policy from. A value here ' +
@@ -312,9 +334,18 @@ export function parsePolicy(text, source) {
312
334
  for (const key of Object.keys(options)) {
313
335
  if (RESERVED_OPTIONS[product].includes(key)) {
314
336
  throw new PolicyError(`${source}: "${key}" under gates.${role}.options is reserved. ` +
315
- reservedReason(product, key));
337
+ reservedReason(product, role, key));
316
338
  }
317
339
  }
340
+ // Only the vulnerabilities gate has a base comparison to apply the key to.
341
+ // On another gate it would read as a promise nothing keeps, so it is
342
+ // refused rather than ignored.
343
+ const presentOnBase = entry['present-on-base'];
344
+ if (presentOnBase !== undefined && role !== 'vulnerabilities') {
345
+ throw new PolicyError(`${source}: gates.${role}.present-on-base is set, but only the vulnerabilities gate ` +
346
+ '(osv-scanner) compares a pull request with its base, so the key has nothing to decide ' +
347
+ `on the ${role} gate. Remove it there.`);
348
+ }
318
349
  const command = entry.command;
319
350
  if (command !== undefined && !path.isAbsolute(command)) {
320
351
  throw new PolicyError(`${source}: gates.${role}.command must be an absolute path, got "${command}". ` +
@@ -338,6 +369,14 @@ export function parsePolicy(text, source) {
338
369
  ...(command === undefined ? {} : { command }),
339
370
  ...(entry.args === undefined ? {} : { args: entry.args }),
340
371
  options,
372
+ // Absent means block: a policy written before the key existed blocks
373
+ // on every known vulnerability, so no policy is loosened by an upgrade.
374
+ ...(role === 'vulnerabilities' ? { presentOnBase: presentOnBase ?? 'block' } : {}),
375
+ // Only when the key is present: an absent key is the profile default,
376
+ // decided in resolveTimeLimit, never a value frozen in here.
377
+ ...(entry['timeout-seconds'] === undefined
378
+ ? {}
379
+ : { timeoutSeconds: entry['timeout-seconds'] }),
341
380
  };
342
381
  }
343
382
  return {
@@ -1,4 +1,4 @@
1
- import type { Product } from './policy.js';
1
+ import type { GateRole, Product } from './policy.js';
2
2
  export type OutputSource = {
3
3
  kind: 'stdout';
4
4
  } | {
@@ -27,7 +27,14 @@ export interface ProductProfile {
27
27
  versionProbe: VersionProbeSpec | null;
28
28
  output: OutputSource;
29
29
  exit: ExitSemantics;
30
+ /** The time limit when the policy sets no timeout-seconds for this gate. */
30
31
  timeoutMs: number;
32
+ /**
33
+ * What to do about a gate stopped at its limit: the sentence the timed-out
34
+ * detail carries. Never a bounded history window or a default size cap,
35
+ * which would narrow coverage without anybody deciding to.
36
+ */
37
+ timeoutRemedies: (role: GateRole) => string;
31
38
  /** Oldest version whose command line this runner speaks; null means any. */
32
39
  minVersion: string | null;
33
40
  /** Config file the tool auto-loads from the scanned tree; read from the base ref on a pull request. */
@@ -56,11 +63,13 @@ export interface ProductProfile {
56
63
  */
57
64
  stderrError: RegExp | null;
58
65
  /**
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.
66
+ * Which tracked files the tool is handed one by one, by base name, instead
67
+ * of being pointed at a directory to walk, and how: `bare` as the path
68
+ * itself, `requirements` as a pip requirements file that must first pass
69
+ * the pin check (src/requirements-pin.ts). Null for a tool that is not
70
+ * handed files.
62
71
  */
63
- lockfileNames: readonly string[] | null;
72
+ lockfileMatcher: ((file: string) => LockfileKind | null) | null;
64
73
  /**
65
74
  * The config can name another file (`[extend] path`) that the tool reads
66
75
  * relative to its working directory. On a pull request every such file is
@@ -84,20 +93,40 @@ export interface ProductProfile {
84
93
  */
85
94
  readsHistory: boolean;
86
95
  }
96
+ /** How a matched file is handed over: as its own path, or as a requirements file. */
97
+ export type LockfileKind = 'bare' | 'requirements';
87
98
  /**
88
- * The lockfiles osv-scanner is handed, matched by base name at any depth
89
- * among the repository's TRACKED files (`git ls-files`).
99
+ * The lockfiles osv-scanner is handed as a bare path, matched by base name at
100
+ * any depth among the repository's TRACKED files (`git ls-files`).
90
101
  *
91
102
  * By name, not by walking the tree, for three reasons: osv-scanner's own walk
92
103
  * skips anything .gitignore matches, tracked or not, so a pull request could
93
104
  * hide a committed lockfile from it with one ignore line; the walk can reach
94
105
  * 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.
106
+ * judged.
107
+ *
108
+ * Every name here was handed to osv-scanner 2.4.0 with --lockfile and read
109
+ * (the 2026-10-11 osv design under docs/superpowers/specs, section 2.1). go.sum is deliberately absent: 2.4.0
110
+ * rejects it ("could not determine extractor", exit 127), which would make
111
+ * every Go pull request could-not-run, and go.mod is what it reads for Go.
112
+ *
113
+ * The second group was added on 2026-10-13 (audit finding F3: a tracked
114
+ * mix.lock was neither scanned nor named), each measured the same way
115
+ * against 2.4.0 and read with one or more packages. Measured and NOT added,
116
+ * because 2.4.0 exits 127 on them: Podfile.lock and deno.lock (both are
117
+ * named by the unread-manifests note instead). gradle's
118
+ * verification-metadata.xml is read only inside a `gradle` directory and is
119
+ * matched by `osvLockfileKind` rather than listed here.
99
120
  */
100
121
  export declare const OSV_LOCKFILE_NAMES: readonly string[];
122
+ /**
123
+ * What osv-scanner is handed for a tracked file, or null. Takes the
124
+ * repository-relative path (a bare base name works for every name but one):
125
+ * gradle's verification-metadata.xml is read by osv-scanner 2.4.0 only when
126
+ * its parent directory is `gradle`, and anywhere else it exits 127, so the
127
+ * parent is part of the match for that one file.
128
+ */
129
+ export declare function osvLockfileKind(file: string): LockfileKind | null;
101
130
  /**
102
131
  * The npm gates print a bare version. No capture group on purpose: the runner
103
132
  * has always reported the whole first line minus a leading v, prerelease
package/dist/products.js CHANGED
@@ -7,18 +7,33 @@
7
7
  // consults it. The three npm profiles below restate exactly what the runner
8
8
  // did before profiles existed; changing one of them changes a gate that
9
9
  // adopters already run.
10
+ /** The first half of every timed-out remedy: where the limit is raised. */
11
+ function raiseTheLimit(role) {
12
+ return (`Raise the limit with gates.${role}.timeout-seconds in .guardrails.yaml (on a pull request, on ` +
13
+ 'the base branch).');
14
+ }
10
15
  /**
11
- * The lockfiles osv-scanner is handed, matched by base name at any depth
12
- * among the repository's TRACKED files (`git ls-files`).
16
+ * The lockfiles osv-scanner is handed as a bare path, matched by base name at
17
+ * any depth among the repository's TRACKED files (`git ls-files`).
13
18
  *
14
19
  * By name, not by walking the tree, for three reasons: osv-scanner's own walk
15
20
  * skips anything .gitignore matches, tracked or not, so a pull request could
16
21
  * hide a committed lockfile from it with one ignore line; the walk can reach
17
22
  * 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.
23
+ * judged.
24
+ *
25
+ * Every name here was handed to osv-scanner 2.4.0 with --lockfile and read
26
+ * (the 2026-10-11 osv design under docs/superpowers/specs, section 2.1). go.sum is deliberately absent: 2.4.0
27
+ * rejects it ("could not determine extractor", exit 127), which would make
28
+ * every Go pull request could-not-run, and go.mod is what it reads for Go.
29
+ *
30
+ * The second group was added on 2026-10-13 (audit finding F3: a tracked
31
+ * mix.lock was neither scanned nor named), each measured the same way
32
+ * against 2.4.0 and read with one or more packages. Measured and NOT added,
33
+ * because 2.4.0 exits 127 on them: Podfile.lock and deno.lock (both are
34
+ * named by the unread-manifests note instead). gradle's
35
+ * verification-metadata.xml is read only inside a `gradle` directory and is
36
+ * matched by `osvLockfileKind` rather than listed here.
22
37
  */
23
38
  export const OSV_LOCKFILE_NAMES = [
24
39
  'package-lock.json',
@@ -26,7 +41,61 @@ export const OSV_LOCKFILE_NAMES = [
26
41
  'pnpm-lock.yaml',
27
42
  'yarn.lock',
28
43
  'bun.lock',
44
+ 'go.mod',
45
+ 'poetry.lock',
46
+ 'Pipfile.lock',
47
+ 'uv.lock',
48
+ 'pdm.lock',
49
+ 'Cargo.lock',
50
+ 'Gemfile.lock',
51
+ 'composer.lock',
52
+ 'gradle.lockfile',
53
+ 'packages.lock.json',
54
+ 'mix.lock',
55
+ 'pubspec.lock',
56
+ 'Package.resolved',
57
+ 'conan.lock',
58
+ 'renv.lock',
59
+ 'packages.config',
60
+ 'buildscript-gradle.lockfile',
61
+ 'gems.locked',
62
+ 'pylock.toml',
63
+ 'cabal.project.freeze',
64
+ 'stack.yaml.lock',
29
65
  ];
66
+ /** gradle's dependency verification file, which 2.4.0 reads only under a `gradle` directory. */
67
+ const GRADLE_VERIFICATION_METADATA = 'verification-metadata.xml';
68
+ /**
69
+ * pip requirements files, by base name: requirements.txt itself,
70
+ * requirements-dev.txt and its _ and . spellings, and dev-requirements.txt.
71
+ * Not requirements.in (pip-tools input, unpinned by design), not constraints
72
+ * files, and not a file under a requirements/ directory whose own name does
73
+ * not match. A requirements file is handed over only when every requirement
74
+ * in it, and in every file it includes, is pinned with == (the pin check).
75
+ */
76
+ const REQUIREMENTS_PATTERNS = [
77
+ /^requirements\.txt$/,
78
+ /^requirements[-_.][A-Za-z0-9._-]+\.txt$/,
79
+ /^[A-Za-z0-9._-]+[-_]requirements\.txt$/,
80
+ ];
81
+ /**
82
+ * What osv-scanner is handed for a tracked file, or null. Takes the
83
+ * repository-relative path (a bare base name works for every name but one):
84
+ * gradle's verification-metadata.xml is read by osv-scanner 2.4.0 only when
85
+ * its parent directory is `gradle`, and anywhere else it exits 127, so the
86
+ * parent is part of the match for that one file.
87
+ */
88
+ export function osvLockfileKind(file) {
89
+ const segments = file.split('/');
90
+ const basename = segments[segments.length - 1] ?? '';
91
+ if (basename === GRADLE_VERIFICATION_METADATA) {
92
+ return segments[segments.length - 2] === 'gradle' ? 'bare' : null;
93
+ }
94
+ if (OSV_LOCKFILE_NAMES.includes(basename)) {
95
+ return 'bare';
96
+ }
97
+ return REQUIREMENTS_PATTERNS.some((pattern) => pattern.test(basename)) ? 'requirements' : null;
98
+ }
30
99
  /**
31
100
  * The npm gates print a bare version. No capture group on purpose: the runner
32
101
  * has always reported the whole first line minus a leading v, prerelease
@@ -49,13 +118,15 @@ function managedProfile(product) {
49
118
  output: { kind: 'stdout' },
50
119
  exit: NPM_EXIT,
51
120
  timeoutMs: 120_000,
121
+ timeoutRemedies: (role) => `${raiseTheLimit(role)} A family gate that needs more than two minutes is unusual, so the ` +
122
+ "gate's own output below is worth reading first.",
52
123
  minVersion: null,
53
124
  configFile: null,
54
125
  neutralConfig: null,
55
126
  ignoreFile: null,
56
127
  remedy: managedRemedy(product),
57
128
  stderrError: null,
58
- lockfileNames: null,
129
+ lockfileMatcher: null,
59
130
  followsConfigExtend: false,
60
131
  readsHistory: false,
61
132
  };
@@ -76,7 +147,12 @@ const PROFILES = {
76
147
  exit: { clean: [0], blocked: [3], nothingToScan: [] },
77
148
  // A full-history scan on a large repository outlives the npm gates' two
78
149
  // minutes; could-not-run on every pull request is the failure to avoid.
150
+ // This is the default when the policy sets no timeout-seconds.
79
151
  timeoutMs: 600_000,
152
+ timeoutRemedies: (role) => `${raiseTheLimit(role)} A history scan grows with the repository's history and the size of ` +
153
+ 'what was committed: scan full history on a schedule and let pull requests scan only their ' +
154
+ 'own range, or pass max-target-megabytes under options, which skips every file larger than ' +
155
+ 'the cap without saying which, so a secret in such a file is not found.',
80
156
  minVersion: '8.19.0',
81
157
  configFile: '.gitleaks.toml',
82
158
  neutralConfig: '[extend]\nuseDefault = true\n',
@@ -93,7 +169,7 @@ const PROFILES = {
93
169
  // gitleaks 8.30.1 swallows a git failure: it logs "<time> ERR [git]
94
170
  // fatal: ..." and exits 0 with an empty report (tests/fixtures/README.md).
95
171
  stderrError: /^\S+\s+ERR\s/,
96
- lockfileNames: null,
172
+ lockfileMatcher: null,
97
173
  followsConfigExtend: true,
98
174
  // gitleaks reads git history (--log-opts), never the tree, which is
99
175
  // exactly what makes it the one gate an equal-tree pull request does not
@@ -111,6 +187,8 @@ const PROFILES = {
111
187
  // lockfile has nothing to scan, which is clean, not an error.
112
188
  exit: { clean: [0], blocked: [1], nothingToScan: [128] },
113
189
  timeoutMs: 300_000,
190
+ timeoutRemedies: (role) => `${raiseTheLimit(role)} osv-scanner queries osv.dev over the network, so a slow or ` +
191
+ 'unreachable service shows up as a timeout too.',
114
192
  minVersion: '2.0.0',
115
193
  configFile: 'osv-scanner.toml',
116
194
  neutralConfig: '',
@@ -120,7 +198,7 @@ const PROFILES = {
120
198
  // osv-scanner's exit codes separate an error (127) from a verdict, and
121
199
  // its stderr is progress chatter, so the exit is taken at its word.
122
200
  stderrError: null,
123
- lockfileNames: OSV_LOCKFILE_NAMES,
201
+ lockfileMatcher: osvLockfileKind,
124
202
  followsConfigExtend: false,
125
203
  // osv-scanner reads the tracked lockfiles it is handed, which are the
126
204
  // 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;
@@ -0,0 +1,256 @@
1
+ // The pin check for pip requirements files.
2
+ //
3
+ // osv-scanner reads a requirements file as a list of packages at the versions
4
+ // written in it. A line pinned with == names one version, and an advisory
5
+ // against that version is a statement about what this repository installs.
6
+ // Any other line (>=, ~=, a range, no version at all) names a set of versions,
7
+ // and whatever osv-scanner reports for it is a guess: with its default
8
+ // resolution it is the registry's latest, with --no-resolve it is the lower
9
+ // bound. So a requirements file is handed over only when every requirement in
10
+ // it, and in every file it includes with -r, is pinned with ==.
11
+ //
12
+ // This SELECTS what the tool is handed, like the basename list beside it in
13
+ // src/products.ts, and raises no finding of its own: a file left out is named
14
+ // on the coverage line with the line that stopped it (src/gate-runner.ts).
15
+ //
16
+ // Includes are followed here rather than left to osv-scanner, because
17
+ // osv-scanner 2.4.0 follows -r and swallows a missing include (one stderr
18
+ // line, the rest scanned, exit decided by what it did read): a top file whose
19
+ // include is absent would be scanned and silently under-read. It resolves an
20
+ // include relative to the including file's directory and survives a cycle,
21
+ // and so does this.
22
+ import path from 'node:path';
23
+ /** The deepest include chain followed. A deeper one leaves the top file unscanned. */
24
+ export const MAX_INCLUDE_DEPTH = 8;
25
+ /** Options that take a value and say nothing about which packages are installed. */
26
+ const IGNORED_WITH_VALUE = [
27
+ '-c',
28
+ '--constraint',
29
+ '-i',
30
+ '--index-url',
31
+ '--extra-index-url',
32
+ '-f',
33
+ '--find-links',
34
+ '--trusted-host',
35
+ '--only-binary',
36
+ '--no-binary',
37
+ '--use-feature',
38
+ ];
39
+ /** Flags with no value that say nothing about which packages are installed. */
40
+ const IGNORED_FLAGS = ['--pre', '--prefer-binary', '--require-hashes'];
41
+ const NAME = '[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?';
42
+ const EXTRAS = '\\[[^\\]]*\\]';
43
+ const REQUIREMENT = new RegExp(`^(${NAME})\\s*(${EXTRAS})?\\s*(.*)$`);
44
+ const NAME_AT_URL = new RegExp(`^${NAME}\\s*(${EXTRAS})?\\s*@\\s*\\S`);
45
+ const URL = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
46
+ const HASH_OPTION = /\s+--hash(?:=|\s+)\S+/g;
47
+ function logicalLines(text) {
48
+ const physical = text.split(/\r?\n/);
49
+ const out = [];
50
+ let buffer = null;
51
+ let start = 0;
52
+ const flush = () => {
53
+ if (buffer === null) {
54
+ return;
55
+ }
56
+ // A # that starts the line or follows whitespace starts a comment; one
57
+ // inside a token (a URL fragment, #egg=) does not.
58
+ const stripped = buffer.replace(/(^|\s)#.*$/, '').trim();
59
+ if (stripped !== '') {
60
+ out.push({ line: start, text: stripped });
61
+ }
62
+ buffer = null;
63
+ };
64
+ for (const [index, raw] of physical.entries()) {
65
+ if (buffer === null) {
66
+ buffer = '';
67
+ start = index + 1;
68
+ }
69
+ if (raw.endsWith('\\')) {
70
+ buffer += `${raw.slice(0, -1)} `;
71
+ continue;
72
+ }
73
+ buffer += raw;
74
+ flush();
75
+ }
76
+ flush();
77
+ return out;
78
+ }
79
+ /** Splits a leading option into its name and value: "-rfoo", "-r foo", "--x=foo", "--x foo". */
80
+ function option(text) {
81
+ const long = /^(--[A-Za-z0-9-]+)(?:=|\s+|$)(.*)$/.exec(text);
82
+ if (long !== null) {
83
+ return { name: long[1], value: long[2].trim() };
84
+ }
85
+ const short = /^(-[A-Za-z])\s*(.*)$/.exec(text);
86
+ if (short !== null) {
87
+ return { name: short[1], value: short[2].trim() };
88
+ }
89
+ return null;
90
+ }
91
+ /** Printable, one line, no double quotes, capped: the line goes into a report. */
92
+ function printable(text) {
93
+ const flat = text.replace(/[^\x20-\x7e]/g, '?').replace(/"/g, "'");
94
+ return flat.length > 120 ? `${flat.slice(0, 117)}...` : flat;
95
+ }
96
+ function isDirectReference(text) {
97
+ if (URL.test(text) || NAME_AT_URL.test(text)) {
98
+ return true;
99
+ }
100
+ // A local path: anything that starts like one or has a path separator in
101
+ // the part before a version specifier, or names an archive.
102
+ const head = text.split(/[\s;=<>!~]/)[0] ?? '';
103
+ return (head.startsWith('.') ||
104
+ head.startsWith('/') ||
105
+ head.startsWith('~') ||
106
+ head.includes('/') ||
107
+ head.includes('\\') ||
108
+ /\.(whl|zip|tar\.gz|tgz|tar\.bz2)$/i.test(head));
109
+ }
110
+ function classify(text) {
111
+ if (text.startsWith('-')) {
112
+ const opt = option(text);
113
+ if (opt === null) {
114
+ return { kind: 'unrecognised' };
115
+ }
116
+ if (opt.name === '-r' || opt.name === '--requirement') {
117
+ return opt.value === '' ? { kind: 'unrecognised' } : { kind: 'include', target: opt.value };
118
+ }
119
+ if (opt.name === '-e' || opt.name === '--editable') {
120
+ return { kind: 'excluded' };
121
+ }
122
+ if (IGNORED_WITH_VALUE.includes(opt.name) && opt.value !== '') {
123
+ return { kind: 'ignored' };
124
+ }
125
+ if (IGNORED_FLAGS.includes(opt.name) && opt.value === '') {
126
+ return { kind: 'ignored' };
127
+ }
128
+ return { kind: 'unrecognised' };
129
+ }
130
+ if (isDirectReference(text)) {
131
+ return { kind: 'excluded' };
132
+ }
133
+ // Hash options may follow a requirement; nothing else may.
134
+ const withoutHashes = text.replace(HASH_OPTION, '');
135
+ const [spec = '', ...marker] = withoutHashes.split(';');
136
+ if (marker.join(';').includes(' --') || /\s--?[A-Za-z]/.test(spec)) {
137
+ return { kind: 'unrecognised' };
138
+ }
139
+ const match = REQUIREMENT.exec(spec.trim());
140
+ if (match === null) {
141
+ return { kind: 'unrecognised' };
142
+ }
143
+ const specifier = match[3].trim();
144
+ if (specifier.startsWith('===')) {
145
+ return { kind: 'arbitrary-equality' };
146
+ }
147
+ if (/^==\s*[^\s,=<>!~*$;]+$/.test(specifier)) {
148
+ return { kind: 'pinned' };
149
+ }
150
+ if (specifier === '' || /^[=<>!~]/.test(specifier)) {
151
+ return { kind: 'unpinned' };
152
+ }
153
+ return { kind: 'unrecognised' };
154
+ }
155
+ /**
156
+ * Checks one requirements file and everything it includes.
157
+ *
158
+ * `read` is asked for each file by repository-relative path and decides what
159
+ * "there" means: on the head, a tracked regular file on disk; on the base,
160
+ * the blob at the trust base. Every problem is collected, not only the first,
161
+ * so the ratchet's diagnostic can name each unpinned line; `pinned` is true
162
+ * only when there are none.
163
+ */
164
+ export function checkRequirementsPins(top, read) {
165
+ const files = [];
166
+ const problems = [];
167
+ let excluded = 0;
168
+ let topMissing = null;
169
+ const visited = new Set();
170
+ const visit = (file, depth, from, written) => {
171
+ if (visited.has(file)) {
172
+ return;
173
+ }
174
+ if (depth > MAX_INCLUDE_DEPTH) {
175
+ problems.push({
176
+ file: from ?? file,
177
+ line: null,
178
+ text: written,
179
+ kind: 'include',
180
+ why: `more than ${MAX_INCLUDE_DEPTH} includes deep`,
181
+ });
182
+ return;
183
+ }
184
+ visited.add(file);
185
+ const got = read(file);
186
+ if (got.kind === 'missing') {
187
+ // For the top file itself the sentence would read "includes
188
+ // requirements.txt, which ...", which no caller prints: the head copy
189
+ // is a tracked file, and callers of a base check read topMissing.
190
+ if (from === null) {
191
+ topMissing = got.why;
192
+ }
193
+ problems.push({ file: from ?? file, line: null, text: written, kind: 'include', why: `which ${got.why}` });
194
+ return;
195
+ }
196
+ files.push(file);
197
+ for (const logical of logicalLines(got.text)) {
198
+ const verdict = classify(logical.text);
199
+ switch (verdict.kind) {
200
+ case 'pinned':
201
+ case 'ignored':
202
+ break;
203
+ case 'excluded':
204
+ excluded += 1;
205
+ break;
206
+ case 'include': {
207
+ const target = verdict.target;
208
+ const fail = (why) => {
209
+ problems.push({ file, line: null, text: printable(target), kind: 'include', why });
210
+ };
211
+ if (URL.test(target)) {
212
+ fail('which is a URL');
213
+ break;
214
+ }
215
+ if (path.posix.isAbsolute(target) || path.win32.isAbsolute(target)) {
216
+ fail('which is an absolute path');
217
+ break;
218
+ }
219
+ const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(file), target));
220
+ if (resolved === '..' || resolved.startsWith('../')) {
221
+ fail('which is outside the repository');
222
+ break;
223
+ }
224
+ visit(resolved, depth + 1, file, printable(target));
225
+ break;
226
+ }
227
+ default:
228
+ problems.push({ file, line: logical.line, text: printable(logical.text), kind: verdict.kind });
229
+ }
230
+ }
231
+ };
232
+ visit(top, 0, null, top);
233
+ return { pinned: problems.length === 0, files, excluded, problems, topMissing };
234
+ }
235
+ /**
236
+ * One problem as the reason clause of a diagnostic about `top`, with no
237
+ * trailing full stop: `line 4 "flask>=2.0" is not pinned with ==, so any
238
+ * version osv-scanner reported would be a guess`.
239
+ */
240
+ export function describePinProblem(top, problem) {
241
+ const guess = 'so any version osv-scanner reported would be a guess';
242
+ const where = problem.file === top ? '' : ` of ${problem.file}`;
243
+ switch (problem.kind) {
244
+ case 'unpinned':
245
+ return `line ${problem.line ?? '?'}${where} "${problem.text}" is not pinned with ==, ${guess}`;
246
+ case 'arbitrary-equality':
247
+ return `line ${problem.line ?? '?'}${where} "${problem.text}" is pinned with ===, not ==, ${guess}`;
248
+ case 'unrecognised':
249
+ return (`line ${problem.line ?? '?'}${where} "${problem.text}" is not a line conductor recognises, ` +
250
+ 'so it cannot tell what osv-scanner would read there');
251
+ case 'include': {
252
+ const from = problem.file === top ? '' : ` (from ${problem.file})`;
253
+ return `includes ${problem.text}${from}, ${problem.why ?? 'which could not be read'}`;
254
+ }
255
+ }
256
+ }