@vaultcompass/conductor 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.js CHANGED
@@ -7,7 +7,7 @@
7
7
  // decisions be tested without a subprocess.
8
8
  import { Command, CommanderError } from 'commander';
9
9
  import { execFileSync } from 'node:child_process';
10
- import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
10
+ import { readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
11
11
  import path from 'node:path';
12
12
  import { fileURLToPath } from 'node:url';
13
13
  import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
@@ -16,7 +16,7 @@ import { renderSarif } from './output-sarif.js';
16
16
  import { jobLogSummary, renderText } from './output-text.js';
17
17
  import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
18
18
  import { refusedTrustBase, runAll } from './run.js';
19
- import { policyDiffers, readPolicyAtRef, refuseTrustBaseRef } from './trust-base.js';
19
+ import { headTreeEqualsBase, policyDiffers, readPolicyAtRef, refuseTrustBaseForPullRequest, refuseTrustBaseRef, } from './trust-base.js';
20
20
  const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
21
21
  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
22
22
  /**
@@ -39,6 +39,30 @@ const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
39
39
  * one line on stderr with no stack and the could-not-run exit code, so
40
40
  * nothing here has to know about either.
41
41
  */
42
+ /**
43
+ * True when `cwd` is itself a `.git` directory (or another directory git
44
+ * manages as one, such as a worktree's own git dir), rather than a working
45
+ * tree with no repository at all.
46
+ *
47
+ * Only consulted once `--show-toplevel` has already failed, so the extra
48
+ * spawn is on an error path already about to fail the whole command, never
49
+ * on the path every ordinary run takes. Both failure shapes exit non-zero,
50
+ * so this is what tells "point conductor at a .git directory" apart from
51
+ * "point conductor at a plain, ungoverned directory" without guessing from
52
+ * the path's spelling.
53
+ */
54
+ function isGitDirectory(cwd) {
55
+ try {
56
+ return (execFileSync('git', ['rev-parse', '--is-inside-git-dir'], {
57
+ cwd,
58
+ encoding: 'utf8',
59
+ stdio: ['ignore', 'pipe', 'ignore'],
60
+ }).trim() === 'true');
61
+ }
62
+ catch {
63
+ return false;
64
+ }
65
+ }
42
66
  function repoRoot(cwd) {
43
67
  try {
44
68
  return execFileSync('git', ['rev-parse', '--show-toplevel'], {
@@ -56,6 +80,10 @@ function repoRoot(cwd) {
56
80
  // git ran and refused. The directory is named because it is the one
57
81
  // thing the reader has to check, and it is the directory they typed
58
82
  // the command in rather than anything internal to this tool.
83
+ if (isGitDirectory(cwd)) {
84
+ throw new Error(`${cwd} is a git directory, not a working tree. Point conductor at the repository's ` +
85
+ 'working tree instead of at its .git directory.');
86
+ }
59
87
  throw new Error(`not a git repository: ${cwd}. conductor anchors every gate at the working-tree ` +
60
88
  'root, so run it inside a checkout.');
61
89
  }
@@ -65,6 +93,54 @@ function repoRoot(cwd) {
65
93
  throw new Error(`git could not be run to find the repository root: ${err.message}`);
66
94
  }
67
95
  }
96
+ /**
97
+ * The repository root for one command, from --project when it was given and
98
+ * from the working directory otherwise (issue #55).
99
+ *
100
+ * --project changes WHERE the repository is, never WHAT is trusted: once
101
+ * resolved, the root it names goes through the exact same discovery as the
102
+ * working directory always has, `repoRoot`'s own `git rev-parse
103
+ * --show-toplevel`, so a subdirectory of a repository resolves to that
104
+ * repository's top level exactly as a bare `conductor init` or `conductor
105
+ * run` from that subdirectory already does. Nothing downstream of this
106
+ * function -- the trust-base checks, the node_modules/.bin skip on a
107
+ * pull-request run, the program-vetting rules -- reads the working directory
108
+ * again; every one of them takes this root explicitly.
109
+ *
110
+ * A relative value resolves against the working directory, never against
111
+ * anything already discovered, so this has to run before any git call. A
112
+ * path that does not exist, is not a directory, or is not inside a git
113
+ * repository is a usage error naming the path, never a silent fall back to
114
+ * the working directory: guessing which repository a scripted caller meant
115
+ * is how a CI job ends up gating the wrong tree while reporting a clean run
116
+ * of nothing.
117
+ */
118
+ function resolveProjectRoot(cwd, project) {
119
+ if (project === undefined) {
120
+ return repoRoot(cwd);
121
+ }
122
+ const resolved = path.resolve(cwd, project);
123
+ let stat;
124
+ try {
125
+ stat = statSync(resolved);
126
+ }
127
+ catch {
128
+ throw new Error(`--project ${project}: no such directory (resolved to ${resolved}).`);
129
+ }
130
+ if (!stat.isDirectory()) {
131
+ throw new Error(`--project ${project}: not a directory (resolved to ${resolved}).`);
132
+ }
133
+ // repoRoot names `resolved` in its own "not a git repository" sentence,
134
+ // which is what makes that refusal name the path here too, without a
135
+ // second, separately-worded check that could drift from the one bare `cwd`
136
+ // already goes through.
137
+ return repoRoot(resolved);
138
+ }
139
+ const PROJECT_OPTION_HELP = 'run against this directory instead of the current one, resolved to its repository root ' +
140
+ 'the same way the current directory already is: a subdirectory resolves to the top of that ' +
141
+ 'repository. Relative values resolve against the current directory. A path that does not ' +
142
+ 'exist, is not a directory, or is not inside a git repository is a usage error (exit 2) ' +
143
+ 'naming the path, never a silent fall back to the current directory.';
68
144
  /**
69
145
  * The process exit code for a run, with --advisory applied.
70
146
  *
@@ -127,11 +203,22 @@ function inventoryFromHead(root, overrides) {
127
203
  return { version: 1, gates: {}, report: { format: 'text' } };
128
204
  }
129
205
  }
130
- function policyForRun(root, trustBase, overrides) {
206
+ function policyForRun(root, trustBase, overrides, githubBaseRef) {
131
207
  if (trustBase === undefined) {
132
208
  return { kind: 'policy', policy: applyCliOverrides(loadPolicy(root), overrides) };
133
209
  }
134
- const refusal = refuseTrustBaseRef(root, trustBase);
210
+ // DEFENCE IN DEPTH, ISSUE #58. action.yml's validate step already refuses
211
+ // an explicit trust-base input outright on a pull_request event; this is
212
+ // the same rule for anyone invoking the CLI directly in CI, bypassing that
213
+ // step. Checked BEFORE refuseTrustBaseRef and deliberately narrower than
214
+ // it: it says nothing about HEAD or about tree equality, only about
215
+ // whether the given ref agrees with origin/<GITHUB_BASE_REF>, which is
216
+ // exactly what the composite action itself always passes. So on an
217
+ // ordinary pull-request run this returns null immediately and
218
+ // refuseTrustBaseRef runs its own checks unchanged, the equal-tree
219
+ // first-parent exception (issue #69/#73) included.
220
+ const pullRequestRefusal = refuseTrustBaseForPullRequest(root, trustBase, githubBaseRef);
221
+ const refusal = pullRequestRefusal ?? refuseTrustBaseRef(root, trustBase);
135
222
  if (refusal !== null) {
136
223
  return {
137
224
  kind: 'refused',
@@ -191,6 +278,12 @@ function policyForRun(root, trustBase, overrides) {
191
278
  ref: trustBase,
192
279
  policyChanged: policyDiffers(baseText, headText),
193
280
  refusal: null,
281
+ // Computed AFTER refuseTrustBaseRef has already returned null, on the
282
+ // one shape that check accepts despite an identical tree: a merge
283
+ // commit whose first parent is this ref (issue #69). runAll reads this
284
+ // to run only the gates whose profile says readsHistory and to report
285
+ // every other enabled gate as tree-unchanged instead of spawning it.
286
+ treeUnchanged: headTreeEqualsBase(root, trustBase),
194
287
  },
195
288
  };
196
289
  }
@@ -254,50 +347,84 @@ export function buildProgram() {
254
347
  .option('--force', 'act on a file that has changed since init wrote it: replace a managed hook somebody has ' +
255
348
  'edited (needs --hook), or with --revert remove one and restore any adopted hook')
256
349
  .option('--json', 'print the result as JSON')
350
+ .option('--project <dir>', PROJECT_OPTION_HELP)
257
351
  .exitOverride()
258
352
  .action((options) => {
259
- const cwd = process.cwd();
260
- const shared = { cwd, pathValue: process.env.PATH ?? '' };
261
- if (options.revert) {
262
- const result = revertInit({
353
+ try {
354
+ // options.project === undefined takes the EXACT path main always
355
+ // did: process.cwd() straight through, with no resolveProjectRoot
356
+ // call at all. planInit and revertInit already do their own
357
+ // repoRootOf(options.cwd) and report a non-repository as a
358
+ // structured conflict (not-a-git-repository, JSON under --json,
359
+ // exit 2 through the ordinary result.ok branch below) rather than
360
+ // throwing, and planInit checks flag-requires-hook (--adopt or
361
+ // --force without --hook) BEFORE it ever asks whether it is in a
362
+ // repository at all. Calling resolveProjectRoot unconditionally
363
+ // here used to short-circuit both of those: it threw its own
364
+ // differently-worded, JSON-less error before planInit ever ran, so
365
+ // a plain "conductor init" outside a repository stopped matching
366
+ // main, and "--adopt" without "--hook" outside a repository
367
+ // reported the wrong conflict. Only an EXPLICIT --project goes
368
+ // through resolveProjectRoot, whose own usage errors (a path that
369
+ // does not exist, is not a directory, or is not inside a git
370
+ // repository) are new behaviour this flag introduces on purpose.
371
+ const cwd = options.project === undefined
372
+ ? process.cwd()
373
+ : resolveProjectRoot(process.cwd(), options.project);
374
+ const shared = { cwd, pathValue: process.env.PATH ?? '' };
375
+ if (options.revert) {
376
+ const result = revertInit({
377
+ ...shared,
378
+ force: Boolean(options.force),
379
+ dryRun: Boolean(options.dryRun),
380
+ });
381
+ const rendered = `${renderRevertHuman(result)}\n`;
382
+ if (options.json) {
383
+ process.stdout.write(`${JSON.stringify(result)}\n`);
384
+ }
385
+ else if (result.ok) {
386
+ process.stdout.write(rendered);
387
+ }
388
+ else {
389
+ // A partial revert left something behind, so it is not success
390
+ // output. Writing it to stdout would let a script pipe it past a
391
+ // reader who needed to see it.
392
+ process.stderr.write(rendered);
393
+ }
394
+ process.exitCode = result.ok ? 0 : EXIT_COULD_NOT_RUN;
395
+ return;
396
+ }
397
+ const initOptions = {
263
398
  ...shared,
264
- force: Boolean(options.force),
265
- dryRun: Boolean(options.dryRun),
266
- });
267
- const rendered = `${renderRevertHuman(result)}\n`;
399
+ ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
400
+ ...(options.hook === undefined ? {} : { hook: options.hook }),
401
+ ...(options.adopt === undefined ? {} : { adopt: options.adopt }),
402
+ ...(options.force === undefined ? {} : { force: options.force }),
403
+ };
404
+ const result = applyInit(planInit(initOptions), initOptions);
268
405
  if (options.json) {
269
406
  process.stdout.write(`${JSON.stringify(result)}\n`);
270
407
  }
271
408
  else if (result.ok) {
272
- process.stdout.write(rendered);
409
+ process.stdout.write(`${renderInitHuman(result)}\n`);
273
410
  }
274
411
  else {
275
- // A partial revert left something behind, so it is not success
276
- // output. Writing it to stdout would let a script pipe it past a
277
- // reader who needed to see it.
278
- process.stderr.write(rendered);
412
+ process.stderr.write(`${renderInitHuman(result)}\n`);
279
413
  }
280
414
  process.exitCode = result.ok ? 0 : EXIT_COULD_NOT_RUN;
281
- return;
282
415
  }
283
- const initOptions = {
284
- ...shared,
285
- ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
286
- ...(options.hook === undefined ? {} : { hook: options.hook }),
287
- ...(options.adopt === undefined ? {} : { adopt: options.adopt }),
288
- ...(options.force === undefined ? {} : { force: options.force }),
289
- };
290
- const result = applyInit(planInit(initOptions), initOptions);
291
- if (options.json) {
292
- process.stdout.write(`${JSON.stringify(result)}\n`);
293
- }
294
- else if (result.ok) {
295
- process.stdout.write(`${renderInitHuman(result)}\n`);
296
- }
297
- else {
298
- process.stderr.write(`${renderInitHuman(result)}\n`);
416
+ catch (err) {
417
+ // planInit, applyInit and revertInit report every ordinary
418
+ // conflict as a structured result rather than throwing, exactly as
419
+ // they did before this flag existed, so in practice only an
420
+ // explicit --project's own usage error reaches here. But this is
421
+ // not narrowed to that: any throw from this block lands here and
422
+ // gets the same one-line, no-stack treatment main's own outer catch
423
+ // gives an uncaught error, which is what this local catch replaces
424
+ // for the init command, the same shape "run"'s own catch below
425
+ // uses for the same kind of failure.
426
+ process.exitCode = fail(`conductor: ${err instanceof Error ? err.message : String(err)}`);
299
427
  }
300
- process.exitCode = result.ok ? 0 : EXIT_COULD_NOT_RUN;
301
428
  });
302
429
  program
303
430
  .command('run')
@@ -313,21 +440,23 @@ export function buildProgram() {
313
440
  .option('--compact-on-refusal', 'when the trust base was refused and no gate ran, print a short body instead of the full refusal report: the version, the verdict, and the refusal reason (with its remedy, when one applies), never the full per-gate report. Built for the pull-request-comment step; every other run is unaffected, whatever --verbose says. Text output only; SARIF is unaffected.')
314
441
  .option('--gate <role>', 'restrict the run to this role; repeatable', (value, previous = []) => [...previous, value])
315
442
  .option('--advisory', 'maps exit 1 (every enabled gate ran and at least one blocked) to exit 0, so a blocking finding never fails this run. A gate that could not run is unaffected and still exits 2: advisory changes what a FINDING does, never what a broken gate does. The report is unchanged and a blocking finding still prints as BLOCKING; only the process exit code and the verdict line, which says findings were advisory, are different.')
443
+ .option('--project <dir>', PROJECT_OPTION_HELP)
316
444
  .exitOverride()
317
445
  .action((options) => {
318
446
  const cwd = process.cwd();
319
447
  try {
320
- // Inside the try, because repoRoot now reports rather than guesses,
321
- // and the catch below is what turns any of its three sentences into
322
- // one line on stderr and the could-not-run exit code.
323
- const root = repoRoot(cwd);
448
+ // Inside the try, because resolveProjectRoot (like repoRoot before
449
+ // it) reports rather than guesses, and the catch below is what turns
450
+ // any of its sentences into one line on stderr and the could-not-run
451
+ // exit code.
452
+ const root = resolveProjectRoot(cwd, options.project);
324
453
  const overrides = {
325
454
  ...(parseRoles(options.gate) === undefined
326
455
  ? {}
327
456
  : { gates: parseRoles(options.gate) }),
328
457
  };
329
458
  const stage = parseStage(options.stage);
330
- const source = policyForRun(root, options.trustBase, overrides);
459
+ const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF);
331
460
  const policy = source.kind === 'policy' ? source.policy : source.inventory;
332
461
  const format = parseFormat(options.format ?? policy.report.format);
333
462
  const result = source.kind === 'refused'
@@ -409,11 +409,17 @@ function probeVersion(binary, product, repoRoot, timeoutMs) {
409
409
  * `context.blocked` is whether the gate's exit said it blocked. The npm gates
410
410
  * carry that in their own JSON and ignore it; the external tools' reports do
411
411
  * not, so their normalizers take it from here.
412
+ *
413
+ * `context.online` and `context.lockfiles` are read from the umbrella's OWN
414
+ * constructed argv, never from a gate's JSON (issue #72): whether --online
415
+ * was passed and which lockfiles were handed over with --lockfile are
416
+ * questions about what this run asked for, which the umbrella already knows
417
+ * before the child ever answers.
412
418
  */
413
419
  function normalizeFor(product, parsed, version, context) {
414
420
  switch (product) {
415
421
  case 'dep-guard':
416
- return normalizeDepGuard(parsed, version);
422
+ return normalizeDepGuard(parsed, version, context.online);
417
423
  case 'vault-guard':
418
424
  return normalizeVaultGuard(parsed, version);
419
425
  case 'intent-guard':
@@ -421,7 +427,7 @@ function normalizeFor(product, parsed, version, context) {
421
427
  case 'gitleaks':
422
428
  return normalizeGitleaks(parsed, version, context.blocked);
423
429
  case 'osv-scanner':
424
- return normalizeOsvScanner(parsed, version, context.blocked, context.roots);
430
+ return normalizeOsvScanner(parsed, version, context.blocked, context.roots, context.lockfiles);
425
431
  }
426
432
  }
427
433
  /**
@@ -1046,6 +1052,10 @@ function spawnAndRead(ctx) {
1046
1052
  const normalized = normalizeFor(gate.product, parsed, version, {
1047
1053
  blocked,
1048
1054
  roots: rootSpellings(options.repoRoot),
1055
+ // The literal flag, read off the argv this run actually spawned with,
1056
+ // not off gate.options: the argv is what dep-guard was actually told.
1057
+ online: argv.includes('--online'),
1058
+ lockfiles: external.lockfiles ?? [],
1049
1059
  });
1050
1060
  return {
1051
1061
  ...withRun,
@@ -1,7 +1,16 @@
1
1
  import { type Finding, type NormalizedGateOutput, type Severity } from './envelope.js';
2
2
  import type { GateRole, Product } from './policy.js';
3
- export declare function normalizeDepGuard(raw: unknown, version: string | null): NormalizedGateOutput;
3
+ export declare function normalizeDepGuard(raw: unknown, version: string | null,
4
+ /** Whether the umbrella passed --online to dep-guard, read from its own argv. */
5
+ onlineRequested?: boolean): NormalizedGateOutput;
4
6
  export declare function normalizeVaultGuard(raw: unknown, version: string | null): NormalizedGateOutput;
7
+ /**
8
+ * intent-guard's own namespace for its advance-notice warnings, not the
9
+ * umbrella's: the umbrella never mints a `conductor/` id for this, because
10
+ * the statement being relayed is entirely intent-guard's own (see AGENTS.md
11
+ * on the umbrella's fixed set of ids).
12
+ */
13
+ export declare const INTENT_WARNING = "intent-guard/warning";
5
14
  /**
6
15
  * The three ways the intent gate can block on the STATE of the contract
7
16
  * rather than on anything in the diff.
@@ -41,7 +50,9 @@ export declare function normalizeGitleaks(raw: unknown, version: string | null,
41
50
  export declare function cvssToSeverity(score: number | null): Severity;
42
51
  export declare function normalizeOsvScanner(raw: unknown, version: string | null, blocked: boolean,
43
52
  /** The scan root as a path osv-scanner may have printed it, in any spelling. */
44
- roots?: readonly string[]): NormalizedGateOutput;
53
+ roots?: readonly string[],
54
+ /** The lockfiles the umbrella passed with --lockfile, repository-relative. */
55
+ lockfiles?: readonly string[]): NormalizedGateOutput;
45
56
  export type GateProblemRule = 'conductor/gate-missing' | 'conductor/gate-output-unparseable' | 'conductor/gate-failed';
46
57
  /**
47
58
  * The finding raised when an ENABLED gate's binary cannot be found.
package/dist/normalize.js CHANGED
@@ -114,13 +114,42 @@ function readDiagnostics(value, product, where) {
114
114
  };
115
115
  });
116
116
  }
117
- export function normalizeDepGuard(raw, version) {
117
+ function readOnlineInfo(value) {
118
+ if (!isRecord(value)) {
119
+ return null;
120
+ }
121
+ const info = {};
122
+ if (value.enabled !== undefined) {
123
+ if (typeof value.enabled !== 'boolean') {
124
+ return null;
125
+ }
126
+ info.enabled = value.enabled;
127
+ }
128
+ if (value.lookupsAttempted !== undefined) {
129
+ if (typeof value.lookupsAttempted !== 'number' || !Number.isFinite(value.lookupsAttempted)) {
130
+ return null;
131
+ }
132
+ info.lookupsAttempted = value.lookupsAttempted;
133
+ }
134
+ if (value.lookupsSkippedByDeadline !== undefined) {
135
+ if (typeof value.lookupsSkippedByDeadline !== 'number' ||
136
+ !Number.isFinite(value.lookupsSkippedByDeadline)) {
137
+ return null;
138
+ }
139
+ info.lookupsSkippedByDeadline = value.lookupsSkippedByDeadline;
140
+ }
141
+ return info;
142
+ }
143
+ export function normalizeDepGuard(raw, version,
144
+ /** Whether the umbrella passed --online to dep-guard, read from its own argv. */
145
+ onlineRequested = false) {
118
146
  const product = 'dep-guard';
119
147
  const root = needRecord(raw, product, 'the output');
120
148
  const run = needRecord(root.run, product, 'run');
121
149
  const threshold = optionalString(run.failOn, product, 'run.failOn') ?? null;
122
150
  const trustBase = readTrustBase(root.trustBase, product);
123
151
  const diagnostics = [];
152
+ const onlineInfo = readOnlineInfo(run.online);
124
153
  const findings = needArray(root.findings, product, 'findings').map((entry, index) => {
125
154
  const where = `findings[${index}]`;
126
155
  const source = needRecord(entry, product, where);
@@ -167,12 +196,34 @@ export function normalizeDepGuard(raw, version) {
167
196
  suppressed: typeof root.suppressed === 'number' ? root.suppressed : 0,
168
197
  ignored: typeof root.ignored === 'number' ? root.ignored : 0,
169
198
  // Diagnostics never move dep-guard's own exit code, so they stay out
170
- // of findings[] here too rather than becoming pseudo-findings.
199
+ // of findings[] here too rather than becoming pseudo-findings. An
200
+ // installed dep-guard old enough to have no `run.online` object, or
201
+ // one whose online object says the budget ran out, raises its own
202
+ // online-deadline-exceeded diagnostic here, and it is carried through
203
+ // unchanged rather than the umbrella minting a second note about the
204
+ // same event (issue #72 fix round: dep-guard's own diagnostic already
205
+ // names the count, so nothing here duplicates it).
171
206
  diagnostics: readDiagnostics(run.diagnostics, product, 'run.diagnostics'),
172
207
  details: {
173
208
  mode: run.mode ?? null,
174
209
  corpusBuiltAt: run.corpusBuiltAt ?? null,
175
210
  lockfileFormat: run.lockfileFormat ?? null,
211
+ // dep-guard's own `enabled` claim wins whenever the online object is
212
+ // present and valid: dep-guard can turn online checks on from
213
+ // ".dep-guard.json"'s own "online" key with no flag at all, so the
214
+ // umbrella's argv does not always know the true answer. Only when
215
+ // there is no trustworthy claim to read does this fall back to
216
+ // stating what the umbrella itself asked for, worded so it is never
217
+ // mistaken for a claim about what dep-guard actually did.
218
+ ...(onlineInfo?.enabled === undefined
219
+ ? { 'online-flag': onlineRequested ? 'passed' : 'not passed' }
220
+ : { online: onlineInfo.enabled }),
221
+ ...(onlineInfo?.lookupsAttempted === undefined
222
+ ? {}
223
+ : { lookups: onlineInfo.lookupsAttempted }),
224
+ ...(onlineInfo?.lookupsSkippedByDeadline === undefined
225
+ ? {}
226
+ : { 'skipped-by-deadline': onlineInfo.lookupsSkippedByDeadline }),
176
227
  },
177
228
  },
178
229
  diagnostics,
@@ -331,6 +382,57 @@ const DRIFT_SEVERITY = {
331
382
  info: 'low',
332
383
  proceed: 'info',
333
384
  };
385
+ /**
386
+ * intent-guard's own namespace for its advance-notice warnings, not the
387
+ * umbrella's: the umbrella never mints a `conductor/` id for this, because
388
+ * the statement being relayed is entirely intent-guard's own (see AGENTS.md
389
+ * on the umbrella's fixed set of ids).
390
+ */
391
+ export const INTENT_WARNING = 'intent-guard/warning';
392
+ /**
393
+ * intent-guard 1.7.0's own advance notice that a frozen contract's
394
+ * `protected_paths` or `allowed_paths` carries an entry no git path can
395
+ * ever match (a leading slash, an empty path segment, and the like), read
396
+ * from the optional `warnings` array. 1.7.0 warns about this; 2.0.0 turns it
397
+ * into a blocking reason (intent-guard's own budget-paths.ts).
398
+ *
399
+ * Tolerant on purpose, unlike everything else this file validates: this is
400
+ * reporting, never judgment, so a shape an installed intent-guard did not
401
+ * send correctly must never turn into a could-not-run for the gate. Absent
402
+ * (1.6.0 and earlier, which never sent this field) means none. A value that
403
+ * is not an array, or an array holding even one non-string entry, is
404
+ * ignored outright rather than partially read: half-reading it would print
405
+ * some warnings and silently drop others, which is worse than saying
406
+ * nothing until the shape is understood again.
407
+ */
408
+ function readIntentWarnings(raw) {
409
+ if (!Array.isArray(raw)) {
410
+ return [];
411
+ }
412
+ return raw.every((entry) => typeof entry === 'string') ? raw : [];
413
+ }
414
+ /**
415
+ * intent-guard 1.6.0 (issue #34) caps a constraint finding at advisory when
416
+ * its `source` is a prose rules file (CLAUDE.md, AGENTS.md, GEMINI.md,
417
+ * cursor rules): a strong match is still reported, but it never raises
418
+ * `constraint_violation`, `criticalViolated`, or the gate's own exit code.
419
+ *
420
+ * `finding_details` carries no field saying so. `strength` is "strong" for a
421
+ * capped prose match exactly the same as an uncapped one, and the
422
+ * constraint's `source` is never carried onto the finding at all. The ONLY
423
+ * surviving signal is this literal prefix, which intent-guard's own drift.ts
424
+ * puts on the message for this one case.
425
+ *
426
+ * THIS IS NOT A SAFETY NET. Nothing in this repository detects an upstream
427
+ * rewording of that prefix: there is no test against the live binary, only
428
+ * a static fixture capture, so a wording change in a future intent-guard
429
+ * release would silently stop matching here and a capped finding would go
430
+ * back to rendering as blocking with no warning anywhere in this report or
431
+ * in CI. Filed upstream as intent-guard #114, asking for a machine-readable
432
+ * per-finding field so this can stop keying on message text; this constant
433
+ * is the interim measure until that lands, not a substitute for it.
434
+ */
435
+ const ADVISORY_CONSTRAINT_PREFIX = 'advisory ';
334
436
  /**
335
437
  * The three ways the intent gate can block on the STATE of the contract
336
438
  * rather than on anything in the diff.
@@ -432,6 +534,7 @@ export function normalizeIntentGuard(raw, version) {
432
534
  fail(product, 'status', 'either "ok" or "blocked"');
433
535
  }
434
536
  const trustBase = readTrustBase(root.trustBase, product);
537
+ const warnings = readIntentWarnings(root.warnings);
435
538
  const findings = [];
436
539
  const budget = root.budget === undefined ? undefined : needRecord(root.budget, product, 'budget');
437
540
  const drift = root.drift === undefined ? undefined : needRecord(root.drift, product, 'drift');
@@ -486,6 +589,11 @@ export function normalizeIntentGuard(raw, version) {
486
589
  const where = `drift.finding_details[${index}]`;
487
590
  const detail = needRecord(rawDetail, product, where);
488
591
  const category = needString(detail.category, product, `${where}.category`);
592
+ const message = needString(detail.message, product, `${where}.message`);
593
+ // See ADVISORY_CONSTRAINT_PREFIX. A capped finding never contributed to
594
+ // driftAction, so it must not inherit that action's blocking flag or
595
+ // severity the way every other drift finding here does (issue #34).
596
+ const advisoryCapped = category === 'constraint_violation' && message.startsWith(ADVISORY_CONSTRAINT_PREFIX);
489
597
  findings.push({
490
598
  schemaVersion: 1,
491
599
  product,
@@ -494,10 +602,10 @@ export function normalizeIntentGuard(raw, version) {
494
602
  // rule id that contains a user's sentence is not a rule id. The full
495
603
  // value goes in details.
496
604
  ruleId: `intent-guard/drift.${category}`,
497
- severity: DRIFT_SEVERITY[driftAction] ?? 'info',
605
+ severity: advisoryCapped ? 'low' : (DRIFT_SEVERITY[driftAction] ?? 'info'),
498
606
  severityIsDerived: true,
499
- blocking: driftBlocks,
500
- message: needString(detail.message, product, `${where}.message`),
607
+ blocking: advisoryCapped ? false : driftBlocks,
608
+ message,
501
609
  // No paths subject: `matched` here is "tokens or paths", so treating
502
610
  // it as a path list would sometimes point at a file that does not
503
611
  // exist. It stays in details, where it is not claiming to be a location.
@@ -577,7 +685,10 @@ export function normalizeIntentGuard(raw, version) {
577
685
  failOn: null,
578
686
  suppressed: 0,
579
687
  ignored: 0,
580
- diagnostics: [],
688
+ // intent-guard's own advance-notice warnings (1.7.0's budget-path
689
+ // deprecation notes). Reporting, never a finding: no severity, no
690
+ // fingerprint, no blocking flag, and no effect on the exit code.
691
+ diagnostics: warnings.map((message) => ({ code: INTENT_WARNING, message })),
581
692
  details: {
582
693
  contractFound: root.contractFound ?? null,
583
694
  contractFrozen: root.contractFrozen ?? null,
@@ -823,9 +934,21 @@ function relativeToRoots(file, roots) {
823
934
  }
824
935
  return file;
825
936
  }
937
+ /**
938
+ * The vulnerabilities summary line's lockfile fact (issue #72): the count and
939
+ * names of the lockfiles the UMBRELLA handed osv-scanner with --lockfile,
940
+ * never osv-scanner's own results[], which 2.x prints only for a source with
941
+ * findings. A clean scan of one lockfile and a run that scanned none both
942
+ * have results: [], and only this list tells them apart.
943
+ */
944
+ function describeLockfiles(lockfiles) {
945
+ return lockfiles.length === 0 ? '0' : `${lockfiles.length} (${lockfiles.join(', ')})`;
946
+ }
826
947
  export function normalizeOsvScanner(raw, version, blocked,
827
948
  /** The scan root as a path osv-scanner may have printed it, in any spelling. */
828
- roots = []) {
949
+ roots = [],
950
+ /** The lockfiles the umbrella passed with --lockfile, repository-relative. */
951
+ lockfiles = []) {
829
952
  const product = 'osv-scanner';
830
953
  const top = needRecord(raw, product, 'the output');
831
954
  const results = needArray(top.results, product, 'results');
@@ -888,7 +1011,13 @@ roots = []) {
888
1011
  suppressed: 0,
889
1012
  ignored: 0,
890
1013
  diagnostics: [],
891
- details: { sources: results.length },
1014
+ details: {
1015
+ lockfiles: describeLockfiles(lockfiles),
1016
+ // Distinct from the old "sources" name on purpose: this counts only
1017
+ // the sources osv-scanner reported findings for, never how many were
1018
+ // scanned, and the old name read as the latter.
1019
+ 'sources-with-findings': results.length,
1020
+ },
892
1021
  },
893
1022
  diagnostics: [],
894
1023
  };