@vaultcompass/conductor 0.11.0 → 0.12.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 CHANGED
@@ -166,7 +166,7 @@ required.
166
166
  A commit with a staged credential in it prints the full report and exits 1:
167
167
 
168
168
  ```
169
- conductor 0.11.0
169
+ conductor 0.12.0
170
170
  verdict-token: blocked (1)
171
171
  conductor run: 2 gate(s), 1 finding(s)
172
172
 
@@ -359,11 +359,17 @@ gates:
359
359
  secrets-history:
360
360
  product: gitleaks
361
361
  enabled: true
362
+ # Enabled because gitleaks was found on the machine that ran init. CI must
363
+ # install gitleaks itself (conductor does not); without it this gate
364
+ # reports conductor/gate-missing and the run exits 2.
362
365
  stage: ci
363
366
  enforce: true
364
367
  vulnerabilities:
365
368
  product: osv-scanner
366
369
  enabled: true
370
+ # Enabled because osv-scanner was found on the machine that ran init. CI must
371
+ # install osv-scanner itself (conductor does not); without it this gate
372
+ # reports conductor/gate-missing and the run exits 2.
367
373
  stage: ci
368
374
  enforce: true
369
375
  present-on-base: report
@@ -1093,6 +1099,29 @@ gate (gitleaks) enabled, because conductor hands it `git log --diff-merges`,
1093
1099
  which arrived in git 2.31. Only that gate checks: an older git makes it
1094
1100
  could-not-run, naming the version, and the other gates run.
1095
1101
 
1102
+ ### Trying pull-request mode locally
1103
+
1104
+ To see roughly what CI would say about a branch, check it out and name the
1105
+ base as the trust base:
1106
+
1107
+ ```
1108
+ conductor run --trust-base refs/remotes/origin/main --verbose
1109
+ ```
1110
+
1111
+ `--trust-base` takes any ref git resolves in your clone, so use a clone with
1112
+ the base branch present (the CI recipes use `fetch-depth: 0` for the same
1113
+ reason). With no `GITHUB_BASE_REF` set, as on a laptop, the change set for the
1114
+ intent gate is measured from the trust base, so `--base` is optional; add
1115
+ `--base <ref>` to measure from a different ref. Add `--stage ci` to run at
1116
+ the stage the Action runs at.
1117
+
1118
+ The gotcha is the same locally as in CI: the policy and the other control
1119
+ files are read from the base ref, not from your working tree. A local edit to
1120
+ `.guardrails.yaml` has no effect on a `--trust-base` run until the change is
1121
+ on the base; it shows up as a proposal line in the report instead. To preview
1122
+ a policy edit, run `conductor run` without `--trust-base`, as in "Adopting
1123
+ conductor" above.
1124
+
1096
1125
  ## Intent at a pull request
1097
1126
 
1098
1127
  The intent gate is the only one of the five with any ceremony: its native
@@ -1288,7 +1317,11 @@ runs `npm install -g --ignore-scripts` under the runner temp, never into the
1288
1317
  workspace, and prepends that bin directory to `PATH`, so the run step invokes
1289
1318
  `conductor` off `PATH` and each gate resolves by name the same way. The install
1290
1319
  is **unconditional**, on push and `pull_request` alike, so there is one code
1291
- path rather than one that matters and one that nobody exercises.
1320
+ path rather than one that matters and one that nobody exercises. On a push
1321
+ run, though, a repository's own devDependency on a gate in
1322
+ `node_modules/.bin` outranks that install and shadows the action's pin; when
1323
+ its version differs from the pin, conductor now warns in the job log, as a
1324
+ `::warning::` annotation and in the step summary, and still runs it.
1292
1325
 
1293
1326
  **On a pull request those four inputs may not pin backward.** The shape check
1294
1327
  asks whether an input is an exact version; it says nothing about which one, and
@@ -1378,7 +1411,7 @@ request being judged, and the version-pin protection described above
1378
1411
  "protects nothing" against a tree that controls its own judge (the
1379
1412
  validate step's own comment in `action.yml` says so in those words). A tag
1380
1413
  moves when someone pushes it. Name this action by owner and the full commit
1381
- SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.11.0.
1414
+ SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.12.0.
1382
1415
 
1383
1416
  ```yaml
1384
1417
  name: guardrails
@@ -1400,7 +1433,7 @@ jobs:
1400
1433
  with:
1401
1434
  node-version: '22.11.0'
1402
1435
  - id: conductor
1403
- uses: vaultcompasshq/conductor@v0.11.0
1436
+ uses: vaultcompasshq/conductor@v0.12.0
1404
1437
  with:
1405
1438
  output: conductor.sarif
1406
1439
  - uses: github/codeql-action/upload-sarif@v3
@@ -1475,7 +1508,7 @@ jobs:
1475
1508
  # installs those itself, globally. Leave conductor-version unset so the
1476
1509
  # umbrella is the default in the pinned action.yml.
1477
1510
  - id: conductor
1478
- uses: vaultcompasshq/conductor@v0.11.0
1511
+ uses: vaultcompasshq/conductor@v0.12.0
1479
1512
  with:
1480
1513
  output: conductor.sarif
1481
1514
  # Exact versions, never a range and never "latest". These three
@@ -1486,9 +1519,9 @@ jobs:
1486
1519
  # request of their own. On a pull request the action refuses a pin
1487
1520
  # below what the pinned action.yml ships, and the three lines can
1488
1521
  # be left out entirely to take that action's own versions.
1489
- dep-guard-version: 0.14.0
1490
- vault-guard-version: 1.11.0
1491
- intent-guard-version: 1.10.0
1522
+ dep-guard-version: 0.15.0
1523
+ vault-guard-version: 1.12.1
1524
+ intent-guard-version: 1.10.1
1492
1525
  - uses: github/codeql-action/upload-sarif@v3
1493
1526
  # Always: the log is most worth having on the run that failed.
1494
1527
  if: always()
@@ -1681,7 +1714,7 @@ jobs:
1681
1714
  node-version: '22.11.0'
1682
1715
  - id: conductor
1683
1716
  timeout-minutes: 5
1684
- uses: vaultcompasshq/conductor@v0.11.0
1717
+ uses: vaultcompasshq/conductor@v0.12.0
1685
1718
  with:
1686
1719
  pr-comment: true
1687
1720
  advisory: true
@@ -1817,7 +1850,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1817
1850
  # the pull request runs before the action in this job: no install, build
1818
1851
  # or test step here; those belong in a separate job. ...
1819
1852
  - id: conductor
1820
- uses: vaultcompasshq/conductor@v0.11.0
1853
+ uses: vaultcompasshq/conductor@v0.12.0
1821
1854
  with:
1822
1855
  output: conductor.sarif
1823
1856
  pr-comment: true
@@ -1896,12 +1929,12 @@ per pull request.
1896
1929
 
