@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.
- package/README.md +131 -21
- package/dist/cli.js +27 -2
- package/dist/envelope.d.ts +7 -1
- package/dist/gate-runner.d.ts +36 -10
- package/dist/gate-runner.js +202 -19
- package/dist/intent-prepare.d.ts +33 -1
- package/dist/intent-prepare.js +137 -33
- package/dist/intent-spec.d.ts +108 -22
- package/dist/intent-spec.js +226 -55
- package/dist/normalize.js +28 -3
- package/dist/osv-baseline.d.ts +65 -0
- package/dist/osv-baseline.js +105 -1
- package/dist/osv-coverage.d.ts +18 -2
- package/dist/osv-coverage.js +47 -10
- package/dist/output-sarif.js +90 -1
- package/dist/output-text.d.ts +39 -7
- package/dist/output-text.js +205 -19
- package/dist/run.d.ts +9 -1
- package/dist/run.js +1 -0
- package/dist/unread-manifests.js +4 -0
- package/package.json +1 -1
package/dist/gate-runner.js
CHANGED
|
@@ -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
|
|
1162
|
-
//
|
|
1163
|
-
//
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
|
|
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: {
|
|
1193
|
+
versionSkew: {
|
|
1194
|
+
expected: options.expectedVersion,
|
|
1195
|
+
found: version,
|
|
1196
|
+
source: binary.source,
|
|
1197
|
+
path: inside ? relative : binary.program,
|
|
1198
|
+
},
|
|
1170
1199
|
});
|
|
1171
1200
|
}
|
|
1172
1201
|
// The command-line floor. Only the external tools have one: the umbrella
|
|
@@ -1300,6 +1329,94 @@ function spawnAndRead(ctx) {
|
|
|
1300
1329
|
// notes. Carried onto every outcome from here on that reports a scan.
|
|
1301
1330
|
let selection = null;
|
|
1302
1331
|
const selectionDiagnostics = [];
|
|
1332
|
+
// On a decided trust base, the base lockfiles the head deleted or moved:
|
|
1333
|
+
// candidates for the emptied-lockfile base check below. Null when the base
|
|
1334
|
+
// tree could not be listed, which that check reads as unverified.
|
|
1335
|
+
let removedLockfiles = [];
|
|
1336
|
+
// THE EMPTIED-LOCKFILE BASE CHECK (audit 2026-10-18 N1, design
|
|
1337
|
+
// docs/superpowers/specs/2026-10-18-emptied-lockfile-under-trust-base.md).
|
|
1338
|
+
// Only on a decided trust base and only for the vulnerabilities gate. The
|
|
1339
|
+
// candidates are the emptied handed lockfiles plus the base lockfiles the
|
|
1340
|
+
// head deleted or moved. Called after a completed head scan (every head
|
|
1341
|
+
// could-not-run returns first), or, when nothing at all was handed, in its
|
|
1342
|
+
// place. Returns the could-not-run outcome, or null when the head result
|
|
1343
|
+
// stands. `headArgv` null means no head run, so there is no command line
|
|
1344
|
+
// to hold the base one against.
|
|
1345
|
+
const removalCheck = (input) => {
|
|
1346
|
+
if (gate.product !== 'osv-scanner' || decidedRef === undefined) {
|
|
1347
|
+
return null;
|
|
1348
|
+
}
|
|
1349
|
+
const removed = removedLockfiles;
|
|
1350
|
+
if (input.emptied.length === 0 && removed !== null && removed.length === 0) {
|
|
1351
|
+
return null;
|
|
1352
|
+
}
|
|
1353
|
+
const baseArgv = (copies) => [
|
|
1354
|
+
...binary.argvPrefix,
|
|
1355
|
+
...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: [...copies] }),
|
|
1356
|
+
];
|
|
1357
|
+
const checked = removed === null
|
|
1358
|
+
? { kind: 'unverified', detail: `the base tree at ${decidedRef} could not be listed` }
|
|
1359
|
+
: workDir === null
|
|
1360
|
+
? { kind: 'unverified', detail: 'there is no work directory to hold the base copies' }
|
|
1361
|
+
: checkEmptiedAgainstBase({
|
|
1362
|
+
repoRoot: options.repoRoot,
|
|
1363
|
+
ref: decidedRef,
|
|
1364
|
+
workDir,
|
|
1365
|
+
emptied: input.emptied,
|
|
1366
|
+
removed,
|
|
1367
|
+
headCounts: input.headCounts,
|
|
1368
|
+
headArgv: input.headArgv,
|
|
1369
|
+
baseArgv,
|
|
1370
|
+
budgetMs: input.budgetMs,
|
|
1371
|
+
spawn: (argv, cwd, budget) => {
|
|
1372
|
+
const baseChild = spawnSync(binary.command, [...argv], {
|
|
1373
|
+
cwd,
|
|
1374
|
+
encoding: 'utf8',
|
|
1375
|
+
timeout: budget,
|
|
1376
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
1377
|
+
});
|
|
1378
|
+
return {
|
|
1379
|
+
status: baseChild.status,
|
|
1380
|
+
stderr: stripAnsi(baseChild.stderr ?? ''),
|
|
1381
|
+
failure: spawnFailure(baseChild),
|
|
1382
|
+
};
|
|
1383
|
+
},
|
|
1384
|
+
});
|
|
1385
|
+
if (checked.kind === 'clear') {
|
|
1386
|
+
return null;
|
|
1387
|
+
}
|
|
1388
|
+
const done = { ...input.outcome, durationMs: Date.now() - started };
|
|
1389
|
+
if (checked.kind === 'timed-out') {
|
|
1390
|
+
const detail = timedOutDetail(gate, 'base-check', timeLimit, checked.elapsedMs, options.trustBase);
|
|
1391
|
+
const timedOut = timedOutRecord('base-check', timeLimit, checked.elapsedMs, checked.signal);
|
|
1392
|
+
return {
|
|
1393
|
+
...done,
|
|
1394
|
+
couldNotRun: { reason: 'timed-out', detail, timedOut },
|
|
1395
|
+
findings: [timedOutFinding(gate, detail, timedOut)],
|
|
1396
|
+
run: EMPTY_RUN,
|
|
1397
|
+
diagnostics: [],
|
|
1398
|
+
};
|
|
1399
|
+
}
|
|
1400
|
+
const named = [...new Set([...input.emptied, ...(removed ?? [])])];
|
|
1401
|
+
const detail = checked.kind === 'emptied'
|
|
1402
|
+
? `${checked.files
|
|
1403
|
+
.map((entry) => entry.removed
|
|
1404
|
+
? `${entry.path} is not in this pull request but had ${entry.packages} package(s) at the base (${decidedRef})`
|
|
1405
|
+
: `${entry.path} read no packages at the head but ${entry.packages} at the base (${decidedRef})`)
|
|
1406
|
+
.join('; ')}, so the dependencies this pull request removed cannot be judged. Regenerate the ` +
|
|
1407
|
+
'lockfile, or add its replacement beside the same manifest in this pull request, or remove ' +
|
|
1408
|
+
"the manifest's dependencies with it."
|
|
1409
|
+
: `${named.join(', ')} ${named.length === 1 ? 'was' : 'were'} emptied, deleted or moved by this pull ` +
|
|
1410
|
+
`request, and the check that the base had no packages there could not be completed: ` +
|
|
1411
|
+
`${checked.detail}. Nothing the pull request removed was judged.`;
|
|
1412
|
+
return {
|
|
1413
|
+
...done,
|
|
1414
|
+
couldNotRun: { reason: checked.kind === 'emptied' ? 'lockfile-emptied' : 'lockfile-emptied-unverified', detail },
|
|
1415
|
+
findings: [normalizeFailedGate(gate.role, gate.product, detail)],
|
|
1416
|
+
run: EMPTY_RUN,
|
|
1417
|
+
diagnostics: [],
|
|
1418
|
+
};
|
|
1419
|
+
};
|
|
1303
1420
|
// Tracked manifests this gate was NOT handed, when it was handed others
|
|
1304
1421
|
// (review of 1b.2, item 5): a run note, so a Podfile.lock beside a scanned
|
|
1305
1422
|
// mix.lock is named without pushing a clean run off its one-line summary.
|
|
@@ -1355,6 +1472,7 @@ function spawnAndRead(ctx) {
|
|
|
1355
1472
|
selectionDiagnostics.push(...selection.diagnostics);
|
|
1356
1473
|
if (decidedRef !== undefined) {
|
|
1357
1474
|
selectionDiagnostics.push(...noLongerScanned(options.repoRoot, decidedRef, new Set(tracked)));
|
|
1475
|
+
removedLockfiles = noLongerScannedFiles(options.repoRoot, decidedRef, new Set(tracked));
|
|
1358
1476
|
}
|
|
1359
1477
|
if (external.lockfiles.length > 0) {
|
|
1360
1478
|
const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
|
|
@@ -1365,6 +1483,25 @@ function spawnAndRead(ctx) {
|
|
|
1365
1483
|
// without spawning it. The verdict is unchanged (clean); what changes is
|
|
1366
1484
|
// what is said: which requirements files the pin check left out, and
|
|
1367
1485
|
// which tracked manifests were not handed to this scanner.
|
|
1486
|
+
// Every lockfile the base had may have been deleted: on a trust base
|
|
1487
|
+
// the removed ones are still checked, with no head scan to precede
|
|
1488
|
+
// it, so the whole limit is the budget.
|
|
1489
|
+
const removedOutcome = removalCheck({
|
|
1490
|
+
emptied: [],
|
|
1491
|
+
headCounts: new Map(),
|
|
1492
|
+
headArgv: null,
|
|
1493
|
+
budgetMs: timeoutMs,
|
|
1494
|
+
outcome: {
|
|
1495
|
+
...base,
|
|
1496
|
+
productVersion: version,
|
|
1497
|
+
binary,
|
|
1498
|
+
...(trustBase === undefined ? {} : { trustBase }),
|
|
1499
|
+
exitCode: null,
|
|
1500
|
+
},
|
|
1501
|
+
});
|
|
1502
|
+
if (removedOutcome !== null) {
|
|
1503
|
+
return removedOutcome;
|
|
1504
|
+
}
|
|
1368
1505
|
const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
|
|
1369
1506
|
const cleanBecause = 'the verdict is clean because there was nothing to read, not because a scan found nothing.';
|
|
1370
1507
|
return {
|
|
@@ -1517,6 +1654,15 @@ function spawnAndRead(ctx) {
|
|
|
1517
1654
|
// Keep the backstop's view current, so an unexpected throw below still
|
|
1518
1655
|
// reports which binary ran and what it printed.
|
|
1519
1656
|
Object.assign(progress, withRun);
|
|
1657
|
+
// The emptied-lockfile base check after a completed head scan, under what
|
|
1658
|
+
// is left of the limit (removalCheck, above).
|
|
1659
|
+
const emptiedOnBase = (emptied, headCounts, exitCode) => removalCheck({
|
|
1660
|
+
emptied,
|
|
1661
|
+
headCounts,
|
|
1662
|
+
headArgv: argv,
|
|
1663
|
+
budgetMs: timeoutMs - (Date.now() - spawnStarted),
|
|
1664
|
+
outcome: { ...withRun, exitCode },
|
|
1665
|
+
});
|
|
1520
1666
|
// THE FIRST THING READ after spawnSync returns, ahead of every status,
|
|
1521
1667
|
// signal, report and stdout check, and it returns for every error. A child
|
|
1522
1668
|
// stopped at the limit that handled SIGTERM can come back with status 0, or
|
|
@@ -1556,6 +1702,12 @@ function spawnAndRead(ctx) {
|
|
|
1556
1702
|
// scan that did not happen. So it is clean, and the report says why.
|
|
1557
1703
|
if (exitCode !== null && profile.exit.nothingToScan.includes(exitCode)) {
|
|
1558
1704
|
const handedAll = external.lockfiles ?? [];
|
|
1705
|
+
// Every handed file read nothing: on a trust base, each one's base copy
|
|
1706
|
+
// is checked (the emptied-lockfile check above).
|
|
1707
|
+
const emptiedAll = emptiedOnBase(handedAll, new Map(), exitCode);
|
|
1708
|
+
if (emptiedAll !== null) {
|
|
1709
|
+
return emptiedAll;
|
|
1710
|
+
}
|
|
1559
1711
|
return {
|
|
1560
1712
|
...withRun,
|
|
1561
1713
|
exitCode: 0,
|
|
@@ -1713,6 +1865,45 @@ function spawnAndRead(ctx) {
|
|
|
1713
1865
|
// never a could-not-run, unlike the normalizer failure the catch below
|
|
1714
1866
|
// is for.
|
|
1715
1867
|
let findings = normalized.findings;
|
|
1868
|
+
// A handed lockfile osv-scanner read no packages from, while it read
|
|
1869
|
+
// packages from another (audit finding F2). Exit 128 above covers only
|
|
1870
|
+
// the all-empty case; this is the rest, named on the coverage line and
|
|
1871
|
+
// in a diagnostic, so an emptied lockfile's advisories never vanish
|
|
1872
|
+
// without a word. Annotation only on a plain run; on a trust base the
|
|
1873
|
+
// emptied-lockfile check runs first, BEFORE the comparison, and a head
|
|
1874
|
+
// that blocked is checked too, so the verdict is could-not-run rather
|
|
1875
|
+
// than blocked when the head emptied a file the base had packages in.
|
|
1876
|
+
const emptied = gate.product === 'osv-scanner'
|
|
1877
|
+
? emptiedLockfiles(withRun.stderr, external.lockfiles ?? [], spawnCwd)
|
|
1878
|
+
: [];
|
|
1879
|
+
const headCounts = gate.product === 'osv-scanner'
|
|
1880
|
+
? packageCounts(withRun.stderr, external.lockfiles ?? [], spawnCwd)
|
|
1881
|
+
: new Map();
|
|
1882
|
+
// A LOWERED VERBOSITY FAILS CLOSED on a trust base: without a count line
|
|
1883
|
+
// for a handed lockfile, an emptied one cannot be told from a populated
|
|
1884
|
+
// one, so the check that the head removed nothing cannot run. Said, and
|
|
1885
|
+
// the option left alone: conductor never edits a gate's configuration.
|
|
1886
|
+
const uncounted = gate.product === 'osv-scanner' && decidedRef !== undefined
|
|
1887
|
+
? (external.lockfiles ?? []).filter((file) => osvLockfileKind(path.posix.basename(file)) !== 'requirements' && !headCounts.has(file))
|
|
1888
|
+
: [];
|
|
1889
|
+
if (uncounted.length > 0) {
|
|
1890
|
+
const detail = `osv-scanner printed no package count for ${uncounted.join(', ')}, which the trust-base check that ` +
|
|
1891
|
+
'this pull request emptied, deleted or moved no lockfile needs. A verbosity option in the ' +
|
|
1892
|
+
"policy's osv-scanner options hides those counts: remove it.";
|
|
1893
|
+
return {
|
|
1894
|
+
...withRun,
|
|
1895
|
+
durationMs: Date.now() - started,
|
|
1896
|
+
exitCode,
|
|
1897
|
+
couldNotRun: { reason: 'lockfile-emptied-unverified', detail },
|
|
1898
|
+
findings: [normalizeFailedGate(gate.role, gate.product, detail)],
|
|
1899
|
+
run: EMPTY_RUN,
|
|
1900
|
+
diagnostics: [],
|
|
1901
|
+
};
|
|
1902
|
+
}
|
|
1903
|
+
const emptiedOutcome = emptiedOnBase(emptied, headCounts, exitCode);
|
|
1904
|
+
if (emptiedOutcome !== null) {
|
|
1905
|
+
return emptiedOutcome;
|
|
1906
|
+
}
|
|
1716
1907
|
let baseComparison;
|
|
1717
1908
|
const comparisonDiagnostics = [];
|
|
1718
1909
|
if (gate.product === 'osv-scanner' &&
|
|
@@ -1757,14 +1948,6 @@ function spawnAndRead(ctx) {
|
|
|
1757
1948
|
baseComparison = compared.comparison;
|
|
1758
1949
|
comparisonDiagnostics.push(...compared.diagnostics);
|
|
1759
1950
|
}
|
|
1760
|
-
// A handed lockfile osv-scanner read no packages from, while it read
|
|
1761
|
-
// packages from another (audit finding F2). Exit 128 above covers only
|
|
1762
|
-
// the all-empty case; this is the rest, named on the coverage line and
|
|
1763
|
-
// in a diagnostic, so an emptied lockfile's advisories never vanish
|
|
1764
|
-
// without a word. Annotation only: the verdict is osv-scanner's.
|
|
1765
|
-
const emptied = gate.product === 'osv-scanner'
|
|
1766
|
-
? emptiedLockfiles(withRun.stderr, external.lockfiles ?? [], spawnCwd)
|
|
1767
|
-
: [];
|
|
1768
1951
|
const emptyDiagnostics = emptied.length === 0
|
|
1769
1952
|
? []
|
|
1770
1953
|
: [
|
package/dist/intent-prepare.d.ts
CHANGED
|
@@ -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
|
-
|
|
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;
|
package/dist/intent-prepare.js
CHANGED
|
@@ -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,
|
|
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
|
-
|
|
402
|
-
|
|
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 {
|
|
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
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
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, {
|
|
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
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
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
|
}
|