@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
@@ -6,19 +6,38 @@
6
6
  * otherwise choose the commit the rules are read from.
7
7
  */
8
8
  export declare const PRIVATE_TRUST_BASE_REF = "refs/conductor/trust-base";
9
+ /** What a fully spelled ref names: nothing, an object, or an answer git could not give. */
10
+ export type RefLookup = {
11
+ kind: 'absent';
12
+ } | {
13
+ kind: 'ref';
14
+ oid: string;
15
+ } | {
16
+ kind: 'error';
17
+ detail: string;
18
+ };
19
+ /**
20
+ * The object a fully spelled ref EXACTLY names, keeping "no such ref" apart
21
+ * from "git could not answer". `show-ref --verify` looks at that ref and
22
+ * nothing else: it does not run git's name-resolution rules, so a tag stored
23
+ * as refs/tags/refs/conductor/trust-base is never taken for
24
+ * refs/conductor/trust-base. With --quiet it exits 1 for a ref that is not
25
+ * there and something else for a failure, which is the split this needs.
26
+ */
27
+ export declare function exactRefLookup(repoRoot: string, fullRef: string): RefLookup;
9
28
  /**
10
29
  * The object id a fully spelled ref EXACTLY names, or null when there is no
11
- * such ref. `show-ref --verify` looks at that ref and nothing else: it does
12
- * not run git's name-resolution rules, so a tag stored as
13
- * refs/tags/refs/conductor/trust-base is never taken for
14
- * refs/conductor/trust-base.
30
+ * such ref or it cannot be read. For callers where both mean "cannot use
31
+ * it"; a caller that would fall back to something else on absence uses
32
+ * `exactRefLookup` instead, so an unreadable ref never takes that fallback.
15
33
  */
16
34
  export declare function exactRefObject(repoRoot: string, fullRef: string): string | null;
17
35
  /**
18
36
  * A caller-given trust base that starts with "-", or null. Git allows a tag
19
37
  * named refs/tags/--output=x, and such a name handed to git as an argument is
20
- * read as an option, not a revision. Refused before any git call sees it; the
21
- * git calls below also pass --end-of-options as a second line of defence.
38
+ * read as an option, not a revision. Refused before any git call sees it; each
39
+ * git-calling function below refuses one again itself, so no caller can skip
40
+ * the check.
22
41
  */
23
42
  export declare function refuseDashLeadingRef(ref: string): string | null;
24
43
  /** A full 40- or 64-hex object id: never subject to ref name resolution. */
@@ -129,15 +148,62 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
129
148
  */
130
149
  export declare function refuseTrustBaseForPullRequest(repoRoot: string, ref: string, githubBaseRef: string | undefined): string | null;
