@vaultcompass/conductor 0.16.0 → 0.18.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.
@@ -404,14 +404,23 @@ function gateSection(gate, verbose, refusedOnTerminal = false) {
404
404
  const facts = Object.entries(gate.run.details)
405
405
  .filter(([key, value]) =>
406
406
  // ignoredReported drives the line above rather than being a fact
407
- // about the run, so it is not printed twice.
407
+ // about the run, so it is not printed twice. skipReason gets its
408
+ // own line, below.
408
409
  key !== 'ignoredReported' &&
410
+ key !== 'skipReason' &&
409
411
  (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') &&
410
412
  value !== '')
411
413
  .map(([key, value]) => `${key} ${String(value)}`);
412
414
  if (facts.length > 0) {
413
415
  lines.push(` ${facts.join(' ')}`);
414
416
  }
417
+ // The gate's own sentence for having checked nothing (issue 103), in the
418
+ // words the pull-request path's skipped line uses for the same state.
419
+ // The gate wrote it, so it is cleaned like any other gate text.
420
+ const skipReason = intentSkipReason(gate);
421
+ if (skipReason !== null && intentCheckedNothing(gate)) {
422
+ lines.push(` ${skipWording('no-contract').line}: ${cleanOutputLine(skipReason)}`);
423
+ }
415
424
  for (const diagnostic of gate.run.diagnostics) {
416
425
  lines.push(` note ${diagnostic.code}: ${diagnostic.message}`);
417
426
  }
@@ -596,7 +605,7 @@ function trustBaseLines(result) {
596
605
  for (const { gate, reason } of withheldTrustBase(result)) {
597
606
  lines.push(` NOT in pull-request mode ${gate.role} ${gate.product} ${reason}`);
598
607
  }
599
- lines.push(...nodeModulesSkippedLine(result));
608
+ lines.push(...baseMovedSentences(result).map((moved) => ` ${moved}`), ...nodeModulesSkippedLine(result));
600
609
  return lines;
601
610
  }
602
611
  /**
@@ -713,7 +722,7 @@ export function gateOutcomeWords(gate) {
713
722
  }
714
723
  const total = gate.findings.length;
715
724
  const blocking = gate.findings.filter((finding) => finding.blocking).length;
716
- let outcome = total === 0 && (gate.exitCode ?? 0) === 0 ? 'ok' : `findings (${total}, ${blocking} blocking)`;
725
+ let outcome = total === 0 && (gate.exitCode ?? 0) === 0 ? intentCleanWords(gate) : `findings (${total}, ${blocking} blocking)`;
717
726
  // Only when the gate said so; the outcome word above is unchanged.
718
727
  const coverage = deadlineCoverage(gate);
719
728
  if (coverage !== null) {
@@ -947,8 +956,8 @@ function blockingCount(gate) {
947
956
  * nothing-checked exit 0, but nothing was checked: no gate ran at
948
957
  * all (none enabled, or every one deferred,
949
958
  * tree-unchanged or skipped), or every gate that
950
- * ran checked nothing (nothing to scan, or no
951
- * contract; audit finding F4)
959
+ * ran checked nothing (nothing to scan, no contract,
960
+ * or an empty change set; audit finding F4)
952
961
  * advisory-blocked (N) exit 1 that --advisory turned into exit 0
953
962
  * unenforced-findings (N) exit 0, but enforce: false gates blocked or
954
963
  * could not run
@@ -1012,8 +1021,8 @@ export function verdictToken(result, advisory) {
1012
1021
  * A gate that ran and examined nothing: osv-scanner with nothing to scan,
1013
1022
  * osv-scanner whose every handed lockfile parsed to no packages (exit 128,
1014
1023
  * marked `packages-read 0`; a sole lockfile rewritten to {} is exactly the
1015
- * same news as no lockfile), or an intent gate that found no contract to
1016
- * check against. The one predicate behind both the verdict token and the
1024
+ * same news as no lockfile), or an intent gate with no contract to check
1025
+ * against or no changed path. The one predicate behind both the verdict token and the
1017
1026
  * verdict sentence's list of what was not checked.
1018
1027
  *
1019
1028
  * NOT the partial-empty case: `conductor/lockfiles-empty` is also raised
@@ -1030,12 +1039,35 @@ function gateCheckedNothing(gate) {
1030
1039
  }
1031
1040
  return (gate.diagnostics.some((d) => d.code === 'conductor/nothing-to-scan') ||
1032
1041
  readNoPackages(gate) ||
1033
- (gate.role === 'intent' && gate.run.details.contractFound === false));
1042
+ intentCheckedNothing(gate) || intentEmptyChangeSet(gate));
1043
+ }
1044
+ /**
1045
+ * The gate's own skipReason (intent-guard 1.10.4, issue 103), or null. Put
1046
+ * in the run details by normalizeIntentGuard only when non-empty.
1047
+ */
1048
+ export function intentSkipReason(gate) {
1049
+ const said = gate.run.details.skipReason;
1050
+ return typeof said === 'string' && said !== '' ? said : null;
1051
+ }
1052
+ /**
1053
+ * An intent gate that RAN and checked nothing: it said so with skipReason,
1054
+ * or (before 1.10.4) it reported no contract found. The one predicate the
1055
+ * text report, its one-line summary and the SARIF notification all read, so
1056
+ * a directly spawned run reports this state on the same surfaces as the
1057
+ * pull-request path's no-contract skip (issue 103). Never for a gate that
1058
+ * could not run or that blocked: a missing contract under require-frozen is
1059
+ * a block, not a skip.
1060
+ */
1061
+ export function intentCheckedNothing(gate) {
1062
+ return (gate.role === 'intent' &&
1063
+ gate.couldNotRun === null &&
1064
+ !gate.findings.some((finding) => finding.blocking) &&
1065
+ (intentSkipReason(gate) !== null || gate.run.details.contractFound === false));
1034
1066
  }
1035
1067
  /** How the verdict sentence names a gate that ran and checked nothing. */
1036
1068
  function checkedNothingWording(gate) {
1037
1069
  if (gate.role === 'intent') {
1038
- return `${gate.role} ran but found no contract to check against`;
1070
+ return intentNothingWording(gate);
1039
1071
  }
1040
1072
  return readNoPackages(gate)
1041
1073
  ? `${gate.role} read no packages from its lockfiles`
@@ -1239,7 +1271,7 @@ function verdictForRun(result, advisory) {
1239
1271
  function isFullyClean(result) {
1240
1272
  // Every gate that ran checked nothing is the nothing-checked token's state
1241
1273
  // (audit finding F4), and a line opening "clean" would contradict it.
1242
- if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing)) {
1274
+ if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing) || result.gates.some(intentEmptyChangeSet)) {
1243
1275
  return false;
1244
1276
  }
1245
1277
  // A tie the convention refused to guess, or a skip whose branch 0.10.0
@@ -1364,7 +1396,16 @@ function summaryLine(result) {
1364
1396
  // decided there is none exactly where most readers stop reading. Grouped in
1365
1397
  // first-seen order so the sentence does not reorder itself between runs.
1366
1398
  const skippedByWording = new Map();
1367
- for (const gate of result.skipped) {
1399
+ // An intent gate that ran and checked nothing (issue 103) is named in the
1400
+ // same clause as the pull-request path's no-contract skip: it is the same
1401
+ // state, and this line is all a hook or a pull request comment prints.
1402
+ const checkedNothing = [
1403
+ ...result.skipped,
1404
+ ...result.gates
1405
+ .filter(intentCheckedNothing)
1406
+ .map((gate) => ({ role: gate.role, product: gate.product, reason: 'no-contract' })),
1407
+ ];
1408
+ for (const gate of checkedNothing) {
1368
1409
  const lead = skipWording(gate.reason).summary;
1369
1410
  skippedByWording.set(lead, [
1370
1411
  ...(skippedByWording.get(lead) ?? []),
@@ -1460,7 +1501,7 @@ function summaryLine(result) {
1460
1501
  // produces a clean report, and without this clause the only trace of the
1461
1502
  // attempt would be in a file nobody re-reads.
1462
1503
  if (result.trustBase !== null) {
1463
- parts.push(`Rules from ${result.trustBase.ref}. ${proposalCount(result)}.`);
1504
+ parts.push(`Rules from ${result.trustBase.ref}. ${proposalCount(result)}.`, ...baseMovedSentences(result));
1464
1505
  const withheld = withheldTrustBase(result);
1465
1506
  if (withheld.length > 0) {
1466
1507
  const names = withheld.map(({ gate }) => `${gate.role} (${gate.product})`).join(', ');
@@ -1572,3 +1613,48 @@ export function renderText(result, options = {}) {
1572
1613
  lines.push('', verdict(result, Boolean(options.advisory)));
1573
1614
  return withPreview(`${lines.join('\n')}\n`);
1574
1615
  }
1616
+ /**
1617
+ * An intent gate that ran with a contract on a change set of no paths: a branch
1618
+ * the base it was measured against already carries, or a net-empty one. The
1619
+ * gate says it is clean and it is, about nothing. Never for a gate that could
1620
+ * not run or that blocked: every could-not-run outcome carries a blocking finding,
1621
+ * so the one clause covers both. It does its work in the SARIF notification, which
1622
+ * reads this directly; the text report sorts those gates out before it gets here.
1623
+ */
1624
+ export function intentEmptyChangeSet(gate) {
1625
+ return (gate.role === 'intent' &&
1626
+ !gate.findings.some((finding) => finding.blocking) &&
1627
+ gate.intent?.changedPaths === 0);
1628
+ }
1629
+ /** How the verdict sentence names an intent gate that ran and checked nothing. */
1630
+ export function intentNothingWording(gate) {
1631
+ return intentCheckedNothing(gate)
1632
+ ? `${gate.role} ran but found no contract to check against`
1633
+ : `${gate.role} ran on an empty change set, so no path was judged against its contract`;
1634
+ }
1635
+ /**
1636
+ * The outcome word on a gate's log line when it found nothing and exited 0. An
1637
+ * intent gate with no contract gets the words of the pull-request path's skipped
1638
+ * line for the same state, though it did run and so has an exit code to give.
1639
+ */
1640
+ function intentCleanWords(gate) {
1641
+ if (intentCheckedNothing(gate)) {
1642
+ return `skipped (${skipWording('no-contract').line})`;
1643
+ }
1644
+ return intentEmptyChangeSet(gate) ? 'ok, empty change set' : 'ok';
1645
+ }
1646
+ /**
1647
+ * Why the rules commit is not the base branch's tip, on a run the Action moved
1648
+ * past it, as a list of one, or of none. Says what happened and never that
1649
+ * anything merged: the same shape occurs on an open pull request. The text
1650
+ * report and the SARIF log read this one sentence, so they cannot disagree.
1651
+ */
1652
+ export function baseMovedSentences(result) {
1653
+ const trust = result.trustBase;
1654
+ return trust === null || trust.baseTip === undefined
1655
+ ? []
1656
+ : [
1657
+ `The base branch moved past the merge ref this run is on, to ${trust.baseTip}, which has ` +
1658
+ `the same tree, so the rules are from ${trust.ref}, the commit the merge ref was built from.`,
1659
+ ];
1660
+ }
package/dist/policy.d.ts CHANGED
@@ -140,11 +140,31 @@ export interface CliOverrides {
140
140
  export declare function applyCliOverrides(policy: Policy, overrides: CliOverrides): Policy;
141
141
  /** Enabled gates in role order, so a report's section order never depends on file order. */
142
142
  export declare function enabledGates(policy: Policy): GatePolicy[];
143
+ /**
144
+ * Flags that take NO value, per product, read from each gate's own `--help`
145
+ * (osv-scanner 2.4.0 `scan source`, gitleaks 8.30.1 `git`, dep-guard 0.17.0
146
+ * and vault-guard 1.12.1 `scan`, intent-guard 1.10.2 `check`, and 1.10.3
147
+ * `check` again for issue 161, which lists the same flags). Two readers:
148
+ *
149
+ * - gateArgEntries in resolve.ts: the word after one of these is NOT its
150
+ * value, so `osv-scanner scan source -r .` keeps `.` as a positional scan
151
+ * target (re-review 2026-10-28, R1). Any flag not listed stays
152
+ * fail-closed there: the word after it is read as its value. A wrong
153
+ * entry would let a value be read as a positional, which leaves a
154
+ * directory unvetted, so entries come only from a gate's own help text.
155
+ * - renderOptionFlags below: a `true` option whose gate lists `--no-<key>`
156
+ * and not `--<key>` is not rendered (issue 161).
157
+ */
158
+ export declare const NO_VALUE_FLAGS: Record<Product, readonly string[]>;
143
159
  /**
144
160
  * Renders a passthrough option bag as child-process arguments.
145
161
  *
146
162
  * Keys are sorted so two policy files that differ only in key order produce
147
163
  * the same command line, which is what makes a run reproducible and a
148
164
  * report diffable.
165
+ *
166
+ * `product` is required so every caller renders what that gate accepts:
167
+ * `true` is `--key`, except where the gate's own help has only `--no-key`
168
+ * (onlyNegatedSpelling), where it is nothing.
149
169
  */
150
- export declare function renderOptionFlags(options: Record<string, OptionValue>): string[];
170
+ export declare function renderOptionFlags(options: Record<string, OptionValue>, product: Product): string[];
package/dist/policy.js CHANGED
@@ -443,19 +443,75 @@ export function applyCliOverrides(policy, overrides) {
443
443
  export function enabledGates(policy) {
444
444
  return GATE_ROLES.map((role) => policy.gates[role]).filter((gate) => gate !== undefined && gate.enabled);
445
445
  }
446
+ /**
447
+ * Flags that take NO value, per product, read from each gate's own `--help`
448
+ * (osv-scanner 2.4.0 `scan source`, gitleaks 8.30.1 `git`, dep-guard 0.17.0
449
+ * and vault-guard 1.12.1 `scan`, intent-guard 1.10.2 `check`, and 1.10.3
450
+ * `check` again for issue 161, which lists the same flags). Two readers:
451
+ *
452
+ * - gateArgEntries in resolve.ts: the word after one of these is NOT its
453
+ * value, so `osv-scanner scan source -r .` keeps `.` as a positional scan
454
+ * target (re-review 2026-10-28, R1). Any flag not listed stays
455
+ * fail-closed there: the word after it is read as its value. A wrong
456
+ * entry would let a value be read as a positional, which leaves a
457
+ * directory unvetted, so entries come only from a gate's own help text.
458
+ * - renderOptionFlags below: a `true` option whose gate lists `--no-<key>`
459
+ * and not `--<key>` is not rendered (issue 161).
460
+ */
461
+ export const NO_VALUE_FLAGS = {
462
+ 'osv-scanner': [
463
+ '-r', '--recursive', '--no-ignore', '--include-git-root', '--serve', '--offline',
464
+ '--offline-vulnerabilities', '--download-offline-databases', '--no-resolve',
465
+ '--allow-no-lockfiles', '--all-packages', '--all-vulns',
466
+ '--experimental-flag-deprecated-packages', '--experimental-no-default-plugins', '-h', '--help',
467
+ ],
468
+ gitleaks: [
469
+ '-v', '--verbose', '--pre-commit', '--staged', '--ignore-gitleaks-allow', '--no-banner',
470
+ '--no-color', '--redact', '-h', '--help',
471
+ ],
472
+ 'dep-guard': ['--staged', '--online', '--no-online', '-h', '--help'],
473
+ 'vault-guard': ['--staged', '-h', '--help'],
474
+ 'intent-guard': ['--staged', '--no-require-frozen', '--log', '--json', '-h', '--help', '-v', '--version'],
475
+ };
476
+ /**
477
+ * Whether `--<key>` is a spelling the gate does not have while `--no-<key>`
478
+ * is: its own help lists only the negation. The gate's default for such a
479
+ * flag is then on (a `--no-` flag exists to turn a default off), so a policy
480
+ * value `true` asks for exactly the default, and rendering it would hand the
481
+ * gate an option it refuses (issue 161: intent-guard 1.10.3 `check
482
+ * --require-frozen` exits 1 with "unknown option", which every directly
483
+ * spawned run reported as unparseable output).
484
+ *
485
+ * General across gates, not an intent-guard case: gitleaks `banner` and
486
+ * `color` and osv-scanner `ignore` and `resolve` take the same path. The
487
+ * premise is the table's: NO_VALUE_FLAGS lists only value-less flags, so
488
+ * this reads "the gate has a value-less --no-<key> and no value-less
489
+ * --<key>". A gate with a VALUED --<key> beside a value-less --no-<key>
490
+ * would wrongly lose `true`; no gate has that shape today.
491
+ */
492
+ function onlyNegatedSpelling(key, product) {
493
+ const known = NO_VALUE_FLAGS[product];
494
+ return known.includes(`--no-${key}`) && !known.includes(`--${key}`);
495
+ }
446
496
  /**
447
497
  * Renders a passthrough option bag as child-process arguments.
448
498
  *
449
499
  * Keys are sorted so two policy files that differ only in key order produce
450
500
  * the same command line, which is what makes a run reproducible and a
451
501
  * report diffable.
502
+ *
503
+ * `product` is required so every caller renders what that gate accepts:
504
+ * `true` is `--key`, except where the gate's own help has only `--no-key`
505
+ * (onlyNegatedSpelling), where it is nothing.
452
506
  */
453
- export function renderOptionFlags(options) {
507
+ export function renderOptionFlags(options, product) {
454
508
  const args = [];
455
509
  for (const key of Object.keys(options).sort()) {
456
510
  const value = options[key];
457
511
  if (value === true) {
458
- args.push(`--${key}`);
512
+ if (!onlyNegatedSpelling(key, product)) {
513
+ args.push(`--${key}`);
514
+ }
459
515
  }
460
516
  else if (value === false) {
461
517
  // Both dep-guard and intent-guard spell a negated boolean this way,
package/dist/resolve.d.ts CHANGED
@@ -26,6 +26,8 @@ export interface DataArgument {
26
26
  positional: boolean;
27
27
  /** The args entry as written, for the refusal message. */
28
28
  entry: string;
29
+ /** 'options' when the value came from the policy's `options:`, so the refusal names that list; absent for `args:`. */
30
+ from?: 'options';
29
31
  }
30
32
  export interface ResolvedBinary {
31
33
  /** What to spawn. */
@@ -59,14 +61,23 @@ export interface ResolvedBinary {
59
61
  * When `command:` is the gate itself (commandIsGateProgram) only the args
60
62
  * entries with a code extension are listed here (`codeArguments`); the
61
63
  * rest of its args are its own argv, read as data, and land in
62
- * `dataArguments` instead.
64
+ * `dataArguments` instead. The code-extension `options:` values are listed
65
+ * here too, for every command and for a gate resolution found (audit
66
+ * 2026-11-01, MB1).
63
67
  */
64
68
  argumentPaths: string[];
69
+ /**
70
+ * The entries of `argumentPaths` that came from `options:`, so a refusal
71
+ * names the list the value was written in (review of the 2026-11-01 fix,
72
+ * item 3). Absent is the same as empty: every entry came from `args:`.
73
+ */
74
+ optionArgumentPaths?: string[];
65
75
  /**
66
76
  * Every args entry that could name a path, when `command:` is the gate
67
77
  * itself (`dataArgumentPaths`), in args order, by POSITION and never by
68
- * what the head's disk holds. Empty for every other command, and when
69
- * resolution found the gate.
78
+ * what the head's disk holds; then every non-code `options:` value as
79
+ * rendered, for every command and for a gate resolution found (audit
80
+ * 2026-11-01, MB1).
70
81
  *
71
82
  * The pull-request check (refuseHeadControlledData) decides from the BASE
72
83
  * tree what each one is: a file must be the base's blob, a directory given
@@ -195,7 +206,8 @@ export declare function argumentCandidates(arg: string, repoRoot: string): strin
195
206
  /**
196
207
  * The args entries vetted as CODE: every entry when the command is not the
197
208
  * gate itself, and only the code-extension values (`hasCodeExtension`) when
198
- * it is. Each goes through `argumentCandidates`, here and in the preview.
209
+ * it is, then the code-extension `options:` values (optionCodeArguments).
210
+ * Each goes through `argumentCandidates`, here and in the preview.
199
211
  */
200
212
  export declare function codeArguments(gate: GatePolicy): string[];
201
213
  /**
@@ -218,5 +230,12 @@ export declare function codeArguments(gate: GatePolicy): string[];
218
230
  * wrapper given a gate's name that hands an extension-less entry to an
219
231
  * interpreter is a wrapper, vetted no further than this (README,
220
232
  * pull-request trust boundary).
233
+ *
234
+ * Then every non-code `options:` value (optionEntries), WHATEVER the command
235
+ * is and with no command at all: they are rendered into the argv of every
236
+ * spawn, after the args, so they are the gate's own data (or a script's)
237
+ * whoever runs them, and a rules directory written there is as much the
238
+ * rules as one written in args (audit 2026-11-01, MB1). Marked `from:
239
+ * 'options'` only so a refusal names the list the value came from.
221
240
  */
222
241
  export declare function dataArgumentPaths(gate: GatePolicy, repoRoot: string): DataArgument[];
package/dist/resolve.js CHANGED
@@ -61,6 +61,7 @@
61
61
  // reported missing.
62
62
  import { accessSync, constants, lstatSync, statSync } from 'node:fs';
63
63
  import path from 'node:path';
64
+ import { NO_VALUE_FLAGS, renderOptionFlags } from './policy.js';
64
65
  import { profileFor } from './products.js';
65
66
  export const CANDIDATES = {
66
67
  'dep-guard': [{ name: 'dep-guard', prefix: ['scan'], versionSafe: true }],
@@ -221,6 +222,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
221
222
  const candidateName = inferred?.name ?? baseName(gate.command);
222
223
  const candidate = inferred ?? table[0];
223
224
  const argumentPaths = argumentPathsOf(gate, repoRoot);
225
+ const optionArgumentPaths = optionArgumentPathsOf(gate, repoRoot);
224
226
  const dataArguments = dataArgumentPaths(gate, repoRoot);
225
227
  // A build directory holds plain .js files with a shebang but no
226
228
  // executable bit surprisingly often (a fresh tsc output, a file copied
@@ -234,6 +236,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
234
236
  program: gate.command,
235
237
  argvPrefix: [gate.command, ...prefix],
236
238
  argumentPaths,
239
+ optionArgumentPaths,
237
240
  dataArguments,
238
241
  source: 'policy',
239
242
  candidate: candidateName,
@@ -255,6 +258,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
255
258
  program: gate.command,
256
259
  argvPrefix: prefix,
257
260
  argumentPaths,
261
+ optionArgumentPaths,
258
262
  dataArguments,
259
263
  source: 'policy',
260
264
  candidate: candidateName,
@@ -271,8 +275,11 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
271
275
  command: found.command,
272
276
  program: found.command,
273
277
  argvPrefix: [...candidate.prefix],
274
- argumentPaths: [],
275
- dataArguments: [],
278
+ // No args: here (they go with a command:), but the options: are handed
279
+ // to this gate all the same (audit 2026-11-01, MB1).
280
+ argumentPaths: optionArgumentPathsOf(gate, repoRoot),
281
+ optionArgumentPaths: optionArgumentPathsOf(gate, repoRoot),
282
+ dataArguments: dataArgumentPaths(gate, repoRoot),
276
283
  source: found.source,
277
284
  candidate: candidate.name,
278
285
  versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
@@ -412,35 +419,10 @@ function hasCodeExtension(value) {
412
419
  * - a bare word that is one of the product's subcommands: nothing;
413
420
  * - any other word: a positional.
414
421
  */
415
- /**
416
- * Flags that take NO value, per product, read from each gate's own `--help`
417
- * (osv-scanner 2.4.0 `scan source`, gitleaks 8.30.1 `git`, dep-guard 0.17.0
418
- * and vault-guard 1.12.1 `scan`, intent-guard 1.10.2 `check`). The word after
419
- * one of these is NOT its value, so `osv-scanner scan source -r .` keeps `.`
420
- * as a positional scan target (re-review 2026-10-28, R1). Any flag not listed
421
- * stays fail-closed: the word after it is read as its value. A wrong entry
422
- * would let a value be read as a positional, which leaves a directory
423
- * unvetted, so entries come only from a gate's own help text.
424
- */
425
- const NO_VALUE_FLAGS = {
426
- 'osv-scanner': [
427
- '-r', '--recursive', '--no-ignore', '--include-git-root', '--serve', '--offline',
428
- '--offline-vulnerabilities', '--download-offline-databases', '--no-resolve',
429
- '--allow-no-lockfiles', '--all-packages', '--all-vulns',
430
- '--experimental-flag-deprecated-packages', '--experimental-no-default-plugins', '-h', '--help',
431
- ],
432
- gitleaks: [
433
- '-v', '--verbose', '--pre-commit', '--staged', '--ignore-gitleaks-allow', '--no-banner',
434
- '--no-color', '--redact', '-h', '--help',
435
- ],
436
- 'dep-guard': ['--staged', '--online', '--no-online', '-h', '--help'],
437
- 'vault-guard': ['--staged', '-h', '--help'],
438
- 'intent-guard': ['--staged', '--no-require-frozen', '--log', '--json', '-h', '--help', '-v', '--version'],
439
- };
440
- function gateArgEntries(gate) {
422
+ function gateArgEntries(product, words) {
441
423
  const entries = [];
442
424
  let pendingOption = false;
443
- for (const arg of gate.args ?? []) {
425
+ for (const arg of words) {
444
426
  if (arg.startsWith('-') && arg !== '-') {
445
427
  pendingOption = false;
446
428
  const equals = arg.indexOf('=');
@@ -453,7 +435,7 @@ function gateArgEntries(gate) {
453
435
  else {
454
436
  // A flag the gate's own help says takes no value leaves the next word
455
437
  // a positional (NO_VALUE_FLAGS); any other flag claims it.
456
- pendingOption = !NO_VALUE_FLAGS[gate.product].includes(arg);
438
+ pendingOption = !NO_VALUE_FLAGS[product].includes(arg);
457
439
  }
458
440
  continue;
459
441
  }
@@ -462,30 +444,54 @@ function gateArgEntries(gate) {
462
444
  entries.push({ value: arg, positional: false, entry: arg });
463
445
  continue;
464
446
  }
465
- if (CANDIDATES[gate.product].some((candidate) => candidate.prefix.includes(arg))) {
447
+ if (CANDIDATES[product].some((candidate) => candidate.prefix.includes(arg))) {
466
448
  continue;
467
449
  }
468
450
  entries.push({ value: arg, positional: true, entry: arg });
469
451
  }
470
452
  return entries.filter((each) => each.value !== '');
471
453
  }
454
+ /**
455
+ * The policy's `options:` as the gate receives them: rendered to flags
456
+ * (renderOptionFlags, the same rendering gateArgs appends to every spawn) and
457
+ * read by position like a gate-named command's args (audit 2026-11-01, MB1).
458
+ *
459
+ * Whatever the command is: the rendered flags always come after the args, so
460
+ * they are the gate's own argv, or a script's argv when the command is an
461
+ * interpreter, and never an interpreter's. Option keys cannot hold `=` (the
462
+ * schema's key pattern), so `--name value` is the only rendering there is.
463
+ */
464
+ function optionEntries(gate) {
465
+ return gateArgEntries(gate.product, renderOptionFlags(gate.options, gate.product));
466
+ }
467
+ /** The `options:` values vetted as CODE: those with a code extension, as for a gate-named command's args. */
468
+ function optionCodeArguments(gate) {
469
+ return optionEntries(gate)
470
+ .filter((each) => hasCodeExtension(each.value))
471
+ .map((each) => each.value);
472
+ }
472
473
  /**
473
474
  * The args entries vetted as CODE: every entry when the command is not the
474
475
  * gate itself, and only the code-extension values (`hasCodeExtension`) when
475
- * it is. Each goes through `argumentCandidates`, here and in the preview.
476
+ * it is, then the code-extension `options:` values (optionCodeArguments).
477
+ * Each goes through `argumentCandidates`, here and in the preview.
476
478
  */
477
479
  export function codeArguments(gate) {
478
- if (!commandIsGateProgram(gate)) {
479
- return gate.args ?? [];
480
- }
481
- return gateArgEntries(gate)
482
- .filter((each) => hasCodeExtension(each.value))
483
- .map((each) => each.value);
480
+ const fromArgs = !commandIsGateProgram(gate)
481
+ ? gate.args ?? []
482
+ : gateArgEntries(gate.product, gate.args ?? [])
483
+ .filter((each) => hasCodeExtension(each.value))
484
+ .map((each) => each.value);
485
+ return [...fromArgs, ...optionCodeArguments(gate)];
484
486
  }
485
487
  /** `argumentCandidates` for every code argument (`codeArguments`), flattened. */
486
488
  function argumentPathsOf(gate, repoRoot) {
487
489
  return codeArguments(gate).flatMap((arg) => argumentCandidates(arg, repoRoot));
488
490
  }
491
+ /** `argumentCandidates` for the code-extension `options:` values alone (optionCodeArguments). */
492
+ function optionArgumentPathsOf(gate, repoRoot) {
493
+ return optionCodeArguments(gate).flatMap((arg) => argumentCandidates(arg, repoRoot));
494
+ }
489
495
  /**
490
496
  * The args entries of a gate-named command that are its own DATA, when
491
497
  * `command:` is the gate itself (commandIsGateProgram), in args order; empty
@@ -506,14 +512,29 @@ function argumentPathsOf(gate, repoRoot) {
506
512
  * wrapper given a gate's name that hands an extension-less entry to an
507
513
  * interpreter is a wrapper, vetted no further than this (README,
508
514
  * pull-request trust boundary).
515
+ *
516
+ * Then every non-code `options:` value (optionEntries), WHATEVER the command
517
+ * is and with no command at all: they are rendered into the argv of every
518
+ * spawn, after the args, so they are the gate's own data (or a script's)
519
+ * whoever runs them, and a rules directory written there is as much the
520
+ * rules as one written in args (audit 2026-11-01, MB1). Marked `from:
521
+ * 'options'` only so a refusal names the list the value came from.
509
522
  */
510
523
  export function dataArgumentPaths(gate, repoRoot) {
511
- if (gate.command === undefined || !commandIsGateProgram(gate)) {
512
- return [];
513
- }
514
- return gateArgEntries(gate)
524
+ const fromArgs = gate.command === undefined || !commandIsGateProgram(gate)
525
+ ? []
526
+ : gateArgEntries(gate.product, gate.args ?? [])
527
+ .filter((each) => !hasCodeExtension(each.value))
528
+ .map((each) => ({ path: path.resolve(repoRoot, each.value), positional: each.positional, entry: each.entry }));
529
+ const fromOptions = optionEntries(gate)
515
530
  .filter((each) => !hasCodeExtension(each.value))
516
- .map((each) => ({ path: path.resolve(repoRoot, each.value), positional: each.positional, entry: each.entry }));
531
+ .map((each) => ({
532
+ path: path.resolve(repoRoot, each.value),
533
+ positional: each.positional,
534
+ entry: each.entry,
535
+ from: 'options',
536
+ }));
537
+ return [...fromArgs, ...fromOptions];
517
538
  }
518
539
  /**
519
540
  * The version probe for a policy `command:` that is not itself a gate name,
package/dist/run.d.ts CHANGED
@@ -109,7 +109,7 @@ export interface ControlProposal {
109
109
  * the policy file at the base ref with the one at the head commit. It is
110
110
  * reported and never acted on: the base ref's policy is the one that ran.
111
111
  */
112
- export interface RunTrustBase {
112
+ export interface RunTrustBase extends BaseTipForDisplay {
113
113
  /** The ref the umbrella took its own policy from. */
114
114
  ref: string;
115
115
  /** Whether the head commit's own policy file differs from that one. */
@@ -340,3 +340,13 @@ export declare function guardPreview<T>(work: () => T, fallback: (message: strin
340
340
  */
341
341
  export declare function runPreview(policy: Policy, options: RunOptions): RunPreview;
342
342
  export declare function runAll(policy: Policy, options: RunOptions): RunResult;
343
+ /** The part of a trust base only the reports read. */
344
+ interface BaseTipForDisplay {
345
+ /**
346
+ * The base branch's tip, when the Action moved this trust base past it
347
+ * (`withMovedBaseTip`, trust-base.ts). Printed by the reports and read by
348
+ * nothing else.
349
+ */
350
+ baseTip?: string;
351
+ }
352
+ export {};