@vaultcompass/conductor 0.15.0 → 0.16.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, } 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
  /**
@@ -681,6 +681,15 @@ export function refuseHeadControlledBinary(repoRoot, trustBase, binary) {
681
681
  return refusal;
682
682
  }
683
683
  }
684
+ // A command that is the gate itself reads the rest of its args as data
685
+ // (audit 2026-10-28, N1, and its review): what each path is comes from the
686
+ // base tree, and a file or an option-value directory must be the base's.
687
+ for (const data of binary.dataArguments) {
688
+ const refusal = refuseHeadControlledData(repoRoot, trustBase, data);
689
+ if (refusal !== null) {
690
+ return refusal;
691
+ }
692
+ }
684
693
  return null;
685
694
  }
686
695
  /**
@@ -1310,10 +1319,14 @@ function previewRefusal(gate, repoRoot) {
1310
1319
  // own entry is in the tree, wherever it points (its directory is checked).
1311
1320
  // The candidate set is the primary run's (argumentCandidates): the entry and
1312
1321
  // 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);
1322
+ // tools/gate/ is refused here too. The entries are the primary run's code
1323
+ // arguments (codeArguments): every entry for a command that is not the gate
1324
+ // itself, and only the code-extension ones for one that is. The gate's
1325
+ // other args are data it reads (audit 2026-10-28, N1), and runGate's data
1326
+ // check (refuseHeadControlledData, through refuseHeadControlledBinary) runs
1327
+ // on every preview spawn, an option-value directory included (review B1).
1328
+ for (const arg of codeArguments(gate)) {
1329
+ const candidates = argumentCandidates(arg, repoRoot);
1317
1330
  if (candidates.some((named) => realPathInside(repoRoot, named) || realPathInside(repoRoot, path.dirname(named)))) {
1318
1331
  return {
1319
1332
  reason: 'gate-program-refused',
@@ -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
  /**
package/dist/resolve.d.ts CHANGED
@@ -18,6 +18,15 @@ 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
+ }
21
30
  export interface ResolvedBinary {
22
31
  /** What to spawn. */
23
32
  command: string;
@@ -46,8 +55,26 @@ export interface ResolvedBinary {
46
55
  * policy's args, never a candidate's built-in prefix (`scan`, `source`):
47
56
  * those are subcommands this package wrote, and a directory of the same
48
57
  * name in somebody's repository is not a program.
58
+ *
59
+ * When `command:` is the gate itself (commandIsGateProgram) only the args
60
+ * entries with a code extension are listed here (`codeArguments`); the
61
+ * rest of its args are its own argv, read as data, and land in
62
+ * `dataArguments` instead.
49
63
  */
50
64
  argumentPaths: string[];
65
+ /**
66
+ * Every args entry that could name a path, when `command:` is the gate
67
+ * 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.
70
+ *
71
+ * The pull-request check (refuseHeadControlledData) decides from the BASE
72
+ * tree what each one is: a file must be the base's blob, a directory given
73
+ * as an option's value must be the base's tree, and a positional directory
74
+ * is a scan target and is not compared (audit 2026-10-28, N1, and its
75
+ * review, B1 and N-a).
76
+ */
77
+ dataArguments: DataArgument[];
51
78
  source: ResolutionSource;
52
79
  /** The candidate name this matched, for the report's gate header. */
53
80
  candidate: string;
@@ -107,14 +134,22 @@ export declare function candidateNames(product: Product): string[];
107
134
  * Whether the policy's `command:` is itself the gate program, so its `args:`
108
135
  * are that gate's own argv rather than something an interpreter will load.
109
136
  *
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).
137
+ * True only when the command's NAME is a candidate name (`vault-guard`,
138
+ * `intent-guard.js`, executable or not). False for anything else: an
139
+ * interpreter such as `node` or `python3`, a renamed gate binary, and any
140
+ * wrapper or dispatcher whose name is not a gate name, a non-executable
141
+ * `my-build.js` included. Only when true are the product's subcommand words
142
+ * (`scan`, `source`) exempt from being read as paths, and the args read as
143
+ * the gate's own data rather than as code (`dataArgumentPaths`): an
144
+ * interpreter handed `scan` runs `scan.js` or `scan/index.js`, so for it the
145
+ * word is a path like any other (audit 2026-10-27 fix round, MB3).
146
+ *
147
+ * The name is the only test. An earlier version also counted every
148
+ * non-executable `.js` command, because this package runs one through its own
149
+ * Node with the script as the program; but how a file is RUN says nothing
150
+ * about what it LOADS, and a dispatcher that requires the script its first
151
+ * argument names let a pull request rewrite `scan.js` and pass (audit
152
+ * 2026-10-28, MB1).
118
153
  */
119
154
  export declare function commandIsGateProgram(gate: GatePolicy): boolean;
120
155
  /**
@@ -134,11 +169,11 @@ export declare function commandIsGateProgram(gate: GatePolicy): boolean;
134
169
  * (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
135
170
  * after the first `=`, since that is where an interpreter takes a file to
136
171
  * 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.
172
+ * - Nothing else is exempt, the product's own subcommand words (`scan`,
173
+ * `source`) included: this is only ever asked for a command that is not
174
+ * the gate itself (commandIsGateProgram), and an interpreter handed `scan`
175
+ * runs `scan.js` or `scan/index.js`. The gate itself has no code args;
176
+ * its args are data (dataArgumentPaths).
142
177
  * - The entry as written, when it exists as a file, a directory or a
143
178
  * symlink, without following the symlink, so the caller can refuse an
144
179
  * in-tree link on its own entry.
@@ -156,4 +191,32 @@ export declare function commandIsGateProgram(gate: GatePolicy): boolean;
156
191
  * string (`node -e`, `bash -c`), is not recognised as a path. The README says
157
192
  * so.
158
193
  */
159
- export declare function argumentCandidates(arg: string, repoRoot: string, product: Product, exemptSubcommands: boolean): string[];
194
+ export declare function argumentCandidates(arg: string, repoRoot: string): string[];
195
+ /**
196
+ * The args entries vetted as CODE: every entry when the command is not the
197
+ * gate itself, and only the code-extension values (`hasCodeExtension`) when
198
+ * it is. Each goes through `argumentCandidates`, here and in the preview.
199
+ */
200
+ export declare function codeArguments(gate: GatePolicy): string[];
201
+ /**
202
+ * The args entries of a gate-named command that are its own DATA, when
203
+ * `command:` is the gate itself (commandIsGateProgram), in args order; empty
204
+ * for every other command (audit 2026-10-28, N1, and its review, B1, N-a,
205
+ * N-b, N-e).
206
+ *
207
+ * Every non-code entry (`gateArgEntries`, less the code-extension ones in
208
+ * `codeArguments`) is listed with its position, resolved against the
209
+ * repository root, WHETHER OR NOT the head's disk has it and whatever kind of
210
+ * thing the disk holds there: a head must not be able to delete a path or
211
+ * change it from a file to a directory to move it out of vetting. What each
212
+ * one is, and so which rule applies, is decided from the base tree by
213
+ * refuseHeadControlledData. No `<entry>.js` sibling is tried: that is how an
214
+ * interpreter resolves a name, and this command is not one.
215
+ *
216
+ * What this trusts is the NAME: a program named like a gate is taken to be
217
+ * that gate, except that a code-extension entry keeps the code rule. A
218
+ * wrapper given a gate's name that hands an extension-less entry to an
219
+ * interpreter is a wrapper, vetted no further than this (README,
220
+ * pull-request trust boundary).
221
+ */
222
+ export declare function dataArgumentPaths(gate: GatePolicy, repoRoot: string): DataArgument[];
package/dist/resolve.js CHANGED
@@ -221,6 +221,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
221
221
  const candidateName = inferred?.name ?? baseName(gate.command);
222
222
  const candidate = inferred ?? table[0];
223
223
  const argumentPaths = argumentPathsOf(gate, repoRoot);
224
+ const dataArguments = dataArgumentPaths(gate, repoRoot);
224
225
  // A build directory holds plain .js files with a shebang but no
225
226
  // executable bit surprisingly often (a fresh tsc output, a file copied
226
227
  // out of a tarball). Running it through this same Node is exactly what
@@ -233,6 +234,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
233
234
  program: gate.command,
234
235
  argvPrefix: [gate.command, ...prefix],
235
236
  argumentPaths,
237
+ dataArguments,
236
238
  source: 'policy',
237
239
  candidate: candidateName,
238
240
  versionProbe: candidate.versionSafe && profileFor(gate.product).versionProbe !== null
@@ -253,6 +255,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
253
255
  program: gate.command,
254
256
  argvPrefix: prefix,
255
257
  argumentPaths,
258
+ dataArguments,
256
259
  source: 'policy',
257
260
  candidate: candidateName,
258
261
  versionProbe: viaScript ??
@@ -269,6 +272,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
269
272
  program: found.command,
270
273
  argvPrefix: [...candidate.prefix],
271
274
  argumentPaths: [],
275
+ dataArguments: [],
272
276
  source: found.source,
273
277
  candidate: candidate.name,
274
278
  versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
@@ -303,22 +307,27 @@ function existsAtAll(candidate) {
303
307
  * Whether the policy's `command:` is itself the gate program, so its `args:`
304
308
  * are that gate's own argv rather than something an interpreter will load.
305
309
  *
306
- * True when the command's name is a candidate name (`vault-guard`,
307
- * `intent-guard.js`), and for a non-executable `.js` command, which this
308
- * package runs through its own Node with the script as the program. False
309
- * for anything else, an interpreter such as `node` or `python3` above all.
310
- * Only then are the product's subcommand words (`scan`, `source`) exempt
311
- * from being read as paths: an interpreter handed `scan` runs `scan.js` or
312
- * `scan/index.js`, so for it the word is a path like any other (audit
313
- * 2026-10-27 fix round, MB3).
310
+ * True only when the command's NAME is a candidate name (`vault-guard`,
311
+ * `intent-guard.js`, executable or not). False for anything else: an
312
+ * interpreter such as `node` or `python3`, a renamed gate binary, and any
313
+ * wrapper or dispatcher whose name is not a gate name, a non-executable
314
+ * `my-build.js` included. Only when true are the product's subcommand words
315
+ * (`scan`, `source`) exempt from being read as paths, and the args read as
316
+ * the gate's own data rather than as code (`dataArgumentPaths`): an
317
+ * interpreter handed `scan` runs `scan.js` or `scan/index.js`, so for it the
318
+ * word is a path like any other (audit 2026-10-27 fix round, MB3).
319
+ *
320
+ * The name is the only test. An earlier version also counted every
321
+ * non-executable `.js` command, because this package runs one through its own
322
+ * Node with the script as the program; but how a file is RUN says nothing
323
+ * about what it LOADS, and a dispatcher that requires the script its first
324
+ * argument names let a pull request rewrite `scan.js` and pass (audit
325
+ * 2026-10-28, MB1).
314
326
  */
315
327
  export function commandIsGateProgram(gate) {
316
328
  if (gate.command === undefined) {
317
329
  return true;
318
330
  }
319
- if (!isExecutableFile(gate.command) && /\.(?:js|mjs|cjs)$/.test(gate.command)) {
320
- return true;
321
- }
322
331
  const name = baseName(gate.command);
323
332
  return CANDIDATES[gate.product].some((candidate) => candidate.name === name);
324
333
  }
@@ -339,11 +348,11 @@ export function commandIsGateProgram(gate) {
339
348
  * (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
340
349
  * after the first `=`, since that is where an interpreter takes a file to
341
350
  * load and a gate takes a file to read its rules from.
342
- * - When `exemptSubcommands` is true (the command is the gate program
343
- * itself, commandIsGateProgram), a bare word that is one of the product's
344
- * own subcommands (`scan`, `git`, `source`, `check`) names nothing, even
345
- * when a directory of that name exists. For an interpreter nothing is
346
- * exempt.
351
+ * - Nothing else is exempt, the product's own subcommand words (`scan`,
352
+ * `source`) included: this is only ever asked for a command that is not
353
+ * the gate itself (commandIsGateProgram), and an interpreter handed `scan`
354
+ * runs `scan.js` or `scan/index.js`. The gate itself has no code args;
355
+ * its args are data (dataArgumentPaths).
347
356
  * - The entry as written, when it exists as a file, a directory or a
348
357
  * symlink, without following the symlink, so the caller can refuse an
349
358
  * in-tree link on its own entry.
@@ -361,7 +370,7 @@ export function commandIsGateProgram(gate) {
361
370
  * string (`node -e`, `bash -c`), is not recognised as a path. The README says
362
371
  * so.
363
372
  */
364
- export function argumentCandidates(arg, repoRoot, product, exemptSubcommands) {
373
+ export function argumentCandidates(arg, repoRoot) {
365
374
  let value = arg;
366
375
  if (arg.startsWith('-')) {
367
376
  const equals = arg.indexOf('=');
@@ -370,19 +379,141 @@ export function argumentCandidates(arg, repoRoot, product, exemptSubcommands) {
370
379
  }
371
380
  value = arg.slice(equals + 1);
372
381
  }
373
- else if (exemptSubcommands && CANDIDATES[product].some((candidate) => candidate.prefix.includes(arg))) {
374
- return [];
375
- }
376
382
  if (value === '') {
377
383
  return [];
378
384
  }
379
385
  const absolute = path.resolve(repoRoot, value);
380
386
  return [absolute, ...LOADABLE_EXTENSIONS.map((extension) => absolute + extension)].filter(existsAtAll);
381
387
  }
382
- /** `argumentCandidates` for every entry of a policy's `args:`, flattened. */
388
+ /**
389
+ * Extensions that mark an args entry as CODE whatever the command is named
390
+ * (review 2026-10-28, N-e). None of the five gates reads such a file as data,
391
+ * so a gate-named command losing the code rule for them buys nothing, while a
392
+ * wrapper carrying a gate's name that hands `tools/run.js` to an interpreter
393
+ * would otherwise be vetted by that file's bytes alone, weaker than v0.15.0.
394
+ */
395
+ const CODE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.node', '.ts', '.mts', '.cts', '.py', '.sh', '.bash', '.rb', '.pl'];
396
+ function hasCodeExtension(value) {
397
+ return CODE_EXTENSIONS.some((extension) => value.endsWith(extension));
398
+ }
399
+ /**
400
+ * A gate-named command's args entries, read by POSITION as that gate's own
401
+ * argv (review 2026-10-28, B1 and N-b):
402
+ *
403
+ * - `--name=value` and `-x=value`: the value, an option value;
404
+ * - `--name` or `-x` with no `=`: the NEXT entry is its value, unless that
405
+ * entry is itself an option. Which options take a value is the gate's
406
+ * business and not known here, so a word after any such option is read
407
+ * as one; that is the fail-closed direction (a positional written after a
408
+ * flag is vetted as data, and the refusal says to write it first);
409
+ * - `-xvalue`, a short option joined to its value (pflag shorthand): the
410
+ * rest of the word, an option value. Bundled flags (`-rv`) read the same
411
+ * way name nothing on disk, so they cost one lookup and refuse nothing;
412
+ * - a bare word that is one of the product's subcommands: nothing;
413
+ * - any other word: a positional.
414
+ */
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) {
441
+ const entries = [];
442
+ let pendingOption = false;
443
+ for (const arg of gate.args ?? []) {
444
+ if (arg.startsWith('-') && arg !== '-') {
445
+ pendingOption = false;
446
+ const equals = arg.indexOf('=');
447
+ if (equals >= 0) {
448
+ entries.push({ value: arg.slice(equals + 1), positional: false, entry: arg });
449
+ }
450
+ else if (!arg.startsWith('--') && arg.length > 2) {
451
+ entries.push({ value: arg.slice(2), positional: false, entry: arg });
452
+ }
453
+ else {
454
+ // A flag the gate's own help says takes no value leaves the next word
455
+ // a positional (NO_VALUE_FLAGS); any other flag claims it.
456
+ pendingOption = !NO_VALUE_FLAGS[gate.product].includes(arg);
457
+ }
458
+ continue;
459
+ }
460
+ if (pendingOption) {
461
+ pendingOption = false;
462
+ entries.push({ value: arg, positional: false, entry: arg });
463
+ continue;
464
+ }
465
+ if (CANDIDATES[gate.product].some((candidate) => candidate.prefix.includes(arg))) {
466
+ continue;
467
+ }
468
+ entries.push({ value: arg, positional: true, entry: arg });
469
+ }
470
+ return entries.filter((each) => each.value !== '');
471
+ }
472
+ /**
473
+ * The args entries vetted as CODE: every entry when the command is not the
474
+ * gate itself, and only the code-extension values (`hasCodeExtension`) when
475
+ * it is. Each goes through `argumentCandidates`, here and in the preview.
476
+ */
477
+ 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);
484
+ }
485
+ /** `argumentCandidates` for every code argument (`codeArguments`), flattened. */
383
486
  function argumentPathsOf(gate, repoRoot) {
384
- const exempt = commandIsGateProgram(gate);
385
- return (gate.args ?? []).flatMap((arg) => argumentCandidates(arg, repoRoot, gate.product, exempt));
487
+ return codeArguments(gate).flatMap((arg) => argumentCandidates(arg, repoRoot));
488
+ }
489
+ /**
490
+ * The args entries of a gate-named command that are its own DATA, when
491
+ * `command:` is the gate itself (commandIsGateProgram), in args order; empty
492
+ * for every other command (audit 2026-10-28, N1, and its review, B1, N-a,
493
+ * N-b, N-e).
494
+ *
495
+ * Every non-code entry (`gateArgEntries`, less the code-extension ones in
496
+ * `codeArguments`) is listed with its position, resolved against the
497
+ * repository root, WHETHER OR NOT the head's disk has it and whatever kind of
498
+ * thing the disk holds there: a head must not be able to delete a path or
499
+ * change it from a file to a directory to move it out of vetting. What each
500
+ * one is, and so which rule applies, is decided from the base tree by
501
+ * refuseHeadControlledData. No `<entry>.js` sibling is tried: that is how an
502
+ * interpreter resolves a name, and this command is not one.
503
+ *
504
+ * What this trusts is the NAME: a program named like a gate is taken to be
505
+ * that gate, except that a code-extension entry keeps the code rule. A
506
+ * wrapper given a gate's name that hands an extension-less entry to an
507
+ * interpreter is a wrapper, vetted no further than this (README,
508
+ * pull-request trust boundary).
509
+ */
510
+ export function dataArgumentPaths(gate, repoRoot) {
511
+ if (gate.command === undefined || !commandIsGateProgram(gate)) {
512
+ return [];
513
+ }
514
+ return gateArgEntries(gate)
515
+ .filter((each) => !hasCodeExtension(each.value))
516
+ .map((each) => ({ path: path.resolve(repoRoot, each.value), positional: each.positional, entry: each.entry }));
386
517
  }
387
518
  /**
388
519
  * The version probe for a policy `command:` that is not itself a gate name,
@@ -418,7 +549,7 @@ function scriptVersionProbe(gate, repoRoot) {
418
549
  // Only the FIRST non-option entry can be the script. A later file is the
419
550
  // script's own argument (`my-build check rules.json`), and a probe that
420
551
  // carried the subcommand before it would make the gate do work.
421
- return argumentCandidates(arg, repoRoot, gate.product, false).length > 0
552
+ return argumentCandidates(arg, repoRoot).length > 0
422
553
  ? { command: gate.command, argv: [...gate.args.slice(0, index + 1), ...spec.argv] }
423
554
  : null;
424
555
  }
@@ -323,7 +323,9 @@ export declare function treeEntryAt(repoRoot: string, ref: string, relativePath:
323
323
  * Vetting the target is what catches a link whose own path is outside the
324
324
  * tree pointing into it; it never decides the in-repo case.
325
325
  */
326
- export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string): string | null;
326
+ export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string,
327
+ /** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
328
+ fromArgs?: boolean): string | null;
327
329
  /**
328
330
  * Whether a gate's reported version is at least `minimum`.
329
331
  *
@@ -370,3 +372,46 @@ export declare function atLeastVersion(version: string | null, minimum: string):
370
372
  * vetted as a link.
371
373
  */
372
374
  export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string): string | null;
375
+ /**
376
+ * Why a path a gate's own `args:` name cannot be trusted on a pull-request
377
+ * run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
378
+ *
379
+ * Asked only when `command:` is the gate itself (dataArgumentPaths in
380
+ * src/resolve.ts), whose args are its own argv: a rules file such as
381
+ * `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
382
+ * `--corpus-dir`, is read as data, not loaded as code. Its contents still
383
+ * decide what the gate reports, so a pull request that rewrote them would
384
+ * choose the rules that judge it; but nothing beside a file runs, so a
385
+ * file's directory is not compared and a file at the repository root is
386
+ * fine.
387
+ *
388
+ * WHAT THE PATH IS COMES FROM THE BASE TREE, never from the head's disk, so a
389
+ * head cannot delete a path or turn a file into a directory to change which
390
+ * rule applies:
391
+ *
392
+ * - Outside the working tree, by its own spelling and by its realpath:
393
+ * accepted, as for a program.
394
+ * - The repository root: accepted as a POSITIONAL entry (`scan .`, the
395
+ * repository the gate is handed anyway, which is the thing being judged
396
+ * and cannot be the base's on any pull request), refused as an OPTION
397
+ * VALUE (`--corpus-dir=.` would make the whole head tree the rules).
398
+ * - A tree at the base: a positional entry is a scan target and is not
399
+ * compared (the head's version of it is what the gate is there to judge).
400
+ * An option value is data: the head must hold a tree with the same tree
401
+ * object id, or it is refused.
402
+ * - A blob at the base: a tracked regular file at both refs with the same
403
+ * blob, whatever its position. An in-tree link is refused on its own entry
404
+ * (a link entry), as everywhere else, because what it points at is the
405
+ * head's choice. A head that deleted it or replaced it is refused.
406
+ * - Absent at the base: accepted only if the head has nothing there either,
407
+ * tracked or on disk (a word that is not a path, `--format=json`);
408
+ * otherwise it is a path this pull request chose, and refused.
409
+ *
410
+ * Only whether something exists on disk at a path the base does not track is
411
+ * read from the working tree; every other answer is a `git ls-tree` listing.
412
+ */
413
+ export declare function refuseHeadControlledData(repoRoot: string, trustBase: string, data: {
414
+ path: string;
415
+ positional: boolean;
416
+ entry?: string;
417
+ }): string | null;