@vaultcompass/conductor 0.12.0 → 0.13.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
@@ -92,7 +92,9 @@ required.
92
92
 
93
93
  **Globally, and that is the guidance for CI too.** A devDependency is
94
94
  fine beside it for your own pre-commit hook, and nothing about a local
95
- run changed. It is not what gates your pull requests: on a pull-request
95
+ run changed, but under the Action keep it at the Action's pin or a push
96
+ run is could-not-run (see "The Action" below). It is not what gates
97
+ your pull requests: on a pull-request
96
98
  run the umbrella never looks in `node_modules/.bin` at all, because what
97
99
  is installed there is chosen by the head's own manifest and lockfile. The
98
100
  Action installs all four packages itself, globally, at versions pinned in
@@ -166,7 +168,7 @@ required.
166
168
  A commit with a staged credential in it prints the full report and exits 1:
167
169
 
168
170
  ```
169
- conductor 0.12.0
171
+ conductor 0.13.0
170
172
  verdict-token: blocked (1)
171
173
  conductor run: 2 gate(s), 1 finding(s)
172
174
 
@@ -1319,9 +1321,16 @@ workspace, and prepends that bin directory to `PATH`, so the run step invokes
1319
1321
  is **unconditional**, on push and `pull_request` alike, so there is one code
1320
1322
  path rather than one that matters and one that nobody exercises. On a push
1321
1323
  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.
1324
+ `node_modules/.bin` outranks that install and shadows the action's pin. Since
1325
+ 0.13.0, when a gate's version differs from the pin, wherever it was found
1326
+ (`node_modules/.bin`, `PATH` or a policy `command:`), conductor does not run
1327
+ it: the gate is could-not-run, reason `version-skew`, and the run exits 2,
1328
+ whatever the policy's `enforce` and whatever `advisory` say. It is named in
1329
+ the job log, as a `::error::` annotation, in the step summary and in the
1330
+ reports. A gate whose version cannot be read under the Action is
1331
+ could-not-run too, reason `version-unverified`. The fix is to bump the
1332
+ devDependency to the pin or remove it. A plain `conductor run` outside the
1333
+ Action sets no pin and is unchanged.
1325
1334
 
1326
1335
  **On a pull request those four inputs may not pin backward.** The shape check
1327
1336
  asks whether an input is an exact version; it says nothing about which one, and
@@ -1411,7 +1420,7 @@ request being judged, and the version-pin protection described above
1411
1420
  "protects nothing" against a tree that controls its own judge (the
1412
1421
  validate step's own comment in `action.yml` says so in those words). A tag
1413
1422
  moves when someone pushes it. Name this action by owner and the full commit
1414
- SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.12.0.
1423
+ SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.13.0.
1415
1424
 
1416
1425
  ```yaml
1417
1426
  name: guardrails
@@ -1433,7 +1442,7 @@ jobs:
1433
1442
  with:
1434
1443
  node-version: '22.11.0'
1435
1444
  - id: conductor
1436
- uses: vaultcompasshq/conductor@v0.12.0
1445
+ uses: vaultcompasshq/conductor@v0.13.0
1437
1446
  with:
1438
1447
  output: conductor.sarif
1439
1448
  - uses: github/codeql-action/upload-sarif@v3
@@ -1508,7 +1517,7 @@ jobs:
1508
1517
  # installs those itself, globally. Leave conductor-version unset so the
1509
1518
  # umbrella is the default in the pinned action.yml.
1510
1519
  - id: conductor
1511
- uses: vaultcompasshq/conductor@v0.12.0
1520
+ uses: vaultcompasshq/conductor@v0.13.0
1512
1521
  with:
1513
1522
  output: conductor.sarif
1514
1523
  # Exact versions, never a range and never "latest". These three
@@ -1714,7 +1723,7 @@ jobs:
1714
1723
  node-version: '22.11.0'
1715
1724
  - id: conductor
1716
1725
  timeout-minutes: 5
1717
- uses: vaultcompasshq/conductor@v0.12.0
1726
+ uses: vaultcompasshq/conductor@v0.13.0
1718
1727
  with:
1719
1728
  pr-comment: true
1720
1729
  advisory: true
@@ -1850,7 +1859,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1850
1859
  # the pull request runs before the action in this job: no install, build
1851
1860
  # or test step here; those belong in a separate job. ...
1852
1861
  - id: conductor
1853
- uses: vaultcompasshq/conductor@v0.12.0
1862
+ uses: vaultcompasshq/conductor@v0.13.0
1854
1863
  with:
1855
1864
  output: conductor.sarif
1856
1865
  pr-comment: true
@@ -1929,12 +1938,12 @@ per pull request.
1929
1938
 
