@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.
@@ -25,8 +25,8 @@ import { runGit } from './git.js';
25
25
  import { NormalizeError } from './envelope.js';
26
26
  import { describeLockfiles, normalizeDepGuard, normalizeFailedGate, normalizeGitleaks, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeOsvScanner, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
27
27
  import { renderOptionFlags } from './policy.js';
28
- import { NO_RESOLVE_OVERRIDDEN, emptiedLockfiles, noLongerScanned, nothingScannableMessage, notScannedDetail, selectOsvInputs, } from './osv-coverage.js';
29
- import { compareWithBase, comparisonFailed, } from './osv-baseline.js';
28
+ import { NO_RESOLVE_OVERRIDDEN, emptiedLockfiles, noLongerScanned, noLongerScannedFiles, nothingScannableMessage, notScannedDetail, packageCounts, selectOsvInputs, } from './osv-coverage.js';
29
+ import { checkEmptiedAgainstBase, compareWithBase, comparisonFailed, } from './osv-baseline.js';
30
30
  import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals, } from './external-config.js';
31
31
  import { osvLockfileKind, profileFor } from './products.js';
32
32
  import { unreadManifestsNote } from './unread-manifests.js';
@@ -82,6 +82,8 @@ export const CONDUCTOR_OWN_REASONS = new Set([
82
82
  'gate-version-unsupported',
83
83
  'history-shallow',
84
84
  'timed-out',
85
+ 'lockfile-emptied',
86
+ 'lockfile-emptied-unverified',
85
87
  ]);
86
88
  /**
87
89
  * A gate's time limit, and where it came from. THE ONE PLACE the precedence
@@ -150,6 +152,11 @@ function timedOutDetail(gate, step, limit, elapsedMs, trustBase) {
150
152
  return (`the version probe of ${gate.product} was stopped at ${limitSeconds} s (${where}), so the gate ` +
151
153
  'was not run and nothing was checked by it.');
152
154
  }
155
+ if (step === 'base-check') {
156
+ return (`${gate.product}'s check of the base copies of the lockfiles this pull request emptied was stopped ` +
157
+ `after ${elapsedSeconds} s, at what was left of its ${limitSeconds} s limit (${where}) after the ` +
158
+ `head scan, so the dependencies the pull request removed were not judged. ${remedies}`);
159
+ }
153
160
  const what = step === 'scan'
154
161
  ? `${gate.product} was stopped after ${elapsedSeconds} s, at its ${limitSeconds} s limit (${where}), ` +
155
162
  'so nothing was checked by it.'
@@ -195,6 +202,18 @@ export function cleanOutputLine(raw) {
195
202
  /** A zerolog line at one level: gitleaks' "<time> ERR ..." shape. */
196
203
  const ZEROLOG_ERR = /^\S+\s+ERR\s/;
197
204
  const ZEROLOG_WRN = /^\S+\s+WRN\s/;
205
+ /**
206
+ * osv-scanner 2.4.0's progress lines, which come before its error on every
207
+ * run (tests/fixtures/stated-reason-captures.json, audit 2026-10-18 N4): the
208
+ * walk banner, one "Scanned <file> file and found N package(s)" per file
209
+ * read, and the "End status:" counters. Quoting the banner as "gate said"
210
+ * was noise on every osv could-not-run.
211
+ */
212
+ const OSV_PROGRESS = [
213
+ /^Starting filesystem walk for root: /,
214
+ /^Scanned .+ file and found \d+ packages?$/,
215
+ /^End status: /,
216
+ ];
198
217
  function plainLine(raw) {
199
218
  return raw.replace(/[^\x20-\x7e]/g, ' ').replace(/\s+/g, ' ').trim();
200
219
  }
@@ -209,7 +228,8 @@ function plainLine(raw) {
209
228
  * 2. Informational lines are never chosen: a `note:` line and every
210
229
  * following indented line (a BLANK line ends the note block, so an
211
230
  * indented reason after it is not swallowed), and gitleaks' two
212
- * rename-detection warnings.
231
+ * rename-detection warnings, and osv-scanner's progress lines
232
+ * (OSV_PROGRESS).
213
233
  * 3. A marker wins: the first remaining INCOMPLETE: or zerolog ERR line,
214
234
  * joined with the indented lines after it, skipping blank lines, up to
215
235
  * the first non-blank line that is not indented.
@@ -234,6 +254,9 @@ function statedReasonFromStderr(stderr) {
234
254
  (line.text.includes('rename detection was skipped') || line.text.includes('diff.renameLimit'))) {
235
255
  line.informational = true;
236
256
  }
257
+ else if (OSV_PROGRESS.some((pattern) => pattern.test(line.text))) {
258
+ line.informational = true;
259
+ }
237
260
  }
238
261
  const candidate = (line) => !line.blank && !line.informational && line.text !== '';
239
262
  const markerAt = lines.findIndex((line) => candidate(line) && (line.text.startsWith('INCOMPLETE:') || ZEROLOG_ERR.test(line.text)));
@@ -1158,15 +1181,21 @@ function runGateInner(gate, options, started, progress) {
1158
1181
  };
1159
1182
  }
1160
1183
  const version = probed.kind === 'version' ? probed.value : null;
1161
- // A PATH binary at a different version than the run was told to expect: a
1162
- // fact for a warning and nothing else. It sits on `progress` (which `base`
1163
- // is) so every outcome from here on carries it, and no branch below reads it.
1164
- if (options.expectedVersion !== undefined &&
1165
- version !== null &&
1166
- binary.source === 'path' &&
1167
- version !== options.expectedVersion) {
1184
+ // A binary at a different version than the run was told to expect, from
1185
+ // whichever location resolution took it (node_modules/.bin, PATH or a
1186
+ // policy command): a fact for a warning and nothing else. It sits on
1187
+ // `progress` (which `base` is) so every outcome from here on carries it,
1188
+ // and no branch below reads it.
1189
+ if (options.expectedVersion !== undefined && version !== null && version !== options.expectedVersion) {
1190
+ const relative = path.relative(options.repoRoot, binary.program);
1191
+ const inside = relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
1168
1192
  Object.assign(progress, {
1169
- versionSkew: { expected: options.expectedVersion, found: version, path: binary.program },
1193
+ versionSkew: {
1194
+ expected: options.expectedVersion,
1195
+ found: version,
1196
+ source: binary.source,
1197
+ path: inside ? relative : binary.program,
1198
+ },
1170
1199
  });
1171
1200
  }
1172
1201
  // The command-line floor. Only the external tools have one: the umbrella
@@ -1300,6 +1329,94 @@ function spawnAndRead(ctx) {
1300
1329
  // notes. Carried onto every outcome from here on that reports a scan.
1301
1330
  let selection = null;
1302
1331
  const selectionDiagnostics = [];
1332
+ // On a decided trust base, the base lockfiles the head deleted or moved:
1333
+ // candidates for the emptied-lockfile base check below. Null when the base
1334
+ // tree could not be listed, which that check reads as unverified.
1335
+ let removedLockfiles = [];
1336
+ // THE EMPTIED-LOCKFILE BASE CHECK (audit 2026-10-18 N1, design
1337
+ // docs/superpowers/specs/2026-10-18-emptied-lockfile-under-trust-base.md).
1338
+ // Only on a decided trust base and only for the vulnerabilities gate. The
1339
+ // candidates are the emptied handed lockfiles plus the base lockfiles the
1340
+ // head deleted or moved. Called after a completed head scan (every head
1341
+ // could-not-run returns first), or, when nothing at all was handed, in its
1342
+ // place. Returns the could-not-run outcome, or null when the head result
1343
+ // stands. `headArgv` null means no head run, so there is no command line
1344
+ // to hold the base one against.
1345
+ const removalCheck = (input) => {
1346
+ if (gate.product !== 'osv-scanner' || decidedRef === undefined) {
1347
+ return null;
1348
+ }
1349
+ const removed = removedLockfiles;
1350
+ if (input.emptied.length === 0 && removed !== null && removed.length === 0) {
1351
+ return null;
1352
+ }
1353
+ const baseArgv = (copies) => [
1354
+ ...binary.argvPrefix,
1355
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: [...copies] }),
1356
+ ];
1357
+ const checked = removed === null
1358
+ ? { kind: 'unverified', detail: `the base tree at ${decidedRef} could not be listed` }
1359
+ : workDir === null
1360
+ ? { kind: 'unverified', detail: 'there is no work directory to hold the base copies' }
1361
+ : checkEmptiedAgainstBase({
1362
+ repoRoot: options.repoRoot,
1363
+ ref: decidedRef,
1364
+ workDir,
1365
+ emptied: input.emptied,
1366
+ removed,
1367
+ headCounts: input.headCounts,
1368
+ headArgv: input.headArgv,
1369
+ baseArgv,
1370
+ budgetMs: input.budgetMs,
1371
+ spawn: (argv, cwd, budget) => {
1372
+ const baseChild = spawnSync(binary.command, [...argv], {
1373
+ cwd,
1374
+ encoding: 'utf8',
1375
+ timeout: budget,
1376
+ maxBuffer: 64 * 1024 * 1024,
1377
+ });
1378
+ return {
1379
+ status: baseChild.status,
1380
+ stderr: stripAnsi(baseChild.stderr ?? ''),
1381
+ failure: spawnFailure(baseChild),
1382
+ };
1383
+ },
1384
+ });
1385
+ if (checked.kind === 'clear') {
1386
+ return null;
1387
+ }
1388
+ const done = { ...input.outcome, durationMs: Date.now() - started };
1389
+ if (checked.kind === 'timed-out') {
1390
+ const detail = timedOutDetail(gate, 'base-check', timeLimit, checked.elapsedMs, options.trustBase);
1391
+ const timedOut = timedOutRecord('base-check', timeLimit, checked.elapsedMs, checked.signal);
1392
+ return {
1393
+ ...done,
1394
+ couldNotRun: { reason: 'timed-out', detail, timedOut },
1395
+ findings: [timedOutFinding(gate, detail, timedOut)],
1396
+ run: EMPTY_RUN,
1397
+ diagnostics: [],
1398
+ };
1399
+ }
1400
+ const named = [...new Set([...input.emptied, ...(removed ?? [])])];
1401
+ const detail = checked.kind === 'emptied'
1402
+ ? `${checked.files
1403
+ .map((entry) => entry.removed
1404
+ ? `${entry.path} is not in this pull request but had ${entry.packages} package(s) at the base (${decidedRef})`
1405
+ : `${entry.path} read no packages at the head but ${entry.packages} at the base (${decidedRef})`)
1406
+ .join('; ')}, so the dependencies this pull request removed cannot be judged. Regenerate the ` +
1407
+ 'lockfile, or add its replacement beside the same manifest in this pull request, or remove ' +
1408
+ "the manifest's dependencies with it."
1409
+ : `${named.join(', ')} ${named.length === 1 ? 'was' : 'were'} emptied, deleted or moved by this pull ` +
1410
+ `request, and the check that the base had no packages there could not be completed: ` +
1411
+ `${checked.detail}. Nothing the pull request removed was judged.`;
1412
+ return {
1413
+ ...done,
1414
+ couldNotRun: { reason: checked.kind === 'emptied' ? 'lockfile-emptied' : 'lockfile-emptied-unverified', detail },
1415
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
1416
+ run: EMPTY_RUN,
1417
+ diagnostics: [],
1418
+ };
1419
+ };
1303
1420
  // Tracked manifests this gate was NOT handed, when it was handed others
1304
1421
  // (review of 1b.2, item 5): a run note, so a Podfile.lock beside a scanned
1305
1422
  // mix.lock is named without pushing a clean run off its one-line summary.
@@ -1355,6 +1472,7 @@ function spawnAndRead(ctx) {
1355
1472
  selectionDiagnostics.push(...selection.diagnostics);
1356
1473
  if (decidedRef !== undefined) {
1357
1474
  selectionDiagnostics.push(...noLongerScanned(options.repoRoot, decidedRef, new Set(tracked)));
1475
+ removedLockfiles = noLongerScannedFiles(options.repoRoot, decidedRef, new Set(tracked));
1358
1476
  }
1359
1477
  if (external.lockfiles.length > 0) {
1360
1478
  const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
@@ -1365,6 +1483,25 @@ function spawnAndRead(ctx) {
1365
1483
  // without spawning it. The verdict is unchanged (clean); what changes is
1366
1484
  // what is said: which requirements files the pin check left out, and
1367
1485
  // which tracked manifests were not handed to this scanner.
1486
+ // Every lockfile the base had may have been deleted: on a trust base
1487
+ // the removed ones are still checked, with no head scan to precede
1488
+ // it, so the whole limit is the budget.
1489
+ const removedOutcome = removalCheck({
1490
+ emptied: [],
1491
+ headCounts: new Map(),
1492
+ headArgv: null,
1493
+ budgetMs: timeoutMs,
1494
+ outcome: {
1495
+ ...base,
1496
+ productVersion: version,
1497
+ binary,
1498
+ ...(trustBase === undefined ? {} : { trustBase }),
1499
+ exitCode: null,
1500
+ },
1501
+ });
1502
+ if (removedOutcome !== null) {
1503
+ return removedOutcome;
1504
+ }
1368
1505
  const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
1369
1506
  const cleanBecause = 'the verdict is clean because there was nothing to read, not because a scan found nothing.';
1370
1507
  return {
@@ -1517,6 +1654,15 @@ function spawnAndRead(ctx) {
1517
1654
  // Keep the backstop's view current, so an unexpected throw below still
1518
1655
  // reports which binary ran and what it printed.
1519
1656
  Object.assign(progress, withRun);
1657
+ // The emptied-lockfile base check after a completed head scan, under what
1658
+ // is left of the limit (removalCheck, above).
1659
+ const emptiedOnBase = (emptied, headCounts, exitCode) => removalCheck({
1660
+ emptied,
1661
+ headCounts,
1662
+ headArgv: argv,
1663
+ budgetMs: timeoutMs - (Date.now() - spawnStarted),
1664
+ outcome: { ...withRun, exitCode },
1665
+ });
1520
1666
  // THE FIRST THING READ after spawnSync returns, ahead of every status,
1521
1667
  // signal, report and stdout check, and it returns for every error. A child
1522
1668
  // stopped at the limit that handled SIGTERM can come back with status 0, or
@@ -1556,6 +1702,12 @@ function spawnAndRead(ctx) {
1556
1702
  // scan that did not happen. So it is clean, and the report says why.
1557
1703
  if (exitCode !== null && profile.exit.nothingToScan.includes(exitCode)) {
1558
1704
  const handedAll = external.lockfiles ?? [];
1705
+ // Every handed file read nothing: on a trust base, each one's base copy
1706
+ // is checked (the emptied-lockfile check above).
1707
+ const emptiedAll = emptiedOnBase(handedAll, new Map(), exitCode);
1708
+ if (emptiedAll !== null) {
1709
+ return emptiedAll;
1710
+ }
1559
1711
  return {
1560
1712
  ...withRun,
1561
1713
  exitCode: 0,
@@ -1713,6 +1865,45 @@ function spawnAndRead(ctx) {
1713
1865
  // never a could-not-run, unlike the normalizer failure the catch below
1714
1866
  // is for.
1715
1867
  let findings = normalized.findings;
1868
+ // A handed lockfile osv-scanner read no packages from, while it read
1869
+ // packages from another (audit finding F2). Exit 128 above covers only
1870
+ // the all-empty case; this is the rest, named on the coverage line and
1871
+ // in a diagnostic, so an emptied lockfile's advisories never vanish
1872
+ // without a word. Annotation only on a plain run; on a trust base the
1873
+ // emptied-lockfile check runs first, BEFORE the comparison, and a head
1874
+ // that blocked is checked too, so the verdict is could-not-run rather
1875
+ // than blocked when the head emptied a file the base had packages in.
1876
+ const emptied = gate.product === 'osv-scanner'
1877
+ ? emptiedLockfiles(withRun.stderr, external.lockfiles ?? [], spawnCwd)
1878
+ : [];
1879
+ const headCounts = gate.product === 'osv-scanner'
1880
+ ? packageCounts(withRun.stderr, external.lockfiles ?? [], spawnCwd)
1881
+ : new Map();
1882
+ // A LOWERED VERBOSITY FAILS CLOSED on a trust base: without a count line
1883
+ // for a handed lockfile, an emptied one cannot be told from a populated
1884
+ // one, so the check that the head removed nothing cannot run. Said, and
1885
+ // the option left alone: conductor never edits a gate's configuration.
1886
+ const uncounted = gate.product === 'osv-scanner' && decidedRef !== undefined
1887
+ ? (external.lockfiles ?? []).filter((file) => osvLockfileKind(path.posix.basename(file)) !== 'requirements' && !headCounts.has(file))
1888
+ : [];
1889
+ if (uncounted.length > 0) {
1890
+ const detail = `osv-scanner printed no package count for ${uncounted.join(', ')}, which the trust-base check that ` +
1891
+ 'this pull request emptied, deleted or moved no lockfile needs. A verbosity option in the ' +
1892
+ "policy's osv-scanner options hides those counts: remove it.";
1893
+ return {
1894
+ ...withRun,
1895
+ durationMs: Date.now() - started,
1896
+ exitCode,
1897
+ couldNotRun: { reason: 'lockfile-emptied-unverified', detail },
1898
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
1899
+ run: EMPTY_RUN,
1900
+ diagnostics: [],
1901
+ };
1902
+ }
1903
+ const emptiedOutcome = emptiedOnBase(emptied, headCounts, exitCode);
1904
+ if (emptiedOutcome !== null) {
1905
+ return emptiedOutcome;
1906
+ }
1716
1907
  let baseComparison;
1717
1908
  const comparisonDiagnostics = [];
1718
1909
  if (gate.product === 'osv-scanner' &&
@@ -1757,14 +1948,6 @@ function spawnAndRead(ctx) {
1757
1948
  baseComparison = compared.comparison;
1758
1949
  comparisonDiagnostics.push(...compared.diagnostics);
1759
1950
  }
1760
- // A handed lockfile osv-scanner read no packages from, while it read
1761
- // packages from another (audit finding F2). Exit 128 above covers only
1762
- // the all-empty case; this is the rest, named on the coverage line and
1763
- // in a diagnostic, so an emptied lockfile's advisories never vanish
1764
- // without a word. Annotation only: the verdict is osv-scanner's.
1765
- const emptied = gate.product === 'osv-scanner'
1766
- ? emptiedLockfiles(withRun.stderr, external.lockfiles ?? [], spawnCwd)
1767
- : [];
1768
1951
  const emptyDiagnostics = emptied.length === 0
1769
1952
  ? []
1770
1953
  : [
@@ -1,3 +1,4 @@
1
+ import type { ConventionMatch, SelectionMiss } from './intent-spec.js';
1
2
  import type { ResolvedBinary } from './resolve.js';
2
3
  /** Prefix of the per-run directory, exported so a test can count leaks. */
3
4
  export declare const TEMP_PREFIX = "conductor-intent-";
@@ -51,9 +52,32 @@ export type ContractSource =
51
52
  spec: string;
52
53
  plan: string | null;
53
54
  ref?: string;
55
+ /**
56
+ * Set only when the branch-name convention chose the spec. Its presence
57
+ * is how every renderer knows the branch name chose it; nothing
58
+ * recomputes that from the policy or the path.
59
+ */
60
+ match?: ReportedMatch;
54
61
  } | {
55
62
  kind: 'none';
56
63
  };
64
+ /**
65
+ * A convention match as the report carries it: how the spec was chosen, plus
66
+ * which remedy the weak-match line names. `pr-body` on a run with a pull
67
+ * request event (a "Spec:" line), `spec-flag` locally (--spec).
68
+ */
69
+ export type ReportedMatch = ConventionMatch & {
70
+ remedy: 'pr-body' | 'spec-flag';
71
+ };
72
+ /** How many tied specs a report sentence names before "and N more". */
73
+ export declare const TIED_SHOWN = 5;
74
+ /**
75
+ * The legacy clause for a branch 0.10.0 bound and this release does not.
76
+ * Reporting only, for one minor release.
77
+ */
78
+ export declare function legacyNoneSentence(legacy: string): string;
79
+ /** The legacy clause for a branch whose chosen spec changed this release. */
80
+ export declare function legacyChangedSentence(legacy: string): string;
57
81
  export interface IntentPreparation {
58
82
  contractSource: ContractSource;
59
83
  /** The ref the change set was measured against, or null for a staged run. */
@@ -112,10 +136,18 @@ export type IntentPrepareResult = {
112
136
  */
113
137
  | {
114
138
  kind: 'skip';
115
- reason: 'no-contract' | 'contract-waived';
139
+ /**
140
+ * `spec-ambiguous`: two or more specs matched the branch name equally,
141
+ * so none was chosen. Its own reason because its remedy differs (a
142
+ * spec exists; choose one) and because a tie that 0.10.0 silently
143
+ * broke must not file itself under "nobody wrote one".
144
+ */
145
+ reason: 'no-contract' | 'contract-waived' | 'spec-ambiguous';
116
146
  detail: string;
117
147
  /** As on IntentPreparation: what this pull request proposes. */
118
148
  proposals?: string[];
149
+ /** What the branch-name convention said, for the details bag. */
150
+ selection?: SelectionMiss;
119
151
  } | {
120
152
  kind: 'failed';
121
153
  step: PrepareStep;
@@ -37,7 +37,7 @@ import { parse as parseYaml } from 'yaml';
37
37
  import { gitComplaint, runGit } from './git.js';
38
38
  import { changedPathsSince, currentBranch, orderForPathsFlag, pathsFlagRefusal, resolveBaseRefInRepo, } from './intent-base.js';
39
39
  import { summariseStderr } from './normalize.js';
40
- import { PLAN_DIR, SPEC_DIR, SPEC_WAIVER_TOKEN, bestMatch, branchSlug, discoverSpec, normalizeStem, prBodyFromEvent, specFromPrBody, } from './intent-spec.js';
40
+ import { PLAN_DIR, SPEC_DIR, SPEC_WAIVER_TOKEN, discoverSpec, matchOf, normalizeStem, prBodyFromEvent, selectByBranch, specFromPrBody, } from './intent-spec.js';
41
41
  import { readFileAtRef, unreadableBaseRemedy } from './trust-base.js';
42
42
  /** Prefix of the per-run directory, exported so a test can count leaks. */
43
43
  export const TEMP_PREFIX = 'conductor-intent-';
@@ -80,6 +80,82 @@ export const NATIVE_CONTRACT_PATHS = [
80
80
  export function isLegacyContractPath(contractPath) {
81
81
  return contractPath === LEGACY_NATIVE_CONTRACT_PATH;
82
82
  }
83
+ /** How many tied specs a report sentence names before "and N more". */
84
+ export const TIED_SHOWN = 5;
85
+ /** The tied specs, as repository paths, capped for a report sentence. */
86
+ function tiedList(tied) {
87
+ const shown = tied.slice(0, TIED_SHOWN).map((name) => `${SPEC_DIR}/${name}`);
88
+ const more = tied.length - shown.length;
89
+ return more > 0 ? `${shown.join(', ')}, and ${more} more` : shown.join(', ');
90
+ }
91
+ /** The skip detail when two or more specs match the branch equally (5.2). */
92
+ function ambiguousDetail(branch, tied, ref) {
93
+ return (`No spec was chosen: the branch name "${branch}" matches ${tied.length} specs equally` +
94
+ `${ref === undefined ? '' : ` on "${ref}"`} (${tiedList(tied)}), and conductor does not ` +
95
+ 'guess between them. Add a "Spec: <path>" line to the pull request body or pass --spec, ' +
96
+ "or rename the branch to one spec's name.");
97
+ }
98
+ /**
99
+ * The legacy clause for a branch 0.10.0 bound and this release does not.
100
+ * Reporting only, for one minor release.
101
+ */
102
+ export function legacyNoneSentence(legacy) {
103
+ return (`Before conductor 0.11.0 this branch name chose ${SPEC_DIR}/${legacy} by a partial-word ` +
104
+ 'match; it no longer does.');
105
+ }
106
+ /** The legacy clause for a branch whose chosen spec changed this release. */
107
+ export function legacyChangedSentence(legacy) {
108
+ return (`Before conductor 0.11.0 this branch name chose ${SPEC_DIR}/${legacy}; it now chooses this ` +
109
+ 'spec, which matches it on whole words.');
110
+ }
111
+ /** The sentences a no-contract skip gains from the convention's answer. */
112
+ function selectionSuffix(branch, selection) {
113
+ if (selection === undefined) {
114
+ return '';
115
+ }
116
+ const sentences = [];
117
+ if (selection.why === 'no-usable-token' && branch !== null) {
118
+ sentences.push(`The branch name "${branch}" has no word of three or more letters that is not a common ` +
119
+ 'branch word (fix, feat, wip, ...), so it cannot choose a spec.');
120
+ }
121
+ if (selection.legacy !== null) {
122
+ sentences.push(legacyNoneSentence(selection.legacy));
123
+ }
124
+ return sentences.map((sentence) => ` ${sentence}`).join('');
125
+ }
126
+ /**
127
+ * The selection a skip carries for its details bag, or undefined when it
128
+ * says nothing the ordinary adoption-ramp skip does not: a usable branch name
129
+ * that matched no spec, under either rule, keeps its 0.10.0 shape exactly.
130
+ */
131
+ function reportedSelection(selection) {
132
+ if (selection === undefined || (selection.why === 'no-candidate' && selection.legacy === null)) {
133
+ return undefined;
134
+ }
135
+ return selection;
136
+ }
137
+ /** The skip for a convention that found nothing, on either path. */
138
+ function noSpecChosen(branch, selection, noContractDetail, proposals, ref) {
139
+ const reported = reportedSelection(selection);
140
+ const withProposals = proposals.length === 0 ? {} : { proposals };
141
+ if (selection !== undefined && selection.why === 'ambiguous' && branch !== null) {
142
+ return {
143
+ kind: 'skip',
144
+ reason: 'spec-ambiguous',
145
+ detail: ambiguousDetail(branch, selection.tied, ref) +
146
+ (selection.legacy === null ? '' : ` ${legacyNoneSentence(selection.legacy)}`),
147
+ selection,
148
+ ...withProposals,
149
+ };
150
+ }
151
+ return {
152
+ kind: 'skip',
153
+ reason: 'no-contract',
154
+ detail: noContractDetail + selectionSuffix(branch, selection),
155
+ ...(reported === undefined ? {} : { selection: reported }),
156
+ ...withProposals,
157
+ };
158
+ }
83
159
  /**
84
160
  * Whether a contract on disk has been approved.
85
161
  *
@@ -393,17 +469,21 @@ export function prepareIntent(options) {
393
469
  else if (discovery.kind === 'none') {
394
470
  source = { kind: 'none' };
395
471
  }
472
+ else if (discovery.kind === 'convention') {
473
+ source = {
474
+ kind: 'imported',
475
+ spec: discovery.spec,
476
+ plan: discovery.plan,
477
+ match: { ...discovery.match, remedy: eventPath === undefined ? 'spec-flag' : 'pr-body' },
478
+ };
479
+ }
396
480
  else {
397
481
  source = { kind: 'imported', spec: discovery.spec, plan: discovery.plan };
398
482
  }
399
483
  if (source.kind === 'none') {
400
- return {
401
- kind: 'skip',
402
- reason: 'no-contract',
403
- detail: `No frozen ${NATIVE_CONTRACT_PATHS.join(' or ')} and no spec under ${SPEC_DIR} matching ` +
404
- `${branch === null ? 'this branch' : `branch "${branch}"`}. ` +
405
- 'Name one with a "Spec: <path>" line in the pull request body, or pass --spec.',
406
- };
484
+ return noSpecChosen(branch, discovery.kind === 'none' ? discovery.selection : undefined, `No frozen ${NATIVE_CONTRACT_PATHS.join(' or ')} and no spec under ${SPEC_DIR} matching ` +
485
+ `${branch === null ? 'this branch' : `branch "${branch}"`}. ` +
486
+ 'Name one with a "Spec: <path>" line in the pull request body, or pass --spec.', []);
407
487
  }
408
488
  return finishPreparation(options, source, null, []);
409
489
  }
@@ -785,12 +865,19 @@ function planAtRef(repoRoot, ref, spec) {
785
865
  * failure, never "no spec".
786
866
  */
787
867
  function discoverSpecAtRef(repoRoot, ref, inputs) {
788
- const found = (spec, specText) => {
868
+ const found = (spec, specText, match) => {
789
869
  const plan = planAtRef(repoRoot, ref, spec);
790
870
  if (!plan.ok) {
791
871
  return { kind: 'failed', detail: plan.detail };
792
872
  }
793
- return { kind: 'found', spec, specText, plan: plan.plan, planText: plan.planText };
873
+ return {
874
+ kind: 'found',
875
+ spec,
876
+ specText,
877
+ plan: plan.plan,
878
+ planText: plan.planText,
879
+ ...(match === undefined ? {} : { match }),
880
+ };
794
881
  };
795
882
  if (inputs.spec !== undefined) {
796
883
  const relative = toRepoRelative(repoRoot, inputs.spec);
@@ -837,18 +924,25 @@ function discoverSpecAtRef(repoRoot, ref, inputs) {
837
924
  if (!listed.ok) {
838
925
  return { kind: 'failed', detail: listed.detail };
839
926
  }
840
- const best = bestMatch(listed.names, branchSlug(inputs.branch));
841
- if (best !== undefined) {
842
- const relative = `${SPEC_DIR}/${best}`;
843
- const read = readFileAtRef(repoRoot, ref, relative);
844
- if (read.kind !== 'file') {
845
- return {
846
- kind: 'failed',
847
- detail: read.kind === 'error' ? read.detail : `${relative} was listed at "${ref}" but not found`,
848
- };
849
- }
850
- return found(relative, read.text);
927
+ // The same selector as the working tree, over the names listed AT THE
928
+ // BASE: a head branch name only ever chooses among the base's specs.
929
+ const selection = selectByBranch(listed.names, inputs.branch);
930
+ if (selection.kind === 'none') {
931
+ return {
932
+ kind: 'none',
933
+ flagOnHead: null,
934
+ selection: { why: selection.why, tied: selection.tied, legacy: selection.legacy },
935
+ };
936
+ }
937
+ const relative = `${SPEC_DIR}/${selection.name}`;
938
+ const read = readFileAtRef(repoRoot, ref, relative);
939
+ if (read.kind !== 'file') {
940
+ return {
941
+ kind: 'failed',
942
+ detail: read.kind === 'error' ? read.detail : `${relative} was listed at "${ref}" but not found`,
943
+ };
851
944
  }
945
+ return found(relative, read.text, matchOf(selection));
852
946
  }
853
947
  return { kind: 'none', flagOnHead: null };
854
948
  }
@@ -943,7 +1037,22 @@ function prepareAgainstTrustBase(options, trustBase) {
943
1037
  files.push({ path: atBase.plan, baseText: atBase.planText });
944
1038
  }
945
1039
  proposals.push(...importedFileProposals(repoRoot, trustBase, files));
946
- return finishPreparation(options, { kind: 'imported', spec: atBase.spec, plan: atBase.plan, ref: trustBase }, { ref: trustBase, specText: atBase.specText, planText: atBase.planText }, proposals);
1040
+ return finishPreparation(options, {
1041
+ kind: 'imported',
1042
+ spec: atBase.spec,
1043
+ plan: atBase.plan,
1044
+ ref: trustBase,
1045
+ ...(atBase.match === undefined
1046
+ ? {}
1047
+ : { match: { ...atBase.match, remedy: eventPath === undefined ? 'spec-flag' : 'pr-body' } }),
1048
+ }, { ref: trustBase, specText: atBase.specText, planText: atBase.planText }, proposals);
1049
+ }
1050
+ // The base carries SEVERAL specs the branch name matches equally. Saying
1051
+ // the base has no spec for the branch would be false, so this returns
1052
+ // before the head-spec proposal below: no spec is proposed when the base
1053
+ // already has candidates. The proposals already collected are kept.
1054
+ if (atBase.selection?.why === 'ambiguous') {
1055
+ return noSpecChosen(branch, atBase.selection, '', proposals, trustBase);
947
1056
  }
948
1057
  // Nothing on the base. A spec the head carries is a proposal, and a --spec
949
1058
  // that names a file neither side has is still reported as missing.
@@ -969,15 +1078,10 @@ function prepareAgainstTrustBase(options, trustBase) {
969
1078
  proposals.push(`${headSpec} is a spec in this pull request but not on "${trustBase}": it is a proposal, ` +
970
1079
  'and pull requests are judged against it once it is on the base branch.');
971
1080
  }
972
- return {
973
- kind: 'skip',
974
- reason: 'no-contract',
975
- detail: `No contract on the base: "${trustBase}" carries no frozen ` +
976
- `${NATIVE_CONTRACT_PATHS.join(' or ')} and no spec under ${SPEC_DIR} for ` +
977
- `${branch === null ? 'this branch' : `branch "${branch}"`}. On a pull-request run the ` +
978
- 'intent contract comes from the base ref only, so nothing in this pull request can ' +
979
- 'become it; once a contract or spec is on the base branch, the next pull request is ' +
980
- 'judged against it.',
981
- ...(proposals.length === 0 ? {} : { proposals }),
982
- };
1081
+ return noSpecChosen(branch, atBase.selection, `No contract on the base: "${trustBase}" carries no frozen ` +
1082
+ `${NATIVE_CONTRACT_PATHS.join(' or ')} and no spec under ${SPEC_DIR} for ` +
1083
+ `${branch === null ? 'this branch' : `branch "${branch}"`}. On a pull-request run the ` +
1084
+ 'intent contract comes from the base ref only, so nothing in this pull request can ' +
1085
+ 'become it; once a contract or spec is on the base branch, the next pull request is ' +
1086
+ 'judged against it.', proposals, trustBase);
983
1087
  }