@vaultcompass/conductor 0.16.0 → 0.18.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.
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * The private, fully spelled ref the composite action fetches the base branch
3
- * into (action.yml, gates step). Nothing else writes it and no short name can
4
- * shadow it: git resolves a short name like origin/main through refs/tags/
5
- * BEFORE refs/remotes/, so a tag pushed by anyone able to push tags would
6
- * otherwise choose the commit the rules are read from.
3
+ * into, or moves to the merge ref's first parent on issue 159's one shape
4
+ * (action.yml, fetch-base step). Nothing else writes it and no short name can
5
+ * shadow it: git resolves origin/main through refs/tags/ BEFORE refs/remotes/,
6
+ * so a tag pushed by anyone able to push tags would choose the rules' commit.
7
7
  */
8
8
  export declare const PRIVATE_TRUST_BASE_REF = "refs/conductor/trust-base";
9
9
  /** What a fully spelled ref names: nothing, an object, or an answer git could not give. */
@@ -120,8 +120,8 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
120
120
  * else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
121
121
  * a platform that never sets it. When it is set, the given ref is accepted
122
122
  * only when it is the FULL COMMIT ID the composite action's "Fetch the trust
123
- * base" step published (which must equal refs/conductor/trust-base, the
124
- * authority, or refs/remotes/origin/<githubBaseRef>, both read with show-ref),
123
+ * base" step published, the tip or on one shape its first parent (it must equal
124
+ * refs/conductor/trust-base, the authority, or refs/remotes/origin/<githubBaseRef>, both via show-ref),
125
125
  * or is that private ref itself, or -- for an explicit trust base -- resolves
126
126
  * to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
127
127
  * pull-request run through the action returns null here, before
@@ -253,6 +253,12 @@ export type TreeEntry = {
253
253
  * decided outside the tree, so it is an error, never absent.
254
254
  */
255
255
  export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): TreeEntry;
256
+ /**
257
+ * Whether `candidate`, as written, names the working tree or something in it
258
+ * (writtenRelative). For the preview's outright refusals, so a base path
259
+ * written inside the tree is refused there even when a link on it points out.
260
+ */
261
+ export declare function writtenInsideWorkingTree(repoRoot: string, candidate: string): boolean;
256
262
  /**
257
263
  * Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
258
264
  *
@@ -322,10 +328,23 @@ export declare function treeEntryAt(repoRoot: string, ref: string, relativePath:
322
328
  * or its tree entry is a link rather than a regular file, and either refuses.
323
329
  * Vetting the target is what catches a link whose own path is outside the
324
330
  * tree pointing into it; it never decides the in-repo case.
331
+ *
332
+ * AND THE PATH AS WRITTEN, for this rule and for both args rules below
333
+ * (audit 2026-11-01, MB2). Both spellings above resolve the directories on
334
+ * the path through the head's disk, so a head that replaced `tools/` with a
335
+ * link to a base-tracked `stub/` had `tools/vault-guard` judged as
336
+ * `stub/vault-guard`, which the base approved. So the path is also judged
337
+ * exactly as written inside the tree (writtenRelative): refused when HEAD's
338
+ * tree holds any directory on it as a link (linkOnWrittenPathAtHead), and
339
+ * the written path is one more candidate, judged by its own entries at both
340
+ * refs like the others. A link the base already had there is refused too:
341
+ * what the gate is handed through it is still decided by the head tree.
325
342
  */
326
343
  export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string,
327
344
  /** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
328
- fromArgs?: boolean): string | null;
345
+ fromArgs?: boolean,
346
+ /** Which policy list an argument came from, for its refusals: `args:`, or `options:` for a code-extension option value. */
347
+ list?: string): string | null;
329
348
  /**
330
349
  * Whether a gate's reported version is at least `minimum`.
331
350
  *
@@ -371,13 +390,16 @@ export declare function atLeastVersion(version: string | null, minimum: string):
371
390
  * read from disk, and a link is never followed for that, so a link is always
372
391
  * vetted as a link.
373
392
  */
374
- export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string): string | null;
393
+ export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string,
394
+ /** Which policy list the path came from, for the refusals: `args:`, or `options:` for a code-extension option value. */
395
+ list?: string): string | null;
375
396
  /**
376
397
  * Why a path a gate's own `args:` name cannot be trusted on a pull-request
377
398
  * run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
378
399
  *
379
- * Asked only when `command:` is the gate itself (dataArgumentPaths in
380
- * src/resolve.ts), whose args are its own argv: a rules file such as
400
+ * Asked for the args of a `command:` that is the gate itself, and for the
401
+ * `options:` values of every gate (dataArgumentPaths in src/resolve.ts),
402
+ * since both are the gate's own argv: a rules file such as
381
403
  * `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
382
404
  * `--corpus-dir`, is read as data, not loaded as code. Its contents still
383
405
  * decide what the gate reports, so a pull request that rewrote them would
@@ -406,6 +428,14 @@ export declare function refuseHeadControlledArgument(repoRoot: string, trustBase
406
428
  * - Absent at the base: accepted only if the head has nothing there either,
407
429
  * tracked or on disk (a word that is not a path, `--format=json`);
408
430
  * otherwise it is a path this pull request chose, and refused.
431
+ * - AS WRITTEN as well as resolved (audit 2026-11-01, MB2): a directory on
432
+ * the written path that HEAD's tree holds as a link is refused, the
433
+ * written path is judged by the rules above like the resolved ones, and a
434
+ * positional scan target the base tracks as a directory is refused when
435
+ * HEAD holds it as a link, since that one is otherwise not compared.
436
+ * - The same for an `options:` value (audit 2026-11-01, MB1): it is
437
+ * rendered into the gate's argv and read the same way (dataArgumentPaths),
438
+ * and `from: 'options'` only changes which list the refusal names.
409
439
  *
410
440
  * Only whether something exists on disk at a path the base does not track is
411
441
  * read from the working tree; every other answer is a `git ls-tree` listing.
@@ -414,4 +444,23 @@ export declare function refuseHeadControlledData(repoRoot: string, trustBase: st
414
444
  path: string;
415
445
  positional: boolean;
416
446
  entry?: string;
447
+ from?: 'options';
417
448
  }): string | null;
449
+ /**
450
+ * The trust base with the base branch's tip to name in the report, when the
451
+ * Action moved the trust base past it. FOR DISPLAY ONLY: nothing that decides
452
+ * anything reads `baseTip`. The value comes from the environment, so it is
453
+ * honored only when the repository bears it out: a full id of a commit that is
454
+ * neither HEAD nor the trust base, with HEAD's tree, and the trust base is HEAD's
455
+ * first parent. Anything else is ignored without a word: the sentence is the only
456
+ * thing it could change, and leaving it out is true.
457
+ *
458
+ * The CLI cannot work this out alone. It sees the private ref at HEAD's first
459
+ * parent, which is also what every ordinary pull-request run looks like, and it
460
+ * never sees the tip the Action moved away from. It can only check what it is told.
461
+ */
462
+ export declare function withMovedBaseTip<T extends {
463
+ ref: string;
464
+ }>(repoRoot: string, trustBase: T, value: string | undefined): T & {
465
+ baseTip?: string;
466
+ };
@@ -77,10 +77,10 @@ import { parse as parseYaml } from 'yaml';
77
77
  import { gitComplaint, runGit, runGitBytes } from './git.js';
78
78
  /**
79
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.
80
+ * into, or moves to the merge ref's first parent on issue 159's one shape
81
+ * (action.yml, fetch-base step). Nothing else writes it and no short name can
82
+ * shadow it: git resolves origin/main through refs/tags/ BEFORE refs/remotes/,
83
+ * so a tag pushed by anyone able to push tags would choose the rules' commit.
84
84
  */
85
85
  export const PRIVATE_TRUST_BASE_REF = 'refs/conductor/trust-base';
86
86
  /**
@@ -332,9 +332,9 @@ export function refuseTrustBaseRef(repoRoot, ref) {
332
332
  `identical tree (${headTree}), so the policy would come from the tree being judged and ` +
333
333
  'there would be nothing for pull-request mode to compare. Likely cause: the base already ' +
334
334
  'carries this tree, which usually means the pull request was merged while this job was ' +
335
- 'queued; if so, nothing here needs fixing, and a later push re-runs the check. Otherwise ' +
336
- 'the trust base names the head or merge commit: pass the base branch (for example ' +
337
- 'origin/main) instead. Nothing was checked.');
335
+ 'queued. ' +
336
+ `${EQUAL_TREE_ADVICE} ` +
337
+ 'Nothing was checked.');
338
338
  }
339
339
  return null;
340
340
  }
@@ -360,8 +360,8 @@ export function refuseTrustBaseRef(repoRoot, ref) {
360
360
  * else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
361
361
  * a platform that never sets it. When it is set, the given ref is accepted
362
362
  * only when it is the FULL COMMIT ID the composite action's "Fetch the trust
363
- * base" step published (which must equal refs/conductor/trust-base, the
364
- * authority, or refs/remotes/origin/<githubBaseRef>, both read with show-ref),
363
+ * base" step published, the tip or on one shape its first parent (it must equal
364
+ * refs/conductor/trust-base, the authority, or refs/remotes/origin/<githubBaseRef>, both via show-ref),
365
365
  * or is that private ref itself, or -- for an explicit trust base -- resolves
366
366
  * to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
367
367
  * pull-request run through the action returns null here, before
@@ -708,6 +708,132 @@ function withResolvedParent(candidate) {
708
708
  const parent = path.dirname(candidate);
709
709
  return path.join(realOrNull(parent) ?? parent, path.basename(candidate));
710
710
  }
711
+ /**
712
+ * A vetted path AS WRITTEN, relative to the repository root with `/`
713
+ * separators: '' for the root itself, null when the path is not in the
714
+ * working tree (audit 2026-11-01, MB2).
715
+ *
716
+ * The resolved spellings above follow every link on the path, and a link
717
+ * inside the tree is the head's to choose: a head that replaces `data/` with
718
+ * a link to a base-approved `alt/` makes `data/corpus` resolve to
719
+ * `alt/corpus`, whose tree is the base's, while the policy named
720
+ * `data/corpus`. So the components INSIDE the tree are kept exactly as
721
+ * written. Only the leading components that reach the tree are resolved: the
722
+ * shortest prefix whose real path is the root or under it, which is how a
723
+ * root spelled through a symlinked mount (a macOS temporary directory) or an
724
+ * outside link into the tree still lands inside. Components above the tree
725
+ * are the machine's, which a pull request cannot write.
726
+ */
727
+ function writtenRelative(repoReal, candidate) {
728
+ const absolute = path.resolve(candidate);
729
+ const root = path.parse(absolute).root;
730
+ const segments = absolute.slice(root.length).split(path.sep).filter((segment) => segment !== '');
731
+ for (let depth = 0; depth <= segments.length; depth += 1) {
732
+ const real = realOrNull(path.join(root, ...segments.slice(0, depth)));
733
+ if (real === null) {
734
+ // Nothing below a missing component exists either.
735
+ return null;
736
+ }
737
+ if (real === repoReal || insideWorkingTree(repoReal, real)) {
738
+ const reached = path.relative(repoReal, real).split(path.sep).filter((segment) => segment !== '');
739
+ return [...reached, ...segments.slice(depth)].join('/');
740
+ }
741
+ }
742
+ return null;
743
+ }
744
+ /**
745
+ * Whether `candidate`, as written, names the working tree or something in it
746
+ * (writtenRelative). For the preview's outright refusals, so a base path
747
+ * written inside the tree is refused there even when a link on it points out.
748
+ */
749
+ export function writtenInsideWorkingTree(repoRoot, candidate) {
750
+ const repoReal = realOrNull(repoRoot);
751
+ return repoReal !== null && writtenRelative(repoReal, candidate) !== null;
752
+ }
753
+ /**
754
+ * The first DIRECTORY component above the last one of `relative` that HEAD's
755
+ * tree holds as a symbolic link, or null (audit 2026-11-01, MB2). Read from
756
+ * `git ls-tree`, one component at a time, never from the disk. Stops,
757
+ * answering null, at a component HEAD does not have, cannot list, or holds as
758
+ * a file: what is below it is then absent or unreadable, which the rule
759
+ * asking decides. The last component is each rule's own entry, which every
760
+ * rule already refuses as a link in its own words (a positional scan target
761
+ * included, in refuseHeadControlledData).
762
+ */
763
+ function linkOnWrittenPathAtHead(repoRoot, relative) {
764
+ const segments = relative.split('/').filter((segment) => segment !== '' && segment !== '.');
765
+ for (let depth = 1; depth < segments.length; depth += 1) {
766
+ const prefix = segments.slice(0, depth).join('/');
767
+ const listed = listOne(repoRoot, 'HEAD', prefix);
768
+ if (listed.kind !== 'entry') {
769
+ return null;
770
+ }
771
+ if (listed.mode === '120000') {
772
+ return prefix;
773
+ }
774
+ if (listed.type !== 'tree') {
775
+ return null;
776
+ }
777
+ }
778
+ return null;
779
+ }
780
+ /**
781
+ * The refusal for a vetted path a link at HEAD redirects, naming the link.
782
+ * `subject` is how the rule asking names the path: "the gate program at X",
783
+ * "in the gate's args:, the path X", "the path X named in the gate's args:".
784
+ */
785
+ function linkOnWrittenPathRefusal(subject, link, baseName) {
786
+ return (`${subject} goes through ${link}, which is a symbolic link at the head commit, so this pull ` +
787
+ 'request changed the path it is judged by: the gate would be handed whatever that link points ' +
788
+ `at, not the path ${baseName} approved. conductor judges every path as written and follows no ` +
789
+ 'link inside the repository. Name the directory the link points at, or commit a real directory ' +
790
+ 'there on the base branch. Nothing was checked by this gate.');
791
+ }
792
+ /**
793
+ * The first component of `relative`, the last one included, that is a
794
+ * symbolic link ON DISK while HEAD's tree holds no link at that exact
795
+ * spelling, or null (review of the 2026-11-01 fix, item 1).
796
+ *
797
+ * `git ls-tree` matches names exactly, and a case-insensitive disk does not:
798
+ * a head that adds a link entry `data` beside the base's tree `Data` leaves
799
+ * only `data -> alt` on disk after a checkout, so `Data/corpus` reads the
800
+ * link's target while the tree still says `Data` is the base's directory.
801
+ * The disk is therefore asked too, and a link there that the tree does not
802
+ * declare at that spelling refuses: what the gate is handed is decided by
803
+ * something other than the tree conductor judged. A link the tree DOES
804
+ * declare is left to the checks that already refuse it. Stops at the first
805
+ * component that is missing or not a directory. Each rule asks this LAST, so
806
+ * a path its own checks refuse keeps its wording; the exception is the data
807
+ * rule's positional root, which returns early and asks this first (R1).
808
+ */
809
+ function undeclaredLinkOnDisk(repoRoot, repoReal, relative) {
810
+ const segments = relative.split('/').filter((segment) => segment !== '' && segment !== '.');
811
+ for (let depth = 1; depth <= segments.length; depth += 1) {
812
+ const prefix = segments.slice(0, depth).join('/');
813
+ let stats;
814
+ try {
815
+ stats = lstatSync(path.join(repoReal, prefix));
816
+ }
817
+ catch {
818
+ return null;
819
+ }
820
+ if (stats.isSymbolicLink()) {
821
+ const listed = listOne(repoRoot, 'HEAD', prefix);
822
+ return listed.kind === 'entry' && listed.mode === '120000' ? null : prefix;
823
+ }
824
+ if (!stats.isDirectory()) {
825
+ return null;
826
+ }
827
+ }
828
+ return null;
829
+ }
830
+ /** The refusal for a link on disk the head tree does not declare, naming it. */
831
+ function undeclaredLinkRefusal(subject, link) {
832
+ return (`${subject} goes through ${link}, which is a symbolic link on disk that the pull request's tree does not declare ` +
833
+ 'there, so what the gate would be handed is decided by something other than the tree conductor ' +
834
+ 'judged. On a case-insensitive filesystem a tree entry spelled with different case is the same ' +
835
+ 'path. Nothing was checked by this gate.');
836
+ }
711
837
  /**
712
838
  * The tree object id of one directory at a ref, or null.
713
839
  *
@@ -792,16 +918,44 @@ function treeShaAt(repoRoot, ref, relativeDir) {
792
918
  * or its tree entry is a link rather than a regular file, and either refuses.
793
919
  * Vetting the target is what catches a link whose own path is outside the
794
920
  * tree pointing into it; it never decides the in-repo case.
921
+ *
922
+ * AND THE PATH AS WRITTEN, for this rule and for both args rules below
923
+ * (audit 2026-11-01, MB2). Both spellings above resolve the directories on
924
+ * the path through the head's disk, so a head that replaced `tools/` with a
925
+ * link to a base-tracked `stub/` had `tools/vault-guard` judged as
926
+ * `stub/vault-guard`, which the base approved. So the path is also judged
927
+ * exactly as written inside the tree (writtenRelative): refused when HEAD's
928
+ * tree holds any directory on it as a link (linkOnWrittenPathAtHead), and
929
+ * the written path is one more candidate, judged by its own entries at both
930
+ * refs like the others. A link the base already had there is refused too:
931
+ * what the gate is handed through it is still decided by the head tree.
795
932
  */