1930
1939
  ```yaml
1931
1940
  - id: conductor-package-a
1932
- uses: vaultcompasshq/conductor@v0.12.0
1941
+ uses: vaultcompasshq/conductor@v0.13.0
1933
1942
  with:
1934
1943
  pr-comment: true
1935
1944
  pr-comment-marker: 'package-a'
1936
1945
  - id: conductor-package-b
1937
- uses: vaultcompasshq/conductor@v0.12.0
1946
+ uses: vaultcompasshq/conductor@v0.13.0
1938
1947
  with:
1939
1948
  pr-comment: true
1940
1949
  pr-comment-marker: 'package-b'
@@ -2055,7 +2064,7 @@ an explicit pin is unaffected, which is how a stale pin can sit unnoticed
2055
2064
  until the first pull request after the upgrade.
2056
2065
 
2057
2066
  **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
2067
+ example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.13.0`. To
2059
2068
  find the SHA for a tag, run
2060
2069
  `gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
2061
2070
  the Releases page.
@@ -2078,6 +2087,7 @@ tag with no row here has an entry that does not state its defaults; read
2078
2087
 
2079
2088
  | Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
2080
2089
  | --- | --- | --- | --- |
2090
+ | v0.13.0 | package | 0.13.0 | none (gate defaults unchanged) |
2081
2091
  | 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
2092
  | 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
2093
  | v0.11.0 | package | 0.11.0 | dep-guard 0.14.0, intent-guard 1.10.0 |
package/dist/cli.js CHANGED
@@ -712,7 +712,8 @@ export function buildProgram() {
712
712
  // STEP-SUMMARY LINE, so a run on a stale gate is visible on the run's
713
713
  // page without anybody opening the log (audit 2026-10-18: every guard
714
714
  // repository's own push runs used a stale devDependency for weeks and
715
- // only the log said which version ran). Reporting only. The
715
+ // only the log said which version ran). Since 0.13.0 that gate is
716
+ // could-not-run, decided in runGate; these lines only say so. The
716
717
  // annotation goes to stdout when stdout is not the report (--output
717
718
  // given, which is how the Action runs), and to stderr otherwise. A
718
719
  // summary that cannot be written is skipped: it never changes the
@@ -68,6 +68,19 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
68
68
  * (docs/superpowers/specs/2026-10-18-emptied-lockfile-under-trust-base.md).
69
69
  */
70
70
  | 'lockfile-emptied'
71
+ /**
72
+ * The run was told which version of this gate must judge it (the Action's
73
+ * pin, `RunGateOptions.expectedVersion`) and the resolved binary reports
74
+ * another one, from whichever location resolution took it. The gate's
75
+ * check was not run. Design:
76
+ * docs/superpowers/specs/2026-10-18-version-skew-could-not-run.md.
77
+ */
78
+ | 'version-skew'
79
+ /**
80
+ * The same expectation, and the resolved binary's version could not be
81
+ * read, so it is not known to be the expected one. Fail closed.
82
+ */
83
+ | 'version-unverified'
71
84
  /**
72
85
  * The same check could not clear the head: a base copy unreadable, a base
73
86
  * run that failed or printed no count, a command-line mismatch, or a head
@@ -120,6 +133,22 @@ export declare function breakWorkflowMarkers(text: string): string;
120
133
  * it, as opposed to something the gate itself said or did.
121
134
  */
122
135
  export declare const CONDUCTOR_OWN_REASONS: ReadonlySet<CouldNotRunReason>;
136
+ /**
137
+ * A probed version as it may be printed. The probe for the family gates
138
+ * accepts anything after x.y.z on the first line, and the text reaches a
139
+ * workflow command, the step summary and the reports, so only version
140
+ * characters are kept.
141
+ */
142
+ export declare function versionCharacters(raw: string): string;
143
+ /** Where a resolved binary came from, in words. Never a machine path. */
144
+ export declare function resolutionPlace(source: ResolutionSource): string;
145
+ /**
146
+ * The remedy for a gate that is not at the expected version, which depends
147
+ * on where the binary came from. THE ONE PLACE it is written: the
148
+ * could-not-run detail and every version-skew line in src/output-text.ts
149
+ * call this.
150
+ */
151
+ export declare function versionSkewRemedy(product: string, source: ResolutionSource, expected: string): string;
123
152
  /**
124
153
  * A gate's time limit, and where it came from. THE ONE PLACE the precedence
125
154
  * is written: the test hook (`RunGateOptions.timeoutMs`, which no CLI path
@@ -326,9 +355,9 @@ export interface GateOutcome {
326
355
  * Present only when the version this gate reported differs from the one
327
356
  * the run was told to expect (the Action's pin, handed over as an
328
357
  * 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.
358
+ * resolved from. Since 0.13.0 it is present exactly on a `version-skew`
359
+ * could-not-run, and carries the facts the warning surfaces print; it is
360
+ * the outcome, not this record, that the exit code reads.
332
361
  *
333
362
  * Every location, not only PATH (audit 2026-10-18, the intent-guard
334
363
  * audit's MB3). Outside a pull request a repository's own devDependency in
@@ -373,8 +402,9 @@ export interface RunGateOptions {
373
402
  /**
374
403
  * The version this run expects of the gate, when something says so (the
375
404
  * 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.
405
+ * wherever it was found: another version is `version-skew` and an
406
+ * unreadable one `version-unverified`, both could-not-run (0.13.0). Absent
407
+ * means no expectation, which is every local run, and changes nothing.
378
408
  */
379
409
  expectedVersion?: string;
380
410
  repoRoot: string;
@@ -84,7 +84,38 @@ export const CONDUCTOR_OWN_REASONS = new Set([
84
84
  'timed-out',
85
85
  'lockfile-emptied',
86
86
  'lockfile-emptied-unverified',
87
+ 'version-skew',
88
+ 'version-unverified',
87
89
  ]);
90
+ /**
91
+ * A probed version as it may be printed. The probe for the family gates
92
+ * accepts anything after x.y.z on the first line, and the text reaches a
93
+ * workflow command, the step summary and the reports, so only version
94
+ * characters are kept.
95
+ */
96
+ export function versionCharacters(raw) {
97
+ return raw.replace(/[^0-9A-Za-z.+-]/g, '').slice(0, 64);
98
+ }
99
+ /** Where a resolved binary came from, in words. Never a machine path. */
100
+ export function resolutionPlace(source) {
101
+ return source === 'node_modules' ? 'node_modules/.bin' : source === 'path' ? 'PATH' : 'the policy command';
102
+ }
103
+ /**
104
+ * The remedy for a gate that is not at the expected version, which depends
105
+ * on where the binary came from. THE ONE PLACE it is written: the
106
+ * could-not-run detail and every version-skew line in src/output-text.ts
107
+ * call this.
108
+ */
109
+ export function versionSkewRemedy(product, source, expected) {
110
+ if (source === 'node_modules') {
111
+ return (`Fix: bump or remove the repository's own ${product} devDependency. node_modules/.bin outranks ` +
112
+ "PATH outside a pull request, so on a push run it shadows the action's install.");
113
+ }
114
+ if (source === 'path') {
115
+ return `Fix: remove the other ${product} from PATH, or install ${expected}.`;
116
+ }
117
+ return `Fix: point the policy command at ${product} ${expected}, or remove the command override.`;
118
+ }
88
119
  /**
89
120
  * A gate's time limit, and where it came from. THE ONE PLACE the precedence
90
121
  * is written: the test hook (`RunGateOptions.timeoutMs`, which no CLI path
@@ -1165,13 +1196,15 @@ function runGateInner(gate, options, started, progress) {
1165
1196
  // would read as trust-base-unverified, a packaging problem that does not
1166
1197
  // exist), and a local run does not go on to scan with the version
1167
1198
  // unknown. Enforced under a trust base, like trust-base-unverified: the
1168
- // gate could not be placed inside the boundary.
1199
+ // gate could not be placed inside the boundary. Enforced under the
1200
+ // Action's expected-version signal too, like version-unverified: the run
1201
+ // cannot show this is the pinned build.
1169
1202
  const detail = timedOutDetail(gate, 'version-probe', timeLimit, probed.elapsedMs, options.trustBase);
1170
1203
  const timedOut = timedOutRecord('version-probe', timeLimit, probed.elapsedMs, probed.signal);
1171
1204
  return {
1172
1205
  ...base,
1173
1206
  binary,
1174
- enforce: options.trustBase !== undefined ? true : gate.enforce,
1207
+ enforce: options.trustBase !== undefined || options.expectedVersion !== undefined ? true : gate.enforce,
1175
1208
  durationMs: Date.now() - started,
1176
1209
  exitCode: null,
1177
1210
  couldNotRun: { reason: 'timed-out', detail, timedOut },
@@ -1181,22 +1214,54 @@ function runGateInner(gate, options, started, progress) {
1181
1214
  };
1182
1215
  }
1183
1216
  const version = probed.kind === 'version' ? probed.value : null;
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) {
1217
+ // THE EXPECTED VERSION (0.13.0, design
1218
+ // docs/superpowers/specs/2026-10-18-version-skew-could-not-run.md). When
1219
+ // the run was told which version must judge it (the Action's pin), a
1220
+ // binary at another version, or one whose version cannot be read, is
1221
+ // could-not-run, from whichever location resolution took it
1222
+ // (node_modules/.bin, PATH or a policy command). Resolution itself is
1223
+ // unchanged. Here, right after the probe and before the command-line floor
1224
+ // and decideTrustBase, so nothing past the probe runs. ENFORCED whatever
1225
+ // the policy says, like a refused program: the gate produced no verdict for
1226
+ // `enforce: false` to be a decision about. No expectation (every plain run)
1227
+ // skips all of this.
1228
+ if (options.expectedVersion !== undefined && version !== options.expectedVersion) {
1229
+ const expected = options.expectedVersion;
1190
1230
  const relative = path.relative(options.repoRoot, binary.program);
1191
1231
  const inside = relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
1192
- Object.assign(progress, {
1193
- versionSkew: {
1194
- expected: options.expectedVersion,
1195
- found: version,
1196
- source: binary.source,
1197
- path: inside ? relative : binary.program,
1198
- },
1199
- });
1232
+ // Repository-relative inside the repository; outside it, words only,
1233
+ // because this detail reaches the reports and a published log.
1234
+ const place = binary.source === 'node_modules' && inside ? relative : resolutionPlace(binary.source);
1235
+ const remedy = versionSkewRemedy(gate.product, binary.source, expected);
1236
+ const pinned = `${expected} (the version the action pinned)`;
1237
+ const detail = version === null
1238
+ ? `${gate.product} did not run: the version of the build resolved from ${place} could not be read, ` +
1239
+ `so it is not known to be ${pinned}. ${remedy}`
1240
+ : `${gate.product} did not run: the build resolved from ${place} reports version ` +
1241
+ `${versionCharacters(version)}, but this run expects ${pinned}. ${remedy}`;
1242
+ return {
1243
+ ...base,
1244
+ ...(version === null
1245
+ ? {}
1246
+ : {
1247
+ // Kept for the job-log line, the annotation, the step summary,
1248
+ // the text report line and the SARIF note that 0.12.0 printed.
1249
+ versionSkew: {
1250
+ expected,
1251
+ found: version,
1252
+ source: binary.source,
1253
+ path: inside ? relative : binary.program,
1254
+ },
1255
+ }),
1256
+ productVersion: version,
1257
+ binary,
1258
+ enforce: true,
1259
+ durationMs: Date.now() - started,
1260
+ couldNotRun: { reason: version === null ? 'version-unverified' : 'version-skew', detail },
1261
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
1262
+ run: EMPTY_RUN,
1263
+ diagnostics: [],
1264
+ };
1200
1265
  }
1201
1266
  // The command-line floor. Only the external tools have one: the umbrella
1202
1267
  // writes flags they grew at a known release (gitleaks' git subcommand,
@@ -121,6 +121,14 @@ export type EmptiedCheckResult = {
121
121
  elapsedMs: number;
122
122
  signal: string | null;
123
123
  };
124
+ /**
125
+ * Whether `file` is a regular file (mode 100644 or 100755, stage 0) in the
126
+ * head's index: the listing the gate's handed files come from (`git
127
+ * ls-files`). A symbolic link (120000), a submodule, a conflicted or missing
128
+ * entry, and an index git cannot read are all false (fail closed). The path
129
+ * is passed as a literal pathspec, so no character in it is a glob.
130
+ */
131
+ export declare function regularInHeadIndex(repoRoot: string, file: string): boolean;
124
132
  /**
125
133
  * The emptied-lockfile base check (design
126
134
  * docs/superpowers/specs/2026-10-18-emptied-lockfile-under-trust-base.md,
@@ -129,8 +137,9 @@ export type EmptiedCheckResult = {
129
137
  * is copied from the base and osv-scanner is run once on those copies; a
130
138
  * copy with packages means the head removed what the gate judges. A removed
131
139
  * 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).
140
+ * read packages, is not a requirements file, is absent from the base tree,
141
+ * is of the removed file's ecosystem family, and is a regular file in the
142
+ * head's index (a migration, say npm to pnpm, beside the same manifest).
134
143
  *
135
144
  * FAIL CLOSED, unlike compareWithBase, whose labels only ever move toward
136
145
  * introduced. This check exists only to stop a head from removing what the
@@ -19,7 +19,7 @@ import path from 'node:path';
19
19
  import { realPathInside, runGit } from './git.js';
20
20
  import { normalizeOsvScanner } from './normalize.js';
21
21
  import { ABSENT_ON_BASE, baseReader, packageCounts } from './osv-coverage.js';
22
- import { osvLockfileKind } from './products.js';
22
+ import { osvLockfileKind, sameOsvFamily } from './products.js';
23
23
  import { checkRequirementsPins } from './requirements-pin.js';
24
24
  import { readFileAtRefBytes, treeEntryAt } from './trust-base.js';
25
25
  /** The comparison key: advisory id, ecosystem, package, installed version, lockfile path. */
