@vaultcompass/conductor 0.18.0 → 0.19.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.
@@ -0,0 +1,206 @@
1
+ // The "existing findings" message: what a run with no base says when the
2
+ // history gate (gitleaks) or the vulnerabilities gate (osv-scanner) blocks.
3
+ //
4
+ // WORDS ONLY. Nothing in this file reaches the exit code, the verdict token
5
+ // or any finding's `blocking` flag: collectExistingFindings reads the
6
+ // outcomes after the exit code is composed and only counts, and the text it
7
+ // feeds is printed beside the verdict, never instead of it. A repository that
8
+ // adopts conductor late meets its whole history on the first run with no
9
+ // base (a local run, a push, a scheduled run); every one of those findings
10
+ // still blocks, and this section says why there are so many and what the
11
+ // real options are.
12
+ //
13
+ // Two of the facts are git facts and are only ever stated when git answered:
14
+ // how many history findings predate the commit that added the policy file,
15
+ // and how many cite a file that is gone at HEAD. When git cannot answer
16
+ // (not a repository, a failed call) the number is null and the report says
17
+ // nothing about it rather than guess.
18
+ import { runGit } from './git.js';
19
+ import { POLICY_FILE_NAME } from './policy.js';
20
+ /** Blocking findings of one gate that block the run: enforced, ran, found something. */
21
+ function blockingOf(outcomes, role) {
22
+ return outcomes
23
+ .filter((gate) => gate.role === role && gate.couldNotRun === null && gate.enforce)
24
+ .flatMap((gate) => gate.findings.filter((finding) => finding.blocking && finding.product === gate.product));
25
+ }
26
+ /** The commits a history finding carries: the kept one and every alsoIn. */
27
+ function carriedCommits(details) {
28
+ if (typeof details.commit !== 'string' || details.commit.length === 0) {
29
+ return null;
30
+ }
31
+ const also = Array.isArray(details.alsoIn)
32
+ ? details.alsoIn.filter((value) => typeof value === 'string')
33
+ : [];
34
+ return [details.commit, ...also];
35
+ }
36
+ /** Every path in HEAD's tree, or null when git could not list it. */
37
+ function headPaths(repoRoot) {
38
+ const listed = runGit(repoRoot, ['ls-tree', '-r', '-z', '--name-only', 'HEAD']);
39
+ if (listed.error !== undefined || listed.status !== 0) {
40
+ return null;
41
+ }
42
+ return new Set(listed.stdout.split('\0').filter((entry) => entry.length > 0));
43
+ }
44
+ /**
45
+ * The oldest commit on HEAD's first-parent chain that adds the policy file:
46
+ * a commit id, 'none' when the file is in no commit and not in HEAD (not
47
+ * committed yet), or null when git could not say.
48
+ */
49
+ function policyCommit(repoRoot, paths) {
50
+ const lines = (result) => result.error !== undefined || result.status !== 0
51
+ ? null
52
+ : result.stdout.split('\n').filter((line) => line.length > 0);
53
+ // --no-renames: a policy renamed into place is an add, not an R the filter skips.
54
+ const firstParent = lines(runGit(repoRoot, ['log', '--first-parent', '--no-renames', '--diff-filter=A', '--format=%H', '--', POLICY_FILE_NAME]));
55
+ // EVERY commit reachable from HEAD that adds the file relative to any
56
+ // parent, merges included, on any branch: HEAD's first-parent chain can run
57
+ // through a branch that forked before the policy and merged it in, where the
58
+ // only "add" on that chain is the merge itself and every commit on the
59
+ // branch would look old; and a merge that introduces the file in its own
60
+ // conflict resolution can sit off that chain. -m lists a merge once per
61
+ // parent it adds the file against; the Set below dedupes.
62
+ const everywhere = lines(runGit(repoRoot, [
63
+ 'log',
64
+ '--full-history',
65
+ '-m',
66
+ '--no-renames',
67
+ '--diff-filter=A',
68
+ '--format=%H',
69
+ '--',
70
+ POLICY_FILE_NAME,
71
+ ]));
72
+ if (firstParent === null || everywhere === null) {
73
+ return null;
74
+ }
75
+ const ids = new Set([
76
+ ...(firstParent.length > 0 ? [firstParent[firstParent.length - 1]] : []),
77
+ ...everywhere,
78
+ ]);
79
+ if (ids.size > MAX_POLICY_ADDS) {
80
+ return null;
81
+ }
82
+ if (ids.size > 0) {
83
+ return [...ids];
84
+ }
85
+ // No commit adds it. Not committed yet only when HEAD does not hold it
86
+ // either; a file in HEAD that no first-parent commit adds is not a state
87
+ // this can name, so it says nothing.
88
+ if (paths === null) {
89
+ return null;
90
+ }
91
+ return paths.has(POLICY_FILE_NAME) ? null : 'none';
92
+ }
93
+ /** More add commits than this and the number is left out: each costs a rev-list. */
94
+ const MAX_POLICY_ADDS = 20;
95
+ /** Every commit that is an ancestor of the policy commit's first parent; empty for a root commit. */
96
+ function commitsBeforePolicy(repoRoot, policy) {
97
+ const parent = runGit(repoRoot, ['rev-parse', '--verify', '--quiet', `${policy}^`]);
98
+ if (parent.error !== undefined) {
99
+ return null;
100
+ }
101
+ if (parent.status !== 0) {
102
+ // A root commit has no parent: nothing predates it. A different failure
103
+ // is not told apart from that, so confirm the commit really is a root.
104
+ const parents = runGit(repoRoot, ['rev-list', '--parents', '-n', '1', policy]);
105
+ const fields = parents.stdout.trim().split(' ').filter((field) => field.length > 0);
106
+ return parents.status === 0 && fields.length === 1 ? new Set() : null;
107
+ }
108
+ const ancestors = runGit(repoRoot, ['rev-list', parent.stdout.trim()]);
109
+ if (ancestors.error !== undefined || ancestors.status !== 0) {
110
+ return null;
111
+ }
112
+ return new Set(ancestors.stdout.split('\n').filter((line) => line.length > 0));
113
+ }
114
+ /**
115
+ * The facts for the message, or null when the gates that block are not the
116
+ * history or the vulnerabilities gate. The caller only calls it on a run with
117
+ * no trust base; the text report checks that again.
118
+ *
119
+ * A history finding counts as predating the policy only when EVERY commit it
120
+ * carries (the kept commit and each alsoIn) is an ancestor of the policy
121
+ * commit's first parent. The kept commit can be the newest, or chosen by a
122
+ * forged date, so it alone proves nothing. Gaming this changes a sentence,
123
+ * never an exit code.
124
+ */
125
+ export function collectExistingFindings(outcomes, repoRoot) {
126
+ const historyFindings = blockingOf(outcomes, 'secrets-history');
127
+ const vulnerabilities = blockingOf(outcomes, 'vulnerabilities').length;
128
+ if (historyFindings.length === 0 && vulnerabilities === 0) {
129
+ return null;
130
+ }
131
+ let predating = null;
132
+ let goneAtHead = null;
133
+ let stillAtHead = null;
134
+ if (historyFindings.length > 0) {
135
+ const paths = headPaths(repoRoot);
136
+ if (paths !== null) {
137
+ const gone = historyFindings.filter((finding) => finding.subject.kind === 'location' && !paths.has(finding.subject.file)).length;
138
+ goneAtHead = gone;
139
+ stillAtHead = historyFindings.length - gone;
140
+ }
141
+ const policy = policyCommit(repoRoot, paths);
142
+ if (policy === 'none') {
143
+ predating = { kind: 'not-committed' };
144
+ }
145
+ else if (policy !== null) {
146
+ // The intersection of the ancestor sets of every add commit's first
147
+ // parent: a commit predates the policy only if it predates every way
148
+ // the policy arrived. Any set that cannot be computed, no number.
149
+ const sets = policy.map((add) => commitsBeforePolicy(repoRoot, add));
150
+ const complete = sets.every((one) => one !== null);
151
+ if (complete) {
152
+ const [first, ...rest] = sets;
153
+ const known = rest.reduce((acc, one) => new Set([...acc].filter((id) => one.has(id))), first);
154
+ const count = historyFindings.filter((finding) => {
155
+ const commits = carriedCommits(finding.details);
156
+ return commits !== null && commits.every((id) => known.has(id));
157
+ }).length;
158
+ predating = { kind: 'count', count };
159
+ }
160
+ }
161
+ }
162
+ return { history: historyFindings.length, vulnerabilities, predating, goneAtHead, stillAtHead };
163
+ }
164
+ /**
165
+ * The report section. Every name in it exists today: the stage split, each
166
+ * tool's own ignore mechanism and each family gate's own baseline. Nothing
167
+ * here points at a conductor command that records findings as known.
168
+ */
169
+ export function existingFindingsLines(info) {
170
+ const counts = [
171
+ ...(info.history > 0 ? [`${info.history} blocking finding(s) in secrets-history`] : []),
172
+ ...(info.vulnerabilities > 0
173
+ ? [info.history > 0 ? `${info.vulnerabilities} in vulnerabilities` : `${info.vulnerabilities} blocking finding(s) in vulnerabilities`]
174
+ : []),
175
+ ].join(' and ');
176
+ const judged = [
177
+ ...(info.history > 0 ? ['all of git history'] : []),
178
+ ...(info.vulnerabilities > 0 ? ['every tracked lockfile'] : []),
179
+ ].join(' and ');
180
+ const lines = [
181
+ `existing findings: ${counts}.`,
182
+ ` This run has no base, so it judged ${judged}, including what was here before conductor.`,
183
+ ' A pull request is judged only on what it changes.',
184
+ ];
185
+ if (info.history > 0) {
186
+ if (info.predating?.kind === 'count') {
187
+ lines.push(` ${info.predating.count} of the ${info.history} in secrets-history are only in commits made before ` +
188
+ `${POLICY_FILE_NAME} was first committed.`);
189
+ }
190
+ else if (info.predating?.kind === 'not-committed') {
191
+ lines.push(` In secrets-history, all of them are in commits made before ${POLICY_FILE_NAME}, which is not committed yet.`);
192
+ }
193
+ if (info.goneAtHead !== null && info.stillAtHead !== null) {
194
+ lines.push(` By file: ${info.goneAtHead} gone at HEAD, ${info.stillAtHead} still at HEAD (the line may have moved).`);
195
+ }
196
+ }
197
+ lines.push(' first: read them. A key that was ever live must be rotated; deleting the file does not remove it from history.', " then: run history and advisories on a schedule, not on every push: the Action's stage: push on push runs", ' (README, What a history scan costs).');
198
+ if (info.history > 0) {
199
+ lines.push(' accept a reviewed old history finding in .gitleaksignore, one line per commit the finding lists (its', ' commit and each "also in"), in the form commit:file:rule:line. gitleaks then drops those records and', ' this report does not count them. One line silences every secret on that line in that commit that the', ' same rule matches, not only the one you reviewed.');
200
+ }
201
+ if (info.vulnerabilities > 0) {
202
+ lines.push(' accept a reviewed advisory in osv-scanner.toml under [[IgnoredVulns]] with a reason; osv-scanner counts', ' those, and they show as suppressed here.');
203
+ }
204
+ lines.push(' dependencies and secrets keep their own baselines: vault-guard baseline, and .dep-guard.baseline.json', ' for dep-guard. Those cover the dependencies and secrets gates, not the history or vulnerability', ' findings this section is about.');
205
+ return lines;
206
+ }
@@ -200,15 +200,19 @@ export declare function cleanOutputLine(raw: string): string;
200
200
  * What a gate that exited with a non-verdict code said about why.
201
201
  *
202
202
  * TOTAL, and never a decision: the caller has already settled that this is a
203
- * could-not-run, and nothing here can change that. stderr is preferred, since
204
- * that is where every gate in the family prints its reason on exit 2
205
- * (dep-guard, intent-guard and vault-guard all do), read by the rule in
206
- * `statedReasonFromStderr`: the line the gate marks as the failure, never an
207
- * informational line. Failing that, stdout is parsed only for a gate whose
208
- * output is JSON on stdout, and only a string `reason` field (top level, or
209
- * on `run`) is read; anything else, including output that does not parse, is
210
- * simply no excerpt. An absent excerpt is better than quoting a warning as
211
- * the cause; the full stderr is still printed in the text report.
203
+ * could-not-run, and nothing here can change that.
204
+ *
205
+ * 1. A gate that wrote JSON is quoted from its couldNotRun field when that
206
+ * field is present (top level, or on `run`): a string as itself, or an
207
+ * object from its message and, when it has one, its code.
208
+ * 2. Otherwise, when stderr contains a `note (...)` or `warning (...)` line,
209
+ * the last line that is neither. dep-guard 0.20.0 prints those notes
210
+ * before the could-not-run line, and the first-line rule quoted the note.
211
+ * 3. Otherwise the line `statedReasonFromStderr` already chose, and failing
212
+ * that a string `reason` field on JSON stdout.
213
+ *
214
+ * An absent excerpt is better than quoting a warning as the cause; the full
215
+ * stderr is still printed in the text report.
212
216
  */
213
217
  export declare function gateStatedReason(stderr: string, stdout: string | null | undefined, stdoutIsJson: boolean): string | null;
214
218
  /**
@@ -21,7 +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 { realPathInside, runGit } from './git.js';
24
+ import { gateChildEnv, realPathInside, runGit } from './git.js';
25
25
  import { NormalizeError } from './envelope.js';
26
26
  import { describeLockfiles, normalizeDepGuard, normalizeFailedGate, normalizeGitleaks, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeOsvScanner, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
27
27
  import { renderOptionFlags } from './policy.js';
@@ -324,48 +324,142 @@ function statedReasonFromStderr(stderr) {
324
324
  const first = lines.find(candidate);
325
325
  return first === undefined ? null : sanitizeGateSaid(first.text);
326
326
  }
327
+ /**
328
+ * dep-guard's diagnostic lines, `note (code): ...` and `warning (code): ...`.
329
+ * A `note:` block (vault-guard) does not match: the parenthesis is the
330
+ * difference, and that block stays on the first-line rule.
331
+ */
332
+ const PAREN_NOTE = /^(?:note|warning) \(/i;
333
+ /**
334
+ * The last stderr line that is not a `note (...)` or `warning (...)` line,
335
+ * when the stderr has at least one of those. Null when this shape is absent,
336
+ * so the caller keeps the first-line rule for every other gate.
337
+ */
338
+ function lastLineAfterParentheticalNotes(stderr) {
339
+ const lines = stripAnsi(stderr)
340
+ .split('\n')
341
+ .map((raw) => plainLine(raw))
342
+ .filter((text) => text !== '');
343
+ if (!lines.some((text) => PAREN_NOTE.test(text))) {
344
+ return null;
345
+ }
346
+ for (let i = lines.length - 1; i >= 0; i--) {
347
+ const text = lines[i];
348
+ if (!PAREN_NOTE.test(text)) {
349
+ return sanitizeGateSaid(text);
350
+ }
351
+ }
352
+ return null;
353
+ }
354
+ /** Stdout parsed as one JSON object, or null when it is not JSON or will not parse. */
355
+ function jsonStdout(stdout, stdoutIsJson) {
356
+ if (!stdoutIsJson || typeof stdout !== 'string' || !stdout.trimStart().startsWith('{')) {
357
+ return null;
358
+ }
359
+ try {
360
+ const parsed = JSON.parse(stdout);
361
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
362
+ return null;
363
+ }
364
+ return parsed;
365
+ }
366
+ catch {
367
+ return null;
368
+ }
369
+ }
370
+ /** A gate's own couldNotRun field, as one quoted line. Null when the field is absent. */
371
+ function couldNotRunExcerpt(record) {
372
+ if (record === null) {
373
+ return null;
374
+ }
375
+ const run = record.run;
376
+ const candidates = [
377
+ record.couldNotRun,
378
+ typeof run === 'object' && run !== null ? run.couldNotRun : undefined,
379
+ ];
380
+ for (const candidate of candidates) {
381
+ const excerpt = formatCouldNotRun(candidate);
382
+ if (excerpt !== null) {
383
+ return excerpt;
384
+ }
385
+ }
386
+ return null;
387
+ }
388
+ function formatCouldNotRun(value) {
389
+ if (typeof value === 'string') {
390
+ return sanitizeGateSaid(value);
391
+ }
392
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) {
393
+ return null;
394
+ }
395
+ const field = value;
396
+ const message = typeof field.message === 'string' ? field.message : null;
397
+ const code = typeof field.code === 'string' ? field.code : null;
398
+ if (message !== null && code !== null) {
399
+ return sanitizeGateSaid(`${message} (${code})`);
400
+ }
401
+ if (message !== null) {
402
+ return sanitizeGateSaid(message);
403
+ }
404
+ if (code !== null) {
405
+ return sanitizeGateSaid(code);
406
+ }
407
+ return null;
408
+ }
409
+ /** A string `reason` field, top level or on `run`, the fallback the first-line rule already had. */
410
+ function reasonExcerpt(record) {
411
+ if (record === null) {
412
+ return null;
413
+ }
414
+ const run = record.run;
415
+ const candidates = [
416
+ record.reason,
417
+ typeof run === 'object' && run !== null ? run.reason : undefined,
418
+ ];
419
+ for (const candidate of candidates) {
420
+ if (typeof candidate === 'string') {
421
+ const excerpt = sanitizeGateSaid(candidate);
422
+ if (excerpt !== null) {
423
+ return excerpt;
424
+ }
425
+ }
426
+ }
427
+ return null;
428
+ }
327
429
  /**
328
430
  * What a gate that exited with a non-verdict code said about why.
329
431
  *
330
432
  * TOTAL, and never a decision: the caller has already settled that this is a
331
- * could-not-run, and nothing here can change that. stderr is preferred, since
332
- * that is where every gate in the family prints its reason on exit 2
333
- * (dep-guard, intent-guard and vault-guard all do), read by the rule in
334
- * `statedReasonFromStderr`: the line the gate marks as the failure, never an
335
- * informational line. Failing that, stdout is parsed only for a gate whose
336
- * output is JSON on stdout, and only a string `reason` field (top level, or
337
- * on `run`) is read; anything else, including output that does not parse, is
338
- * simply no excerpt. An absent excerpt is better than quoting a warning as
339
- * the cause; the full stderr is still printed in the text report.
433
+ * could-not-run, and nothing here can change that.
434
+ *
435
+ * 1. A gate that wrote JSON is quoted from its couldNotRun field when that
436
+ * field is present (top level, or on `run`): a string as itself, or an
437
+ * object from its message and, when it has one, its code.
438
+ * 2. Otherwise, when stderr contains a `note (...)` or `warning (...)` line,
439
+ * the last line that is neither. dep-guard 0.20.0 prints those notes
440
+ * before the could-not-run line, and the first-line rule quoted the note.
441
+ * 3. Otherwise the line `statedReasonFromStderr` already chose, and failing
442
+ * that a string `reason` field on JSON stdout.
443
+ *
444
+ * An absent excerpt is better than quoting a warning as the cause; the full
445
+ * stderr is still printed in the text report.
340
446
  */
341
447
  export function gateStatedReason(stderr, stdout, stdoutIsJson) {
342
448
  try {
449
+ const record = jsonStdout(stdout, stdoutIsJson);
450
+ const fromCouldNotRun = couldNotRunExcerpt(record);
451
+ if (fromCouldNotRun !== null) {
452
+ return fromCouldNotRun;
453
+ }
454
+ const fromTail = lastLineAfterParentheticalNotes(stderr);
455
+ if (fromTail !== null) {
456
+ return fromTail;
457
+ }
343
458
  const fromStderr = statedReasonFromStderr(stderr);
344
459
  if (fromStderr !== null) {
345
460
  return fromStderr;
346
461
  }
347
- if (!stdoutIsJson || typeof stdout !== 'string' || !stdout.trimStart().startsWith('{')) {
348
- return null;
349
- }
350
- const parsed = JSON.parse(stdout);
351
- if (typeof parsed !== 'object' || parsed === null) {
352
- return null;
353
- }
354
- const record = parsed;
355
- const run = record.run;
356
- const candidates = [
357
- record.reason,
358
- typeof run === 'object' && run !== null ? run.reason : undefined,
359
- ];
360
- for (const candidate of candidates) {
361
- if (typeof candidate === 'string') {
362
- const excerpt = sanitizeGateSaid(candidate);
363
- if (excerpt !== null) {
364
- return excerpt;
365
- }
366
- }
367
- }
368
- return null;
462
+ return reasonExcerpt(record);
369
463
  }
370
464
  catch {
371
465
  return null;
@@ -568,10 +662,16 @@ export function previewSpawnOptions(limitMs, preview, env) {
568
662
  * of 0 is no timeout at all.
569
663
  */
570
664
  function spawnLimits(limit, preview, env) {
665
+ // Every spawn in this file goes through here: the version probe, the
666
+ // scan, and both base runs of the vulnerabilities gate. The environment
667
+ // is the caller's, with replace refs turned off for git the gate runs
668
+ // itself (gateChildEnv). The intent gate's preparation spawns apply the
669
+ // same function in src/intent-prepare.ts.
670
+ const childEnv = gateChildEnv(env ?? process.env);
571
671
  if (preview === undefined) {
572
- return { start: true, limit, options: { timeout: limit.ms, ...(env === undefined ? {} : { env }) } };
672
+ return { start: true, limit, options: { timeout: limit.ms, env: childEnv } };
573
673
  }
574
- const options = previewSpawnOptions(limit.ms, preview, env ?? process.env);
674
+ const options = previewSpawnOptions(limit.ms, preview, childEnv);
575
675
  return {
576
676
  start: options.timeout > 0,
577
677
  limit: options.timeout < limit.ms ? { ms: options.timeout, source: 'preview-budget' } : limit,
@@ -1510,10 +1610,18 @@ function runGateInner(gate, options, started, progress) {
1510
1610
  // A history gate cannot vouch for history it was not given. Checked before
1511
1611
  // the version probe so nothing is executed for a run that cannot be honest.
1512
1612
  if (profileFor(gate.product).readsHistory && isShallowRepository(options.repoRoot)) {
1613
+ // Two wordings: a pull-request run reads a range from the base to HEAD,
1614
+ // and a run with no base (local, push, scheduled) reads the whole history,
1615
+ // where a range and a pull request are not what is being cut off.
1616
+ const cause = options.trustBase !== undefined
1617
+ ? 'is truncated: with the default actions/checkout depth of 1 the range from the base to HEAD ' +
1618
+ 'holds a single grafted commit, and a secret added and then removed inside the pull ' +
1619
+ 'request would never be seen.'
1620
+ : 'is truncated: the whole history this gate reads is cut off at the graft (with the default ' +
1621
+ 'actions/checkout depth of 1, at the single checked-out commit), so older commits and a ' +
1622
+ 'secret added and later removed would never be seen.';
1513
1623
  const detail = `${gate.product} did not run, because this checkout is shallow and the git history it reads ` +
1514
- 'is truncated: with the default actions/checkout depth of 1 the range from the base to HEAD ' +
1515
- 'holds a single grafted commit, and a secret added and then removed inside the pull ' +
1516
- 'request would never be seen. Fix: check out with fetch-depth: 0 (actions/checkout) or run ' +
1624
+ `${cause} Fix: check out with fetch-depth: 0 (actions/checkout) or run ` +
1517
1625
  'git fetch --unshallow, then run again. conductor does not deepen the checkout itself.';
1518
1626
  return {
1519
1627
  ...base,
package/dist/git.d.ts CHANGED
@@ -12,6 +12,76 @@ export declare function currentGitProgram(): string;
12
12
  * on a pull-request run, with an absolute path; tests call it to reset.
13
13
  */
14
14
  export declare function useGitProgram(program: string): void;
15
+ /**
16
+ * A graft file path that cannot exist: /dev/null is not a directory, so
17
+ * nothing can be created under it. The same value the Action's fetch step
18
+ * exports (action.yml, "Fetch the trust base"). git reads a missing graft
19
+ * file as no grafts, without a warning.
20
+ */
21
+ export declare const NO_GRAFT_FILE = "/dev/null/conductor-no-grafts";
22
+ /**
23
+ * The environment of every git call conductor makes itself: the caller's
24
+ * own, with replace objects off and the graft file pointed at nothing.
25
+ *
26
+ * A replace ref swaps one object for another and a graft gives a commit
27
+ * other parents, both from files in the git directory that no commit
28
+ * records. The trees were always read without the first. The second matters
29
+ * since the adoption proposal (issue 101), which asks what the merge bases
30
+ * of two commits are and what the base branch's own first-parent history
31
+ * touched: both answers are read from parents, and a graft would rewrite
32
+ * them. Set last, so a value already in the environment never wins.
33
+ */
34
+ export declare function pinnedGitEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
35
+ /**
36
+ * Configuration set on the command line of every git call conductor makes
37
+ * itself, ahead of the subcommand. The command line outranks every other
38
+ * place git reads configuration from: the system, global and repository
39
+ * files, anything they include, and GIT_CONFIG_COUNT in the environment.
40
+ *
41
+ * - core.useReplaceRefs=false. GIT_NO_REPLACE_OBJECTS is NOT enough on its
42
+ * own: the same key set to true in any configuration git reads turns
43
+ * replacement back on over the variable (seen on git 2.39.3), and a
44
+ * replace ref can then swap the base commit for one with another tree and
45
+ * other parents. The variable stays as well, for a git where it is the
46
+ * one that counts.
47
+ * - core.commitGraph=false. A commit-graph file in the git directory holds
48
+ * each commit's parents and root tree, and no commit records it, so every
49
+ * read takes both from the commit object itself.
50
+ */
51
+ export declare const PINNED_GIT_CONFIG: readonly string[];
52
+ /**
53
+ * The environment of a gate conductor starts: `env`, plus the pins below.
54
+ * GIT_TEST_COMMIT_GRAPH is not passed on. A `-c` the gate itself adds is
55
+ * not something this function can outrank.
56
+ *
57
+ * conductor cannot put anything on the command line of a git call a gate
58
+ * makes itself. What it can give the gate is the two environment channels
59
+ * git reads configuration from. Numbered GIT_CONFIG_COUNT pairs are read
60
+ * after every configuration file, so an entry there outranks
61
+ * core.useReplaceRefs=true in the repository's configuration or a global
62
+ * one. GIT_CONFIG_PARAMETERS is read after those numbered entries, so it
63
+ * outranks them and the files. GIT_NO_REPLACE_OBJECTS does not: such a
64
+ * setting turns replacement back on over it. A -c the gate passes on its
65
+ * own git command line is read after GIT_CONFIG_PARAMETERS and still wins;
66
+ * none of the spawns here pass one.
67
+ *
68
+ * The numbered entry is APPENDED, at the index the caller's own count ends
69
+ * on, never written at index 0: the caller's entries are kept (an Action's
70
+ * authentication header is one), and of two entries for one key git takes
71
+ * the later. It is core.useReplaceRefs=false only. The same value, and
72
+ * core.commitGraph=false, are appended to GIT_CONFIG_PARAMETERS after
73
+ * exactly one space. When the caller's value is unset or the empty string
74
+ * the two pins are the whole value, with no leading space. The caller's
75
+ * value is not trimmed, parsed or repaired.
76
+ *
77
+ * A count git refuses is left exactly as it is and nothing is appended to
78
+ * the numbered entries. The parameters pins are still set on that branch,
79
+ * so there is no branch where they are absent. With a count git refuses,
80
+ * every git call fails, and a failed read is a refusal everywhere here;
81
+ * rewriting the count to make git work again would be conductor deciding
82
+ * what the caller meant. Returns a new object and never changes `env`.
83
+ */
84
+ export declare function gateChildEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
15
85
  /** Runs one git command in `cwd`, reading stdout as UTF-8. Never throws. */
16
86
  export declare function runGit(cwd: string, args: readonly string[], options?: {
17
87
  maxBuffer?: number;