@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.
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,8 @@ 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);
226
+ const dataArguments = dataArgumentPaths(gate, repoRoot);
224
227
  // A build directory holds plain .js files with a shebang but no
225
228
  // executable bit surprisingly often (a fresh tsc output, a file copied
226
229
  // out of a tarball). Running it through this same Node is exactly what
@@ -233,6 +236,8 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
233
236
  program: gate.command,
234
237
  argvPrefix: [gate.command, ...prefix],
235
238
  argumentPaths,
239
+ optionArgumentPaths,
240
+ dataArguments,
236
241
  source: 'policy',
237
242
  candidate: candidateName,
238
243
  versionProbe: candidate.versionSafe && profileFor(gate.product).versionProbe !== null
@@ -253,6 +258,8 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
253
258
  program: gate.command,
254
259
  argvPrefix: prefix,
255
260
  argumentPaths,
261
+ optionArgumentPaths,
262
+ dataArguments,
256
263
  source: 'policy',
257
264
  candidate: candidateName,
258
265
  versionProbe: viaScript ??
@@ -268,7 +275,11 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
268
275
  command: found.command,
269
276
  program: found.command,
270
277
  argvPrefix: [...candidate.prefix],
271
- argumentPaths: [],
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),
272
283
  source: found.source,
273
284
  candidate: candidate.name,
274
285
  versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
@@ -303,22 +314,27 @@ function existsAtAll(candidate) {
303
314
  * Whether the policy's `command:` is itself the gate program, so its `args:`
304
315
  * are that gate's own argv rather than something an interpreter will load.
305
316
  *
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).
317
+ * True only when the command's NAME is a candidate name (`vault-guard`,
318
+ * `intent-guard.js`, executable or not). False for anything else: an
319
+ * interpreter such as `node` or `python3`, a renamed gate binary, and any
320
+ * wrapper or dispatcher whose name is not a gate name, a non-executable
321
+ * `my-build.js` included. Only when true are the product's subcommand words
322
+ * (`scan`, `source`) exempt from being read as paths, and the args read as
323
+ * the gate's own data rather than as code (`dataArgumentPaths`): an
324
+ * interpreter handed `scan` runs `scan.js` or `scan/index.js`, so for it the
325
+ * word is a path like any other (audit 2026-10-27 fix round, MB3).
326
+ *
327
+ * The name is the only test. An earlier version also counted every
328
+ * non-executable `.js` command, because this package runs one through its own
329
+ * Node with the script as the program; but how a file is RUN says nothing
330
+ * about what it LOADS, and a dispatcher that requires the script its first
331
+ * argument names let a pull request rewrite `scan.js` and pass (audit
332
+ * 2026-10-28, MB1).
314
333
  */
315
334
  export function commandIsGateProgram(gate) {
316
335
  if (gate.command === undefined) {
317
336
  return true;
318
337
  }
319
- if (!isExecutableFile(gate.command) && /\.(?:js|mjs|cjs)$/.test(gate.command)) {
320
- return true;
321
- }
322
338
  const name = baseName(gate.command);
323
339
  return CANDIDATES[gate.product].some((candidate) => candidate.name === name);
324
340
  }
@@ -339,11 +355,11 @@ export function commandIsGateProgram(gate) {
339
355
  * (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
340
356
  * after the first `=`, since that is where an interpreter takes a file to
341
357
  * 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.
358
+ * - Nothing else is exempt, the product's own subcommand words (`scan`,
359
+ * `source`) included: this is only ever asked for a command that is not
360
+ * the gate itself (commandIsGateProgram), and an interpreter handed `scan`
361
+ * runs `scan.js` or `scan/index.js`. The gate itself has no code args;
362
+ * its args are data (dataArgumentPaths).
347
363
  * - The entry as written, when it exists as a file, a directory or a
348
364
  * symlink, without following the symlink, so the caller can refuse an
349
365
  * in-tree link on its own entry.
@@ -361,7 +377,7 @@ export function commandIsGateProgram(gate) {
361
377
  * string (`node -e`, `bash -c`), is not recognised as a path. The README says
362
378
  * so.
363
379
  */
364
- export function argumentCandidates(arg, repoRoot, product, exemptSubcommands) {
380
+ export function argumentCandidates(arg, repoRoot) {
365
381
  let value = arg;
366
382
  if (arg.startsWith('-')) {
367
383
  const equals = arg.indexOf('=');
@@ -370,19 +386,155 @@ export function argumentCandidates(arg, repoRoot, product, exemptSubcommands) {
370
386
  }
371
387
  value = arg.slice(equals + 1);
372
388
  }
373
- else if (exemptSubcommands && CANDIDATES[product].some((candidate) => candidate.prefix.includes(arg))) {
374
- return [];
375
- }
376
389
  if (value === '') {
377
390
  return [];
378
391
  }
379
392
  const absolute = path.resolve(repoRoot, value);
380
393
  return [absolute, ...LOADABLE_EXTENSIONS.map((extension) => absolute + extension)].filter(existsAtAll);
381
394
  }
382
- /** `argumentCandidates` for every entry of a policy's `args:`, flattened. */
395
+ /**
396
+ * Extensions that mark an args entry as CODE whatever the command is named
397
+ * (review 2026-10-28, N-e). None of the five gates reads such a file as data,
398
+ * so a gate-named command losing the code rule for them buys nothing, while a
399
+ * wrapper carrying a gate's name that hands `tools/run.js` to an interpreter
400
+ * would otherwise be vetted by that file's bytes alone, weaker than v0.15.0.
401
+ */
402
+ const CODE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.node', '.ts', '.mts', '.cts', '.py', '.sh', '.bash', '.rb', '.pl'];
403
+ function hasCodeExtension(value) {
404
+ return CODE_EXTENSIONS.some((extension) => value.endsWith(extension));
405
+ }
406
+ /**
407
+ * A gate-named command's args entries, read by POSITION as that gate's own
408
+ * argv (review 2026-10-28, B1 and N-b):
409
+ *
410
+ * - `--name=value` and `-x=value`: the value, an option value;
411
+ * - `--name` or `-x` with no `=`: the NEXT entry is its value, unless that
412
+ * entry is itself an option. Which options take a value is the gate's
413
+ * business and not known here, so a word after any such option is read
414
+ * as one; that is the fail-closed direction (a positional written after a
415
+ * flag is vetted as data, and the refusal says to write it first);
416
+ * - `-xvalue`, a short option joined to its value (pflag shorthand): the
417
+ * rest of the word, an option value. Bundled flags (`-rv`) read the same
418
+ * way name nothing on disk, so they cost one lookup and refuse nothing;
419
+ * - a bare word that is one of the product's subcommands: nothing;
420
+ * - any other word: a positional.
421
+ */
422
+ function gateArgEntries(product, words) {
423
+ const entries = [];
424
+ let pendingOption = false;
425
+ for (const arg of words) {
426
+ if (arg.startsWith('-') && arg !== '-') {
427
+ pendingOption = false;
428
+ const equals = arg.indexOf('=');
429
+ if (equals >= 0) {
430
+ entries.push({ value: arg.slice(equals + 1), positional: false, entry: arg });
431
+ }
432
+ else if (!arg.startsWith('--') && arg.length > 2) {
433
+ entries.push({ value: arg.slice(2), positional: false, entry: arg });
434
+ }
435
+ else {
436
+ // A flag the gate's own help says takes no value leaves the next word
437
+ // a positional (NO_VALUE_FLAGS); any other flag claims it.
438
+ pendingOption = !NO_VALUE_FLAGS[product].includes(arg);
439
+ }
440
+ continue;
441
+ }
442
+ if (pendingOption) {
443
+ pendingOption = false;
444
+ entries.push({ value: arg, positional: false, entry: arg });
445
+ continue;
446
+ }
447
+ if (CANDIDATES[product].some((candidate) => candidate.prefix.includes(arg))) {
448
+ continue;
449
+ }
450
+ entries.push({ value: arg, positional: true, entry: arg });
451
+ }
452
+ return entries.filter((each) => each.value !== '');
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
+ }
473
+ /**
474
+ * The args entries vetted as CODE: every entry when the command is not the
475
+ * gate itself, and only the code-extension values (`hasCodeExtension`) when
476
+ * it is, then the code-extension `options:` values (optionCodeArguments).
477
+ * Each goes through `argumentCandidates`, here and in the preview.
478
+ */
479
+ export function codeArguments(gate) {
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)];
486
+ }
487
+ /** `argumentCandidates` for every code argument (`codeArguments`), flattened. */
383
488
  function argumentPathsOf(gate, repoRoot) {
384
- const exempt = commandIsGateProgram(gate);
385
- return (gate.args ?? []).flatMap((arg) => argumentCandidates(arg, repoRoot, gate.product, exempt));
489
+ return codeArguments(gate).flatMap((arg) => argumentCandidates(arg, repoRoot));
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
+ }
495
+ /**
496
+ * The args entries of a gate-named command that are its own DATA, when
497
+ * `command:` is the gate itself (commandIsGateProgram), in args order; empty
498
+ * for every other command (audit 2026-10-28, N1, and its review, B1, N-a,
499
+ * N-b, N-e).
500
+ *
501
+ * Every non-code entry (`gateArgEntries`, less the code-extension ones in
502
+ * `codeArguments`) is listed with its position, resolved against the
503
+ * repository root, WHETHER OR NOT the head's disk has it and whatever kind of
504
+ * thing the disk holds there: a head must not be able to delete a path or
505
+ * change it from a file to a directory to move it out of vetting. What each
506
+ * one is, and so which rule applies, is decided from the base tree by
507
+ * refuseHeadControlledData. No `<entry>.js` sibling is tried: that is how an
508
+ * interpreter resolves a name, and this command is not one.
509
+ *
510
+ * What this trusts is the NAME: a program named like a gate is taken to be
511
+ * that gate, except that a code-extension entry keeps the code rule. A
512
+ * wrapper given a gate's name that hands an extension-less entry to an
513
+ * interpreter is a wrapper, vetted no further than this (README,
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.
522
+ */
523
+ export function dataArgumentPaths(gate, repoRoot) {
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)
530
+ .filter((each) => !hasCodeExtension(each.value))
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];
386
538
  }
387
539
  /**
388
540
  * The version probe for a policy `command:` that is not itself a gate name,
@@ -418,7 +570,7 @@ function scriptVersionProbe(gate, repoRoot) {
418
570
  // Only the FIRST non-option entry can be the script. A later file is the
419
571
  // script's own argument (`my-build check rules.json`), and a probe that
420
572
  // carried the subcommand before it would make the gate do work.
421
- return argumentCandidates(arg, repoRoot, gate.product, false).length > 0
573
+ return argumentCandidates(arg, repoRoot).length > 0
422
574
  ? { command: gate.command, argv: [...gate.args.slice(0, index + 1), ...spec.argv] }
423
575
  : null;
424
576
  }
@@ -253,6 +253,12 @@ export type TreeEntry = {
253
253
  * decided outside the tree, so it is an error, never absent.
254
254
  */
255
255
  export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): TreeEntry;
256
+ /**
257
+ * Whether `candidate`, as written, names the working tree or something in it
258
+ * (writtenRelative). For the preview's outright refusals, so a base path
259
+ * written inside the tree is refused there even when a link on it points out.
260
+ */
261
+ export declare function writtenInsideWorkingTree(repoRoot: string, candidate: string): boolean;
256
262
  /**
257
263
  * Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
258
264
  *
@@ -322,8 +328,23 @@ export declare function treeEntryAt(repoRoot: string, ref: string, relativePath:
322
328
  * or its tree entry is a link rather than a regular file, and either refuses.
323
329
  * Vetting the target is what catches a link whose own path is outside the
324
330
  * tree pointing into it; it never decides the in-repo case.
331
+ *
332
+ * AND THE PATH AS WRITTEN, for this rule and for both args rules below
333
+ * (audit 2026-11-01, MB2). Both spellings above resolve the directories on
334
+ * the path through the head's disk, so a head that replaced `tools/` with a
335
+ * link to a base-tracked `stub/` had `tools/vault-guard` judged as
336
+ * `stub/vault-guard`, which the base approved. So the path is also judged
337
+ * exactly as written inside the tree (writtenRelative): refused when HEAD's
338
+ * tree holds any directory on it as a link (linkOnWrittenPathAtHead), and
339
+ * the written path is one more candidate, judged by its own entries at both
340
+ * refs like the others. A link the base already had there is refused too:
341
+ * what the gate is handed through it is still decided by the head tree.
325
342
  */
326
- export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string): string | null;
343
+ export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string,
344
+ /** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
345
+ fromArgs?: boolean,
346
+ /** Which policy list an argument came from, for its refusals: `args:`, or `options:` for a code-extension option value. */
347
+ list?: string): string | null;
327
348
  /**
328
349
  * Whether a gate's reported version is at least `minimum`.
329
350
  *
@@ -369,4 +390,59 @@ export declare function atLeastVersion(version: string | null, minimum: string):
369
390
  * read from disk, and a link is never followed for that, so a link is always
370
391
  * vetted as a link.
371
392
  */
372
- export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string): string | null;
393
+ export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string,
394
+ /** Which policy list the path came from, for the refusals: `args:`, or `options:` for a code-extension option value. */
395
+ list?: string): string | null;
396
+ /**
397
+ * Why a path a gate's own `args:` name cannot be trusted on a pull-request
398
+ * run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
399
+ *
400
+ * Asked for the args of a `command:` that is the gate itself, and for the
401
+ * `options:` values of every gate (dataArgumentPaths in src/resolve.ts),
402
+ * since both are the gate's own argv: a rules file such as
403
+ * `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
404
+ * `--corpus-dir`, is read as data, not loaded as code. Its contents still
405
+ * decide what the gate reports, so a pull request that rewrote them would
406
+ * choose the rules that judge it; but nothing beside a file runs, so a
407
+ * file's directory is not compared and a file at the repository root is
408
+ * fine.
409
+ *
410
+ * WHAT THE PATH IS COMES FROM THE BASE TREE, never from the head's disk, so a
411
+ * head cannot delete a path or turn a file into a directory to change which
412
+ * rule applies:
413
+ *
414
+ * - Outside the working tree, by its own spelling and by its realpath:
415
+ * accepted, as for a program.
416
+ * - The repository root: accepted as a POSITIONAL entry (`scan .`, the
417
+ * repository the gate is handed anyway, which is the thing being judged
418
+ * and cannot be the base's on any pull request), refused as an OPTION
419
+ * VALUE (`--corpus-dir=.` would make the whole head tree the rules).
420
+ * - A tree at the base: a positional entry is a scan target and is not
421
+ * compared (the head's version of it is what the gate is there to judge).
422
+ * An option value is data: the head must hold a tree with the same tree
423
+ * object id, or it is refused.
424
+ * - A blob at the base: a tracked regular file at both refs with the same
425
+ * blob, whatever its position. An in-tree link is refused on its own entry
426
+ * (a link entry), as everywhere else, because what it points at is the
427
+ * head's choice. A head that deleted it or replaced it is refused.
428
+ * - Absent at the base: accepted only if the head has nothing there either,
429
+ * tracked or on disk (a word that is not a path, `--format=json`);
430
+ * otherwise it is a path this pull request chose, and refused.
431
+ * - AS WRITTEN as well as resolved (audit 2026-11-01, MB2): a directory on
432
+ * the written path that HEAD's tree holds as a link is refused, the
433
+ * written path is judged by the rules above like the resolved ones, and a
434
+ * positional scan target the base tracks as a directory is refused when
435
+ * HEAD holds it as a link, since that one is otherwise not compared.
436
+ * - The same for an `options:` value (audit 2026-11-01, MB1): it is
437
+ * rendered into the gate's argv and read the same way (dataArgumentPaths),
438
+ * and `from: 'options'` only changes which list the refusal names.
439
+ *
440
+ * Only whether something exists on disk at a path the base does not track is
441
+ * read from the working tree; every other answer is a `git ls-tree` listing.
442
+ */
443
+ export declare function refuseHeadControlledData(repoRoot: string, trustBase: string, data: {
444
+ path: string;
445
+ positional: boolean;
446
+ entry?: string;
447
+ from?: 'options';
448
+ }): string | null;