@@ -148,6 +148,28 @@ export function comparisonFailed(args, reason) {
148
148
  diagnostics: unavailableNotes(unavailable),
149
149
  };
150
150
  }
151
+ /**
152
+ * Whether `file` is a regular file (mode 100644 or 100755, stage 0) in the
153
+ * head's index: the listing the gate's handed files come from (`git
154
+ * ls-files`). A symbolic link (120000), a submodule, a conflicted or missing
155
+ * entry, and an index git cannot read are all false (fail closed). The path
156
+ * is passed as a literal pathspec, so no character in it is a glob.
157
+ */
158
+ export function regularInHeadIndex(repoRoot, file) {
159
+ const out = runGit(repoRoot, ['ls-files', '--stage', '-z', '--', `:(literal)${file}`]);
160
+ if (out.error !== undefined || out.status !== 0) {
161
+ return false;
162
+ }
163
+ const entries = out.stdout.split('\0').filter((entry) => entry !== '');
164
+ if (entries.length !== 1) {
165
+ return false;
166
+ }
167
+ const match = /^(\d{6}) [0-9a-f]+ (\d)\t(.*)$/s.exec(entries[0]);
168
+ return (match !== null &&
169
+ (match[1] === '100644' || match[1] === '100755') &&
170
+ match[2] === '0' &&
171
+ match[3] === file);
172
+ }
151
173
  /**
152
174
  * The emptied-lockfile base check (design
153
175
  * docs/superpowers/specs/2026-10-18-emptied-lockfile-under-trust-base.md,
@@ -156,8 +178,9 @@ export function comparisonFailed(args, reason) {
156
178
  * is copied from the base and osv-scanner is run once on those copies; a
157
179
  * copy with packages means the head removed what the gate judges. A removed
158
180
  * 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).
181
+ * read packages, is not a requirements file, is absent from the base tree,
182
+ * is of the removed file's ecosystem family, and is a regular file in the
183
+ * head's index (a migration, say npm to pnpm, beside the same manifest).
161
184
  *
162
185
  * FAIL CLOSED, unlike compareWithBase, whose labels only ever move toward
163
186
  * introduced. This check exists only to stop a head from removing what the
@@ -241,11 +264,20 @@ export function checkEmptiedAgainstBase(args) {
241
264
  // (a Cargo.lock beside the deleted package-lock.json), carries another
242
265
  // manifest's packages. A base listing that errors is not absent, so that
243
266
  // file does not count (fail closed).
267
+ //
268
+ // 0.13.0, operator ruling of 2026-10-18: also of the removed file's
269
+ // ecosystem family (a NEW Cargo.lock carries a Rust manifest's packages,
270
+ // not the npm ones the head removed; an unknown family matches nothing),
271
+ // and a regular file in the head's index (a symbolic link to a populated
272
+ // lockfile elsewhere reads that file's packages). The cheap checks first,
273
+ // so git is asked only about a candidate that could otherwise count.
244
274
  const newOnHead = (other) => treeEntryAt(args.repoRoot, args.ref, other).kind === 'absent';
245
275
  const replaced = (file) => [...args.headCounts].some(([other, count]) => other !== file &&
246
276
  count > 0 &&
247
277
  path.posix.dirname(other) === path.posix.dirname(file) &&
248
278
  osvLockfileKind(path.posix.basename(other)) !== 'requirements' &&
279
+ sameOsvFamily(other, file) &&
280
+ regularInHeadIndex(args.repoRoot, other) &&
249
281
  newOnHead(other));
250
282
  const emptied = copied
251
283
  .map((file, index) => ({ path: file, packages: counts.get(copies[index]) ?? 0, removed: removed.has(file) }))
@@ -834,8 +834,9 @@ function nodeModulesSkippedNotifications(result) {
834
834
  * A gate whose resolved binary reported a version other than the one the
835
835
  * run was pinned to (the Action's CONDUCTOR_EXPECTED_* variables), from any
836
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.
837
+ * A NOTE: it says which build was found, a statement in the same shape as
838
+ * node-modules-skipped, and the gate's own outcome (a version-skew
839
+ * could-not-run since 0.13.0) is reported on its own, at its own level.
839
840
  * The path is carried only when it is repository-relative (node_modules);
840
841
  * a PATH binary's absolute machine path stays in the job log line.
841
842
  */
@@ -851,7 +852,7 @@ function versionSkewNotifications(result) {
851
852
  id: 'conductor/version-skew',
852
853
  message: `The ${gate.role} gate (${gate.product}) reported version ${found}, but this run expects ` +
853
854
  `${skew.expected} (the version the action pinned); it was resolved from ${skewPlace(skew)}. ` +
854
- 'Resolution is unchanged and that binary was used.',
855
+ 'Resolution is unchanged; the gate was not run and is could-not-run (version-skew).',
855
856
  details: {
856
857
  role: gate.role,
857
858
  product: gate.product,
@@ -80,33 +80,28 @@ export declare function gateLogLines(result: RunResult, options?: {
80
80
  type VersionSkew = NonNullable<GateOutcome['versionSkew']>;
81
81
  /** Where a skewed binary came from, in words. Never a machine path. */
82
82
  export declare function skewPlace(skew: VersionSkew): string;
83
- /**
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
- */
83
+ /** The reported version as it may be printed: version characters only (`versionCharacters`). */
89
84
  export declare function skewFound(skew: VersionSkew): string;
90
85
  /**
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.
86
+ * One error line per gate whose resolved binary reported a version other
87
+ * than the one this run expected (the Action's pin), wherever it was found:
88
+ * node_modules/.bin, PATH or a policy command. Since 0.13.0 every such gate
89
+ * is could-not-run, so the line says so.
94
90
  *
95
91
  * For the job log: it names the file the binary was found at, which for PATH
96
92
  * is an absolute machine path, so this exact line is never part of a report.
97
93
  * 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.
94
+ * conductor/version-skew notification in SARIF). Resolution is unchanged.
101
95
  */
102
96
  export declare function versionSkewWarnings(result: RunResult): string[];
103
97
  /**
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.
98
+ * The same lines as GitHub Actions `::error::` annotations (a could-not-run
99
+ * since 0.13.0, a `::warning::` before), so a skew shows on the run's summary
100
+ * page without anybody opening the log. No machine path: the location is
101
+ * named in words.
107
102
  */
108
103
  export declare function versionSkewAnnotations(result: RunResult): string[];
109
- /** The step-summary lines for the same warnings, one paragraph each. */
104
+ /** The step-summary lines for the same errors, one paragraph each. */
110
105
  export declare function versionSkewSummaryLines(result: RunResult): string[];
111
106
  /**
112
107
  * The verdict token: a label for the umbrella's OWN exit decision, in a
@@ -23,7 +23,7 @@
23
23
  // everywhere is worth more here than a nicer-looking terminal.
24
24
  import { compareFindings } from './envelope.js';
25
25
  import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, gateExitBlocks } from './exit-codes.js';
26
- import { CONDUCTOR_OWN_REASONS, cleanOutputLine, conductorStatedReason, } from './gate-runner.js';
26
+ import { CONDUCTOR_OWN_REASONS, cleanOutputLine, conductorStatedReason, resolutionPlace, versionCharacters, versionSkewRemedy, } from './gate-runner.js';
27
27
  import { isLegacyContractPath, legacyChangedSentence } from './intent-prepare.js';
28
28
  import { SPEC_DIR } from './intent-spec.js';
29
29
  function subjectLabel(finding) {
@@ -748,52 +748,42 @@ export function gateLogLines(result, options = {}) {
748
748
  }
749
749
  /** Where a skewed binary came from, in words. Never a machine path. */
750
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';
751
+ return resolutionPlace(skew.source);
756
752
  }
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
- */
753
+ /** The reported version as it may be printed: version characters only (`versionCharacters`). */
763
754
  export function skewFound(skew) {
764
- return skew.found.replace(/[^0-9A-Za-z.+-]/g, '').slice(0, 64);
755
+ return versionCharacters(skew.found);
765
756
  }
766
- /** The remedy, which depends on where the binary came from. */
757
+ /** The remedy, which depends on where the binary came from. One source: `versionSkewRemedy`. */
767
758
  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.`;
759
+ return versionSkewRemedy(product, skew.source, skew.expected);
776
760
  }
777
761
  /**
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.
762
+ * The sentence every GitHub surface shares (0.13.0): what was found, what was
763
+ * expected, and that the gate was therefore not run. No machine path.
764
+ */
765
+ function skewSentence(product, skew) {
766
+ return (`${product} resolved from ${skewPlace(skew)} reports version ${skewFound(skew)}, but this run expects ` +
767
+ `${skew.expected} (the version the action pinned), so conductor did not run it: the gate is ` +
768
+ 'could-not-run (version-skew).');
769
+ }
770
+ /**
771
+ * One error line per gate whose resolved binary reported a version other
772
+ * than the one this run expected (the Action's pin), wherever it was found:
773
+ * node_modules/.bin, PATH or a policy command. Since 0.13.0 every such gate
774
+ * is could-not-run, so the line says so.
781
775
  *
782
776
  * For the job log: it names the file the binary was found at, which for PATH
783
777
  * is an absolute machine path, so this exact line is never part of a report.
784
778
  * 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.
779
+ * conductor/version-skew notification in SARIF). Resolution is unchanged.
788
780
  */
789
781
  export function versionSkewWarnings(result) {
790
782
  return result.gates.flatMap((gate) => gate.versionSkew === undefined
791
783
  ? []
792
784
  : [
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)}`,
785
+ `conductor: error: ${skewSentence(gate.product, gate.versionSkew)} It was found at ` +
786
+ `${gate.versionSkew.path}. ${skewFix(gate.product, gate.versionSkew)}`,
797
787
  ]);
798
788
  }
799
789
  /** A workflow-command message: `%`, CR and LF escaped, as the runner requires. */
@@ -801,30 +791,24 @@ function workflowCommandData(text) {
801
791
  return text.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
802
792
  }
803
793
  /**
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.
794
+ * The same lines as GitHub Actions `::error::` annotations (a could-not-run
795
+ * since 0.13.0, a `::warning::` before), so a skew shows on the run's summary
796
+ * page without anybody opening the log. No machine path: the location is
797
+ * named in words.
807
798
  */
808
799
  export function versionSkewAnnotations(result) {
809
800
  return result.gates.flatMap((gate) => gate.versionSkew === undefined
810
801
  ? []
811
802
  : [
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)),
803
+ '::error title=conductor version skew::' +
804
+ workflowCommandData(`${skewSentence(gate.product, gate.versionSkew)} ${skewFix(gate.product, gate.versionSkew)}`),
817
805
  ]);
818
806
  }
819
- /** The step-summary lines for the same warnings, one paragraph each. */
807
+ /** The step-summary lines for the same errors, one paragraph each. */
820
808
  export function versionSkewSummaryLines(result) {
821
809
  return result.gates.flatMap((gate) => gate.versionSkew === undefined
822
810
  ? []
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)}`,
827
- ]);
811
+ : [`conductor error: ${skewSentence(gate.product, gate.versionSkew)} ${skewFix(gate.product, gate.versionSkew)}`]);
828
812
  }
829
813
  /** The gate-block line of the text report. Repository-relative paths only. */
830
814
  function versionSkewLine(gate) {
@@ -833,7 +817,7 @@ function versionSkewLine(gate) {
833
817
  return null;
834
818
  }
835
819
  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 ` +
820
+ return (` ! conductor/version-skew: ${gate.product} ${skewFound(skew)}, from ${from}, was not run: this run expects ` +
837
821
  `${skew.expected} (the version the action pinned). Resolution is unchanged. ${skewFix(gate.product, skew)}`);
838
822
  }
839
823
  /**
@@ -117,7 +117,43 @@ export type LockfileKind = 'bare' | 'requirements';
117
117
  * named by the unread-manifests note instead). gradle's
118
118
  * verification-metadata.xml is read only inside a `gradle` directory and is
119
119
  * matched by `osvLockfileKind` rather than listed here.
120
+ *
121
+ * ONE TABLE, name to ecosystem family (0.13.0): its keys ARE the name list,
122
+ * so a name cannot be handed to osv-scanner without a family. The family is
123
+ * read by the emptied-lockfile replacement rule (src/osv-baseline.ts), where
124
+ * a replacement must be of the removed file's family; see
125
+ * `osvLockfileFamily`.
120
126
  */
127
+ export declare const OSV_LOCKFILE_ECOSYSTEMS: {
128
+ readonly 'package-lock.json': "javascript";
129
+ readonly 'npm-shrinkwrap.json': "javascript";
130
+ readonly 'pnpm-lock.yaml': "javascript";
131
+ readonly 'yarn.lock': "javascript";
132
+ readonly 'bun.lock': "javascript";
133
+ readonly 'go.mod': "go";
134
+ readonly 'poetry.lock': "python";
135
+ readonly 'Pipfile.lock': "python";
136
+ readonly 'uv.lock': "python";
137
+ readonly 'pdm.lock': "python";
138
+ readonly 'Cargo.lock': "rust";
139
+ readonly 'Gemfile.lock': "ruby";
140
+ readonly 'composer.lock': "php";
141
+ readonly 'gradle.lockfile': "jvm";
142
+ readonly 'packages.lock.json': "dotnet";
143
+ readonly 'mix.lock': "hex";
144
+ readonly 'pubspec.lock': "dart";
145
+ readonly 'Package.resolved': "swift";
146
+ readonly 'conan.lock': "conan";
147
+ readonly 'renv.lock': "r";
148
+ readonly 'packages.config': "dotnet";
149
+ readonly 'buildscript-gradle.lockfile': "jvm";
150
+ readonly 'gems.locked': "ruby";
151
+ readonly 'pylock.toml': "python";
152
+ readonly 'cabal.project.freeze': "haskell";
153
+ readonly 'stack.yaml.lock': "haskell";
154
+ };
155
+ /** An ecosystem family, as the replacement rule compares them. */
156
+ export type OsvEcosystemFamily = (typeof OSV_LOCKFILE_ECOSYSTEMS)[keyof typeof OSV_LOCKFILE_ECOSYSTEMS];
121
157
  export declare const OSV_LOCKFILE_NAMES: readonly string[];
122
158
  /**
123
159
  * What osv-scanner is handed for a tracked file, or null. Takes the
@@ -127,6 +163,17 @@ export declare const OSV_LOCKFILE_NAMES: readonly string[];
127
163
  * parent is part of the match for that one file.
128
164
  */
129
165
  export declare function osvLockfileKind(file: string): LockfileKind | null;
166
+ /**
167
+ * The ecosystem family of a tracked file, or null. DERIVED FROM
168
+ * `osvLockfileKind`, never a second list: a file with no kind has no family,
169
+ * a requirements file is python, gradle's verification-metadata.xml (matched
170
+ * by kind on its parent) is jvm, and every other bare name is looked up in
171
+ * the one table above. Null means unknown, and an unknown family matches
172
+ * nothing, itself included: callers compare with `sameOsvFamily`.
173
+ */
174
+ export declare function osvLockfileFamily(file: string): OsvEcosystemFamily | null;
175
+ /** Whether two tracked files are of one known ecosystem family. Fail closed: unknown never matches. */
176
+ export declare function sameOsvFamily(a: string, b: string): boolean;
130
177
  /**
131
178
  * The npm gates print a bare version. No capture group on purpose: the runner
132
179
  * has always reported the whole first line minus a leading v, prerelease
package/dist/products.js CHANGED
@@ -34,35 +34,42 @@ function raiseTheLimit(role) {
34
34
  * named by the unread-manifests note instead). gradle's
35
35
  * verification-metadata.xml is read only inside a `gradle` directory and is
36
36
  * matched by `osvLockfileKind` rather than listed here.
37
+ *
38
+ * ONE TABLE, name to ecosystem family (0.13.0): its keys ARE the name list,
39
+ * so a name cannot be handed to osv-scanner without a family. The family is
40
+ * read by the emptied-lockfile replacement rule (src/osv-baseline.ts), where
41
+ * a replacement must be of the removed file's family; see
42
+ * `osvLockfileFamily`.
37
43
  */
38
- export const OSV_LOCKFILE_NAMES = [
39
- 'package-lock.json',
40
- 'npm-shrinkwrap.json',
41
- 'pnpm-lock.yaml',
42
- 'yarn.lock',
43
- 'bun.lock',
44
- 'go.mod',
45
- 'poetry.lock',
46
- 'Pipfile.lock',
47
- 'uv.lock',
48
- 'pdm.lock',
49
- 'Cargo.lock',
50
- 'Gemfile.lock',
51
- 'composer.lock',
52
- 'gradle.lockfile',
53
- 'packages.lock.json',
54
- 'mix.lock',
55
- 'pubspec.lock',
56
- 'Package.resolved',
57
- 'conan.lock',
58
- 'renv.lock',
59
- 'packages.config',
60
- 'buildscript-gradle.lockfile',
61
- 'gems.locked',
62
- 'pylock.toml',
63
- 'cabal.project.freeze',
64
- 'stack.yaml.lock',
65
- ];
44
+ export const OSV_LOCKFILE_ECOSYSTEMS = {
45
+ 'package-lock.json': 'javascript',
46
+ 'npm-shrinkwrap.json': 'javascript',
47
+ 'pnpm-lock.yaml': 'javascript',
48
+ 'yarn.lock': 'javascript',
49
+ 'bun.lock': 'javascript',
50
+ 'go.mod': 'go',
51
+ 'poetry.lock': 'python',
52
+ 'Pipfile.lock': 'python',
53
+ 'uv.lock': 'python',
54
+ 'pdm.lock': 'python',
55
+ 'Cargo.lock': 'rust',
56
+ 'Gemfile.lock': 'ruby',
57
+ 'composer.lock': 'php',
58
+ 'gradle.lockfile': 'jvm',
59
+ 'packages.lock.json': 'dotnet',
60
+ 'mix.lock': 'hex',
61
+ 'pubspec.lock': 'dart',
62
+ 'Package.resolved': 'swift',
63
+ 'conan.lock': 'conan',
64
+ 'renv.lock': 'r',
65
+ 'packages.config': 'dotnet',
66
+ 'buildscript-gradle.lockfile': 'jvm',
67
+ 'gems.locked': 'ruby',
68
+ 'pylock.toml': 'python',
69
+ 'cabal.project.freeze': 'haskell',
70
+ 'stack.yaml.lock': 'haskell',
71
+ };
72
+ export const OSV_LOCKFILE_NAMES = Object.keys(OSV_LOCKFILE_ECOSYSTEMS);
66
73
  /** gradle's dependency verification file, which 2.4.0 reads only under a `gradle` directory. */
67
74
  const GRADLE_VERIFICATION_METADATA = 'verification-metadata.xml';
68
75
  /**
@@ -96,6 +103,35 @@ export function osvLockfileKind(file) {
96
103
  }
97
104
  return REQUIREMENTS_PATTERNS.some((pattern) => pattern.test(basename)) ? 'requirements' : null;
98
105
  }
106
+ /**
107
+ * The ecosystem family of a tracked file, or null. DERIVED FROM
108
+ * `osvLockfileKind`, never a second list: a file with no kind has no family,
109
+ * a requirements file is python, gradle's verification-metadata.xml (matched
110
+ * by kind on its parent) is jvm, and every other bare name is looked up in
111
+ * the one table above. Null means unknown, and an unknown family matches
112
+ * nothing, itself included: callers compare with `sameOsvFamily`.
113
+ */
114
+ export function osvLockfileFamily(file) {
115
+ const kind = osvLockfileKind(file);
116
+ if (kind === null) {
117
+ return null;
118
+ }
119
+ if (kind === 'requirements') {
120
+ return 'python';
121
+ }
122
+ const basename = file.split('/').pop() ?? '';
123
+ if (basename === GRADLE_VERIFICATION_METADATA) {
124
+ return 'jvm';
125
+ }
126
+ return Object.hasOwn(OSV_LOCKFILE_ECOSYSTEMS, basename)
127
+ ? OSV_LOCKFILE_ECOSYSTEMS[basename]
128
+ : null;
129
+ }
130
+ /** Whether two tracked files are of one known ecosystem family. Fail closed: unknown never matches. */
131
+ export function sameOsvFamily(a, b) {
132
+ const left = osvLockfileFamily(a);
133
+ return left !== null && left === osvLockfileFamily(b);
134
+ }
99
135
  /**
100
136
  * The npm gates print a bare version. No capture group on purpose: the runner
101
137
  * has always reported the whole first line minus a leading v, prerelease
package/dist/run.js CHANGED
@@ -225,10 +225,12 @@ function splitOnTreeUnchanged(gates, trustBase) {
225
225
  }
226
226
  /**
227
227
  * The environment variables the Action sets to say which version of each
228
- * family gate it pinned, read only to warn when a gate resolved from PATH
229
- * reports a different one. Not a control input: nothing about resolution or
230
- * the verdict reads them, so a run that sets them wrongly gets a wrong warning
231
- * and nothing else.
228
+ * family gate it pinned. Since 0.13.0 a control input, in ONE DIRECTION
229
+ * ONLY: a gate that reports another version, or none, is could-not-run
230
+ * (runGate), and nothing else reads them. They can add a could-not-run and
231
+ * never clear a gate or drop a finding, so a run that sets them wrongly fails
232
+ * closed and a run without them is the plain run it always was. Resolution
233
+ * is unchanged.
232
234
  */
233
235
  const EXPECTED_VERSION_ENV = {
234
236
  'dep-guard': 'CONDUCTOR_EXPECTED_DEP_GUARD_VERSION',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.12.0",
3
+ "version": "0.13.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [