@vaultcompass/conductor 0.15.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.
- package/README.md +152 -1184
- package/dist/gate-runner.js +19 -6
- package/dist/output-text.js +8 -0
- package/dist/resolve.d.ts +77 -14
- package/dist/resolve.js +155 -24
- package/dist/trust-base.d.ts +46 -1
- package/dist/trust-base.js +176 -5
- package/package.json +1 -1
package/dist/trust-base.js
CHANGED
|
@@ -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.
|
|
331
|
-
'
|
|
332
|
-
'
|
|
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 ' +
|
|
@@ -942,7 +998,7 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
|
|
|
942
998
|
isDirectory = false;
|
|
943
999
|
}
|
|
944
1000
|
if (!isDirectory) {
|
|
945
|
-
return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath);
|
|
1001
|
+
return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath, true);
|
|
946
1002
|
}
|
|
947
1003
|
for (const spelling of new Set(spellings)) {
|
|
948
1004
|
if (!insideWorkingTree(repoReal, spelling)) {
|
|
@@ -968,3 +1024,118 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
|
|
|
968
1024
|
}
|
|
969
1025
|
return null;
|
|
970
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
|
+
}
|