@vaultcompass/conductor 0.8.0 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -21,6 +21,7 @@ import { spawnSync } from 'node:child_process';
21
21
  import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
22
22
  import { tmpdir } from 'node:os';
23
23
  import path from 'node:path';
24
+ import { runGit } from './git.js';
24
25
  import { NormalizeError } from './envelope.js';
25
26
  import { normalizeDepGuard, normalizeFailedGate, normalizeGitleaks, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeOsvScanner, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
26
27
  import { renderOptionFlags } from './policy.js';
@@ -28,6 +29,119 @@ import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals,
28
29
  import { profileFor } from './products.js';
29
30
  import { atLeastVersion, refuseHeadControlledProgram } from './trust-base.js';
30
31
  import { ResolveError, candidateNames, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
32
+ /** The longest excerpt of a gate's own reason that is carried. */
33
+ export const GATE_SAID_MAX_CHARS = 160;
34
+ /**
35
+ * A short, plain excerpt of one line of gate output.
36
+ *
37
+ * ASCII only and one line, because the excerpt lands in a job log line, in the
38
+ * text report and in a pull-request comment: control characters, escape
39
+ * sequences and anything a terminal would interpret are replaced, whitespace is
40
+ * collapsed, workflow-command markers are broken up, double quotes become
41
+ * single quotes (the excerpt is shown inside double quotes), and the result is
42
+ * cut at GATE_SAID_MAX_CHARS.
43
+ */
44
+ function sanitizeGateSaid(raw) {
45
+ const flat = breakWorkflowMarkers(stripAnsi(raw)
46
+ .replace(/[^\x20-\x7e]/g, ' ')
47
+ .replace(/\s+/g, ' ')
48
+ .trim()).replace(/"/g, "'");
49
+ if (flat === '') {
50
+ return null;
51
+ }
52
+ return flat.length > GATE_SAID_MAX_CHARS ? `${flat.slice(0, GATE_SAID_MAX_CHARS - 3)}...` : flat;
53
+ }
54
+ /**
55
+ * Breaks up the two character sequences a CI log reader treats as a command
56
+ * ("##[" and "::") by putting a space inside them, so gate-printed text stays
57
+ * inert in a job log. Repeated until stable, so runs such as ":::" and "###["
58
+ * are covered too.
59
+ */
60
+ export function breakWorkflowMarkers(text) {
61
+ let out = text;
62
+ for (;;) {
63
+ const next = out.replace(/#(?=#\[)/g, '# ').replace(/:(?=:)/g, ': ');
64
+ if (next === out) {
65
+ return out;
66
+ }
67
+ out = next;
68
+ }
69
+ }
70
+ /**
71
+ * The could-not-run reasons that are conductor's OWN decision, made before
72
+ * the gate was spawned (or instead of spawning it), as opposed to something
73
+ * the gate itself said or did.
74
+ */
75
+ export const CONDUCTOR_OWN_REASONS = new Set([
76
+ 'preparation-failed',
77
+ 'trust-base-unverified',
78
+ 'gate-program-refused',
79
+ 'gate-version-unsupported',
80
+ 'history-shallow',
81
+ ]);
82
+ /**
83
+ * conductor's own reason for a could-not-run, as a job-log excerpt: cleaned,
84
+ * one line, capped and with double quotes replaced, exactly like a gate's
85
+ * stated reason. Null when there is nothing to print.
86
+ */
87
+ export function conductorStatedReason(detail) {
88
+ return sanitizeGateSaid(detail);
89
+ }
90
+ /**
91
+ * One line of raw gate output, made safe to print: control characters (escape
92
+ * included) become spaces and workflow-command markers are broken up. The
93
+ * content is otherwise left as it was.
94
+ */
95
+ export function cleanOutputLine(raw) {
96
+ return breakWorkflowMarkers(raw.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' '));
97
+ }
98
+ /**
99
+ * What a gate that exited with a non-verdict code said about why.
100
+ *
101
+ * TOTAL, and never a decision: the caller has already settled that this is a
102
+ * could-not-run, and nothing here can change that. The first non-empty stderr
103
+ * line is preferred, since that is where every gate in the family prints its
104
+ * reason on exit 2 (dep-guard, intent-guard and vault-guard all do). Failing
105
+ * that, stdout is parsed only for a gate whose output is JSON on stdout, and
106
+ * only a string `reason` field (top level, or on `run`) is read; anything else,
107
+ * including output that does not parse, is simply no excerpt.
108
+ */
109
+ export function gateStatedReason(stderr, stdout, stdoutIsJson) {
110
+ try {
111
+ const firstLine = stripAnsi(stderr)
112
+ .split('\n')
113
+ .map((line) => sanitizeGateSaid(line))
114
+ .find((line) => line !== null);
115
+ if (firstLine !== undefined && firstLine !== null) {
116
+ return firstLine;
117
+ }
118
+ if (!stdoutIsJson || typeof stdout !== 'string' || !stdout.trimStart().startsWith('{')) {
119
+ return null;
120
+ }
121
+ const parsed = JSON.parse(stdout);
122
+ if (typeof parsed !== 'object' || parsed === null) {
123
+ return null;
124
+ }
125
+ const record = parsed;
126
+ const run = record.run;
127
+ const candidates = [
128
+ record.reason,
129
+ typeof run === 'object' && run !== null ? run.reason : undefined,
130
+ ];
131
+ for (const candidate of candidates) {
132
+ if (typeof candidate === 'string') {
133
+ const excerpt = sanitizeGateSaid(candidate);
134
+ if (excerpt !== null) {
135
+ return excerpt;
136
+ }
137
+ }
138
+ }
139
+ return null;
140
+ }
141
+ catch {
142
+ return null;
143
+ }
144
+ }
31
145
  /**
32
146
  * The first version of each gate that understands `--trust-base`.
33
147
  *
@@ -36,10 +150,11 @@ import { ResolveError, candidateNames, nodeModulesCandidate, resolveGateBinary,
36
150
  * against every combination in the meantime. A product missing from this
37
151
  * table has no pull-request mode yet and is never handed the flag; a product
38
152
  * in it is handed the flag only when the installed build says it is at least
39
- * this version. Both directions matter: handing an older build a flag it does
40
- * not parse makes it exit non-zero with no JSON, which the umbrella correctly
41
- * reports as could-not-run, so a wrong guess here turns a working repository's
42
- * pull requests red rather than merely leaving a gate un-hardened.
153
+ * this version, and on a run with a trust base a build below it is
154
+ * could-not-run rather than run without the flag, since without the flag it
155
+ * would take its rules from the tree being judged. The entries are the
156
+ * minimum the umbrella requires on a pull-request run, which can be later
157
+ * than the release the flag first appeared in.
43
158
  *
44
159
  * The umbrella is deliberately NOT the place a version pin lives otherwise
45
160
  * (nothing here imports any gate's package), and this is the one exception:
@@ -47,9 +162,9 @@ import { ResolveError, candidateNames, nodeModulesCandidate, resolveGateBinary,
47
162
  * this package has to those tools.
48
163
  */
49
164
  export const TRUST_BASE_MIN_VERSION = {
50
- 'intent-guard': '1.4.0',
51
- 'vault-guard': '1.7.0',
52
- 'dep-guard': '0.6.0',
165
+ 'intent-guard': '1.8.1',
166
+ 'vault-guard': '1.9.1',
167
+ 'dep-guard': '0.10.1',
53
168
  // The two external tools have no --trust-base and are never handed one.
54
169
  // For them the umbrella itself provides pull-request mode: it scopes the
55
170
  // history to base..HEAD and hands over the config (and gitleaks' ignore
@@ -64,6 +179,48 @@ export const TRUST_BASE_MIN_VERSION = {
64
179
  // branch below is what keeps that gate from being handed a flag it would
65
180
  // reject.
66
181
  };
182
+ /**
183
+ * The first intent-guard whose own `--base` can carry any change set: it
184
+ * reads the paths from git NUL-separated (1.8.0) and lists a moved submodule
185
+ * pointer with --ignore-submodules=none and ends the range with "--" (the
186
+ * release after 1.8.0). For a native contract on this version or later the
187
+ * runner hands the gate `--base` instead of `--paths`, so a changed path
188
+ * that `--paths` cannot carry (a comma, a backslash, edge whitespace, a
189
+ * leading "-") is judged rather than refused.
190
+ *
191
+ * It equals the intent-guard entry in `TRUST_BASE_MIN_VERSION`, so on a run
192
+ * with a trust base every intent gate that runs is new enough, and the
193
+ * `--paths` refusal for a native contract is reached only on a run without
194
+ * one (an explicit `--base`). Kept as its own constant because the two
195
+ * answer different questions and the floor may move without it.
196
+ */
197
+ export const INTENT_BASE_CHANNEL_MIN_VERSION = '1.8.1';
198
+ /**
199
+ * How the intent gate is handed the change set on a prepared run: its own
200
+ * `--base` (native contract, gate new enough), `--paths`, or not at all,
201
+ * with the reason, when `--paths` cannot carry it and `--base` is not
202
+ * available.
203
+ */
204
+ function intentChangeChannel(gate, intent, version) {
205
+ if (gate.product !== 'intent-guard' || intent === undefined || intent.paths === null) {
206
+ return { kind: 'paths' };
207
+ }
208
+ if (intent.contractSource.kind === 'native' &&
209
+ intent.baseRef !== null &&
210
+ atLeastVersion(version, INTENT_BASE_CHANNEL_MIN_VERSION)) {
211
+ return { kind: 'base', ref: intent.baseRef };
212
+ }
213
+ if (intent.pathsRefusal !== undefined) {
214
+ return {
215
+ kind: 'refused',
216
+ detail: `${intent.pathsRefusal} intent-guard ${version ?? 'of an unreadable version'} takes the ` +
217
+ 'change set only as that list, so nothing was checked by this gate. To clear it, ' +
218
+ `upgrade intent-guard to ${INTENT_BASE_CHANNEL_MIN_VERSION} or later, which reads the ` +
219
+ 'change set from git itself for a contract frozen in the repository.',
220
+ };
221
+ }
222
+ return { kind: 'paths' };
223
+ }
67
224
  /**
68
225
  * Whether this gate can be handed `--trust-base`, and why not when it cannot.
69
226
  *
@@ -94,11 +251,6 @@ export function decideTrustBase(gate, intent, trustBase, productVersion) {
94
251
  refused: reason,
95
252
  proposals: [],
96
253
  });
97
- if (intent !== undefined && intent.contractSource.kind !== 'native') {
98
- return withheld('the intent gate is running against a contract imported for this run, which lives in a ' +
99
- 'temporary directory with no repository in it, so there is no ref there to read control ' +
100
- 'inputs from. The contract it is judging against came from a spec in the head tree.');
101
- }
102
254
  const minimum = TRUST_BASE_MIN_VERSION[gate.product];
103
255
  if (minimum === undefined) {
104
256
  return withheld(`${gate.product} has no pull-request mode yet, so it read its own configuration from the ` +
@@ -117,10 +269,25 @@ export function decideTrustBase(gate, intent, trustBase, productVersion) {
117
269
  'its rules from the base ref. Nothing was checked by it. Running it anyway would put it ' +
118
270
  'quietly outside the trust boundary on exactly the runs where something is already wrong.');
119
271
  }
272
+ // A version BELOW the minimum is refused too, never withheld: running it
273
+ // without the flag would let it take its rules from the tree being judged
274
+ // on a run whose whole promise is that every rule comes from the base ref.
120
275
  if (!atLeastVersion(productVersion, minimum)) {
121
- return withheld(`${gate.product} ${productVersion} does not understand --trust-base, which arrived in ` +
122
- `${minimum}, so it read its own control inputs from the tree being judged. Upgrade it to ` +
123
- 'put this gate into pull-request mode.');
276
+ return refused(`${gate.product} did not run: the installed ${productVersion} is older than ${minimum}, the ` +
277
+ 'first version that takes its rules from the base ref on a pull-request run, so nothing ' +
278
+ `was checked by it. Fix: install ${gate.product} ${minimum} or newer, or remove an ` +
279
+ 'explicit older version pin.');
280
+ }
281
+ // AFTER the version checks, so an imported contract cannot let an older
282
+ // gate run: this withholding is about where --project points, not about
283
+ // what the gate understands, and the contract itself came from the base.
284
+ if (intent !== undefined && intent.contractSource.kind !== 'native') {
285
+ const from = intent.contractSource.kind === 'imported' && intent.contractSource.ref !== undefined
286
+ ? `came from the spec on "${intent.contractSource.ref}"`
287
+ : 'came from a spec in the head tree';
288
+ return withheld('the intent gate is running against a contract imported for this run, which lives in a ' +
289
+ 'temporary directory with no repository in it, so there is no ref there to read control ' +
290
+ `inputs from. The contract it is judging against ${from}.`);
124
291
  }
125
292
  return { ref: trustBase, withheld: null, refused: null, proposals: [] };
126
293
  }
@@ -241,7 +408,12 @@ export function gateArgs(gate, staged, intent,
241
408
  */
242
409
  trustBase,
243
410
  /** Paths the runner owns for an external tool; the npm gates ignore them. */
244
- external = {}) {
411
+ external = {},
412
+ /**
413
+ * For the intent gate on a prepared run: hand it this base with its own
414
+ * `--base` in place of `--paths`. Decided by `intentChangeChannel`.
415
+ */
416
+ intentBase) {
245
417
  const passthrough = renderOptionFlags(gate.options);
246
418
  const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
247
419
  const config = external.configPath === undefined ? [] : ['--config', external.configPath];
@@ -275,9 +447,12 @@ external = {}) {
275
447
  // a passthrough value being read as the positional.
276
448
  //
277
449
  // `scan` takes --trust-base from 1.7.0. On exit 2 it prints a line on
278
- // stderr and may also write a JSON document (it can on a staged run);
279
- // conductor never parses stdout on exit 2, so the could-not-run path
280
- // above handles both before JSON.parse is reached.
450
+ // stderr and may also write a JSON document (it can on a staged run, and
451
+ // from 1.9.1 on a scan that skipped files). conductor never reads a
452
+ // verdict out of stdout on exit 2: the could-not-run branch in
453
+ // spawnAndRead, below, returns before the verdict JSON.parse is reached.
454
+ // That branch does read the stderr first line, or a reason field in the
455
+ // JSON, as a bounded excerpt for the reader (gateStatedReason).
281
456
  return [...(staged ? ['--staged'] : []), '-f', 'json', ...trust, ...passthrough];
282
457
  case 'intent-guard': {
283
458
  if (intent === undefined) {
@@ -305,7 +480,9 @@ external = {}) {
305
480
  ? staged
306
481
  ? ['--staged']
307
482
  : []
308
- : ['--paths', intent.paths.join(',')]),
483
+ : intentBase !== undefined
484
+ ? ['--base', intentBase]
485
+ : ['--paths', intent.paths.join(',')]),
309
486
  // Beside --paths on purpose, and they are independent: --trust-base
310
487
  // says where the RULES come from, --paths says which paths are
311
488
  // judged. A pull-request run passes both.
@@ -525,6 +702,7 @@ export function runGate(gate, options) {
525
702
  intent: {
526
703
  contractSource: options.intent.contractSource,
527
704
  baseRef: options.intent.baseRef,
705
+ ...(options.intent.note === undefined ? {} : { note: options.intent.note }),
528
706
  },
529
707
  }
530
708
  : options.intentContract === undefined
@@ -568,12 +746,20 @@ export function runGate(gate, options) {
568
746
  * than a clear "true" (no git, an old git that does not know the flag) is
569
747
  * not shallow: those runs have their own failure paths.
570
748
  */
749
+ /** The oldest git a history gate runs under on a pull-request run. */
750
+ export const HISTORY_GIT_FLOOR = '2.31.0';
751
+ /** git's own version ("git version 2.39.3 (Apple Git-145)" reads 2.39.3), or null. */
752
+ function probeGitVersion(repoRoot) {
753
+ const probe = runGit(repoRoot, ['--version']);
754
+ if (probe.error !== undefined || probe.status !== 0) {
755
+ return null;
756
+ }
757
+ const match = /git version (\d+\.\d+\.\d+)/.exec(probe.stdout);
758
+ return match === null ? null : match[1];
759
+ }
571
760
  function isShallowRepository(repoRoot) {
572
- const probe = spawnSync('git', ['rev-parse', '--is-shallow-repository'], {
573
- cwd: repoRoot,
574
- encoding: 'utf8',
575
- });
576
- return probe.status === 0 && typeof probe.stdout === 'string' && probe.stdout.trim() === 'true';
761
+ const probe = runGit(repoRoot, ['rev-parse', '--is-shallow-repository']);
762
+ return probe.status === 0 && probe.stdout.trim() === 'true';
577
763
  }
578
764
  function runGateInner(gate, options, started, progress) {
579
765
  const timeoutMs = options.timeoutMs ?? profileFor(gate.product).timeoutMs;
@@ -660,13 +846,41 @@ function runGateInner(gate, options, started, progress) {
660
846
  };
661
847
  }
662
848
  }
849
+ // THE GIT FLOOR, on a pull-request run, for a gate that reads history. The
850
+ // newest git option this umbrella relies on is the one it hands gitleaks,
851
+ // "git log --diff-merges=first-parent" (git 2.31, per git's release notes);
852
+ // every other option conductor itself passes is older (rev-parse
853
+ // --is-shallow-repository is git 2.15). An older git would make that gate
854
+ // log a git error rather than say why, so the version is asked once, here,
855
+ // and an older one is a named could-not-run. Only where the option is used:
856
+ // a run with no history gate never pays for the probe or meets the floor.
857
+ if (profileFor(gate.product).readsHistory && options.trustBase !== undefined) {
858
+ const gitVersion = probeGitVersion(options.repoRoot);
859
+ if (gitVersion === null || !atLeastVersion(gitVersion, HISTORY_GIT_FLOOR)) {
860
+ const found = gitVersion === null
861
+ ? `the git version could not be read, so git is not known to be ${HISTORY_GIT_FLOOR} or later`
862
+ : `git ${gitVersion} is older than ${HISTORY_GIT_FLOOR}`;
863
+ const detail = `${found}, which ${gate.product} needs on a pull-request run: conductor hands it ` +
864
+ '"git log --diff-merges=first-parent", which arrived in git 2.31. Upgrade git, then run ' +
865
+ 'again. Nothing was checked by this gate.';
866
+ return {
867
+ ...base,
868
+ enforce: true,
869
+ durationMs: Date.now() - started,
870
+ couldNotRun: { reason: 'preparation-failed', detail },
871
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
872
+ run: EMPTY_RUN,
873
+ diagnostics: [],
874
+ };
875
+ }
876
+ }
663
877
  // A history gate cannot vouch for history it was not given. Checked before
664
878
  // the version probe so nothing is executed for a run that cannot be honest.
665
879
  if (profileFor(gate.product).readsHistory && isShallowRepository(options.repoRoot)) {
666
- const detail = `this checkout is shallow, so the git history ${gate.product} reads is truncated: ` +
667
- 'with the default actions/checkout depth of 1 the range from the base to HEAD holds a ' +
668
- 'single grafted commit, and a secret added and then removed inside the pull request ' +
669
- 'would never be seen. Check out with fetch-depth: 0 (actions/checkout) or run ' +
880
+ const detail = `${gate.product} did not run, because this checkout is shallow and the git history it reads ` +
881
+ 'is truncated: with the default actions/checkout depth of 1 the range from the base to HEAD ' +
882
+ 'holds a single grafted commit, and a secret added and then removed inside the pull ' +
883
+ 'request would never be seen. Fix: check out with fetch-depth: 0 (actions/checkout) or run ' +
670
884
  'git fetch --unshallow, then run again. conductor does not deepen the checkout itself.';
671
885
  return {
672
886
  ...base,
@@ -682,6 +896,17 @@ function runGateInner(gate, options, started, progress) {
682
896
  };
683
897
  }
684
898
  const version = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
899
+ // A PATH binary at a different version than the run was told to expect: a
900
+ // fact for a warning and nothing else. It sits on `progress` (which `base`
901
+ // is) so every outcome from here on carries it, and no branch below reads it.
902
+ if (options.expectedVersion !== undefined &&
903
+ version !== null &&
904
+ binary.source === 'path' &&
905
+ version !== options.expectedVersion) {
906
+ Object.assign(progress, {
907
+ versionSkew: { expected: options.expectedVersion, found: version, path: binary.program },
908
+ });
909
+ }
685
910
  // The command-line floor. Only the external tools have one: the umbrella
686
911
  // writes flags they grew at a known release (gitleaks' git subcommand,
687
912
  // osv-scanner's scan source), and an older build would reject the command
@@ -692,8 +917,9 @@ function runGateInner(gate, options, started, progress) {
692
917
  if (profile.minVersion !== null &&
693
918
  version !== null &&
694
919
  !atLeastVersion(version, profile.minVersion)) {
695
- const detail = `${gate.product} ${version} is older than ${profile.minVersion}, the oldest version whose ` +
696
- `command line this umbrella speaks. Upgrade it to ${profile.minVersion} or later.`;
920
+ const detail = `${gate.product} did not run: the installed ${version} is older than ${profile.minVersion}, ` +
921
+ 'the oldest version whose command line this umbrella speaks. ' +
922
+ `Fix: upgrade it to ${profile.minVersion} or later.`;
697
923
  return {
698
924
  ...base,
699
925
  productVersion: version,
@@ -707,9 +933,8 @@ function runGateInner(gate, options, started, progress) {
707
933
  }
708
934
  // AFTER the version probe and BEFORE the command line is built, because the
709
935
  // decision reads the version. That ordering is the whole capability gate:
710
- // an intent-guard older than 1.4.0 must not be handed a flag it would
711
- // reject, and a gate IN the table whose version could not be read is
712
- // refused rather than run outside the boundary.
936
+ // a gate IN the table whose version is below its minimum, or could not be
937
+ // read, is refused rather than run outside the boundary.
713
938
  const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version);
714
939
  if (trustBase !== undefined && trustBase.refused !== null) {
715
940
  return {
@@ -722,23 +947,42 @@ function runGateInner(gate, options, started, progress) {
722
947
  // a decision about, and this is the umbrella saying it could not
723
948
  // establish that the gate was inside the boundary.
724
949
  //
725
- // Reachable now only as a PACKAGING problem, not as an attack: the
726
- // program check above runs first, and with its directory-subtree rule a
727
- // pull request can no longer put a program here whose version probe it
728
- // controls. Before that rule it could, through the wrapper shape: a
729
- // head-replaced inner script exiting 3 on --version landed exactly
730
- // here, with enforce false and exit 0. A packaging quirk that
731
- // fails a build loudly is the better failure: the alternative is a
732
- // boundary that quietly downgrades itself on the runs where something
733
- // is already wrong, which is the shape of every bug in this file.
950
+ // Reachable as an installation problem (a gate older than its minimum)
951
+ // or a packaging one (a version that does not read), not as an attack:
952
+ // the program check above runs first, and with its directory-subtree
953
+ // rule a pull request cannot put a program here whose version probe it
954
+ // controls. A build that fails loudly is the better failure: the
955
+ // alternative is a boundary that quietly downgrades itself.
734
956
  enforce: true,
735
957
  trustBase,
736
- couldNotRun: { reason: 'trust-base-unverified', detail: trustBase.refused },
958
+ // decideTrustBase refuses for exactly two reasons: a version it could
959
+ // not read, and a version it read that is below the minimum.
960
+ couldNotRun: {
961
+ reason: version === null ? 'trust-base-unverified' : 'gate-version-unsupported',
962
+ detail: trustBase.refused,
963
+ },
737
964
  findings: [normalizeFailedGate(gate.role, gate.product, trustBase.refused)],
738
965
  run: EMPTY_RUN,
739
966
  diagnostics: [],
740
967
  };
741
968
  }
969
+ const channel = intentChangeChannel(gate, options.intent, version);
970
+ if (channel.kind === 'refused') {
971
+ return {
972
+ ...base,
973
+ productVersion: version,
974
+ binary,
975
+ durationMs: Date.now() - started,
976
+ // Enforced under a trust base: the gate produced nothing for
977
+ // enforce: false to be a decision about.
978
+ enforce: options.trustBase !== undefined ? true : gate.enforce,
979
+ ...(trustBase === undefined ? {} : { trustBase }),
980
+ couldNotRun: { reason: 'preparation-failed', detail: channel.detail },
981
+ findings: [normalizeFailedGate(gate.role, gate.product, channel.detail)],
982
+ run: EMPTY_RUN,
983
+ diagnostics: [],
984
+ };
985
+ }
742
986
  // A directory of the runner's own for an external tool's working files: the
743
987
  // report gitleaks writes. Made under the caller's temporary root when there
744
988
  // is one, and removed whatever happens, so a run leaves nothing behind. The
@@ -789,12 +1033,8 @@ function spawnAndRead(ctx) {
789
1033
  const nestedProposals = [];
790
1034
  if (profile.lockfileNames !== null) {
791
1035
  const names = new Set(profile.lockfileNames);
792
- const listing = spawnSync('git', ['ls-files', '-z'], {
793
- cwd: options.repoRoot,
794
- encoding: 'utf8',
795
- maxBuffer: 64 * 1024 * 1024,
796
- });
797
- if (listing.status !== 0 || typeof listing.stdout !== 'string') {
1036
+ const listing = runGit(options.repoRoot, ['ls-files', '-z'], { maxBuffer: 64 * 1024 * 1024 });
1037
+ if (listing.error !== undefined || listing.status !== 0) {
798
1038
  const detail = `the repository's tracked files could not be listed, so ${gate.product} had no ` +
799
1039
  'lockfiles to be handed.';
800
1040
  return {
@@ -811,7 +1051,25 @@ function spawnAndRead(ctx) {
811
1051
  }
812
1052
  const tracked = listing.stdout.split('\0').filter((file) => file !== '');
813
1053
  if (decidedRef !== undefined && profile.configFile !== null) {
814
- nestedProposals.push(...nestedConfigProposals(options.repoRoot, decidedRef, tracked, profile.configFile));
1054
+ try {
1055
+ nestedProposals.push(...nestedConfigProposals(options.repoRoot, decidedRef, tracked, profile.configFile));
1056
+ }
1057
+ catch (err) {
1058
+ if (!(err instanceof ExternalConfigError)) {
1059
+ throw err;
1060
+ }
1061
+ return {
1062
+ ...base,
1063
+ productVersion: version,
1064
+ binary,
1065
+ durationMs: Date.now() - started,
1066
+ ...(trustBase === undefined ? {} : { trustBase }),
1067
+ couldNotRun: { reason: 'preparation-failed', detail: err.message },
1068
+ findings: [normalizeFailedGate(gate.role, gate.product, err.message)],
1069
+ run: EMPTY_RUN,
1070
+ diagnostics: [],
1071
+ };
1072
+ }
815
1073
  }
816
1074
  external.lockfiles = tracked
817
1075
  // Never a vendored copy under node_modules: that is a dependency's own
@@ -897,11 +1155,8 @@ function spawnAndRead(ctx) {
897
1155
  }
898
1156
  }
899
1157
  if (profile.ignoreFile?.alsoLoadedFromScanRoot === true) {
900
- const gitDir = spawnSync('git', ['rev-parse', '--absolute-git-dir'], {
901
- cwd: options.repoRoot,
902
- encoding: 'utf8',
903
- });
904
- const resolved = typeof gitDir.stdout === 'string' ? gitDir.stdout.trim() : '';
1158
+ const gitDir = runGit(options.repoRoot, ['rev-parse', '--absolute-git-dir']);
1159
+ const resolved = gitDir.stdout.trim();
905
1160
  if (gitDir.status !== 0 || resolved === '') {
906
1161
  // No git directory means no history to scan and nowhere safe to scan
907
1162
  // it from. Not a clean result.
@@ -925,9 +1180,13 @@ function spawnAndRead(ctx) {
925
1180
  const trustBaseOut = trustBase === undefined || configProposals.length === 0
926
1181
  ? trustBase
927
1182
  : { ...trustBase, proposals: [...trustBase.proposals, ...configProposals] };
1183
+ // Decided again here from the same inputs rather than threaded through:
1184
+ // intentChangeChannel is pure, and runGateInner already returned on the one
1185
+ // outcome that does not spawn.
1186
+ const channel = intentChangeChannel(gate, options.intent, version);
928
1187
  const argv = [
929
1188
  ...binary.argvPrefix,
930
- ...gateArgs(gate, options.staged, options.intent, decidedRef, external),
1189
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, external, channel.kind === 'base' ? channel.ref : undefined),
931
1190
  ];
932
1191
  const child = spawnSync(binary.command, argv, {
933
1192
  cwd: spawnCwd,
@@ -954,8 +1213,7 @@ function spawnAndRead(ctx) {
954
1213
  // Carried on every return path below, the failures included: WHETHER
955
1214
  // this gate was in pull-request mode is exactly as interesting when it
956
1215
  // could not run as when it could, and the withheld reason is the only
957
- // place a report can say a gate read its own rules out of the tree under
958
- // judgment.
1216
+ // place a report can say a gate was not handed the base ref.
959
1217
  ...(trustBaseOut === undefined ? {} : { trustBase: trustBaseOut }),
960
1218
  };
961
1219
  // Keep the backstop's view current, so an unexpected throw below still
@@ -1012,10 +1270,20 @@ function spawnAndRead(ctx) {
1012
1270
  const detail = exitCode === null
1013
1271
  ? 'the gate did not exit normally (killed, or timed out).'
1014
1272
  : `the gate exited ${exitCode}, which it uses for "could not run".`;
1273
+ // WHY, in the gate's own words, when it said. Read here and nowhere
1274
+ // earlier: the exit code has already been judged above, and this only
1275
+ // annotates the result. It never reads stdout for a verdict.
1276
+ const gateSaid = exitCode === null
1277
+ ? null
1278
+ : gateStatedReason(withRun.stderr, child.stdout, profile.output.kind === 'stdout');
1015
1279
  return {
1016
1280
  ...withRun,
1017
1281
  exitCode,
1018
- couldNotRun: { reason: 'gate-error', detail },
1282
+ couldNotRun: {
1283
+ reason: 'gate-error',
1284
+ detail,
1285
+ ...(gateSaid === null ? {} : { gateSaid }),
1286
+ },
1019
1287
  // The child's own stderr goes with it. The text report prints it from
1020
1288
  // the outcome, but a gate that could not run gets no SARIF run of its
1021
1289
  // own, so this finding is the only place a published log can say what
package/dist/git.d.ts ADDED
@@ -0,0 +1,80 @@
1
+ export interface GitResult {
2
+ status: number | null;
3
+ stdout: string;
4
+ stderr: string;
5
+ /** Set when git could not be started at all. */
6
+ error: Error | undefined;
7
+ }
8
+ /** The program every git call in this process runs. */
9
+ export declare function currentGitProgram(): string;
10
+ /**
11
+ * Pins the git program for the rest of this process. The CLI calls it once
12
+ * on a pull-request run, with an absolute path; tests call it to reset.
13
+ */
14
+ export declare function useGitProgram(program: string): void;
15
+ /** Runs one git command in `cwd`, reading stdout as UTF-8. Never throws. */
16
+ export declare function runGit(cwd: string, args: readonly string[], options?: {
17
+ maxBuffer?: number;
18
+ }): GitResult;
19
+ /**
20
+ * A PATH with every entry that would resolve against the working directory
21
+ * removed: an empty entry (which means the current directory) and a relative
22
+ * one. Returns the cleaned value and what was removed, in order.
23
+ *
24
+ * Used on a run with a trust base, where the working directory of nearly
25
+ * every child is the tree under judgment, so that every PATH lookup, for
26
+ * git, for node in a gate's "#!/usr/bin/env node" line, or for a gate,
27
+ * resolves against an absolute directory.
28
+ */
29
+ export declare function absolutePathEntries(pathValue: string): {
30
+ value: string;
31
+ removed: string[];
32
+ };
33
+ /**
34
+ * The nearest directory at or above `start` holding a `.git` entry (the
35
+ * work tree a git run from `start` would find), resolved, or null. Found
36
+ * without running git, because it decides which git may be run.
37
+ */
38
+ export declare function workTreeAbove(start: string): string | null;
39
+ /**
40
+ * The first git on `pathValue` whose real path (symlinks resolved) is
41
+ * outside every root in `excluded`, as that real path, or null when there
42
+ * is none. Only absolute PATH entries are considered.
43
+ */
44
+ export declare function gitOutside(pathValue: string, excluded: readonly string[]): string | null;
45
+ /**
46
+ * Pins every git call in this process to the first git on `pathValue` that
47
+ * is outside the given work trees, and returns it; null, with nothing
48
+ * pinned, when there is none. Called once on a pull-request run.
49
+ */
50
+ export declare function pinGitOutside(pathValue: string, excluded: readonly string[]): string | null;
51
+ /** Whether the pinned git program's real path is inside `root`. */
52
+ export declare function pinnedGitInside(root: string): boolean;
53
+ /** Whether `candidate`'s real path is `root`'s real path or under it. */
54
+ export declare function realPathInside(root: string, candidate: string): boolean;
55
+ /** The name every private git directory starts with, under the temp directory. */
56
+ export declare const GIT_SHIM_PREFIX = "conductor-git-";
57
+ /**
58
+ * On a run with a trust base: creates the private directory that goes first
59
+ * on PATH for every child the run starts, so that a gate, or anything a gate
60
+ * starts, that looks git up by name runs the pinned `program` and never a git
61
+ * found in a PATH entry inside the tree being judged.
62
+ *
63
+ * The directory is a fresh mkdtemp directory under `tempRoot`, mode 0700,
64
+ * holding exactly one entry, `git`, a symbolic link to `program`, so no other
65
+ * lookup is shadowed. git finds its helpers through its own exec path, not
66
+ * through PATH, so a link is enough. Throws, with a sentence saying why and
67
+ * what to set, when `tempRoot` is inside one of `excluded` or the directory
68
+ * cannot be made; it never returns an unprotected result silently.
69
+ *
70
+ * On Windows it creates nothing and returns null: a symbolic link needs a
71
+ * privilege there, and a git.cmd wrapper is not found by a child that starts
72
+ * git without a shell. There the gates look git up through the cleaned PATH.
73
+ */
74
+ export declare function createGitShim(program: string, tempRoot: string, excluded: readonly string[], platform?: NodeJS.Platform): string | null;
75
+ /** Why a run cannot go ahead when the temp directory is inside the tree. */
76
+ export declare function tempInsideTreeMessage(tempRoot: string): string;
77
+ /** Removes a directory createGitShim made. Never throws. */
78
+ export declare function removeGitShim(dir: string): void;
79
+ /** git's first line of complaint, without a trailing full stop. */
80
+ export declare function gitComplaint(result: GitResult): string;