@vaultcompass/conductor 0.15.0 → 0.17.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.
@@ -325,11 +325,16 @@ export function refuseTrustBaseRef(repoRoot, ref) {
325
325
  if (parents.length >= 2 && parents[0] === base) {
326
326
  return null;
327
327
  }
328
+ // Still could-not-run: nothing was compared, so nothing here is a pass.
329
+ // But the usual cause is benign and the reader should be told so, rather
330
+ // than sent to fix a workflow that is not broken.
328
331
  return (`refusing "${ref}" as the trust base: it is a different commit from HEAD but carries an ` +
329
332
  `identical tree (${headTree}), so the policy would come from the tree being judged and ` +
330
- 'there would be nothing for pull-request mode to compare. A pull request merge ref looks ' +
331
- 'exactly like this when the base has not moved. Pass the base branch (for example ' +
332
- 'origin/main), not the head or merge commit. Nothing was checked.');
333
+ 'there would be nothing for pull-request mode to compare. Likely cause: the base already ' +
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.');
333
338
  }
334
339
  return null;
335
340
  }
@@ -672,6 +677,16 @@ function realOrNull(candidate) {
672
677
  return null;
673
678
  }
674
679
  }
680
+ /** Whether anything at all, a dangling link included, is at `candidate`. */
681
+ function existsOnDisk(candidate) {
682
+ try {
683
+ lstatSync(candidate);
684
+ return true;
685
+ }
686
+ catch {
687
+ return false;
688
+ }
689
+ }
675
690
  /** Whether `candidate` is the working tree or something under it. */
676
691
  function insideWorkingTree(repoReal, candidate) {
677
692
  const relative = path.relative(repoReal, candidate);
@@ -693,6 +708,132 @@ function withResolvedParent(candidate) {
693
708
  const parent = path.dirname(candidate);
694
709
  return path.join(realOrNull(parent) ?? parent, path.basename(candidate));
695
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
+ }
696
837
  /**
697
838
  * The tree object id of one directory at a ref, or null.
698
839
  *
@@ -777,14 +918,44 @@ function treeShaAt(repoRoot, ref, relativeDir) {
777
918
  * or its tree entry is a link rather than a regular file, and either refuses.
778
919
  * Vetting the target is what catches a link whose own path is outside the
779
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.
780
932
  */
781
- export function refuseHeadControlledProgram(repoRoot, trustBase, programPath) {
933
+ export function refuseHeadControlledProgram(repoRoot, trustBase, programPath,
934
+ /** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
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:") {
782
938
  const repoReal = realOrNull(repoRoot);
783
939
  if (repoReal === null) {
784
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.`;
785
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
+ }
786
953
  const candidates = new Set();
787
- 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
+ ]) {
788
959
  if (candidate !== null && insideWorkingTree(repoReal, candidate)) {
789
960
  candidates.add(candidate);
790
961
  }
@@ -806,6 +977,25 @@ export function refuseHeadControlledProgram(repoRoot, trustBase, programPath) {
806
977
  }
807
978
  const base = baseEntry.kind === 'entry' ? baseEntry : null;
808
979
  const head = headEntry.kind === 'entry' ? headEntry : null;
980
+ // An interpreter's args entry is named as a file in args:, never as "the
981
+ // gate program": it may be a script or a file a script reads (review
982
+ // 2026-10-28, N-f, which the first N1 round fixed for the root only).
983
+ if (fromArgs && (base === null || head === null)) {
984
+ return (`in ${list}, the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not ` +
985
+ `track ${relative}, a file named there or one an interpreter could load for it, so it is ` +
986
+ 'a file this pull request controls, vetted as code. Land it on the base branch first, or ' +
987
+ 'name a script outside the repository. Nothing was checked by this gate.');
988
+ }
989
+ if (fromArgs && (!isRegularFileMode(base.mode) || !isRegularFileMode(head.mode))) {
990
+ return (`in ${list}, the file ${relative} is not a regular file at both "${trustBase}" ` +
991
+ 'and the head commit, so what an interpreter would load is decided by something other ' +
992
+ 'than the approved bytes. Nothing was checked by this gate.');
993
+ }
994
+ if (fromArgs && base.sha !== head.sha) {
995
+ return (`in ${list}, the file ${relative} is not the one "${trustBase}" approved: this ` +
996
+ 'pull request changes it, and it is vetted as code an interpreter could load. Land the ' +
997
+ 'change on the base branch first. Nothing was checked by this gate.');
998
+ }
809
999
  if (base === null || head === null) {
810
1000
  return (`the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not track the gate program ` +
811
1001
  `at ${relative}, so it is a file this pull request controls and running it would let the ` +
@@ -841,11 +1031,31 @@ export function refuseHeadControlledProgram(repoRoot, trustBase, programPath) {
841
1031
  // differs, which is every pull request. Refusing with the remedy
842
1032
  // beats a rule that silently means "no pull request may change
843
1033
  // anything".
1034
+ if (fromArgs) {
1035
+ // Reached for an interpreter's args (refuseHeadControlledArgument):
1036
+ // the file may be a script or something the script reads, so it is
1037
+ // not called "the gate program", and the remedy is about the
1038
+ // command, not about vendoring (audit 2026-10-28, N1).
1039
+ return (`the file ${relative} named in ${list} is at the repository root, and it is ` +
1040
+ 'vetted as code an interpreter could load (the command is not the gate itself, or ' +
1041
+ 'the entry has a code extension): ' +
1042
+ 'the directory that would have to be unchanged is the whole repository, and this pull ' +
1043
+ `request differs from "${trustBase}" somewhere in it. Move the script into its own ` +
1044
+ 'directory, or, if the command is the gate binary under another name, point command: ' +
1045
+ 'at a file named like the gate so its args are read as data. Nothing was checked by ' +
1046
+ 'this gate.');
1047
+ }
844
1048
  return (`the gate program at ${relative} is at the repository root, so the directory that ` +
845
1049
  'would have to be unchanged for it to be trusted is the whole repository, and this ' +
846
1050
  `pull request differs from "${trustBase}" somewhere in it. Move a vendored gate into ` +
847
1051
  'its own directory, or install it on PATH. Nothing was checked by this gate.');
848
1052
  }
1053
+ if (fromArgs) {
1054
+ return (`in ${list}, a file beside ${relative} in ${directory} is not what ` +
1055
+ `"${trustBase}" approved: ${relative} is unchanged, but the directory around it is not, ` +
1056
+ 'and code an interpreter loads can load its neighbours. Land the change on the base ' +
1057
+ 'branch first, or name a script outside the repository. Nothing was checked by this gate.');
1058
+ }
849
1059
  return (`a file beside the gate program in ${directory} is not what "${trustBase}" approved: the ` +
850
1060
  `program at ${relative} is unchanged, but the directory around it is not, and a gate is ` +
851
1061
  'rarely one file. A wrapper that execs a helper beside it runs whatever this pull ' +
@@ -853,6 +1063,13 @@ export function refuseHeadControlledProgram(repoRoot, trustBase, programPath) {
853
1063
  'PATH. Nothing was checked by this gate.');
854
1064
  }
855
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
+ }
856
1073
  return null;
857
1074
  }
858
1075
  /**
@@ -919,18 +1136,32 @@ export function atLeastVersion(version, minimum) {
919
1136
  * read from disk, and a link is never followed for that, so a link is always
920
1137
  * vetted as a link.
921
1138
  */
922
- 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:") {
923
1142
  const repoReal = realOrNull(repoRoot);
924
1143
  if (repoReal === null) {
925
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.`;
926
1145
  }
927
- 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);
928
1153
  if (spellings.some((spelling) => path.relative(repoReal, spelling) === '')) {
929
- 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 ` +
930
1155
  `the whole working tree, and this pull request differs from "${trustBase}" somewhere in it. ` +
931
1156
  'conductor already hands each gate the repository it scans; name a script in its own ' +
932
1157
  'directory instead. Nothing was checked by this gate.');
933
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
+ }
934
1165
  let isDirectory;
935
1166
  try {
936
1167
  isDirectory = lstatSync(argumentPath).isDirectory();
@@ -942,7 +1173,7 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
942
1173
  isDirectory = false;
943
1174
  }
944
1175
  if (!isDirectory) {
945
- return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath);
1176
+ return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath, true, list);
946
1177
  }
947
1178
  for (const spelling of new Set(spellings)) {
948
1179
  if (!insideWorkingTree(repoReal, spelling)) {
@@ -953,18 +1184,189 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
953
1184
  const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
954
1185
  for (const listed of [baseEntry, headEntry]) {
955
1186
  if (listed.kind === 'error') {
956
- 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 ` +
957
1188
  `"${trustBase}": ${listed.detail}. Nothing was checked by this gate.`);
958
1189
  }
959
1190
  }
960
1191
  const base = baseEntry.kind === 'entry' ? baseEntry : null;
961
1192
  const head = headEntry.kind === 'entry' ? headEntry : null;
962
1193
  if (base === null || head === null || base.type !== 'tree' || head.type !== 'tree' || base.sha !== head.sha) {
963
- 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: ` +
964
1195
  'this pull request adds, removes or changes something in it, and an interpreter handed a ' +
965
1196
  'directory runs what is inside. Land the change on the base branch first, or name a ' +
966
1197
  'script outside the repository. Nothing was checked by this gate.');
967
1198
  }
968
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
+ }
1207
+ return null;
1208
+ }
1209
+ /**
1210
+ * Why a path a gate's own `args:` name cannot be trusted on a pull-request
1211
+ * run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
1212
+ *
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
1216
+ * `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
1217
+ * `--corpus-dir`, is read as data, not loaded as code. Its contents still
1218
+ * decide what the gate reports, so a pull request that rewrote them would
1219
+ * choose the rules that judge it; but nothing beside a file runs, so a
1220
+ * file's directory is not compared and a file at the repository root is
1221
+ * fine.
1222
+ *
1223
+ * WHAT THE PATH IS COMES FROM THE BASE TREE, never from the head's disk, so a
1224
+ * head cannot delete a path or turn a file into a directory to change which
1225
+ * rule applies:
1226
+ *
1227
+ * - Outside the working tree, by its own spelling and by its realpath:
1228
+ * accepted, as for a program.
1229
+ * - The repository root: accepted as a POSITIONAL entry (`scan .`, the
1230
+ * repository the gate is handed anyway, which is the thing being judged
1231
+ * and cannot be the base's on any pull request), refused as an OPTION
1232
+ * VALUE (`--corpus-dir=.` would make the whole head tree the rules).
1233
+ * - A tree at the base: a positional entry is a scan target and is not
1234
+ * compared (the head's version of it is what the gate is there to judge).
1235
+ * An option value is data: the head must hold a tree with the same tree
1236
+ * object id, or it is refused.
1237
+ * - A blob at the base: a tracked regular file at both refs with the same
1238
+ * blob, whatever its position. An in-tree link is refused on its own entry
1239
+ * (a link entry), as everywhere else, because what it points at is the
1240
+ * head's choice. A head that deleted it or replaced it is refused.
1241
+ * - Absent at the base: accepted only if the head has nothing there either,
1242
+ * tracked or on disk (a word that is not a path, `--format=json`);
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.
1252
+ *
1253
+ * Only whether something exists on disk at a path the base does not track is
1254
+ * read from the working tree; every other answer is a `git ls-tree` listing.
1255
+ */
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:";
1261
+ const repoReal = realOrNull(repoRoot);
1262
+ if (repoReal === null) {
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.`;
1264
+ }
1265
+ const dataPath = data.path;
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);
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
+ }
1293
+ if (spellings.some((spelling) => path.relative(repoReal, spelling) === '')) {
1294
+ if (data.positional) {
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);
1300
+ }
1301
+ // The entry as written, never the absolute checkout path, which would
1302
+ // reach the pull-request comment and SARIF; and the remedy for the common
1303
+ // case, a scan target written after a flag, first (re-review R1).
1304
+ return (`${list} give the repository root (${data.entry ?? '.'}) as an option's value, so ` +
1305
+ `the whole working tree would be data the gate reads, and this pull request differs from ` +
1306
+ `${baseName} somewhere in it. If it is the scan target written after a flag, move it before ` +
1307
+ 'the flags, where it reads as a positional; otherwise give that option a directory of its ' +
1308
+ 'own. Nothing was checked by this gate.');
1309
+ }
1310
+ const candidates = new Set();
1311
+ for (const candidate of spellings) {
1312
+ if (insideWorkingTree(repoReal, candidate)) {
1313
+ candidates.add(candidate);
1314
+ }
1315
+ }
1316
+ for (const candidate of candidates) {
1317
+ const relative = path.relative(repoReal, candidate).split(path.sep).join('/');
1318
+ const baseEntry = treeEntryAt(repoRoot, trustBase, relative);
1319
+ const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
1320
+ for (const listed of [baseEntry, headEntry]) {
1321
+ if (listed.kind === 'error') {
1322
+ return (`the file ${relative} named in ${list} could not be checked against ${baseName}: ` +
1323
+ `${listed.detail}. Nothing was checked by this gate.`);
1324
+ }
1325
+ }
1326
+ const base = baseEntry.kind === 'entry' ? baseEntry : null;
1327
+ const head = headEntry.kind === 'entry' ? headEntry : null;
1328
+ if (base === null) {
1329
+ if (head === null && !existsOnDisk(candidate)) {
1330
+ // Names nothing at either side: a word, not a path.
1331
+ continue;
1332
+ }
1333
+ return (`the file ${relative} named in ${list} is not tracked at ${baseName} and the head ` +
1334
+ 'commit both, so the gate would read a path this pull request chose. Commit it on the base ' +
1335
+ 'branch first, or name a file outside the repository. Nothing was checked by this gate.');
1336
+ }
1337
+ if (base.type === 'tree') {
1338
+ if (data.positional) {
1339
+ // A scan target: the head's version of it is what the gate judges.
1340
+ continue;
1341
+ }
1342
+ if (head === null || head.type !== 'tree' || head.sha !== base.sha) {
1343
+ return (`the directory ${relative} named in ${list} is not what ${baseName} approved: ` +
1344
+ 'this pull request adds, removes or changes something in it, and it is given as an ' +
1345
+ "option's value, so the gate reads it as data, such as a rules directory " +
1346
+ '(dep-guard --corpus-dir). Land the change on the base branch first. If it is a scan ' +
1347
+ 'target written after a flag, move it before the flags, where it reads as a positional ' +
1348
+ 'and is not compared. Nothing was checked by this gate.');
1349
+ }
1350
+ continue;
1351
+ }
1352
+ if (head === null || !isRegularFileMode(base.mode) || !isRegularFileMode(head.mode)) {
1353
+ return (`the file ${relative} named in ${list} is not a regular file at both ${baseName} ` +
1354
+ 'and the head commit, so what the gate would read is decided by something other than the ' +
1355
+ 'approved bytes. Name the file itself. Nothing was checked by this gate.');
1356
+ }
1357
+ if (base.sha !== head.sha) {
1358
+ return (`the file ${relative} named in ${list} is not the one ${baseName} approved: this ` +
1359
+ 'pull request changes it, and the gate reads it, so running the gate would let the pull ' +
1360
+ 'request choose the rules that judge it. Land the change on the base branch first. ' +
1361
+ 'Nothing was checked by this gate.');
1362
+ }
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
+ }
969
1371
  return null;
970
1372
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.15.0",
3
+ "version": "0.17.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [