@vaultcompass/conductor 0.13.0 → 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.
package/dist/run.js CHANGED
@@ -1,13 +1,19 @@
1
1
  // One run across every enabled gate.
2
+ import { mkdtempSync, rmSync } from 'node:fs';
3
+ import os from 'node:os';
4
+ import path from 'node:path';
2
5
  import { compareFindings } from './envelope.js';
3
6
  import { EXIT_COULD_NOT_RUN, composeExitCode, gateExitBlocks } from './exit-codes.js';
4
- import { gateProgramRefused, preparationFailed, preparationTimedOut, refuseHeadControlledBinary, resolveTimeLimit, runGate, } from './gate-runner.js';
7
+ import { cleanOutputLine, expectedVersionBeforePreparation, gateProgramRefused, preparationFailed, preparationTimedOut, refuseHeadControlledBinary, resolveTimeLimit, runGate, } from './gate-runner.js';
5
8
  import { resolveBaseRef } from './intent-base.js';
6
9
  import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
7
10
  import { GATE_ROLES, enabledGates, runsAtStage } from './policy.js';
8
11
  import { profileFor } from './products.js';
9
12
  import { ResolveError, resolveGateBinary } from './resolve.js';
10
13
  import { POLICY_PROPOSAL_LINE } from './trust-base.js';
14
+ import { policyChangeLine } from './policy-diff.js';
15
+ /** The whole preview's hard deadline (spec 5.2, finding 2). */
16
+ export const PREVIEW_BUDGET_MS = 300_000;
11
17
  /**
12
18
  * Whether this run is the pull-request shaped one.
13
19
  *
@@ -169,7 +175,13 @@ function collectProposals(outcomes, trustBase,
169
175
  preparation = []) {
170
176
  const proposals = [];
171
177
  if (trustBase?.policyChanged === true) {
172
- proposals.push({ product: 'conductor', role: null, line: POLICY_PROPOSAL_LINE });
178
+ const changes = trustBase.policyChanges ?? [];
179
+ if (changes.length === 0) {
180
+ proposals.push({ product: 'conductor', role: null, line: POLICY_PROPOSAL_LINE });
181
+ }
182
+ for (const change of changes) {
183
+ proposals.push({ product: 'conductor', role: null, line: policyChangeLine(change) });
184
+ }
173
185
  }
174
186
  proposals.push(...preparation);
175
187
  for (const outcome of outcomes) {
@@ -227,7 +239,8 @@ function splitOnTreeUnchanged(gates, trustBase) {
227
239
  * The environment variables the Action sets to say which version of each
228
240
  * family gate it pinned. Since 0.13.0 a control input, in ONE DIRECTION
229
241
  * ONLY: a gate that reports another version, or none, is could-not-run
230
- * (runGate), and nothing else reads them. They can add a could-not-run and
242
+ * (runGate, and for the intent gate also before its preparation, below), and
243
+ * nothing else reads them. They can add a could-not-run and
231
244
  * never clear a gate or drop a finding, so a run that sets them wrongly fails
232
245
  * closed and a run without them is the plain run it always was. Resolution
233
246
  * is unchanged.
@@ -245,6 +258,107 @@ function expectedVersionOption(product, env) {
245
258
  ? { expectedVersion: value }
246
259
  : {};
247
260
  }
261
+ /**
262
+ * The runGate options every gate of a run gets, the preview's included: the
263
+ * preview runs a gate with exactly these, plus its own `preview`.
264
+ */
265
+ function gateRunOptions(gate, options, env) {
266
+ return {
267
+ repoRoot: options.repoRoot,
268
+ staged: options.staged,
269
+ pathValue: options.pathValue,
270
+ ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
271
+ ...expectedVersionOption(gate.product, env),
272
+ // Offered to every child. runGate decides which ones take it: a gate
273
+ // below its pull-request-mode minimum is could-not-run, and a gate it is
274
+ // withheld from carries the reason on the outcome. NEVER left out of the
275
+ // preview: every pull-request protection keys off it (spec 5.2, finding 1).
276
+ ...(options.trustBase === undefined ? {} : { trustBase: options.trustBase.ref }),
277
+ // Where an external gate's working directory goes (its report file, its
278
+ // config from the base ref). The runner removes what it makes.
279
+ ...(options.tempRoot === undefined ? {} : { tempRoot: options.tempRoot }),
280
+ };
281
+ }
282
+ /**
283
+ * Runs `work`, and turns any throw into `fallback(message)`, the message
284
+ * cleaned for a log line and cut to 200 characters. Never rethrows: nothing
285
+ * the preview does may reach the verdict, and a throw would (spec 5.2,
286
+ * finding 3).
287
+ */
288
+ export function guardPreview(work, fallback) {
289
+ try {
290
+ return work();
291
+ }
292
+ catch (err) {
293
+ let raw;
294
+ try {
295
+ raw = err instanceof Error ? err.message : String(err);
296
+ }
297
+ catch {
298
+ raw = 'an error that could not be described';
299
+ }
300
+ return fallback(cleanOutputLine(raw).slice(0, 200));
301
+ }
302
+ }
303
+ /**
304
+ * The preview under the proposed rules: each role of `policy` run once more,
305
+ * with the primary run's own options, trust base included, under one hard
306
+ * deadline. The intent role is deferred and never prepared.
307
+ */
308
+ export function runPreview(policy, options) {
309
+ const clock = options.previewClock ?? Date.now;
310
+ const start = clock();
311
+ const deadline = start + PREVIEW_BUDGET_MS;
312
+ const env = options.env ?? {};
313
+ const skipped = [];
314
+ const deferred = [];
315
+ const toRun = [];
316
+ for (const role of GATE_ROLES) {
317
+ const gate = policy.gates[role];
318
+ if (gate === undefined)
319
+ continue;
320
+ if (gate.excludedByCli) {
321
+ skipped.push({ role, product: gate.product, reason: 'excluded' });
322
+ }
323
+ else if (!gate.enabled) {
324
+ skipped.push({ role, product: gate.product, reason: 'disabled' });
325
+ }
326
+ else if (role === 'intent') {
327
+ // BEFORE the loop, and it never enters it: prepareIntent spawns the
328
+ // intent program (spec 5.2, finding 9).
329
+ deferred.push(role);
330
+ }
331
+ else if (options.stage !== undefined && !runsAtStage(gate.stage, options.stage)) {
332
+ skipped.push({ role, product: gate.product, reason: 'stage' });
333
+ }
334
+ else {
335
+ toRun.push(gate);
336
+ }
337
+ }
338
+ const gates = [];
339
+ const overBudget = [];
340
+ const cacheDir = mkdtempSync(path.join(options.tempRoot ?? os.tmpdir(), 'conductor-preview-'));
341
+ try {
342
+ for (const [index, gate] of toRun.entries()) {
343
+ if (deadline - clock() <= 0) {
344
+ overBudget.push(...toRun.slice(index).map((later) => later.role));
345
+ break;
346
+ }
347
+ gates.push(runGate(gate, { ...gateRunOptions(gate, options, env), preview: { deadline, clock, cacheDir } }));
348
+ }
349
+ }
350
+ finally {
351
+ rmSync(cacheDir, { recursive: true, force: true });
352
+ }
353
+ return {
354
+ gates,
355
+ findings: gates.flatMap((outcome) => outcome.findings).sort(compareFindings),
356
+ skipped,
357
+ deferred,
358
+ overBudget,
359
+ threw: null,
360
+ };
361
+ }
248
362
  export function runAll(policy, options) {
249
363
  const { gates: partitioned, deferred, excluded } = partitionGates(policy, options.stage);
250
364
  const { toRun: gates, treeUnchanged } = splitOnTreeUnchanged(partitioned, options.trustBase);
@@ -283,6 +397,26 @@ export function runAll(policy, options) {
283
397
  continue;
284
398
  }
285
399
  }
400
+ // THEN THE EXPECTED VERSION, still before the preparation spawns
401
+ // anything (residual 3, 2026-10-20). A failed or timed-out
402
+ // preparation ends this gate below, before runGate's own version
403
+ // check, so an off-pin build whose import-spec failed on a run with
404
+ // no trust base and enforce: false read as an unenforced
405
+ // preparation-failed, exit 0, instead of version-skew, exit 2. Same
406
+ // probe and same builder as runGate's. No expectation, no change.
407
+ const expected = expectedVersionOption(gate.product, env).expectedVersion;
408
+ if (expected !== undefined) {
409
+ const notExpected = expectedVersionBeforePreparation(gate, binary, {
410
+ repoRoot: options.repoRoot,
411
+ expectedVersion: expected,
412
+ ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
413
+ ...(trustBaseRef === undefined ? {} : { trustBase: trustBaseRef }),
414
+ });
415
+ if (notExpected !== null) {
416
+ outcomes.push(notExpected);
417
+ continue;
418
+ }
419
+ }
286
420
  const intentLimit = resolveTimeLimit(gate, options.timeoutMs);
287
421
  const prepared = prepareIntent({
288
422
  repoRoot: options.repoRoot,
@@ -344,25 +478,14 @@ export function runAll(policy, options) {
344
478
  }
345
479
  }
346
480
  outcomes.push(runGate(gate, {
347
- repoRoot: options.repoRoot,
348
- staged: options.staged,
349
- pathValue: options.pathValue,
350
- ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
481
+ ...gateRunOptions(gate, options, env),
351
482
  ...(intent === undefined ? {} : { intent }),
352
- ...expectedVersionOption(gate.product, env),
353
483
  // For a run with no preparation: which contract the child will read
354
484
  // out of the repository itself. Looked up only for the gate it is
355
485
  // about, so no other gate pays for the two stat calls.
356
486
  ...(intent !== undefined || gate.role !== 'intent'
357
487
  ? {}
358
488
  : nativeContractOption(options.repoRoot)),
359
- // Offered to every child. runGate decides which ones take it: a
360
- // gate below its pull-request-mode minimum is could-not-run, and a
361
- // gate it is withheld from carries the reason on the outcome.
362
- ...(options.trustBase === undefined ? {} : { trustBase: options.trustBase.ref }),
363
- // Where an external gate's working directory goes (its report file,
364
- // its config from the base ref). The runner removes what it makes.
365
- ...(options.tempRoot === undefined ? {} : { tempRoot: options.tempRoot }),
366
489
  }));
367
490
  }
368
491
  }
@@ -389,9 +512,31 @@ export function runAll(policy, options) {
389
512
  hasBlockingFinding: outcome.findings.some((finding) => finding.blocking),
390
513
  enforce: outcome.enforce,
391
514
  })));
515
+ const summary = {
516
+ blocking: findings.filter((finding) => finding.blocking).length,
517
+ byProduct,
518
+ bySeverity,
519
+ };
520
+ const proposals = collectProposals(outcomes, options.trustBase, preparationProposals);
521
+ // Before the preview too, so a preview of up to 300 s cannot move it.
522
+ const generatedAt = (options.now?.() ?? new Date()).toISOString();
523
+ // LAST, after outcomes, findings, summary, exitCode and proposals are
524
+ // fixed, and nothing above reads it. Inside the throw wrapper, so a throw
525
+ // here is one line in the report and never exit 2 (spec 5.2, finding 3).
526
+ const previewPolicy = options.preview?.policy;
527
+ const preview = previewPolicy === undefined
528
+ ? undefined
529
+ : guardPreview(() => runPreview(previewPolicy, options), (message) => ({
530
+ gates: [],
531
+ findings: [],
532
+ skipped: [],
533
+ deferred: [],
534
+ overBudget: [],
535
+ threw: message,
536
+ }));
392
537
  return {
393
538
  schemaVersion: 1,
394
- generatedAt: (options.now?.() ?? new Date()).toISOString(),
539
+ generatedAt,
395
540
  gates: outcomes,
396
541
  // Absent rather than empty when nothing is disabled, so a run with every
397
542
  // gate on serialises exactly as it did before this field existed.
@@ -402,12 +547,9 @@ export function runAll(policy, options) {
402
547
  treeUnchanged,
403
548
  findings,
404
549
  trustBase: options.trustBase ?? null,
405
- proposals: collectProposals(outcomes, options.trustBase, preparationProposals),
406
- summary: {
407
- blocking: findings.filter((finding) => finding.blocking).length,
408
- byProduct,
409
- bySeverity,
410
- },
550
+ proposals,
551
+ summary,
411
552
  exitCode,
553
+ ...(preview === undefined ? {} : { preview }),
412
554
  };
413
555
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.13.0",
3
+ "version": "0.14.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [
@@ -59,7 +59,7 @@
59
59
  "enum": ["block", "report"]
60
60
  },
61
61
  "timeout-seconds": {
62
- "description": "How long conductor lets this gate run before stopping it, in whole seconds, from 10 to 21600 (six hours, the GitHub-hosted job limit). Every spawn of the gate gets the full limit: the version probe, the scan, the intent gate's preparation steps and osv-scanner's base run. Absent means the default for the product: 120 for dep-guard, vault-guard and intent-guard, 600 for gitleaks, 300 for osv-scanner. A gate stopped at its limit could not run (timed-out). Read from the base branch policy on a pull request, so a pull request cannot change its own limit. Not the same as a gate's own timeout flag under options.",
62
+ "description": "How long conductor lets this gate run before stopping it, in whole seconds, from 10 to 21600 (six hours, the GitHub-hosted job limit). Every spawn of the gate gets the full limit: the version probe, the scan, the intent gate's preparation steps and osv-scanner's base run. Absent means the default for the product: 120 for dep-guard, vault-guard and intent-guard, 600 for gitleaks, 300 for osv-scanner. A gate stopped at its limit could not run (timed-out). Read from the base branch policy on a pull request, so a pull request cannot change its own limit. The preview under the proposed rules also uses the base value, or the product default for a role the base does not have, capped by its 300 second deadline. Not the same as a gate's own timeout flag under options.",
63
63
  "type": "integer",
64
64
  "minimum": 10,
65
65
  "maximum": 21600