@vaultcompass/conductor 0.15.0 → 0.17.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.
@@ -31,8 +31,8 @@ import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals,
31
31
  import { osvLockfileKind, profileFor } from './products.js';
32
32
  import { unreadManifestsNote } from './unread-manifests.js';
33
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';
34
+ import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledData, refuseHeadControlledProgram, writtenInsideWorkingTree, } from './trust-base.js';
35
+ import { ResolveError, argumentCandidates, candidateNames, codeArguments, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
36
36
  /** The longest excerpt of a gate's own reason that is carried. */
37
37
  export const GATE_SAID_MAX_CHARS = 160;
38
38
  /**
@@ -675,8 +675,18 @@ export function refuseHeadControlledBinary(repoRoot, trustBase, binary) {
675
675
  return refusal;
676
676
  }
677
677
  }
678
+ const fromOptions = new Set(binary.optionArgumentPaths ?? []);
678
679
  for (const argument of binary.argumentPaths) {
679
- const refusal = refuseHeadControlledArgument(repoRoot, trustBase, argument);
680
+ const refusal = refuseHeadControlledArgument(repoRoot, trustBase, argument, fromOptions.has(argument) ? "the gate's options:" : "the gate's args:");
681
+ if (refusal !== null) {
682
+ return refusal;
683
+ }
684
+ }
685
+ // A command that is the gate itself reads the rest of its args as data
686
+ // (audit 2026-10-28, N1, and its review): what each path is comes from the
687
+ // base tree, and a file or an option-value directory must be the base's.
688
+ for (const data of binary.dataArguments) {
689
+ const refusal = refuseHeadControlledData(repoRoot, trustBase, data);
680
690
  if (refusal !== null) {
681
691
  return refusal;
682
692
  }
@@ -761,7 +771,7 @@ changeBase,
761
771
  * after its enables, so the appended flag wins.
762
772
  */
763
773
  preview = false) {
764
- const passthrough = renderOptionFlags(gate.options);
774
+ const passthrough = renderOptionFlags(gate.options, gate.product);
765
775
  const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
766
776
  const config = external.configPath === undefined ? [] : ['--config', external.configPath];
767
777
  switch (gate.product) {
@@ -937,7 +947,7 @@ preview = false) {
937
947
  ...lockfiles,
938
948
  ...(noResolve ? ['--no-resolve'] : []),
939
949
  ...callAnalysis,
940
- ...renderOptionFlags(options),
950
+ ...renderOptionFlags(options, gate.product),
941
951
  ...(preview ? ['--no-call-analysis=all'] : []),
942
952
  ];
943
953
  }
@@ -1295,7 +1305,11 @@ function previewRefusal(gate, repoRoot) {
1295
1305
  detail: "the preview does not run call analysis, because it would build the head's code",
1296
1306
  };
1297
1307
  }
1298
- if (gate.command !== undefined && realPathInside(repoRoot, gate.command)) {
1308
+ // Inside by its real path OR as written: a directory on the written path
1309
+ // that is a link out of the tree is the head's choice too (audit
1310
+ // 2026-11-01, MB2), and the primary rule judges every path as written.
1311
+ if (gate.command !== undefined &&
1312
+ (realPathInside(repoRoot, gate.command) || writtenInsideWorkingTree(repoRoot, gate.command))) {
1299
1313
  return {
1300
1314
  reason: 'gate-program-refused',
1301
1315
  detail: `preview under the proposed rules: the base command ${gate.command} is inside the working tree, so this gate was not run`,
@@ -1310,11 +1324,17 @@ function previewRefusal(gate, repoRoot) {
1310
1324
  // own entry is in the tree, wherever it points (its directory is checked).
1311
1325
  // The candidate set is the primary run's (argumentCandidates): the entry and
1312
1326
  // 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)))) {
1327
+ // tools/gate/ is refused here too. The entries are the primary run's code
1328
+ // arguments (codeArguments): every entry for a command that is not the gate
1329
+ // itself, and only the code-extension ones for one that is. The gate's
1330
+ // other args are data it reads (audit 2026-10-28, N1), and runGate's data
1331
+ // check (refuseHeadControlledData, through refuseHeadControlledBinary) runs
1332
+ // on every preview spawn, an option-value directory included (review B1).
1333
+ for (const arg of codeArguments(gate)) {
1334
+ const candidates = argumentCandidates(arg, repoRoot);
1335
+ if (candidates.some((named) => realPathInside(repoRoot, named) ||
1336
+ realPathInside(repoRoot, path.dirname(named)) ||
1337
+ writtenInsideWorkingTree(repoRoot, named))) {
1318
1338
  return {
1319
1339
  reason: 'gate-program-refused',
1320
1340
  detail: `preview under the proposed rules: the base args entry ${arg} names a path inside the working tree, so this gate was not run`,
package/dist/normalize.js CHANGED
@@ -533,8 +533,15 @@ function readTrustBase(raw, product) {
533
533
  export function normalizeIntentGuard(raw, version) {
534
534
  const product = 'intent-guard';
535
535
  const root = needRecord(raw, product, 'the output');
536
- if (root.status !== 'blocked' && root.status !== 'ok') {
537
- fail(product, 'status', 'either "ok" or "blocked"');
536
+ // "skipped" is accepted ahead of the gate using it (issue 103): intent-guard
537
+ // 1.10.4 says "nothing was checked" as status ok plus skipReason, because
538
+ // anything else would have been unparseable to every conductor up to this
539
+ // one, and a later release can move to a status of its own once its pin
540
+ // floor is above this version. It is the one value added; every other
541
+ // status is still refused, and readSkipReason refuses a skipped status
542
+ // that names no reason or that carries a finding.
543
+ if (root.status !== 'blocked' && root.status !== 'ok' && root.status !== 'skipped') {
544
+ fail(product, 'status', 'one of "ok", "blocked" or "skipped"');
538
545
  }
539
546
  const trustBase = readTrustBase(root.trustBase, product);
540
547
  const warnings = readIntentWarnings(root.warnings);
@@ -678,6 +685,7 @@ export function normalizeIntentGuard(raw, version) {
678
685
  : 'The intent gate blocked without stating a reason.', 'unattributed'));
679
686
  }
680
687
  }
688
+ const skipReason = readSkipReason(root, findings, product);
681
689
  return {
682
690
  findings,
683
691
  ...(trustBase === undefined ? {} : { trustBase }),
@@ -700,11 +708,43 @@ export function normalizeIntentGuard(raw, version) {
700
708
  driftCategories: drift?.categories ?? null,
701
709
  budgetAction: budget?.action ?? null,
702
710
  reasons,
711
+ // Present only when the gate said it checked nothing. The report
712
+ // surfaces read it through intentCheckedNothing in output-text.ts.
713
+ ...(skipReason === null ? {} : { skipReason }),
703
714
  },
704
715
  },
705
716
  diagnostics: [],
706
717
  };
707
718
  }
719
+ /**
720
+ * The gate's own statement that it checked nothing, or null (issue 103).
721
+ *
722
+ * intent-guard 1.10.4 puts a top-level `skipReason` string on a result whose
723
+ * status is still "ok" when require-frozen is off and there is no contract;
724
+ * a future status "skipped" means the same. Read only on those two
725
+ * statuses: a blocked result stays blocked whatever else it says, which is
726
+ * the fail-closed reading of a contradiction. An empty string is no reason.
727
+ *
728
+ * Refused as unparseable, never guessed at: a skipReason that is not a
729
+ * string, a status "skipped" that names no reason, and a skip that carries
730
+ * any finding. "Nothing was checked" beside a finding is a contradiction,
731
+ * and reading it as a skip would hide the finding, so the gate is reported
732
+ * as one whose output could not be read.
733
+ */
734
+ function readSkipReason(root, findings, product) {
735
+ if (root.status === 'blocked') {
736
+ return null;
737
+ }
738
+ const said = optionalString(root.skipReason ?? undefined, product, 'skipReason');
739
+ const reason = said === undefined || said === '' ? null : said;
740
+ if (root.status === 'skipped' && reason === null) {
741
+ fail(product, 'skipReason', 'a non-empty string when status is "skipped"');
742
+ }
743
+ if (reason !== null && findings.length > 0) {
744
+ fail(product, 'findings', 'empty when the gate says it checked nothing (skipReason)');
745
+ }
746
+ return reason;
747
+ }
708
748
  // -- gitleaks (external, git history mode) -------------------------------
709
749
  //
710
750
  // The report is a JSON array written to a file, one entry per leak, with
@@ -121,7 +121,7 @@ import { gateExitBlocks } from './exit-codes.js';
121
121
  import { cleanPreviewLine } from './gate-runner.js';
122
122
  import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
123
123
  import { INTENT_WARNING } from './normalize.js';
124
- import { gateOutcomeWords, skewFound, skewPlace } from './output-text.js';
124
+ import { gateOutcomeWords, intentCheckedNothing, intentSkipReason, skewFound, skewPlace, } from './output-text.js';
125
125
  import { POLICY_FILE_NAME } from './policy.js';
126
126
  import { policyChangeLine } from './policy-diff.js';
127
127
  import { guardPreview } from './run.js';
@@ -587,6 +587,27 @@ function treeUnchangedNotifications(result) {
587
587
  * keep answering it the same way.
588
588
  */
589
589
  function skippedNotifications(result) {
590
+ return [...preparedSkipNotifications(result), ...ranAndCheckedNothingNotifications(result)];
591
+ }
592
+ /**
593
+ * An intent gate that RAN and checked nothing (issue 103): intent-guard
594
+ * 1.10.4's skipReason on a directly spawned run, or, before it, no contract
595
+ * found with require-frozen off. Filed under the same id as the
596
+ * pull-request path's no-contract skip, with the same message shape and the
597
+ * gate's own sentence as the detail, because it is the same state and a
598
+ * consumer filtering on intent-guard/no-contract should see both. The same
599
+ * predicate the text report reads (intentCheckedNothing), so the two agree.
600
+ * The gate's own run is still in the log, since it did run.
601
+ */
602
+ function ranAndCheckedNothingNotifications(result) {
603
+ return result.gates.filter(intentCheckedNothing).map((gate) => ({
604
+ id: `${gate.product}/no-contract`,
605
+ message: `The ${gate.role} gate (${gate.product}) checked nothing on this branch. ` +
606
+ (intentSkipReason(gate) ?? 'It found no contract to check against.'),
607
+ details: { role: gate.role, product: gate.product, reason: 'no-contract' },
608
+ }));
609
+ }
610
+ function preparedSkipNotifications(result) {
590
611
  return result.skipped.map((gate) => ({
591
612
  // The reason IS the second half of the id, which keeps
592
613
  // intent-guard/no-contract exactly where consumers already have it and
@@ -177,6 +177,21 @@ export declare function versionSkewSummaryLines(result: RunResult): string[];
177
177
  * not a pass.
178
178
  */
179
179
  export declare function verdictToken(result: RunResult, advisory: boolean): string;
180
+ /**
181
+ * The gate's own skipReason (intent-guard 1.10.4, issue 103), or null. Put
182
+ * in the run details by normalizeIntentGuard only when non-empty.
183
+ */
184
+ export declare function intentSkipReason(gate: GateOutcome): string | null;
185
+ /**
186
+ * An intent gate that RAN and checked nothing: it said so with skipReason,
187
+ * or (before 1.10.4) it reported no contract found. The one predicate the
188
+ * text report, its one-line summary and the SARIF notification all read, so
189
+ * a directly spawned run reports this state on the same surfaces as the
190
+ * pull-request path's no-contract skip (issue 103). Never for a gate that
191
+ * could not run or that blocked: a missing contract under require-frozen is
192
+ * a block, not a skip.
193
+ */
194
+ export declare function intentCheckedNothing(gate: GateOutcome): boolean;
180
195
  export interface TextOptions {
181
196
  /**
182
197
  * Print the full report even when the run is fully clean.
@@ -235,6 +235,14 @@ function enforcementNote(gate) {
235
235
  `${gate.exitCode ?? '?'}, and enforce is false for it in .guardrails.yaml, so the commit ` +
236
236
  'proceeds. Set enforce: true there to make it block.');
237
237
  }
238
+ // A gate that ran and checked nothing (an intent gate with no contract, a
239
+ // scanner with nothing to scan) found nothing because it looked at nothing,
240
+ // and "found nothing to block on" reads as a clean result (audit
241
+ // 2026-10-28, N5). The same predicate and words as the verdict's list.
242
+ if (gateCheckedNothing(gate)) {
243
+ return (' not enforced: enforce is false for this gate in .guardrails.yaml, and it checked ' +
244
+ `nothing here: ${checkedNothingWording(gate)}. This is not a clean result.`);
245
+ }
238
246
  return ' not enforced: enforce is false for this gate in .guardrails.yaml. It found nothing to block on here.';
239
247
  }
240
248
  /**
@@ -396,14 +404,23 @@ function gateSection(gate, verbose, refusedOnTerminal = false) {
396
404
  const facts = Object.entries(gate.run.details)
397
405
  .filter(([key, value]) =>
398
406
  // ignoredReported drives the line above rather than being a fact
399
- // 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.
400
409
  key !== 'ignoredReported' &&
410
+ key !== 'skipReason' &&
401
411
  (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') &&
402
412
  value !== '')
403
413
  .map(([key, value]) => `${key} ${String(value)}`);
404
414
  if (facts.length > 0) {
405
415
  lines.push(` ${facts.join(' ')}`);
406
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
+ }
407
424
  for (const diagnostic of gate.run.diagnostics) {
408
425
  lines.push(` note ${diagnostic.code}: ${diagnostic.message}`);
409
426
  }
@@ -1022,7 +1039,30 @@ function gateCheckedNothing(gate) {
1022
1039
  }
1023
1040
  return (gate.diagnostics.some((d) => d.code === 'conductor/nothing-to-scan') ||
1024
1041
  readNoPackages(gate) ||
1025
- (gate.role === 'intent' && gate.run.details.contractFound === false));
1042
+ intentCheckedNothing(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));
1026
1066
  }
1027
1067
  /** How the verdict sentence names a gate that ran and checked nothing. */
1028
1068
  function checkedNothingWording(gate) {
@@ -1356,7 +1396,16 @@ function summaryLine(result) {
1356
1396
  // decided there is none exactly where most readers stop reading. Grouped in
1357
1397
  // first-seen order so the sentence does not reorder itself between runs.
1358
1398
  const skippedByWording = new Map();
1359
- 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) {
1360
1409
  const lead = skipWording(gate.reason).summary;
1361
1410
  skippedByWording.set(lead, [
1362
1411
  ...(skippedByWording.get(lead) ?? []),
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
@@ -18,6 +18,17 @@ export interface VersionProbe {
18
18
  command: string;
19
19
  argv: string[];
20
20
  }
21
+ /** One args entry of a gate-named command that could name a path (`dataArgumentPaths`). */
22
+ export interface DataArgument {
23
+ /** Absolute, resolved against the repository root. */
24
+ path: string;
25
+ /** False for an option's value (`--x=v`, the word after `--x`, `-xv`): data the gate reads. */
26
+ positional: boolean;
27
+ /** The args entry as written, for the refusal message. */
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';
31
+ }
21
32
  export interface ResolvedBinary {
22
33
  /** What to spawn. */
23
34
  command: string;
@@ -46,8 +57,35 @@ export interface ResolvedBinary {
46
57
  * policy's args, never a candidate's built-in prefix (`scan`, `source`):
47
58
  * those are subcommands this package wrote, and a directory of the same
48
59
  * name in somebody's repository is not a program.
60
+ *
61
+ * When `command:` is the gate itself (commandIsGateProgram) only the args
62
+ * entries with a code extension are listed here (`codeArguments`); the
63
+ * rest of its args are its own argv, read as data, and land in
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).
49
67
  */
50
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[];
75
+ /**
76
+ * Every args entry that could name a path, when `command:` is the gate
77
+ * itself (`dataArgumentPaths`), in args order, by POSITION and never by
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).
81
+ *
82
+ * The pull-request check (refuseHeadControlledData) decides from the BASE
83
+ * tree what each one is: a file must be the base's blob, a directory given
84
+ * as an option's value must be the base's tree, and a positional directory
85
+ * is a scan target and is not compared (audit 2026-10-28, N1, and its
86
+ * review, B1 and N-a).
87
+ */
88
+ dataArguments: DataArgument[];
51
89
  source: ResolutionSource;
52
90
  /** The candidate name this matched, for the report's gate header. */
53
91
  candidate: string;
@@ -107,14 +145,22 @@ export declare function candidateNames(product: Product): string[];
107
145
  * Whether the policy's `command:` is itself the gate program, so its `args:`
108
146
  * are that gate's own argv rather than something an interpreter will load.
109
147
  *
110
- * True when the command's name is a candidate name (`vault-guard`,
111
- * `intent-guard.js`), and for a non-executable `.js` command, which this
112
- * package runs through its own Node with the script as the program. False
113
- * for anything else, an interpreter such as `node` or `python3` above all.
114
- * Only then are the product's subcommand words (`scan`, `source`) exempt
115
- * from being read as paths: an interpreter handed `scan` runs `scan.js` or
116
- * `scan/index.js`, so for it the word is a path like any other (audit
117
- * 2026-10-27 fix round, MB3).
148
+ * True only when the command's NAME is a candidate name (`vault-guard`,
149
+ * `intent-guard.js`, executable or not). False for anything else: an
150
+ * interpreter such as `node` or `python3`, a renamed gate binary, and any
151
+ * wrapper or dispatcher whose name is not a gate name, a non-executable
152
+ * `my-build.js` included. Only when true are the product's subcommand words
153
+ * (`scan`, `source`) exempt from being read as paths, and the args read as
154
+ * the gate's own data rather than as code (`dataArgumentPaths`): an
155
+ * interpreter handed `scan` runs `scan.js` or `scan/index.js`, so for it the
156
+ * word is a path like any other (audit 2026-10-27 fix round, MB3).
157
+ *
158
+ * The name is the only test. An earlier version also counted every
159
+ * non-executable `.js` command, because this package runs one through its own
160
+ * Node with the script as the program; but how a file is RUN says nothing
161
+ * about what it LOADS, and a dispatcher that requires the script its first
162
+ * argument names let a pull request rewrite `scan.js` and pass (audit
163
+ * 2026-10-28, MB1).
118
164
  */
119
165
  export declare function commandIsGateProgram(gate: GatePolicy): boolean;
120
166
  /**
@@ -134,11 +180,11 @@ export declare function commandIsGateProgram(gate: GatePolicy): boolean;
134
180
  * (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
135
181
  * after the first `=`, since that is where an interpreter takes a file to
136
182
  * load and a gate takes a file to read its rules from.
137
- * - When `exemptSubcommands` is true (the command is the gate program
138
- * itself, commandIsGateProgram), a bare word that is one of the product's
139
- * own subcommands (`scan`, `git`, `source`, `check`) names nothing, even
140
- * when a directory of that name exists. For an interpreter nothing is
141
- * exempt.
183
+ * - Nothing else is exempt, the product's own subcommand words (`scan`,
184
+ * `source`) included: this is only ever asked for a command that is not
185
+ * the gate itself (commandIsGateProgram), and an interpreter handed `scan`
186
+ * runs `scan.js` or `scan/index.js`. The gate itself has no code args;
187
+ * its args are data (dataArgumentPaths).
142
188
  * - The entry as written, when it exists as a file, a directory or a
143
189
  * symlink, without following the symlink, so the caller can refuse an
144
190
  * in-tree link on its own entry.
@@ -156,4 +202,40 @@ export declare function commandIsGateProgram(gate: GatePolicy): boolean;
156
202
  * string (`node -e`, `bash -c`), is not recognised as a path. The README says
157
203
  * so.
158
204
  */
159
- export declare function argumentCandidates(arg: string, repoRoot: string, product: Product, exemptSubcommands: boolean): string[];
205
+ export declare function argumentCandidates(arg: string, repoRoot: string): string[];
206
+ /**
207
+ * The args entries vetted as CODE: every entry when the command is not the
208
+ * gate itself, and only the code-extension values (`hasCodeExtension`) when
209
+ * it is, then the code-extension `options:` values (optionCodeArguments).
210
+ * Each goes through `argumentCandidates`, here and in the preview.
211
+ */
212
+ export declare function codeArguments(gate: GatePolicy): string[];
213
+ /**
214
+ * The args entries of a gate-named command that are its own DATA, when
215
+ * `command:` is the gate itself (commandIsGateProgram), in args order; empty
216
+ * for every other command (audit 2026-10-28, N1, and its review, B1, N-a,
217
+ * N-b, N-e).
218
+ *
219
+ * Every non-code entry (`gateArgEntries`, less the code-extension ones in
220
+ * `codeArguments`) is listed with its position, resolved against the
221
+ * repository root, WHETHER OR NOT the head's disk has it and whatever kind of
222
+ * thing the disk holds there: a head must not be able to delete a path or
223
+ * change it from a file to a directory to move it out of vetting. What each
224
+ * one is, and so which rule applies, is decided from the base tree by
225
+ * refuseHeadControlledData. No `<entry>.js` sibling is tried: that is how an
226
+ * interpreter resolves a name, and this command is not one.
227
+ *
228
+ * What this trusts is the NAME: a program named like a gate is taken to be
229
+ * that gate, except that a code-extension entry keeps the code rule. A
230
+ * wrapper given a gate's name that hands an extension-less entry to an
231
+ * interpreter is a wrapper, vetted no further than this (README,
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.
240
+ */
241
+ export declare function dataArgumentPaths(gate: GatePolicy, repoRoot: string): DataArgument[];