131
150
  /**
132
- * The policy file's contents at a ref, or null when that ref carries none.
151
+ * How a control file that cannot be read at the base is cleared, as one
152
+ * sentence for every refusal that names one. The pull request that fixes the
153
+ * file is judged against the same base, so it cannot pass this check itself.
154
+ */
155
+ export declare function unreadableBaseRemedy(relativePath: string): string;
156
+ /** One file at a ref: not there, its text, or a read this run could not make. */
157
+ export type FileAtRef = {
158
+ kind: 'absent';
159
+ } | {
160
+ kind: 'file';
161
+ text: string;
162
+ } | {
163
+ kind: 'error';
164
+ detail: string;
165
+ };
166
+ /**
167
+ * One file's contents at a ref, with absent, present and unreadable kept
168
+ * apart. THE ONE READER for every file the umbrella takes from a ref.
133
169
  *
134
- * `git show`, never a checkout switch and never a read from the working
135
- * tree. The `./` is load-bearing for the same reason it is in intent-guard:
136
- * it makes git resolve the path relative to the working directory, which is
137
- * the repository root here, rather than to wherever the repository root would
138
- * be from somewhere else.
170
+ * Two steps. `git ls-tree <ref> -- ./<path>` looks the path up in the ref's
171
+ * tree: a listing that succeeds and names nothing is ABSENT, and a listing
172
+ * that fails is an ERROR. The entry must be a regular file; a symlink, a
173
+ * directory or a submodule at the path, or at any directory above it, is an
174
+ * ERROR, never read as its link target or as nothing. Then
175
+ * `git cat-file blob <id>` reads the blob by the id the listing named, and a
176
+ * failure there is an ERROR too. The path is only ever a path and the
177
+ * revision only ever a revision, so a file name can never be read as part of
178
+ * a revision, and absent, present and unreadable are three separate answers.
179
+ *
180
+ * No caller turns an ERROR into empty text or into a default. An error is
181
+ * could-not-run: the trusted file exists, or may, and nothing was judged
182
+ * against it.
183
+ *
184
+ * The `./` makes git resolve the path relative to the working directory,
185
+ * which is the repository root here.
186
+ */
187
+ export declare function readFileAtRef(repoRoot: string, ref: string, relativePath: string): FileAtRef;
188
+ /** One file at a ref as bytes: not there, its exact bytes, or a read this run could not make. */
189
+ export type BytesAtRef = {
190
+ kind: 'absent';
191
+ } | {
192
+ kind: 'file';
193
+ bytes: Buffer;
194
+ } | {
195
+ kind: 'error';
196
+ detail: string;
197
+ };
198
+ /**
199
+ * `readFileAtRef`, byte-exact. The same lookup (the same tree listing, the
200
+ * same refusal of a symlink, directory or submodule at the path or above it,
201
+ * the same blob read by the id the listing named), with the blob kept as
202
+ * bytes rather than decoded as UTF-8. For a file that is copied out and read
203
+ * by another program (the vulnerabilities gate's base copies): decoding would
204
+ * rewrite a lockfile with invalid bytes before that program saw it.
139
205
  */
140
- export declare function readPolicyAtRef(repoRoot: string, ref: string): string | null;
206
+ export declare function readFileAtRefBytes(repoRoot: string, ref: string, relativePath: string): BytesAtRef;
141
207
  /**
142
208
  * Whether two policy files differ in what they SAY.
143
209
  *
@@ -148,7 +214,7 @@ export declare function readPolicyAtRef(repoRoot: string, ref: string): string |
148
214
  * compared instead, which is the fail-closed direction: an unparseable head
149
215
  * policy is reported as a change rather than quietly matching.
150
216
  *
151
- * BOTH SIDES COME FROM `git show`, base and head alike, and that is not an
217
+ * BOTH SIDES COME FROM `readFileAtRef`, base and head alike, and that is not an
152
218
  * accident of implementation. intent-guard read its head side from the
153
219
  * working tree with a call that follows symlinks, so a pull request that
154
220
  * replaced a control file with a link compared equal to the base and was
@@ -159,19 +225,34 @@ export declare function readPolicyAtRef(repoRoot: string, ref: string): string |
159
225
  export declare function policyDiffers(base: string | null, head: string | null): boolean;
160
226
  /** The one line the report prints when the head proposes a different policy. */
161
227
  export declare const POLICY_PROPOSAL_LINE = "policy changed in this pull request";
228
+ /** One path's tree entry at a ref: not there, the entry, or a listing that failed. */
229
+ export type TreeEntry = {
230
+ kind: 'absent';
231
+ } | {
232
+ kind: 'entry';
233
+ mode: string;
234
+ type: string;
235
+ sha: string;
236
+ } | {
237
+ kind: 'error';
238
+ detail: string;
239
+ };
162
240
  /**
163
- * One path's tree entry at a ref, or null when the ref has no such path.
241
+ * One path's tree entry at a ref, keeping "the ref has no such path" apart
242
+ * from "git could not list it".
164
243
  *
165
244
  * `ls-tree` rather than `git show`, because the BLOB ID is the thing being
166
245
  * compared and `show` prints contents without telling you what kind of entry
167
246
  * produced them. The mode comes with it, so a regular file can be told from a
168
247
  * symlink, a submodule or a directory in the same read.
248
+ *
249
+ * Only a listing that SUCCEEDS and names nothing is absent. ls-tree exiting
250
+ * non-zero (a ref that will not resolve, a tree it cannot read) is a read
251
+ * this run cannot make, and so is a path with a symlink or a submodule at
252
+ * any directory above it in the ref's tree: what the path means there is
253
+ * decided outside the tree, so it is an error, never absent.
169
254
  */
