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