@vaultcompass/conductor 0.13.2 → 0.15.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 +145 -20
- package/dist/cli.d.ts +38 -0
- package/dist/cli.js +77 -6
- package/dist/gate-runner.d.ts +83 -4
- package/dist/gate-runner.js +288 -49
- package/dist/output-sarif.d.ts +2 -2
- package/dist/output-sarif.js +47 -2
- package/dist/output-text.d.ts +37 -1
- package/dist/output-text.js +125 -27
- package/dist/policy-diff.d.ts +43 -0
- package/dist/policy-diff.js +181 -0
- package/dist/resolve.d.ts +68 -0
- package/dist/resolve.js +156 -2
- package/dist/run.d.ts +63 -0
- package/dist/run.js +142 -21
- package/dist/trust-base.d.ts +34 -0
- package/dist/trust-base.js +83 -1
- package/package.json +1 -1
- package/schema/guardrails.schema.json +1 -1
package/dist/gate-runner.js
CHANGED
|
@@ -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 { runGit } from './git.js';
|
|
24
|
+
import { 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';
|
|
@@ -30,8 +30,9 @@ import { checkEmptiedAgainstBase, compareWithBase, comparisonFailed, } from './o
|
|
|
30
30
|
import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals, } from './external-config.js';
|
|
31
31
|
import { osvLockfileKind, profileFor } from './products.js';
|
|
32
32
|
import { unreadManifestsNote } from './unread-manifests.js';
|
|
33
|
-
import {
|
|
34
|
-
import {
|
|
33
|
+
import { escapeNonAscii } from './policy-diff.js';
|
|
34
|
+
import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledProgram } from './trust-base.js';
|
|
35
|
+
import { ResolveError, argumentCandidates, candidateNames, commandIsGateProgram, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
|
|
35
36
|
/** The longest excerpt of a gate's own reason that is carried. */
|
|
36
37
|
export const GATE_SAID_MAX_CHARS = 160;
|
|
37
38
|
/**
|
|
@@ -158,6 +159,9 @@ function limitSourcePhrase(gate, source, trustBase) {
|
|
|
158
159
|
? `gates.${gate.role}.timeout-seconds`
|
|
159
160
|
: `gates.${gate.role}.timeout-seconds on ${trustBase}`;
|
|
160
161
|
}
|
|
162
|
+
if (source === 'preview-budget') {
|
|
163
|
+
return 'what was left of the 300 s preview budget';
|
|
164
|
+
}
|
|
161
165
|
return source === 'default' ? 'the default for this gate' : 'set by the caller';
|
|
162
166
|
}
|
|
163
167
|
/**
|
|
@@ -178,7 +182,17 @@ function timedOutDetail(gate, step, limit, elapsedMs, trustBase) {
|
|
|
178
182
|
const elapsedSeconds = Math.round(elapsedMs / 1000);
|
|
179
183
|
const where = limitSourcePhrase(gate, limit.source, trustBase);
|
|
180
184
|
const own = gateOwnTimeoutNote(gate, limit, trustBase);
|
|
181
|
-
|
|
185
|
+
// A preview stopped by its own budget has no limit to raise: the budget is
|
|
186
|
+
// fixed, and the gate's own limit was not what stopped it.
|
|
187
|
+
const remedies = limit.source === 'preview-budget'
|
|
188
|
+
? 'The preview under the proposed rules has 300 s in all, whatever each gate\'s own limit.'
|
|
189
|
+
: profileFor(gate.product).timeoutRemedies(gate.role);
|
|
190
|
+
// A preview spawn with no budget left was never started (spawnLimits):
|
|
191
|
+
// there is no elapsed time or limit to report.
|
|
192
|
+
if (limit.source === 'preview-budget' && limit.ms === 0) {
|
|
193
|
+
const what = step === 'version-probe' ? `the version probe of ${gate.product}` : gate.product;
|
|
194
|
+
return `${what} was not started: the preview budget was spent, so nothing was checked by it. ${remedies}`;
|
|
195
|
+
}
|
|
182
196
|
if (step === 'version-probe') {
|
|
183
197
|
return (`the version probe of ${gate.product} was stopped at ${limitSeconds} s (${where}), so the gate ` +
|
|
184
198
|
'was not run and nothing was checked by it.');
|
|
@@ -436,6 +450,12 @@ function intentChangeChannel(gate, intent, version) {
|
|
|
436
450
|
}
|
|
437
451
|
return { kind: 'paths' };
|
|
438
452
|
}
|
|
453
|
+
/**
|
|
454
|
+
* Why dep-guard and vault-guard are not handed `--trust-base` in the preview
|
|
455
|
+
* under the proposed rules: the preview shows what the head's rules would do,
|
|
456
|
+
* and their own control files are part of those rules.
|
|
457
|
+
*/
|
|
458
|
+
export const PREVIEW_WITHHELD = 'preview under the proposed rules: this gate read its own control files from the head';
|
|
439
459
|
/**
|
|
440
460
|
* Whether this gate can be handed `--trust-base`, and why not when it cannot.
|
|
441
461
|
*
|
|
@@ -450,7 +470,14 @@ function intentChangeChannel(gate, intent, version) {
|
|
|
450
470
|
* was working a moment ago would report could-not-run. So the flag goes only
|
|
451
471
|
* where `--project` is the repository itself.
|
|
452
472
|
*/
|
|
453
|
-
export function decideTrustBase(gate, intent, trustBase, productVersion
|
|
473
|
+
export function decideTrustBase(gate, intent, trustBase, productVersion,
|
|
474
|
+
/**
|
|
475
|
+
* The preview under the proposed rules. dep-guard and vault-guard then read
|
|
476
|
+
* their own control files from the head, so the flag is withheld from them;
|
|
477
|
+
* the trust base itself stays set on the run, and every other product is
|
|
478
|
+
* decided exactly as without it.
|
|
479
|
+
*/
|
|
480
|
+
preview = false) {
|
|
454
481
|
if (trustBase === undefined) {
|
|
455
482
|
return undefined;
|
|
456
483
|
}
|
|
@@ -493,6 +520,15 @@ export function decideTrustBase(gate, intent, trustBase, productVersion) {
|
|
|
493
520
|
`was checked by it. Fix: install ${gate.product} ${minimum} or newer, or remove an ` +
|
|
494
521
|
'explicit older version pin.');
|
|
495
522
|
}
|
|
523
|
+
// AFTER both version refusals, so a gate refused in the primary run is
|
|
524
|
+
// refused in the preview too. Only the --trust-base flag is withheld: the
|
|
525
|
+
// run keeps its trust base, and with it the node_modules skip, the program
|
|
526
|
+
// refusal and the forced enforce, and dep-guard keeps --base (gateArgs'
|
|
527
|
+
// changeBase). gitleaks and osv-scanner never reach this: the umbrella
|
|
528
|
+
// itself is their pull-request mode, and it stays the base's.
|
|
529
|
+
if (preview && (gate.product === 'dep-guard' || gate.product === 'vault-guard')) {
|
|
530
|
+
return withheld(PREVIEW_WITHHELD);
|
|
531
|
+
}
|
|
496
532
|
// AFTER the version checks, so an imported contract cannot let an older
|
|
497
533
|
// gate run: this withholding is about where --project points, not about
|
|
498
534
|
// what the gate understands, and the contract itself came from the base.
|
|
@@ -506,6 +542,47 @@ export function decideTrustBase(gate, intent, trustBase, productVersion) {
|
|
|
506
542
|
}
|
|
507
543
|
return { ref: trustBase, withheld: null, refused: null, proposals: [] };
|
|
508
544
|
}
|
|
545
|
+
/** The smaller of a spawn's own limit and what is left of the preview budget, never negative. */
|
|
546
|
+
export function previewSpawnTimeout(limitMs, preview) {
|
|
547
|
+
return Math.max(0, Math.min(limitMs, preview.deadline - preview.clock()));
|
|
548
|
+
}
|
|
549
|
+
/**
|
|
550
|
+
* The spawn options of every preview spawn: the timeout above, SIGKILL, so a
|
|
551
|
+
* child that traps SIGTERM cannot outlive the budget, and the spawn's own
|
|
552
|
+
* environment with XDG_CACHE_HOME pointed at the preview's private cache, so
|
|
553
|
+
* nothing the head's rules fetched persists on a shared runner.
|
|
554
|
+
*/
|
|
555
|
+
export function previewSpawnOptions(limitMs, preview, env) {
|
|
556
|
+
return {
|
|
557
|
+
timeout: previewSpawnTimeout(limitMs, preview),
|
|
558
|
+
killSignal: 'SIGKILL',
|
|
559
|
+
env: { ...env, XDG_CACHE_HOME: preview.cacheDir },
|
|
560
|
+
};
|
|
561
|
+
}
|
|
562
|
+
/**
|
|
563
|
+
* The options one spawn passes to spawnSync beside its own, and the limit it
|
|
564
|
+
* ran under. Outside the preview: the full limit and nothing else, exactly as
|
|
565
|
+
* before. In the preview: `previewSpawnOptions`, and the limit's source is
|
|
566
|
+
* `preview-budget` when the budget left was the smaller. `start` false means
|
|
567
|
+
* no budget is left, and the spawn must not be started: a spawnSync timeout
|
|
568
|
+
* of 0 is no timeout at all.
|
|
569
|
+
*/
|
|
570
|
+
function spawnLimits(limit, preview, env) {
|
|
571
|
+
if (preview === undefined) {
|
|
572
|
+
return { start: true, limit, options: { timeout: limit.ms, ...(env === undefined ? {} : { env }) } };
|
|
573
|
+
}
|
|
574
|
+
const options = previewSpawnOptions(limit.ms, preview, env ?? process.env);
|
|
575
|
+
return {
|
|
576
|
+
start: options.timeout > 0,
|
|
577
|
+
limit: options.timeout < limit.ms ? { ms: options.timeout, source: 'preview-budget' } : limit,
|
|
578
|
+
options,
|
|
579
|
+
};
|
|
580
|
+
}
|
|
581
|
+
/** A spawnSync-shaped result for a preview spawn that was never started: no budget left. */
|
|
582
|
+
function notStartedResult() {
|
|
583
|
+
const error = Object.assign(new Error('spawnSync ETIMEDOUT: the preview budget was spent'), { code: 'ETIMEDOUT' });
|
|
584
|
+
return { pid: 0, output: [], stdout: '', stderr: '', status: null, signal: null, error };
|
|
585
|
+
}
|
|
509
586
|
/**
|
|
510
587
|
* A gate that never got as far as being spawned.
|
|
511
588
|
*
|
|
@@ -577,6 +654,13 @@ const EMPTY_RUN = {
|
|
|
577
654
|
* only the first left the probe free to spawn whatever the head put at the
|
|
578
655
|
* second, and a probe RUNS a program as thoroughly as a scan does.
|
|
579
656
|
*
|
|
657
|
+
* And every path the policy's `args:` name (`binary.argumentPaths`), because
|
|
658
|
+
* an interpreter `command:` takes the program as an argument: with `command:
|
|
659
|
+
* /usr/bin/node` and `args: [tools/gate/run.mjs]` the script judges, and
|
|
660
|
+
* vetting Node alone let a pull request rewrite the script (audit 2026-10-27,
|
|
661
|
+
* B1). The version probe's argv is a prefix of those same args, so it is
|
|
662
|
+
* covered by the same loop.
|
|
663
|
+
*
|
|
580
664
|
* The first refusal wins and the rest is not consulted. The verdict is the
|
|
581
665
|
* same either way, and the sentence a reader has to act on should name one
|
|
582
666
|
* file rather than two.
|
|
@@ -591,6 +675,12 @@ export function refuseHeadControlledBinary(repoRoot, trustBase, binary) {
|
|
|
591
675
|
return refusal;
|
|
592
676
|
}
|
|
593
677
|
}
|
|
678
|
+
for (const argument of binary.argumentPaths) {
|
|
679
|
+
const refusal = refuseHeadControlledArgument(repoRoot, trustBase, argument);
|
|
680
|
+
if (refusal !== null) {
|
|
681
|
+
return refusal;
|
|
682
|
+
}
|
|
683
|
+
}
|
|
594
684
|
return null;
|
|
595
685
|
}
|
|
596
686
|
/**
|
|
@@ -655,7 +745,22 @@ external = {},
|
|
|
655
745
|
* For the intent gate on a prepared run: hand it this base with its own
|
|
656
746
|
* `--base` in place of `--paths`. Decided by `intentChangeChannel`.
|
|
657
747
|
*/
|
|
658
|
-
intentBase
|
|
748
|
+
intentBase,
|
|
749
|
+
/**
|
|
750
|
+
* dep-guard's `--base` when `trustBase` is withheld from it in the preview
|
|
751
|
+
* under the proposed rules: the change is still measured against the base
|
|
752
|
+
* ref, only the rules are the head's. Ignored when `trustBase` is set, and
|
|
753
|
+
* by every other product.
|
|
754
|
+
*/
|
|
755
|
+
changeBase,
|
|
756
|
+
/**
|
|
757
|
+
* True for a spawn of the preview under the proposed rules. osv-scanner
|
|
758
|
+
* then gets `--no-call-analysis=all` appended after the base's own options,
|
|
759
|
+
* whatever they say: call analysis builds the project it scans, which in
|
|
760
|
+
* the preview is the head's code, and osv-scanner applies its disables
|
|
761
|
+
* after its enables, so the appended flag wins.
|
|
762
|
+
*/
|
|
763
|
+
preview = false) {
|
|
659
764
|
const passthrough = renderOptionFlags(gate.options);
|
|
660
765
|
const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
|
|
661
766
|
const config = external.configPath === undefined ? [] : ['--config', external.configPath];
|
|
@@ -680,7 +785,8 @@ intentBase) {
|
|
|
680
785
|
// name incompatible comparisons -- the git index versus an arbitrary
|
|
681
786
|
// ref. A staged run already has its own comparison and --trust-base
|
|
682
787
|
// is unaffected, since it answers a different question.
|
|
683
|
-
const
|
|
788
|
+
const baseRef = trustBase ?? changeBase;
|
|
789
|
+
const base = baseRef !== undefined && !staged ? ['--base', baseRef] : [];
|
|
684
790
|
return [...(staged ? ['--staged'] : []), '--format', 'json', ...trust, ...base, ...passthrough];
|
|
685
791
|
}
|
|
686
792
|
case 'vault-guard':
|
|
@@ -832,26 +938,30 @@ intentBase) {
|
|
|
832
938
|
...(noResolve ? ['--no-resolve'] : []),
|
|
833
939
|
...callAnalysis,
|
|
834
940
|
...renderOptionFlags(options),
|
|
941
|
+
...(preview ? ['--no-call-analysis=all'] : []),
|
|
835
942
|
];
|
|
836
943
|
}
|
|
837
944
|
}
|
|
838
945
|
}
|
|
839
|
-
function probeVersion(binary, product, repoRoot,
|
|
946
|
+
function probeVersion(binary, product, repoRoot, timeLimit, preview) {
|
|
840
947
|
const spec = profileFor(product).versionProbe;
|
|
841
948
|
if (binary.versionProbe === null || spec === null) {
|
|
842
949
|
return { kind: 'unreadable' };
|
|
843
950
|
}
|
|
951
|
+
const limits = spawnLimits(timeLimit, preview, undefined);
|
|
844
952
|
const probeStarted = Date.now();
|
|
845
|
-
const probe =
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
953
|
+
const probe = limits.start
|
|
954
|
+
? spawnSync(binary.versionProbe.command, binary.versionProbe.argv, {
|
|
955
|
+
cwd: repoRoot,
|
|
956
|
+
encoding: 'utf8',
|
|
957
|
+
...limits.options,
|
|
958
|
+
})
|
|
959
|
+
: notStartedResult();
|
|
850
960
|
// FIRST, before the status: a probe that handled SIGTERM can exit 0 with a
|
|
851
961
|
// version on stdout, and it was still stopped at the limit.
|
|
852
962
|
const failure = spawnFailure(probe);
|
|
853
963
|
if (failure !== null && failure.reason === 'timed-out') {
|
|
854
|
-
return { kind: 'timed-out', elapsedMs: Date.now() - probeStarted, signal: failure.signal };
|
|
964
|
+
return { kind: 'timed-out', elapsedMs: Date.now() - probeStarted, signal: failure.signal, limit: limits.limit };
|
|
855
965
|
}
|
|
856
966
|
if (probe.status !== 0 || typeof probe.stdout !== 'string') {
|
|
857
967
|
return { kind: 'unreadable' };
|
|
@@ -943,7 +1053,7 @@ export function expectedVersionBeforePreparation(gate, binary, options) {
|
|
|
943
1053
|
const skipped = options.trustBase === undefined ? null : nodeModulesCandidate(gate, options.repoRoot);
|
|
944
1054
|
const carried = { timeLimit, ...(skipped === null ? {} : { nodeModulesSkipped: skipped }) };
|
|
945
1055
|
const started = Date.now();
|
|
946
|
-
const probed = probeVersion(binary, gate.product, options.repoRoot, timeLimit
|
|
1056
|
+
const probed = probeVersion(binary, gate.product, options.repoRoot, timeLimit);
|
|
947
1057
|
if (probed.kind === 'timed-out') {
|
|
948
1058
|
// The same outcome runGate builds for a stopped probe under the
|
|
949
1059
|
// expectation: enforced, because the run cannot show this is the pinned
|
|
@@ -1136,6 +1246,83 @@ export function runGate(gate, options) {
|
|
|
1136
1246
|
};
|
|
1137
1247
|
}
|
|
1138
1248
|
}
|
|
1249
|
+
function callAnalysisOff(options) {
|
|
1250
|
+
const asList = (value) => (Array.isArray(value) ? value : [value]);
|
|
1251
|
+
for (const key of Object.keys(options)) {
|
|
1252
|
+
if (!key.includes('call-analysis'))
|
|
1253
|
+
continue;
|
|
1254
|
+
const value = options[key];
|
|
1255
|
+
if (key === 'no-call-analysis' && (value === true || asList(value).some((item) => item === 'all')))
|
|
1256
|
+
continue;
|
|
1257
|
+
return false;
|
|
1258
|
+
}
|
|
1259
|
+
return true;
|
|
1260
|
+
}
|
|
1261
|
+
/**
|
|
1262
|
+
* The three refusals only the preview under the proposed rules makes.
|
|
1263
|
+
*
|
|
1264
|
+
* An option value starting with "-" would render as a flag of its own
|
|
1265
|
+
* (renderOptionFlags), so a value the base never ran with could add an output
|
|
1266
|
+
* path or a second --log-opts. A base `command:` inside the working tree is
|
|
1267
|
+
* checked by refuseHeadControlledProgram for its own blob only, while what it
|
|
1268
|
+
* imports comes from the head, and the preview can reach a role the base has
|
|
1269
|
+
* switched off, whose command nobody has exercised (spec 5.2, finding 7).
|
|
1270
|
+
* osv-scanner call analysis builds the project it scans, here the head's
|
|
1271
|
+
* code, so only the all-off form of it is allowed (callAnalysisOff), and
|
|
1272
|
+
* gateArgs forces it off on every preview spawn besides.
|
|
1273
|
+
*/
|
|
1274
|
+
function previewRefusal(gate, repoRoot) {
|
|
1275
|
+
for (const name of Object.keys(gate.options).sort()) {
|
|
1276
|
+
const value = gate.options[name];
|
|
1277
|
+
const values = Array.isArray(value) ? value : [value];
|
|
1278
|
+
if (values.some((item) => typeof item === 'string' && item.startsWith('-'))) {
|
|
1279
|
+
return {
|
|
1280
|
+
reason: 'preparation-failed',
|
|
1281
|
+
detail: `preview under the proposed rules: option ${name} has a value starting with "-", so this gate was not run`,
|
|
1282
|
+
};
|
|
1283
|
+
}
|
|
1284
|
+
}
|
|
1285
|
+
// osv-scanner's call analysis builds the project it scans, and in the
|
|
1286
|
+
// preview that is the head's code (a Rust build.rs, for one).
|
|
1287
|
+
// Every option key is rendered as a flag, so the check is by key match:
|
|
1288
|
+
// any key containing "call-analysis" is refused unless it is the one
|
|
1289
|
+
// unambiguous all-off form, `no-call-analysis: true` or `all`. An absent
|
|
1290
|
+
// key is fine. Belt and braces: gateArgs appends --no-call-analysis=all
|
|
1291
|
+
// to every osv-scanner preview spawn as well.
|
|
1292
|
+
if (gate.product === 'osv-scanner' && !callAnalysisOff(gate.options)) {
|
|
1293
|
+
return {
|
|
1294
|
+
reason: 'preparation-failed',
|
|
1295
|
+
detail: "the preview does not run call analysis, because it would build the head's code",
|
|
1296
|
+
};
|
|
1297
|
+
}
|
|
1298
|
+
if (gate.command !== undefined && realPathInside(repoRoot, gate.command)) {
|
|
1299
|
+
return {
|
|
1300
|
+
reason: 'gate-program-refused',
|
|
1301
|
+
detail: `preview under the proposed rules: the base command ${gate.command} is inside the working tree, so this gate was not run`,
|
|
1302
|
+
};
|
|
1303
|
+
}
|
|
1304
|
+
// THE SAME FOR A PATH IN args:, for the same reason (audit 2026-10-27, B1):
|
|
1305
|
+
// an interpreter command takes the program as an argument, and a script in
|
|
1306
|
+
// the tree imports from the head as surely as a command there does. Refused
|
|
1307
|
+
// outright, as the command is, rather than by the base-equality rule: that
|
|
1308
|
+
// rule still runs in runGate on every preview spawn, so this is the
|
|
1309
|
+
// stricter of the two. The root counts as inside, and so does a link whose
|
|
1310
|
+
// own entry is in the tree, wherever it points (its directory is checked).
|
|
1311
|
+
// The candidate set is the primary run's (argumentCandidates): the entry and
|
|
1312
|
+
// every loadable sibling of it, so a head-added tools/gate.js beside a base
|
|
1313
|
+
// tools/gate/ is refused here too.
|
|
1314
|
+
const exempt = commandIsGateProgram(gate);
|
|
1315
|
+
for (const arg of gate.args ?? []) {
|
|
1316
|
+
const candidates = argumentCandidates(arg, repoRoot, gate.product, exempt);
|
|
1317
|
+
if (candidates.some((named) => realPathInside(repoRoot, named) || realPathInside(repoRoot, path.dirname(named)))) {
|
|
1318
|
+
return {
|
|
1319
|
+
reason: 'gate-program-refused',
|
|
1320
|
+
detail: `preview under the proposed rules: the base args entry ${arg} names a path inside the working tree, so this gate was not run`,
|
|
1321
|
+
};
|
|
1322
|
+
}
|
|
1323
|
+
}
|
|
1324
|
+
return null;
|
|
1325
|
+
}
|
|
1139
1326
|
/**
|
|
1140
1327
|
* Whether git says the repository at `repoRoot` is shallow. Anything other
|
|
1141
1328
|
* than a clear "true" (no git, an old git that does not know the flag) is
|
|
@@ -1159,9 +1346,10 @@ function isShallowRepository(repoRoot) {
|
|
|
1159
1346
|
function runGateInner(gate, options, started, progress) {
|
|
1160
1347
|
// Every spawn of this gate gets the FULL limit, not a share of it: the
|
|
1161
1348
|
// version probe, the scan and, on a compared pull request, osv-scanner's
|
|
1162
|
-
// base run. Onto `progress` so every outcome from here on carries it.
|
|
1349
|
+
// base run. Onto `progress` so every outcome from here on carries it. In
|
|
1350
|
+
// the preview each spawn gets the smaller of this and what is left of the
|
|
1351
|
+
// preview's budget (spawnLimits), and the outcome says which it was.
|
|
1163
1352
|
const timeLimit = resolveTimeLimit(gate, options.timeoutMs);
|
|
1164
|
-
const timeoutMs = timeLimit.ms;
|
|
1165
1353
|
Object.assign(progress, { timeLimit });
|
|
1166
1354
|
const ownOption = gateOwnTimeoutNote(gate, timeLimit, options.trustBase);
|
|
1167
1355
|
if (ownOption !== null) {
|
|
@@ -1181,6 +1369,24 @@ function runGateInner(gate, options, started, progress) {
|
|
|
1181
1369
|
Object.assign(progress, { nodeModulesSkipped: skipped });
|
|
1182
1370
|
}
|
|
1183
1371
|
const base = progress;
|
|
1372
|
+
// THE PREVIEW'S OWN REFUSALS, before resolution and before any spawn, the
|
|
1373
|
+
// version probe included. The primary run needs neither.
|
|
1374
|
+
if (options.preview !== undefined) {
|
|
1375
|
+
const refused = previewRefusal(gate, options.repoRoot);
|
|
1376
|
+
if (refused !== null) {
|
|
1377
|
+
return {
|
|
1378
|
+
...base,
|
|
1379
|
+
// Enforced under a trust base, like every refusal there; the preview
|
|
1380
|
+
// never reaches the exit code either way.
|
|
1381
|
+
enforce: options.trustBase !== undefined ? true : gate.enforce,
|
|
1382
|
+
durationMs: Date.now() - started,
|
|
1383
|
+
couldNotRun: refused,
|
|
1384
|
+
findings: [normalizeFailedGate(gate.role, gate.product, refused.detail)],
|
|
1385
|
+
run: EMPTY_RUN,
|
|
1386
|
+
diagnostics: [],
|
|
1387
|
+
};
|
|
1388
|
+
}
|
|
1389
|
+
}
|
|
1184
1390
|
let binary;
|
|
1185
1391
|
try {
|
|
1186
1392
|
binary = resolveGateBinary(gate, options.repoRoot, options.pathValue, { skipNodeModules });
|
|
@@ -1302,8 +1508,11 @@ function runGateInner(gate, options, started, progress) {
|
|
|
1302
1508
|
diagnostics: [],
|
|
1303
1509
|
};
|
|
1304
1510
|
}
|
|
1305
|
-
const probed = probeVersion(binary, gate.product, options.repoRoot,
|
|
1511
|
+
const probed = probeVersion(binary, gate.product, options.repoRoot, timeLimit, options.preview);
|
|
1306
1512
|
if (probed.kind === 'timed-out') {
|
|
1513
|
+
// The limit the probe ran under, which in the preview can be what was
|
|
1514
|
+
// left of the budget; onto `progress` so the outcome says so.
|
|
1515
|
+
Object.assign(progress, { timeLimit: probed.limit });
|
|
1307
1516
|
// Stopped here, before the version floor and before decideTrustBase: a
|
|
1308
1517
|
// timed-out probe is not an unreadable version (which on a pull request
|
|
1309
1518
|
// would read as trust-base-unverified, a packaging problem that does not
|
|
@@ -1312,8 +1521,8 @@ function runGateInner(gate, options, started, progress) {
|
|
|
1312
1521
|
// gate could not be placed inside the boundary. Enforced under the
|
|
1313
1522
|
// Action's expected-version signal too, like version-unverified: the run
|
|
1314
1523
|
// cannot show this is the pinned build.
|
|
1315
|
-
const detail = timedOutDetail(gate, 'version-probe',
|
|
1316
|
-
const timedOut = timedOutRecord('version-probe',
|
|
1524
|
+
const detail = timedOutDetail(gate, 'version-probe', probed.limit, probed.elapsedMs, options.trustBase);
|
|
1525
|
+
const timedOut = timedOutRecord('version-probe', probed.limit, probed.elapsedMs, probed.signal);
|
|
1317
1526
|
return {
|
|
1318
1527
|
...base,
|
|
1319
1528
|
binary,
|
|
@@ -1373,7 +1582,7 @@ function runGateInner(gate, options, started, progress) {
|
|
|
1373
1582
|
// decision reads the version. That ordering is the whole capability gate:
|
|
1374
1583
|
// a gate IN the table whose version is below its minimum, or could not be
|
|
1375
1584
|
// read, is refused rather than run outside the boundary.
|
|
1376
|
-
const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version);
|
|
1585
|
+
const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version, options.preview !== undefined);
|
|
1377
1586
|
if (trustBase !== undefined && trustBase.refused !== null) {
|
|
1378
1587
|
return {
|
|
1379
1588
|
...base,
|
|
@@ -1499,7 +1708,7 @@ function spawnAndRead(ctx) {
|
|
|
1499
1708
|
}
|
|
1500
1709
|
const baseArgv = (copies) => [
|
|
1501
1710
|
...binary.argvPrefix,
|
|
1502
|
-
...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: [...copies] }),
|
|
1711
|
+
...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: [...copies] }, undefined, undefined, options.preview !== undefined),
|
|
1503
1712
|
];
|
|
1504
1713
|
const checked = removed === null
|
|
1505
1714
|
? { kind: 'unverified', detail: `the base tree at ${decidedRef} could not be listed` }
|
|
@@ -1516,12 +1725,15 @@ function spawnAndRead(ctx) {
|
|
|
1516
1725
|
baseArgv,
|
|
1517
1726
|
budgetMs: input.budgetMs,
|
|
1518
1727
|
spawn: (argv, cwd, budget) => {
|
|
1519
|
-
const
|
|
1520
|
-
|
|
1521
|
-
|
|
1522
|
-
|
|
1523
|
-
|
|
1524
|
-
|
|
1728
|
+
const limits = spawnLimits({ ...timeLimit, ms: budget }, options.preview, undefined);
|
|
1729
|
+
const baseChild = limits.start
|
|
1730
|
+
? spawnSync(binary.command, [...argv], {
|
|
1731
|
+
cwd,
|
|
1732
|
+
encoding: 'utf8',
|
|
1733
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
1734
|
+
...limits.options,
|
|
1735
|
+
})
|
|
1736
|
+
: notStartedResult();
|
|
1525
1737
|
return {
|
|
1526
1738
|
status: baseChild.status,
|
|
1527
1739
|
stderr: stripAnsi(baseChild.stderr ?? ''),
|
|
@@ -1763,24 +1975,33 @@ function spawnAndRead(ctx) {
|
|
|
1763
1975
|
// intentChangeChannel is pure, and runGateInner already returned on the one
|
|
1764
1976
|
// outcome that does not spawn.
|
|
1765
1977
|
const channel = intentChangeChannel(gate, options.intent, version);
|
|
1978
|
+
// In the preview, dep-guard and vault-guard are not handed --trust-base
|
|
1979
|
+
// (decideTrustBase), and dep-guard still measures the change against the
|
|
1980
|
+
// base ref: --base comes from the run's trust base, which stays set.
|
|
1981
|
+
const changeBase = options.preview !== undefined && trustBase?.withheld === PREVIEW_WITHHELD ? options.trustBase : undefined;
|
|
1766
1982
|
const argv = [
|
|
1767
1983
|
...binary.argvPrefix,
|
|
1768
|
-
...gateArgs(gate, options.staged, options.intent, decidedRef, external, channel.kind === 'base' ? channel.ref : undefined),
|
|
1984
|
+
...gateArgs(gate, options.staged, options.intent, decidedRef, external, channel.kind === 'base' ? channel.ref : undefined, changeBase, options.preview !== undefined),
|
|
1769
1985
|
];
|
|
1986
|
+
// A history gate reads git history, and replace refs or grafts can cut
|
|
1987
|
+
// that history without making the repository shallow. Ignoring replace
|
|
1988
|
+
// objects makes it read the real commits. Other gates keep the inherited
|
|
1989
|
+
// environment untouched, outside the preview.
|
|
1990
|
+
const scanLimits = spawnLimits(timeLimit, options.preview, profile.readsHistory ? { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' } : undefined);
|
|
1991
|
+
if (scanLimits.limit !== timeLimit) {
|
|
1992
|
+
Object.assign(progress, { timeLimit: scanLimits.limit });
|
|
1993
|
+
}
|
|
1770
1994
|
// Taken just before the call, so a timed-out message's elapsed time is the
|
|
1771
1995
|
// scan's own and not resolution plus the version probe.
|
|
1772
1996
|
const spawnStarted = Date.now();
|
|
1773
|
-
const child =
|
|
1774
|
-
|
|
1775
|
-
|
|
1776
|
-
|
|
1777
|
-
|
|
1778
|
-
|
|
1779
|
-
|
|
1780
|
-
|
|
1781
|
-
// inherited environment untouched.
|
|
1782
|
-
...(profile.readsHistory ? { env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' } } : {}),
|
|
1783
|
-
});
|
|
1997
|
+
const child = scanLimits.start
|
|
1998
|
+
? spawnSync(binary.command, argv, {
|
|
1999
|
+
cwd: spawnCwd,
|
|
2000
|
+
encoding: 'utf8',
|
|
2001
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
2002
|
+
...scanLimits.options,
|
|
2003
|
+
})
|
|
2004
|
+
: notStartedResult();
|
|
1784
2005
|
const withRun = {
|
|
1785
2006
|
...base,
|
|
1786
2007
|
productVersion: version,
|
|
@@ -1822,8 +2043,8 @@ function spawnAndRead(ctx) {
|
|
|
1822
2043
|
if (failure !== null) {
|
|
1823
2044
|
if (failure.reason === 'timed-out') {
|
|
1824
2045
|
const elapsedMs = Date.now() - spawnStarted;
|
|
1825
|
-
const detail = timedOutDetail(gate, 'scan',
|
|
1826
|
-
const timedOut = timedOutRecord('scan',
|
|
2046
|
+
const detail = timedOutDetail(gate, 'scan', scanLimits.limit, elapsedMs, options.trustBase);
|
|
2047
|
+
const timedOut = timedOutRecord('scan', scanLimits.limit, elapsedMs, failure.signal);
|
|
1827
2048
|
return {
|
|
1828
2049
|
...withRun,
|
|
1829
2050
|
exitCode: null,
|
|
@@ -2071,15 +2292,18 @@ function spawnAndRead(ctx) {
|
|
|
2071
2292
|
headArgv: argv,
|
|
2072
2293
|
baseArgv: (copies) => [
|
|
2073
2294
|
...binary.argvPrefix,
|
|
2074
|
-
...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: copies }),
|
|
2295
|
+
...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: copies }, undefined, undefined, options.preview !== undefined),
|
|
2075
2296
|
],
|
|
2076
2297
|
spawn: (baseArgv, cwd) => {
|
|
2077
|
-
const
|
|
2078
|
-
|
|
2079
|
-
|
|
2080
|
-
|
|
2081
|
-
|
|
2082
|
-
|
|
2298
|
+
const limits = spawnLimits(timeLimit, options.preview, undefined);
|
|
2299
|
+
const baseChild = limits.start
|
|
2300
|
+
? spawnSync(binary.command, [...baseArgv], {
|
|
2301
|
+
cwd,
|
|
2302
|
+
encoding: 'utf8',
|
|
2303
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
2304
|
+
...limits.options,
|
|
2305
|
+
})
|
|
2306
|
+
: notStartedResult();
|
|
2083
2307
|
return { status: baseChild.status, stdout: baseChild.stdout ?? '', error: baseChild.error };
|
|
2084
2308
|
},
|
|
2085
2309
|
rootSpellings,
|
|
@@ -2169,3 +2393,18 @@ function spawnAndRead(ctx) {
|
|
|
2169
2393
|
};
|
|
2170
2394
|
}
|
|
2171
2395
|
}
|
|
2396
|
+
/**
|
|
2397
|
+
* cleanOutputLine, then every remaining character outside printable ASCII
|
|
2398
|
+
* escaped as \uXXXX (escapeNonAscii). For every preview line: there a gate
|
|
2399
|
+
* reads the head's own control files, so a rule id or a message can be
|
|
2400
|
+
* head-chosen text, a right-to-left override included (audit 2026-10-27,
|
|
2401
|
+
* N3). cleanOutputLine alone breaks a workflow command and keeps the
|
|
2402
|
+
* override. The primary run is NOT safe by the same argument: its rule ids
|
|
2403
|
+
* come from base-approved config, but its file paths are the head's own
|
|
2404
|
+
* names. So the primary text report escapes finding paths (subjectLabel,
|
|
2405
|
+
* src/output-text.ts), and only those; a primary gate message or stderr
|
|
2406
|
+
* excerpt that quotes a path keeps its characters, a known limit.
|
|
2407
|
+
*/
|
|
2408
|
+
export function cleanPreviewLine(raw) {
|
|
2409
|
+
return escapeNonAscii(cleanOutputLine(raw));
|
|
2410
|
+
}
|
package/dist/output-sarif.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import type
|
|
2
|
-
import type
|
|
1
|
+
import { type GateOutcome } from './gate-runner.js';
|
|
2
|
+
import { type RunResult } from './run.js';
|
|
3
3
|
export declare const UMBRELLA_DRIVER_NAME = "conductor";
|
|
4
4
|
/** The partialFingerprints key for a product's own fingerprint. */
|
|
5
5
|
export declare function fingerprintKey(scope: string): string;
|
package/dist/output-sarif.js
CHANGED
|
@@ -118,10 +118,13 @@
|
|
|
118
118
|
// normalize.ts, which is where the omission would stop mattering if the
|
|
119
119
|
// field were ever carried.
|
|
120
120
|
import { gateExitBlocks } from './exit-codes.js';
|
|
121
|
+
import { cleanPreviewLine } from './gate-runner.js';
|
|
121
122
|
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
122
123
|
import { INTENT_WARNING } from './normalize.js';
|
|
123
|
-
import { skewFound, skewPlace } from './output-text.js';
|
|
124
|
+
import { gateOutcomeWords, skewFound, skewPlace } from './output-text.js';
|
|
124
125
|
import { POLICY_FILE_NAME } from './policy.js';
|
|
126
|
+
import { policyChangeLine } from './policy-diff.js';
|
|
127
|
+
import { guardPreview } from './run.js';
|
|
125
128
|
const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
|
|
126
129
|
export const UMBRELLA_DRIVER_NAME = 'conductor';
|
|
127
130
|
/**
|
|
@@ -363,6 +366,16 @@ function notificationDeclarations(notifications) {
|
|
|
363
366
|
const ids = [...new Set(notifications.map((notification) => notification.id))].sort();
|
|
364
367
|
return ids.map((id) => ({ id, name: id.slice(id.indexOf('/') + 1) }));
|
|
365
368
|
}
|
|
369
|
+
/**
|
|
370
|
+
* The trust base as the log carries it: the per-key changes become their
|
|
371
|
+
* rendered lines (escaped and truncated), never the raw head values.
|
|
372
|
+
*/
|
|
373
|
+
function sarifTrustBase(trustBase) {
|
|
374
|
+
const { policyChanges, ...rest } = trustBase;
|
|
375
|
+
return policyChanges === undefined
|
|
376
|
+
? rest
|
|
377
|
+
: { ...rest, policyChanges: policyChanges.map(policyChangeLine) };
|
|
378
|
+
}
|
|
366
379
|
function makeRun(name, version, findings,
|
|
367
380
|
/** The artifact a result with no location of its own is filed against. */
|
|
368
381
|
fallbackUri, properties, invocation) {
|
|
@@ -695,6 +708,31 @@ function proposalNotifications(result) {
|
|
|
695
708
|
},
|
|
696
709
|
}));
|
|
697
710
|
}
|
|
711
|
+
/**
|
|
712
|
+
* The preview under the proposed rules, one note per preview gate.
|
|
713
|
+
*
|
|
714
|
+
* NOTES ONLY, and never a result, a rule, a fingerprint or a run: the
|
|
715
|
+
* preview decides nothing, so nothing of it may reach the alert list or the
|
|
716
|
+
* code scanning tab's identity for a finding. The caller appends these only
|
|
717
|
+
* to a notification list that is non-empty without them, so a preview never
|
|
718
|
+
* creates the umbrella's run, and executionSuccessful still reads only the
|
|
719
|
+
* primary gates. A throw here yields no preview notification at all.
|
|
720
|
+
*/
|
|
721
|
+
function previewNotifications(result) {
|
|
722
|
+
const preview = result.preview;
|
|
723
|
+
if (preview === undefined) {
|
|
724
|
+
return [];
|
|
725
|
+
}
|
|
726
|
+
return guardPreview(() => preview.gates.map((gate) => {
|
|
727
|
+
const outcome = cleanPreviewLine(gateOutcomeWords(gate));
|
|
728
|
+
return {
|
|
729
|
+
id: 'conductor/preview-under-proposed-rules',
|
|
730
|
+
message: 'Preview under the proposed rules, which does not affect the verdict: ' +
|
|
731
|
+
`${gate.role} (${gate.product}) ${outcome}, ${gate.findings.length} finding(s).`,
|
|
732
|
+
details: { role: gate.role, product: gate.product, outcome, findings: gate.findings.length },
|
|
733
|
+
};
|
|
734
|
+
}), () => []);
|
|
735
|
+
}
|
|
698
736
|
/**
|
|
699
737
|
* The trust base the umbrella refused, when it refused one.
|
|
700
738
|
*
|
|
@@ -1043,6 +1081,11 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
1043
1081
|
...intentWarningNotifications(result),
|
|
1044
1082
|
...gateOwnOptionNotifications(result),
|
|
1045
1083
|
];
|
|
1084
|
+
// Only onto a list that is already non-empty: the preview never earns the
|
|
1085
|
+
// umbrella's run on its own.
|
|
1086
|
+
if (notifications.length > 0) {
|
|
1087
|
+
notifications.push(...previewNotifications(result));
|
|
1088
|
+
}
|
|
1046
1089
|
// Notifications earn the run on their own. Before this, the umbrella run
|
|
1047
1090
|
// existed only when it had findings and a deferred gate was one; without
|
|
1048
1091
|
// this clause a commit-stage log would say nothing whatever about the gate
|
|
@@ -1063,7 +1106,9 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
1063
1106
|
// fact about the whole run: every gate that could take the flag was
|
|
1064
1107
|
// handed this same ref. A consumer reading only the log can then tell
|
|
1065
1108
|
// a pull-request run from an ordinary one without parsing sentences.
|
|
1066
|
-
result.trustBase === null
|
|
1109
|
+
result.trustBase === null
|
|
1110
|
+
? undefined
|
|
1111
|
+
: { trustBase: sarifTrustBase(result.trustBase) }, {
|
|
1067
1112
|
// A claim about whether the analysis completed, taken from the
|
|
1068
1113
|
// gates rather than from the exit code: an unenforced gate that
|
|
1069
1114
|
// could not run leaves the run at exit 0, and nothing was checked
|