1897
1930
  ```yaml
1898
1931
  - id: conductor-package-a
1899
- uses: vaultcompasshq/conductor@v0.11.0
1932
+ uses: vaultcompasshq/conductor@v0.12.0
1900
1933
  with:
1901
1934
  pr-comment: true
1902
1935
  pr-comment-marker: 'package-a'
1903
1936
  - id: conductor-package-b
1904
- uses: vaultcompasshq/conductor@v0.11.0
1937
+ uses: vaultcompasshq/conductor@v0.12.0
1905
1938
  with:
1906
1939
  pr-comment: true
1907
1940
  pr-comment-marker: 'package-b'
@@ -2001,6 +2034,63 @@ is one snapshot of one run: no per-finding state, nothing to dismiss, no
2001
2034
  history between runs, and a new comment every time rather than an alert that
2002
2035
  closes when the finding goes away.
2003
2036
 
2037
+ ## Upgrading
2038
+
2039
+ An adopter pins two numbers, and they control different things.
2040
+
2041
+ - **The action ref**, `uses: vaultcompasshq/conductor@<tag or SHA>`, picks
2042
+ which `action.yml` runs. That file carries the defaults for the four
2043
+ version inputs and the constants the pull-request backward-pin rule
2044
+ measures a pin against.
2045
+ - **The `conductor-version` input** picks which `@vaultcompass/conductor`
2046
+ the install step installs. The same step installs the three gates at
2047
+ `dep-guard-version`, `vault-guard-version` and `intent-guard-version`.
2048
+ Each input defaults to the version the tag shipped.
2049
+
2050
+ **The recommended shape is to leave all four version inputs unset** and move
2051
+ only the action ref. On a pull request, the validate step refuses an input
2052
+ naming a version below the one the tag ships, so an explicit old pin breaks
2053
+ the day you upgrade the ref (see "The Action" above). Outside a pull request
2054
+ an explicit pin is unaffected, which is how a stale pin can sit unnoticed
2055
+ until the first pull request after the upgrade.
2056
+
2057
+ **Pin the action ref to a full commit SHA** with the tag as a comment, for
2058
+ example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.12.0`. To
2059
+ find the SHA for a tag, run
2060
+ `gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
2061
+ the Releases page.
2062
+
2063
+ **Dependabot or Renovate bumping that SHA changes the action ref only.** It
2064
+ does not touch a `dep-guard-version`, `vault-guard-version`,
2065
+ `intent-guard-version` or `conductor-version` you set by hand, so such a pin
2066
+ must be raised or removed by hand in the same pull request, or that pull
2067
+ request is refused by the rule above.
2068
+
2069
+ **An action-only tag moves the tag while the npm package stays.** The
2070
+ CHANGELOG marks these as "An action-only release" and says which
2071
+ `conductor-version` default stays. `@vaultcompass/conductor` does not change
2072
+ on those, so `conductor-version` need not change either; the gate defaults
2073
+ may.
2074
+
2075
+ Defaults per tag, taken only from CHANGELOG.md entries that state them. A
2076
+ tag with no row here has an entry that does not state its defaults; read
2077
+ `action.yml` at that tag.
2078
+
2079
+ | Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
2080
+ | --- | --- | --- | --- |
2081
+ | v0.12.0 | package | 0.12.0 | vault-guard 1.12.1 (from 1.12.0), intent-guard 1.10.1 (from 1.10.0) |
2082
+ | v0.11.1 | action-only | 0.11.0 | dep-guard 0.15.0 (from 0.14.0), vault-guard 1.12.0 (from 1.11.0) |
2083
+ | v0.11.0 | package | 0.11.0 | dep-guard 0.14.0, intent-guard 1.10.0 |
2084
+ | v0.10.0 | package | 0.10.0 | dep-guard 0.13.0, vault-guard 1.11.0 |
2085
+ | v0.8.2 | action-only | 0.8.1 | dep-guard 0.11.1 (from 0.10.1) |
2086
+ | v0.8.1 | package | 0.8.1 | dep-guard 0.10.1, vault-guard 1.9.1, intent-guard 1.8.1 |
2087
+ | v0.8.0 | package | 0.8.0 | dep-guard 0.10.0, vault-guard 1.9.0, intent-guard 1.8.0 |
2088
+ | v0.7.0 | package | 0.7.0 | none |
2089
+ | v0.6.0 | package | 0.6.0 | dep-guard 0.9.0 (from 0.8.0), intent-guard 1.7.0 (from 1.6.0) |
2090
+ | v0.5.1 | action-only | 0.5.0 | dep-guard 0.8.0 (from 0.7.0), intent-guard 1.6.0 (from 1.5.2) |
2091
+ | v0.4.4 | action-only | 0.4.0 | dep-guard 0.7.0 (from 0.6.0), vault-guard 1.8.0 (from 1.7.0) |
2092
+ | v0.4.3 | action-only | 0.4.0 | intent-guard 1.5.2 (from 1.4.0) |
2093
+
2004
2094
  ## What is in and what is out
2005
2095
 
2006
2096
  In: the policy file and its schema, `init` with dry-run, revert, and adopt,
package/dist/cli.js CHANGED
@@ -6,7 +6,7 @@
6
6
  // parses arguments and prints. That split is what lets every one of those
7
7
  // decisions be tested without a subprocess.
8
8
  import { Command, CommanderError } from 'commander';
9
- import { closeSync, constants as fsConstants, lstatSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from 'node:fs';
9
+ import { appendFileSync, closeSync, constants as fsConstants, lstatSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from 'node:fs';
10
10
  import os from 'node:os';
11
11
  import path from 'node:path';
12
12
  import { fileURLToPath } from 'node:url';
@@ -14,7 +14,7 @@ import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
14
14
  import { absolutePathEntries, createGitShim, pinGitOutside, pinnedGitInside, realPathInside, removeGitShim, runGit, tempInsideTreeMessage, workTreeAbove, } from './git.js';
15
15
  import { applyInit, planInit, renderInitHuman, renderRevertHuman, revertInit, } from './init.js';
16
16
  import { renderSarif } from './output-sarif.js';
17
- import { gateLogLines, jobLogSummary, renderText, verdictToken, versionSkewWarnings, } from './output-text.js';
17
+ import { gateLogLines, jobLogSummary, renderText, verdictToken, versionSkewAnnotations, versionSkewSummaryLines, versionSkewWarnings, } from './output-text.js';
18
18
  import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
19
19
  import { refusedTrustBase, runAll } from './run.js';
20
20
  import { headTreeEqualsBase, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
@@ -708,6 +708,31 @@ export function buildProgram() {
708
708
  if (logLines.length > 0) {
709
709
  process.stderr.write(`${logLines.join('\n')}\n`);
710
710
  }
711
+ // IN GITHUB ACTIONS, A VERSION SKEW IS ALSO AN ANNOTATION AND A
712
+ // STEP-SUMMARY LINE, so a run on a stale gate is visible on the run's
713
+ // page without anybody opening the log (audit 2026-10-18: every guard
714
+ // repository's own push runs used a stale devDependency for weeks and
715
+ // only the log said which version ran). Reporting only. The
716
+ // annotation goes to stdout when stdout is not the report (--output
717
+ // given, which is how the Action runs), and to stderr otherwise. A
718
+ // summary that cannot be written is skipped: it never changes the
719
+ // exit code.
720
+ if (process.env.GITHUB_ACTIONS === 'true') {
721
+ const annotations = versionSkewAnnotations(result);
722
+ if (annotations.length > 0) {
723
+ (options.output !== undefined ? process.stdout : process.stderr).write(`${annotations.join('\n')}\n`);
724
+ }
725
+ const summaryFile = process.env.GITHUB_STEP_SUMMARY;
726
+ const summaryLines = versionSkewSummaryLines(result);
727
+ if (summaryFile !== undefined && summaryFile !== '' && summaryLines.length > 0) {
728
+ try {
729
+ appendFileSync(summaryFile, summaryLines.map((line) => `${line}\n\n`).join(''));
730
+ }
731
+ catch {
732
+ // The annotation and the log line above already say it.
733
+ }
734
+ }
735
+ }
711
736
  process.exitCode = applyAdvisory(result.exitCode, advisory);
712
737
  }
713
738
  catch (err) {
@@ -21,7 +21,13 @@ export type Subject = {
21
21
  manifest: string;
22
22
  lockfile?: string;
23
23
  }
24
- /** `column` and `endColumn` are 1-based here even where the source is 0-based. */
24
+ /**
25
+ * `column` and `endColumn` are 1-based here even where the source is
26
+ * 0-based (SARIF 2.1.0 sets a minimum of 1 on both). The gitleaks
27
+ * normalizer enforces it: a column below 1 becomes 1, and an `endColumn`
28
+ * is kept only when it is at least `column` and on the same line.
29
+ * vault-guard's is its 0-based column plus one, with no `endColumn`.
30
+ */
25
31
  | {
26
32
  kind: 'location';
27
33
  file: string;
@@ -2,7 +2,7 @@ import type { Diagnostic, Finding, RunSummary } from './envelope.js';
2
2
  import type { ContractSource, IntentPreparation } from './intent-prepare.js';
3
3
  import type { GatePolicy, GateRole, GateStage, Product } from './policy.js';
4
4
  import { type BaseComparison } from './osv-baseline.js';
5
- import type { ResolvedBinary } from './resolve.js';
5
+ import type { ResolutionSource, ResolvedBinary } from './resolve.js';
6
6
  export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing' | 'spawn-failed' | 'gate-error' | 'unparseable-output'
7
7
  /**
8
8
  * The gate was never spawned because the run could not be set up for it:
@@ -58,7 +58,22 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
58
58
  * Raised for the version probe, the scan, and the intent gate's
59
59
  * preparation steps; `timedOut.step` says which spawn was stopped.
60
60
  */
61
- | 'timed-out';
61
+ | 'timed-out'
62
+ /**
63
+ * The vulnerabilities gate on a decided trust base: a handed lockfile read
64
+ * no packages at the head, or a base lockfile is gone from the head with
65
+ * no populated replacement in its directory, and the base copy had
66
+ * packages, so the dependency set the head removed cannot be judged.
67
+ * Fail closed by design
68
+ * (docs/superpowers/specs/2026-10-18-emptied-lockfile-under-trust-base.md).
69
+ */
70
+ | 'lockfile-emptied'
71
+ /**
72
+ * The same check could not clear the head: a base copy unreadable, a base
73
+ * run that failed or printed no count, a command-line mismatch, or a head
74
+ * run whose stderr carries no package count (a lowered verbosity).
75
+ */
76
+ | 'lockfile-emptied-unverified';
62
77
  /** Where a gate's time limit came from: the test hook, the policy, or the product default. */
63
78
  export type TimeLimitSource = 'override' | 'policy' | 'default';
64
79
  export interface TimeLimit {
@@ -66,7 +81,7 @@ export interface TimeLimit {
66
81
  source: TimeLimitSource;
67
82
  }
68
83
  /** Which of a gate's spawns was stopped at the limit. The intent gate's check is `scan`. */
69
- export type TimedOutStep = 'version-probe' | 'scan' | 'import-spec' | 'freeze';
84
+ export type TimedOutStep = 'version-probe' | 'scan' | 'import-spec' | 'freeze' | 'base-check';
70
85
  export interface TimedOut {
71
86
  step: TimedOutStep;
72
87
  limitSeconds: number;
@@ -308,15 +323,25 @@ export interface GateOutcome {
308
323
  */
309
324
  nodeModulesSkipped?: string;
310
325
  /**
311
- * Present only when this gate was resolved from PATH, the version it
312
- * reported differs from the one the run was told to expect (the Action's
313
- * pin, handed over as an environment variable), and both are known. A
314
- * statement for a warning, never an input to a decision: resolution,
315
- * trust-base handling and the exit code are all settled without it.
326
+ * Present only when the version this gate reported differs from the one
327
+ * the run was told to expect (the Action's pin, handed over as an
328
+ * environment variable), and both are known, WHEREVER the binary was
329
+ * resolved from. A statement for a warning, never an input to a decision:
330
+ * resolution, trust-base handling and the exit code are all settled
331
+ * without it.
332
+ *
333
+ * Every location, not only PATH (audit 2026-10-18, the intent-guard
334
+ * audit's MB3). Outside a pull request a repository's own devDependency in
335
+ * node_modules/.bin outranks the Action's global install by design, and
336
+ * recording PATH alone left every guard repository's own push runs on
337
+ * stale gates with the pins set and nothing said. `path` is
338
+ * repository-relative when the binary is inside the repository (it
339
+ * reaches a published log through the reports), and absolute otherwise.
316
340
  */
317
341
  versionSkew?: {
318
342
  expected: string;
319
343
  found: string;
344
+ source: ResolutionSource;
320
345
  path: string;
321
346
  };
322
347
  /**
@@ -347,8 +372,9 @@ export interface GateOutcome {
347
372
  export interface RunGateOptions {
348
373
  /**
349
374
  * The version this run expects of the gate, when something says so (the
350
- * Action passes its pin). Compared with what the PATH binary reports, for a
351
- * warning only. Absent means no expectation, which is every local run.
375
+ * Action passes its pin). Compared with what the resolved binary reports,
376
+ * wherever it was found, for a warning only. Absent means no expectation,
377
+ * which is every local run.
352
378
  */
353
379
  expectedVersion?: string;
354
380
  repoRoot: string;
@@ -25,8 +25,8 @@ import { runGit } from './git.js';
25
25
  import { NormalizeError } from './envelope.js';
26
26
  import { describeLockfiles, normalizeDepGuard, normalizeFailedGate, normalizeGitleaks, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeOsvScanner, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
27
27
  import { renderOptionFlags } from './policy.js';
28
- import { NO_RESOLVE_OVERRIDDEN, emptiedLockfiles, noLongerScanned, nothingScannableMessage, notScannedDetail, selectOsvInputs, } from './osv-coverage.js';
29
- import { compareWithBase, comparisonFailed, } from './osv-baseline.js';
28
+ import { NO_RESOLVE_OVERRIDDEN, emptiedLockfiles, noLongerScanned, noLongerScannedFiles, nothingScannableMessage, notScannedDetail, packageCounts, selectOsvInputs, } from './osv-coverage.js';
29
+ import { checkEmptiedAgainstBase, compareWithBase, comparisonFailed, } from './osv-baseline.js';
30
30
  import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals, } from './external-config.js';
31
31
  import { osvLockfileKind, profileFor } from './products.js';
32
32
  import { unreadManifestsNote } from './unread-manifests.js';
@@ -82,6 +82,8 @@ export const CONDUCTOR_OWN_REASONS = new Set([
82
82
  'gate-version-unsupported',
83
83
  'history-shallow',
84
84
  'timed-out',
85
+ 'lockfile-emptied',
86
+ 'lockfile-emptied-unverified',
85
87
  ]);
86
88
  /**
87
89
  * A gate's time limit, and where it came from. THE ONE PLACE the precedence
@@ -150,6 +152,11 @@ function timedOutDetail(gate, step, limit, elapsedMs, trustBase) {
150
152
  return (`the version probe of ${gate.product} was stopped at ${limitSeconds} s (${where}), so the gate ` +
151
153
  'was not run and nothing was checked by it.');
152
154
  }
155
+ if (step === 'base-check') {
156
+ return (`${gate.product}'s check of the base copies of the lockfiles this pull request emptied was stopped ` +
157
+ `after ${elapsedSeconds} s, at what was left of its ${limitSeconds} s limit (${where}) after the ` +
158
+ `head scan, so the dependencies the pull request removed were not judged. ${remedies}`);
159
+ }
153
160
  const what = step === 'scan'
