@vaultcompass/conductor 0.4.6 → 0.5.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 +526 -169
- package/dist/cli.js +47 -9
- package/dist/envelope.js +1 -1
- package/dist/exit-codes.js +5 -1
- package/dist/external-config.d.ts +54 -0
- package/dist/external-config.js +171 -0
- package/dist/gate-runner.d.ts +43 -3
- package/dist/gate-runner.js +463 -37
- package/dist/init-policy.d.ts +19 -1
- package/dist/init-policy.js +42 -8
- package/dist/init.d.ts +30 -1
- package/dist/init.js +108 -19
- package/dist/normalize.d.ts +7 -1
- package/dist/normalize.js +309 -5
- package/dist/output-sarif.js +3 -2
- package/dist/output-text.d.ts +41 -0
- package/dist/output-text.js +68 -9
- package/dist/policy.d.ts +10 -4
- package/dist/policy.js +100 -14
- package/dist/products.d.ts +91 -0
- package/dist/products.js +123 -0
- package/dist/resolve.js +18 -4
- package/dist/run.js +3 -0
- package/package.json +1 -1
- package/schema/guardrails.schema.json +7 -5
package/dist/cli.js
CHANGED
|
@@ -10,10 +10,10 @@ import { execFileSync } from 'node:child_process';
|
|
|
10
10
|
import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
|
|
11
11
|
import path from 'node:path';
|
|
12
12
|
import { fileURLToPath } from 'node:url';
|
|
13
|
-
import { EXIT_COULD_NOT_RUN } from './exit-codes.js';
|
|
13
|
+
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
|
|
14
14
|
import { applyInit, planInit, renderInitHuman, renderRevertHuman, revertInit, } from './init.js';
|
|
15
15
|
import { renderSarif } from './output-sarif.js';
|
|
16
|
-
import { renderText } from './output-text.js';
|
|
16
|
+
import { jobLogSummary, renderText } from './output-text.js';
|
|
17
17
|
import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
|
|
18
18
|
import { refusedTrustBase, runAll } from './run.js';
|
|
19
19
|
import { policyDiffers, readPolicyAtRef, refuseTrustBaseRef } from './trust-base.js';
|
|
@@ -65,6 +65,27 @@ function repoRoot(cwd) {
|
|
|
65
65
|
throw new Error(`git could not be run to find the repository root: ${err.message}`);
|
|
66
66
|
}
|
|
67
67
|
}
|
|
68
|
+
/**
|
|
69
|
+
* The process exit code for a run, with --advisory applied.
|
|
70
|
+
*
|
|
71
|
+
* ONE PLACE, so the mapping cannot drift from what the verdict line claims:
|
|
72
|
+
* this reads the same `result.exitCode` that `renderText`'s own `advisory`
|
|
73
|
+
* option reads, and the two are always passed the same boolean from the same
|
|
74
|
+
* call site below.
|
|
75
|
+
*
|
|
76
|
+
* ONLY EXIT_BLOCKED (1) IS EVER REMAPPED, and only to EXIT_OK (0). A gate
|
|
77
|
+
* that could not run (2) is left exactly alone: "advisory" means a finding
|
|
78
|
+
* does not block, never that the umbrella cannot fail. Swallowing a
|
|
79
|
+
* could-not-run exit is the precise failure this flag exists to close (a
|
|
80
|
+
* crashed `npm audit signatures` read as nothing wrong for two days,
|
|
81
|
+
* issue #36, because every step carried `continue-on-error` instead of a
|
|
82
|
+
* flag that only ever touches a FINDING's verdict). Any other code -- there
|
|
83
|
+
* is none today besides 0, 1 and 2, but a future one would land here too --
|
|
84
|
+
* passes through unchanged for the same reason.
|
|
85
|
+
*/
|
|
86
|
+
function applyAdvisory(exitCode, advisory) {
|
|
87
|
+
return advisory && exitCode === EXIT_BLOCKED ? EXIT_OK : exitCode;
|
|
88
|
+
}
|
|
68
89
|
/**
|
|
69
90
|
* Reads the policy for one run, from the base ref in pull-request mode.
|
|
70
91
|
*
|
|
@@ -223,11 +244,15 @@ export function buildProgram() {
|
|
|
223
244
|
.exitOverride();
|
|
224
245
|
program
|
|
225
246
|
.command('init')
|
|
226
|
-
.description('Write the policy file
|
|
247
|
+
.description('Write the policy file. Add --hook for a pre-commit hook running the commit-stage gates.')
|
|
227
248
|
.option('--dry-run', 'print every file that would be written or changed, and write nothing')
|
|
228
|
-
.option('--
|
|
249
|
+
.option('--hook', 'also write a pre-commit hook running the commit-stage gates. Without it, only the policy ' +
|
|
250
|
+
'file and the manifest are written. .git/hooks is never part of a clone, so a second ' +
|
|
251
|
+
'clone needs its own "conductor init --hook".')
|
|
252
|
+
.option('--adopt', "replace a gate's own pre-commit hook with the umbrella hook (needs --hook)")
|
|
229
253
|
.option('--revert', 'remove exactly what a previous init wrote')
|
|
230
|
-
.option('--force', 'act on a file that has changed since init wrote it: replace a managed hook somebody has
|
|
254
|
+
.option('--force', 'act on a file that has changed since init wrote it: replace a managed hook somebody has ' +
|
|
255
|
+
'edited (needs --hook), or with --revert remove one and restore any adopted hook')
|
|
231
256
|
.option('--json', 'print the result as JSON')
|
|
232
257
|
.exitOverride()
|
|
233
258
|
.action((options) => {
|
|
@@ -258,6 +283,7 @@ export function buildProgram() {
|
|
|
258
283
|
const initOptions = {
|
|
259
284
|
...shared,
|
|
260
285
|
...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
|
|
286
|
+
...(options.hook === undefined ? {} : { hook: options.hook }),
|
|
261
287
|
...(options.adopt === undefined ? {} : { adopt: options.adopt }),
|
|
262
288
|
...(options.force === undefined ? {} : { force: options.force }),
|
|
263
289
|
};
|
|
@@ -286,6 +312,7 @@ export function buildProgram() {
|
|
|
286
312
|
.option('--verbose', 'print the full per-gate report even when the run is clean. A clean run prints one summary line by default, because a pre-commit hook that prints a screenful on every commit is a hook a team switches off. Text output only; SARIF is unaffected.')
|
|
287
313
|
.option('--compact-on-refusal', 'when the trust base was refused and no gate ran, print a short body instead of the full refusal report: the version, the verdict, and the refusal reason (with its remedy, when one applies), never the full per-gate report. Built for the pull-request-comment step; every other run is unaffected, whatever --verbose says. Text output only; SARIF is unaffected.')
|
|
288
314
|
.option('--gate <role>', 'restrict the run to this role; repeatable', (value, previous = []) => [...previous, value])
|
|
315
|
+
.option('--advisory', 'maps exit 1 (every enabled gate ran and at least one blocked) to exit 0, so a blocking finding never fails this run. A gate that could not run is unaffected and still exits 2: advisory changes what a FINDING does, never what a broken gate does. The report is unchanged and a blocking finding still prints as BLOCKING; only the process exit code and the verdict line, which says findings were advisory, are different.')
|
|
289
316
|
.exitOverride()
|
|
290
317
|
.action((options) => {
|
|
291
318
|
const cwd = process.cwd();
|
|
@@ -317,12 +344,18 @@ export function buildProgram() {
|
|
|
317
344
|
...(options.spec === undefined ? {} : { spec: options.spec }),
|
|
318
345
|
...(source.trustBase === undefined ? {} : { trustBase: source.trustBase }),
|
|
319
346
|
});
|
|
347
|
+
const advisory = Boolean(options.advisory);
|
|
348
|
+
// SARIF carries no verdict line, so --advisory has nothing to say
|
|
349
|
+
// there: each finding's `properties.blocking` is the gate's own
|
|
350
|
+
// decision (see output-sarif.ts) and is unaffected by this flag,
|
|
351
|
+
// exactly as the text report's per-finding BLOCKING marker is.
|
|
320
352
|
const rendered = format === 'sarif'
|
|
321
353
|
? `${renderSarif(result, pkg.version)}\n`
|
|
322
354
|
: renderText(result, {
|
|
323
355
|
verbose: Boolean(options.verbose),
|
|
324
356
|
version: pkg.version,
|
|
325
357
|
compact: Boolean(options.compactOnRefusal),
|
|
358
|
+
advisory,
|
|
326
359
|
});
|
|
327
360
|
if (options.output === undefined) {
|
|
328
361
|
process.stdout.write(rendered);
|
|
@@ -335,11 +368,16 @@ export function buildProgram() {
|
|
|
335
368
|
// fail on a missing file with no explanation here.
|
|
336
369
|
writeFileSync(options.output, rendered);
|
|
337
370
|
// One line, so a CI job whose only product is an uploaded artifact
|
|
338
|
-
// does not read as a job that did nothing.
|
|
339
|
-
|
|
340
|
-
|
|
371
|
+
// does not read as a job that did nothing. jobLogSummary carries
|
|
372
|
+
// its own "N gate(s), N finding(s)" on an ordinary run, unchanged,
|
|
373
|
+
// and a refusal sentence instead on a refused run: refusedTrustBase
|
|
374
|
+
// fills result.gates and result.findings with one couldNotRun
|
|
375
|
+
// outcome per enabled gate, so the plain count used to read as
|
|
376
|
+
// "N gate(s), N finding(s)" on a run where nothing ran and nothing
|
|
377
|
+
// was found (issue #46).
|
|
378
|
+
process.stdout.write(`conductor run: ${jobLogSummary(result)}; ${format} report written to ${options.output}\n`);
|
|
341
379
|
}
|
|
342
|
-
process.exitCode = result.exitCode;
|
|
380
|
+
process.exitCode = applyAdvisory(result.exitCode, advisory);
|
|
343
381
|
}
|
|
344
382
|
catch (err) {
|
|
345
383
|
// One line, never a stack. runGate is total, so nothing from a gate
|
package/dist/envelope.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
//
|
|
3
3
|
// This shape is NOT published. SARIF is the family's published finding
|
|
4
4
|
// format, and every field here exists to make one SARIF mapping decision
|
|
5
|
-
// possible without the mapping having to know which of the
|
|
5
|
+
// possible without the mapping having to know which of the five gates it
|
|
6
6
|
// is looking at. Keeping it internal is what lets it change when a gate
|
|
7
7
|
// changes, without anybody's pipeline breaking.
|
|
8
8
|
//
|
package/dist/exit-codes.js
CHANGED
|
@@ -5,7 +5,11 @@
|
|
|
5
5
|
// third code, 2, for "could not run the checks at all"; the other two have
|
|
6
6
|
// only 0 and 1, and both use 1 for a rejected config as well as for a real
|
|
7
7
|
// finding. Taking a maximum would flatten dep-guard's distinction away and
|
|
8
|
-
// would call a broken config a policy violation.
|
|
8
|
+
// would call a broken config a policy violation. The two external gates
|
|
9
|
+
// have their own numbers again (gitleaks is handed --exit-code 3 for a
|
|
10
|
+
// leak, osv-scanner uses 128 for nothing to scan); the gate runner reads
|
|
11
|
+
// each child's exit through that product's profile (src/products.ts) before
|
|
12
|
+
// anything reaches this file.
|
|
9
13
|
//
|
|
10
14
|
// 2 an enabled gate could not run: its binary is missing, it exited 2,
|
|
11
15
|
// it was rejected its own config, or its output could not be parsed.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import type { ProductProfile } from './products.js';
|
|
2
|
+
export interface MaterializedIgnore {
|
|
3
|
+
/** A directory holding the base's ignore file (or an empty one). */
|
|
4
|
+
dir: string;
|
|
5
|
+
proposal: string | null;
|
|
6
|
+
}
|
|
7
|
+
export interface MaterializedConfig {
|
|
8
|
+
path: string;
|
|
9
|
+
proposal: string | null;
|
|
10
|
+
source: 'base' | 'neutral';
|
|
11
|
+
/** The tool's ignore file, for a tool that auto-loads one; null otherwise. */
|
|
12
|
+
ignore: MaterializedIgnore | null;
|
|
13
|
+
/**
|
|
14
|
+
* The directory to run the tool from. Every relative path the base config
|
|
15
|
+
* names ([extend] path, a baseline) was materialised here from the base
|
|
16
|
+
* ref, so it resolves here and never in the head tree.
|
|
17
|
+
*/
|
|
18
|
+
cwd: string;
|
|
19
|
+
/** Head-side differences in those materialised files, one line each. */
|
|
20
|
+
extendProposals: string[];
|
|
21
|
+
}
|
|
22
|
+
/** The base ref's config cannot be materialised; the gate cannot run safely. */
|
|
23
|
+
export declare class ExternalConfigError extends Error {
|
|
24
|
+
constructor(message: string);
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* The `[extend] path` a gitleaks config names, or null when it names none.
|
|
28
|
+
*
|
|
29
|
+
* A deliberately small reader rather than a TOML parser: it looks for the
|
|
30
|
+
* `path` key inside an `[extend]` table, or a top-level `extend.path`, and
|
|
31
|
+
* accepts a basic or literal string. A config that names an extend path in
|
|
32
|
+
* any other spelling is refused rather than guessed at, because a missed
|
|
33
|
+
* extend is exactly a file read from the head.
|
|
34
|
+
*/
|
|
35
|
+
export declare function extendPath(config: string): string | null;
|
|
36
|
+
/**
|
|
37
|
+
* Proposals for config files in subdirectories that differ from the base.
|
|
38
|
+
*
|
|
39
|
+
* osv-scanner loads an osv-scanner.toml from each lockfile's own directory
|
|
40
|
+
* when no --config is given. On a pull request --config is always given, so
|
|
41
|
+
* a nested file added or edited by the pull request has no effect on the run
|
|
42
|
+
* (measured against 2.6.0: a nested file ignoring lodash passes without
|
|
43
|
+
* --config and blocks with it). It is still a change to how the tool behaves
|
|
44
|
+
* once merged, so it is reported the way the root config is.
|
|
45
|
+
*/
|
|
46
|
+
export declare function nestedConfigProposals(repoRoot: string, trustBase: string, trackedFiles: readonly string[], configFile: string): string[];
|
|
47
|
+
export declare function materializeExternalConfig(args: {
|
|
48
|
+
repoRoot: string;
|
|
49
|
+
trustBase: string;
|
|
50
|
+
profile: ProductProfile;
|
|
51
|
+
tempRoot: string;
|
|
52
|
+
/** Further relative files the tool will read from its working directory, such as a baseline. */
|
|
53
|
+
extraFiles?: readonly string[];
|
|
54
|
+
}): MaterializedConfig | null;
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
// An external tool's config, read from the base ref on a pull request.
|
|
2
|
+
//
|
|
3
|
+
// Both external tools auto-load a config file out of the tree they scan:
|
|
4
|
+
// gitleaks reads .gitleaks.toml (and .gitleaksignore), osv-scanner reads
|
|
5
|
+
// osv-scanner.toml. On a pull request that tree is the head, so without this
|
|
6
|
+
// a pull request could add an allowlist entry for exactly the secret or the
|
|
7
|
+
// advisory it introduces, and the gate would read that entry and pass. The
|
|
8
|
+
// umbrella's own policy is read from the base ref for the same reason
|
|
9
|
+
// (src/trust-base.ts); this does the same for the files the external tools
|
|
10
|
+
// would otherwise pick up themselves.
|
|
11
|
+
//
|
|
12
|
+
// The umbrella ALWAYS hands over a path on a pull request. When the base has
|
|
13
|
+
// no config, the tool gets a neutral one (gitleaks' defaults, an empty
|
|
14
|
+
// osv-scanner config), because handing it nothing would let it find the
|
|
15
|
+
// head's file on its own. A head-side difference is not an error: it is
|
|
16
|
+
// reported as a proposal, which takes effect once it merges and the base
|
|
17
|
+
// carries it.
|
|
18
|
+
import { spawnSync } from 'node:child_process';
|
|
19
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
20
|
+
import path from 'node:path';
|
|
21
|
+
/** The base ref's config cannot be materialised; the gate cannot run safely. */
|
|
22
|
+
export class ExternalConfigError extends Error {
|
|
23
|
+
constructor(message) {
|
|
24
|
+
super(message);
|
|
25
|
+
this.name = 'ExternalConfigError';
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* The `[extend] path` a gitleaks config names, or null when it names none.
|
|
30
|
+
*
|
|
31
|
+
* A deliberately small reader rather than a TOML parser: it looks for the
|
|
32
|
+
* `path` key inside an `[extend]` table, or a top-level `extend.path`, and
|
|
33
|
+
* accepts a basic or literal string. A config that names an extend path in
|
|
34
|
+
* any other spelling is refused rather than guessed at, because a missed
|
|
35
|
+
* extend is exactly a file read from the head.
|
|
36
|
+
*/
|
|
37
|
+
export function extendPath(config) {
|
|
38
|
+
let inExtend = false;
|
|
39
|
+
let beforeAnyTable = true;
|
|
40
|
+
for (const raw of config.split(/\r?\n/)) {
|
|
41
|
+
const line = raw.replace(/^\s+/, '');
|
|
42
|
+
if (line.startsWith('#') || line === '') {
|
|
43
|
+
continue;
|
|
44
|
+
}
|
|
45
|
+
if (line.startsWith('[')) {
|
|
46
|
+
beforeAnyTable = false;
|
|
47
|
+
inExtend = /^\[\s*extend\s*\]\s*(#.*)?$/.test(line);
|
|
48
|
+
continue;
|
|
49
|
+
}
|
|
50
|
+
const key = inExtend ? /^path\s*=/ : beforeAnyTable ? /^extend\.path\s*=/ : null;
|
|
51
|
+
if (key === null || !key.test(line)) {
|
|
52
|
+
continue;
|
|
53
|
+
}
|
|
54
|
+
const value = /=\s*(?:"([^"\\]*)"|'([^']*)')\s*(#.*)?$/.exec(line);
|
|
55
|
+
if (value === null) {
|
|
56
|
+
throw new ExternalConfigError(`the base ref's config names an [extend] path in a form conductor does not read (${line.trim()}); ` +
|
|
57
|
+
'write it as a plain quoted string.');
|
|
58
|
+
}
|
|
59
|
+
return value[1] ?? value[2] ?? null;
|
|
60
|
+
}
|
|
61
|
+
return null;
|
|
62
|
+
}
|
|
63
|
+
/** A file's contents at a ref, or null when the ref does not have it. */
|
|
64
|
+
function showAtRef(repoRoot, ref, file) {
|
|
65
|
+
const child = spawnSync('git', ['show', `${ref}:${file}`], { cwd: repoRoot, encoding: 'utf8' });
|
|
66
|
+
return child.status === 0 && typeof child.stdout === 'string' ? child.stdout : null;
|
|
67
|
+
}
|
|
68
|
+
function headCopy(repoRoot, file) {
|
|
69
|
+
const full = path.join(repoRoot, file);
|
|
70
|
+
return existsSync(full) ? readFileSync(full, 'utf8') : null;
|
|
71
|
+
}
|
|
72
|
+
function differs(file, base, head) {
|
|
73
|
+
if (head === null || head === base) {
|
|
74
|
+
return null;
|
|
75
|
+
}
|
|
76
|
+
return `${file} differs from the base ref; the base's copy was used and this change takes effect after merge.`;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Copies one relative file from the base ref into the run directory, at the
|
|
80
|
+
* same relative path, and returns its base contents. Refuses a path that is
|
|
81
|
+
* absolute or climbs out of the run directory, and a file the base ref does
|
|
82
|
+
* not have: either way the tool would read something no ref approved.
|
|
83
|
+
*/
|
|
84
|
+
function materializeRelative(repoRoot, trustBase, cwd, file, what) {
|
|
85
|
+
const target = path.resolve(cwd, file);
|
|
86
|
+
if (path.isAbsolute(file) || !target.startsWith(`${cwd}${path.sep}`)) {
|
|
87
|
+
throw new ExternalConfigError(`${what} ${file} is not a path inside the repository, so conductor cannot read it from ` +
|
|
88
|
+
'the base ref; name it relative to the repository root.');
|
|
89
|
+
}
|
|
90
|
+
const base = showAtRef(repoRoot, trustBase, path.relative(cwd, target).split(path.sep).join('/'));
|
|
91
|
+
if (base === null) {
|
|
92
|
+
throw new ExternalConfigError(`${what} ${file} does not exist on the base ref ${trustBase}, so there is no approved copy ` +
|
|
93
|
+
'to read; commit it to the base branch or remove the reference.');
|
|
94
|
+
}
|
|
95
|
+
mkdirSync(path.dirname(target), { recursive: true });
|
|
96
|
+
writeFileSync(target, base);
|
|
97
|
+
return base;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Proposals for config files in subdirectories that differ from the base.
|
|
101
|
+
*
|
|
102
|
+
* osv-scanner loads an osv-scanner.toml from each lockfile's own directory
|
|
103
|
+
* when no --config is given. On a pull request --config is always given, so
|
|
104
|
+
* a nested file added or edited by the pull request has no effect on the run
|
|
105
|
+
* (measured against 2.6.0: a nested file ignoring lodash passes without
|
|
106
|
+
* --config and blocks with it). It is still a change to how the tool behaves
|
|
107
|
+
* once merged, so it is reported the way the root config is.
|
|
108
|
+
*/
|
|
109
|
+
export function nestedConfigProposals(repoRoot, trustBase, trackedFiles, configFile) {
|
|
110
|
+
return trackedFiles
|
|
111
|
+
.filter((file) => file !== configFile && path.posix.basename(file) === configFile)
|
|
112
|
+
.map((file) => differs(file, showAtRef(repoRoot, trustBase, file), headCopy(repoRoot, file)))
|
|
113
|
+
.filter((proposal) => proposal !== null);
|
|
114
|
+
}
|
|
115
|
+
export function materializeExternalConfig(args) {
|
|
116
|
+
const { repoRoot, trustBase, profile, tempRoot } = args;
|
|
117
|
+
if (profile.configFile === null) {
|
|
118
|
+
return null;
|
|
119
|
+
}
|
|
120
|
+
const base = showAtRef(repoRoot, trustBase, profile.configFile);
|
|
121
|
+
const ext = path.extname(profile.configFile) || '.toml';
|
|
122
|
+
const out = path.join(tempRoot, `${profile.product}-config${ext}`);
|
|
123
|
+
writeFileSync(out, base ?? profile.neutralConfig ?? '');
|
|
124
|
+
// The run directory. gitleaks resolves a relative [extend] path against
|
|
125
|
+
// its working directory, which would otherwise be the head tree: a base
|
|
126
|
+
// config extending gl-extra.toml would read the pull request's copy of it.
|
|
127
|
+
const cwd = path.join(tempRoot, 'cwd');
|
|
128
|
+
mkdirSync(cwd, { recursive: true });
|
|
129
|
+
const extendProposals = [];
|
|
130
|
+
const recordDifference = (file, baseCopy) => {
|
|
131
|
+
const proposal = differs(file, baseCopy, headCopy(repoRoot, file));
|
|
132
|
+
if (proposal !== null) {
|
|
133
|
+
extendProposals.push(proposal);
|
|
134
|
+
}
|
|
135
|
+
};
|
|
136
|
+
if (profile.followsConfigExtend && base !== null) {
|
|
137
|
+
// An extended file may extend again. Followed to a small fixed depth,
|
|
138
|
+
// each hop from the base ref; a longer chain is refused, not truncated.
|
|
139
|
+
let next = extendPath(base);
|
|
140
|
+
for (let depth = 0; next !== null; depth += 1) {
|
|
141
|
+
if (depth >= 4) {
|
|
142
|
+
throw new ExternalConfigError('the base config [extend] chain is longer than four files.');
|
|
143
|
+
}
|
|
144
|
+
const copy = materializeRelative(repoRoot, trustBase, cwd, next, 'the [extend] path');
|
|
145
|
+
recordDifference(next, copy);
|
|
146
|
+
next = extendPath(copy);
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
for (const file of args.extraFiles ?? []) {
|
|
150
|
+
recordDifference(file, materializeRelative(repoRoot, trustBase, cwd, file, 'the file'));
|
|
151
|
+
}
|
|
152
|
+
let ignore = null;
|
|
153
|
+
if (profile.ignoreFile !== null) {
|
|
154
|
+
const name = profile.ignoreFile.name;
|
|
155
|
+
const baseIgnore = showAtRef(repoRoot, trustBase, name);
|
|
156
|
+
const dir = path.join(tempRoot, `${profile.product}-ignore`);
|
|
157
|
+
mkdirSync(dir, { recursive: true });
|
|
158
|
+
// An empty file when the base has none, for the reason the neutral
|
|
159
|
+
// config exists: pointing the tool anywhere else lets it find the head's.
|
|
160
|
+
writeFileSync(path.join(dir, name), baseIgnore ?? '');
|
|
161
|
+
ignore = { dir, proposal: differs(name, baseIgnore, headCopy(repoRoot, name)) };
|
|
162
|
+
}
|
|
163
|
+
return {
|
|
164
|
+
path: out,
|
|
165
|
+
proposal: differs(profile.configFile, base, headCopy(repoRoot, profile.configFile)),
|
|
166
|
+
source: base === null ? 'neutral' : 'base',
|
|
167
|
+
ignore,
|
|
168
|
+
cwd,
|
|
169
|
+
extendProposals,
|
|
170
|
+
};
|
|
171
|
+
}
|
package/dist/gate-runner.d.ts
CHANGED
|
@@ -24,7 +24,19 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
|
|
|
24
24
|
* places: one is a packaging problem with the installed gate, and this one
|
|
25
25
|
* is a pull request choosing the program that judges it.
|
|
26
26
|
*/
|
|
27
|
-
| 'gate-program-refused'
|
|
27
|
+
| 'gate-program-refused'
|
|
28
|
+
/**
|
|
29
|
+
* The installed build is older than the oldest version whose command line
|
|
30
|
+
* the umbrella speaks (`minVersion` in src/products.ts). Only the external
|
|
31
|
+
* tools have a floor; nothing was run beyond the version probe.
|
|
32
|
+
*/
|
|
33
|
+
| 'gate-version-unsupported'
|
|
34
|
+
/**
|
|
35
|
+
* The gate exited with a verdict but the report file it writes that
|
|
36
|
+
* verdict to is not there. Only a tool whose output is a report file can
|
|
37
|
+
* land here.
|
|
38
|
+
*/
|
|
39
|
+
| 'report-missing';
|
|
28
40
|
export interface CouldNotRun {
|
|
29
41
|
reason: CouldNotRunReason;
|
|
30
42
|
detail: string;
|
|
@@ -32,7 +44,7 @@ export interface CouldNotRun {
|
|
|
32
44
|
/**
|
|
33
45
|
* The first version of each gate that understands `--trust-base`.
|
|
34
46
|
*
|
|
35
|
-
* A TABLE rather than a boolean, because the three gates
|
|
47
|
+
* A TABLE rather than a boolean, because the three family gates got pull-request
|
|
36
48
|
* mode in three separate releases and the umbrella has to keep working
|
|
37
49
|
* against every combination in the meantime. A product missing from this
|
|
38
50
|
* table has no pull-request mode yet and is never handed the flag; a product
|
|
@@ -178,6 +190,13 @@ export interface RunGateOptions {
|
|
|
178
190
|
* Offered to every child; `decideTrustBase` says which ones can take it.
|
|
179
191
|
*/
|
|
180
192
|
trustBase?: string;
|
|
193
|
+
/**
|
|
194
|
+
* The directory under which this gate's own working directory is made, for
|
|
195
|
+
* an external tool's report file and materialised config. The runner
|
|
196
|
+
* removes what it made. Defaults to the system temporary directory; tests
|
|
197
|
+
* inject one so they can see that nothing is left behind.
|
|
198
|
+
*/
|
|
199
|
+
tempRoot?: string;
|
|
181
200
|
}
|
|
182
201
|
/**
|
|
183
202
|
* A gate that never got as far as being spawned.
|
|
@@ -220,6 +239,25 @@ export declare function refuseHeadControlledBinary(repoRoot: string, trustBase:
|
|
|
220
239
|
* and keep the run green.
|
|
221
240
|
*/
|
|
222
241
|
export declare function gateProgramRefused(gate: GatePolicy, trustBase: string, refusal: string, binary: ResolvedBinary): GateOutcome;
|
|
242
|
+
/**
|
|
243
|
+
* Files the runner owns on an external tool's behalf: where gitleaks writes
|
|
244
|
+
* its report, and the config materialised from the base ref on a pull
|
|
245
|
+
* request (src/external-config.ts).
|
|
246
|
+
*/
|
|
247
|
+
export interface ExternalArgs {
|
|
248
|
+
reportPath?: string;
|
|
249
|
+
configPath?: string;
|
|
250
|
+
/** Where the tool's ignore file was materialised (gitleaks only). */
|
|
251
|
+
ignorePath?: string;
|
|
252
|
+
/**
|
|
253
|
+
* What gitleaks scans, when not the working tree. On a pull request it is
|
|
254
|
+
* the repository's git directory: the same history, with no head-written
|
|
255
|
+
* .gitleaksignore at its root for gitleaks to load on its own.
|
|
256
|
+
*/
|
|
257
|
+
scanRoot?: string;
|
|
258
|
+
/** The tracked lockfiles osv-scanner is handed, repository-relative. */
|
|
259
|
+
lockfiles?: readonly string[];
|
|
260
|
+
}
|
|
223
261
|
/**
|
|
224
262
|
* The arguments the umbrella adds, per product.
|
|
225
263
|
*
|
|
@@ -241,7 +279,9 @@ export declare function gateArgs(gate: GatePolicy, staged: boolean, intent: Inte
|
|
|
241
279
|
* `decideTrustBase`; nothing here re-decides it, so a gate that cannot take
|
|
242
280
|
* the flag is never handed one by a second opinion written in this switch.
|
|
243
281
|
*/
|
|
244
|
-
trustBase?: string
|
|
282
|
+
trustBase?: string,
|
|
283
|
+
/** Paths the runner owns for an external tool; the npm gates ignore them. */
|
|
284
|
+
external?: ExternalArgs): string[];
|
|
245
285
|
/**
|
|
246
286
|
* Runs one gate. TOTAL: this never throws.
|
|
247
287
|
*
|