@vaultcompass/conductor 0.7.0 → 0.8.1

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.
@@ -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,122 @@
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 } from './git.js';
78
+ /**
79
+ * The private, fully spelled ref the composite action fetches the base branch
80
+ * into (action.yml, gates step). Nothing else writes it and no short name can
81
+ * shadow it: git resolves a short name like origin/main through refs/tags/
82
+ * BEFORE refs/remotes/, so a tag pushed by anyone able to push tags would
83
+ * otherwise choose the commit the rules are read from.
84
+ */
85
+ export const PRIVATE_TRUST_BASE_REF = 'refs/conductor/trust-base';
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 };
111
+ }
112
+ /**
113
+ * The object id a fully spelled ref EXACTLY names, or null when there is no
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.
117
+ */
118
+ export function exactRefObject(repoRoot, fullRef) {
119
+ const lookup = exactRefLookup(repoRoot, fullRef);
120
+ return lookup.kind === 'ref' ? lookup.oid : null;
121
+ }
122
+ /**
123
+ * A caller-given trust base that starts with "-", or null. Git allows a tag
124
+ * named refs/tags/--output=x, and such a name handed to git as an argument is
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.
128
+ */
129
+ export function refuseDashLeadingRef(ref) {
130
+ if (!ref.startsWith('-')) {
131
+ return null;
132
+ }
133
+ return (`refusing "${ref}" as the trust base: it starts with "-", which git would read as an ` +
134
+ 'option rather than a revision. Pass a ref name or a full commit id. Nothing was checked.');
135
+ }
136
+ /** A full 40- or 64-hex object id: never subject to ref name resolution. */
137
+ export function isFullObjectId(value) {
138
+ return /^([0-9a-f]{40}|[0-9a-f]{64})$/i.test(value);
139
+ }
140
+ /**
141
+ * Why a SHORT ref name cannot be trusted as spelled, or null.
142
+ *
143
+ * A name that matches more than one kind of ref (a tag and a remote-tracking
144
+ * ref or a branch) is resolved by git in its own precedence order, tags
145
+ * first, with no warning under --quiet. That is a choice made by whoever can
146
+ * create the tag, so it is refused rather than resolved. A ref already spelled
147
+ * from refs/ is unambiguous, and revision expressions (HEAD, HEAD~1, a sha) are
148
+ * not names and are left to the callers' own checks.
149
+ */
150
+ export function refuseAmbiguousRef(repoRoot, ref,
151
+ /** What the ref is used as, for the message: "the trust base", "the intent base". */
152
+ noun = 'the trust base') {
153
+ // The NAME part only: origin/main~0, origin/main^{commit} and origin/main@{0}
154
+ // resolve through the same tag-first rules as origin/main, so a revision
155
+ // suffix is cut off (from the first ~ ^ : or @{) before the check. A bare @
156
+ // is HEAD and is NOT a cut: a name may carry a literal @ (a branch and a tag
157
+ // both named feature@x, where git picks the tag), and cutting there hid it.
158
+ const cut = ref.search(/[~^:]|@\{/);
159
+ const name = cut === -1 ? ref : ref.slice(0, cut);
160
+ if (name === '' ||
161
+ name === 'HEAD' ||
162
+ name === '@' ||
163
+ name.startsWith('refs/') ||
164
+ /[\s{}\\]/.test(name) ||
165
+ isFullObjectId(name)) {
166
+ return null;
167
+ }
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
+ }
182
+ if (matches.length <= 1) {
183
+ return null;
184
+ }
185
+ return (`refusing "${ref}" as ${noun}: the name "${name}" is ambiguous, it matches ${matches.join(' and ')}, ` +
186
+ 'and git would pick one of them by its own precedence (tags first). Whoever can push a tag ' +
187
+ 'could choose the base this way. Pass the ref spelled in full, for example ' +
188
+ 'refs/remotes/origin/main. Nothing was checked.');
189
+ }
72
190
  /**
73
191
  * What a rev resolves to at this repository, or null when it does not.
74
192
  *
@@ -76,15 +194,32 @@ import { POLICY_FILE_NAME } from './policy.js';
76
194
  * forwarding on failure: the caller writes a sentence a reader can act on
77
195
  * rather than repeating the command line that failed.
78
196
  */
79
- function resolveRev(repoRoot, rev, kind) {
80
- const child = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${rev}^{${kind}}`], {
81
- cwd: repoRoot,
82
- encoding: 'utf8',
83
- });
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
+ }
203
+ // A refs/ name is NEVER handed to git's name resolution: rev-parse would
204
+ // try refs/tags/<name> when the ref itself is absent, so a pushed tag named
205
+ // refs/conductor/trust-base would stand in for the private ref. The exact
206
+ // ref is read with show-ref and its object id is what gets resolved (a full
207
+ // object id is not subject to name resolution).
208
+ let target = rev;
209
+ if (rev.startsWith('refs/')) {
210
+ const exact = exactRefObject(repoRoot, rev);
211
+ if (exact === null) {
212
+ return null;
213
+ }
214
+ target = exact;
215
+ }
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}}`]);
84
219
  if (child.error !== undefined || child.status !== 0) {
85
220
  return null;
86
221
  }
87
- const value = (child.stdout ?? '').trim();
222
+ const value = child.stdout.trim();
88
223
  return value === '' ? null : value;
89
224
  }
90
225
  /**
@@ -98,14 +233,14 @@ function resolveRev(repoRoot, rev, kind) {
98
233
  * branch first and the pull request's own head second.
99
234
  */
100
235
  function headParents(repoRoot) {
101
- const child = spawnSync('git', ['rev-list', '--parents', '-n', '1', 'HEAD'], {
102
- cwd: repoRoot,
103
- encoding: 'utf8',
104
- });
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', '--']);
105
240
  if (child.error !== undefined || child.status !== 0) {
106
241
  return [];
107
242
  }
108
- const line = (child.stdout ?? '').trim();
243
+ const line = child.stdout.trim();
109
244
  if (line === '') {
110
245
  return [];
111
246
  }
@@ -150,6 +285,14 @@ export function headTreeEqualsBase(repoRoot, ref) {
150
285
  * learns the trees matched even on this accepted path.
151
286
  */
152
287
  export function refuseTrustBaseRef(repoRoot, ref) {
288
+ const dashed = refuseDashLeadingRef(ref);
289
+ if (dashed !== null) {
290
+ return dashed;
291
+ }
292
+ const ambiguous = refuseAmbiguousRef(repoRoot, ref);
293
+ if (ambiguous !== null) {
294
+ return ambiguous;
295
+ }
153
296
  const base = resolveRev(repoRoot, ref, 'commit');
154
297
  if (base === null) {
155
298
  return (`cannot read the policy from base ref "${ref}": it does not resolve to a commit in ` +
@@ -211,11 +354,12 @@ export function refuseTrustBaseRef(repoRoot, ref) {
211
354
  * NAME on a pull_request or pull_request_target event, and empty everywhere
212
355
  * else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
213
356
  * a platform that never sets it. When it is set, the given ref is accepted
214
- * only when it resolves to the SAME COMMIT as origin/<githubBaseRef>, which
215
- * is exactly what the composite action itself always passes
216
- * (`--trust-base "origin/$GITHUB_BASE_REF"` in action.yml's gates step). So
217
- * an ordinary pull-request run sees the given ref and the expected ref as the
218
- * identical spelling and this returns null immediately, before
357
+ * only when it is the FULL COMMIT ID the composite action's "Fetch the trust
358
+ * base" step published (which must equal refs/conductor/trust-base, the
359
+ * authority, or refs/remotes/origin/<githubBaseRef>, both read with show-ref),
360
+ * or is that private ref itself, or -- for an explicit trust base -- resolves
361
+ * to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
362
+ * pull-request run through the action returns null here, before
219
363
  * refuseTrustBaseRef's own checks -- HEAD, and the equal-tree exception from
220
364
  * issue #69/#73 -- ever run: this check is narrower than those and says
221
365
  * nothing about HEAD or about tree equality, only about whether the given ref
@@ -223,11 +367,11 @@ export function refuseTrustBaseRef(repoRoot, ref) {
223
367
  * request's own branch, or anything else that disagrees, is refused with both
224
368
  * refs and both commits named.
225
369
  *
226
- * FAILS CLOSED when origin/<githubBaseRef> itself does not resolve, naming
227
- * it: reachable on the default actions/checkout (fetch-depth: 1), which does
228
- * not carry the base branch at all. The README already asks for
229
- * fetch-depth: 0, and a checkout that does not carry the base branch is not a
230
- * reason to skip the comparison.
370
+ * FAILS CLOSED when neither the private ref nor refs/remotes/origin/
371
+ * <githubBaseRef> exists, naming them: reachable through the CLI on the
372
+ * default actions/checkout (fetch-depth: 1), which does not carry the base
373
+ * branch at all. The README already asks for fetch-depth: 0, and a checkout
374
+ * that does not carry the base branch is not a reason to skip the comparison.
231
375
  *
232
376
  * When the GIVEN ref does not resolve at all, this returns null rather than
233
377
  * refusing: refuseTrustBaseRef is the function with its own sentence for an
@@ -241,44 +385,151 @@ export function refuseTrustBaseForPullRequest(repoRoot, ref, githubBaseRef) {
241
385
  if (githubBaseRef === undefined || githubBaseRef === '') {
242
386
  return null;
243
387
  }
244
- const expectedRef = `origin/${githubBaseRef}`;
388
+ const dashed = refuseDashLeadingRef(ref);
389
+ if (dashed !== null) {
390
+ return dashed;
391
+ }
392
+ const ambiguous = refuseAmbiguousRef(repoRoot, ref);
393
+ if (ambiguous !== null) {
394
+ return ambiguous;
395
+ }
396
+ // SPELLED IN FULL, and read with show-ref (resolveRev does that for every
397
+ // refs/ name): a short origin/<base> would resolve through
398
+ // refs/tags/origin/<base> first, and a refs/ name through a tag of that
399
+ // name when the ref is absent.
400
+ const expectedRef = `refs/remotes/origin/${githubBaseRef}`;
245
401
  const expectedCommit = resolveRev(repoRoot, expectedRef, '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
+ }
416
+ // THE ACTION PASSES A FULL COMMIT ID, never a ref name (a full object id is
417
+ // not subject to name resolution). It is accepted only when it IS the
418
+ // private ref's commit (the authority, fetched and verified by the action's
419
+ // fetch step) or, ONLY when the private ref does not exist, the commit of
420
+ // refs/remotes/origin/<base> (both read with show-ref).
421
+ if (isFullObjectId(ref)) {
422
+ const given = resolveRev(repoRoot, ref, 'commit');
423
+ if (given === null) {
424
+ return null;
425
+ }
426
+ // The private ref is the ONLY acceptable answer when it exists: pull-request
427
+ // code can move refs/remotes/origin/<base>, so an id that matches only that
428
+ // ref is the attack, not a second answer. The remote-tracking ref is the
429
+ // reference only when the private ref is absent.
430
+ if (privateCommit !== null ? given === privateCommit : given === expectedCommit) {
431
+ return null;
432
+ }
433
+ if (privateCommit === null && expectedCommit === null) {
434
+ return (`cannot verify "${ref}" as the trust base: neither ${PRIVATE_TRUST_BASE_REF} (the ` +
435
+ `composite action's fetch of the base branch) nor "${expectedRef}" exists in this ` +
436
+ 'repository, so there is nothing to compare it against. Nothing was checked. In CI, fetch ' +
437
+ 'the base branch (actions/checkout with fetch-depth: 0) before running the gates.');
438
+ }
439
+ return (`refusing "${ref}" as the trust base: GITHUB_BASE_REF is set to "${githubBaseRef}", so this ` +
440
+ 'run is a pull request, and on a pull request the trust base must be the base branch and ' +
441
+ `nothing else. It equals neither ${PRIVATE_TRUST_BASE_REF} (${privateCommit ?? 'absent'}) ` +
442
+ `nor ${expectedRef} (${expectedCommit ?? 'absent'}). Nothing was checked.`);
443
+ }
444
+ // THE PRIVATE REF IS THE AUTHORITY, and nothing reads
445
+ // refs/remotes/origin/<base> for trust. That ref is fixed at checkout time
446
+ // and is the side pull-request code can move, while the private ref is
447
+ // fetched later by the action: comparing them adds a false refusal whenever
448
+ // the base branch advances in between, and no protection. Only an explicit
449
+ // trust base (below) has the remote-tracking ref as its one reference.
450
+ if (ref === PRIVATE_TRUST_BASE_REF) {
451
+ if (privateCommit !== null) {
452
+ return null;
453
+ }
454
+ return (`refusing "${ref}" as the trust base: no such ref exists in this repository (a tag or ` +
455
+ 'branch of that name does not count: only the exact ref the action fetched does). The ' +
456
+ 'action\'s fetch of the base branch did not run or did not succeed. Nothing was checked.');
457
+ }
246
458
  if (expectedCommit === null) {
247
459
  return (`cannot verify "${ref}" as the trust base: "${expectedRef}" does not resolve to a commit ` +
248
- 'in this repository, so there is nothing to compare it against. Nothing was checked. In ' +
249
- 'CI, fetch the base branch (actions/checkout with fetch-depth: 0) before running the gates.');
460
+ `in this repository, so there is nothing to compare it against, and only ` +
461
+ `${PRIVATE_TRUST_BASE_REF} (fetched by the composite action) is accepted without it. ` +
462
+ 'Nothing was checked. In CI, fetch the base branch (actions/checkout with ' +
463
+ 'fetch-depth: 0) before running the gates.');
250
464
  }
251
465
  const givenCommit = resolveRev(repoRoot, ref, 'commit');
252
466
  if (givenCommit === null) {
253
467
  return null;
254
468
  }
469
+ // A NAMED explicit trust base may equal refs/remotes/origin/<base> even
470
+ // while the private ref exists: the full-id rule above applies to the
471
+ // action's own id, not to a name the caller typed.
255
472
  if (givenCommit === expectedCommit) {
256
473
  return null;
257
474
  }
258
475
  return (`refusing "${ref}" as the trust base: GITHUB_BASE_REF is set to "${githubBaseRef}", so this ` +
259
476
  'run is a pull request, and on a pull request the trust base must be the base branch and ' +
260
477
  `nothing else. "${ref}" resolves to ${givenCommit}, and "${expectedRef}" resolves to ` +
261
- `${expectedCommit}, a different commit. Pass ${expectedRef} instead. Nothing was checked.`);
478
+ `${expectedCommit}, a different commit: something moved one of them, so neither can be ` +
479
+ `trusted. Pass ${expectedRef} or ${PRIVATE_TRUST_BASE_REF} instead. Nothing was checked.`);
262
480
  }
263
481
  /**
264
- * 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.
265
505
  *
266
- * `git show`, never a checkout switch and never a read from the working
267
- * tree. The `./` is load-bearing for the same reason it is in intent-guard:
268
- * it makes git resolve the path relative to the working directory, which is
269
- * the repository root here, rather than to wherever the repository root would
270
- * be from somewhere else.
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.
509
+ *
510
+ * The `./` makes git resolve the path relative to the working directory,
511
+ * which is the repository root here.
271
512
  */
272
- export function readPolicyAtRef(repoRoot, ref) {
273
- const child = spawnSync('git', ['show', `${ref}:./${POLICY_FILE_NAME}`], {
274
- cwd: repoRoot,
275
- encoding: 'utf8',
276
- maxBuffer: 32 * 1024 * 1024,
277
- });
278
- if (child.error !== undefined || child.status !== 0) {
279
- return null;
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
+ };
280
531
  }
281
- return child.stdout ?? '';
532
+ return { kind: 'file', text: blob.stdout };
282
533
  }
283
534
  /**
284
535
  * Whether two policy files differ in what they SAY.
@@ -290,7 +541,7 @@ export function readPolicyAtRef(repoRoot, ref) {
290
541
  * compared instead, which is the fail-closed direction: an unparseable head
291
542
  * policy is reported as a change rather than quietly matching.
292
543
  *
293
- * BOTH SIDES COME FROM `git show`, base and head alike, and that is not an
544
+ * BOTH SIDES COME FROM `readFileAtRef`, base and head alike, and that is not an
294
545
  * accident of implementation. intent-guard read its head side from the
295
546
  * working tree with a call that follows symlinks, so a pull request that
296
547
  * replaced a control file with a link compared equal to the base and was
@@ -315,30 +566,62 @@ export function policyDiffers(base, head) {
315
566
  /** The one line the report prints when the head proposes a different policy. */
316
567
  export const POLICY_PROPOSAL_LINE = 'policy changed in this pull request';
317
568
  /**
318
- * One path's tree entry at a ref, or null when the ref has no such path.
569
+ * One path's tree entry at a ref, keeping "the ref has no such path" apart
570
+ * from "git could not list it".
319
571
  *
320
572
  * `ls-tree` rather than `git show`, because the BLOB ID is the thing being
321
573
  * compared and `show` prints contents without telling you what kind of entry
322
574
  * produced them. The mode comes with it, so a regular file can be told from a
323
575
  * symlink, a submodule or a directory in the same read.
576
+ *
577
+ * Only a listing that SUCCEEDS and names nothing is absent. ls-tree exiting
578
+ * non-zero (a ref that will not resolve, a tree it cannot read) is a read
579
+ * this run cannot make, and so is a path with a symlink or a submodule at
580
+ * any directory above it in the ref's tree: what the path means there is
581
+ * decided outside the tree, so it is an error, never absent.
324
582
  */
325
583
  export function treeEntryAt(repoRoot, ref, relativePath) {
326
- const child = spawnSync('git', ['ls-tree', ref, '--', `./${relativePath}`], {
327
- cwd: repoRoot,
328
- encoding: 'utf8',
329
- });
584
+ if (ref.startsWith('-')) {
585
+ return {
586
+ kind: 'error',
587
+ detail: `refusing "${ref}": it starts with "-", which git would read as an option rather than a revision`,
588
+ };
589
+ }
590
+ const segments = relativePath.split('/').filter((segment) => segment !== '' && segment !== '.');
591
+ for (let depth = 1; depth < segments.length; depth += 1) {
592
+ const parent = segments.slice(0, depth).join('/');
593
+ const listed = listOne(repoRoot, ref, parent);
594
+ if (listed.kind !== 'entry') {
595
+ return listed;
596
+ }
597
+ if (listed.mode === '120000' || listed.mode === '160000') {
598
+ return {
599
+ kind: 'error',
600
+ detail: `${parent} is a ${listed.mode === '120000' ? 'symbolic link' : 'submodule'} at "${ref}", ` +
601
+ `so ${relativePath} cannot be read there as a file in the tree`,
602
+ };
603
+ }
604
+ if (listed.type !== 'tree') {
605
+ return { kind: 'absent' };
606
+ }
607
+ }
608
+ return listOne(repoRoot, ref, relativePath);
609
+ }
610
+ /** One `ls-tree` listing of exactly this path. */
611
+ function listOne(repoRoot, ref, relativePath) {
612
+ const child = runGit(repoRoot, ['ls-tree', ref, '--', `./${relativePath}`]);
330
613
  if (child.error !== undefined || child.status !== 0) {
331
- return null;
614
+ return { kind: 'error', detail: `cannot list ${relativePath} at "${ref}": ${gitComplaint(child)}` };
332
615
  }
333
- const line = (child.stdout ?? '').split('\n').find((entry) => entry.trim().length > 0);
616
+ const line = child.stdout.split('\n').find((entry) => entry.trim().length > 0);
334
617
  if (line === undefined) {
335
- return null;
618
+ return { kind: 'absent' };
336
619
  }
337
620
  const [mode, type, sha] = line.split(/\s+/);
338
621
  if (mode === undefined || type === undefined || sha === undefined) {
339
- return null;
622
+ return { kind: 'error', detail: `cannot read the listing of ${relativePath} at "${ref}"` };
340
623
  }
341
- return { mode, type, sha };
624
+ return { kind: 'entry', mode, type, sha };
342
625
  }
343
626
  /** The two modes that mean an ordinary file git will hand back. */
344
627
  function isRegularFileMode(mode) {
@@ -392,7 +675,9 @@ function treeShaAt(repoRoot, ref, relativeDir) {
392
675
  return resolveRev(repoRoot, ref, 'tree');
393
676
  }
394
677
  const entry = treeEntryAt(repoRoot, ref, relativeDir);
395
- return entry === null || entry.type !== 'tree' ? null : entry.sha;
678
+ // Absent, unreadable or not a directory all mean "not the approved tree",
679
+ // which refuses the program: the fail-closed direction for each.
680
+ return entry.kind !== 'entry' || entry.type !== 'tree' ? null : entry.sha;
396
681
  }
397
682
  /**
398
683
  * Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
@@ -482,8 +767,16 @@ export function refuseHeadControlledProgram(repoRoot, trustBase, programPath) {
482
767
  }
483
768
  for (const candidate of candidates) {
484
769
  const relative = path.relative(repoReal, candidate).split(path.sep).join('/');
485
- const base = treeEntryAt(repoRoot, trustBase, relative);
486
- const head = treeEntryAt(repoRoot, 'HEAD', relative);
770
+ const baseEntry = treeEntryAt(repoRoot, trustBase, relative);
771
+ const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
772
+ for (const listed of [baseEntry, headEntry]) {
773
+ if (listed.kind === 'error') {
774
+ return (`the gate program at ${relative} could not be checked against "${trustBase}": ` +
775
+ `${listed.detail}. Nothing was checked by this gate.`);
776
+ }
777
+ }
778
+ const base = baseEntry.kind === 'entry' ? baseEntry : null;
779
+ const head = headEntry.kind === 'entry' ? headEntry : null;
487
780
  if (base === null || head === null) {
488
781
  return (`the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not track the gate program ` +
489
782
  `at ${relative}, so it is a file this pull request controls and running it would let the ` +
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.7.0",
3
+ "version": "0.8.1",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [