@vaultcompass/conductor 0.13.2 → 0.14.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.
@@ -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';
@@ -158,6 +158,9 @@ function limitSourcePhrase(gate, source, trustBase) {
158
158
  ? `gates.${gate.role}.timeout-seconds`
159
159
  : `gates.${gate.role}.timeout-seconds on ${trustBase}`;
160
160
  }
161
+ if (source === 'preview-budget') {
162
+ return 'what was left of the 300 s preview budget';
163
+ }
161
164
  return source === 'default' ? 'the default for this gate' : 'set by the caller';
162
165
  }
163
166
  /**
@@ -178,7 +181,17 @@ function timedOutDetail(gate, step, limit, elapsedMs, trustBase) {
178
181
  const elapsedSeconds = Math.round(elapsedMs / 1000);
179
182
  const where = limitSourcePhrase(gate, limit.source, trustBase);
180
183
  const own = gateOwnTimeoutNote(gate, limit, trustBase);
181
- const remedies = profileFor(gate.product).timeoutRemedies(gate.role);
184
+ // A preview stopped by its own budget has no limit to raise: the budget is
185
+ // fixed, and the gate's own limit was not what stopped it.
186
+ const remedies = limit.source === 'preview-budget'
187
+ ? 'The preview under the proposed rules has 300 s in all, whatever each gate\'s own limit.'
188
+ : profileFor(gate.product).timeoutRemedies(gate.role);
189
+ // A preview spawn with no budget left was never started (spawnLimits):
190
+ // there is no elapsed time or limit to report.
191
+ if (limit.source === 'preview-budget' && limit.ms === 0) {
192
+ const what = step === 'version-probe' ? `the version probe of ${gate.product}` : gate.product;
193
+ return `${what} was not started: the preview budget was spent, so nothing was checked by it. ${remedies}`;
194
+ }
182
195
  if (step === 'version-probe') {
183
196
  return (`the version probe of ${gate.product} was stopped at ${limitSeconds} s (${where}), so the gate ` +
184
197
  'was not run and nothing was checked by it.');
@@ -436,6 +449,12 @@ function intentChangeChannel(gate, intent, version) {
436
449
  }
437
450
  return { kind: 'paths' };
438
451
  }
452
+ /**
453
+ * Why dep-guard and vault-guard are not handed `--trust-base` in the preview
454
+ * under the proposed rules: the preview shows what the head's rules would do,
455
+ * and their own control files are part of those rules.
456
+ */
457
+ export const PREVIEW_WITHHELD = 'preview under the proposed rules: this gate read its own control files from the head';
439
458
  /**
440
459
  * Whether this gate can be handed `--trust-base`, and why not when it cannot.
441
460
  *
@@ -450,7 +469,14 @@ function intentChangeChannel(gate, intent, version) {
450
469
  * was working a moment ago would report could-not-run. So the flag goes only
451
470
  * where `--project` is the repository itself.
452
471
  */
453
- export function decideTrustBase(gate, intent, trustBase, productVersion) {
472
+ export function decideTrustBase(gate, intent, trustBase, productVersion,
473
+ /**
474
+ * The preview under the proposed rules. dep-guard and vault-guard then read
475
+ * their own control files from the head, so the flag is withheld from them;
476
+ * the trust base itself stays set on the run, and every other product is
477
+ * decided exactly as without it.
478
+ */
479
+ preview = false) {
454
480
  if (trustBase === undefined) {
455
481
  return undefined;
456
482
  }
@@ -493,6 +519,15 @@ export function decideTrustBase(gate, intent, trustBase, productVersion) {
493
519
  `was checked by it. Fix: install ${gate.product} ${minimum} or newer, or remove an ` +
494
520
  'explicit older version pin.');
495
521
  }
522
+ // AFTER both version refusals, so a gate refused in the primary run is
523
+ // refused in the preview too. Only the --trust-base flag is withheld: the
524
+ // run keeps its trust base, and with it the node_modules skip, the program
525
+ // refusal and the forced enforce, and dep-guard keeps --base (gateArgs'
526
+ // changeBase). gitleaks and osv-scanner never reach this: the umbrella
527
+ // itself is their pull-request mode, and it stays the base's.
528
+ if (preview && (gate.product === 'dep-guard' || gate.product === 'vault-guard')) {
529
+ return withheld(PREVIEW_WITHHELD);
530
+ }
496
531
  // AFTER the version checks, so an imported contract cannot let an older
497
532
  // gate run: this withholding is about where --project points, not about
498
533
  // what the gate understands, and the contract itself came from the base.
@@ -506,6 +541,47 @@ export function decideTrustBase(gate, intent, trustBase, productVersion) {
506
541
  }
507
542
  return { ref: trustBase, withheld: null, refused: null, proposals: [] };
508
543
  }
544
+ /** The smaller of a spawn's own limit and what is left of the preview budget, never negative. */
545
+ export function previewSpawnTimeout(limitMs, preview) {
546
+ return Math.max(0, Math.min(limitMs, preview.deadline - preview.clock()));
547
+ }
548
+ /**
549
+ * The spawn options of every preview spawn: the timeout above, SIGKILL, so a
550
+ * child that traps SIGTERM cannot outlive the budget, and the spawn's own
551
+ * environment with XDG_CACHE_HOME pointed at the preview's private cache, so
552
+ * nothing the head's rules fetched persists on a shared runner.
553
+ */
554
+ export function previewSpawnOptions(limitMs, preview, env) {
555
+ return {
556
+ timeout: previewSpawnTimeout(limitMs, preview),
557
+ killSignal: 'SIGKILL',
558
+ env: { ...env, XDG_CACHE_HOME: preview.cacheDir },
559
+ };
560
+ }
561
+ /**
562
+ * The options one spawn passes to spawnSync beside its own, and the limit it
563
+ * ran under. Outside the preview: the full limit and nothing else, exactly as
564
+ * before. In the preview: `previewSpawnOptions`, and the limit's source is
565
+ * `preview-budget` when the budget left was the smaller. `start` false means
566
+ * no budget is left, and the spawn must not be started: a spawnSync timeout
567
+ * of 0 is no timeout at all.
568
+ */
569
+ function spawnLimits(limit, preview, env) {
570
+ if (preview === undefined) {
571
+ return { start: true, limit, options: { timeout: limit.ms, ...(env === undefined ? {} : { env }) } };
572
+ }
573
+ const options = previewSpawnOptions(limit.ms, preview, env ?? process.env);
574
+ return {
575
+ start: options.timeout > 0,
576
+ limit: options.timeout < limit.ms ? { ms: options.timeout, source: 'preview-budget' } : limit,
577
+ options,
578
+ };
579
+ }
580
+ /** A spawnSync-shaped result for a preview spawn that was never started: no budget left. */
581
+ function notStartedResult() {
582
+ const error = Object.assign(new Error('spawnSync ETIMEDOUT: the preview budget was spent'), { code: 'ETIMEDOUT' });
583
+ return { pid: 0, output: [], stdout: '', stderr: '', status: null, signal: null, error };
584
+ }
509
585
  /**
510
586
  * A gate that never got as far as being spawned.
511
587
  *
@@ -655,7 +731,22 @@ external = {},
655
731
  * For the intent gate on a prepared run: hand it this base with its own
656
732
  * `--base` in place of `--paths`. Decided by `intentChangeChannel`.
657
733
  */
658
- intentBase) {
734
+ intentBase,
735
+ /**
736
+ * dep-guard's `--base` when `trustBase` is withheld from it in the preview
737
+ * under the proposed rules: the change is still measured against the base
738
+ * ref, only the rules are the head's. Ignored when `trustBase` is set, and
739
+ * by every other product.
740
+ */
741
+ changeBase,
742
+ /**
743
+ * True for a spawn of the preview under the proposed rules. osv-scanner
744
+ * then gets `--no-call-analysis=all` appended after the base's own options,
745
+ * whatever they say: call analysis builds the project it scans, which in
746
+ * the preview is the head's code, and osv-scanner applies its disables
747
+ * after its enables, so the appended flag wins.
748
+ */
749
+ preview = false) {
659
750
  const passthrough = renderOptionFlags(gate.options);
660
751
  const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
661
752
  const config = external.configPath === undefined ? [] : ['--config', external.configPath];
@@ -680,7 +771,8 @@ intentBase) {
680
771
  // name incompatible comparisons -- the git index versus an arbitrary
681
772
  // ref. A staged run already has its own comparison and --trust-base
682
773
  // is unaffected, since it answers a different question.
683
- const base = trustBase !== undefined && !staged ? ['--base', trustBase] : [];
774
+ const baseRef = trustBase ?? changeBase;
775
+ const base = baseRef !== undefined && !staged ? ['--base', baseRef] : [];
684
776
  return [...(staged ? ['--staged'] : []), '--format', 'json', ...trust, ...base, ...passthrough];
685
777
  }
686
778
  case 'vault-guard':
@@ -832,26 +924,30 @@ intentBase) {
832
924
  ...(noResolve ? ['--no-resolve'] : []),
833
925
  ...callAnalysis,
834
926
  ...renderOptionFlags(options),
927
+ ...(preview ? ['--no-call-analysis=all'] : []),
835
928
  ];
836
929
  }
837
930
  }
838
931
  }
839
- function probeVersion(binary, product, repoRoot, timeoutMs) {
932
+ function probeVersion(binary, product, repoRoot, timeLimit, preview) {
840
933
  const spec = profileFor(product).versionProbe;
841
934
  if (binary.versionProbe === null || spec === null) {
842
935
  return { kind: 'unreadable' };
843
936
  }
937
+ const limits = spawnLimits(timeLimit, preview, undefined);
844
938
  const probeStarted = Date.now();
845
- const probe = spawnSync(binary.versionProbe.command, binary.versionProbe.argv, {
846
- cwd: repoRoot,
847
- encoding: 'utf8',
848
- timeout: timeoutMs,
849
- });
939
+ const probe = limits.start
940
+ ? spawnSync(binary.versionProbe.command, binary.versionProbe.argv, {
941
+ cwd: repoRoot,
942
+ encoding: 'utf8',
943
+ ...limits.options,
944
+ })
945
+ : notStartedResult();
850
946
  // FIRST, before the status: a probe that handled SIGTERM can exit 0 with a
851
947
  // version on stdout, and it was still stopped at the limit.
852
948
  const failure = spawnFailure(probe);
853
949
  if (failure !== null && failure.reason === 'timed-out') {
854
- return { kind: 'timed-out', elapsedMs: Date.now() - probeStarted, signal: failure.signal };
950
+ return { kind: 'timed-out', elapsedMs: Date.now() - probeStarted, signal: failure.signal, limit: limits.limit };
855
951
  }
856
952
  if (probe.status !== 0 || typeof probe.stdout !== 'string') {
857
953
  return { kind: 'unreadable' };
@@ -943,7 +1039,7 @@ export function expectedVersionBeforePreparation(gate, binary, options) {
943
1039
  const skipped = options.trustBase === undefined ? null : nodeModulesCandidate(gate, options.repoRoot);
944
1040
  const carried = { timeLimit, ...(skipped === null ? {} : { nodeModulesSkipped: skipped }) };
945
1041
  const started = Date.now();
946
- const probed = probeVersion(binary, gate.product, options.repoRoot, timeLimit.ms);
1042
+ const probed = probeVersion(binary, gate.product, options.repoRoot, timeLimit);
947
1043
  if (probed.kind === 'timed-out') {
948
1044
  // The same outcome runGate builds for a stopped probe under the
949
1045
  // expectation: enforced, because the run cannot show this is the pinned
@@ -1136,6 +1232,63 @@ export function runGate(gate, options) {
1136
1232
  };
1137
1233
  }
1138
1234
  }
1235
+ function callAnalysisOff(options) {
1236
+ const asList = (value) => (Array.isArray(value) ? value : [value]);
1237
+ for (const key of Object.keys(options)) {
1238
+ if (!key.includes('call-analysis'))
1239
+ continue;
1240
+ const value = options[key];
1241
+ if (key === 'no-call-analysis' && (value === true || asList(value).some((item) => item === 'all')))
1242
+ continue;
1243
+ return false;
1244
+ }
1245
+ return true;
1246
+ }
1247
+ /**
1248
+ * The three refusals only the preview under the proposed rules makes.
1249
+ *
1250
+ * An option value starting with "-" would render as a flag of its own
1251
+ * (renderOptionFlags), so a value the base never ran with could add an output
1252
+ * path or a second --log-opts. A base `command:` inside the working tree is
1253
+ * checked by refuseHeadControlledProgram for its own blob only, while what it
1254
+ * imports comes from the head, and the preview can reach a role the base has
1255
+ * switched off, whose command nobody has exercised (spec 5.2, finding 7).
1256
+ * osv-scanner call analysis builds the project it scans, here the head's
1257
+ * code, so only the all-off form of it is allowed (callAnalysisOff), and
1258
+ * gateArgs forces it off on every preview spawn besides.
1259
+ */
1260
+ function previewRefusal(gate, repoRoot) {
1261
+ for (const name of Object.keys(gate.options).sort()) {
1262
+ const value = gate.options[name];
1263
+ const values = Array.isArray(value) ? value : [value];
1264
+ if (values.some((item) => typeof item === 'string' && item.startsWith('-'))) {
1265
+ return {
1266
+ reason: 'preparation-failed',
1267
+ detail: `preview under the proposed rules: option ${name} has a value starting with "-", so this gate was not run`,
1268
+ };
1269
+ }
1270
+ }
1271
+ // osv-scanner's call analysis builds the project it scans, and in the
1272
+ // preview that is the head's code (a Rust build.rs, for one).
1273
+ // Every option key is rendered as a flag, so the check is by key match:
1274
+ // any key containing "call-analysis" is refused unless it is the one
1275
+ // unambiguous all-off form, `no-call-analysis: true` or `all`. An absent
1276
+ // key is fine. Belt and braces: gateArgs appends --no-call-analysis=all
1277
+ // to every osv-scanner preview spawn as well.
1278
+ if (gate.product === 'osv-scanner' && !callAnalysisOff(gate.options)) {
1279
+ return {
1280
+ reason: 'preparation-failed',
1281
+ detail: "the preview does not run call analysis, because it would build the head's code",
1282
+ };
1283
+ }
1284
+ if (gate.command !== undefined && realPathInside(repoRoot, gate.command)) {
1285
+ return {
1286
+ reason: 'gate-program-refused',
1287
+ detail: `preview under the proposed rules: the base command ${gate.command} is inside the working tree, so this gate was not run`,
1288
+ };
1289
+ }
1290
+ return null;
1291
+ }
1139
1292
  /**
1140
1293
  * Whether git says the repository at `repoRoot` is shallow. Anything other
1141
1294
  * than a clear "true" (no git, an old git that does not know the flag) is
@@ -1159,9 +1312,10 @@ function isShallowRepository(repoRoot) {
1159
1312
  function runGateInner(gate, options, started, progress) {
1160
1313
  // Every spawn of this gate gets the FULL limit, not a share of it: the
1161
1314
  // 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.
1315
+ // base run. Onto `progress` so every outcome from here on carries it. In
1316
+ // the preview each spawn gets the smaller of this and what is left of the
1317
+ // preview's budget (spawnLimits), and the outcome says which it was.
1163
1318
  const timeLimit = resolveTimeLimit(gate, options.timeoutMs);
1164
- const timeoutMs = timeLimit.ms;
1165
1319
  Object.assign(progress, { timeLimit });
1166
1320
  const ownOption = gateOwnTimeoutNote(gate, timeLimit, options.trustBase);
1167
1321
  if (ownOption !== null) {
@@ -1181,6 +1335,24 @@ function runGateInner(gate, options, started, progress) {
1181
1335
  Object.assign(progress, { nodeModulesSkipped: skipped });
1182
1336
  }
1183
1337
  const base = progress;
1338
+ // THE PREVIEW'S OWN REFUSALS, before resolution and before any spawn, the
1339
+ // version probe included. The primary run needs neither.
1340
+ if (options.preview !== undefined) {
1341
+ const refused = previewRefusal(gate, options.repoRoot);
1342
+ if (refused !== null) {
1343
+ return {
1344
+ ...base,
1345
+ // Enforced under a trust base, like every refusal there; the preview
1346
+ // never reaches the exit code either way.
1347
+ enforce: options.trustBase !== undefined ? true : gate.enforce,
1348
+ durationMs: Date.now() - started,
1349
+ couldNotRun: refused,
1350
+ findings: [normalizeFailedGate(gate.role, gate.product, refused.detail)],
1351
+ run: EMPTY_RUN,
1352
+ diagnostics: [],
1353
+ };
1354
+ }
1355
+ }
1184
1356
  let binary;
1185
1357
  try {
1186
1358
  binary = resolveGateBinary(gate, options.repoRoot, options.pathValue, { skipNodeModules });
@@ -1302,8 +1474,11 @@ function runGateInner(gate, options, started, progress) {
1302
1474
  diagnostics: [],
1303
1475
  };
1304
1476
  }
1305
- const probed = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
1477
+ const probed = probeVersion(binary, gate.product, options.repoRoot, timeLimit, options.preview);
1306
1478
  if (probed.kind === 'timed-out') {
1479
+ // The limit the probe ran under, which in the preview can be what was
1480
+ // left of the budget; onto `progress` so the outcome says so.
1481
+ Object.assign(progress, { timeLimit: probed.limit });
1307
1482
  // Stopped here, before the version floor and before decideTrustBase: a
1308
1483
  // timed-out probe is not an unreadable version (which on a pull request
1309
1484
  // would read as trust-base-unverified, a packaging problem that does not
@@ -1312,8 +1487,8 @@ function runGateInner(gate, options, started, progress) {
1312
1487
  // gate could not be placed inside the boundary. Enforced under the
1313
1488
  // Action's expected-version signal too, like version-unverified: the run
1314
1489
  // cannot show this is the pinned build.
1315
- const detail = timedOutDetail(gate, 'version-probe', timeLimit, probed.elapsedMs, options.trustBase);
1316
- const timedOut = timedOutRecord('version-probe', timeLimit, probed.elapsedMs, probed.signal);
1490
+ const detail = timedOutDetail(gate, 'version-probe', probed.limit, probed.elapsedMs, options.trustBase);
1491
+ const timedOut = timedOutRecord('version-probe', probed.limit, probed.elapsedMs, probed.signal);
1317
1492
  return {
1318
1493
  ...base,
1319
1494
  binary,
@@ -1373,7 +1548,7 @@ function runGateInner(gate, options, started, progress) {
1373
1548
  // decision reads the version. That ordering is the whole capability gate:
1374
1549
  // a gate IN the table whose version is below its minimum, or could not be
1375
1550
  // read, is refused rather than run outside the boundary.
1376
- const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version);
1551
+ const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version, options.preview !== undefined);
1377
1552
  if (trustBase !== undefined && trustBase.refused !== null) {
1378
1553
  return {
1379
1554
  ...base,
@@ -1499,7 +1674,7 @@ function spawnAndRead(ctx) {
1499
1674
  }
1500
1675
  const baseArgv = (copies) => [
1501
1676
  ...binary.argvPrefix,
1502
- ...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: [...copies] }),
1677
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: [...copies] }, undefined, undefined, options.preview !== undefined),
1503
1678
  ];
1504
1679
  const checked = removed === null
1505
1680
  ? { kind: 'unverified', detail: `the base tree at ${decidedRef} could not be listed` }
@@ -1516,12 +1691,15 @@ function spawnAndRead(ctx) {
1516
1691
  baseArgv,
1517
1692
  budgetMs: input.budgetMs,
1518
1693
  spawn: (argv, cwd, budget) => {
1519
- const baseChild = spawnSync(binary.command, [...argv], {
1520
- cwd,
1521
- encoding: 'utf8',
1522
- timeout: budget,
1523
- maxBuffer: 64 * 1024 * 1024,
1524
- });
1694
+ const limits = spawnLimits({ ...timeLimit, ms: budget }, options.preview, undefined);
1695
+ const baseChild = limits.start
1696
+ ? spawnSync(binary.command, [...argv], {
1697
+ cwd,
1698
+ encoding: 'utf8',
1699
+ maxBuffer: 64 * 1024 * 1024,
1700
+ ...limits.options,
1701
+ })
1702
+ : notStartedResult();
1525
1703
  return {
1526
1704
  status: baseChild.status,
1527
1705
  stderr: stripAnsi(baseChild.stderr ?? ''),
@@ -1763,24 +1941,33 @@ function spawnAndRead(ctx) {
1763
1941
  // intentChangeChannel is pure, and runGateInner already returned on the one
1764
1942
  // outcome that does not spawn.
1765
1943
  const channel = intentChangeChannel(gate, options.intent, version);
1944
+ // In the preview, dep-guard and vault-guard are not handed --trust-base
1945
+ // (decideTrustBase), and dep-guard still measures the change against the
1946
+ // base ref: --base comes from the run's trust base, which stays set.
1947
+ const changeBase = options.preview !== undefined && trustBase?.withheld === PREVIEW_WITHHELD ? options.trustBase : undefined;
1766
1948
  const argv = [
1767
1949
  ...binary.argvPrefix,
1768
- ...gateArgs(gate, options.staged, options.intent, decidedRef, external, channel.kind === 'base' ? channel.ref : undefined),
1950
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, external, channel.kind === 'base' ? channel.ref : undefined, changeBase, options.preview !== undefined),
1769
1951
  ];
1952
+ // A history gate reads git history, and replace refs or grafts can cut
1953
+ // that history without making the repository shallow. Ignoring replace
1954
+ // objects makes it read the real commits. Other gates keep the inherited
1955
+ // environment untouched, outside the preview.
1956
+ const scanLimits = spawnLimits(timeLimit, options.preview, profile.readsHistory ? { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' } : undefined);
1957
+ if (scanLimits.limit !== timeLimit) {
1958
+ Object.assign(progress, { timeLimit: scanLimits.limit });
1959
+ }
1770
1960
  // Taken just before the call, so a timed-out message's elapsed time is the
1771
1961
  // scan's own and not resolution plus the version probe.
1772
1962
  const spawnStarted = Date.now();
1773
- const child = spawnSync(binary.command, argv, {
1774
- cwd: spawnCwd,
1775
- encoding: 'utf8',
1776
- timeout: timeoutMs,
1777
- maxBuffer: 64 * 1024 * 1024,
1778
- // A history gate reads git history, and replace refs or grafts can cut
1779
- // that history without making the repository shallow. Ignoring replace
1780
- // objects makes it read the real commits. Other gates keep the
1781
- // inherited environment untouched.
1782
- ...(profile.readsHistory ? { env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' } } : {}),
1783
- });
1963
+ const child = scanLimits.start
1964
+ ? spawnSync(binary.command, argv, {
1965
+ cwd: spawnCwd,
1966
+ encoding: 'utf8',
1967
+ maxBuffer: 64 * 1024 * 1024,
1968
+ ...scanLimits.options,
1969
+ })
1970
+ : notStartedResult();
1784
1971
  const withRun = {
1785
1972
  ...base,
1786
1973
  productVersion: version,
@@ -1822,8 +2009,8 @@ function spawnAndRead(ctx) {
1822
2009
  if (failure !== null) {
1823
2010
  if (failure.reason === 'timed-out') {
1824
2011
  const elapsedMs = Date.now() - spawnStarted;
1825
- const detail = timedOutDetail(gate, 'scan', timeLimit, elapsedMs, options.trustBase);
1826
- const timedOut = timedOutRecord('scan', timeLimit, elapsedMs, failure.signal);
2012
+ const detail = timedOutDetail(gate, 'scan', scanLimits.limit, elapsedMs, options.trustBase);
2013
+ const timedOut = timedOutRecord('scan', scanLimits.limit, elapsedMs, failure.signal);
1827
2014
  return {
1828
2015
  ...withRun,
1829
2016
  exitCode: null,
@@ -2071,15 +2258,18 @@ function spawnAndRead(ctx) {
2071
2258
  headArgv: argv,
2072
2259
  baseArgv: (copies) => [
2073
2260
  ...binary.argvPrefix,
2074
- ...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: copies }),
2261
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: copies }, undefined, undefined, options.preview !== undefined),
2075
2262
  ],
2076
2263
  spawn: (baseArgv, cwd) => {
2077
- const baseChild = spawnSync(binary.command, [...baseArgv], {
2078
- cwd,
2079
- encoding: 'utf8',
2080
- timeout: timeoutMs,
2081
- maxBuffer: 64 * 1024 * 1024,
2082
- });
2264
+ const limits = spawnLimits(timeLimit, options.preview, undefined);
2265
+ const baseChild = limits.start
2266
+ ? spawnSync(binary.command, [...baseArgv], {
2267
+ cwd,
2268
+ encoding: 'utf8',
2269
+ maxBuffer: 64 * 1024 * 1024,
2270
+ ...limits.options,
2271
+ })
2272
+ : notStartedResult();
2083
2273
  return { status: baseChild.status, stdout: baseChild.stdout ?? '', error: baseChild.error };
2084
2274
  },
2085
2275
  rootSpellings,
@@ -1,5 +1,5 @@
1
- import type { GateOutcome } from './gate-runner.js';
2
- import type { RunResult } from './run.js';
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;
@@ -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 { cleanOutputLine } 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 = cleanOutputLine(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 ? undefined : { trustBase: result.trustBase }, {
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
@@ -1,6 +1,6 @@
1
1
  import { type GateOutcome } from './gate-runner.js';
2
2
  import type { ReportedMatch } from './intent-prepare.js';
3
- import type { RunResult } from './run.js';
3
+ import { type RunResult } from './run.js';
4
4
  /**
5
5
  * How many entries a section prints before it rolls the rest up into one
6
6
  * line, unless --verbose. A full-history gitleaks scan or an osv-scanner run
@@ -56,6 +56,42 @@ export declare function proposalCount(result: RunResult): string;
56
56
  * not change.
57
57
  */
58
58
  export declare function jobLogSummary(result: RunResult): string;
59
+ /**
60
+ * The proposal lines for a job log: the count sentence, then one line per
61
+ * proposed control change. Empty outside pull-request mode, and empty when
62
+ * the trust base was refused or never given, because no rules were read and
63
+ * there is nothing proposed to count. Each line goes through
64
+ * cleanOutputLine, since a proposal carries text a gate printed.
65
+ */
66
+ export declare function proposalLogLines(result: RunResult): string[];
67
+ /**
68
+ * A gate's outcome in the job log's words: `ok`, `findings (N, M blocking)`
69
+ * with dep-guard's deadline clause when it said so, `could-not-run (reason)`
70
+ * or `missing (reason)`. Shared by the per-gate lines and the preview's.
71
+ */
72
+ export declare function gateOutcomeWords(gate: GateOutcome): string;
73
+ /**
74
+ * The header the preview block starts with, in the report and the comment.
75
+ * scripts/lib/pr-comment.mjs spells it too, to cut the preview first from a
76
+ * comment over the limit, and action.yml stops its summary scan at it.
77
+ */
78
+ export declare const PREVIEW_HEADER = "Preview under the proposed rules (does not affect the verdict)";
79
+ /**
80
+ * The preview under the proposed rules, as report lines: empty without a
81
+ * preview, otherwise a blank line, the header, the fixed-shape count line,
82
+ * one gate section per preview gate, then the deferred, over-budget, threw
83
+ * and advisory lines. Printed only AFTER the verdict line, and read by
84
+ * nothing that decides one. Every line goes through cleanOutputLine: a
85
+ * preview runs under head-proposed keys, so its gate text is not trusted to
86
+ * be free of a workflow command.
87
+ */
88
+ export declare function previewLines(result: RunResult, verbose: boolean): string[];
89
+ /**
90
+ * The preview's job log lines: one per preview gate in the per-gate lines'
91
+ * outcome words, one per over-budget role, and one for a deferred intent
92
+ * gate. Empty without a preview. Each line goes through cleanOutputLine.
93
+ */
94
+ export declare function previewLogLines(result: RunResult): string[];
59
95
  /**
60
96
  * One plain line per gate, for the job log: which gate, which version, what
61
97
  * happened, and the exit code. Written to stderr by cli.ts on EVERY run, so