796
933
  export function refuseHeadControlledProgram(repoRoot, trustBase, programPath,
797
934
  /** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
798
- fromArgs = false) {
935
+ fromArgs = false,
936
+ /** Which policy list an argument came from, for its refusals: `args:`, or `options:` for a code-extension option value. */
937
+ list = "the gate's args:") {
799
938
  const repoReal = realOrNull(repoRoot);
800
939
  if (repoReal === null) {
801
940
  return `the repository root ${repoRoot} could not be resolved, so the gate program could not be checked against "${trustBase}". Nothing was checked by this gate.`;
802
941
  }
942
+ // AS WRITTEN, before either resolved spelling (audit 2026-11-01, MB2): a
943
+ // directory on the written path that HEAD holds as a link redirects the
944
+ // program to wherever the head points it, and the written path is also a
945
+ // candidate below, judged by its own entries at both refs.
946
+ const written = writtenRelative(repoReal, programPath);
947
+ if (written !== null && written !== '') {
948
+ const link = linkOnWrittenPathAtHead(repoRoot, written);
949
+ if (link !== null) {
950
+ return linkOnWrittenPathRefusal(fromArgs ? `in ${list}, the path ${written}` : `the gate program at ${written}`, link, trustBase === '' ? 'the base' : `"${trustBase}"`);
951
+ }
952
+ }
803
953
  const candidates = new Set();
804
- for (const candidate of [withResolvedParent(programPath), realOrNull(programPath)]) {
954
+ for (const candidate of [
955
+ withResolvedParent(programPath),
956
+ realOrNull(programPath),
957
+ written === null ? null : path.join(repoReal, written),
958
+ ]) {
805
959
  if (candidate !== null && insideWorkingTree(repoReal, candidate)) {
806
960
  candidates.add(candidate);
807
961
  }
@@ -827,18 +981,18 @@ fromArgs = false) {
827
981
  // gate program": it may be a script or a file a script reads (review
828
982
  // 2026-10-28, N-f, which the first N1 round fixed for the root only).
829
983
  if (fromArgs && (base === null || head === null)) {
830
- return (`in the gate's args:, the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not ` +
984
+ return (`in ${list}, the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not ` +
831
985
  `track ${relative}, a file named there or one an interpreter could load for it, so it is ` +
832
986
  'a file this pull request controls, vetted as code. Land it on the base branch first, or ' +
833
987
  'name a script outside the repository. Nothing was checked by this gate.');
834
988
  }
835
989
  if (fromArgs && (!isRegularFileMode(base.mode) || !isRegularFileMode(head.mode))) {
836
- return (`in the gate's args:, the file ${relative} is not a regular file at both "${trustBase}" ` +
990
+ return (`in ${list}, the file ${relative} is not a regular file at both "${trustBase}" ` +
837
991
  'and the head commit, so what an interpreter would load is decided by something other ' +
838
992
  'than the approved bytes. Nothing was checked by this gate.');
839
993
  }
840
994
  if (fromArgs && base.sha !== head.sha) {
841
- return (`in the gate's args:, the file ${relative} is not the one "${trustBase}" approved: this ` +
995
+ return (`in ${list}, the file ${relative} is not the one "${trustBase}" approved: this ` +
842
996
  'pull request changes it, and it is vetted as code an interpreter could load. Land the ' +
843
997
  'change on the base branch first. Nothing was checked by this gate.');
844
998
  }
@@ -882,7 +1036,7 @@ fromArgs = false) {
882
1036
  // the file may be a script or something the script reads, so it is
883
1037
  // not called "the gate program", and the remedy is about the
884
1038
  // command, not about vendoring (audit 2026-10-28, N1).
885
- return (`the file ${relative} named in the gate's args: is at the repository root, and it is ` +
1039
+ return (`the file ${relative} named in ${list} is at the repository root, and it is ` +
886
1040
  'vetted as code an interpreter could load (the command is not the gate itself, or ' +
887
1041
  'the entry has a code extension): ' +
888
1042
  'the directory that would have to be unchanged is the whole repository, and this pull ' +
@@ -897,7 +1051,7 @@ fromArgs = false) {
897
1051
  'its own directory, or install it on PATH. Nothing was checked by this gate.');
898
1052
  }
899
1053
  if (fromArgs) {
900
- return (`in the gate's args:, a file beside ${relative} in ${directory} is not what ` +
1054
+ return (`in ${list}, a file beside ${relative} in ${directory} is not what ` +
901
1055
  `"${trustBase}" approved: ${relative} is unchanged, but the directory around it is not, ` +
902
1056
  'and code an interpreter loads can load its neighbours. Land the change on the base ' +
903
1057
  'branch first, or name a script outside the repository. Nothing was checked by this gate.');
@@ -909,6 +1063,13 @@ fromArgs = false) {
909
1063
  'PATH. Nothing was checked by this gate.');
910
1064
  }
911
1065
  }
1066
+ // LAST, the disk against the tree (review of the 2026-11-01 fix, item 1).
1067
+ if (written !== null && written !== '') {
1068
+ const undeclared = undeclaredLinkOnDisk(repoRoot, repoReal, written);
1069
+ if (undeclared !== null) {
1070
+ return undeclaredLinkRefusal(fromArgs ? `in ${list}, the path ${written}` : `the gate program at ${written}`, undeclared);
1071
+ }
1072
+ }
912
1073
  return null;
913
1074
  }
914
1075
  /**
@@ -975,18 +1136,32 @@ export function atLeastVersion(version, minimum) {
975
1136
  * read from disk, and a link is never followed for that, so a link is always
976
1137
  * vetted as a link.
977
1138
  */
978
- export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath) {
1139
+ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath,
1140
+ /** Which policy list the path came from, for the refusals: `args:`, or `options:` for a code-extension option value. */
1141
+ list = "the gate's args:") {
979
1142
  const repoReal = realOrNull(repoRoot);
980
1143
  if (repoReal === null) {
981
1144
  return `the repository root ${repoRoot} could not be resolved, so the gate arguments could not be checked against "${trustBase}". Nothing was checked by this gate.`;
982
1145
  }
983
- const spellings = [withResolvedParent(argumentPath), realOrNull(argumentPath)].filter((spelling) => spelling !== null);
1146
+ // The written spelling beside the resolved ones (audit 2026-11-01, MB2).
1147
+ const written = writtenRelative(repoReal, argumentPath);
1148
+ const spellings = [
1149
+ withResolvedParent(argumentPath),
1150
+ realOrNull(argumentPath),
1151
+ written === null ? null : path.join(repoReal, written),
1152
+ ].filter((spelling) => spelling !== null);
984
1153
  if (spellings.some((spelling) => path.relative(repoReal, spelling) === '')) {
985
- return (`the gate's args: name the repository root (${argumentPath}), so what would run is decided by ` +
1154
+ return (`${list} name the repository root (${argumentPath}), so what would run is decided by ` +
986
1155
  `the whole working tree, and this pull request differs from "${trustBase}" somewhere in it. ` +
987
1156
  'conductor already hands each gate the repository it scans; name a script in its own ' +
988
1157
  'directory instead. Nothing was checked by this gate.');
989
1158
  }
1159
+ if (written !== null) {
1160
+ const link = linkOnWrittenPathAtHead(repoRoot, written);
1161
+ if (link !== null) {
1162
+ return linkOnWrittenPathRefusal(`in ${list}, the path ${written}`, link, trustBase === '' ? 'the base' : `"${trustBase}"`);
1163
+ }
1164
+ }
990
1165
  let isDirectory;
991
1166
  try {
992
1167
  isDirectory = lstatSync(argumentPath).isDirectory();
@@ -998,7 +1173,7 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
998
1173
  isDirectory = false;
999
1174
  }
1000
1175
  if (!isDirectory) {
1001
- return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath, true);
1176
+ return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath, true, list);
1002
1177
  }
1003
1178
  for (const spelling of new Set(spellings)) {
1004
1179
  if (!insideWorkingTree(repoReal, spelling)) {
@@ -1009,27 +1184,35 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
1009
1184
  const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
1010
1185
  for (const listed of [baseEntry, headEntry]) {
1011
1186
  if (listed.kind === 'error') {
1012
- return (`the directory ${relative} named in the gate's args: could not be checked against ` +
1187
+ return (`the directory ${relative} named in ${list} could not be checked against ` +
1013
1188
  `"${trustBase}": ${listed.detail}. Nothing was checked by this gate.`);
1014
1189
  }
1015
1190
  }
1016
1191
  const base = baseEntry.kind === 'entry' ? baseEntry : null;
1017
1192
  const head = headEntry.kind === 'entry' ? headEntry : null;
1018
1193
  if (base === null || head === null || base.type !== 'tree' || head.type !== 'tree' || base.sha !== head.sha) {
1019
- return (`the directory ${relative} named in the gate's args: is not what "${trustBase}" approved: ` +
1194
+ return (`the directory ${relative} named in ${list} is not what "${trustBase}" approved: ` +
1020
1195
  'this pull request adds, removes or changes something in it, and an interpreter handed a ' +
1021
1196
  'directory runs what is inside. Land the change on the base branch first, or name a ' +
1022
1197
  'script outside the repository. Nothing was checked by this gate.');
1023
1198
  }
1024
1199
  }
1200
+ // LAST, the disk against the tree (review of the 2026-11-01 fix, item 1).
1201
+ if (written !== null) {
1202
+ const undeclared = undeclaredLinkOnDisk(repoRoot, repoReal, written);
1203
+ if (undeclared !== null) {
1204
+ return undeclaredLinkRefusal(`in ${list}, the path ${written}`, undeclared);
1205
+ }
1206
+ }
1025
1207
  return null;
1026
1208
  }
1027
1209
  /**
1028
1210
  * Why a path a gate's own `args:` name cannot be trusted on a pull-request
1029
1211
  * run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
1030
1212
  *
1031
- * Asked only when `command:` is the gate itself (dataArgumentPaths in
1032
- * src/resolve.ts), whose args are its own argv: a rules file such as
1213
+ * Asked for the args of a `command:` that is the gate itself, and for the
1214
+ * `options:` values of every gate (dataArgumentPaths in src/resolve.ts),
1215
+ * since both are the gate's own argv: a rules file such as
1033
1216
  * `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
1034
1217
  * `--corpus-dir`, is read as data, not loaded as code. Its contents still
1035
1218
  * decide what the gate reports, so a pull request that rewrote them would
@@ -1058,26 +1241,67 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
1058
1241
  * - Absent at the base: accepted only if the head has nothing there either,
1059
1242
  * tracked or on disk (a word that is not a path, `--format=json`);
1060
1243
  * otherwise it is a path this pull request chose, and refused.
1244
+ * - AS WRITTEN as well as resolved (audit 2026-11-01, MB2): a directory on
1245
+ * the written path that HEAD's tree holds as a link is refused, the
1246
+ * written path is judged by the rules above like the resolved ones, and a
1247
+ * positional scan target the base tracks as a directory is refused when
1248
+ * HEAD holds it as a link, since that one is otherwise not compared.
1249
+ * - The same for an `options:` value (audit 2026-11-01, MB1): it is
1250
+ * rendered into the gate's argv and read the same way (dataArgumentPaths),
1251
+ * and `from: 'options'` only changes which list the refusal names.
1061
1252
  *
1062
1253
  * Only whether something exists on disk at a path the base does not track is
1063
1254
  * read from the working tree; every other answer is a `git ls-tree` listing.
1064
1255
  */
1065
1256
  export function refuseHeadControlledData(repoRoot, trustBase, data) {
1257
+ // Which list of the policy the value came from, for every message below:
1258
+ // an `options:` value is rendered into the same argv and vetted the same
1259
+ // way (audit 2026-11-01, MB1).
1260
+ const list = data.from === 'options' ? "the gate's options:" : "the gate's args:";
1066
1261
  const repoReal = realOrNull(repoRoot);
1067
1262
  if (repoReal === null) {
1068
- return `the repository root ${repoRoot} could not be resolved, so the files named in the gate's args: could not be checked against "${trustBase}". Nothing was checked by this gate.`;
1263
+ return `the repository root ${repoRoot} could not be resolved, so the files named in ${list} could not be checked against "${trustBase}". Nothing was checked by this gate.`;
1069
1264
  }
1070
1265
  const dataPath = data.path;
1071
- const spellings = [withResolvedParent(dataPath), realOrNull(dataPath)].filter((spelling) => spelling !== null);
1266
+ // The written spelling beside the resolved ones (audit 2026-11-01, MB2).
1267
+ const written = writtenRelative(repoReal, dataPath);
1268
+ const spellings = [
1269
+ withResolvedParent(dataPath),
1270
+ realOrNull(dataPath),
1271
+ written === null ? null : path.join(repoReal, written),
1272
+ ].filter((spelling) => spelling !== null);
1072
1273
  const baseName = trustBase === '' ? 'the base' : `"${trustBase}"`;
1274
+ if (written !== null && written !== '') {
1275
+ const subject = `the path ${written} named in ${list}`;
1276
+ const link = linkOnWrittenPathAtHead(repoRoot, written);
1277
+ if (link !== null) {
1278
+ return linkOnWrittenPathRefusal(subject, link, baseName);
1279
+ }
1280
+ // A positional directory the base tracks is a scan target and is not
1281
+ // compared below, so its own entry is asked here: a link there hands the
1282
+ // gate wherever the head points it, possibly the root, instead of the
1283
+ // target the base named. Every other own-entry link (a file, an option
1284
+ // value) is refused below, in the words of its kind.
1285
+ if (data.positional) {
1286
+ const own = listOne(repoRoot, 'HEAD', written);
1287
+ const approved = treeEntryAt(repoRoot, trustBase, written);
1288
+ if (own.kind === 'entry' && own.mode === '120000' && approved.kind === 'entry' && approved.type === 'tree') {
1289
+ return linkOnWrittenPathRefusal(subject, written, baseName);
1290
+ }
1291
+ }
1292
+ }
1073
1293
  if (spellings.some((spelling) => path.relative(repoReal, spelling) === '')) {
1074
1294
  if (data.positional) {
1075
- return null;
1295
+ // A scan target that IS the root is accepted, so the disk check that
1296
+ // otherwise runs last runs here first: a link on disk the head tree
1297
+ // does not declare can fold a positional onto the root (review R1).
1298
+ const undeclared = written === null || written === '' ? null : undeclaredLinkOnDisk(repoRoot, repoReal, written);
1299
+ return undeclared === null ? null : undeclaredLinkRefusal(`the path ${written} named in ${list}`, undeclared);
1076
1300
  }
1077
1301
  // The entry as written, never the absolute checkout path, which would
1078
1302
  // reach the pull-request comment and SARIF; and the remedy for the common
1079
1303
  // case, a scan target written after a flag, first (re-review R1).
1080
- return (`the gate's args: give the repository root (${data.entry ?? '.'}) as an option's value, so ` +
1304
+ return (`${list} give the repository root (${data.entry ?? '.'}) as an option's value, so ` +
1081
1305
  `the whole working tree would be data the gate reads, and this pull request differs from ` +
1082
1306
  `${baseName} somewhere in it. If it is the scan target written after a flag, move it before ` +
1083
1307
  'the flags, where it reads as a positional; otherwise give that option a directory of its ' +
@@ -1095,7 +1319,7 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
1095
1319
  const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
1096
1320
  for (const listed of [baseEntry, headEntry]) {
1097
1321
  if (listed.kind === 'error') {
1098
- return (`the file ${relative} named in the gate's args: could not be checked against ${baseName}: ` +
1322
+ return (`the file ${relative} named in ${list} could not be checked against ${baseName}: ` +
1099
1323
  `${listed.detail}. Nothing was checked by this gate.`);
1100
1324
  }
1101
1325
  }
@@ -1106,7 +1330,7 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
1106
1330
  // Names nothing at either side: a word, not a path.
1107
1331
  continue;
1108
1332
  }
1109
- return (`the file ${relative} named in the gate's args: is not tracked at ${baseName} and the head ` +
1333
+ return (`the file ${relative} named in ${list} is not tracked at ${baseName} and the head ` +
1110
1334
  'commit both, so the gate would read a path this pull request chose. Commit it on the base ' +
1111
1335
  'branch first, or name a file outside the repository. Nothing was checked by this gate.');
1112
1336
  }
@@ -1116,7 +1340,7 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
1116
1340
  continue;
1117
1341
  }
1118
1342
  if (head === null || head.type !== 'tree' || head.sha !== base.sha) {
1119
- return (`the directory ${relative} named in the gate's args: is not what ${baseName} approved: ` +
1343
+ return (`the directory ${relative} named in ${list} is not what ${baseName} approved: ` +
1120
1344
  'this pull request adds, removes or changes something in it, and it is given as an ' +
1121
1345
  "option's value, so the gate reads it as data, such as a rules directory " +
1122
1346
  '(dep-guard --corpus-dir). Land the change on the base branch first. If it is a scan ' +
@@ -1126,16 +1350,55 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
1126
1350
  continue;
1127
1351
  }
1128
1352
  if (head === null || !isRegularFileMode(base.mode) || !isRegularFileMode(head.mode)) {
1129
- return (`the file ${relative} named in the gate's args: is not a regular file at both ${baseName} ` +
1353
+ return (`the file ${relative} named in ${list} is not a regular file at both ${baseName} ` +
1130
1354
  'and the head commit, so what the gate would read is decided by something other than the ' +
1131
1355
  'approved bytes. Name the file itself. Nothing was checked by this gate.');
1132
1356
  }
1133
1357
  if (base.sha !== head.sha) {
1134
- return (`the file ${relative} named in the gate's args: is not the one ${baseName} approved: this ` +
1358
+ return (`the file ${relative} named in ${list} is not the one ${baseName} approved: this ` +
1135
1359
  'pull request changes it, and the gate reads it, so running the gate would let the pull ' +
1136
1360
  'request choose the rules that judge it. Land the change on the base branch first. ' +
1137
1361
  'Nothing was checked by this gate.');
1138
1362
  }
1139
1363
  }
1364
+ // LAST, the disk against the tree (review of the 2026-11-01 fix, item 1).
1365
+ if (written !== null && written !== '') {
1366
+ const undeclared = undeclaredLinkOnDisk(repoRoot, repoReal, written);
1367
+ if (undeclared !== null) {
1368
+ return undeclaredLinkRefusal(`the path ${written} named in ${list}`, undeclared);
1369
+ }
1370
+ }
1140
1371
  return null;
1141
1372
  }
1373
+ /** What a run refused for carrying HEAD's tree tells the reader to do. */
1374
+ const EQUAL_TREE_ADVICE = 'A pull request that landed gets no later push, so nothing re-runs this check: this run stays ' +
1375
+ 'red and its changes went unchecked here. One still open re-runs on its next push. The Action judges this shape against the commit the merge ref was ' +
1376
+ 'built from only on a full clone (fetch-depth: 0) with the same control files at both commits. ' +
1377
+ 'If neither case applies, the trust base names the head or merge commit: pass the base branch ' +
1378
+ '(for example origin/main) instead.';
1379
+ /**
1380
+ * The trust base with the base branch's tip to name in the report, when the
1381
+ * Action moved the trust base past it. FOR DISPLAY ONLY: nothing that decides
1382
+ * anything reads `baseTip`. The value comes from the environment, so it is
1383
+ * honored only when the repository bears it out: a full id of a commit that is
1384
+ * neither HEAD nor the trust base, with HEAD's tree, and the trust base is HEAD's
1385
+ * first parent. Anything else is ignored without a word: the sentence is the only
1386
+ * thing it could change, and leaving it out is true.
1387
+ *
1388
+ * The CLI cannot work this out alone. It sees the private ref at HEAD's first
1389
+ * parent, which is also what every ordinary pull-request run looks like, and it
1390
+ * never sees the tip the Action moved away from. It can only check what it is told.
1391
+ */
1392
+ export function withMovedBaseTip(repoRoot, trustBase, value) {
1393
+ if (value === undefined || !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(value)) {
1394
+ return trustBase;
1395
+ }
1396
+ const base = resolveRev(repoRoot, trustBase.ref, 'commit');
1397
+ const borneOut = base !== null &&
1398
+ value !== base &&
1399
+ resolveRev(repoRoot, value, 'commit') === value &&
1400
+ value !== resolveRev(repoRoot, 'HEAD', 'commit') &&
1401
+ headTreeEqualsBase(repoRoot, value) &&
1402
+ headParents(repoRoot)[0] === base;
1403
+ return borneOut ? { ...trustBase, baseTip: value } : trustBase;
1404
+ }
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Tracked manifest-like files that were not handed to `product`, sorted, as
2
+ * Tracked dependency files that were not handed to `product`, sorted, as
3
3
  * one sentence fragment, or null when there are none.
4
4
  *
5
5
  * `handed` are the repository-relative paths the gate was actually handed,