@vaultcompass/conductor 0.10.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.
@@ -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';
@@ -582,9 +583,54 @@ function skippedNotifications(result) {
582
583
  // body on purpose, so it is a notification and never a result.
583
584
  id: `${gate.product}/${gate.reason}`,
584
585
  message: `The ${gate.role} gate (${gate.product}) checked nothing on this branch. ${gate.detail}`,
585
- details: { role: gate.role, product: gate.product, reason: gate.reason },
586
+ details: {
587
+ role: gate.role,
588
+ product: gate.product,
589
+ reason: gate.reason,
590
+ // The full tied list here; the message caps it for reading.
591
+ ...(gate.selection?.why === 'ambiguous'
592
+ ? { tied: gate.selection.tied, tiedCount: gate.selection.tied.length }
593
+ : {}),
594
+ ...(gate.selection === undefined || gate.selection.legacy === null
595
+ ? {}
596
+ : { legacySelection: gate.selection.legacy }),
597
+ },
586
598
  }));
587
599
  }
600
+ /**
601
+ * A spec the branch-name convention chose on thin evidence, as a NOTE.
602
+ *
603
+ * A notification by the rule above: it says how much this run's verdict can
604
+ * be trusted to be about the right contract, which is a statement about the
605
+ * run's coverage, true on every run of this branch until somebody pins the
606
+ * spec. The verdict and enforcement are unchanged by it.
607
+ */
608
+ function weakMatchNotifications(result) {
609
+ return result.gates.flatMap((gate) => {
610
+ const source = gate.intent?.contractSource;
611
+ if (source === undefined || source.kind !== 'imported' || source.match?.strength !== 'weak') {
612
+ return [];
613
+ }
614
+ const match = source.match;
615
+ return [
616
+ {
617
+ id: `${gate.product}/spec-weak-match`,
618
+ message: `The ${gate.role} gate (${gate.product}) used ${source.spec}, chosen by the branch name on ` +
619
+ `a weak match (${match.weakBecause.join(', ')}). Name the spec with a "Spec: <path>" line ` +
620
+ 'or --spec, or rename the branch to the spec name, to be sure it is the right contract.',
621
+ details: {
622
+ role: gate.role,
623
+ product: gate.product,
624
+ spec: source.spec,
625
+ shared: match.shared,
626
+ weakBecause: match.weakBecause,
627
+ runnerUp: match.runnerUp,
628
+ ...(match.legacy === null ? {} : { legacySelection: match.legacy }),
629
+ },
630
+ },
631
+ ];
632
+ });
633
+ }
588
634
  /**
589
635
  * intent-guard 1.7.0's own advance-notice warnings, as notifications.
590
636
  *
@@ -784,6 +830,40 @@ function nodeModulesSkippedNotifications(result) {
784
830
  },
785
831
  ];
786
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
+ }
787
867
  /**
788
868
  * A passthrough option that is a gate's own setting under a name conductor
789
869
  * also uses (gitleaks' `options.timeout`), as notifications. A NOTE: nothing
@@ -917,6 +997,13 @@ export function renderSarif(result, umbrellaVersion) {
917
997
  ...(gate.intent === undefined
918
998
  ? {}
919
999
  : { contractSource: gate.intent.contractSource, baseRef: gate.intent.baseRef }),
1000
+ // What 0.10.0 would have chosen, when the branch-name convention now
1001
+ // chooses a different spec. Reporting only, for one minor release.
1002
+ ...(gate.intent?.contractSource.kind === 'imported' &&
1003
+ gate.intent.contractSource.match !== undefined &&
1004
+ gate.intent.contractSource.match.legacy !== null
1005
+ ? { legacySelection: gate.intent.contractSource.match.legacy }
1006
+ : {}),
920
1007
  // The gate's own run facts (issue #72: the lockfiles the umbrella
921
1008
  // handed osv-scanner, and dep-guard's online-lookup reporting), the
922
1009
  // same bag the text report renders as scalars. Carried verbatim and
@@ -945,11 +1032,13 @@ export function renderSarif(result, umbrellaVersion) {
945
1032
  ...skippedNotifications(result),
946
1033
  ...unenforcedNotifications(result),
947
1034
  ...legacyStateDirNotifications(result),
1035
+ ...weakMatchNotifications(result),
948
1036
  ...trustBaseRefusedNotifications(result),
949
1037
  ...programRefusedNotifications(result),
950
1038
  ...proposalNotifications(result),
951
1039
  ...trustBaseWithheldNotifications(result),
952
1040
  ...nodeModulesSkippedNotifications(result),
1041
+ ...versionSkewNotifications(result),
953
1042
  ...intentWarningNotifications(result),
954
1043
  ...gateOwnOptionNotifications(result),
955
1044
  ];
@@ -1,3 +1,5 @@
1
+ import { type GateOutcome } from './gate-runner.js';
2
+ import type { ReportedMatch } from './intent-prepare.js';
1
3
  import type { RunResult } from './run.js';
2
4
  /**
3
5
  * How many entries a section prints before it rolls the rest up into one
@@ -8,6 +10,8 @@ import type { RunResult } from './run.js';
8
10
  * SARIF log, --verbose prints them, and the exit code never reads this.
9
11
  */
10
12
  export declare const FINDINGS_SHOWN_PER_GATE = 20;
13
+ /** The convention match behind a gate's contract, when the branch name chose it. */
14
+ export declare function conventionMatch(gate: GateOutcome): ReportedMatch | null;
11
15
  /**
12
16
  * The one sentence the whole of pull-request mode has to fit into.
13
17
  *
@@ -73,17 +77,37 @@ export declare function jobLogSummary(result: RunResult): string;
73
77
  export declare function gateLogLines(result: RunResult, options?: {
74
78
  terminal?: boolean;
75
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;
76
83
  /**
77
- * One warning per gate that was found on PATH at a version other than the one
78
- * 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.
79
94
  *
80
- * For the job log only: it names where the binary was found, and an absolute
81
- * path has no business in a published SARIF log or a pull request comment, so
82
- * this is never part of either report. A warning and nothing more. Resolution
83
- * is unchanged and the gate ran (or was refused) exactly as it would have
84
- * 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.
85
101
  */
86
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[];
87
111
  /**
88
112
  * The verdict token: a label for the umbrella's OWN exit decision, in a
89
113
  * closed set, so a person or a script reading a report or a job summary gets
@@ -183,6 +207,13 @@ export interface TextOptions {
183
207
  */
184
208
  terminal?: boolean;
185
209
  }
210
+ /**
211
+ * The intent-spec header line: a CLOSED SET of four strings, in precedence
212
+ * order, naming no branch, no file and no token. The Action copies one to the
213
+ * step summary only on a whole-line match, so nothing the repository or the
214
+ * head branch carries can reach that summary through it.
215
+ */
216
+ export declare const INTENT_SPEC_LINES: readonly ["intent-spec: none chosen, two or more specs matched the branch equally", "intent-spec: none chosen, this branch chose a spec before conductor 0.11.0", "intent-spec: a different spec chosen than before conductor 0.11.0, see the report", "intent-spec: weak match, see the intent gate in the report"];
186
217
  /**
187
218
  * dep-guard's own diagnostic code for an online budget that ran out before
188
219
  * every lookup was made (dep-guard core, online/deadline.ts,
@@ -190,3 +221,4 @@ export interface TextOptions {
190
221
  */
191
222
  export declare const DEP_GUARD_DEADLINE_CODE = "online-deadline-exceeded";
192
223
  export declare function renderText(result: RunResult, options?: TextOptions): string;
224
+ export {};