@vaultcompass/conductor 0.14.0 → 0.16.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.
@@ -71,7 +71,7 @@
71
71
  // RUN proceeds, so the caller can still learn the trees matched
72
72
  // (`headTreeEqualsBase` below) and run only the gates whose input is
73
73
  // history rather than the tree.
74
- import { realpathSync } from 'node:fs';
74
+ import { lstatSync, realpathSync } from 'node:fs';
75
75
  import path from 'node:path';
76
76
  import { parse as parseYaml } from 'yaml';
77
77
  import { gitComplaint, runGit, runGitBytes } from './git.js';
@@ -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);
@@ -778,7 +793,9 @@ function treeShaAt(repoRoot, ref, relativeDir) {
778
793
  * Vetting the target is what catches a link whose own path is outside the
779
794
  * tree pointing into it; it never decides the in-repo case.
780
795
  */
781
- export function refuseHeadControlledProgram(repoRoot, trustBase, programPath) {
796
+ export function refuseHeadControlledProgram(repoRoot, trustBase, programPath,
797
+ /** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
798
+ fromArgs = false) {
782
799
  const repoReal = realOrNull(repoRoot);
783
800
  if (repoReal === null) {
784
801
  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.`;
@@ -806,6 +823,25 @@ export function refuseHeadControlledProgram(repoRoot, trustBase, programPath) {
806
823
  }
807
824
  const base = baseEntry.kind === 'entry' ? baseEntry : null;
808
825
  const head = headEntry.kind === 'entry' ? headEntry : null;
826
+ // An interpreter's args entry is named as a file in args:, never as "the
827
+ // gate program": it may be a script or a file a script reads (review
828
+ // 2026-10-28, N-f, which the first N1 round fixed for the root only).
829
+ if (fromArgs && (base === null || head === null)) {
830
+ return (`in the gate's args:, the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not ` +
831
+ `track ${relative}, a file named there or one an interpreter could load for it, so it is ` +
832
+ 'a file this pull request controls, vetted as code. Land it on the base branch first, or ' +
833
+ 'name a script outside the repository. Nothing was checked by this gate.');
834
+ }
835
+ 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}" ` +
837
+ 'and the head commit, so what an interpreter would load is decided by something other ' +
838
+ 'than the approved bytes. Nothing was checked by this gate.');
839
+ }
840
+ if (fromArgs && base.sha !== head.sha) {
841
+ return (`in the gate's args:, the file ${relative} is not the one "${trustBase}" approved: this ` +
842
+ 'pull request changes it, and it is vetted as code an interpreter could load. Land the ' +
843
+ 'change on the base branch first. Nothing was checked by this gate.');
844
+ }
809
845
  if (base === null || head === null) {
810
846
  return (`the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not track the gate program ` +
811
847
  `at ${relative}, so it is a file this pull request controls and running it would let the ` +
@@ -841,11 +877,31 @@ export function refuseHeadControlledProgram(repoRoot, trustBase, programPath) {
841
877
  // differs, which is every pull request. Refusing with the remedy
842
878
  // beats a rule that silently means "no pull request may change
843
879
  // anything".
880
+ if (fromArgs) {
881
+ // Reached for an interpreter's args (refuseHeadControlledArgument):
882
+ // the file may be a script or something the script reads, so it is
883
+ // not called "the gate program", and the remedy is about the
884
+ // 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 ` +
886
+ 'vetted as code an interpreter could load (the command is not the gate itself, or ' +
887
+ 'the entry has a code extension): ' +
888
+ 'the directory that would have to be unchanged is the whole repository, and this pull ' +
889
+ `request differs from "${trustBase}" somewhere in it. Move the script into its own ` +
890
+ 'directory, or, if the command is the gate binary under another name, point command: ' +
891
+ 'at a file named like the gate so its args are read as data. Nothing was checked by ' +
892
+ 'this gate.');
893
+ }
844
894
  return (`the gate program at ${relative} is at the repository root, so the directory that ` +
845
895
  'would have to be unchanged for it to be trusted is the whole repository, and this ' +
846
896
  `pull request differs from "${trustBase}" somewhere in it. Move a vendored gate into ` +
847
897
  'its own directory, or install it on PATH. Nothing was checked by this gate.');
848
898
  }
899
+ if (fromArgs) {
900
+ return (`in the gate's args:, a file beside ${relative} in ${directory} is not what ` +
901
+ `"${trustBase}" approved: ${relative} is unchanged, but the directory around it is not, ` +
902
+ 'and code an interpreter loads can load its neighbours. Land the change on the base ' +
903
+ 'branch first, or name a script outside the repository. Nothing was checked by this gate.');
904
+ }
849
905
  return (`a file beside the gate program in ${directory} is not what "${trustBase}" approved: the ` +
850
906
  `program at ${relative} is unchanged, but the directory around it is not, and a gate is ` +
851
907
  'rarely one file. A wrapper that execs a helper beside it runs whatever this pull ' +
@@ -886,3 +942,200 @@ export function atLeastVersion(version, minimum) {
886
942
  }
887
943
  return true;
888
944
  }
945
+ /**
946
+ * Why a path named in a gate's `args:` cannot be trusted on a pull-request
947
+ * run, or null (audit 2026-10-27, B1).
948
+ *
949
+ * An interpreter `command:` takes the program as an argument: with
950
+ * `command: /usr/bin/node` and `args: [tools/gate/run.mjs, scan]` the script
951
+ * judges and Node only runs it, so vetting `command:` alone let a pull request
952
+ * rewrite the script and choose its own judge. `argumentCandidates`
953
+ * (src/resolve.ts) lists every path an interpreter could load for an entry,
954
+ * the entry and each of its loadable siblings (`tools/gate.js` beside
955
+ * `tools/gate/`), and each one is asked here separately; this decides
956
+ * whether that one path is the base's.
957
+ *
958
+ * - A FILE, or a symlink of any kind, goes through refuseHeadControlledProgram
959
+ * unchanged: blob and containing directory identical at both refs, an
960
+ * in-tree link refused on its own entry, the root refused, anything outside
961
+ * the tree accepted. The same rule as a `command:`, because it is the same
962
+ * question.
963
+ * - A DIRECTORY inside the tree is accepted only when it is a tracked tree
964
+ * at both refs with the same tree object id: when no sibling file wins,
965
+ * an interpreter handed a directory (`node tools/gate`) runs what is
966
+ * inside it, so the whole subtree is the unit, as it is beside a program.
967
+ * A sibling file that would win is a separate candidate, vetted as a file.
968
+ * - THE REPOSITORY ROOT ITSELF is refused (`node .` runs the head's own
969
+ * package.json main). Approving it would mean comparing the whole tree,
970
+ * which differs on every pull request; conductor already hands every gate
971
+ * the repository it scans, so no gate needs the root in `args:`.
972
+ *
973
+ * NOTHING HERE READS THE WORKING TREE's CONTENTS, as for the program: both
974
+ * sides are `git ls-tree` listings. Only whether the entry is a directory is
975
+ * read from disk, and a link is never followed for that, so a link is always
976
+ * vetted as a link.
977
+ */
978
+ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath) {
979
+ const repoReal = realOrNull(repoRoot);
980
+ if (repoReal === null) {
981
+ 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
+ }
983
+ const spellings = [withResolvedParent(argumentPath), realOrNull(argumentPath)].filter((spelling) => spelling !== null);
984
+ 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 ` +
986
+ `the whole working tree, and this pull request differs from "${trustBase}" somewhere in it. ` +
987
+ 'conductor already hands each gate the repository it scans; name a script in its own ' +
988
+ 'directory instead. Nothing was checked by this gate.');
989
+ }
990
+ let isDirectory;
991
+ try {
992
+ isDirectory = lstatSync(argumentPath).isDirectory();
993
+ }
994
+ catch {
995
+ // Gone between resolution and now: nothing for a child to run from here,
996
+ // and nothing for the program rule to approve either. Asking it anyway
997
+ // is the fail-closed direction, since an untracked or absent path refuses.
998
+ isDirectory = false;
999
+ }
1000
+ if (!isDirectory) {
1001
+ return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath, true);
1002
+ }
1003
+ for (const spelling of new Set(spellings)) {
1004
+ if (!insideWorkingTree(repoReal, spelling)) {
1005
+ continue;
1006
+ }
1007
+ const relative = path.relative(repoReal, spelling).split(path.sep).join('/');
1008
+ const baseEntry = treeEntryAt(repoRoot, trustBase, relative);
1009
+ const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
1010
+ for (const listed of [baseEntry, headEntry]) {
1011
+ if (listed.kind === 'error') {
1012
+ return (`the directory ${relative} named in the gate's args: could not be checked against ` +
1013
+ `"${trustBase}": ${listed.detail}. Nothing was checked by this gate.`);
1014
+ }
1015
+ }
1016
+ const base = baseEntry.kind === 'entry' ? baseEntry : null;
1017
+ const head = headEntry.kind === 'entry' ? headEntry : null;
1018
+ 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: ` +
1020
+ 'this pull request adds, removes or changes something in it, and an interpreter handed a ' +
1021
+ 'directory runs what is inside. Land the change on the base branch first, or name a ' +
1022
+ 'script outside the repository. Nothing was checked by this gate.');
1023
+ }
1024
+ }
1025
+ return null;
1026
+ }
1027
+ /**
1028
+ * Why a path a gate's own `args:` name cannot be trusted on a pull-request
1029
+ * run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
1030
+ *
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
1033
+ * `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
1034
+ * `--corpus-dir`, is read as data, not loaded as code. Its contents still
1035
+ * decide what the gate reports, so a pull request that rewrote them would
1036
+ * choose the rules that judge it; but nothing beside a file runs, so a
1037
+ * file's directory is not compared and a file at the repository root is
1038
+ * fine.
1039
+ *
1040
+ * WHAT THE PATH IS COMES FROM THE BASE TREE, never from the head's disk, so a
1041
+ * head cannot delete a path or turn a file into a directory to change which
1042
+ * rule applies:
1043
+ *
1044
+ * - Outside the working tree, by its own spelling and by its realpath:
1045
+ * accepted, as for a program.
1046
+ * - The repository root: accepted as a POSITIONAL entry (`scan .`, the
1047
+ * repository the gate is handed anyway, which is the thing being judged
1048
+ * and cannot be the base's on any pull request), refused as an OPTION
1049
+ * VALUE (`--corpus-dir=.` would make the whole head tree the rules).
1050
+ * - A tree at the base: a positional entry is a scan target and is not
1051
+ * compared (the head's version of it is what the gate is there to judge).
1052
+ * An option value is data: the head must hold a tree with the same tree
1053
+ * object id, or it is refused.
1054
+ * - A blob at the base: a tracked regular file at both refs with the same
1055
+ * blob, whatever its position. An in-tree link is refused on its own entry
1056
+ * (a link entry), as everywhere else, because what it points at is the
1057
+ * head's choice. A head that deleted it or replaced it is refused.
1058
+ * - Absent at the base: accepted only if the head has nothing there either,
1059
+ * tracked or on disk (a word that is not a path, `--format=json`);
1060
+ * otherwise it is a path this pull request chose, and refused.
1061
+ *
1062
+ * Only whether something exists on disk at a path the base does not track is
1063
+ * read from the working tree; every other answer is a `git ls-tree` listing.
1064
+ */
1065
+ export function refuseHeadControlledData(repoRoot, trustBase, data) {
1066
+ const repoReal = realOrNull(repoRoot);
1067
+ 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.`;
1069
+ }
1070
+ const dataPath = data.path;
1071
+ const spellings = [withResolvedParent(dataPath), realOrNull(dataPath)].filter((spelling) => spelling !== null);
1072
+ const baseName = trustBase === '' ? 'the base' : `"${trustBase}"`;
1073
+ if (spellings.some((spelling) => path.relative(repoReal, spelling) === '')) {
1074
+ if (data.positional) {
1075
+ return null;
1076
+ }
1077
+ // The entry as written, never the absolute checkout path, which would
1078
+ // reach the pull-request comment and SARIF; and the remedy for the common
1079
+ // 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 ` +
1081
+ `the whole working tree would be data the gate reads, and this pull request differs from ` +
1082
+ `${baseName} somewhere in it. If it is the scan target written after a flag, move it before ` +
1083
+ 'the flags, where it reads as a positional; otherwise give that option a directory of its ' +
1084
+ 'own. Nothing was checked by this gate.');
1085
+ }
1086
+ const candidates = new Set();
1087
+ for (const candidate of spellings) {
1088
+ if (insideWorkingTree(repoReal, candidate)) {
1089
+ candidates.add(candidate);
1090
+ }
1091
+ }
1092
+ for (const candidate of candidates) {
1093
+ const relative = path.relative(repoReal, candidate).split(path.sep).join('/');
1094
+ const baseEntry = treeEntryAt(repoRoot, trustBase, relative);
1095
+ const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
1096
+ for (const listed of [baseEntry, headEntry]) {
1097
+ if (listed.kind === 'error') {
1098
+ return (`the file ${relative} named in the gate's args: could not be checked against ${baseName}: ` +
1099
+ `${listed.detail}. Nothing was checked by this gate.`);
1100
+ }
1101
+ }
1102
+ const base = baseEntry.kind === 'entry' ? baseEntry : null;
1103
+ const head = headEntry.kind === 'entry' ? headEntry : null;
1104
+ if (base === null) {
1105
+ if (head === null && !existsOnDisk(candidate)) {
1106
+ // Names nothing at either side: a word, not a path.
1107
+ continue;
1108
+ }
1109
+ return (`the file ${relative} named in the gate's args: is not tracked at ${baseName} and the head ` +
1110
+ 'commit both, so the gate would read a path this pull request chose. Commit it on the base ' +
1111
+ 'branch first, or name a file outside the repository. Nothing was checked by this gate.');
1112
+ }
1113
+ if (base.type === 'tree') {
1114
+ if (data.positional) {
1115
+ // A scan target: the head's version of it is what the gate judges.
1116
+ continue;
1117
+ }
1118
+ 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: ` +
1120
+ 'this pull request adds, removes or changes something in it, and it is given as an ' +
1121
+ "option's value, so the gate reads it as data, such as a rules directory " +
1122
+ '(dep-guard --corpus-dir). Land the change on the base branch first. If it is a scan ' +
1123
+ 'target written after a flag, move it before the flags, where it reads as a positional ' +
1124
+ 'and is not compared. Nothing was checked by this gate.');
1125
+ }
1126
+ continue;
1127
+ }
1128
+ 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} ` +
1130
+ 'and the head commit, so what the gate would read is decided by something other than the ' +
1131
+ 'approved bytes. Name the file itself. Nothing was checked by this gate.');
1132
+ }
1133
+ if (base.sha !== head.sha) {
1134
+ return (`the file ${relative} named in the gate's args: is not the one ${baseName} approved: this ` +
1135
+ 'pull request changes it, and the gate reads it, so running the gate would let the pull ' +
1136
+ 'request choose the rules that judge it. Land the change on the base branch first. ' +
1137
+ 'Nothing was checked by this gate.');
1138
+ }
1139
+ }
1140
+ return null;
1141
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.14.0",
3
+ "version": "0.16.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [