@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/README.md +154 -1186
- package/dist/gate-runner.js +31 -11
- package/dist/normalize.js +42 -2
- package/dist/output-sarif.js +22 -1
- package/dist/output-text.d.ts +15 -0
- package/dist/output-text.js +52 -3
- package/dist/policy.d.ts +21 -1
- package/dist/policy.js +58 -2
- package/dist/resolve.d.ts +96 -14
- package/dist/resolve.js +177 -25
- package/dist/trust-base.d.ts +78 -2
- package/dist/trust-base.js +413 -11
- package/package.json +1 -1
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
|
-
|
|
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
|
|
307
|
-
* `intent-guard.js
|
|
308
|
-
*
|
|
309
|
-
*
|
|
310
|
-
* Only
|
|
311
|
-
* from being read as paths
|
|
312
|
-
*
|
|
313
|
-
*
|
|
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
|
-
* -
|
|
343
|
-
*
|
|
344
|
-
*
|
|
345
|
-
*
|
|
346
|
-
*
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
|
|
385
|
-
|
|
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
|
|
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
|
}
|
package/dist/trust-base.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
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;
|