170
- export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): {
171
- mode: string;
172
- type: string;
173
- sha: string;
174
- } | null;
255
+ export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): TreeEntry;
175
256
  /**
176
257
  * Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
177
258
  *
@@ -21,10 +21,17 @@
21
21
  // mirrored on purpose so the two gates cannot disagree about what a trust
22
22
  // base is:
23
23
  //
24
- // - READS ONLY, AND NEVER INTO THE REPOSITORY. `git rev-parse` and
25
- // `git show`, both of which only read. No checkout switch, no worktree, no
26
- // stash, no write of any kind. An umbrella that moved somebody's HEAD to
27
- // do its job would be a worse bug than the one it fixes.
24
+ // - READS ONLY, AND NEVER INTO THE REPOSITORY. This file runs read-only git:
25
+ // rev-parse, show-ref, rev-list, ls-tree and cat-file. No checkout switch,
26
+ // no worktree, no stash, no write of any kind. An umbrella that moved
27
+ // somebody's HEAD to do its job would be a worse bug than the one it fixes.
28
+ //
29
+ // Every function here that hands git a revision refuses a dash-leading one
30
+ // itself, before git sees it, and ends the revision list with "--" where
31
+ // the command takes paths, so git always reads the revision as a revision
32
+ // and every path as a path. One reader (`readFileAtRef`) looks a path up
33
+ // in the ref's tree and reads the blob by its id. --end-of-options is not
34
+ // used: git rev-parse only accepts it from git 2.30.
28
35
  //
29
36
  // - FAIL CLOSED ON THE REF. A ref that will not resolve is could-not-run for
30
37
  // every enabled gate. It is never a reason to fall back to the head,
@@ -64,11 +71,10 @@
64
71
  // RUN proceeds, so the caller can still learn the trees matched
65
72
  // (`headTreeEqualsBase` below) and run only the gates whose input is
66
73
  // history rather than the tree.
67
- import { spawnSync } from 'node:child_process';
68
74
  import { realpathSync } from 'node:fs';
69
75
  import path from 'node:path';
70
76
  import { parse as parseYaml } from 'yaml';
71
- import { POLICY_FILE_NAME } from './policy.js';
77
+ import { gitComplaint, runGit, runGitBytes } from './git.js';
72
78
  /**
73
79
  * The private, fully spelled ref the composite action fetches the base branch
74
80
  * into (action.yml, gates step). Nothing else writes it and no short name can
@@ -77,36 +83,48 @@ import { POLICY_FILE_NAME } from './policy.js';
77
83
  * otherwise choose the commit the rules are read from.
78
84
  */
79
85
  export const PRIVATE_TRUST_BASE_REF = 'refs/conductor/trust-base';
80
- function refExists(repoRoot, fullRef) {
81
- const child = spawnSync('git', ['show-ref', '--verify', '--quiet', fullRef], {
82
- cwd: repoRoot,
83
- encoding: 'utf8',
84
- });
85
- return child.error === undefined && child.status === 0;
86
+ /**
87
+ * The object a fully spelled ref EXACTLY names, keeping "no such ref" apart
88
+ * from "git could not answer". `show-ref --verify` looks at that ref and
89
+ * nothing else: it does not run git's name-resolution rules, so a tag stored
90
+ * as refs/tags/refs/conductor/trust-base is never taken for
91
+ * refs/conductor/trust-base. With --quiet it exits 1 for a ref that is not
92
+ * there and something else for a failure, which is the split this needs.
93
+ */
94
+ export function exactRefLookup(repoRoot, fullRef) {
95
+ if (fullRef.startsWith('-')) {
96
+ return { kind: 'error', detail: `refusing "${fullRef}": it starts with "-"` };
97
+ }
98
+ const probe = runGit(repoRoot, ['show-ref', '--verify', '--quiet', fullRef]);
99
+ if (probe.error === undefined && probe.status === 1) {
100
+ return { kind: 'absent' };
101
+ }
102
+ if (probe.error !== undefined || probe.status !== 0) {
103
+ return { kind: 'error', detail: `cannot read ${fullRef}: ${gitComplaint(probe)}` };
104
+ }
105
+ const read = runGit(repoRoot, ['show-ref', '--verify', '--hash', fullRef]);
106
+ const value = read.stdout.trim();
107
+ if (read.error !== undefined || read.status !== 0 || !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(value)) {
108
+ return { kind: 'error', detail: `cannot read ${fullRef}: ${gitComplaint(read)}` };
109
+ }
110
+ return { kind: 'ref', oid: value };
86
111
  }
87
112
  /**
88
113
  * The object id a fully spelled ref EXACTLY names, or null when there is no
89
- * such ref. `show-ref --verify` looks at that ref and nothing else: it does
90
- * not run git's name-resolution rules, so a tag stored as
91
- * refs/tags/refs/conductor/trust-base is never taken for
92
- * refs/conductor/trust-base.
114
+ * such ref or it cannot be read. For callers where both mean "cannot use
115
+ * it"; a caller that would fall back to something else on absence uses
116
+ * `exactRefLookup` instead, so an unreadable ref never takes that fallback.
93
117
  */
94
118
  export function exactRefObject(repoRoot, fullRef) {
95
- const child = spawnSync('git', ['show-ref', '--verify', '--hash', fullRef], {
96
- cwd: repoRoot,
97
- encoding: 'utf8',
98
- });
99
- if (child.error !== undefined || child.status !== 0) {
100
- return null;
101
- }
102
- const value = (child.stdout ?? '').trim();
103
- return /^[0-9a-f]{40}([0-9a-f]{24})?$/.test(value) ? value : null;
119
+ const lookup = exactRefLookup(repoRoot, fullRef);
120
+ return lookup.kind === 'ref' ? lookup.oid : null;
104
121
  }
105
122
  /**
106
123
  * A caller-given trust base that starts with "-", or null. Git allows a tag
107
124
  * named refs/tags/--output=x, and such a name handed to git as an argument is
108
- * read as an option, not a revision. Refused before any git call sees it; the
109
- * git calls below also pass --end-of-options as a second line of defence.
125
+ * read as an option, not a revision. Refused before any git call sees it; each
126
+ * git-calling function below refuses one again itself, so no caller can skip
127
+ * the check.
110
128
  */
111
129
  export function refuseDashLeadingRef(ref) {
112
130
  if (!ref.startsWith('-')) {
@@ -147,7 +165,20 @@ noun = 'the trust base') {
147
165
  isFullObjectId(name)) {
148
166
  return null;
149
167
  }
150
- const matches = [`refs/tags/${name}`, `refs/heads/${name}`, `refs/remotes/${name}`].filter((full) => refExists(repoRoot, full));
168
+ const matches = [];
169
+ for (const full of [`refs/tags/${name}`, `refs/heads/${name}`, `refs/remotes/${name}`]) {
170
+ const lookup = exactRefLookup(repoRoot, full);
171
+ if (lookup.kind === 'error') {
172
+ // Could not tell whether the name is shadowed, so it cannot be trusted
173
+ // as spelled. Refused with git's own reason rather than read as absent.
174
+ return (`refusing "${ref}" as ${noun}: whether the name "${name}" is ambiguous could not be ` +
175
+ `checked (${lookup.detail}). Pass the ref spelled in full, for example ` +
176
+ 'refs/remotes/origin/main. Nothing was checked.');
177
+ }
178
+ if (lookup.kind === 'ref') {
179
+ matches.push(full);
180
+ }
181
+ }
151
182
  if (matches.length <= 1) {
152
183
  return null;
153
184
  }
@@ -164,6 +195,11 @@ noun = 'the trust base') {
164
195
  * rather than repeating the command line that failed.
165
196
  */
166
197
  export function resolveRev(repoRoot, rev, kind) {
198
+ // A dash-leading rev is an option to git, not a revision. Refused here,
199
+ // inside the function that calls git, so no caller can skip it.
200
+ if (rev.startsWith('-')) {
201
+ return null;
202
+ }
167
203
  // A refs/ name is NEVER handed to git's name resolution: rev-parse would
168
204
  // try refs/tags/<name> when the ref itself is absent, so a pushed tag named
169
205
  // refs/conductor/trust-base would stand in for the private ref. The exact
@@ -177,14 +213,13 @@ export function resolveRev(repoRoot, rev, kind) {
177
213
  }
178
214
  target = exact;
179
215
  }
180
- const child = spawnSync('git', ['rev-parse', '--verify', '--quiet', '--end-of-options', `${target}^{${kind}}`], {
181
- cwd: repoRoot,
182
- encoding: 'utf8',
183
- });
216
+ // No "--" here: rev-parse --verify takes exactly one revision and reads it
217
+ // only as a revision.
218
+ const child = runGit(repoRoot, ['rev-parse', '--verify', '--quiet', `${target}^{${kind}}`]);
184
219
  if (child.error !== undefined || child.status !== 0) {
185
220
  return null;
186
221
  }
187
- const value = (child.stdout ?? '').trim();
222
+ const value = child.stdout.trim();
188
223
  return value === '' ? null : value;
189
224
  }
190
225
  /**
@@ -198,14 +233,14 @@ export function resolveRev(repoRoot, rev, kind) {
198
233
  * branch first and the pull request's own head second.
199
234
  */
200
235
  function headParents(repoRoot) {
201
- const child = spawnSync('git', ['rev-list', '--parents', '-n', '1', 'HEAD'], {
202
- cwd: repoRoot,
203
- encoding: 'utf8',
204
- });
236
+ // "--" ends the revisions, so HEAD is read as a revision whatever files the
237
+ // working tree holds. A failure stays an empty list, which refuses the
238
+ // equal-tree exception: the fail-closed direction.
239
+ const child = runGit(repoRoot, ['rev-list', '--parents', '-n', '1', 'HEAD', '--']);
205
240
  if (child.error !== undefined || child.status !== 0) {
206
241
  return [];
207
242
  }
208
- const line = (child.stdout ?? '').trim();
243
+ const line = child.stdout.trim();
209
244
  if (line === '') {
210
245
  return [];
211
246
  }
@@ -364,7 +399,20 @@ export function refuseTrustBaseForPullRequest(repoRoot, ref, githubBaseRef) {
364
399
  // name when the ref is absent.
365
400
  const expectedRef = `refs/remotes/origin/${githubBaseRef}`;
366
401
  const expectedCommit = resolveRev(repoRoot, expectedRef, 'commit');
367
- const privateCommit = resolveRev(repoRoot, PRIVATE_TRUST_BASE_REF, 'commit');
402
+ // The private ref decides which reference applies, so a private ref git
403
+ // could not read is never taken for an absent one: the remote-tracking ref
404
+ // is the reference only when the private ref is truly absent.
405
+ const privateLookup = exactRefLookup(repoRoot, PRIVATE_TRUST_BASE_REF);
406
+ if (privateLookup.kind === 'error') {
407
+ return (`cannot verify "${ref}" as the trust base: ${privateLookup.detail}. Check that git can ` +
408
+ `read the repository and that the action's fetch of the base branch into ` +
409
+ `${PRIVATE_TRUST_BASE_REF} succeeded. Nothing was checked.`);
410
+ }
411
+ const privateCommit = privateLookup.kind === 'absent' ? null : resolveRev(repoRoot, PRIVATE_TRUST_BASE_REF, 'commit');
412
+ if (privateLookup.kind === 'ref' && privateCommit === null) {
413
+ return (`cannot verify "${ref}" as the trust base: ${PRIVATE_TRUST_BASE_REF} exists but does not ` +
414
+ 'name a commit. Nothing was checked.');
415
+ }
368
416
  // THE ACTION PASSES A FULL COMMIT ID, never a ref name (a full object id is
369
417
  // not subject to name resolution). It is accepted only when it IS the
370
418
  // private ref's commit (the authority, fetched and verified by the action's
@@ -431,27 +479,86 @@ export function refuseTrustBaseForPullRequest(repoRoot, ref, githubBaseRef) {
431
479
  `trusted. Pass ${expectedRef} or ${PRIVATE_TRUST_BASE_REF} instead. Nothing was checked.`);
432
480
  }
433
481
  /**
434
- * The policy file's contents at a ref, or null when that ref carries none.
482
+ * How a control file that cannot be read at the base is cleared, as one
483
+ * sentence for every refusal that names one. The pull request that fixes the
484
+ * file is judged against the same base, so it cannot pass this check itself.
485
+ */
486
+ export function unreadableBaseRemedy(relativePath) {
487
+ return (`To clear it, make ${relativePath} a regular file on the base branch, with no symbolic ` +
488
+ 'link or submodule in the directories above it. The pull request ' +
489
+ 'that does so is judged against this same base, so it has to be merged by someone ' +
490
+ 'allowed to merge without this check passing.');
491
+ }
492
+ /**
493
+ * One file's contents at a ref, with absent, present and unreadable kept
494
+ * apart. THE ONE READER for every file the umbrella takes from a ref.
495
+ *
496
+ * Two steps. `git ls-tree <ref> -- ./<path>` looks the path up in the ref's
497
+ * tree: a listing that succeeds and names nothing is ABSENT, and a listing
498
+ * that fails is an ERROR. The entry must be a regular file; a symlink, a
499
+ * directory or a submodule at the path, or at any directory above it, is an
500
+ * ERROR, never read as its link target or as nothing. Then
501
+ * `git cat-file blob <id>` reads the blob by the id the listing named, and a
502
+ * failure there is an ERROR too. The path is only ever a path and the
503
+ * revision only ever a revision, so a file name can never be read as part of
504
+ * a revision, and absent, present and unreadable are three separate answers.
505
+ *
506
+ * No caller turns an ERROR into empty text or into a default. An error is
507
+ * could-not-run: the trusted file exists, or may, and nothing was judged
508
+ * against it.
435
509
  *
436
- * `git show`, never a checkout switch and never a read from the working
437
- * tree. The `./` is load-bearing for the same reason it is in intent-guard:
438
- * it makes git resolve the path relative to the working directory, which is
439
- * the repository root here, rather than to wherever the repository root would
440
- * be from somewhere else.
510
+ * The `./` makes git resolve the path relative to the working directory,
511
+ * which is the repository root here.
441
512
  */
442
- export function readPolicyAtRef(repoRoot, ref) {
443
- if (ref.startsWith('-')) {
444
- return null;
445
- }
446
- const child = spawnSync('git', ['show', '--end-of-options', `${ref}:./${POLICY_FILE_NAME}`], {
447
- cwd: repoRoot,
448
- encoding: 'utf8',
449
- maxBuffer: 32 * 1024 * 1024,
450
- });
451
- if (child.error !== undefined || child.status !== 0) {
452
- return null;
453
- }
454
- return child.stdout ?? '';
513
+ export function readFileAtRef(repoRoot, ref, relativePath) {
514
+ const listed = treeEntryAt(repoRoot, ref, relativePath);
515
+ if (listed.kind !== 'entry') {
516
+ return listed;
517
+ }
518
+ if (listed.type !== 'blob' || !isRegularFileMode(listed.mode)) {
519
+ return {
520
+ kind: 'error',
521
+ detail: `${relativePath} is not a regular file at "${ref}" (git lists it with mode ${listed.mode}), ` +
522
+ 'so there is no file to read there',
523
+ };
524
+ }
525
+ const blob = runGit(repoRoot, ['cat-file', 'blob', listed.sha]);
526
+ if (blob.error !== undefined || blob.status !== 0) {
527
+ return {
528
+ kind: 'error',
529
+ detail: `${relativePath} is listed at "${ref}" but its contents could not be read: ${gitComplaint(blob)}`,
530
+ };
531
+ }
532
+ return { kind: 'file', text: blob.stdout };
533
+ }
534
+ /**
535
+ * `readFileAtRef`, byte-exact. The same lookup (the same tree listing, the
536
+ * same refusal of a symlink, directory or submodule at the path or above it,
537
+ * the same blob read by the id the listing named), with the blob kept as
538
+ * bytes rather than decoded as UTF-8. For a file that is copied out and read
539
+ * by another program (the vulnerabilities gate's base copies): decoding would
540
+ * rewrite a lockfile with invalid bytes before that program saw it.
541
+ */
542
+ export function readFileAtRefBytes(repoRoot, ref, relativePath) {
543
+ const listed = treeEntryAt(repoRoot, ref, relativePath);
544
+ if (listed.kind !== 'entry') {
545
+ return listed;
546
+ }
547
+ if (listed.type !== 'blob' || !isRegularFileMode(listed.mode)) {
548
+ return {
549
+ kind: 'error',
550
+ detail: `${relativePath} is not a regular file at "${ref}" (git lists it with mode ${listed.mode}), ` +
551
+ 'so there is no file to read there',
552
+ };
553
+ }
554
+ const blob = runGitBytes(repoRoot, ['cat-file', 'blob', listed.sha]);
555
+ if (blob.error !== undefined || blob.status !== 0) {
556
+ return {
557
+ kind: 'error',
558
+ detail: `${relativePath} is listed at "${ref}" but its contents could not be read: ${gitComplaint({ ...blob, stdout: '' })}`,
559
+ };
560
+ }
561
+ return { kind: 'file', bytes: blob.stdout };
455
562
  }
456
563
  /**
457
564
  * Whether two policy files differ in what they SAY.
@@ -463,7 +570,7 @@ export function readPolicyAtRef(repoRoot, ref) {
463
570
  * compared instead, which is the fail-closed direction: an unparseable head
464
571
  * policy is reported as a change rather than quietly matching.
465
572
  *
466
- * BOTH SIDES COME FROM `git show`, base and head alike, and that is not an
573
+ * BOTH SIDES COME FROM `readFileAtRef`, base and head alike, and that is not an
467
574
  * accident of implementation. intent-guard read its head side from the
468
575
  * working tree with a call that follows symlinks, so a pull request that
469
576
  * replaced a control file with a link compared equal to the base and was
@@ -488,33 +595,62 @@ export function policyDiffers(base, head) {
488
595
  /** The one line the report prints when the head proposes a different policy. */
489
596
  export const POLICY_PROPOSAL_LINE = 'policy changed in this pull request';
490
597
  /**
491
- * One path's tree entry at a ref, or null when the ref has no such path.
598
+ * One path's tree entry at a ref, keeping "the ref has no such path" apart
599
+ * from "git could not list it".
492
600
  *
493
601
  * `ls-tree` rather than `git show`, because the BLOB ID is the thing being
494
602
  * compared and `show` prints contents without telling you what kind of entry
495
603
  * produced them. The mode comes with it, so a regular file can be told from a
496
604
  * symlink, a submodule or a directory in the same read.
605
+ *
606
+ * Only a listing that SUCCEEDS and names nothing is absent. ls-tree exiting
607
+ * non-zero (a ref that will not resolve, a tree it cannot read) is a read
608
+ * this run cannot make, and so is a path with a symlink or a submodule at
609
+ * any directory above it in the ref's tree: what the path means there is
610
+ * decided outside the tree, so it is an error, never absent.
497
611
  */
498
612
  export function treeEntryAt(repoRoot, ref, relativePath) {
499
613
  if (ref.startsWith('-')) {
500
- return null;
614
+ return {
615
+ kind: 'error',
616
+ detail: `refusing "${ref}": it starts with "-", which git would read as an option rather than a revision`,
617
+ };
618
+ }
619
+ const segments = relativePath.split('/').filter((segment) => segment !== '' && segment !== '.');
620
+ for (let depth = 1; depth < segments.length; depth += 1) {
621
+ const parent = segments.slice(0, depth).join('/');
622
+ const listed = listOne(repoRoot, ref, parent);
623
+ if (listed.kind !== 'entry') {
624
+ return listed;
625
+ }
626
+ if (listed.mode === '120000' || listed.mode === '160000') {
627
+ return {
628
+ kind: 'error',
629
+ detail: `${parent} is a ${listed.mode === '120000' ? 'symbolic link' : 'submodule'} at "${ref}", ` +
630
+ `so ${relativePath} cannot be read there as a file in the tree`,
631
+ };
632
+ }
633
+ if (listed.type !== 'tree') {
634
+ return { kind: 'absent' };
635
+ }
501
636
  }
502
- const child = spawnSync('git', ['ls-tree', '--end-of-options', ref, '--', `./${relativePath}`], {
503
- cwd: repoRoot,
504
- encoding: 'utf8',
505
- });
637
+ return listOne(repoRoot, ref, relativePath);
638
+ }
639
+ /** One `ls-tree` listing of exactly this path. */
640
+ function listOne(repoRoot, ref, relativePath) {
641
+ const child = runGit(repoRoot, ['ls-tree', ref, '--', `./${relativePath}`]);
506
642
  if (child.error !== undefined || child.status !== 0) {
507
- return null;
643
+ return { kind: 'error', detail: `cannot list ${relativePath} at "${ref}": ${gitComplaint(child)}` };
508
644
  }
509
- const line = (child.stdout ?? '').split('\n').find((entry) => entry.trim().length > 0);
645
+ const line = child.stdout.split('\n').find((entry) => entry.trim().length > 0);
510
646
  if (line === undefined) {
511
- return null;
647
+ return { kind: 'absent' };
512
648
  }
513
649
  const [mode, type, sha] = line.split(/\s+/);
514
650
  if (mode === undefined || type === undefined || sha === undefined) {
515
- return null;
651
+ return { kind: 'error', detail: `cannot read the listing of ${relativePath} at "${ref}"` };
516
652
  }
517
- return { mode, type, sha };
653
+ return { kind: 'entry', mode, type, sha };
518
654
  }
519
655
  /** The two modes that mean an ordinary file git will hand back. */
520
656
  function isRegularFileMode(mode) {
@@ -568,7 +704,9 @@ function treeShaAt(repoRoot, ref, relativeDir) {
568
704
  return resolveRev(repoRoot, ref, 'tree');
569
705
  }
570
706
  const entry = treeEntryAt(repoRoot, ref, relativeDir);
571
- return entry === null || entry.type !== 'tree' ? null : entry.sha;
707
+ // Absent, unreadable or not a directory all mean "not the approved tree",
708
+ // which refuses the program: the fail-closed direction for each.
709
+ return entry.kind !== 'entry' || entry.type !== 'tree' ? null : entry.sha;
572
710
  }
573
711
  /**
574
712
  * Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
@@ -658,8 +796,16 @@ export function refuseHeadControlledProgram(repoRoot, trustBase, programPath) {
658
796
  }
659
797
  for (const candidate of candidates) {
660
798
  const relative = path.relative(repoReal, candidate).split(path.sep).join('/');
661
- const base = treeEntryAt(repoRoot, trustBase, relative);
662
- const head = treeEntryAt(repoRoot, 'HEAD', relative);
799
+ const baseEntry = treeEntryAt(repoRoot, trustBase, relative);
800
+ const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
801
+ for (const listed of [baseEntry, headEntry]) {
802
+ if (listed.kind === 'error') {
803
+ return (`the gate program at ${relative} could not be checked against "${trustBase}": ` +
804
+ `${listed.detail}. Nothing was checked by this gate.`);
805
+ }
806
+ }
807
+ const base = baseEntry.kind === 'entry' ? baseEntry : null;
808
+ const head = headEntry.kind === 'entry' ? headEntry : null;
663
809
  if (base === null || head === null) {
664
810
  return (`the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not track the gate program ` +
665
811
  `at ${relative}, so it is a file this pull request controls and running it would let the ` +
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Tracked manifest-like files that were not handed to `product`, sorted, as
3
+ * one sentence fragment, or null when there are none.
4
+ *
5
+ * `handed` are the repository-relative paths the gate was actually handed,
6
+ * so a file it does read is never listed. By path rather than by base name,
7
+ * because the vulnerabilities gate hands a requirements file only when it
8
+ * passes the pin check (src/osv-coverage.ts): an unpinned requirements.txt
9
+ * is not read even when another requirements.txt is, and is listed. go.mod
10
+ * and a pinned requirements file are handed, so they leave this list.
11
+ * Vendored and testdata directories are skipped like node_modules: they are
12
+ * not this repository's own manifests.
13
+ */
14
+ export declare function unreadManifestsNote(tracked: readonly string[], handed: ReadonlySet<string>, product: string): string | null;