154
161
  ? `${gate.product} was stopped after ${elapsedSeconds} s, at its ${limitSeconds} s limit (${where}), ` +
155
162
  'so nothing was checked by it.'
@@ -195,6 +202,18 @@ export function cleanOutputLine(raw) {
195
202
  /** A zerolog line at one level: gitleaks' "<time> ERR ..." shape. */
196
203
  const ZEROLOG_ERR = /^\S+\s+ERR\s/;
197
204
  const ZEROLOG_WRN = /^\S+\s+WRN\s/;
205
+ /**
206
+ * osv-scanner 2.4.0's progress lines, which come before its error on every
207
+ * run (tests/fixtures/stated-reason-captures.json, audit 2026-10-18 N4): the
208
+ * walk banner, one "Scanned <file> file and found N package(s)" per file
209
+ * read, and the "End status:" counters. Quoting the banner as "gate said"
210
+ * was noise on every osv could-not-run.
211
+ */
212
+ const OSV_PROGRESS = [
213
+ /^Starting filesystem walk for root: /,
214
+ /^Scanned .+ file and found \d+ packages?$/,
215
+ /^End status: /,
216
+ ];
198
217
  function plainLine(raw) {
199
218
  return raw.replace(/[^\x20-\x7e]/g, ' ').replace(/\s+/g, ' ').trim();
200
219
  }
@@ -209,7 +228,8 @@ function plainLine(raw) {
209
228
  * 2. Informational lines are never chosen: a `note:` line and every
210
229
  * following indented line (a BLANK line ends the note block, so an
211
230
  * indented reason after it is not swallowed), and gitleaks' two
212
- * rename-detection warnings.
231
+ * rename-detection warnings, and osv-scanner's progress lines
232
+ * (OSV_PROGRESS).
213
233
  * 3. A marker wins: the first remaining INCOMPLETE: or zerolog ERR line,
214
234
  * joined with the indented lines after it, skipping blank lines, up to
215
235
  * the first non-blank line that is not indented.
@@ -234,6 +254,9 @@ function statedReasonFromStderr(stderr) {
234
254
  (line.text.includes('rename detection was skipped') || line.text.includes('diff.renameLimit'))) {
235
255
  line.informational = true;
236
256
  }
257
+ else if (OSV_PROGRESS.some((pattern) => pattern.test(line.text))) {
258
+ line.informational = true;
259
+ }
237
260
  }
238
261
  const candidate = (line) => !line.blank && !line.informational && line.text !== '';
239
262
  const markerAt = lines.findIndex((line) => candidate(line) && (line.text.startsWith('INCOMPLETE:') || ZEROLOG_ERR.test(line.text)));
@@ -1158,15 +1181,21 @@ function runGateInner(gate, options, started, progress) {
1158
1181
  };
1159
1182
  }
1160
1183
  const version = probed.kind === 'version' ? probed.value : null;
1161
- // A PATH binary at a different version than the run was told to expect: a
1162
- // fact for a warning and nothing else. It sits on `progress` (which `base`
1163
- // is) so every outcome from here on carries it, and no branch below reads it.
1164
- if (options.expectedVersion !== undefined &&
1165
- version !== null &&
1166
- binary.source === 'path' &&
1167
- version !== options.expectedVersion) {
1184
+ // A binary at a different version than the run was told to expect, from
1185
+ // whichever location resolution took it (node_modules/.bin, PATH or a
1186
+ // policy command): a fact for a warning and nothing else. It sits on
1187
+ // `progress` (which `base` is) so every outcome from here on carries it,
1188
+ // and no branch below reads it.
1189
+ if (options.expectedVersion !== undefined && version !== null && version !== options.expectedVersion) {
1190
+ const relative = path.relative(options.repoRoot, binary.program);
1191
+ const inside = relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
1168
1192
  Object.assign(progress, {
1169
- versionSkew: { expected: options.expectedVersion, found: version, path: binary.program },
1193
+ versionSkew: {
1194
+ expected: options.expectedVersion,
1195
+ found: version,
1196
+ source: binary.source,
1197
+ path: inside ? relative : binary.program,
1198
+ },
1170
1199
  });
1171
1200
  }
1172
1201
  // The command-line floor. Only the external tools have one: the umbrella
@@ -1300,6 +1329,94 @@ function spawnAndRead(ctx) {
1300
1329
  // notes. Carried onto every outcome from here on that reports a scan.
1301
1330
  let selection = null;
1302
1331
  const selectionDiagnostics = [];
1332
+ // On a decided trust base, the base lockfiles the head deleted or moved:
1333
+ // candidates for the emptied-lockfile base check below. Null when the base
1334
+ // tree could not be listed, which that check reads as unverified.
1335
+ let removedLockfiles = [];
1336
+ // THE EMPTIED-LOCKFILE BASE CHECK (audit 2026-10-18 N1, design
1337
+ // docs/superpowers/specs/2026-10-18-emptied-lockfile-under-trust-base.md).
1338
+ // Only on a decided trust base and only for the vulnerabilities gate. The
1339
+ // candidates are the emptied handed lockfiles plus the base lockfiles the
1340
+ // head deleted or moved. Called after a completed head scan (every head
1341
+ // could-not-run returns first), or, when nothing at all was handed, in its
1342
+ // place. Returns the could-not-run outcome, or null when the head result
1343
+ // stands. `headArgv` null means no head run, so there is no command line
1344
+ // to hold the base one against.
1345
+ const removalCheck = (input) => {
1346
+ if (gate.product !== 'osv-scanner' || decidedRef === undefined) {
1347
+ return null;
1348
+ }
1349
+ const removed = removedLockfiles;
1350
+ if (input.emptied.length === 0 && removed !== null && removed.length === 0) {
1351
+ return null;
1352
+ }
1353
+ const baseArgv = (copies) => [
1354
+ ...binary.argvPrefix,
1355
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: [...copies] }),
1356
+ ];
1357
+ const checked = removed === null
1358
+ ? { kind: 'unverified', detail: `the base tree at ${decidedRef} could not be listed` }
1359
+ : workDir === null
1360
+ ? { kind: 'unverified', detail: 'there is no work directory to hold the base copies' }
1361
+ : checkEmptiedAgainstBase({
1362
+ repoRoot: options.repoRoot,
1363
+ ref: decidedRef,
1364
+ workDir,
1365
+ emptied: input.emptied,
1366
+ removed,
1367
+ headCounts: input.headCounts,
1368
+ headArgv: input.headArgv,
1369
+ baseArgv,
1370
+ budgetMs: input.budgetMs,
1371
+ spawn: (argv, cwd, budget) => {
1372
+ const baseChild = spawnSync(binary.command, [...argv], {
1373
+ cwd,
1374
+ encoding: 'utf8',
1375
+ timeout: budget,
1376
+ maxBuffer: 64 * 1024 * 1024,
1377
+ });
1378
+ return {
1379
+ status: baseChild.status,
1380
+ stderr: stripAnsi(baseChild.stderr ?? ''),
1381
+ failure: spawnFailure(baseChild),
1382
+ };
1383
+ },
1384
+ });
1385
+ if (checked.kind === 'clear') {
1386
+ return null;
1387
+ }
1388
+ const done = { ...input.outcome, durationMs: Date.now() - started };
1389
+ if (checked.kind === 'timed-out') {
1390
+ const detail = timedOutDetail(gate, 'base-check', timeLimit, checked.elapsedMs, options.trustBase);
1391
+ const timedOut = timedOutRecord('base-check', timeLimit, checked.elapsedMs, checked.signal);
1392
+ return {
1393
+ ...done,
1394
+ couldNotRun: { reason: 'timed-out', detail, timedOut },
1395
+ findings: [timedOutFinding(gate, detail, timedOut)],
1396
+ run: EMPTY_RUN,
1397
+ diagnostics: [],
1398
+ };
1399
+ }
1400
+ const named = [...new Set([...input.emptied, ...(removed ?? [])])];
1401
+ const detail = checked.kind === 'emptied'
1402
+ ? `${checked.files
1403
+ .map((entry) => entry.removed
1404
+ ? `${entry.path} is not in this pull request but had ${entry.packages} package(s) at the base (${decidedRef})`
1405
+ : `${entry.path} read no packages at the head but ${entry.packages} at the base (${decidedRef})`)
1406
+ .join('; ')}, so the dependencies this pull request removed cannot be judged. Regenerate the ` +
1407
+ 'lockfile, or add its replacement beside the same manifest in this pull request, or remove ' +
1408
+ "the manifest's dependencies with it."
1409
+ : `${named.join(', ')} ${named.length === 1 ? 'was' : 'were'} emptied, deleted or moved by this pull ` +
1410
+ `request, and the check that the base had no packages there could not be completed: ` +
1411
+ `${checked.detail}. Nothing the pull request removed was judged.`;
1412
+ return {
1413
+ ...done,
1414
+ couldNotRun: { reason: checked.kind === 'emptied' ? 'lockfile-emptied' : 'lockfile-emptied-unverified', detail },
1415
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
1416
+ run: EMPTY_RUN,
1417
+ diagnostics: [],
1418
+ };
1419
+ };
1303
1420
  // Tracked manifests this gate was NOT handed, when it was handed others
1304
1421
  // (review of 1b.2, item 5): a run note, so a Podfile.lock beside a scanned
1305
1422
  // mix.lock is named without pushing a clean run off its one-line summary.
@@ -1355,6 +1472,7 @@ function spawnAndRead(ctx) {
1355
1472
  selectionDiagnostics.push(...selection.diagnostics);
1356
1473
  if (decidedRef !== undefined) {
1357
1474
  selectionDiagnostics.push(...noLongerScanned(options.repoRoot, decidedRef, new Set(tracked)));
1475
+ removedLockfiles = noLongerScannedFiles(options.repoRoot, decidedRef, new Set(tracked));
1358
1476
  }
1359
1477
  if (external.lockfiles.length > 0) {
1360
1478
  const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
@@ -1365,6 +1483,25 @@ function spawnAndRead(ctx) {
1365
1483
  // without spawning it. The verdict is unchanged (clean); what changes is
1366
1484
  // what is said: which requirements files the pin check left out, and
1367
1485
  // which tracked manifests were not handed to this scanner.
1486
+ // Every lockfile the base had may have been deleted: on a trust base
1487
+ // the removed ones are still checked, with no head scan to precede
1488
+ // it, so the whole limit is the budget.
1489
+ const removedOutcome = removalCheck({
1490
+ emptied: [],
1491
+ headCounts: new Map(),
1492
+ headArgv: null,
1493
+ budgetMs: timeoutMs,
1494
+ outcome: {
1495
+ ...base,
1496
+ productVersion: version,
1497
+ binary,
1498
+ ...(trustBase === undefined ? {} : { trustBase }),
1499
+ exitCode: null,
1500
+ },
1501
+ });
1502
+ if (removedOutcome !== null) {
1503
+ return removedOutcome;
1504
+ }
1368
1505
  const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
1369
1506
  const cleanBecause = 'the verdict is clean because there was nothing to read, not because a scan found nothing.';
1370
1507
  return {
@@ -1517,6 +1654,15 @@ function spawnAndRead(ctx) {
1517
1654
  // Keep the backstop's view current, so an unexpected throw below still
1518
1655
  // reports which binary ran and what it printed.
1519
1656
  Object.assign(progress, withRun);
1657
+ // The emptied-lockfile base check after a completed head scan, under what
1658
+ // is left of the limit (removalCheck, above).
1659
+ const emptiedOnBase = (emptied, headCounts, exitCode) => removalCheck({
1660
+ emptied,
1661
+ headCounts,
1662
+ headArgv: argv,
1663
+ budgetMs: timeoutMs - (Date.now() - spawnStarted),
1664
+ outcome: { ...withRun, exitCode },
1665
+ });
1520
1666
  // THE FIRST THING READ after spawnSync returns, ahead of every status,
1521
1667
  // signal, report and stdout check, and it returns for every error. A child
1522
1668
  // stopped at the limit that handled SIGTERM can come back with status 0, or
@@ -1556,6 +1702,12 @@ function spawnAndRead(ctx) {
1556
1702
  // scan that did not happen. So it is clean, and the report says why.
1557
1703
  if (exitCode !== null && profile.exit.nothingToScan.includes(exitCode)) {
1558
1704
  const handedAll = external.lockfiles ?? [];
1705
+ // Every handed file read nothing: on a trust base, each one's base copy
1706
+ // is checked (the emptied-lockfile check above).
1707
+ const emptiedAll = emptiedOnBase(handedAll, new Map(), exitCode);
1708
+ if (emptiedAll !== null) {
1709
+ return emptiedAll;
1710
+ }
1559
1711
  return {
1560
1712
  ...withRun,
1561
1713
  exitCode: 0,
@@ -1713,6 +1865,45 @@ function spawnAndRead(ctx) {
1713
1865
  // never a could-not-run, unlike the normalizer failure the catch below
1714
1866
  // is for.
1715
1867
  let findings = normalized.findings;
1868
+ // A handed lockfile osv-scanner read no packages from, while it read
1869
+ // packages from another (audit finding F2). Exit 128 above covers only
1870
+ // the all-empty case; this is the rest, named on the coverage line and
1871
+ // in a diagnostic, so an emptied lockfile's advisories never vanish
1872
+ // without a word. Annotation only on a plain run; on a trust base the
1873
+ // emptied-lockfile check runs first, BEFORE the comparison, and a head
1874
+ // that blocked is checked too, so the verdict is could-not-run rather
1875
+ // than blocked when the head emptied a file the base had packages in.
1876
+ const emptied = gate.product === 'osv-scanner'
1877
+ ? emptiedLockfiles(withRun.stderr, external.lockfiles ?? [], spawnCwd)
1878
+ : [];
1879
+ const headCounts = gate.product === 'osv-scanner'
1880
+ ? packageCounts(withRun.stderr, external.lockfiles ?? [], spawnCwd)
1881
+ : new Map();
1882
+ // A LOWERED VERBOSITY FAILS CLOSED on a trust base: without a count line
1883
+ // for a handed lockfile, an emptied one cannot be told from a populated
1884
+ // one, so the check that the head removed nothing cannot run. Said, and
1885
+ // the option left alone: conductor never edits a gate's configuration.
1886
+ const uncounted = gate.product === 'osv-scanner' && decidedRef !== undefined
1887
+ ? (external.lockfiles ?? []).filter((file) => osvLockfileKind(path.posix.basename(file)) !== 'requirements' && !headCounts.has(file))
1888
+ : [];
1889
+ if (uncounted.length > 0) {
1890
+ const detail = `osv-scanner printed no package count for ${uncounted.join(', ')}, which the trust-base check that ` +
1891
+ 'this pull request emptied, deleted or moved no lockfile needs. A verbosity option in the ' +
1892
+ "policy's osv-scanner options hides those counts: remove it.";
1893
+ return {
1894
+ ...withRun,
1895
+ durationMs: Date.now() - started,
1896
+ exitCode,
1897
+ couldNotRun: { reason: 'lockfile-emptied-unverified', detail },
1898
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
1899
+ run: EMPTY_RUN,
1900
+ diagnostics: [],
1901
+ };
1902
+ }
1903
+ const emptiedOutcome = emptiedOnBase(emptied, headCounts, exitCode);
1904
+ if (emptiedOutcome !== null) {
1905
+ return emptiedOutcome;
1906
+ }
1716
1907
  let baseComparison;
1717
1908
  const comparisonDiagnostics = [];
1718
1909
  if (gate.product === 'osv-scanner' &&
@@ -1757,14 +1948,6 @@ function spawnAndRead(ctx) {
1757
1948
  baseComparison = compared.comparison;
1758
1949
  comparisonDiagnostics.push(...compared.diagnostics);
1759
1950
  }
1760
- // A handed lockfile osv-scanner read no packages from, while it read
1761
- // packages from another (audit finding F2). Exit 128 above covers only
1762
- // the all-empty case; this is the rest, named on the coverage line and
1763
- // in a diagnostic, so an emptied lockfile's advisories never vanish
1764
- // without a word. Annotation only: the verdict is osv-scanner's.
1765
- const emptied = gate.product === 'osv-scanner'
1766
- ? emptiedLockfiles(withRun.stderr, external.lockfiles ?? [], spawnCwd)
1767
- : [];
1768
1951
  const emptyDiagnostics = emptied.length === 0
1769
1952
  ? []
1770
1953
  : [
package/dist/normalize.js CHANGED
@@ -736,13 +736,38 @@ export function normalizeGitleaks(raw, version, blocked) {
736
736
  const entry = needRecord(rawEntry, product, where);
737
737
  const rule = needString(entry.RuleID, product, `${where}.RuleID`);
738
738
  const file = needString(entry.File, product, `${where}.File`);
739
- const line = needNumber(entry.StartLine, product, `${where}.StartLine`);
739
+ // Required, and then floored like the columns below: SARIF 2.1.0 gives
740
+ // startLine a minimum of 1, so a line below 1 or not an integer is 1.
741
+ const startLine = needNumber(entry.StartLine, product, `${where}.StartLine`);
742
+ const line = Number.isInteger(startLine) && startLine >= 1 ? startLine : 1;
740
743
  // Carried as gitleaks reports them, which is also what its own SARIF
741
744
  // output uses. gitleaks 8.30.1 column numbers are not consistently 0- or
742
745
  // 1-based across findings (one token at character 21 was reported at 22,
743
746
  // another at character 15 at 15), so no correction is applied.
744
- const column = typeof entry.StartColumn === 'number' ? entry.StartColumn : 1;
745
- const endColumn = typeof entry.EndColumn === 'number' ? entry.EndColumn : undefined;
747
+ //
748
+ // BUT A COLUMN BELOW 1 IS NEVER CARRIED. The envelope's columns are
749
+ // 1-based and SARIF 2.1.0 gives startColumn and endColumn a minimum of 1,
750
+ // and gitleaks 8.30.1 writes "EndColumn": 0 on its private-key rule over
751
+ // a PEM file (tests/fixtures/gitleaks-8.30.1-private-key-endcolumn-zero.json),
752
+ // which made the SARIF file invalid and so refused by code scanning
753
+ // (audit 2026-10-18 B1). A start column below 1 becomes 1. The end column
754
+ // is kept only as an integer that is at least 1 and at least the start
755
+ // column, on a finding whose EndLine is absent or equals its StartLine:
756
+ // the subject carries no end line, so a region read from it ends on its
757
+ // start line, and an end column from a later line would mark the wrong
758
+ // span. Otherwise it is left out, which SARIF reads as "to the end of
759
+ // the line".
760
+ const column = typeof entry.StartColumn === 'number' && Number.isInteger(entry.StartColumn) && entry.StartColumn >= 1
761
+ ? entry.StartColumn
762
+ : 1;
763
+ const oneLine = entry.EndLine === undefined || entry.EndLine === entry.StartLine;
764
+ const endColumn = oneLine &&
765
+ typeof entry.EndColumn === 'number' &&
766
+ Number.isInteger(entry.EndColumn) &&
767
+ entry.EndColumn >= 1 &&
768
+ entry.EndColumn >= column
769
+ ? entry.EndColumn
770
+ : undefined;
746
771
  const commit = optionalString(entry.Commit, product, `${where}.Commit`);
747
772
  const date = optionalString(entry.Date, product, `${where}.Date`);
748
773
  // gitleaks' own Fingerprint is commit:file:rule:line, identical across
@@ -75,6 +75,71 @@ export interface CompareResult {
75
75
  * finding is introduced. Never could-not-run.
76
76
  */
77
77
  export declare function comparisonFailed(args: CompareArgs, reason: string): CompareResult;
78
+ /** How the emptied-lockfile check's one spawn went, classified by the caller's spawnFailure. */
79
+ export interface EmptiedSpawnResult {
80
+ status: number | null;
81
+ stderr: string;
82
+ failure: null | {
83
+ reason: 'timed-out';
84
+ signal: string | null;
85
+ } | {
86
+ reason: 'spawn-failed';
87
+ message: string;
88
+ };
89
+ }
90
+ export interface EmptiedCheckArgs {
91
+ repoRoot: string;
92
+ ref: string;
93
+ workDir: string;
94
+ /** Repository-relative: the emptied handed lockfiles, or every handed one on exit 128. */
95
+ emptied: readonly string[];
96
+ /** Repository-relative: base lockfiles the head no longer tracks (deleted or moved). */
97
+ removed: readonly string[];
98
+ /** The head run's package count for each handed lockfile, for the same-directory replacement rule. */
99
+ headCounts: ReadonlyMap<string, number>;
100
+ /** Null when nothing was handed and the head was never spawned: no symmetry check. */
101
+ headArgv: readonly string[] | null;
102
+ baseArgv: (copies: readonly string[]) => string[];
103
+ /** What is left of the gate's time limit after the head scan. */
104
+ budgetMs: number;
105
+ spawn: (argv: readonly string[], cwd: string, timeoutMs: number) => EmptiedSpawnResult;
106
+ }
107
+ export type EmptiedCheckResult = {
108
+ kind: 'clear';
109
+ } | {
110
+ kind: 'emptied';
111
+ files: Array<{
112
+ path: string;
113
+ packages: number;
114
+ removed: boolean;
115
+ }>;
116
+ } | {
117
+ kind: 'unverified';
118
+ detail: string;
119
+ } | {
120
+ kind: 'timed-out';
121
+ elapsedMs: number;
122
+ signal: string | null;
123
+ };
124
+ /**
125
+ * The emptied-lockfile base check (design
126
+ * docs/superpowers/specs/2026-10-18-emptied-lockfile-under-trust-base.md,
127
+ * audit 2026-10-18 N1). On a decided trust base, a handed lockfile that read
128
+ * no packages at the head, and a base lockfile the head deleted or moved,
129
+ * is copied from the base and osv-scanner is run once on those copies; a
130
+ * copy with packages means the head removed what the gate judges. A removed
131
+ * file is cleared only by a head-handed lockfile in the SAME directory that
132
+ * read packages, is not a requirements file, and is absent from the base
133
+ * tree (a migration, say npm to pnpm, beside the same manifest).
134
+ *
135
+ * FAIL CLOSED, unlike compareWithBase, whose labels only ever move toward
136
+ * introduced. This check exists only to stop a head from removing what the
137
+ * gate judges, so anything that keeps it from clearing the head (a base
138
+ * copy that cannot be read, an asymmetric command line, a base run that
139
+ * fails, times out or prints no count for a copy) is a failure the caller
140
+ * turns into could-not-run. Requirements files are not checked (known-open).
141
+ */
142
+ export declare function checkEmptiedAgainstBase(args: EmptiedCheckArgs): EmptiedCheckResult;
78
143
  /**
79
144
  * Runs the comparison. Assumes the caller has established section 3.1: a
80
145
  * decided trust base, a head run that exited blocked, at least one finding.
@@ -18,7 +18,7 @@ import { mkdirSync, realpathSync, writeFileSync } from 'node:fs';
18
18
  import path from 'node:path';
19
19
  import { realPathInside, runGit } from './git.js';
20
20
  import { normalizeOsvScanner } from './normalize.js';
21
- import { ABSENT_ON_BASE, baseReader } from './osv-coverage.js';
21
+ import { ABSENT_ON_BASE, baseReader, packageCounts } from './osv-coverage.js';
22
22
  import { osvLockfileKind } from './products.js';
23
23
  import { checkRequirementsPins } from './requirements-pin.js';
24
24
  import { readFileAtRefBytes, treeEntryAt } from './trust-base.js';
@@ -148,6 +148,110 @@ export function comparisonFailed(args, reason) {
148
148
  diagnostics: unavailableNotes(unavailable),
149
149
  };
150
150
  }
151
+ /**
152
+ * The emptied-lockfile base check (design
153
+ * docs/superpowers/specs/2026-10-18-emptied-lockfile-under-trust-base.md,
154
+ * audit 2026-10-18 N1). On a decided trust base, a handed lockfile that read
155
+ * no packages at the head, and a base lockfile the head deleted or moved,
156
+ * is copied from the base and osv-scanner is run once on those copies; a
157
+ * copy with packages means the head removed what the gate judges. A removed
158
+ * file is cleared only by a head-handed lockfile in the SAME directory that
159
+ * read packages, is not a requirements file, and is absent from the base
160
+ * tree (a migration, say npm to pnpm, beside the same manifest).
161
+ *
162
+ * FAIL CLOSED, unlike compareWithBase, whose labels only ever move toward
163
+ * introduced. This check exists only to stop a head from removing what the
164
+ * gate judges, so anything that keeps it from clearing the head (a base
165
+ * copy that cannot be read, an asymmetric command line, a base run that
166
+ * fails, times out or prints no count for a copy) is a failure the caller
167
+ * turns into could-not-run. Requirements files are not checked (known-open).
168
+ */
169
+ export function checkEmptiedAgainstBase(args) {
170
+ const baseDir = path.join(args.workDir, 'osv-base', 'emptied');
171
+ const removed = new Set(args.removed);
172
+ const candidates = [...new Set([...args.emptied, ...args.removed])].filter((file) => osvLockfileKind(path.posix.basename(file)) !== 'requirements');
173
+ const copies = [];
174
+ const copied = [];
175
+ for (const file of candidates) {
176
+ const read = readFileAtRefBytes(args.repoRoot, args.ref, file);
177
+ if (read.kind === 'absent') {
178
+ continue;
179
+ }
180
+ if (read.kind === 'error') {
181
+ return { kind: 'unverified', detail: `the base copy of ${file} cannot be read (${read.detail})` };
182
+ }
183
+ if (realPathInside(args.repoRoot, args.workDir)) {
184
+ return {
185
+ kind: 'unverified',
186
+ detail: 'the temporary directory is inside the repository, so no base copy can be kept outside the ' +
187
+ 'tree being judged',
188
+ };
189
+ }
190
+ try {
191
+ copies.push(placeCopy(baseDir, file, read.bytes));
192
+ }
193
+ catch (err) {
194
+ return { kind: 'unverified', detail: err instanceof Error ? err.message : String(err) };
195
+ }
196
+ copied.push(file);
197
+ }
198
+ if (copies.length === 0) {
199
+ return { kind: 'clear' };
200
+ }
201
+ const baseArgv = args.baseArgv(copies);
202
+ const headRest = args.headArgv === null ? null : withoutLockfiles(args.headArgv);
203
+ const baseRest = withoutLockfiles(baseArgv);
204
+ if (headRest !== null && JSON.stringify(headRest) !== JSON.stringify(baseRest)) {
205
+ return {
206
+ kind: 'unverified',
207
+ detail: `the base run's command line would differ from the head run's at ${firstDifference(headRest, baseRest)}`,
208
+ };
209
+ }
210
+ if (args.budgetMs <= 0) {
211
+ return { kind: 'timed-out', elapsedMs: 0, signal: null };
212
+ }
213
+ const started = Date.now();
214
+ const child = args.spawn(baseArgv, baseDir, args.budgetMs);
215
+ if (child.failure !== null) {
216
+ return child.failure.reason === 'timed-out'
217
+ ? { kind: 'timed-out', elapsedMs: Date.now() - started, signal: child.failure.signal }
218
+ : { kind: 'unverified', detail: `osv-scanner could not be run on the base copies (${child.failure.message})` };
219
+ }
220
+ if (child.status === null) {
221
+ return { kind: 'unverified', detail: 'osv-scanner did not finish on the base copies' };
222
+ }
223
+ // Exit 128: every copy parsed to nothing, so the base had nothing either.
224
+ if (child.status === 128) {
225
+ return { kind: 'clear' };
226
+ }
227
+ if (child.status !== 0 && child.status !== 1) {
228
+ return { kind: 'unverified', detail: `osv-scanner exited ${child.status} on the base copies` };
229
+ }
230
+ const counts = packageCounts(child.stderr, copies, baseDir);
231
+ const unread = copied.filter((_, index) => !counts.has(copies[index]));
232
+ if (unread.length > 0) {
233
+ return {
234
+ kind: 'unverified',
235
+ detail: `osv-scanner printed no package count for the base copy of ${unread.join(', ')}`,
236
+ };
237
+ }
238
+ // A removed file is replaced only by a head-handed lockfile in the same
239
+ // directory that read packages, that is not a requirements file, and that
240
+ // the base tree does not have: one elsewhere, or one the base already had
241
+ // (a Cargo.lock beside the deleted package-lock.json), carries another
242
+ // manifest's packages. A base listing that errors is not absent, so that
243
+ // file does not count (fail closed).
244
+ const newOnHead = (other) => treeEntryAt(args.repoRoot, args.ref, other).kind === 'absent';
245
+ const replaced = (file) => [...args.headCounts].some(([other, count]) => other !== file &&
246
+ count > 0 &&
247
+ path.posix.dirname(other) === path.posix.dirname(file) &&
248
+ osvLockfileKind(path.posix.basename(other)) !== 'requirements' &&
249
+ newOnHead(other));
250
+ const emptied = copied
251
+ .map((file, index) => ({ path: file, packages: counts.get(copies[index]) ?? 0, removed: removed.has(file) }))
252
+ .filter((entry) => entry.packages > 0 && !(entry.removed && replaced(entry.path)));
253
+ return emptied.length === 0 ? { kind: 'clear' } : { kind: 'emptied', files: emptied };
254
+ }
151
255
  /**
152
256
  * Runs the comparison. Assumes the caller has established section 3.1: a
153
257
  * decided trust base, a head run that exited blocked, at least one finding.
@@ -50,10 +50,18 @@ export declare function selectOsvInputs(args: {
50
50
  * Notes for every basename-matched file tracked on the base and absent from
51
51
  * the head (section 3.2): deleted, moved, or renamed to a name the matcher
52
52
  * does not take. Such a file is not scanned on either side, and saying so is
53
- * all this does: it never blocks. A base listing git could not make yields no
54
- * note rather than a guess.
53
+ * all this says: the note never blocks. A base listing git could not make
54
+ * yields no note rather than a guess. Whether the removal blocks is the
55
+ * emptied-lockfile base check's decision (src/osv-baseline.ts), which reads
56
+ * the same list through noLongerScannedFiles.
55
57
  */
56
58
  export declare function noLongerScanned(repoRoot: string, ref: string, tracked: ReadonlySet<string>): Diagnostic[];
59
+ /**
60
+ * The base lockfiles the head no longer tracks, sorted. Null when the base
61
+ * tree could not be listed, which the emptied-lockfile check treats as
62
+ * unverified rather than as none.
63
+ */
64
+ export declare function noLongerScannedFiles(repoRoot: string, ref: string, tracked: ReadonlySet<string>): string[] | null;
57
65
  /** The nothing-to-scan sentence when every candidate was a requirements file left out. */
58
66
  export declare function nothingScannableMessage(notScanned: readonly string[]): string;
59
67
  /** The run detail beside `lockfiles`: how many requirements files were left out, and which. */
@@ -76,5 +84,13 @@ export declare function notScannedDetail(notScanned: readonly string[]): string;
76
84
  * that lowers osv-scanner's verbosity hides every line), not a finding.
77
85
  */
78
86
  export declare function emptiedLockfiles(stderr: string, handed: readonly string[], cwd: string): string[];
87
+ /**
88
+ * The package count osv-scanner printed for each handed file, read by the
89
+ * same SCANNED_LINE and the same two-spelling path match as
90
+ * emptiedLockfiles. A file with no count line is absent from the map. Read
91
+ * by the emptied-lockfile base check (src/osv-baseline.ts), where a missing
92
+ * line fails closed.
93
+ */
94
+ export declare function packageCounts(stderr: string, handed: readonly string[], cwd: string): Map<string, number>;
79
95
  /** The note when a policy's no-resolve was dropped from an invocation. */
80
96
  export declare const NO_RESOLVE_OVERRIDDEN: string;
@@ -135,27 +135,36 @@ export function selectOsvInputs(args) {
135
135
  * Notes for every basename-matched file tracked on the base and absent from
136
136
  * the head (section 3.2): deleted, moved, or renamed to a name the matcher
137
137
  * does not take. Such a file is not scanned on either side, and saying so is
138
- * all this does: it never blocks. A base listing git could not make yields no
139
- * note rather than a guess.
138
+ * all this says: the note never blocks. A base listing git could not make
139
+ * yields no note rather than a guess. Whether the removal blocks is the
140
+ * emptied-lockfile base check's decision (src/osv-baseline.ts), which reads
141
+ * the same list through noLongerScannedFiles.
140
142
  */
141
143
  export function noLongerScanned(repoRoot, ref, tracked) {
144
+ return (noLongerScannedFiles(repoRoot, ref, tracked) ?? []).map((file) => ({
145
+ code: 'conductor/lockfile-no-longer-scanned',
146
+ message: `${file} is tracked on the base and not in this pull request, so it is no longer scanned ` +
147
+ '(by either run). Its removal is visible in the diff.',
148
+ }));
149
+ }
150
+ /**
151
+ * The base lockfiles the head no longer tracks, sorted. Null when the base
152
+ * tree could not be listed, which the emptied-lockfile check treats as
153
+ * unverified rather than as none.
154
+ */
155
+ export function noLongerScannedFiles(repoRoot, ref, tracked) {
142
156
  if (ref.startsWith('-')) {
143
- return [];
157
+ return null;
144
158
  }
145
159
  const listing = runGit(repoRoot, ['ls-tree', '-r', '-z', '--name-only', ref], { maxBuffer: 64 * 1024 * 1024 });
146
160
  if (listing.error !== undefined || listing.status !== 0) {
147
- return [];
161
+ return null;
148
162
  }
149
163
  return listing.stdout
150
164
  .split('\0')
151
165
  .filter((file) => file !== '' && !file.split('/').includes('node_modules'))
152
166
  .filter((file) => osvLockfileKind(file) !== null && !tracked.has(file))
153
- .sort()
154
- .map((file) => ({
155
- code: 'conductor/lockfile-no-longer-scanned',
156
- message: `${file} is tracked on the base and not in this pull request, so it is no longer scanned ` +
157
- '(by either run). Its removal is visible in the diff.',
158
- }));
167
+ .sort();
159
168
  }
160
169
  /** The nothing-to-scan sentence when every candidate was a requirements file left out. */
161
170
  export function nothingScannableMessage(notScanned) {
@@ -218,6 +227,34 @@ export function emptiedLockfiles(stderr, handed, cwd) {
218
227
  }
219
228
  return handed.filter((file) => spellings(path.resolve(cwd, file)).some((spelling) => empty.has(spelling)));
220
229
  }
230
+ /**
231
+ * The package count osv-scanner printed for each handed file, read by the
232
+ * same SCANNED_LINE and the same two-spelling path match as
233
+ * emptiedLockfiles. A file with no count line is absent from the map. Read
234
+ * by the emptied-lockfile base check (src/osv-baseline.ts), where a missing
235
+ * line fails closed.
236
+ */
237
+ export function packageCounts(stderr, handed, cwd) {
238
+ const bySpelling = new Map();
239
+ for (const raw of stderr.split('\n')) {
240
+ const match = SCANNED_LINE.exec(raw.trim());
241
+ if (match !== null) {
242
+ for (const spelling of spellings(match[1])) {
243
+ bySpelling.set(spelling, Number(match[2]));
244
+ }
245
+ }
246
+ }
247
+ const out = new Map();
248
+ for (const file of handed) {
249
+ const count = spellings(path.resolve(cwd, file))
250
+ .map((spelling) => bySpelling.get(spelling))
251
+ .find((value) => value !== undefined);
252
+ if (count !== undefined) {
253
+ out.set(file, count);
254
+ }
255
+ }
256
+ return out;
257
+ }
221
258
  /** The note when a policy's no-resolve was dropped from an invocation. */
222
259
  export const NO_RESOLVE_OVERRIDDEN = 'options.no-resolve in .guardrails.yaml was not passed: requirements files are always scanned ' +
223
260
  'with --no-resolve (direct requirements only).';
@@ -120,6 +120,7 @@
120
120
  import { gateExitBlocks } from './exit-codes.js';
121
121
  import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
122
122
  import { INTENT_WARNING } from './normalize.js';
123
+ import { skewFound, skewPlace } from './output-text.js';
123
124
  import { POLICY_FILE_NAME } from './policy.js';
124
125
  const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
125
126
  export const UMBRELLA_DRIVER_NAME = 'conductor';
@@ -829,6 +830,40 @@ function nodeModulesSkippedNotifications(result) {
829
830
  },
830
831
  ];
831
832
  }
833
+ /**
834
+ * A gate whose resolved binary reported a version other than the one the
835
+ * run was pinned to (the Action's CONDUCTOR_EXPECTED_* variables), from any
836
+ * location: a node_modules/.bin devDependency, PATH, or a policy command.
837
+ * A NOTE: it says which build ran, a statement in the same shape as
838
+ * node-modules-skipped, and the gate's own outcome is reported on its own.
839
+ * The path is carried only when it is repository-relative (node_modules);
840
+ * a PATH binary's absolute machine path stays in the job log line.
841
+ */
842
+ function versionSkewNotifications(result) {
843
+ return result.gates.flatMap((gate) => {
844
+ const skew = gate.versionSkew;
845
+ if (skew === undefined) {
846
+ return [];
847
+ }
848
+ const found = skewFound(skew);
849
+ return [
850
+ {
851
+ id: 'conductor/version-skew',
852
+ message: `The ${gate.role} gate (${gate.product}) reported version ${found}, but this run expects ` +
853
+ `${skew.expected} (the version the action pinned); it was resolved from ${skewPlace(skew)}. ` +
854
+ 'Resolution is unchanged and that binary was used.',
855
+ details: {
856
+ role: gate.role,
857
+ product: gate.product,
858
+ expected: skew.expected,
859
+ found,
860
+ source: skew.source,
861
+ ...(skew.source === 'node_modules' ? { path: skew.path } : {}),
862
+ },
863
+ },
864
+ ];
865
+ });
866
+ }
832
867
  /**
833
868
  * A passthrough option that is a gate's own setting under a name conductor
834
869
  * also uses (gitleaks' `options.timeout`), as notifications. A NOTE: nothing
@@ -1003,6 +1038,7 @@ export function renderSarif(result, umbrellaVersion) {
1003
1038
  ...proposalNotifications(result),
1004
1039
  ...trustBaseWithheldNotifications(result),
1005
1040
  ...nodeModulesSkippedNotifications(result),
1041
+ ...versionSkewNotifications(result),
1006
1042
  ...intentWarningNotifications(result),
1007
1043
  ...gateOwnOptionNotifications(result),
1008
1044
  ];
@@ -77,17 +77,37 @@ export declare function jobLogSummary(result: RunResult): string;
77
77
  export declare function gateLogLines(result: RunResult, options?: {
78
78
  terminal?: boolean;
79
79
  }): string[];
80
+ type VersionSkew = NonNullable<GateOutcome['versionSkew']>;
81
+ /** Where a skewed binary came from, in words. Never a machine path. */
82
+ export declare function skewPlace(skew: VersionSkew): string;
80
83
  /**
81
- * One warning per gate that was found on PATH at a version other than the one
82
- * this run expected (the Action's pin).
84
+ * The reported version as it may be printed. The probe for the family gates
85
+ * accepts anything after x.y.z on the first line, and this text reaches a
86
+ * workflow command and the step summary, so only version characters are
87
+ * kept.
88
+ */
89
+ export declare function skewFound(skew: VersionSkew): string;
90
+ /**
91
+ * One warning per gate whose resolved binary reported a version other than
92
+ * the one this run expected (the Action's pin), wherever it was found:
93
+ * node_modules/.bin, PATH or a policy command.
83
94
  *
84
- * For the job log only: it names where the binary was found, and an absolute
85
- * path has no business in a published SARIF log or a pull request comment, so
86
- * this is never part of either report. A warning and nothing more. Resolution
87
- * is unchanged and the gate ran (or was refused) exactly as it would have
88
- * without it.
95
+ * For the job log: it names the file the binary was found at, which for PATH
96
+ * is an absolute machine path, so this exact line is never part of a report.
97
+ * The reports carry the same fact without that path (gateSection here, the
98
+ * conductor/version-skew notification in SARIF). A warning and nothing more.
99
+ * Resolution is unchanged and the gate ran (or was refused) exactly as it
100
+ * would have without it.
89
101
  */
90
102
  export declare function versionSkewWarnings(result: RunResult): string[];
103
+ /**
104
+ * The same warnings as GitHub Actions `::warning::` annotations, so a skew
105
+ * shows on the run's summary page without anybody opening the log. No
106
+ * machine path: the location is named in words.
107
+ */
108
+ export declare function versionSkewAnnotations(result: RunResult): string[];
109
+ /** The step-summary lines for the same warnings, one paragraph each. */
110
+ export declare function versionSkewSummaryLines(result: RunResult): string[];
91
111
  /**
92
112
  * The verdict token: a label for the umbrella's OWN exit decision, in a
93
113
  * closed set, so a person or a script reading a report or a job summary gets
@@ -201,3 +221,4 @@ export declare const INTENT_SPEC_LINES: readonly ["intent-spec: none chosen, two
201
221
  */
202
222
  export declare const DEP_GUARD_DEADLINE_CODE = "online-deadline-exceeded";
203
223
  export declare function renderText(result: RunResult, options?: TextOptions): string;
224
+ export {};
@@ -316,6 +316,12 @@ function gateSection(gate, verbose, refusedOnTerminal = false) {
316
316
  if (gate.gateOwnOption !== undefined) {
317
317
  lines.push(` note conductor/option-is-gate-own: ${gate.gateOwnOption}`);
318
318
  }
319
+ // Under the header too: the header names the version and the location,
320
+ // and this says that version is not the one the run was pinned to.
321
+ const skew = versionSkewLine(gate);
322
+ if (skew !== null) {
323
+ lines.push(skew);
324
+ }
319
325
  const contract = contractLine(gate);
320
326
  if (contract !== null) {
321
327
  lines.push(contract);
@@ -740,26 +746,96 @@ export function gateLogLines(result, options = {}) {
740
746
  }
741
747
  return lines;
742
748
  }
749
+ /** Where a skewed binary came from, in words. Never a machine path. */
750
+ export function skewPlace(skew) {
751
+ return skew.source === 'node_modules'
752
+ ? 'node_modules/.bin'
753
+ : skew.source === 'path'
754
+ ? 'PATH'
755
+ : 'the policy command';
756
+ }
757
+ /**
758
+ * The reported version as it may be printed. The probe for the family gates
759
+ * accepts anything after x.y.z on the first line, and this text reaches a
760
+ * workflow command and the step summary, so only version characters are
761
+ * kept.
762
+ */
763
+ export function skewFound(skew) {
764
+ return skew.found.replace(/[^0-9A-Za-z.+-]/g, '').slice(0, 64);
765
+ }
766
+ /** The remedy, which depends on where the binary came from. */
767
+ function skewFix(product, skew) {
768
+ if (skew.source === 'node_modules') {
769
+ return (`Fix: bump or remove the repository's own ${product} devDependency. node_modules/.bin outranks ` +
770
+ "PATH outside a pull request, so on a push run it shadows the action's install.");
771
+ }
772
+ if (skew.source === 'path') {
773
+ return `Fix: remove the other ${product} from PATH, or install ${skew.expected}.`;
774
+ }
775
+ return `Fix: point the policy command at ${product} ${skew.expected}, or remove the command override.`;
776
+ }
743
777
  /**
744
- * One warning per gate that was found on PATH at a version other than the one
745
- * this run expected (the Action's pin).
778
+ * One warning per gate whose resolved binary reported a version other than
779
+ * the one this run expected (the Action's pin), wherever it was found:
780
+ * node_modules/.bin, PATH or a policy command.
746
781
  *
747
- * For the job log only: it names where the binary was found, and an absolute
748
- * path has no business in a published SARIF log or a pull request comment, so
749
- * this is never part of either report. A warning and nothing more. Resolution
750
- * is unchanged and the gate ran (or was refused) exactly as it would have
751
- * without it.
782
+ * For the job log: it names the file the binary was found at, which for PATH
783
+ * is an absolute machine path, so this exact line is never part of a report.
784
+ * The reports carry the same fact without that path (gateSection here, the
785
+ * conductor/version-skew notification in SARIF). A warning and nothing more.
786
+ * Resolution is unchanged and the gate ran (or was refused) exactly as it
787
+ * would have without it.
752
788
  */
753
789
  export function versionSkewWarnings(result) {
754
790
  return result.gates.flatMap((gate) => gate.versionSkew === undefined
755
791
  ? []
756
792
  : [
757
- `conductor: warning: ${gate.product} resolved from PATH reports version ${gate.versionSkew.found}, ` +
758
- `but this run expects ${gate.versionSkew.expected} (the version the action pinned). ` +
759
- `It was found at ${gate.versionSkew.path}. Resolution is unchanged and that binary was used. ` +
760
- `Fix: remove the other ${gate.product} from PATH, or install ${gate.versionSkew.expected}.`,
793
+ `conductor: warning: ${gate.product} resolved from ${skewPlace(gate.versionSkew)} reports version ` +
794
+ `${skewFound(gate.versionSkew)}, but this run expects ${gate.versionSkew.expected} (the version the ` +
795
+ `action pinned). It was found at ${gate.versionSkew.path}. Resolution is unchanged and that binary ` +
796
+ `was used. ${skewFix(gate.product, gate.versionSkew)}`,
797
+ ]);
798
+ }
799
+ /** A workflow-command message: `%`, CR and LF escaped, as the runner requires. */
800
+ function workflowCommandData(text) {
801
+ return text.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
802
+ }
803
+ /**
804
+ * The same warnings as GitHub Actions `::warning::` annotations, so a skew
805
+ * shows on the run's summary page without anybody opening the log. No
806
+ * machine path: the location is named in words.
807
+ */
808
+ export function versionSkewAnnotations(result) {
809
+ return result.gates.flatMap((gate) => gate.versionSkew === undefined
810
+ ? []
811
+ : [
812
+ '::warning title=conductor version skew::' +
813
+ workflowCommandData(`${gate.product} resolved from ${skewPlace(gate.versionSkew)} reports version ` +
814
+ `${skewFound(gate.versionSkew)}, but this run expects ${gate.versionSkew.expected} (the version ` +
815
+ `the action pinned). Resolution is unchanged and that binary was used. ` +
816
+ skewFix(gate.product, gate.versionSkew)),
817
+ ]);
818
+ }
819
+ /** The step-summary lines for the same warnings, one paragraph each. */
820
+ export function versionSkewSummaryLines(result) {
821
+ return result.gates.flatMap((gate) => gate.versionSkew === undefined
822
+ ? []
823
+ : [
824
+ `conductor warning: ${gate.product} ${skewFound(gate.versionSkew)} ran from ` +
825
+ `${skewPlace(gate.versionSkew)}, but this run expects ${gate.versionSkew.expected} (the version ` +
826
+ `the action pinned). ${skewFix(gate.product, gate.versionSkew)}`,
761
827
  ]);
762
828
  }
829
+ /** The gate-block line of the text report. Repository-relative paths only. */
830
+ function versionSkewLine(gate) {
831
+ const skew = gate.versionSkew;
832
+ if (skew === undefined) {
833
+ return null;
834
+ }
835
+ const from = skew.source === 'node_modules' ? skew.path : skewPlace(skew);
836
+ return (` ! conductor/version-skew: ${gate.product} ${skewFound(skew)} ran, from ${from}, but this run expects ` +
837
+ `${skew.expected} (the version the action pinned). Resolution is unchanged. ${skewFix(gate.product, skew)}`);
838
+ }
763
839
  /**
764
840
  * How many blocking findings one gate that RAN is carrying, for the token.
765
841
  *
@@ -30,6 +30,10 @@ const EXACT_NAMES = new Set([
30
30
  'deno.lock',
31
31
  'mix.exs',
32
32
  'pubspec.yaml',
33
+ // Added 2026-10-18 (audit finding N8): dep's lockfile, which osv-scanner
34
+ // 2.4.0 has no extractor for ("could not determine extractor suitable to
35
+ // this file", measured), so it is never handed over.
36
+ 'Gopkg.lock',
33
37
  ]);
34
38
  const MAX_LISTED = 12;
35
39
  const SKIPPED_DIRS = new Set(['node_modules', 'vendor', 'testdata']);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.11.0",
3
+ "version": "0.12.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [