From 1834580c74abb8d58f82d79ab0ed791670e2f0db Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Tue, 10 Nov 2026 05:38:26 +0000 Subject: [PATCH 01/14] fix(release): enforce the #1657 peer-floor rules in the release checks Fixes #1657 The 0.12.6 mobile and 0.15.5 web patch releases raised their `e2e` peer floor to `>=0.22.1`, but no stable `e2e@0.22.1` ever shipped, so a fresh install of an unchanged project on `e2e ~0.21.3` fails with ERESOLVE. Per the maintainer direction on #1657, the fix is in the release checks: a floor must name a released version, a raise past a runner minor the previous range accepted needs a `**Breaking:**` minor, and a new `e2e/engine` import counts as a raise. The floors move to the released versions they already meant in practice: web and mobile to `>=0.23.0` (first version exporting `stepTimeout` and the `EngineDoctorCheck` types), acp to `>=0.22.0` (first version exporting the `e2e/agent` rules and tools it imports), limrun to mobile `>=0.11.0`. Signed-off-by: Varshith Puli --- .changeset/engine-peer-floors.md | 8 ++ AGENTS.md | 7 +- packages/acp/package.json | 2 +- packages/limrun/package.json | 2 +- scripts/changeset-bumps.test.ts | 130 ++++++++++++++++++- scripts/changeset-bumps.ts | 128 +++++++++++++++++++ scripts/check-changeset-bumps.ts | 98 +++++++++++++-- scripts/check-peer-ranges.ts | 122 ++++++++++++++++-- scripts/engine-exports.test.ts | 163 ++++++++++++++++++++++++ scripts/engine-exports.ts | 208 +++++++++++++++++++++++++++++++ scripts/peer-ranges.test.ts | 103 +++++++++++++++ scripts/peer-ranges.ts | 88 +++++++++++++ 12 files changed, 1037 insertions(+), 22 deletions(-) create mode 100644 .changeset/engine-peer-floors.md create mode 100644 scripts/engine-exports.test.ts create mode 100644 scripts/engine-exports.ts create mode 100644 scripts/peer-ranges.test.ts create mode 100644 scripts/peer-ranges.ts diff --git a/.changeset/engine-peer-floors.md b/.changeset/engine-peer-floors.md new file mode 100644 index 0000000000..4bfe10d29e --- /dev/null +++ b/.changeset/engine-peer-floors.md @@ -0,0 +1,8 @@ +--- +"@e2e-dev/web": patch +"@e2e-dev/mobile": patch +"@e2e-dev/acp": patch +"@e2e-dev/limrun": patch +--- + +Name the released version each peer floor already meant in practice: web and mobile move their `e2e` peer floor from the never-published `0.22.1` to `0.23.0`, which first exports the `stepTimeout` value and the `EngineDoctorCheck` types both engines import; acp moves from the never-published `0.21.4` to `0.22.0`, which first exports the `e2e/agent` rules and tools it imports; limrun moves its mobile peer from the never-published `0.11.1` to `0.11.0`. None of these cuts off a released version a consumer could install on the old range, so each is a patch. The release checks now enforce all three rules from #1657: a floor must name a released version (or the runner version in the same release), a raise past a runner minor the previous range accepted needs a `**Breaking:**` minor, and a new `e2e/engine` import counts as a raise. diff --git a/AGENTS.md b/AGENTS.md index e1d50d8519..bd968f6c86 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -719,7 +719,12 @@ trees, on both platforms, without a device. newer sibling's export or contract field; `scripts/check-peer-ranges.ts` (`pnpm check`) fails on any other shape for every peer one package under `packages/` has on another (vendor SDK peers - such as `@onkernel/sdk` are not checked). Narrow or exact, every runner minor (exact: every patch too) + such as `@onkernel/sdk` are not checked). The floor must name a version the + sibling released, or the runner version in the same release, and a raise + past a runner minor the previous range accepted needs a `**Breaking:**` + minor changeset (`scripts/check-changeset-bumps.ts`); a new `e2e/engine` + import counts as a raise, so the check also fails any `e2e/*` import the + floor version does not export, read off the `e2e@` tag. Narrow or exact, every runner minor (exact: every patch too) falls out of range, and changesets 3 then patch-bumps each engine and rewrites its pin, never a major (`determineDependents` in `@changesets/assemble-release-plan` patches an out-of-range peer dependent). diff --git a/packages/acp/package.json b/packages/acp/package.json index c804bf40f2..d4606cb12b 100644 --- a/packages/acp/package.json +++ b/packages/acp/package.json @@ -51,7 +51,7 @@ "zod": "4.6.7" }, "peerDependencies": { - "e2e": ">=0.21.4 <1" + "e2e": ">=0.22.0 <1" }, "devDependencies": { "@modelcontextprotocol/client": "2.4.0", diff --git a/packages/limrun/package.json b/packages/limrun/package.json index 3c419263d9..f29759b5eb 100644 --- a/packages/limrun/package.json +++ b/packages/limrun/package.json @@ -48,7 +48,7 @@ "test:unit": "vitest run tests/unit" }, "peerDependencies": { - "@e2e-dev/mobile": ">=0.11.1 <1", + "@e2e-dev/mobile": ">=0.11.0 <1", "@limrun/api": ">=0.59.0 <1", "e2e": ">=0.15.0 <1" }, diff --git a/scripts/changeset-bumps.test.ts b/scripts/changeset-bumps.test.ts index 5af9d0fe5d..e9ac0309dc 100644 --- a/scripts/changeset-bumps.test.ts +++ b/scripts/changeset-bumps.test.ts @@ -1,7 +1,16 @@ import assert from 'node:assert/strict'; import { describe, it } from 'node:test'; import { parseChangesetFile } from '@changesets/parse'; -import { disallowedBumps } from './changeset-bumps.ts'; +import { + announcesFloorRaise, + disallowedBumps, + floorRaiseProblems, + floorRaisesPastMinor, + nextVersionAfterBump, + parseVersion, + pendingBumps, + type FloorRaiseInput, +} from './changeset-bumps.ts'; const versions = new Map([ ['e2e', '0.20.0'], @@ -36,3 +45,122 @@ describe('disallowedBumps', () => { assert.deepEqual(disallowedBumps(parseChangesetFile('---\n---\n'), versions), []); }); }); + +describe('floorRaisesPastMinor', () => { + const released = new Set(['0.18.0', '0.19.0', '0.20.0', '0.21.0', '0.21.3', '0.22.0', '0.23.0']); + + it('flags a raise that cuts off a released version on an older minor', () => { + assert.equal(floorRaisesPastMinor('0.22.0', '0.23.0', released), true); + assert.equal(floorRaisesPastMinor('0.18.0', '0.23.0', released), true); + }); + + it('passes a raise within one minor, a lowering, and no change', () => { + assert.equal(floorRaisesPastMinor('0.22.0', '0.22.1', released), false); + assert.equal(floorRaisesPastMinor('0.23.0', '0.22.0', released), false); + assert.equal(floorRaisesPastMinor('0.22.0', '0.22.0', released), false); + }); + + it('passes a correction from a never-published floor to the version it already meant in practice', () => { + assert.equal(floorRaisesPastMinor('0.22.1', '0.23.0', released), false); + assert.equal(floorRaisesPastMinor('0.21.4', '0.22.0', released), false); + }); + + it('passes when no released version sits between the floors', () => { + assert.equal(floorRaisesPastMinor('0.22.0', '0.23.0', new Set(['0.23.0'])), false); + }); +}); + +describe('announcesFloorRaise', () => { + it('accepts a breaking or release minor and a release major', () => { + assert.equal(announcesFloorRaise('minor', '**Breaking:** drops old runners.'), true); + assert.equal(announcesFloorRaise('minor', '**Release:** the runner API.'), true); + assert.equal(announcesFloorRaise('major', '**Release:** the runner API.'), true); + }); + + it('rejects a patch, a plain minor, and a breaking major', () => { + assert.equal(announcesFloorRaise('patch', '**Breaking:** drops old runners.'), false); + assert.equal(announcesFloorRaise('minor', 'Raises the floor.'), false); + assert.equal(announcesFloorRaise('major', '**Breaking:** drops old runners.'), false); + }); +}); + +describe('floorRaiseProblems', () => { + const released = new Set(['0.22.0', '0.23.0']); + const input = (changes: FloorRaiseInput['changes'], extra: Partial = {}): FloorRaiseInput => ({ + name: '@e2e-dev/web', + path: 'packages/web/package.json', + peer: 'e2e', + previousFloor: '0.22.0', + currentFloor: '0.23.0', + released, + changes, + alreadyFlagged: false, + ...extra, + }); + + it('fails a floor-raising changeset with a patch bump', () => { + const problems = floorRaiseProblems([input([{ type: 'patch', summary: 'Fixes a thing.' }])]); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /e2e peer floor rises 0\.22\.0 -> 0\.23\.0/); + assert.match(problems[0]!, /make it a minor whose summary opens \*\*Breaking:\*\*/); + }); + + it('names the highest bump when several changesets touch the package', () => { + const problems = floorRaiseProblems([ + input([ + { type: 'patch', summary: 'Fixes a thing.' }, + { type: 'patch', summary: 'Fixes another thing.' }, + ]), + ]); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /with only a patch bump/); + }); + + it('fails a floor raise with no changeset at all', () => { + const problems = floorRaiseProblems([input([])]); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /with no changeset for @e2e-dev\/web/); + }); + + it('passes a floor raise carried by a **Breaking:** minor', () => { + assert.deepEqual(floorRaiseProblems([input([{ type: 'minor', summary: '**Breaking:** needs e2e 0.23.0.' }])]), []); + }); + + it('passes a floor raise carried by a **Release:** minor', () => { + assert.deepEqual(floorRaiseProblems([input([{ type: 'minor', summary: '**Release:** the runner API.' }])]), []); + }); + + it('passes a correction from a never-published floor on a patch bump', () => { + assert.deepEqual( + floorRaiseProblems([input([{ type: 'patch', summary: 'Names the released floor.' }], { previousFloor: '0.22.1' })]), + [], + ); + }); + + it('leaves an unannounced minor to disallowedBumps instead of reporting it twice', () => { + assert.deepEqual( + floorRaiseProblems([input([{ type: 'minor', summary: 'Raises the floor.' }], { alreadyFlagged: true })]), + [], + ); + }); +}); + +describe('pendingBumps and nextVersionAfterBump', () => { + it('takes the highest bump per package', () => { + const bumps = pendingBumps([ + parseChangesetFile('---\n"e2e": patch\n---\n\nA fix.\n'), + parseChangesetFile('---\n"e2e": minor\n"@e2e-dev/web": patch\n---\n\n**Breaking:** a break.\n'), + ]); + assert.equal(bumps.get('e2e'), 'minor'); + assert.equal(bumps.get('@e2e-dev/web'), 'patch'); + }); + + it('bumps versions the way changesets does', () => { + assert.equal(nextVersionAfterBump('0.23.0', 'patch'), '0.23.1'); + assert.equal(nextVersionAfterBump('0.23.0', 'minor'), '0.24.0'); + assert.equal(nextVersionAfterBump('0.23.0', 'major'), '1.0.0'); + assert.equal(nextVersionAfterBump('not semver', 'patch'), undefined); + assert.deepEqual(parseVersion('0.23.0'), [0, 23, 0]); + assert.equal(parseVersion('0.23.0-canary-x'), undefined); + }); +}); diff --git a/scripts/changeset-bumps.ts b/scripts/changeset-bumps.ts index 2d2fa960c4..533ab14818 100644 --- a/scripts/changeset-bumps.ts +++ b/scripts/changeset-bumps.ts @@ -9,6 +9,19 @@ * change or a release a maintainer calls, its summary opening with * `**Breaking:**` or `**Release:**`. A `major` makes it `1.0.0`, outside every * sibling's `>=x <1` peer range, so only a `**Release:**` may carry one. + * + * Rule (a) of #1657 sits here too: a changeset that raises a package's peer + * floor on a sibling past a runner minor the previous range accepted must + * be a `**Breaking:**` minor. The check script pairs each pending changeset + * with the floor change it ships: the previous floor is the one at the + * package's release tag, the current floor is the working tree's, and a + * raise counts only when it cuts off a *released* version on an older + * minor. A correction from a never-published floor to the version it + * already meant in practice (for example `>=0.22.1` to `>=0.23.0`, where + * the previous range accepted only released `0.23.0`) cuts off nothing a + * consumer could install, so a patch carries it. The rule lives in this + * check, not in `check-peer-ranges.ts`, because only this check reads the + * changesets that must announce the raise. */ import { parseChangesetFile } from '@changesets/parse'; @@ -25,3 +38,118 @@ export function disallowedBumps(changeset: Changeset, versions: ReadonlyMap=previousFloor` in its + * major) sits below the new floor on an older minor. A raise within one + * minor, a lowering, and a correction from a never-published floor to the + * version it already meant in practice all answer false. + */ +export function floorRaisesPastMinor(previousFloor: string, currentFloor: string, released: ReadonlySet): boolean { + const previous = parseVersion(previousFloor); + const current = parseVersion(currentFloor); + if (previous === undefined || current === undefined) return false; + if (compareVersions(current, previous) <= 0) return false; + for (const version of released) { + const candidate = parseVersion(version); + if (candidate === undefined || candidate[0] !== previous[0]) continue; + if (compareVersions(candidate, previous) < 0 || compareVersions(candidate, current) >= 0) continue; + if (candidate[0] !== current[0] || candidate[1] < current[1]) return true; + } + return false; +} + +/** Whether a changeset entry of `type` with `summary` announces a floor raise: a minor opening `**Breaking:**` or `**Release:**`, or a major opening `**Release:**`. */ +export function announcesFloorRaise(type: BumpType, summary: string): boolean { + if (type === 'minor') return summary.startsWith(BREAKING) || summary.startsWith(RELEASE); + if (type === 'major') return summary.startsWith(RELEASE); + return false; +} + +const BUMP_RANK: Record = { patch: 0, minor: 1, major: 2 }; + +/** The highest bump each package gets across `changesets`; a release type that bumps nothing is skipped. */ +export function pendingBumps(changesets: readonly Changeset[]): Map { + const bumps = new Map(); + for (const changeset of changesets) { + for (const { name, type } of changeset.releases) { + if (!(type in BUMP_RANK)) continue; + const bump = type as BumpType; + const current = bumps.get(name); + if (current === undefined || BUMP_RANK[bump] > BUMP_RANK[current]) bumps.set(name, bump); + } + } + return bumps; +} + +/** The version a `type` bump of `version` releases; undefined when `version` is not `x.y.z`. */ +export function nextVersionAfterBump(version: string, type: BumpType): string | undefined { + const parsed = parseVersion(version); + if (parsed === undefined) return undefined; + const [major, minor, patch] = parsed; + if (type === 'patch') return `${major}.${minor}.${patch + 1}`; + if (type === 'minor') return `${major}.${minor + 1}.0`; + return `${major + 1}.0.0`; +} + +export interface FloorRaiseInput { + readonly name: string; + readonly path: string; + readonly peer: string; + readonly previousFloor: string; + readonly currentFloor: string; + readonly released: ReadonlySet; + readonly changes: readonly { type: BumpType; summary: string }[]; + readonly alreadyFlagged: boolean; +} + +/** + * Every floor raise in `inputs` that no pending changeset announces as a + * `**Breaking:**` minor. A package whose bump `disallowedBumps` already + * flags is skipped: the same summary fix (opening it with `**Breaking:**`) + * cures both, so it is reported once, there. + */ +export function floorRaiseProblems(inputs: readonly FloorRaiseInput[]): string[] { + const problems: string[] = []; + for (const input of inputs) { + if (!floorRaisesPastMinor(input.previousFloor, input.currentFloor, input.released)) continue; + if (input.changes.some((change) => announcesFloorRaise(change.type, change.summary))) continue; + if (input.alreadyFlagged) continue; + const highest = input.changes.reduce( + (top, change) => (top === undefined || BUMP_RANK[change.type] > BUMP_RANK[top] ? change.type : top), + undefined, + ); + const fix = + highest === undefined + ? `with no changeset for ${input.name}; add a minor changeset whose summary opens ${BREAKING}` + : `with only a ${highest} bump; make it a minor whose summary opens ${BREAKING}`; + problems.push( + `${input.path}: ${input.peer} peer floor rises ${input.previousFloor} -> ${input.currentFloor}, past a runner minor the previous range accepted, ${fix}`, + ); + } + return problems; +} diff --git a/scripts/check-changeset-bumps.ts b/scripts/check-changeset-bumps.ts index 037084c486..06d3c37151 100644 --- a/scripts/check-changeset-bumps.ts +++ b/scripts/check-changeset-bumps.ts @@ -1,32 +1,116 @@ /** * Fails when a pending changeset bumps a `0.x` package by `minor` without a * summary opening `**Breaking:**` or `**Release:**`, or by `major` without - * `**Release:**` (`changeset-bumps.ts` says why). + * `**Release:**` (`changeset-bumps.ts` says why), or when a changeset + * raises a package's peer floor on a sibling past a runner minor the + * previous range accepted without a `**Breaking:**` minor + * (`floorRaiseProblems` in `changeset-bumps.ts` says how a raise is judged: + * the previous floor is the one at the package's release tag, and only a + * released version on an older minor counts). * * Usage: `node scripts/check-changeset-bumps.ts`, part of `pnpm check`. Exits * 1 listing every offending changeset. */ +import { execFileSync } from 'node:child_process'; import { readFileSync, readdirSync } from 'node:fs'; -import { join } from 'node:path'; +import { dirname, join, relative } from 'node:path'; import { parseChangesetFile } from '@changesets/parse'; -import { BREAKING, RELEASE, disallowedBumps } from './changeset-bumps.ts'; -import { REPO_ROOT, publicPackages } from './public-packages.ts'; +import { BREAKING, RELEASE, disallowedBumps, floorRaiseProblems, type FloorRaiseInput } from './changeset-bumps.ts'; +import { peerFloor, releasedVersions } from './peer-ranges.ts'; +import { REPO_ROOT, isWidePeerRange, publicPackages, siblingPeers, type PackageManifest } from './public-packages.ts'; + +/** Reads `path` at `tag` (`git show`), undefined when the tag or the file does not exist. */ +function showAtTag(tag: string, path: string): string | undefined { + try { + return execFileSync('git', ['show', `${tag}:${path}`], { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); + } catch { + return undefined; + } +} const versions = new Map(publicPackages().flatMap(({ manifest }) => (manifest.version === undefined ? [] : [[manifest.name, manifest.version] as const]))); const dir = join(REPO_ROOT, '.changeset'); const files = readdirSync(dir).filter((file) => file.endsWith('.md') && file !== 'README.md'); +const changesets = files.map((file) => parseChangesetFile(readFileSync(join(dir, file), 'utf8'))); const problems: string[] = []; -for (const file of files.toSorted()) { - for (const { name, type } of disallowedBumps(parseChangesetFile(readFileSync(join(dir, file), 'utf8')), versions)) { +const flagged = new Set(); +for (const [index, changeset] of changesets.entries()) { + const file = files[index]; + if (file === undefined) continue; + for (const { name, type } of disallowedBumps(changeset, versions)) { + flagged.add(name); const needs = type === 'major' ? RELEASE : `${BREAKING} or ${RELEASE}`; problems.push(`.changeset/${file}: ${type} bump of ${name} ${versions.get(name)}; on 0.x a feature or fix is a patch, and a ${type} needs a summary opening with ${needs}`); } } +const changesByPackage = new Map(); +for (const changeset of changesets) { + for (const { name, type } of changeset.releases) { + if (type !== 'patch' && type !== 'minor' && type !== 'major') continue; + const list = changesByPackage.get(name) ?? []; + list.push({ type, summary: changeset.summary }); + changesByPackage.set(name, list); + } +} + +const packages = publicPackages(); +const byName = new Map(packages.map((pkg) => [pkg.manifest.name, pkg])); +const siblings = new Set(packages.map(({ manifest }) => manifest.name)); +const inputs: FloorRaiseInput[] = []; +let skipped = 0; +for (const { path, manifest } of packages) { + if (manifest.version === undefined) continue; + const tagManifest = showAtTag(`${manifest.name}@${manifest.version}`, relative(REPO_ROOT, path)); + if (tagManifest === undefined) { + skipped += 1; + continue; + } + let previous: Partial; + try { + previous = JSON.parse(tagManifest) as Partial; + } catch { + skipped += 1; + continue; + } + for (const [peer, range] of siblingPeers(manifest.peerDependencies, siblings)) { + if (!isWidePeerRange(range)) continue; + const currentFloor = peerFloor(range); + const previousRange = previous.peerDependencies?.[peer]; + const previousFloor = previousRange === undefined ? undefined : peerFloor(previousRange); + if (currentFloor === undefined || previousFloor === undefined || currentFloor === previousFloor) continue; + const sibling = byName.get(peer); + if (sibling === undefined) continue; + let changelog: string | undefined; + try { + changelog = readFileSync(join(dirname(sibling.path), 'CHANGELOG.md'), 'utf8'); + } catch { + changelog = undefined; + } + if (changelog === undefined) { + skipped += 1; + continue; + } + inputs.push({ + name: manifest.name, + path: relative(REPO_ROOT, path), + peer, + previousFloor, + currentFloor, + released: releasedVersions(changelog), + changes: changesByPackage.get(manifest.name) ?? [], + alreadyFlagged: flagged.has(manifest.name), + }); + } +} +problems.push(...floorRaiseProblems(inputs)); + if (problems.length > 0) { process.stderr.write(`${problems.join('\n')}\n`); process.exitCode = 1; } else { - process.stdout.write(`changeset bumps: ${files.length} pending, none an unannounced 0.x minor or major\n`); + process.stdout.write( + `changeset bumps: ${files.length} pending, none an unannounced 0.x minor or major; ${inputs.length} peer floor ${inputs.length === 1 ? 'change' : 'changes'} checked against their releases, none raised past an accepted minor without a **Breaking:** minor${skipped > 0 ? ` (${skipped} skipped: no release tag or changelog)` : ''}\n`, + ); } diff --git a/scripts/check-peer-ranges.ts b/scripts/check-peer-ranges.ts index dc573ebee9..c927f907b1 100644 --- a/scripts/check-peer-ranges.ts +++ b/scripts/check-peer-ranges.ts @@ -1,7 +1,11 @@ /** * Fails when a public package's peer on another public package (an engine's * on `e2e`, an integration's on an engine) is anything but - * `>= `. + * `>= `, or names a version the sibling never + * released (no `## ` in its CHANGELOG.md, and no pending changeset + * releasing it), or imports an `e2e/*` export the floor version does not + * have (#1657 rule (c): a new `e2e/engine` import counts as raising the + * floor). * * `changeset version --snapshot canary` rewrites those peers to the siblings' * exact canary versions, and the canary output is committed to main as @@ -9,33 +13,129 @@ * dependent and rewrite the pin on each release of the sibling, and leaves a * consumer who updates the sibling alone with a peer npm 7+ refuses * (ERESOLVE). `restore-peer-ranges.ts` puts the ranges back after a publish; - * this check is what notices when it did not run. + * this check is what notices when it did not run. `peer-ranges.ts` says why + * the floor must also be a released version; `engine-exports.ts` says how + * the floor version's exports are read (the `e2e@` tag). * * Usage: `node scripts/check-peer-ranges.ts`, part of `pnpm check`. Exits 1 * listing every offending peer. */ -import { relative } from 'node:path'; -import { REPO_ROOT, isWidePeerRange, publicPackages, siblingPeers } from './public-packages.ts'; +import { execFileSync } from 'node:child_process'; +import { readdirSync, readFileSync, statSync } from 'node:fs'; +import { dirname, join, relative } from 'node:path'; +import { parseChangesetFile } from '@changesets/parse'; +import { nextVersionAfterBump, pendingBumps } from './changeset-bumps.ts'; +import { engineImportProblems, engineImports, tagExportsAt, type EngineImportCheck } from './engine-exports.ts'; +import { peerFloor, peerRangeProblems } from './peer-ranges.ts'; +import { REPO_ROOT, publicPackages, siblingPeers } from './public-packages.ts'; + +/** Reads `path` at `tag` (`git show`), undefined when the tag or the file does not exist. */ +function showAtTag(tag: string, path: string): string | undefined { + try { + return execFileSync('git', ['show', `${tag}:${path}`], { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); + } catch { + return undefined; + } +} + +/** The TypeScript files under `dirPath`, recursively; unreadable entries are skipped. */ +function sourceFiles(dirPath: string): string[] { + const out: string[] = []; + const walk = (current: string): void => { + let entries: string[]; + try { + entries = readdirSync(current); + } catch { + return; + } + for (const entry of entries) { + const full = join(current, entry); + try { + if (statSync(full).isDirectory()) walk(full); + else if (full.endsWith('.ts')) out.push(full); + } catch { + continue; + } + } + }; + walk(dirPath); + return out; +} const packages = publicPackages(); const siblings = new Set(packages.map(({ manifest }) => manifest.name)); -const problems: string[] = []; const checked: string[] = []; -for (const { path, manifest } of packages) { +for (const { manifest } of packages) { for (const [peer, range] of siblingPeers(manifest.peerDependencies, siblings)) { checked.push(`${manifest.name} on ${peer} (${range})`); - if (!isWidePeerRange(range)) { - problems.push( - `${relative(REPO_ROOT, path)}: ${peer} peer is ${JSON.stringify(range)}, expected >= ; run \`node scripts/restore-peer-ranges.ts\``, - ); + } +} + +// The version each sibling's pending changesets will release: a floor may +// name it as the runner version in the same release. +const dir = join(REPO_ROOT, '.changeset'); +const changesetFiles = readdirSync(dir).filter((file) => file.endsWith('.md') && file !== 'README.md'); +const changesets = changesetFiles.map((file) => parseChangesetFile(readFileSync(join(dir, file), 'utf8'))); +const versions = new Map(packages.map(({ manifest }) => [manifest.name, manifest.version])); +const nextVersions = new Map(); +for (const [name, bump] of pendingBumps(changesets)) { + const version = versions.get(name); + if (version === undefined) continue; + const next = nextVersionAfterBump(version, bump); + if (next !== undefined) nextVersions.set(name, next); +} + +const problems = peerRangeProblems(packages, (packagePath) => { + try { + return readFileSync(join(dirname(packagePath), 'CHANGELOG.md'), 'utf8'); + } catch { + return undefined; + } +}, nextVersions); + +// Rule (c): every named import from `e2e/*` must be exported by `e2e` at +// the package's peer floor, read off the `e2e@` tag. +const siblingDirs = new Map(packages.map(({ manifest, path }) => [manifest.name, relative(REPO_ROOT, dirname(path))])); +const exportsCache = new Map | undefined>(); +const exportsAt = (sibling: string, subpath: string, version: string): ReadonlySet | undefined => { + const key = `${sibling}@${version}:${subpath}`; + if (exportsCache.has(key)) return exportsCache.get(key); + const siblingDir = siblingDirs.get(sibling); + const resolved = siblingDir === undefined ? undefined : tagExportsAt(showAtTag, `${sibling}@${version}`, siblingDir, subpath); + exportsCache.set(key, resolved); + return resolved; +}; + +const checks: EngineImportCheck[] = []; +for (const { path, manifest } of packages) { + const range = manifest.peerDependencies?.['e2e']; + if (range === undefined) continue; + const floor = peerFloor(range); + if (floor === undefined) continue; + const imports = new Map>(); + for (const file of sourceFiles(join(dirname(path), 'src'))) { + for (const [subpath, names] of engineImports(readFileSync(file, 'utf8'))) { + let set = imports.get(subpath); + if (set === undefined) { + set = new Set(); + imports.set(subpath, set); + } + for (const name of names) set.add(name); } } + if (imports.size === 0) continue; + checks.push({ packageName: manifest.name, packagePath: relative(REPO_ROOT, path), sibling: 'e2e', floor, imports }); } +const { problems: importProblems, unverifiable } = engineImportProblems(checks, exportsAt); +problems.push(...importProblems); if (problems.length > 0) { process.stderr.write(`${problems.join('\n')}\n`); process.exitCode = 1; } else { - process.stdout.write(`peer ranges: ${checked.toSorted().join(', ')} as wide ranges\n`); + process.stdout.write(`peer ranges: ${checked.toSorted().join(', ')} as wide ranges on released versions; ${checks.length} packages' e2e imports verified against their floors\n`); +} +for (const note of unverifiable) { + process.stdout.write(`note: ${note}\n`); } diff --git a/scripts/engine-exports.test.ts b/scripts/engine-exports.test.ts new file mode 100644 index 0000000000..28495d0487 --- /dev/null +++ b/scripts/engine-exports.test.ts @@ -0,0 +1,163 @@ +import assert from 'node:assert/strict'; +import { execFileSync } from 'node:child_process'; +import { readFileSync, readdirSync, statSync } from 'node:fs'; +import { dirname, join, relative } from 'node:path'; +import { describe, it } from 'node:test'; +import { engineImportProblems, engineImports, resolveEntryExports, resolveModule, subpathEntryFile, tagExportsAt, type EngineImportCheck } from './engine-exports.ts'; +import { peerFloor } from './peer-ranges.ts'; +import { REPO_ROOT, publicPackages } from './public-packages.ts'; + +/** Reads `path` at `tag` (`git show`), undefined when the tag or the file does not exist. */ +function showAtTag(tag: string, path: string): string | undefined { + try { + return execFileSync('git', ['show', `${tag}:${path}`], { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); + } catch { + return undefined; + } +} + +/** The TypeScript files under `dirPath`, recursively. */ +function sourceFiles(dirPath: string): string[] { + const out: string[] = []; + const walk = (current: string): void => { + for (const entry of readdirSync(current)) { + const full = join(current, entry); + if (statSync(full).isDirectory()) walk(full); + else if (full.endsWith('.ts')) out.push(full); + } + }; + walk(dirPath); + return out; +} + +describe('engineImports', () => { + it('reads named, aliased, and type-only imports from e2e entries', () => { + const imports = engineImports( + `import { stepTimeout, EngineError as EngineErr, type EngineDoctorCheck } from 'e2e/engine';\nimport type { StepExecutor } from 'e2e';\nimport { test as base } from 'e2e';\n`, + ); + assert.deepEqual(imports.get('engine'), new Set(['stepTimeout', 'EngineError', 'EngineDoctorCheck'])); + assert.deepEqual(imports.get(''), new Set(['StepExecutor', 'test'])); + }); + + it('records a namespace import as unverifiable, not as names', () => { + const imports = engineImports(`import * as engine from 'e2e/engine';\n`); + assert.deepEqual(imports.get('engine'), new Set(['*'])); + }); + + it('ignores imports from other packages', () => { + assert.equal(engineImports(`import { z } from 'zod';\n`).size, 0); + }); +}); + +describe('exportedNames and resolveEntryExports', () => { + it('reads named exports, aliases, declarations, and export-star chains', () => { + const files = new Map([ + [ + 'src/engine/index.ts', + `export { stepTimeout } from './timing.ts';\nexport { EngineError as EngineErr } from './errors.ts';\nexport type * from './contract.ts';\nexport interface Local { x: string }\n`, + ], + ['src/engine/timing.ts', `export function stepTimeout(): void {}\n`], + ['src/engine/errors.ts', `export class EngineError extends Error {}\n`], + ['src/engine/contract.ts', `export type NodeRef = string;\nexport * from './kinds.ts';\n`], + ['src/engine/kinds.ts', `export type Kind = 'a';\n`], + ]); + const exported = resolveEntryExports((path) => files.get(path), 'src/engine/index.ts'); + assert.deepEqual([...(exported ?? [])].toSorted(), ['EngineErr', 'Kind', 'Local', 'NodeRef', 'stepTimeout']); + }); + + it('answers undefined when an entry file cannot be read', () => { + assert.equal(resolveEntryExports(() => undefined, 'src/engine/index.ts'), undefined); + }); + + it('resolves relative module specifiers', () => { + assert.equal(resolveModule('packages/e2e/src/engine/index.ts', '../internal/time.ts'), 'packages/e2e/src/internal/time.ts'); + assert.equal(resolveModule('packages/e2e/src/engine/index.ts', './contract.ts'), 'packages/e2e/src/engine/contract.ts'); + assert.equal(resolveModule('packages/e2e/src/engine/index.ts', 'zod'), undefined); + }); + + it('reads the entry file off a sibling package.json', () => { + const packageJson = JSON.stringify({ exports: { './engine': { types: './dist/engine/index.d.ts', default: './dist/engine/index.js' } } }); + assert.equal(subpathEntryFile(packageJson, 'packages/e2e', 'engine'), 'packages/e2e/src/engine/index.ts'); + assert.equal(subpathEntryFile('not json', 'packages/e2e', 'engine'), undefined); + assert.equal(subpathEntryFile(packageJson, 'packages/e2e', 'missing'), undefined); + }); +}); + +describe('engineImportProblems', () => { + const check = (floor: string, imports: Map>): EngineImportCheck => ({ + packageName: '@e2e-dev/web', + packagePath: 'packages/web/package.json', + sibling: 'e2e', + floor, + imports, + }); + + it('fails an import the floor version does not export', () => { + const exported = new Set(['EngineError']); + const { problems } = engineImportProblems([check('0.22.0', new Map([['engine', new Set(['stepTimeout', 'EngineError'])]]))], () => exported); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /imports `stepTimeout` from e2e\/engine, but e2e@0\.22\.0 does not export it/); + }); + + it('passes when the floor version exports every import', () => { + const exported = new Set(['stepTimeout', 'EngineError']); + const { problems, unverifiable } = engineImportProblems([check('0.23.0', new Map([['engine', new Set(['stepTimeout'])]]))], () => exported); + assert.deepEqual(problems, []); + assert.deepEqual(unverifiable, []); + }); + + it('reports a floor with no tag record as unverifiable, not a problem', () => { + const { problems, unverifiable } = engineImportProblems([check('0.15.0', new Map([['engine', new Set(['EngineError'])]]))], () => undefined); + assert.deepEqual(problems, []); + assert.equal(unverifiable.length, 1); + assert.match(unverifiable[0]!, /cannot be verified, no tag record/); + }); + + it('reports a namespace import as unverifiable', () => { + const { problems, unverifiable } = engineImportProblems([check('0.23.0', new Map([['engine', new Set(['*'])]]))], () => new Set()); + assert.deepEqual(problems, []); + assert.equal(unverifiable.length, 1); + assert.match(unverifiable[0]!, /imported as a namespace/); + }); +}); + +describe('imports at their floors on this repo', () => { + it('has every e2e import exported at the package floor version (#1657)', () => { + const checks: EngineImportCheck[] = []; + for (const { path, manifest } of publicPackages()) { + const range = manifest.peerDependencies?.['e2e']; + if (range === undefined) continue; + const floor = peerFloor(range); + if (floor === undefined) continue; + const imports = new Map>(); + for (const file of sourceFiles(join(dirname(path), 'src'))) { + for (const [subpath, names] of engineImports(readFileSync(file, 'utf8'))) { + let set = imports.get(subpath); + if (set === undefined) { + set = new Set(); + imports.set(subpath, set); + } + for (const name of names) set.add(name); + } + } + if (imports.size === 0) continue; + checks.push({ packageName: manifest.name, packagePath: relative(REPO_ROOT, path), sibling: 'e2e', floor, imports }); + } + const siblingDirs = new Map(publicPackages().map(({ manifest, path }) => [manifest.name, relative(REPO_ROOT, dirname(path))])); + const { problems } = engineImportProblems(checks, (sibling, subpath, version) => { + const siblingDir = siblingDirs.get(sibling); + if (siblingDir === undefined) return undefined; + return tagExportsAt(showAtTag, `${sibling}@${version}`, siblingDir, subpath); + }); + assert.deepEqual(problems, []); + }); + + it('catches the original bug: web imports stepTimeout, which e2e@0.22.0 does not export', () => { + const exported = tagExportsAt(showAtTag, 'e2e@0.22.0', 'packages/e2e', 'engine'); + assert.equal(exported?.has('stepTimeout'), false); + assert.equal(exported?.has('EngineDoctorCheck'), false); + const atNext = tagExportsAt(showAtTag, 'e2e@0.23.0', 'packages/e2e', 'engine'); + assert.equal(atNext?.has('stepTimeout'), true); + assert.equal(atNext?.has('EngineDoctorCheck'), true); + }); +}); diff --git a/scripts/engine-exports.ts b/scripts/engine-exports.ts new file mode 100644 index 0000000000..8dc7a13b6e --- /dev/null +++ b/scripts/engine-exports.ts @@ -0,0 +1,208 @@ +/** + * Rule (c) of #1657: an engine that starts importing a new `e2e/engine` + * export counts as raising the floor. This module verifies it: for each + * package, every named import it takes from `e2e` or an `e2e/*` entry must + * be exported by `e2e` at the version the package's peer floor names. + * + * The export set at a version comes from the tag record, + * `e2e@`: the entry file is read off the sibling's `package.json` + * `exports` at that tag (its `types` target, mapped from `dist/` to + * `src/`), and `export *` chains are followed. The tag record is the only + * source that names the version's exports exactly: the CHANGELOG records + * releases but not exports, and the published tarball would put the + * network in `pnpm check`. A floor whose tag does not exist (for example + * `e2e@0.15.0`, released before a tag was cut per version) cannot be + * verified this way; that floor is reported as unverifiable, not as a + * failure, and the released-floor rule in `peer-ranges.ts` still applies + * to it. Type-only imports count the same as value imports: the package's + * published `.d.ts` names those types, so a consumer on the floor runner + * fails typecheck when the floor version lacks them. + * + * Only imports from `e2e` itself are checked. An integration's imports + * from another engine (`@e2e-dev/web`, `@e2e-dev/mobile`) are the same + * shape but a different sibling, and the maintainer's rule names + * `e2e/engine`; extending this to engine peers is a follow-up, not part + * of this change. + */ + +export type EngineImportMap = ReadonlyMap>; + +const IMPORT_FROM = /import\s+(?:type\s+)?(?:\w+\s*,\s*)?\{([^}]*)\}\s+from\s+['"]e2e(\/[^'"]*)?['"]/gs; +const REEXPORT_FROM = /export\s+(?:type\s+)?\{([^}]*)\}\s+from\s+['"]e2e(\/[^'"]*)?['"]/gs; +const NAMESPACE_FROM = /import\s+(?:type\s+)?\*\s+as\s+\w+\s+from\s+['"]e2e(\/[^'"]*)?['"]/g; + +/** The named imports from `e2e` and its subpaths in one source file, keyed by subpath (`''` is the bare `e2e` entry). A namespace import is recorded as the name `'*'`, which the check cannot enumerate. */ +export function engineImports(source: string): EngineImportMap { + const found = new Map>(); + const add = (subpath: string, names: readonly string[]): void => { + let set = found.get(subpath); + if (set === undefined) { + set = new Set(); + found.set(subpath, set); + } + for (const name of names) set.add(name); + }; + const splitNames = (list: string): string[] => + list + .split(',') + .map((part) => part.trim().replace(/^type\s+/, '')) + .filter((part) => part.length > 0) + .map((part) => part.split(/\s+as\s+/)[0]?.trim() ?? '') + .filter((part) => part.length > 0); + for (const pattern of [IMPORT_FROM, REEXPORT_FROM]) { + for (const match of source.matchAll(pattern)) { + const list = match[1]; + const subpath = (match[2] ?? '').replace(/^\//, ''); + if (list === undefined) continue; + add(subpath, splitNames(list)); + } + } + for (const match of source.matchAll(NAMESPACE_FROM)) { + add((match[1] ?? '').replace(/^\//, ''), ['*']); + } + return found; +} + +/** The names one file exports, and the relative modules its `export *` pulls in. */ +function exportedNames(source: string): { names: ReadonlySet; starModules: readonly string[] } { + const names = new Set(); + const starModules: string[] = []; + for (const match of source.matchAll(/export\s+(?:type\s+)?\{([^}]*)\}\s*(?:from\s+['"]([^'"]+)['"])?/gs)) { + const list = match[1]; + if (list === undefined) continue; + for (const part of list.split(',')) { + const trimmed = part.trim().replace(/^type\s+/, ''); + if (trimmed.length === 0) continue; + const nameMatch = /(\w+)(?:\s+as\s+(\w+))?/.exec(trimmed); + if (nameMatch === null) continue; + names.add(nameMatch[2] ?? nameMatch[1] ?? ''); + } + } + for (const match of source.matchAll(/export\s+(?:type\s+)?\*\s*(?:as\s+\w+\s*)?from\s+['"]([^'"]+)['"]/g)) { + if (match[1] !== undefined) starModules.push(match[1]); + } + for (const match of source.matchAll(/export\s+(?:declare\s+)?(?:interface|type|class|function|const|let|var|enum|abstract\s+class)\s+(\w+)/g)) { + if (match[1] !== undefined) names.add(match[1]); + } + return { names, starModules }; +} + +/** Resolves a relative module specifier against the file that imports it; undefined for a bare specifier. */ +export function resolveModule(fromFile: string, specifier: string): string | undefined { + if (!specifier.startsWith('.')) return undefined; + const parts = fromFile.split('/').slice(0, -1); + for (const segment of specifier.split('/')) { + if (segment === '.' || segment === '') continue; + if (segment === '..') parts.pop(); + else parts.push(segment); + } + return parts.join('/'); +} + +/** + * The export set of the entry file, following `export *` chains. + * `readFile` reads a repo path (undefined when it has none); the caller + * binds it to a version, for example `git show :`. + */ +export function resolveEntryExports(readFile: (path: string) => string | undefined, entryPath: string): ReadonlySet | undefined { + const exported = new Set(); + const seen = new Set(); + const queue = [entryPath]; + while (queue.length > 0) { + const file = queue.pop(); + if (file === undefined || seen.has(file)) continue; + seen.add(file); + const source = readFile(file); + if (source === undefined) return undefined; + const { names, starModules } = exportedNames(source); + for (const name of names) exported.add(name); + for (const specifier of starModules) { + const target = resolveModule(file, specifier); + if (target !== undefined) queue.push(target); + } + } + return exported; +} + +/** + * The source file for a sibling's subpath entry, from the sibling's + * `package.json` (`exports` `types` target, mapped from `dist/` to + * `src/`). `subpath` is `''` for the bare entry. Undefined when the + * package has no such export, or its manifest does not parse. + */ +export function subpathEntryFile(packageJson: string, siblingDir: string, subpath: string): string | undefined { + let parsed: { exports?: Record }; + try { + parsed = JSON.parse(packageJson) as { exports?: Record }; + } catch { + return undefined; + } + const entry = parsed.exports?.[subpath === '' ? '.' : `./${subpath}`]; + const types = typeof entry === 'string' ? entry : entry?.types; + if (typeof types !== 'string') return undefined; + return `${siblingDir}/src/${types.replace(/^\.\/dist\//, '').replace(/\.d\.ts$/, '.ts')}`; +} + +/** + * The export set of a sibling's subpath at a version, read through + * `showFile(tag, path)`. Undefined when the tag, the manifest, or the + * entry cannot be read. + */ +export function tagExportsAt( + showFile: (tag: string, path: string) => string | undefined, + tag: string, + siblingDir: string, + subpath: string, +): ReadonlySet | undefined { + const manifest = showFile(tag, `${siblingDir}/package.json`); + if (manifest === undefined) return undefined; + const entry = subpathEntryFile(manifest, siblingDir, subpath); + if (entry === undefined) return undefined; + return resolveEntryExports((path) => showFile(tag, path), entry); +} + +export interface EngineImportCheck { + readonly packageName: string; + readonly packagePath: string; + readonly sibling: string; + readonly floor: string; + readonly imports: EngineImportMap; +} + +/** + * Every import in `checks` the sibling does not export at the floor + * version, plus the floors that could not be verified. `exportsAt` + * returns the sibling's export set for a subpath at a version, or + * undefined when that version has no tag record to read; an unverifiable + * floor is a note, not a problem, since the released-floor rule still + * applies to it. A namespace import is unverifiable for the same reason: + * its names cannot be enumerated. + */ +export function engineImportProblems( + checks: readonly EngineImportCheck[], + exportsAt: (sibling: string, subpath: string, version: string) => ReadonlySet | undefined, +): { problems: string[]; unverifiable: string[] } { + const problems: string[] = []; + const unverifiable: string[] = []; + for (const check of checks) { + for (const [subpath, names] of check.imports) { + const label = subpath === '' ? check.sibling : `${check.sibling}/${subpath}`; + if (names.has('*')) { + unverifiable.push(`${check.packagePath}: ${label} is imported as a namespace, so its names cannot be verified against ${check.sibling}@${check.floor}`); + continue; + } + const exported = exportsAt(check.sibling, subpath, check.floor); + if (exported === undefined) { + unverifiable.push(`${check.packagePath}: ${label} at ${check.sibling}@${check.floor} cannot be verified, no tag record for that version; the floor must still name a released version`); + continue; + } + const missing = [...names].filter((name) => !exported.has(name)).toSorted(); + if (missing.length > 0) { + problems.push( + `${check.packagePath}: imports ${missing.map((name) => `\`${name}\``).join(', ')} from ${label}, but ${check.sibling}@${check.floor} does not export ${missing.length === 1 ? 'it' : 'them'}; a new ${label} import counts as raising the floor, so raise the ${check.sibling} peer floor to the first version that exports ${missing.length === 1 ? 'it' : 'them'} (as a **Breaking:** minor when it passes a runner minor the previous range accepted)`, + ); + } + } + } + return { problems, unverifiable }; +} diff --git a/scripts/peer-ranges.test.ts b/scripts/peer-ranges.test.ts new file mode 100644 index 0000000000..f23125da16 --- /dev/null +++ b/scripts/peer-ranges.test.ts @@ -0,0 +1,103 @@ +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { dirname, join } from 'node:path'; +import { describe, it } from 'node:test'; +import { publicPackages } from './public-packages.ts'; +import { peerFloor, peerRangeProblems, releasedVersions, type PublicPackage } from './peer-ranges.ts'; + +function pkg(name: string, peers: Record): PublicPackage { + return { path: `/repo/packages/${name}/package.json`, manifest: { name, version: '0.1.0', peerDependencies: peers } }; +} + +describe('peerFloor', () => { + it('reads the floor of a wide range', () => { + assert.equal(peerFloor('>=0.15.0 <1'), '0.15.0'); + assert.equal(peerFloor('>=1.2.3 <2'), '1.2.3'); + }); + + it('answers undefined for any other shape', () => { + assert.equal(peerFloor('^0.15.0'), undefined); + assert.equal(peerFloor('0.15.0'), undefined); + assert.equal(peerFloor('>=0.15.0'), undefined); + }); +}); + +describe('releasedVersions', () => { + it('reads released versions from changelog headings only', () => { + const versions = releasedVersions('# Changelog\n\n## 0.23.0\n\n- a fix\n\n## 0.22.0\n\nSee ## 0.21.0 in the text, not a heading.\n'); + assert.deepEqual([...versions].toSorted(), ['0.22.0', '0.23.0']); + }); + + it('answers an empty set for a changelog with no releases', () => { + assert.equal(releasedVersions('# Changelog\n').size, 0); + }); +}); + +describe('peerRangeProblems', () => { + const changelog = '## 0.15.0\n\n## 0.18.0\n'; + const read = () => changelog; + + it('passes a wide range on a released floor', () => { + const packages = [pkg('e2e', {}), pkg('@e2e-dev/web', { e2e: '>=0.18.0 <1' })]; + assert.deepEqual(peerRangeProblems(packages, read), []); + }); + + it('fails a wide range on a floor the sibling never released', () => { + const packages = [pkg('e2e', {}), pkg('@e2e-dev/web', { e2e: '>=0.22.1 <1' })]; + const problems = peerRangeProblems(packages, read); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /floor is 0\.22\.1, which e2e never released/); + }); + + it('passes a floor that is the sibling version a pending changeset releases', () => { + const packages = [pkg('e2e', {}), pkg('@e2e-dev/web', { e2e: '>=0.19.0 <1' })]; + assert.deepEqual(peerRangeProblems(packages, read, new Map([['e2e', '0.19.0']])), []); + }); + + it('still fails a floor past the sibling version a pending changeset releases', () => { + const packages = [pkg('e2e', {}), pkg('@e2e-dev/web', { e2e: '>=0.20.0 <1' })]; + const problems = peerRangeProblems(packages, read, new Map([['e2e', '0.19.0']])); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /floor is 0\.20\.0, which e2e never released/); + }); + + it('fails a range that is not a wide range', () => { + const packages = [pkg('e2e', {}), pkg('@e2e-dev/web', { e2e: '^0.18.0' })]; + const problems = peerRangeProblems(packages, read); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /expected >= /); + }); + + it('fails when the sibling has no changelog to show the floor released', () => { + const packages = [pkg('e2e', {}), pkg('@e2e-dev/web', { e2e: '>=0.18.0 <1' })]; + const problems = peerRangeProblems(packages, () => undefined); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /has no CHANGELOG\.md/); + }); + + it('ignores peers that are not siblings', () => { + const packages = [pkg('@e2e-dev/web', { e2e: '>=9.9.9 <1', zod: '^3.0.0' })]; + assert.deepEqual(peerRangeProblems(packages, read), []); + }); +}); + +describe('released floors on this repo', () => { + it('has no sibling peer floor naming a version that never shipped (#1657)', () => { + const problems = peerRangeProblems(publicPackages(), (packagePath) => { + try { + return readFileSync(join(dirname(packagePath), 'CHANGELOG.md'), 'utf8'); + } catch { + return undefined; + } + }); + assert.deepEqual(problems, []); + }); + + it('keeps the #1657 floors at the oldest released sibling each package works with', () => { + const byName = new Map(publicPackages().map(({ manifest }) => [manifest.name, manifest.peerDependencies ?? {}])); + assert.equal(byName.get('@e2e-dev/mobile')?.['e2e'], '>=0.23.0 <1'); + assert.equal(byName.get('@e2e-dev/web')?.['e2e'], '>=0.23.0 <1'); + assert.equal(byName.get('@e2e-dev/acp')?.['e2e'], '>=0.22.0 <1'); + assert.equal(byName.get('@e2e-dev/limrun')?.['@e2e-dev/mobile'], '>=0.11.0 <1'); + }); +}); diff --git a/scripts/peer-ranges.ts b/scripts/peer-ranges.ts new file mode 100644 index 0000000000..ed71ccafe1 --- /dev/null +++ b/scripts/peer-ranges.ts @@ -0,0 +1,88 @@ +/** + * The peer-range policy for one public package's peer on another public + * package (an engine's on `e2e`, an integration's on an engine). + * + * Two rules. First, the shape: `>= `, the floor + * the oldest sibling the package works with. Anything narrower puts every + * sibling minor out of range, and changesets then patch-bumps the dependent + * and rewrites its pin on every release of the sibling; an exact pin also + * leaves a consumer who updates the sibling alone with a peer npm 7+ + * refuses. Second, the floor must name a version the sibling actually + * released, read off its CHANGELOG.md (`## x.y.z` headings), or the version + * the sibling's pending changesets will release alongside it (the runner + * version in the same release). A floor past the latest stable names a + * version no install can satisfy: #1657 raised both engines to `>=0.22.1` + * in a patch release, but no stable `e2e@0.22.1` ever shipped (only + * nightlies), so a fresh `npm install` of an unchanged project on + * `e2e ~0.21.3` failed with ERESOLVE. The same shape hid in `@e2e-dev/acp` + * (`>=0.21.4`, never released) and `@e2e-dev/limrun` + * (`@e2e-dev/mobile >=0.11.1`, never released). A floor may rise only once + * its version is in the changelog (or is the sibling's pending release); + * until then the package either works without the new export, on the old + * floor, or waits for the release. + */ + +import { relative } from 'node:path'; +import { REPO_ROOT, isWidePeerRange, type PackageManifest } from './public-packages.ts'; + +export interface PublicPackage { + readonly path: string; + readonly manifest: PackageManifest; +} + +/** The floor of a wide peer range: `0.15.0` of `>=0.15.0 <1`; undefined for any other shape. */ +export function peerFloor(range: string): string | undefined { + const match = /^>=(\d+\.\d+\.\d+) <\d+$/.exec(range); + return match === null ? undefined : match[1]; +} + +/** The versions a changelog records as released, from its `## x.y.z` headings. */ +export function releasedVersions(changelog: string): ReadonlySet { + const versions: string[] = []; + for (const match of changelog.matchAll(/^## (\d+\.\d+\.\d+)\s*$/gm)) { + if (match[1] !== undefined) versions.push(match[1]); + } + return new Set(versions); +} + +/** + * Every sibling peer range in `packages` that breaks the policy, one + * human-readable problem per offending peer. `readChangelog` reads the + * sibling's CHANGELOG.md for a package path (undefined when it has none); + * the check script passes the real read, tests pass a fake. `nextVersions` + * maps a sibling to the version its pending changesets will release, which + * a floor may name as the runner version in the same release. + */ +export function peerRangeProblems( + packages: readonly PublicPackage[], + readChangelog: (packagePath: string) => string | undefined, + nextVersions: ReadonlyMap = new Map(), +): string[] { + const siblings = new Map(packages.map((pkg) => [pkg.manifest.name, pkg])); + const problems: string[] = []; + for (const { path, manifest } of packages) { + for (const [peer, range] of Object.entries(manifest.peerDependencies ?? {}).filter(([name]) => siblings.has(name))) { + const display = relative(REPO_ROOT, path); + if (!isWidePeerRange(range)) { + problems.push( + `${display}: ${peer} peer is ${JSON.stringify(range)}, expected >= ; run \`node scripts/restore-peer-ranges.ts\``, + ); + continue; + } + const floor = peerFloor(range); + const sibling = siblings.get(peer); + if (floor === undefined || sibling === undefined) continue; + const changelog = readChangelog(sibling.path); + if (changelog === undefined) { + problems.push( + `${display}: ${peer} peer floor is ${floor}, but ${peer} has no CHANGELOG.md to show it released; a floor must name a released stable version`, + ); + } else if (!releasedVersions(changelog).has(floor) && nextVersions.get(peer) !== floor) { + problems.push( + `${display}: ${peer} peer floor is ${floor}, which ${peer} never released (no ## ${floor} in its CHANGELOG.md) and no pending changeset releases; a floor must name a released stable version, or the runner version in the same release, so a patch release cannot raise it past the latest stable. Raise it only after that version ships, or keep the old floor when the package works without the new export`, + ); + } + } + } + return problems; +} From 6dd35f1998103cb63e41bc164af8c3e004cff08c Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Tue, 10 Nov 2026 07:19:24 +0000 Subject: [PATCH 02/14] fix(release): address cubic review findings on the peer-floor checks The test job now checks out with fetch-depth: 0: the new regression test reads the e2e@0.22.0 and e2e@0.23.0 tags, and the shallow checkout failed it on all five test jobs (spec run 42763725083). check-changeset-bumps falls back to the latest released tag when the current version has no tag yet, so a generated release PR still gets its floor check. check-peer-ranges verifies a pending-release floor against the working tree instead of passing it on an unverifiable note. engine-exports tracks value and type imports separately: export type * no longer satisfies a value import (isKeyModifier), and named imports beside a namespace import are still validated. peer-ranges checks the pending version before reporting a missing changelog. A floor raise now needs a **Breaking:** minor: a **Release:** minor no longer announces it. AGENTS.md and the check scripts say the sibling's version in the same release, and that the import check covers named imports. Signed-off-by: Varshith Puli --- .github/workflows/spec.yml | 5 + AGENTS.md | 8 +- scripts/changeset-bumps.test.ts | 28 ++++- scripts/changeset-bumps.ts | 16 ++- scripts/check-changeset-bumps.ts | 29 ++++- scripts/check-peer-ranges.ts | 43 ++++--- scripts/engine-exports.test.ts | 124 ++++++++++++++++---- scripts/engine-exports.ts | 188 ++++++++++++++++++++++--------- scripts/peer-ranges.test.ts | 12 ++ scripts/peer-ranges.ts | 16 +-- 10 files changed, 355 insertions(+), 114 deletions(-) diff --git a/.github/workflows/spec.yml b/.github/workflows/spec.yml index ebda7af760..d8f9962e79 100644 --- a/.github/workflows/spec.yml +++ b/.github/workflows/spec.yml @@ -103,6 +103,11 @@ jobs: node: [22, 24, 26, 22.22.3, 24.8.0] steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + # The script tests read release tags (scripts/engine-exports.test.ts + # verifies imports against e2e@0.22.0 and e2e@0.23.0), so the + # checkout needs the full history and tags, not a shallow fetch. + fetch-depth: 0 - uses: pnpm/action-setup@9fd676a19091d4595eefd76e4bd31c97133911f1 # v4.2.0 - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: diff --git a/AGENTS.md b/AGENTS.md index bd968f6c86..6f2479cf06 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -720,11 +720,13 @@ trees, on both platforms, without a device. `scripts/check-peer-ranges.ts` (`pnpm check`) fails on any other shape for every peer one package under `packages/` has on another (vendor SDK peers such as `@onkernel/sdk` are not checked). The floor must name a version the - sibling released, or the runner version in the same release, and a raise + sibling released, or the sibling's version in the same release, and a raise past a runner minor the previous range accepted needs a `**Breaking:**` minor changeset (`scripts/check-changeset-bumps.ts`); a new `e2e/engine` - import counts as a raise, so the check also fails any `e2e/*` import the - floor version does not export, read off the `e2e@` tag. Narrow or exact, every runner minor (exact: every patch too) + import counts as a raise, so the check also fails any named `e2e/*` import the + floor version does not export, read off the `e2e@` tag (a namespace + import is reported as an unverifiable note instead, since its names cannot + be enumerated). Narrow or exact, every runner minor (exact: every patch too) falls out of range, and changesets 3 then patch-bumps each engine and rewrites its pin, never a major (`determineDependents` in `@changesets/assemble-release-plan` patches an out-of-range peer dependent). diff --git a/scripts/changeset-bumps.test.ts b/scripts/changeset-bumps.test.ts index e9ac0309dc..d0d74af933 100644 --- a/scripts/changeset-bumps.test.ts +++ b/scripts/changeset-bumps.test.ts @@ -6,6 +6,7 @@ import { disallowedBumps, floorRaiseProblems, floorRaisesPastMinor, + latestReleaseVersion, nextVersionAfterBump, parseVersion, pendingBumps, @@ -71,9 +72,9 @@ describe('floorRaisesPastMinor', () => { }); describe('announcesFloorRaise', () => { - it('accepts a breaking or release minor and a release major', () => { + it('accepts a breaking minor and a release major, but not a release minor', () => { assert.equal(announcesFloorRaise('minor', '**Breaking:** drops old runners.'), true); - assert.equal(announcesFloorRaise('minor', '**Release:** the runner API.'), true); + assert.equal(announcesFloorRaise('minor', '**Release:** the runner API.'), false); assert.equal(announcesFloorRaise('major', '**Release:** the runner API.'), true); }); @@ -126,8 +127,10 @@ describe('floorRaiseProblems', () => { assert.deepEqual(floorRaiseProblems([input([{ type: 'minor', summary: '**Breaking:** needs e2e 0.23.0.' }])]), []); }); - it('passes a floor raise carried by a **Release:** minor', () => { - assert.deepEqual(floorRaiseProblems([input([{ type: 'minor', summary: '**Release:** the runner API.' }])]), []); + it('fails a floor raise carried only by a **Release:** minor', () => { + const problems = floorRaiseProblems([input([{ type: 'minor', summary: '**Release:** the runner API.' }])]); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /make it a minor whose summary opens \*\*Breaking:\*\*/); }); it('passes a correction from a never-published floor on a patch bump', () => { @@ -145,8 +148,21 @@ describe('floorRaiseProblems', () => { }); }); -describe('pendingBumps and nextVersionAfterBump', () => { - it('takes the highest bump per package', () => { +describe('latestReleaseVersion', () => { + const tags = ['e2e@0.22.0', 'e2e@0.23.0', 'e2e@0.21.3', '@e2e-dev/web@0.15.5', 'e2e@0.23.0-nightly-1']; + + it('picks the highest released tag for the package', () => { + assert.equal(latestReleaseVersion(tags, 'e2e'), '0.23.0'); + assert.equal(latestReleaseVersion(tags, '@e2e-dev/web'), '0.15.5'); + }); + + it('answers undefined when the package has no released tag', () => { + assert.equal(latestReleaseVersion(tags, '@e2e-dev/e2b'), undefined); + assert.equal(latestReleaseVersion([], 'e2e'), undefined); + }); +}); + +describe('pendingBumps and nextVersionAfterBump', () => { it('takes the highest bump per package', () => { const bumps = pendingBumps([ parseChangesetFile('---\n"e2e": patch\n---\n\nA fix.\n'), parseChangesetFile('---\n"e2e": minor\n"@e2e-dev/web": patch\n---\n\n**Breaking:** a break.\n'), diff --git a/scripts/changeset-bumps.ts b/scripts/changeset-bumps.ts index 533ab14818..0d74f9d403 100644 --- a/scripts/changeset-bumps.ts +++ b/scripts/changeset-bumps.ts @@ -83,13 +83,25 @@ export function floorRaisesPastMinor(previousFloor: string, currentFloor: string return false; } -/** Whether a changeset entry of `type` with `summary` announces a floor raise: a minor opening `**Breaking:**` or `**Release:**`, or a major opening `**Release:**`. */ +/** Whether a changeset entry of `type` with `summary` announces a floor raise: a minor opening `**Breaking:**`, or a major opening `**Release:**`. A `**Release:**` minor does not announce one: the maintainer's rule for #1657 is that a floor raise past an accepted runner minor must be a `**Breaking:**` minor, and a release train is not that signal. A major needs no breaking prefix because the major itself is the signal: no `0.x` consumer picks it up without opting in. */ export function announcesFloorRaise(type: BumpType, summary: string): boolean { - if (type === 'minor') return summary.startsWith(BREAKING) || summary.startsWith(RELEASE); + if (type === 'minor') return summary.startsWith(BREAKING); if (type === 'major') return summary.startsWith(RELEASE); return false; } +/** The latest released version of `name` among `tags` (`@`), undefined when none exists. The bump check falls back to it when the tag for a package's current version does not exist yet, which is exactly a generated release PR: `version-packages` has already bumped the version, so the current tag is missing and the previous released manifest is the one to compare the floor against. */ +export function latestReleaseVersion(tags: readonly string[], name: string): string | undefined { + let latest: Semver | undefined; + for (const tag of tags) { + if (!tag.startsWith(`${name}@`)) continue; + const version = parseVersion(tag.slice(name.length + 1)); + if (version === undefined) continue; + if (latest === undefined || compareVersions(version, latest) > 0) latest = version; + } + return latest === undefined ? undefined : latest.join('.'); +} + const BUMP_RANK: Record = { patch: 0, minor: 1, major: 2 }; /** The highest bump each package gets across `changesets`; a release type that bumps nothing is skipped. */ diff --git a/scripts/check-changeset-bumps.ts b/scripts/check-changeset-bumps.ts index 06d3c37151..6258ff0ce6 100644 --- a/scripts/check-changeset-bumps.ts +++ b/scripts/check-changeset-bumps.ts @@ -5,8 +5,9 @@ * raises a package's peer floor on a sibling past a runner minor the * previous range accepted without a `**Breaking:**` minor * (`floorRaiseProblems` in `changeset-bumps.ts` says how a raise is judged: - * the previous floor is the one at the package's release tag, and only a - * released version on an older minor counts). + * the previous floor is the one at the package's release tag, or, on a + * generated release PR whose bumped version has no tag yet, at its latest + * released tag; only a released version on an older minor counts). * * Usage: `node scripts/check-changeset-bumps.ts`, part of `pnpm check`. Exits * 1 listing every offending changeset. @@ -16,7 +17,7 @@ import { execFileSync } from 'node:child_process'; import { readFileSync, readdirSync } from 'node:fs'; import { dirname, join, relative } from 'node:path'; import { parseChangesetFile } from '@changesets/parse'; -import { BREAKING, RELEASE, disallowedBumps, floorRaiseProblems, type FloorRaiseInput } from './changeset-bumps.ts'; +import { BREAKING, RELEASE, disallowedBumps, floorRaiseProblems, latestReleaseVersion, type FloorRaiseInput } from './changeset-bumps.ts'; import { peerFloor, releasedVersions } from './peer-ranges.ts'; import { REPO_ROOT, isWidePeerRange, publicPackages, siblingPeers, type PackageManifest } from './public-packages.ts'; @@ -29,6 +30,25 @@ function showAtTag(tag: string, path: string): string | undefined { } } +/** The manifest at the package's latest released tag, undefined when it has no release tag. A generated release PR has already bumped the version, so the tag for the current version does not exist yet; the previous released manifest is the one to compare the floor against, instead of skipping the check. */ +function previousReleaseManifest(name: string, packagePath: string): string | undefined { + let tags: string; + try { + tags = execFileSync('git', ['tag', '--list', `${name}@*`], { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); + } catch { + return undefined; + } + const latest = latestReleaseVersion( + tags + .split('\n') + .map((tag) => tag.trim()) + .filter((tag) => tag.length > 0), + name, + ); + if (latest === undefined) return undefined; + return showAtTag(`${name}@${latest}`, packagePath); +} + const versions = new Map(publicPackages().flatMap(({ manifest }) => (manifest.version === undefined ? [] : [[manifest.name, manifest.version] as const]))); const dir = join(REPO_ROOT, '.changeset'); const files = readdirSync(dir).filter((file) => file.endsWith('.md') && file !== 'README.md'); @@ -62,7 +82,8 @@ const inputs: FloorRaiseInput[] = []; let skipped = 0; for (const { path, manifest } of packages) { if (manifest.version === undefined) continue; - const tagManifest = showAtTag(`${manifest.name}@${manifest.version}`, relative(REPO_ROOT, path)); + let tagManifest = showAtTag(`${manifest.name}@${manifest.version}`, relative(REPO_ROOT, path)); + if (tagManifest === undefined) tagManifest = previousReleaseManifest(manifest.name, relative(REPO_ROOT, path)); if (tagManifest === undefined) { skipped += 1; continue; diff --git a/scripts/check-peer-ranges.ts b/scripts/check-peer-ranges.ts index c927f907b1..b7e2896614 100644 --- a/scripts/check-peer-ranges.ts +++ b/scripts/check-peer-ranges.ts @@ -7,6 +7,11 @@ * have (#1657 rule (c): a new `e2e/engine` import counts as raising the * floor). * + * A floor naming the version the sibling's pending changesets will release + * has no tag yet, so its imports are verified against the working tree, + * which is that pending release's source, instead of passing on an + * unverifiable note. + * * `changeset version --snapshot canary` rewrites those peers to the siblings' * exact canary versions, and the canary output is committed to main as * `chore: release`. An exact pin that lands makes changesets patch-bump the @@ -26,7 +31,7 @@ import { readdirSync, readFileSync, statSync } from 'node:fs'; import { dirname, join, relative } from 'node:path'; import { parseChangesetFile } from '@changesets/parse'; import { nextVersionAfterBump, pendingBumps } from './changeset-bumps.ts'; -import { engineImportProblems, engineImports, tagExportsAt, type EngineImportCheck } from './engine-exports.ts'; +import { addEngineImports, engineImportProblems, engineImports, tagExportsAt, type EngineImportCheck, type ExportSets, type ImportKind } from './engine-exports.ts'; import { peerFloor, peerRangeProblems } from './peer-ranges.ts'; import { REPO_ROOT, publicPackages, siblingPeers } from './public-packages.ts'; @@ -73,7 +78,7 @@ for (const { manifest } of packages) { } // The version each sibling's pending changesets will release: a floor may -// name it as the runner version in the same release. +// name it as the sibling's version in the same release. const dir = join(REPO_ROOT, '.changeset'); const changesetFiles = readdirSync(dir).filter((file) => file.endsWith('.md') && file !== 'README.md'); const changesets = changesetFiles.map((file) => parseChangesetFile(readFileSync(join(dir, file), 'utf8'))); @@ -97,12 +102,29 @@ const problems = peerRangeProblems(packages, (packagePath) => { // Rule (c): every named import from `e2e/*` must be exported by `e2e` at // the package's peer floor, read off the `e2e@` tag. const siblingDirs = new Map(packages.map(({ manifest, path }) => [manifest.name, relative(REPO_ROOT, dirname(path))])); -const exportsCache = new Map | undefined>(); -const exportsAt = (sibling: string, subpath: string, version: string): ReadonlySet | undefined => { +const exportsCache = new Map(); + +/** Reads `path` from the working tree, undefined when it cannot be read. */ +function showWorkingTree(_tag: string, path: string): string | undefined { + try { + return readFileSync(join(REPO_ROOT, path), 'utf8'); + } catch { + return undefined; + } +} + +const exportsAt = (sibling: string, subpath: string, version: string): ExportSets | undefined => { const key = `${sibling}@${version}:${subpath}`; if (exportsCache.has(key)) return exportsCache.get(key); const siblingDir = siblingDirs.get(sibling); - const resolved = siblingDir === undefined ? undefined : tagExportsAt(showAtTag, `${sibling}@${version}`, siblingDir, subpath); + let resolved = siblingDir === undefined ? undefined : tagExportsAt(showAtTag, `${sibling}@${version}`, siblingDir, subpath); + if (resolved === undefined && siblingDir !== undefined && nextVersions.get(sibling) === version) { + // A floor naming the version the sibling's pending changesets will + // release has no tag yet, so the tag lookup cannot verify it; the + // working tree is that pending release's source, so verify against it + // instead of passing the floor on an unverifiable note. + resolved = tagExportsAt(showWorkingTree, `${sibling}@${version}`, siblingDir, subpath); + } exportsCache.set(key, resolved); return resolved; }; @@ -113,16 +135,9 @@ for (const { path, manifest } of packages) { if (range === undefined) continue; const floor = peerFloor(range); if (floor === undefined) continue; - const imports = new Map>(); + const imports = new Map>(); for (const file of sourceFiles(join(dirname(path), 'src'))) { - for (const [subpath, names] of engineImports(readFileSync(file, 'utf8'))) { - let set = imports.get(subpath); - if (set === undefined) { - set = new Set(); - imports.set(subpath, set); - } - for (const name of names) set.add(name); - } + addEngineImports(imports, engineImports(readFileSync(file, 'utf8'))); } if (imports.size === 0) continue; checks.push({ packageName: manifest.name, packagePath: relative(REPO_ROOT, path), sibling: 'e2e', floor, imports }); diff --git a/scripts/engine-exports.test.ts b/scripts/engine-exports.test.ts index 28495d0487..ca8c2c39ba 100644 --- a/scripts/engine-exports.test.ts +++ b/scripts/engine-exports.test.ts @@ -3,7 +3,7 @@ import { execFileSync } from 'node:child_process'; import { readFileSync, readdirSync, statSync } from 'node:fs'; import { dirname, join, relative } from 'node:path'; import { describe, it } from 'node:test'; -import { engineImportProblems, engineImports, resolveEntryExports, resolveModule, subpathEntryFile, tagExportsAt, type EngineImportCheck } from './engine-exports.ts'; +import { addEngineImports, engineImportProblems, engineImports, resolveEntryExports, resolveModule, subpathEntryFile, tagExportsAt, type EngineImportCheck, type EngineImportMap, type ImportKind } from './engine-exports.ts'; import { peerFloor } from './peer-ranges.ts'; import { REPO_ROOT, publicPackages } from './public-packages.ts'; @@ -35,13 +35,31 @@ describe('engineImports', () => { const imports = engineImports( `import { stepTimeout, EngineError as EngineErr, type EngineDoctorCheck } from 'e2e/engine';\nimport type { StepExecutor } from 'e2e';\nimport { test as base } from 'e2e';\n`, ); - assert.deepEqual(imports.get('engine'), new Set(['stepTimeout', 'EngineError', 'EngineDoctorCheck'])); - assert.deepEqual(imports.get(''), new Set(['StepExecutor', 'test'])); + assert.deepEqual( + imports.get('engine'), + new Map([ + ['stepTimeout', 'value'], + ['EngineError', 'value'], + ['EngineDoctorCheck', 'type'], + ]), + ); + assert.deepEqual( + imports.get(''), + new Map([ + ['StepExecutor', 'type'], + ['test', 'value'], + ]), + ); }); it('records a namespace import as unverifiable, not as names', () => { const imports = engineImports(`import * as engine from 'e2e/engine';\n`); - assert.deepEqual(imports.get('engine'), new Set(['*'])); + assert.deepEqual(imports.get('engine'), new Map([['*', 'value']])); + }); + + it('records a value import of a name over a type import of the same name', () => { + const imports = engineImports(`import { type EngineError } from 'e2e/engine';\nimport { EngineError } from 'e2e/engine';\n`); + assert.equal(imports.get('engine')?.get('EngineError'), 'value'); }); it('ignores imports from other packages', () => { @@ -62,7 +80,21 @@ describe('exportedNames and resolveEntryExports', () => { ['src/engine/kinds.ts', `export type Kind = 'a';\n`], ]); const exported = resolveEntryExports((path) => files.get(path), 'src/engine/index.ts'); - assert.deepEqual([...(exported ?? [])].toSorted(), ['EngineErr', 'Kind', 'Local', 'NodeRef', 'stepTimeout']); + assert.deepEqual([...(exported?.values ?? [])].toSorted(), ['EngineErr', 'stepTimeout']); + assert.deepEqual([...(exported?.types ?? [])].toSorted(), ['Kind', 'Local', 'NodeRef']); + }); + + it('does not count a type-star re-export as a value export', () => { + const files = new Map([ + ['src/engine/index.ts', `export type * from './contract.ts';\nexport { parseKey } from './contract.ts';\n`], + [ + 'src/engine/contract.ts', + `export function isKeyModifier(value: unknown): boolean { return false; }\nexport function parseKey(value: string): string { return value; }\nexport type KeyModifier = 'Shift';\nexport const KEY_MODIFIERS = ['Shift'] as const;\n`, + ], + ]); + const exported = resolveEntryExports((path) => files.get(path), 'src/engine/index.ts'); + assert.deepEqual([...(exported?.values ?? [])].toSorted(), ['parseKey']); + assert.deepEqual([...(exported?.types ?? [])].toSorted(), ['KeyModifier']); }); it('answers undefined when an entry file cannot be read', () => { @@ -84,41 +116,79 @@ describe('exportedNames and resolveEntryExports', () => { }); describe('engineImportProblems', () => { - const check = (floor: string, imports: Map>): EngineImportCheck => ({ + const check = (floor: string, imports: EngineImportMap): EngineImportCheck => ({ packageName: '@e2e-dev/web', packagePath: 'packages/web/package.json', sibling: 'e2e', floor, imports, }); + const exported = (values: readonly string[], types: readonly string[] = []) => ({ values: new Set(values), types: new Set(types) }); + const named = (entries: readonly (readonly [string, ImportKind])[]): EngineImportMap => + new Map([['engine', new Map(entries)]]); it('fails an import the floor version does not export', () => { - const exported = new Set(['EngineError']); - const { problems } = engineImportProblems([check('0.22.0', new Map([['engine', new Set(['stepTimeout', 'EngineError'])]]))], () => exported); + const { problems } = engineImportProblems( + [check('0.22.0', named([['stepTimeout', 'value'], ['EngineError', 'value']]))], + () => exported(['EngineError']), + ); assert.equal(problems.length, 1); assert.match(problems[0]!, /imports `stepTimeout` from e2e\/engine, but e2e@0\.22\.0 does not export it/); }); it('passes when the floor version exports every import', () => { - const exported = new Set(['stepTimeout', 'EngineError']); - const { problems, unverifiable } = engineImportProblems([check('0.23.0', new Map([['engine', new Set(['stepTimeout'])]]))], () => exported); + const { problems, unverifiable } = engineImportProblems( + [check('0.23.0', named([['stepTimeout', 'value']]))], + () => exported(['stepTimeout', 'EngineError']), + ); assert.deepEqual(problems, []); assert.deepEqual(unverifiable, []); }); + it('passes a type import satisfied by a type-only export', () => { + const { problems } = engineImportProblems( + [check('0.23.0', named([['KeyModifier', 'type']]))], + () => exported(['parseKey'], ['KeyModifier']), + ); + assert.deepEqual(problems, []); + }); + + it('fails a value import satisfied only by a type-only export', () => { + const { problems } = engineImportProblems( + [check('0.23.0', named([['isKeyModifier', 'value'], ['parseKey', 'value'], ['KeyModifier', 'type']]))], + () => exported(['parseKey'], ['KeyModifier']), + ); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /imports `isKeyModifier` from e2e\/engine/); + }); + it('reports a floor with no tag record as unverifiable, not a problem', () => { - const { problems, unverifiable } = engineImportProblems([check('0.15.0', new Map([['engine', new Set(['EngineError'])]]))], () => undefined); + const { problems, unverifiable } = engineImportProblems([check('0.15.0', named([['EngineError', 'value']]))], () => undefined); assert.deepEqual(problems, []); assert.equal(unverifiable.length, 1); assert.match(unverifiable[0]!, /cannot be verified, no tag record/); }); it('reports a namespace import as unverifiable', () => { - const { problems, unverifiable } = engineImportProblems([check('0.23.0', new Map([['engine', new Set(['*'])]]))], () => new Set()); + const { problems, unverifiable } = engineImportProblems( + [check('0.23.0', new Map([['engine', new Map([['*', 'value']])]]))], + () => exported([]), + ); assert.deepEqual(problems, []); assert.equal(unverifiable.length, 1); assert.match(unverifiable[0]!, /imported as a namespace/); }); + + it('still validates named imports beside a namespace import', () => { + const { problems, unverifiable } = engineImportProblems( + [check('0.23.0', new Map([['engine', new Map([['*', 'value'], ['stepTimeout', 'value']])]]))], + () => exported(['EngineError']), + ); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /imports `stepTimeout` from e2e\/engine/); + assert.equal(unverifiable.length, 1); + assert.match(unverifiable[0]!, /imported as a namespace/); + }); }); describe('imports at their floors on this repo', () => { @@ -129,16 +199,9 @@ describe('imports at their floors on this repo', () => { if (range === undefined) continue; const floor = peerFloor(range); if (floor === undefined) continue; - const imports = new Map>(); + const imports = new Map>(); for (const file of sourceFiles(join(dirname(path), 'src'))) { - for (const [subpath, names] of engineImports(readFileSync(file, 'utf8'))) { - let set = imports.get(subpath); - if (set === undefined) { - set = new Set(); - imports.set(subpath, set); - } - for (const name of names) set.add(name); - } + addEngineImports(imports, engineImports(readFileSync(file, 'utf8'))); } if (imports.size === 0) continue; checks.push({ packageName: manifest.name, packagePath: relative(REPO_ROOT, path), sibling: 'e2e', floor, imports }); @@ -154,10 +217,21 @@ describe('imports at their floors on this repo', () => { it('catches the original bug: web imports stepTimeout, which e2e@0.22.0 does not export', () => { const exported = tagExportsAt(showAtTag, 'e2e@0.22.0', 'packages/e2e', 'engine'); - assert.equal(exported?.has('stepTimeout'), false); - assert.equal(exported?.has('EngineDoctorCheck'), false); + assert.notEqual(exported, undefined, 'e2e@0.22.0 tag not fetched; the test job checks out with fetch-depth: 0'); + assert.equal(exported?.values.has('stepTimeout'), false); + assert.equal(exported?.types.has('EngineDoctorCheck'), false); + const atNext = tagExportsAt(showAtTag, 'e2e@0.23.0', 'packages/e2e', 'engine'); + assert.notEqual(atNext, undefined, 'e2e@0.23.0 tag not fetched; the test job checks out with fetch-depth: 0'); + assert.equal(atNext?.values.has('stepTimeout'), true); + assert.equal(atNext?.types.has('EngineDoctorCheck'), true); + }); + + it('does not count a type-star re-export as an e2e/engine value export', () => { const atNext = tagExportsAt(showAtTag, 'e2e@0.23.0', 'packages/e2e', 'engine'); - assert.equal(atNext?.has('stepTimeout'), true); - assert.equal(atNext?.has('EngineDoctorCheck'), true); + assert.notEqual(atNext, undefined, 'e2e@0.23.0 tag not fetched; the test job checks out with fetch-depth: 0'); + assert.equal(atNext?.values.has('isKeyModifier'), false); + assert.equal(atNext?.types.has('isKeyModifier'), false); + assert.equal(atNext?.values.has('parseKey'), true); + assert.equal(atNext?.types.has('KeyModifier'), true); }); }); diff --git a/scripts/engine-exports.ts b/scripts/engine-exports.ts index 8dc7a13b6e..46ec011ff0 100644 --- a/scripts/engine-exports.ts +++ b/scripts/engine-exports.ts @@ -16,7 +16,13 @@ * failure, and the released-floor rule in `peer-ranges.ts` still applies * to it. Type-only imports count the same as value imports: the package's * published `.d.ts` names those types, so a consumer on the floor runner - * fails typecheck when the floor version lacks them. + * fails typecheck when the floor version lacks them. The split runs the + * other way too: a value import needs a value export, so a name that only + * reaches the entry through `export type *` (for example `isKeyModifier` + * from `contract.ts`, which `e2e/engine` does not export as a value) does + * not satisfy a value import. Imports and exports are therefore tracked by + * kind: `value` or `type`. A type import is satisfied by a value or a type + * export; a value import only by a value export. * * Only imports from `e2e` itself are checked. An integration's imports * from another engine (`@e2e-dev/web`, `@e2e-dev/mobile`) are the same @@ -25,66 +31,116 @@ * of this change. */ -export type EngineImportMap = ReadonlyMap>; +/** Whether an import takes the name as a value or only as a type. A value import needs a value export; a type import is satisfied by either kind. */ +export type ImportKind = 'value' | 'type'; -const IMPORT_FROM = /import\s+(?:type\s+)?(?:\w+\s*,\s*)?\{([^}]*)\}\s+from\s+['"]e2e(\/[^'"]*)?['"]/gs; -const REEXPORT_FROM = /export\s+(?:type\s+)?\{([^}]*)\}\s+from\s+['"]e2e(\/[^'"]*)?['"]/gs; +/** The named imports from `e2e` and its subpaths in one source file, keyed by subpath (`''` is the bare `e2e` entry), each name with its kind. A value import of a name subsumes a type import of the same name. */ +export type EngineImportMap = ReadonlyMap>; + +const IMPORT_FROM = /import\s+(type\s+)?(?:\w+\s*,\s*)?\{([^}]*)\}\s+from\s+['"]e2e(\/[^'"]*)?['"]/gs; +const REEXPORT_FROM = /export\s+(type\s+)?\{([^}]*)\}\s+from\s+['"]e2e(\/[^'"]*)?['"]/gs; const NAMESPACE_FROM = /import\s+(?:type\s+)?\*\s+as\s+\w+\s+from\s+['"]e2e(\/[^'"]*)?['"]/g; /** The named imports from `e2e` and its subpaths in one source file, keyed by subpath (`''` is the bare `e2e` entry). A namespace import is recorded as the name `'*'`, which the check cannot enumerate. */ export function engineImports(source: string): EngineImportMap { - const found = new Map>(); - const add = (subpath: string, names: readonly string[]): void => { - let set = found.get(subpath); - if (set === undefined) { - set = new Set(); - found.set(subpath, set); + const found = new Map>(); + const add = (subpath: string, names: readonly (readonly [string, ImportKind])[]): void => { + let map = found.get(subpath); + if (map === undefined) { + map = new Map(); + found.set(subpath, map); + } + for (const [name, kind] of names) { + const existing = map.get(name); + if (existing === undefined || kind === 'value') map.set(name, kind); } - for (const name of names) set.add(name); }; - const splitNames = (list: string): string[] => + const splitNames = (list: string, wholeListType: boolean): [string, ImportKind][] => list .split(',') - .map((part) => part.trim().replace(/^type\s+/, '')) + .map((part) => part.trim()) .filter((part) => part.length > 0) - .map((part) => part.split(/\s+as\s+/)[0]?.trim() ?? '') - .filter((part) => part.length > 0); + .map((part): [string, ImportKind] => { + const typeOnly = wholeListType || part.startsWith('type '); + const name = part.replace(/^type\s+/, '').split(/\s+as\s+/)[0]?.trim() ?? ''; + return [name, typeOnly ? 'type' : 'value']; + }) + .filter(([name]) => name.length > 0); for (const pattern of [IMPORT_FROM, REEXPORT_FROM]) { for (const match of source.matchAll(pattern)) { - const list = match[1]; - const subpath = (match[2] ?? '').replace(/^\//, ''); + const list = match[2]; + const subpath = (match[3] ?? '').replace(/^\//, ''); if (list === undefined) continue; - add(subpath, splitNames(list)); + add(subpath, splitNames(list, match[1] !== undefined)); } } for (const match of source.matchAll(NAMESPACE_FROM)) { - add((match[1] ?? '').replace(/^\//, ''), ['*']); + add((match[1] ?? '').replace(/^\//, ''), [['*', 'value']]); } return found; } -/** The names one file exports, and the relative modules its `export *` pulls in. */ -function exportedNames(source: string): { names: ReadonlySet; starModules: readonly string[] } { - const names = new Set(); +/** Merges `source` into `target`, a value import of a name winning over a type import of the same name. */ +export function addEngineImports(target: Map>, source: EngineImportMap): void { + for (const [subpath, names] of source) { + let map = target.get(subpath); + if (map === undefined) { + map = new Map(); + target.set(subpath, map); + } + for (const [name, kind] of names) { + const existing = map.get(name); + if (existing === undefined || kind === 'value') map.set(name, kind); + } + } +} + +/** The names one file exports, split by kind, and the relative modules its `export *` pulls in. A `type` export or declaration lands in `types`; a class or enum lands in both, since its name is usable as a type; anything else value-like lands in `values`. `export type *` targets are kept apart from value `export *` targets: the former re-export types only. */ +function exportedNames(source: string): { + values: ReadonlySet; + types: ReadonlySet; + starModules: readonly string[]; + typeStarModules: readonly string[]; +} { + const values = new Set(); + const types = new Set(); const starModules: string[] = []; - for (const match of source.matchAll(/export\s+(?:type\s+)?\{([^}]*)\}\s*(?:from\s+['"]([^'"]+)['"])?/gs)) { - const list = match[1]; + const typeStarModules: string[] = []; + for (const match of source.matchAll(/export\s+(type\s+)?\{([^}]*)\}\s*(?:from\s+['"]([^'"]+)['"])?/gs)) { + const wholeListType = match[1] !== undefined; + const list = match[2]; if (list === undefined) continue; for (const part of list.split(',')) { - const trimmed = part.trim().replace(/^type\s+/, ''); + const trimmed = part.trim(); if (trimmed.length === 0) continue; - const nameMatch = /(\w+)(?:\s+as\s+(\w+))?/.exec(trimmed); + const typeOnly = wholeListType || trimmed.startsWith('type '); + const nameMatch = /(\w+)(?:\s+as\s+(\w+))?/.exec(trimmed.replace(/^type\s+/, '')); if (nameMatch === null) continue; - names.add(nameMatch[2] ?? nameMatch[1] ?? ''); + const name = nameMatch[2] ?? nameMatch[1] ?? ''; + if (name.length === 0) continue; + (typeOnly ? types : values).add(name); } } - for (const match of source.matchAll(/export\s+(?:type\s+)?\*\s*(?:as\s+\w+\s*)?from\s+['"]([^'"]+)['"]/g)) { - if (match[1] !== undefined) starModules.push(match[1]); + for (const match of source.matchAll(/export\s+(type\s+)?\*\s*(?:as\s+\w+\s*)?from\s+['"]([^'"]+)['"]/g)) { + if (match[2] !== undefined) (match[1] !== undefined ? typeStarModules : starModules).push(match[2]); } - for (const match of source.matchAll(/export\s+(?:declare\s+)?(?:interface|type|class|function|const|let|var|enum|abstract\s+class)\s+(\w+)/g)) { - if (match[1] !== undefined) names.add(match[1]); + for (const match of source.matchAll(/export\s+(?:declare\s+)?(interface|type|class|function|const|let|var|enum|abstract\s+class)\s+(\w+)/g)) { + const kind = match[1]; + const name = match[2]; + if (kind === undefined || name === undefined) continue; + if (kind === 'interface' || kind === 'type') types.add(name); + else if (kind === 'class' || kind === 'enum' || kind.startsWith('abstract')) { + values.add(name); + types.add(name); + } else values.add(name); } - return { names, starModules }; + return { values, types, starModules, typeStarModules }; +} + +/** The names an entry exports, split by kind. */ +export interface ExportSets { + readonly values: ReadonlySet; + readonly types: ReadonlySet; } /** Resolves a relative module specifier against the file that imports it; undefined for a bare specifier. */ @@ -100,28 +156,47 @@ export function resolveModule(fromFile: string, specifier: string): string | und } /** - * The export set of the entry file, following `export *` chains. + * The export set of the entry file, split by kind, following `export *` + * chains. A file reached through `export type *` contributes its types + * only: a function or const there has no type meaning to re-export. * `readFile` reads a repo path (undefined when it has none); the caller * binds it to a version, for example `git show :`. */ -export function resolveEntryExports(readFile: (path: string) => string | undefined, entryPath: string): ReadonlySet | undefined { - const exported = new Set(); +export function resolveEntryExports(readFile: (path: string) => string | undefined, entryPath: string): ExportSets | undefined { + const values = new Set(); + const types = new Set(); const seen = new Set(); - const queue = [entryPath]; + const queue: [string, boolean][] = [[entryPath, false]]; while (queue.length > 0) { - const file = queue.pop(); - if (file === undefined || seen.has(file)) continue; - seen.add(file); + const next = queue.pop(); + if (next === undefined) continue; + const [file, typeOnly] = next; + const key = `${file}:${typeOnly ? 'type' : 'value'}`; + if (seen.has(key)) continue; + seen.add(key); const source = readFile(file); if (source === undefined) return undefined; - const { names, starModules } = exportedNames(source); - for (const name of names) exported.add(name); - for (const specifier of starModules) { - const target = resolveModule(file, specifier); - if (target !== undefined) queue.push(target); + const exported = exportedNames(source); + if (typeOnly) { + for (const name of exported.types) types.add(name); + for (const specifier of [...exported.starModules, ...exported.typeStarModules]) { + const target = resolveModule(file, specifier); + if (target !== undefined) queue.push([target, true]); + } + } else { + for (const name of exported.values) values.add(name); + for (const name of exported.types) types.add(name); + for (const specifier of exported.starModules) { + const target = resolveModule(file, specifier); + if (target !== undefined) queue.push([target, false]); + } + for (const specifier of exported.typeStarModules) { + const target = resolveModule(file, specifier); + if (target !== undefined) queue.push([target, true]); + } } } - return exported; + return { values, types }; } /** @@ -144,16 +219,16 @@ export function subpathEntryFile(packageJson: string, siblingDir: string, subpat } /** - * The export set of a sibling's subpath at a version, read through - * `showFile(tag, path)`. Undefined when the tag, the manifest, or the - * entry cannot be read. + * The export set of a sibling's subpath at a version, split by kind, read + * through `showFile(tag, path)`. Undefined when the tag, the manifest, or + * the entry cannot be read. */ export function tagExportsAt( showFile: (tag: string, path: string) => string | undefined, tag: string, siblingDir: string, subpath: string, -): ReadonlySet | undefined { +): ExportSets | undefined { const manifest = showFile(tag, `${siblingDir}/package.json`); if (manifest === undefined) return undefined; const entry = subpathEntryFile(manifest, siblingDir, subpath); @@ -176,27 +251,34 @@ export interface EngineImportCheck { * undefined when that version has no tag record to read; an unverifiable * floor is a note, not a problem, since the released-floor rule still * applies to it. A namespace import is unverifiable for the same reason: - * its names cannot be enumerated. + * its names cannot be enumerated. A namespace import does not excuse the + * names imported beside it from the same subpath: those are still + * validated. A value import needs a value export; a type import is + * satisfied by a value or a type export. */ export function engineImportProblems( checks: readonly EngineImportCheck[], - exportsAt: (sibling: string, subpath: string, version: string) => ReadonlySet | undefined, + exportsAt: (sibling: string, subpath: string, version: string) => ExportSets | undefined, ): { problems: string[]; unverifiable: string[] } { const problems: string[] = []; const unverifiable: string[] = []; for (const check of checks) { for (const [subpath, names] of check.imports) { const label = subpath === '' ? check.sibling : `${check.sibling}/${subpath}`; + const named = [...names].filter(([name]) => name !== '*'); if (names.has('*')) { unverifiable.push(`${check.packagePath}: ${label} is imported as a namespace, so its names cannot be verified against ${check.sibling}@${check.floor}`); - continue; } + if (named.length === 0) continue; const exported = exportsAt(check.sibling, subpath, check.floor); if (exported === undefined) { unverifiable.push(`${check.packagePath}: ${label} at ${check.sibling}@${check.floor} cannot be verified, no tag record for that version; the floor must still name a released version`); continue; } - const missing = [...names].filter((name) => !exported.has(name)).toSorted(); + const missing = named + .filter(([name, kind]) => (kind === 'value' ? !exported.values.has(name) : !exported.values.has(name) && !exported.types.has(name))) + .map(([name]) => name) + .toSorted(); if (missing.length > 0) { problems.push( `${check.packagePath}: imports ${missing.map((name) => `\`${name}\``).join(', ')} from ${label}, but ${check.sibling}@${check.floor} does not export ${missing.length === 1 ? 'it' : 'them'}; a new ${label} import counts as raising the floor, so raise the ${check.sibling} peer floor to the first version that exports ${missing.length === 1 ? 'it' : 'them'} (as a **Breaking:** minor when it passes a runner minor the previous range accepted)`, diff --git a/scripts/peer-ranges.test.ts b/scripts/peer-ranges.test.ts index f23125da16..bc18ccfaf6 100644 --- a/scripts/peer-ranges.test.ts +++ b/scripts/peer-ranges.test.ts @@ -75,6 +75,18 @@ describe('peerRangeProblems', () => { assert.match(problems[0]!, /has no CHANGELOG\.md/); }); + it('passes a floor that is the pending version of a sibling with no changelog yet', () => { + const packages = [pkg('e2e', {}), pkg('@e2e-dev/web', { e2e: '>=0.1.0 <1' })]; + assert.deepEqual(peerRangeProblems(packages, () => undefined, new Map([['e2e', '0.1.0']])), []); + }); + + it('still fails a floor past the pending version of a sibling with no changelog', () => { + const packages = [pkg('e2e', {}), pkg('@e2e-dev/web', { e2e: '>=0.18.0 <1' })]; + const problems = peerRangeProblems(packages, () => undefined, new Map([['e2e', '0.2.0']])); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /has no CHANGELOG\.md/); + }); + it('ignores peers that are not siblings', () => { const packages = [pkg('@e2e-dev/web', { e2e: '>=9.9.9 <1', zod: '^3.0.0' })]; assert.deepEqual(peerRangeProblems(packages, read), []); diff --git a/scripts/peer-ranges.ts b/scripts/peer-ranges.ts index ed71ccafe1..67a3fb3818 100644 --- a/scripts/peer-ranges.ts +++ b/scripts/peer-ranges.ts @@ -9,8 +9,8 @@ * leaves a consumer who updates the sibling alone with a peer npm 7+ * refuses. Second, the floor must name a version the sibling actually * released, read off its CHANGELOG.md (`## x.y.z` headings), or the version - * the sibling's pending changesets will release alongside it (the runner - * version in the same release). A floor past the latest stable names a + * the sibling's pending changesets will release alongside it (the + * sibling's version in the same release). A floor past the latest stable names a * version no install can satisfy: #1657 raised both engines to `>=0.22.1` * in a patch release, but no stable `e2e@0.22.1` ever shipped (only * nightlies), so a fresh `npm install` of an unchanged project on @@ -51,7 +51,7 @@ export function releasedVersions(changelog: string): ReadonlySet { * sibling's CHANGELOG.md for a package path (undefined when it has none); * the check script passes the real read, tests pass a fake. `nextVersions` * maps a sibling to the version its pending changesets will release, which - * a floor may name as the runner version in the same release. + * a floor may name as the sibling's version in the same release. */ export function peerRangeProblems( packages: readonly PublicPackage[], @@ -74,12 +74,14 @@ export function peerRangeProblems( if (floor === undefined || sibling === undefined) continue; const changelog = readChangelog(sibling.path); if (changelog === undefined) { - problems.push( - `${display}: ${peer} peer floor is ${floor}, but ${peer} has no CHANGELOG.md to show it released; a floor must name a released stable version`, - ); + if (nextVersions.get(peer) !== floor) { + problems.push( + `${display}: ${peer} peer floor is ${floor}, but ${peer} has no CHANGELOG.md to show it released; a floor must name a released stable version`, + ); + } } else if (!releasedVersions(changelog).has(floor) && nextVersions.get(peer) !== floor) { problems.push( - `${display}: ${peer} peer floor is ${floor}, which ${peer} never released (no ## ${floor} in its CHANGELOG.md) and no pending changeset releases; a floor must name a released stable version, or the runner version in the same release, so a patch release cannot raise it past the latest stable. Raise it only after that version ships, or keep the old floor when the package works without the new export`, + `${display}: ${peer} peer floor is ${floor}, which ${peer} never released (no ## ${floor} in its CHANGELOG.md) and no pending changeset releases; a floor must name a released stable version, or the sibling's version in the same release, so a patch release cannot raise it past the latest stable. Raise it only after that version ships, or keep the old floor when the package works without the new export`, ); } } From e7abe331904a704473819305f16d254446a1d3fd Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Tue, 10 Nov 2026 13:11:54 +0000 Subject: [PATCH 03/14] fix(release): address okwasniewski review findings on the peer-floor checks limrun now floors mobile at >=0.12.0: the provider-owned local daemon change from #988 first shipped in mobile 0.12.0, and on 0.11.0 the local daemon picks up AGENT_DEVICE_DAEMON_BASE_URL. Still a patch, since 0.11.1 never shipped. check-changeset-bumps judges a floor raise by the version change from the previous tag when the current version has no tag yet, so a release PR whose changesets are already consumed no longer fails with "with no changeset": a 0.x minor or a major counts as announced, and a patch bump still does not. The repo-state tests in peer-ranges.test.ts and the tag-reading tests in engine-exports.test.ts are gone, replaced by in-memory fixtures; pnpm check already covers both, and spec.yml no longer fetches full history in the test jobs. check-peer-ranges counts only the packages whose imports were actually verified against a tag record (4, not 12). The import parser now reads export * as ns (only the namespace name), export async function, export declare const enum, comments inside import and export lists, and dynamic import() (destructured names, or unverifiable when bare). oxc-parser is not a clean swap here: it is a dependency of packages/e2e only, so scripts/ cannot import it without a new root dependency, and it exposes no module info, only a raw AST, so both the import and export walks would still be hand-written. showAtTag, the source walk, the import collection, the changelog read, and the changeset parsing are shared in scripts/check-helpers.ts. Both check scripts fail loudly when no e2e@* tags exist at all. The JSDoc blocks state the rules without retelling the #1657 history, and the changeset keeps only the floor changes. Signed-off-by: Varshith Puli --- .changeset/engine-peer-floors.md | 2 +- .github/workflows/spec.yml | 5 - packages/limrun/package.json | 2 +- scripts/changeset-bumps.test.ts | 30 +++++ scripts/changeset-bumps.ts | 18 ++- scripts/check-changeset-bumps.ts | 62 +++------ scripts/check-helpers.ts | 83 ++++++++++++ scripts/check-peer-ranges.ts | 83 +++--------- scripts/engine-exports.test.ts | 216 +++++++++++++++++++++---------- scripts/engine-exports.ts | 104 ++++++++++----- scripts/peer-ranges.test.ts | 24 ---- scripts/peer-ranges.ts | 14 +- 12 files changed, 395 insertions(+), 248 deletions(-) create mode 100644 scripts/check-helpers.ts diff --git a/.changeset/engine-peer-floors.md b/.changeset/engine-peer-floors.md index 4bfe10d29e..4003cd12f7 100644 --- a/.changeset/engine-peer-floors.md +++ b/.changeset/engine-peer-floors.md @@ -5,4 +5,4 @@ "@e2e-dev/limrun": patch --- -Name the released version each peer floor already meant in practice: web and mobile move their `e2e` peer floor from the never-published `0.22.1` to `0.23.0`, which first exports the `stepTimeout` value and the `EngineDoctorCheck` types both engines import; acp moves from the never-published `0.21.4` to `0.22.0`, which first exports the `e2e/agent` rules and tools it imports; limrun moves its mobile peer from the never-published `0.11.1` to `0.11.0`. None of these cuts off a released version a consumer could install on the old range, so each is a patch. The release checks now enforce all three rules from #1657: a floor must name a released version (or the runner version in the same release), a raise past a runner minor the previous range accepted needs a `**Breaking:**` minor, and a new `e2e/engine` import counts as a raise. +Name the released version each peer floor already meant in practice: web and mobile move their `e2e` peer floor from the never-published `0.22.1` to `0.23.0`, which first exports the `stepTimeout` value and the `EngineDoctorCheck` types both engines import; acp moves from the never-published `0.21.4` to `0.22.0`, which first exports the `e2e/agent` rules and tools it imports; limrun moves its mobile peer from the never-published `0.11.1` to `0.12.0`, the first mobile release with the provider-owned local daemon change from #988 (on `0.11.0` the local daemon picks up `AGENT_DEVICE_DAEMON_BASE_URL`). None of these cuts off a released version a consumer could install on the old range, so each is a patch. diff --git a/.github/workflows/spec.yml b/.github/workflows/spec.yml index d8f9962e79..ebda7af760 100644 --- a/.github/workflows/spec.yml +++ b/.github/workflows/spec.yml @@ -103,11 +103,6 @@ jobs: node: [22, 24, 26, 22.22.3, 24.8.0] steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - # The script tests read release tags (scripts/engine-exports.test.ts - # verifies imports against e2e@0.22.0 and e2e@0.23.0), so the - # checkout needs the full history and tags, not a shallow fetch. - fetch-depth: 0 - uses: pnpm/action-setup@9fd676a19091d4595eefd76e4bd31c97133911f1 # v4.2.0 - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: diff --git a/packages/limrun/package.json b/packages/limrun/package.json index f29759b5eb..785319b631 100644 --- a/packages/limrun/package.json +++ b/packages/limrun/package.json @@ -48,7 +48,7 @@ "test:unit": "vitest run tests/unit" }, "peerDependencies": { - "@e2e-dev/mobile": ">=0.11.0 <1", + "@e2e-dev/mobile": ">=0.12.0 <1", "@limrun/api": ">=0.59.0 <1", "e2e": ">=0.15.0 <1" }, diff --git a/scripts/changeset-bumps.test.ts b/scripts/changeset-bumps.test.ts index d0d74af933..8a67a68daa 100644 --- a/scripts/changeset-bumps.test.ts +++ b/scripts/changeset-bumps.test.ts @@ -10,6 +10,7 @@ import { nextVersionAfterBump, parseVersion, pendingBumps, + versionBumpAnnounces, type FloorRaiseInput, } from './changeset-bumps.ts'; @@ -96,6 +97,7 @@ describe('floorRaiseProblems', () => { released, changes, alreadyFlagged: false, + announcedByVersionBump: false, ...extra, }); @@ -140,6 +142,16 @@ describe('floorRaiseProblems', () => { ); }); + it('passes a floor raise the release version bump announces', () => { + assert.deepEqual(floorRaiseProblems([input([], { announcedByVersionBump: true })]), []); + }); + + it('still fails a floor raise carried only by a patch version bump', () => { + const problems = floorRaiseProblems([input([], { announcedByVersionBump: false })]); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /with no changeset for @e2e-dev\/web/); + }); + it('leaves an unannounced minor to disallowedBumps instead of reporting it twice', () => { assert.deepEqual( floorRaiseProblems([input([{ type: 'minor', summary: 'Raises the floor.' }], { alreadyFlagged: true })]), @@ -148,6 +160,24 @@ describe('floorRaiseProblems', () => { }); }); +describe('versionBumpAnnounces', () => { + it('accepts a 0.x minor and a major as the announcement', () => { + assert.equal(versionBumpAnnounces('0.2.4', '0.3.0'), true); + assert.equal(versionBumpAnnounces('0.23.0', '1.0.0'), true); + }); + + it('rejects a patch bump, no bump, and a 1.x minor', () => { + assert.equal(versionBumpAnnounces('0.2.4', '0.2.5'), false); + assert.equal(versionBumpAnnounces('0.2.4', '0.2.4'), false); + assert.equal(versionBumpAnnounces('1.2.3', '1.3.0'), false); + }); + + it('rejects versions that are not x.y.z', () => { + assert.equal(versionBumpAnnounces('0.2.4', '0.3.0-canary-x'), false); + assert.equal(versionBumpAnnounces('not semver', '0.3.0'), false); + }); +}); + describe('latestReleaseVersion', () => { const tags = ['e2e@0.22.0', 'e2e@0.23.0', 'e2e@0.21.3', '@e2e-dev/web@0.15.5', 'e2e@0.23.0-nightly-1']; diff --git a/scripts/changeset-bumps.ts b/scripts/changeset-bumps.ts index 0d74f9d403..7da0d8c241 100644 --- a/scripts/changeset-bumps.ts +++ b/scripts/changeset-bumps.ts @@ -90,6 +90,16 @@ export function announcesFloorRaise(type: BumpType, summary: string): boolean { return false; } +/** Whether the version change from `previousVersion` to `currentVersion` announces a floor raise on its own: a `0.x` minor, or a major. On a release PR the changesets are already consumed, so the bump the release carries is the announcement; a patch bump is not one. */ +export function versionBumpAnnounces(previousVersion: string, currentVersion: string): boolean { + const previous = parseVersion(previousVersion); + const current = parseVersion(currentVersion); + if (previous === undefined || current === undefined) return false; + if (current[0] > previous[0]) return true; + if (previous[0] === 0 && current[0] === 0 && current[1] > previous[1]) return true; + return false; +} + /** The latest released version of `name` among `tags` (`@`), undefined when none exists. The bump check falls back to it when the tag for a package's current version does not exist yet, which is exactly a generated release PR: `version-packages` has already bumped the version, so the current tag is missing and the previous released manifest is the one to compare the floor against. */ export function latestReleaseVersion(tags: readonly string[], name: string): string | undefined { let latest: Semver | undefined; @@ -137,18 +147,24 @@ export interface FloorRaiseInput { readonly released: ReadonlySet; readonly changes: readonly { type: BumpType; summary: string }[]; readonly alreadyFlagged: boolean; + /** The release carrying this floor change already bumped the package by a `0.x` minor or a major, so its consumed changesets announced the raise. */ + readonly announcedByVersionBump: boolean; } /** * Every floor raise in `inputs` that no pending changeset announces as a * `**Breaking:**` minor. A package whose bump `disallowedBumps` already * flags is skipped: the same summary fix (opening it with `**Breaking:**`) - * cures both, so it is reported once, there. + * cures both, so it is reported once, there. A raise the release's own + * version bump announces is skipped too: on a release PR the changesets + * are already consumed, so there is no pending changeset left to carry + * the announcement. */ export function floorRaiseProblems(inputs: readonly FloorRaiseInput[]): string[] { const problems: string[] = []; for (const input of inputs) { if (!floorRaisesPastMinor(input.previousFloor, input.currentFloor, input.released)) continue; + if (input.announcedByVersionBump) continue; if (input.changes.some((change) => announcesFloorRaise(change.type, change.summary))) continue; if (input.alreadyFlagged) continue; const highest = input.changes.reduce( diff --git a/scripts/check-changeset-bumps.ts b/scripts/check-changeset-bumps.ts index 6258ff0ce6..d003d04d4f 100644 --- a/scripts/check-changeset-bumps.ts +++ b/scripts/check-changeset-bumps.ts @@ -4,55 +4,31 @@ * `**Release:**` (`changeset-bumps.ts` says why), or when a changeset * raises a package's peer floor on a sibling past a runner minor the * previous range accepted without a `**Breaking:**` minor - * (`floorRaiseProblems` in `changeset-bumps.ts` says how a raise is judged: - * the previous floor is the one at the package's release tag, or, on a - * generated release PR whose bumped version has no tag yet, at its latest - * released tag; only a released version on an older minor counts). + * (`floorRaiseProblems` in `changeset-bumps.ts` says how a raise is judged). + * The previous floor is the one at the package's release tag; on a + * generated release PR the current version has no tag yet, so the previous + * released tag is used instead, and the version bump from that tag counts + * as the announcement when it is a `0.x` minor or a major. * * Usage: `node scripts/check-changeset-bumps.ts`, part of `pnpm check`. Exits * 1 listing every offending changeset. */ -import { execFileSync } from 'node:child_process'; -import { readFileSync, readdirSync } from 'node:fs'; -import { dirname, join, relative } from 'node:path'; -import { parseChangesetFile } from '@changesets/parse'; -import { BREAKING, RELEASE, disallowedBumps, floorRaiseProblems, latestReleaseVersion, type FloorRaiseInput } from './changeset-bumps.ts'; +import { relative } from 'node:path'; +import { listTags, pendingChangesets, readChangelog, showAtTag } from './check-helpers.ts'; +import { BREAKING, RELEASE, disallowedBumps, floorRaiseProblems, latestReleaseVersion, versionBumpAnnounces, type FloorRaiseInput } from './changeset-bumps.ts'; import { peerFloor, releasedVersions } from './peer-ranges.ts'; import { REPO_ROOT, isWidePeerRange, publicPackages, siblingPeers, type PackageManifest } from './public-packages.ts'; -/** Reads `path` at `tag` (`git show`), undefined when the tag or the file does not exist. */ -function showAtTag(tag: string, path: string): string | undefined { - try { - return execFileSync('git', ['show', `${tag}:${path}`], { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); - } catch { - return undefined; - } -} - /** The manifest at the package's latest released tag, undefined when it has no release tag. A generated release PR has already bumped the version, so the tag for the current version does not exist yet; the previous released manifest is the one to compare the floor against, instead of skipping the check. */ function previousReleaseManifest(name: string, packagePath: string): string | undefined { - let tags: string; - try { - tags = execFileSync('git', ['tag', '--list', `${name}@*`], { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); - } catch { - return undefined; - } - const latest = latestReleaseVersion( - tags - .split('\n') - .map((tag) => tag.trim()) - .filter((tag) => tag.length > 0), - name, - ); + const latest = latestReleaseVersion(listTags(`${name}@*`), name); if (latest === undefined) return undefined; return showAtTag(`${name}@${latest}`, packagePath); } const versions = new Map(publicPackages().flatMap(({ manifest }) => (manifest.version === undefined ? [] : [[manifest.name, manifest.version] as const]))); -const dir = join(REPO_ROOT, '.changeset'); -const files = readdirSync(dir).filter((file) => file.endsWith('.md') && file !== 'README.md'); -const changesets = files.map((file) => parseChangesetFile(readFileSync(join(dir, file), 'utf8'))); +const { files, changesets } = pendingChangesets(); const problems: string[] = []; const flagged = new Set(); for (const [index, changeset] of changesets.entries()) { @@ -75,6 +51,13 @@ for (const changeset of changesets) { } } +// With no `e2e@*` tags at all there is no released version to compare a +// floor against, so the rule below would quietly skip every package. +// Fail loudly instead: a tagless checkout must fetch the tags. +if (listTags('e2e@*').length === 0) { + problems.push('no e2e@* tags exist; a peer floor cannot be compared against any released version, so the check fails instead of quietly skipping (fetch the tags: git fetch --tags)'); +} + const packages = publicPackages(); const byName = new Map(packages.map((pkg) => [pkg.manifest.name, pkg])); const siblings = new Set(packages.map(({ manifest }) => manifest.name)); @@ -83,7 +66,8 @@ let skipped = 0; for (const { path, manifest } of packages) { if (manifest.version === undefined) continue; let tagManifest = showAtTag(`${manifest.name}@${manifest.version}`, relative(REPO_ROOT, path)); - if (tagManifest === undefined) tagManifest = previousReleaseManifest(manifest.name, relative(REPO_ROOT, path)); + const fellBack = tagManifest === undefined; + if (fellBack) tagManifest = previousReleaseManifest(manifest.name, relative(REPO_ROOT, path)); if (tagManifest === undefined) { skipped += 1; continue; @@ -103,12 +87,7 @@ for (const { path, manifest } of packages) { if (currentFloor === undefined || previousFloor === undefined || currentFloor === previousFloor) continue; const sibling = byName.get(peer); if (sibling === undefined) continue; - let changelog: string | undefined; - try { - changelog = readFileSync(join(dirname(sibling.path), 'CHANGELOG.md'), 'utf8'); - } catch { - changelog = undefined; - } + const changelog = readChangelog(sibling.path); if (changelog === undefined) { skipped += 1; continue; @@ -122,6 +101,7 @@ for (const { path, manifest } of packages) { released: releasedVersions(changelog), changes: changesByPackage.get(manifest.name) ?? [], alreadyFlagged: flagged.has(manifest.name), + announcedByVersionBump: fellBack && previous.version !== undefined && versionBumpAnnounces(previous.version, manifest.version), }); } } diff --git a/scripts/check-helpers.ts b/scripts/check-helpers.ts new file mode 100644 index 0000000000..f1d871a90c --- /dev/null +++ b/scripts/check-helpers.ts @@ -0,0 +1,83 @@ +/** + * Shared file and git reads for the release check scripts: the tag lookup, + * the source walk and import collection, the changelog read, and the + * pending changesets. One place, so the check scripts and their tests do + * not each reimplement them. + */ + +import { execFileSync } from 'node:child_process'; +import { readdirSync, readFileSync, statSync } from 'node:fs'; +import { dirname, join } from 'node:path'; +import { parseChangesetFile } from '@changesets/parse'; +import { addEngineImports, engineImports, type EngineImportMap, type ImportKind } from './engine-exports.ts'; +import { REPO_ROOT } from './public-packages.ts'; + +/** Reads `path` at `tag` (`git show`), undefined when the tag or the file does not exist. */ +export function showAtTag(tag: string, path: string): string | undefined { + try { + return execFileSync('git', ['show', `${tag}:${path}`], { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); + } catch { + return undefined; + } +} + +/** The tags matching `pattern` (`git tag --list`), empty when git cannot list them. */ +export function listTags(pattern: string): string[] { + try { + return execFileSync('git', ['tag', '--list', pattern], { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }) + .split('\n') + .map((tag) => tag.trim()) + .filter((tag) => tag.length > 0); + } catch { + return []; + } +} + +/** The TypeScript files under `dirPath`, recursively; unreadable entries are skipped. */ +function sourceFiles(dirPath: string): string[] { + const out: string[] = []; + const walk = (current: string): void => { + let entries: string[]; + try { + entries = readdirSync(current); + } catch { + return; + } + for (const entry of entries) { + const full = join(current, entry); + try { + if (statSync(full).isDirectory()) walk(full); + else if (full.endsWith('.ts')) out.push(full); + } catch { + continue; + } + } + }; + walk(dirPath); + return out; +} + +/** The named `e2e` imports in a package's `src/` tree, keyed by subpath. `packagePath` is the path to the package's `package.json`. */ +export function collectEngineImports(packagePath: string): EngineImportMap { + const imports = new Map>(); + for (const file of sourceFiles(join(dirname(packagePath), 'src'))) { + addEngineImports(imports, engineImports(readFileSync(file, 'utf8'))); + } + return imports; +} + +/** The CHANGELOG.md beside `packagePath`, undefined when it cannot be read. */ +export function readChangelog(packagePath: string): string | undefined { + try { + return readFileSync(join(dirname(packagePath), 'CHANGELOG.md'), 'utf8'); + } catch { + return undefined; + } +} + +/** The pending changesets: every `.md` file in `.changeset` except the README, parsed. */ +export function pendingChangesets(): { files: string[]; changesets: ReturnType[] } { + const dir = join(REPO_ROOT, '.changeset'); + const files = readdirSync(dir).filter((file) => file.endsWith('.md') && file !== 'README.md'); + return { files, changesets: files.map((file) => parseChangesetFile(readFileSync(join(dir, file), 'utf8'))) }; +} diff --git a/scripts/check-peer-ranges.ts b/scripts/check-peer-ranges.ts index b7e2896614..c3f0e8a48e 100644 --- a/scripts/check-peer-ranges.ts +++ b/scripts/check-peer-ranges.ts @@ -4,8 +4,7 @@ * `>= `, or names a version the sibling never * released (no `## ` in its CHANGELOG.md, and no pending changeset * releasing it), or imports an `e2e/*` export the floor version does not - * have (#1657 rule (c): a new `e2e/engine` import counts as raising the - * floor). + * have (rule (c): a new `e2e/engine` import counts as raising the floor). * * A floor naming the version the sibling's pending changesets will release * has no tag yet, so its imports are verified against the working tree, @@ -13,61 +12,23 @@ * unverifiable note. * * `changeset version --snapshot canary` rewrites those peers to the siblings' - * exact canary versions, and the canary output is committed to main as - * `chore: release`. An exact pin that lands makes changesets patch-bump the - * dependent and rewrite the pin on each release of the sibling, and leaves a - * consumer who updates the sibling alone with a peer npm 7+ refuses - * (ERESOLVE). `restore-peer-ranges.ts` puts the ranges back after a publish; - * this check is what notices when it did not run. `peer-ranges.ts` says why - * the floor must also be a released version; `engine-exports.ts` says how - * the floor version's exports are read (the `e2e@` tag). + * exact canary versions; `restore-peer-ranges.ts` puts the ranges back after + * a publish, and this check is what notices when it did not run. See + * `peer-ranges.ts` for why the floor must be a released version and + * `engine-exports.ts` for how the floor version's exports are read. * * Usage: `node scripts/check-peer-ranges.ts`, part of `pnpm check`. Exits 1 * listing every offending peer. */ -import { execFileSync } from 'node:child_process'; -import { readdirSync, readFileSync, statSync } from 'node:fs'; +import { readFileSync } from 'node:fs'; import { dirname, join, relative } from 'node:path'; -import { parseChangesetFile } from '@changesets/parse'; +import { collectEngineImports, listTags, pendingChangesets, readChangelog, showAtTag } from './check-helpers.ts'; import { nextVersionAfterBump, pendingBumps } from './changeset-bumps.ts'; -import { addEngineImports, engineImportProblems, engineImports, tagExportsAt, type EngineImportCheck, type ExportSets, type ImportKind } from './engine-exports.ts'; +import { engineImportProblems, tagExportsAt, type EngineImportCheck, type ExportSets } from './engine-exports.ts'; import { peerFloor, peerRangeProblems } from './peer-ranges.ts'; import { REPO_ROOT, publicPackages, siblingPeers } from './public-packages.ts'; -/** Reads `path` at `tag` (`git show`), undefined when the tag or the file does not exist. */ -function showAtTag(tag: string, path: string): string | undefined { - try { - return execFileSync('git', ['show', `${tag}:${path}`], { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); - } catch { - return undefined; - } -} - -/** The TypeScript files under `dirPath`, recursively; unreadable entries are skipped. */ -function sourceFiles(dirPath: string): string[] { - const out: string[] = []; - const walk = (current: string): void => { - let entries: string[]; - try { - entries = readdirSync(current); - } catch { - return; - } - for (const entry of entries) { - const full = join(current, entry); - try { - if (statSync(full).isDirectory()) walk(full); - else if (full.endsWith('.ts')) out.push(full); - } catch { - continue; - } - } - }; - walk(dirPath); - return out; -} - const packages = publicPackages(); const siblings = new Set(packages.map(({ manifest }) => manifest.name)); const checked: string[] = []; @@ -79,9 +40,7 @@ for (const { manifest } of packages) { // The version each sibling's pending changesets will release: a floor may // name it as the sibling's version in the same release. -const dir = join(REPO_ROOT, '.changeset'); -const changesetFiles = readdirSync(dir).filter((file) => file.endsWith('.md') && file !== 'README.md'); -const changesets = changesetFiles.map((file) => parseChangesetFile(readFileSync(join(dir, file), 'utf8'))); +const { changesets } = pendingChangesets(); const versions = new Map(packages.map(({ manifest }) => [manifest.name, manifest.version])); const nextVersions = new Map(); for (const [name, bump] of pendingBumps(changesets)) { @@ -91,13 +50,14 @@ for (const [name, bump] of pendingBumps(changesets)) { if (next !== undefined) nextVersions.set(name, next); } -const problems = peerRangeProblems(packages, (packagePath) => { - try { - return readFileSync(join(dirname(packagePath), 'CHANGELOG.md'), 'utf8'); - } catch { - return undefined; - } -}, nextVersions); +const problems = peerRangeProblems(packages, readChangelog, nextVersions); + +// With no `e2e@*` tags at all there is no tag record to verify any import +// against, so rule (c) would quietly pass every package. Fail loudly +// instead: a tagless checkout must fetch the tags. +if (listTags('e2e@*').length === 0) { + problems.push('no e2e@* tags exist; no e2e import can be verified against its floor version, so the check fails instead of quietly passing (fetch the tags: git fetch --tags)'); +} // Rule (c): every named import from `e2e/*` must be exported by `e2e` at // the package's peer floor, read off the `e2e@` tag. @@ -135,21 +95,18 @@ for (const { path, manifest } of packages) { if (range === undefined) continue; const floor = peerFloor(range); if (floor === undefined) continue; - const imports = new Map>(); - for (const file of sourceFiles(join(dirname(path), 'src'))) { - addEngineImports(imports, engineImports(readFileSync(file, 'utf8'))); - } + const imports = collectEngineImports(path); if (imports.size === 0) continue; checks.push({ packageName: manifest.name, packagePath: relative(REPO_ROOT, path), sibling: 'e2e', floor, imports }); } -const { problems: importProblems, unverifiable } = engineImportProblems(checks, exportsAt); +const { problems: importProblems, unverifiable, verified } = engineImportProblems(checks, exportsAt); problems.push(...importProblems); if (problems.length > 0) { process.stderr.write(`${problems.join('\n')}\n`); process.exitCode = 1; } else { - process.stdout.write(`peer ranges: ${checked.toSorted().join(', ')} as wide ranges on released versions; ${checks.length} packages' e2e imports verified against their floors\n`); + process.stdout.write(`peer ranges: ${checked.toSorted().join(', ')} as wide ranges on released versions; ${verified} packages' e2e imports verified against their floors\n`); } for (const note of unverifiable) { process.stdout.write(`note: ${note}\n`); diff --git a/scripts/engine-exports.test.ts b/scripts/engine-exports.test.ts index ca8c2c39ba..741ce0ae78 100644 --- a/scripts/engine-exports.test.ts +++ b/scripts/engine-exports.test.ts @@ -1,34 +1,6 @@ import assert from 'node:assert/strict'; -import { execFileSync } from 'node:child_process'; -import { readFileSync, readdirSync, statSync } from 'node:fs'; -import { dirname, join, relative } from 'node:path'; import { describe, it } from 'node:test'; -import { addEngineImports, engineImportProblems, engineImports, resolveEntryExports, resolveModule, subpathEntryFile, tagExportsAt, type EngineImportCheck, type EngineImportMap, type ImportKind } from './engine-exports.ts'; -import { peerFloor } from './peer-ranges.ts'; -import { REPO_ROOT, publicPackages } from './public-packages.ts'; - -/** Reads `path` at `tag` (`git show`), undefined when the tag or the file does not exist. */ -function showAtTag(tag: string, path: string): string | undefined { - try { - return execFileSync('git', ['show', `${tag}:${path}`], { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); - } catch { - return undefined; - } -} - -/** The TypeScript files under `dirPath`, recursively. */ -function sourceFiles(dirPath: string): string[] { - const out: string[] = []; - const walk = (current: string): void => { - for (const entry of readdirSync(current)) { - const full = join(current, entry); - if (statSync(full).isDirectory()) walk(full); - else if (full.endsWith('.ts')) out.push(full); - } - }; - walk(dirPath); - return out; -} +import { engineImportProblems, engineImports, resolveEntryExports, resolveModule, subpathEntryFile, type EngineImportCheck, type EngineImportMap, type ImportKind } from './engine-exports.ts'; describe('engineImports', () => { it('reads named, aliased, and type-only imports from e2e entries', () => { @@ -62,6 +34,34 @@ describe('engineImports', () => { assert.equal(imports.get('engine')?.get('EngineError'), 'value'); }); + it('ignores comments inside import lists', () => { + const imports = engineImports(`import { stepTimeout /* the timeout */, /* leading */ EngineError, type EngineDoctorCheck // trailing\n } from 'e2e/engine';\n`); + assert.deepEqual( + imports.get('engine'), + new Map([ + ['stepTimeout', 'value'], + ['EngineError', 'value'], + ['EngineDoctorCheck', 'type'], + ]), + ); + }); + + it('reads names destructured from a dynamic import', () => { + const imports = engineImports(`const { stepTimeout, type EngineDoctorCheck } = await import('e2e/engine');\n`); + assert.deepEqual( + imports.get('engine'), + new Map([ + ['stepTimeout', 'value'], + ['EngineDoctorCheck', 'type'], + ]), + ); + }); + + it('records a bare dynamic import as unverifiable, not as names', () => { + const imports = engineImports(`await import('e2e/engine');\n`); + assert.deepEqual(imports.get('engine'), new Map([['*', 'value']])); + }); + it('ignores imports from other packages', () => { assert.equal(engineImports(`import { z } from 'zod';\n`).size, 0); }); @@ -97,6 +97,37 @@ describe('exportedNames and resolveEntryExports', () => { assert.deepEqual([...(exported?.types ?? [])].toSorted(), ['KeyModifier']); }); + it('exports only the namespace name for export star as', () => { + const files = new Map([ + ['src/engine/index.ts', `export * as engine from './engine.ts';\n`], + ['src/engine/engine.ts', `export function stepTimeout(): void {}\nexport class EngineError extends Error {}\n`], + ]); + const exported = resolveEntryExports((path) => files.get(path), 'src/engine/index.ts'); + assert.deepEqual([...(exported?.values ?? [])].toSorted(), ['engine']); + assert.deepEqual([...(exported?.types ?? [])].toSorted(), []); + }); + + it('reads async functions and declare const enums as declarations', () => { + const files = new Map([ + [ + 'src/engine/index.ts', + `export async function runCheck(): Promise {}\nexport declare const enum Mode { A = 'a' }\nexport declare function helper(): void;\n`, + ], + ]); + const exported = resolveEntryExports((path) => files.get(path), 'src/engine/index.ts'); + assert.deepEqual([...(exported?.values ?? [])].toSorted(), ['Mode', 'helper', 'runCheck']); + assert.deepEqual([...(exported?.types ?? [])].toSorted(), ['Mode']); + }); + + it('ignores comments inside export lists', () => { + const files = new Map([ + ['src/engine/index.ts', `export { stepTimeout /* the timeout */, EngineError } from './errors.ts';\n`], + ['src/engine/errors.ts', `export function stepTimeout(): void {}\nexport class EngineError extends Error {}\n`], + ]); + const exported = resolveEntryExports((path) => files.get(path), 'src/engine/index.ts'); + assert.deepEqual([...(exported?.values ?? [])].toSorted(), ['EngineError', 'stepTimeout']); + }); + it('answers undefined when an entry file cannot be read', () => { assert.equal(resolveEntryExports(() => undefined, 'src/engine/index.ts'), undefined); }); @@ -189,49 +220,98 @@ describe('engineImportProblems', () => { assert.equal(unverifiable.length, 1); assert.match(unverifiable[0]!, /imported as a namespace/); }); + + it('counts only the checks verified against a tag record', () => { + const { problems, verified } = engineImportProblems( + [ + check('0.23.0', named([['stepTimeout', 'value']])), + check('0.15.0', named([['EngineError', 'value']])), + ], + (_sibling, _subpath, version) => (version === '0.23.0' ? exported(['stepTimeout']) : undefined), + ); + assert.deepEqual(problems, []); + assert.equal(verified, 1); + }); + + it('does not count a namespace-only check as verified', () => { + const { verified } = engineImportProblems( + [check('0.23.0', new Map([['engine', new Map([['*', 'value']])]]))], + () => exported(['stepTimeout']), + ); + assert.equal(verified, 0); + }); }); -describe('imports at their floors on this repo', () => { - it('has every e2e import exported at the package floor version (#1657)', () => { - const checks: EngineImportCheck[] = []; - for (const { path, manifest } of publicPackages()) { - const range = manifest.peerDependencies?.['e2e']; - if (range === undefined) continue; - const floor = peerFloor(range); - if (floor === undefined) continue; - const imports = new Map>(); - for (const file of sourceFiles(join(dirname(path), 'src'))) { - addEngineImports(imports, engineImports(readFileSync(file, 'utf8'))); - } - if (imports.size === 0) continue; - checks.push({ packageName: manifest.name, packagePath: relative(REPO_ROOT, path), sibling: 'e2e', floor, imports }); - } - const siblingDirs = new Map(publicPackages().map(({ manifest, path }) => [manifest.name, relative(REPO_ROOT, dirname(path))])); - const { problems } = engineImportProblems(checks, (sibling, subpath, version) => { - const siblingDir = siblingDirs.get(sibling); - if (siblingDir === undefined) return undefined; - return tagExportsAt(showAtTag, `${sibling}@${version}`, siblingDir, subpath); - }); +describe('floor export checks with in-memory fixtures', () => { + const exported = (values: readonly string[], types: readonly string[] = []) => ({ values: new Set(values), types: new Set(types) }); + + it('verifies every import against fixture export sets for two floors', () => { + const checks: EngineImportCheck[] = [ + { + packageName: '@e2e-dev/web', + packagePath: 'packages/web/package.json', + sibling: 'e2e', + floor: '0.23.0', + imports: new Map([['engine', new Map([['stepTimeout', 'value'], ['EngineDoctorCheck', 'type']])]]), + }, + { + packageName: '@e2e-dev/acp', + packagePath: 'packages/acp/package.json', + sibling: 'e2e', + floor: '0.22.0', + imports: new Map([['agent', new Map([['acp', 'value']])]]), + }, + ]; + const { problems, unverifiable, verified } = engineImportProblems(checks, (_sibling, subpath, version) => + subpath === 'engine' && version === '0.23.0' ? exported(['stepTimeout'], ['EngineDoctorCheck']) : exported(['acp']), + ); assert.deepEqual(problems, []); + assert.deepEqual(unverifiable, []); + assert.equal(verified, 2); }); - it('catches the original bug: web imports stepTimeout, which e2e@0.22.0 does not export', () => { - const exported = tagExportsAt(showAtTag, 'e2e@0.22.0', 'packages/e2e', 'engine'); - assert.notEqual(exported, undefined, 'e2e@0.22.0 tag not fetched; the test job checks out with fetch-depth: 0'); - assert.equal(exported?.values.has('stepTimeout'), false); - assert.equal(exported?.types.has('EngineDoctorCheck'), false); - const atNext = tagExportsAt(showAtTag, 'e2e@0.23.0', 'packages/e2e', 'engine'); - assert.notEqual(atNext, undefined, 'e2e@0.23.0 tag not fetched; the test job checks out with fetch-depth: 0'); - assert.equal(atNext?.values.has('stepTimeout'), true); - assert.equal(atNext?.types.has('EngineDoctorCheck'), true); - }); - - it('does not count a type-star re-export as an e2e/engine value export', () => { - const atNext = tagExportsAt(showAtTag, 'e2e@0.23.0', 'packages/e2e', 'engine'); - assert.notEqual(atNext, undefined, 'e2e@0.23.0 tag not fetched; the test job checks out with fetch-depth: 0'); - assert.equal(atNext?.values.has('isKeyModifier'), false); - assert.equal(atNext?.types.has('isKeyModifier'), false); - assert.equal(atNext?.values.has('parseKey'), true); - assert.equal(atNext?.types.has('KeyModifier'), true); + it('catches the original bug: web imports stepTimeout, which the earlier fixture entry does not export', () => { + const earlier = new Map([ + ['src/engine/index.ts', `export { EngineError } from './errors.ts';\nexport type { NodeRef } from './contract.ts';\n`], + ['src/engine/errors.ts', `export class EngineError extends Error {}\n`], + ['src/engine/contract.ts', `export type NodeRef = string;\n`], + ]); + const later = new Map([ + [ + 'src/engine/index.ts', + `export { EngineError } from './errors.ts';\nexport { stepTimeout } from './timing.ts';\nexport type { NodeRef, EngineDoctorCheck } from './contract.ts';\n`, + ], + ['src/engine/errors.ts', `export class EngineError extends Error {}\n`], + ['src/engine/timing.ts', `export function stepTimeout(): void {}\n`], + ['src/engine/contract.ts', `export type NodeRef = string;\nexport type EngineDoctorCheck = { ok: boolean };\n`], + ]); + const atEarlier = resolveEntryExports((path) => earlier.get(path), 'src/engine/index.ts'); + const atLater = resolveEntryExports((path) => later.get(path), 'src/engine/index.ts'); + assert.equal(atEarlier?.values.has('stepTimeout'), false); + assert.equal(atEarlier?.types.has('EngineDoctorCheck'), false); + assert.equal(atLater?.values.has('stepTimeout'), true); + assert.equal(atLater?.types.has('EngineDoctorCheck'), true); + const imports: EngineImportMap = new Map([['engine', new Map([['stepTimeout', 'value']])]]); + const check = (floor: string): EngineImportCheck => ({ packageName: '@e2e-dev/web', packagePath: 'packages/web/package.json', sibling: 'e2e', floor, imports }); + const { problems: earlierProblems } = engineImportProblems([check('0.22.0')], () => atEarlier); + assert.equal(earlierProblems.length, 1); + assert.match(earlierProblems[0]!, /imports `stepTimeout` from e2e\/engine/); + const { problems: laterProblems } = engineImportProblems([check('0.23.0')], () => atLater); + assert.deepEqual(laterProblems, []); + }); + + it('does not count a type-star re-export as a value export in fixture entries', () => { + const files = new Map([ + ['src/engine/index.ts', `export type * from './contract.ts';\nexport { parseKey } from './contract.ts';\n`], + [ + 'src/engine/contract.ts', + `export function isKeyModifier(value: unknown): boolean { return false; }\nexport function parseKey(value: string): string { return value; }\nexport type KeyModifier = 'Shift';\n`, + ], + ]); + const exportedAt = resolveEntryExports((path) => files.get(path), 'src/engine/index.ts'); + assert.equal(exportedAt?.values.has('isKeyModifier'), false); + assert.equal(exportedAt?.types.has('isKeyModifier'), false); + assert.equal(exportedAt?.values.has('parseKey'), true); + assert.equal(exportedAt?.types.has('KeyModifier'), true); }); }); diff --git a/scripts/engine-exports.ts b/scripts/engine-exports.ts index 46ec011ff0..5666d6dc5f 100644 --- a/scripts/engine-exports.ts +++ b/scripts/engine-exports.ts @@ -1,34 +1,26 @@ /** - * Rule (c) of #1657: an engine that starts importing a new `e2e/engine` - * export counts as raising the floor. This module verifies it: for each - * package, every named import it takes from `e2e` or an `e2e/*` entry must - * be exported by `e2e` at the version the package's peer floor names. + * Rule (c): an engine that starts importing a new `e2e/engine` export + * counts as raising the floor. This module verifies it: every named import + * a package takes from `e2e` or an `e2e/*` entry must be exported by `e2e` + * at the version the package's peer floor names. * - * The export set at a version comes from the tag record, - * `e2e@`: the entry file is read off the sibling's `package.json` - * `exports` at that tag (its `types` target, mapped from `dist/` to - * `src/`), and `export *` chains are followed. The tag record is the only - * source that names the version's exports exactly: the CHANGELOG records - * releases but not exports, and the published tarball would put the - * network in `pnpm check`. A floor whose tag does not exist (for example - * `e2e@0.15.0`, released before a tag was cut per version) cannot be - * verified this way; that floor is reported as unverifiable, not as a - * failure, and the released-floor rule in `peer-ranges.ts` still applies - * to it. Type-only imports count the same as value imports: the package's + * The export set at a version comes from the `e2e@` tag: the entry + * file is read off the sibling's `package.json` `exports` at that tag (its + * `types` target, mapped from `dist/` to `src/`), and `export *` chains are + * followed. A floor whose tag does not exist cannot be verified this way; + * that floor is reported as unverifiable, not a failure, and the + * released-floor rule in `peer-ranges.ts` still applies to it. Imports and + * exports are tracked by kind, `value` or `type`: a value import needs a + * value export (a name that only reaches the entry through `export type *` + * does not satisfy one), and a type import is satisfied by either kind. + * Type-only imports count the same as value imports: the package's * published `.d.ts` names those types, so a consumer on the floor runner - * fails typecheck when the floor version lacks them. The split runs the - * other way too: a value import needs a value export, so a name that only - * reaches the entry through `export type *` (for example `isKeyModifier` - * from `contract.ts`, which `e2e/engine` does not export as a value) does - * not satisfy a value import. Imports and exports are therefore tracked by - * kind: `value` or `type`. A type import is satisfied by a value or a type - * export; a value import only by a value export. + * fails typecheck when the floor version lacks them. * * Only imports from `e2e` itself are checked. An integration's imports * from another engine (`@e2e-dev/web`, `@e2e-dev/mobile`) are the same - * shape but a different sibling, and the maintainer's rule names - * `e2e/engine`; extending this to engine peers is a follow-up, not part - * of this change. + * shape but a different sibling; extending this to engine peers is a + * follow-up, not part of this change. */ /** Whether an import takes the name as a value or only as a type. A value import needs a value export; a type import is satisfied by either kind. */ @@ -40,6 +32,13 @@ export type EngineImportMap = ReadonlyMap - list + stripComments(list) .split(',') .map((part) => part.trim()) .filter((part) => part.length > 0) @@ -77,6 +76,25 @@ export function engineImports(source: string): EngineImportMap { for (const match of source.matchAll(NAMESPACE_FROM)) { add((match[1] ?? '').replace(/^\//, ''), [['*', 'value']]); } + // A dynamic import takes its names the same way, when they are + // destructured; a bare one cannot be enumerated, so it is recorded as + // the namespace name, like a namespace import. The destructured + // statements are blanked before the bare scan, so their import call is + // not also counted as a bare one. + const blanked: [number, number][] = []; + for (const match of source.matchAll(DYNAMIC_IMPORT_NAMES)) { + const list = match[1]; + const subpath = (match[2] ?? '').replace(/^\//, ''); + if (list !== undefined) add(subpath, splitNames(list, false)); + if (match.index !== undefined) blanked.push([match.index, match.index + match[0].length]); + } + let dynamicSource = source; + for (const [start, end] of blanked.toSorted((a, b) => b[0] - a[0])) { + dynamicSource = `${dynamicSource.slice(0, start)}${' '.repeat(end - start)}${dynamicSource.slice(end)}`; + } + for (const match of dynamicSource.matchAll(DYNAMIC_IMPORT)) { + add((match[1] ?? '').replace(/^\//, ''), [['*', 'value']]); + } return found; } @@ -110,7 +128,7 @@ function exportedNames(source: string): { const wholeListType = match[1] !== undefined; const list = match[2]; if (list === undefined) continue; - for (const part of list.split(',')) { + for (const part of stripComments(list).split(',')) { const trimmed = part.trim(); if (trimmed.length === 0) continue; const typeOnly = wholeListType || trimmed.startsWith('type '); @@ -121,15 +139,25 @@ function exportedNames(source: string): { (typeOnly ? types : values).add(name); } } - for (const match of source.matchAll(/export\s+(type\s+)?\*\s*(?:as\s+\w+\s*)?from\s+['"]([^'"]+)['"]/g)) { - if (match[2] !== undefined) (match[1] !== undefined ? typeStarModules : starModules).push(match[2]); + // `export * as ns` exports only the namespace name, not the module's + // names, so it is recorded as one export and its star chain is not + // followed. + for (const match of source.matchAll(/export\s+(type\s+)?\*\s*(?:as\s+(\w+)\s*)?from\s+['"]([^'"]+)['"]/g)) { + if (match[3] === undefined) continue; + if (match[2] !== undefined) { + (match[1] !== undefined ? types : values).add(match[2]); + } else if (match[1] !== undefined) { + typeStarModules.push(match[3]); + } else { + starModules.push(match[3]); + } } - for (const match of source.matchAll(/export\s+(?:declare\s+)?(interface|type|class|function|const|let|var|enum|abstract\s+class)\s+(\w+)/g)) { + for (const match of source.matchAll(/export\s+(?:declare\s+)?(?:async\s+)?(?:abstract\s+)?(?:const\s+)?(interface|type|class|function|const|let|var|enum)\s+(\w+)/g)) { const kind = match[1]; const name = match[2]; if (kind === undefined || name === undefined) continue; if (kind === 'interface' || kind === 'type') types.add(name); - else if (kind === 'class' || kind === 'enum' || kind.startsWith('abstract')) { + else if (kind === 'class' || kind === 'enum') { values.add(name); types.add(name); } else values.add(name); @@ -254,15 +282,20 @@ export interface EngineImportCheck { * its names cannot be enumerated. A namespace import does not excuse the * names imported beside it from the same subpath: those are still * validated. A value import needs a value export; a type import is - * satisfied by a value or a type export. + * satisfied by a value or a type export. `verified` counts the checks + * whose named imports were all checked against a tag record: a check no + * tag record covers is not verified, even when it reports no problem. */ export function engineImportProblems( checks: readonly EngineImportCheck[], exportsAt: (sibling: string, subpath: string, version: string) => ExportSets | undefined, -): { problems: string[]; unverifiable: string[] } { +): { problems: string[]; unverifiable: string[]; verified: number } { const problems: string[] = []; const unverifiable: string[] = []; + let verified = 0; for (const check of checks) { + let checked = false; + let allResolved = true; for (const [subpath, names] of check.imports) { const label = subpath === '' ? check.sibling : `${check.sibling}/${subpath}`; const named = [...names].filter(([name]) => name !== '*'); @@ -273,8 +306,10 @@ export function engineImportProblems( const exported = exportsAt(check.sibling, subpath, check.floor); if (exported === undefined) { unverifiable.push(`${check.packagePath}: ${label} at ${check.sibling}@${check.floor} cannot be verified, no tag record for that version; the floor must still name a released version`); + allResolved = false; continue; } + checked = true; const missing = named .filter(([name, kind]) => (kind === 'value' ? !exported.values.has(name) : !exported.values.has(name) && !exported.types.has(name))) .map(([name]) => name) @@ -285,6 +320,7 @@ export function engineImportProblems( ); } } + if (checked && allResolved) verified += 1; } - return { problems, unverifiable }; + return { problems, unverifiable, verified }; } diff --git a/scripts/peer-ranges.test.ts b/scripts/peer-ranges.test.ts index bc18ccfaf6..6f88125646 100644 --- a/scripts/peer-ranges.test.ts +++ b/scripts/peer-ranges.test.ts @@ -1,8 +1,5 @@ import assert from 'node:assert/strict'; -import { readFileSync } from 'node:fs'; -import { dirname, join } from 'node:path'; import { describe, it } from 'node:test'; -import { publicPackages } from './public-packages.ts'; import { peerFloor, peerRangeProblems, releasedVersions, type PublicPackage } from './peer-ranges.ts'; function pkg(name: string, peers: Record): PublicPackage { @@ -92,24 +89,3 @@ describe('peerRangeProblems', () => { assert.deepEqual(peerRangeProblems(packages, read), []); }); }); - -describe('released floors on this repo', () => { - it('has no sibling peer floor naming a version that never shipped (#1657)', () => { - const problems = peerRangeProblems(publicPackages(), (packagePath) => { - try { - return readFileSync(join(dirname(packagePath), 'CHANGELOG.md'), 'utf8'); - } catch { - return undefined; - } - }); - assert.deepEqual(problems, []); - }); - - it('keeps the #1657 floors at the oldest released sibling each package works with', () => { - const byName = new Map(publicPackages().map(({ manifest }) => [manifest.name, manifest.peerDependencies ?? {}])); - assert.equal(byName.get('@e2e-dev/mobile')?.['e2e'], '>=0.23.0 <1'); - assert.equal(byName.get('@e2e-dev/web')?.['e2e'], '>=0.23.0 <1'); - assert.equal(byName.get('@e2e-dev/acp')?.['e2e'], '>=0.22.0 <1'); - assert.equal(byName.get('@e2e-dev/limrun')?.['@e2e-dev/mobile'], '>=0.11.0 <1'); - }); -}); diff --git a/scripts/peer-ranges.ts b/scripts/peer-ranges.ts index 67a3fb3818..5f1ddacd06 100644 --- a/scripts/peer-ranges.ts +++ b/scripts/peer-ranges.ts @@ -10,16 +10,10 @@ * refuses. Second, the floor must name a version the sibling actually * released, read off its CHANGELOG.md (`## x.y.z` headings), or the version * the sibling's pending changesets will release alongside it (the - * sibling's version in the same release). A floor past the latest stable names a - * version no install can satisfy: #1657 raised both engines to `>=0.22.1` - * in a patch release, but no stable `e2e@0.22.1` ever shipped (only - * nightlies), so a fresh `npm install` of an unchanged project on - * `e2e ~0.21.3` failed with ERESOLVE. The same shape hid in `@e2e-dev/acp` - * (`>=0.21.4`, never released) and `@e2e-dev/limrun` - * (`@e2e-dev/mobile >=0.11.1`, never released). A floor may rise only once - * its version is in the changelog (or is the sibling's pending release); - * until then the package either works without the new export, on the old - * floor, or waits for the release. + * sibling's version in the same release). A floor past the latest stable + * names a version no install can satisfy, so a patch release must not + * raise it there; until the version ships, the package either works + * without the new export, on the old floor, or waits for the release. */ import { relative } from 'node:path'; From 578547139426a2273bede1d416e230bcd0c7dfdc Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Tue, 10 Nov 2026 19:25:43 +0000 Subject: [PATCH 04/14] fix(release): parse engine imports and exports with oxc-parser The regex parser in scripts/engine-exports.ts misread real engine source, so rule (c) could block a release on a doc comment or miss a real import. Replace it with oxc-parser module info (parseSync, root devDep 0.158.0, the version already in the lockfile): JSDoc example imports and commented-out exports no longer count, destructured export const names are read, and types nested inside an exported namespace no longer leak out as top-level exports. Declaration kinds come from the parsed declarations, since module info alone cannot tell a declare function from a type. Also addresses the should-fixes from the same review: the isKeyModifier test now puts the name in the fixture type set, so it tests what its name says; pendingChangesets returns { file, changeset } pairs in sorted file order; check-changeset-bumps uses BumpType instead of the inline union; tagExportsAt takes readFile(path) and showWorkingTree drops its unused tag parameter; the changeset is one line per floor move and changeset-bumps no longer retells the #1657 history. Verified: pnpm run test:scripts 212 pass, 0 fail; tsc -p scripts clean; oxlint clean on the changed files; check-peer-ranges and check-changeset-bumps both exit 0 on the working tree. On the live tags, e2e@0.22.0 still lacks stepTimeout and EngineDoctorCheck while e2e@0.23.0 exports both, and StandardSchemaV1.Props no longer leaks. Signed-off-by: Varshith Puli --- .changeset/engine-peer-floors.md | 4 +- package.json | 1 + pnpm-lock.yaml | 3 + scripts/changeset-bumps.ts | 24 ++- scripts/check-changeset-bumps.ts | 14 +- scripts/check-helpers.ts | 10 +- scripts/check-peer-ranges.ts | 10 +- scripts/engine-exports.test.ts | 58 +++++- scripts/engine-exports.ts | 294 ++++++++++++++++++++++--------- 9 files changed, 296 insertions(+), 122 deletions(-) diff --git a/.changeset/engine-peer-floors.md b/.changeset/engine-peer-floors.md index 4003cd12f7..f6f556a34b 100644 --- a/.changeset/engine-peer-floors.md +++ b/.changeset/engine-peer-floors.md @@ -5,4 +5,6 @@ "@e2e-dev/limrun": patch --- -Name the released version each peer floor already meant in practice: web and mobile move their `e2e` peer floor from the never-published `0.22.1` to `0.23.0`, which first exports the `stepTimeout` value and the `EngineDoctorCheck` types both engines import; acp moves from the never-published `0.21.4` to `0.22.0`, which first exports the `e2e/agent` rules and tools it imports; limrun moves its mobile peer from the never-published `0.11.1` to `0.12.0`, the first mobile release with the provider-owned local daemon change from #988 (on `0.11.0` the local daemon picks up `AGENT_DEVICE_DAEMON_BASE_URL`). None of these cuts off a released version a consumer could install on the old range, so each is a patch. +- web and mobile: `e2e` peer floor `>=0.22.1` to `>=0.23.0`, the first version exporting the `stepTimeout` value and the `EngineDoctorCheck` types they import. +- acp: `e2e` peer floor `>=0.21.4` to `>=0.22.0`, the first version exporting the `e2e/agent` rules and tools it imports. +- limrun: mobile peer floor `>=0.11.1` to `>=0.12.0`, the first mobile release with the provider-owned local daemon change from #988. diff --git a/package.json b/package.json index dd8e1e076d..21ba667488 100644 --- a/package.json +++ b/package.json @@ -52,6 +52,7 @@ "@types/node": "26.6.6", "ajv": "8.20.0", "fallow": "3.43.0", + "oxc-parser": "0.158.0", "oxlint": "1.93.0", "remark-gfm": "4.0.1", "typescript": "7.0.2" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c161c1ef13..07d5bf742c 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -151,6 +151,9 @@ importers: fallow: specifier: 3.43.0 version: 3.43.0 + oxc-parser: + specifier: 0.158.0 + version: 0.158.0 oxlint: specifier: 1.93.0 version: 1.93.0 diff --git a/scripts/changeset-bumps.ts b/scripts/changeset-bumps.ts index 7da0d8c241..a939783b55 100644 --- a/scripts/changeset-bumps.ts +++ b/scripts/changeset-bumps.ts @@ -10,18 +10,16 @@ * `**Breaking:**` or `**Release:**`. A `major` makes it `1.0.0`, outside every * sibling's `>=x <1` peer range, so only a `**Release:**` may carry one. * - * Rule (a) of #1657 sits here too: a changeset that raises a package's peer - * floor on a sibling past a runner minor the previous range accepted must - * be a `**Breaking:**` minor. The check script pairs each pending changeset - * with the floor change it ships: the previous floor is the one at the - * package's release tag, the current floor is the working tree's, and a - * raise counts only when it cuts off a *released* version on an older - * minor. A correction from a never-published floor to the version it - * already meant in practice (for example `>=0.22.1` to `>=0.23.0`, where - * the previous range accepted only released `0.23.0`) cuts off nothing a - * consumer could install, so a patch carries it. The rule lives in this - * check, not in `check-peer-ranges.ts`, because only this check reads the - * changesets that must announce the raise. + * Rule (a): a changeset that raises a package's peer floor on a sibling + * past a runner minor the previous range accepted must be a `**Breaking:**` + * minor. The check script pairs each pending changeset with the floor + * change it ships: the previous floor is the one at the package's release + * tag, the current floor is the working tree's, and a raise counts only + * when it cuts off a *released* version on an older minor. A correction + * from a never-published floor to the released version it already meant + * cuts off nothing a consumer could install, so a patch carries it. The + * rule lives in this check, not in `check-peer-ranges.ts`, because only + * this check reads the changesets that must announce the raise. */ import { parseChangesetFile } from '@changesets/parse'; @@ -83,7 +81,7 @@ export function floorRaisesPastMinor(previousFloor: string, currentFloor: string return false; } -/** Whether a changeset entry of `type` with `summary` announces a floor raise: a minor opening `**Breaking:**`, or a major opening `**Release:**`. A `**Release:**` minor does not announce one: the maintainer's rule for #1657 is that a floor raise past an accepted runner minor must be a `**Breaking:**` minor, and a release train is not that signal. A major needs no breaking prefix because the major itself is the signal: no `0.x` consumer picks it up without opting in. */ +/** Whether a changeset entry of `type` with `summary` announces a floor raise: a minor opening `**Breaking:**`, or a major opening `**Release:**`. A `**Release:**` minor does not announce one: a floor raise past an accepted runner minor must be a `**Breaking:**` minor, and a release train is not that signal. A major needs no breaking prefix because the major itself is the signal: no `0.x` consumer picks it up without opting in. */ export function announcesFloorRaise(type: BumpType, summary: string): boolean { if (type === 'minor') return summary.startsWith(BREAKING); if (type === 'major') return summary.startsWith(RELEASE); diff --git a/scripts/check-changeset-bumps.ts b/scripts/check-changeset-bumps.ts index d003d04d4f..d2bcdc978c 100644 --- a/scripts/check-changeset-bumps.ts +++ b/scripts/check-changeset-bumps.ts @@ -16,7 +16,7 @@ import { relative } from 'node:path'; import { listTags, pendingChangesets, readChangelog, showAtTag } from './check-helpers.ts'; -import { BREAKING, RELEASE, disallowedBumps, floorRaiseProblems, latestReleaseVersion, versionBumpAnnounces, type FloorRaiseInput } from './changeset-bumps.ts'; +import { BREAKING, RELEASE, disallowedBumps, floorRaiseProblems, latestReleaseVersion, versionBumpAnnounces, type BumpType, type FloorRaiseInput } from './changeset-bumps.ts'; import { peerFloor, releasedVersions } from './peer-ranges.ts'; import { REPO_ROOT, isWidePeerRange, publicPackages, siblingPeers, type PackageManifest } from './public-packages.ts'; @@ -28,12 +28,10 @@ function previousReleaseManifest(name: string, packagePath: string): string | un } const versions = new Map(publicPackages().flatMap(({ manifest }) => (manifest.version === undefined ? [] : [[manifest.name, manifest.version] as const]))); -const { files, changesets } = pendingChangesets(); +const pending = pendingChangesets(); const problems: string[] = []; const flagged = new Set(); -for (const [index, changeset] of changesets.entries()) { - const file = files[index]; - if (file === undefined) continue; +for (const { file, changeset } of pending) { for (const { name, type } of disallowedBumps(changeset, versions)) { flagged.add(name); const needs = type === 'major' ? RELEASE : `${BREAKING} or ${RELEASE}`; @@ -41,8 +39,8 @@ for (const [index, changeset] of changesets.entries()) { } } -const changesByPackage = new Map(); -for (const changeset of changesets) { +const changesByPackage = new Map(); +for (const { changeset } of pending) { for (const { name, type } of changeset.releases) { if (type !== 'patch' && type !== 'minor' && type !== 'major') continue; const list = changesByPackage.get(name) ?? []; @@ -112,6 +110,6 @@ if (problems.length > 0) { process.exitCode = 1; } else { process.stdout.write( - `changeset bumps: ${files.length} pending, none an unannounced 0.x minor or major; ${inputs.length} peer floor ${inputs.length === 1 ? 'change' : 'changes'} checked against their releases, none raised past an accepted minor without a **Breaking:** minor${skipped > 0 ? ` (${skipped} skipped: no release tag or changelog)` : ''}\n`, + `changeset bumps: ${pending.length} pending, none an unannounced 0.x minor or major; ${inputs.length} peer floor ${inputs.length === 1 ? 'change' : 'changes'} checked against their releases, none raised past an accepted minor without a **Breaking:** minor${skipped > 0 ? ` (${skipped} skipped: no release tag or changelog)` : ''}\n`, ); } diff --git a/scripts/check-helpers.ts b/scripts/check-helpers.ts index f1d871a90c..31b0fcb36f 100644 --- a/scripts/check-helpers.ts +++ b/scripts/check-helpers.ts @@ -75,9 +75,11 @@ export function readChangelog(packagePath: string): string | undefined { } } -/** The pending changesets: every `.md` file in `.changeset` except the README, parsed. */ -export function pendingChangesets(): { files: string[]; changesets: ReturnType[] } { +/** The pending changesets: every `.md` file in `.changeset` except the README, parsed, in file order. */ +export function pendingChangesets(): { file: string; changeset: ReturnType }[] { const dir = join(REPO_ROOT, '.changeset'); - const files = readdirSync(dir).filter((file) => file.endsWith('.md') && file !== 'README.md'); - return { files, changesets: files.map((file) => parseChangesetFile(readFileSync(join(dir, file), 'utf8'))) }; + const files = readdirSync(dir) + .filter((file) => file.endsWith('.md') && file !== 'README.md') + .toSorted(); + return files.map((file) => ({ file, changeset: parseChangesetFile(readFileSync(join(dir, file), 'utf8')) })); } diff --git a/scripts/check-peer-ranges.ts b/scripts/check-peer-ranges.ts index c3f0e8a48e..02880891a9 100644 --- a/scripts/check-peer-ranges.ts +++ b/scripts/check-peer-ranges.ts @@ -40,10 +40,10 @@ for (const { manifest } of packages) { // The version each sibling's pending changesets will release: a floor may // name it as the sibling's version in the same release. -const { changesets } = pendingChangesets(); +const pending = pendingChangesets(); const versions = new Map(packages.map(({ manifest }) => [manifest.name, manifest.version])); const nextVersions = new Map(); -for (const [name, bump] of pendingBumps(changesets)) { +for (const [name, bump] of pendingBumps(pending.map(({ changeset }) => changeset))) { const version = versions.get(name); if (version === undefined) continue; const next = nextVersionAfterBump(version, bump); @@ -65,7 +65,7 @@ const siblingDirs = new Map(packages.map(({ manifest, path }) => [manifest.name, const exportsCache = new Map(); /** Reads `path` from the working tree, undefined when it cannot be read. */ -function showWorkingTree(_tag: string, path: string): string | undefined { +function showWorkingTree(path: string): string | undefined { try { return readFileSync(join(REPO_ROOT, path), 'utf8'); } catch { @@ -77,13 +77,13 @@ const exportsAt = (sibling: string, subpath: string, version: string): ExportSet const key = `${sibling}@${version}:${subpath}`; if (exportsCache.has(key)) return exportsCache.get(key); const siblingDir = siblingDirs.get(sibling); - let resolved = siblingDir === undefined ? undefined : tagExportsAt(showAtTag, `${sibling}@${version}`, siblingDir, subpath); + let resolved = siblingDir === undefined ? undefined : tagExportsAt((path) => showAtTag(`${sibling}@${version}`, path), siblingDir, subpath); if (resolved === undefined && siblingDir !== undefined && nextVersions.get(sibling) === version) { // A floor naming the version the sibling's pending changesets will // release has no tag yet, so the tag lookup cannot verify it; the // working tree is that pending release's source, so verify against it // instead of passing the floor on an unverifiable note. - resolved = tagExportsAt(showWorkingTree, `${sibling}@${version}`, siblingDir, subpath); + resolved = tagExportsAt(showWorkingTree, siblingDir, subpath); } exportsCache.set(key, resolved); return resolved; diff --git a/scripts/engine-exports.test.ts b/scripts/engine-exports.test.ts index 741ce0ae78..0104719748 100644 --- a/scripts/engine-exports.test.ts +++ b/scripts/engine-exports.test.ts @@ -46,8 +46,15 @@ describe('engineImports', () => { ); }); - it('reads names destructured from a dynamic import', () => { - const imports = engineImports(`const { stepTimeout, type EngineDoctorCheck } = await import('e2e/engine');\n`); + it('ignores an import in a JSDoc example', () => { + const imports = engineImports( + `/**\n * @example\n * import { x } from 'e2e/engine';\n */\nimport { stepTimeout } from 'e2e/engine';\n`, + ); + assert.deepEqual(imports.get('engine'), new Map([['stepTimeout', 'value']])); + }); + + it('reads names re-exported from e2e entries as imports', () => { + const imports = engineImports(`export { stepTimeout, type EngineDoctorCheck } from 'e2e/engine';\n`); assert.deepEqual( imports.get('engine'), new Map([ @@ -57,6 +64,24 @@ describe('engineImports', () => { ); }); + it('records a star re-export from an e2e entry as unverifiable', () => { + const imports = engineImports(`export * from 'e2e/engine';\n`); + assert.deepEqual(imports.get('engine'), new Map([['*', 'value']])); + }); + + it('reads names destructured from a dynamic import', () => { + // A `type` modifier is not valid syntax in a destructuring pattern, so + // destructured names are values. + const imports = engineImports(`const { stepTimeout, EngineError: err } = await import('e2e/engine');\n`); + assert.deepEqual( + imports.get('engine'), + new Map([ + ['stepTimeout', 'value'], + ['EngineError', 'value'], + ]), + ); + }); + it('records a bare dynamic import as unverifiable, not as names', () => { const imports = engineImports(`await import('e2e/engine');\n`); assert.deepEqual(imports.get('engine'), new Map([['*', 'value']])); @@ -119,6 +144,32 @@ describe('exportedNames and resolveEntryExports', () => { assert.deepEqual([...(exported?.types ?? [])].toSorted(), ['Mode']); }); + it('ignores a commented-out export', () => { + const files = new Map([['src/engine/index.ts', `export function kept(): void {}\n// export function gone(): void {}\n`]]); + const exported = resolveEntryExports((path) => files.get(path), 'src/engine/index.ts'); + assert.deepEqual([...(exported?.values ?? [])].toSorted(), ['kept']); + assert.deepEqual([...(exported?.types ?? [])].toSorted(), []); + }); + + it('reads names bound by a destructured export const', () => { + const files = new Map([['src/collect/registry.ts', `export const { describe, beforeEach, afterEach } = test;\n`]]); + const exported = resolveEntryExports((path) => files.get(path), 'src/collect/registry.ts'); + assert.deepEqual([...(exported?.values ?? [])].toSorted(), ['afterEach', 'beforeEach', 'describe']); + assert.deepEqual([...(exported?.types ?? [])].toSorted(), []); + }); + + it('does not leak types nested inside an exported namespace', () => { + const files = new Map([ + [ + 'src/types.ts', + `export namespace StandardSchemaV1 {\n export interface Props { x: string }\n export type Result = { ok: boolean };\n}\n`, + ], + ]); + const exported = resolveEntryExports((path) => files.get(path), 'src/types.ts'); + assert.deepEqual([...(exported?.values ?? [])].toSorted(), ['StandardSchemaV1']); + assert.deepEqual([...(exported?.types ?? [])].toSorted(), []); + }); + it('ignores comments inside export lists', () => { const files = new Map([ ['src/engine/index.ts', `export { stepTimeout /* the timeout */, EngineError } from './errors.ts';\n`], @@ -187,10 +238,11 @@ describe('engineImportProblems', () => { it('fails a value import satisfied only by a type-only export', () => { const { problems } = engineImportProblems( [check('0.23.0', named([['isKeyModifier', 'value'], ['parseKey', 'value'], ['KeyModifier', 'type']]))], - () => exported(['parseKey'], ['KeyModifier']), + () => exported(['parseKey'], ['KeyModifier', 'isKeyModifier']), ); assert.equal(problems.length, 1); assert.match(problems[0]!, /imports `isKeyModifier` from e2e\/engine/); + assert.match(problems[0]!, /does not export it/); }); it('reports a floor with no tag record as unverifiable, not a problem', () => { diff --git a/scripts/engine-exports.ts b/scripts/engine-exports.ts index 5666d6dc5f..b344fb6f15 100644 --- a/scripts/engine-exports.ts +++ b/scripts/engine-exports.ts @@ -4,6 +4,15 @@ * a package takes from `e2e` or an `e2e/*` entry must be exported by `e2e` * at the version the package's peer floor names. * + * Imports and exports come from oxc-parser's module info + * (`parseSync(...).module`), not from pattern matching: comments and JSDoc + * examples never count as imports or exports, destructured declarations + * are read as the names they bind, and names nested inside a namespace + * never leak out as top-level exports. A declaration's kind comes from the + * parsed declaration itself, since module info alone cannot tell a + * `declare` function from a type: interfaces and type aliases are types + * only, classes and enums are both, everything else exported is a value. + * * The export set at a version comes from the `e2e@` tag: the entry * file is read off the sibling's `package.json` `exports` at that tag (its * `types` target, mapped from `dist/` to `src/`), and `export *` chains are @@ -23,21 +32,71 @@ * follow-up, not part of this change. */ +import { parseSync } from 'oxc-parser'; + /** Whether an import takes the name as a value or only as a type. A value import needs a value export; a type import is satisfied by either kind. */ export type ImportKind = 'value' | 'type'; /** The named imports from `e2e` and its subpaths in one source file, keyed by subpath (`''` is the bare `e2e` entry), each name with its kind. A value import of a name subsumes a type import of the same name. */ export type EngineImportMap = ReadonlyMap>; -const IMPORT_FROM = /import\s+(type\s+)?(?:\w+\s*,\s*)?\{([^}]*)\}\s+from\s+['"]e2e(\/[^'"]*)?['"]/gs; -const REEXPORT_FROM = /export\s+(type\s+)?\{([^}]*)\}\s+from\s+['"]e2e(\/[^'"]*)?['"]/gs; -const NAMESPACE_FROM = /import\s+(?:type\s+)?\*\s+as\s+\w+\s+from\s+['"]e2e(\/[^'"]*)?['"]/g; -const DYNAMIC_IMPORT_NAMES = /(?:const|let|var)\s*\{\s*([^}]*)\}\s*=\s*(?:await\s+)?import\s*\(\s*['"]e2e(\/[^'"]*)?['"]\s*\)/gs; -const DYNAMIC_IMPORT = /import\s*\(\s*['"]e2e(\/[^'"]*)?['"]\s*\)/g; +/** The subpath of an `e2e` specifier (`''` for the bare entry), undefined for any other package. */ +function e2eSubpath(specifier: string): string | undefined { + if (specifier === 'e2e') return ''; + if (specifier.startsWith('e2e/')) return specifier.slice('e2e/'.length); + return undefined; +} + +type AstNode = Record; + +function isRecord(value: unknown): value is AstNode { + return typeof value === 'object' && value !== null; +} -/** `source` with block and line comments blanked, so a comment inside an import or export list is never read as a name. */ -function stripComments(source: string): string { - return source.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/\/\/[^\n]*/g, ' '); +/** The `import(...)` call in `node`, unwrapping `await` and parentheses; undefined when `node` is not one. */ +function importCall(node: unknown): AstNode | undefined { + let current: unknown = node; + while (isRecord(current) && (current.type === 'AwaitExpression' || current.type === 'ParenthesizedExpression')) { + current = current.type === 'AwaitExpression' ? current.argument : current.expression; + } + if (!isRecord(current) || current.type !== 'ImportExpression') return undefined; + return current; +} + +/** The source of an `import(...)` call; undefined when `node` is not one. */ +function importCallSource(node: unknown): string | undefined { + const call = importCall(node); + if (call === undefined) return undefined; + const source = call.source; + if (!isRecord(source) || source.type !== 'Literal' || typeof source.value !== 'string') return undefined; + return source.value; +} + +/** The module exports a destructuring pattern reads: the top-level keys of an object pattern, or undefined when the pattern cannot be enumerated (a rest element, a whole-module binding, or anything but an object pattern). A nested pattern reads a property of an export, not another export, so only top-level keys count. */ +function patternNames(pattern: unknown): string[] | undefined { + if (!isRecord(pattern)) return undefined; + if (pattern.type !== 'ObjectPattern' || !Array.isArray(pattern.properties)) return undefined; + const names: string[] = []; + for (const property of pattern.properties) { + if (!isRecord(property)) return undefined; + if (property.type === 'RestElement') return undefined; + if (property.type !== 'Property') return undefined; + const key = property.key; + if (!isRecord(key) || key.type !== 'Identifier' || typeof key.name !== 'string') return undefined; + names.push(key.name); + } + return names; +} + +/** Walks every node in `value`, calling `visit` on each object node. */ +function walkAst(value: unknown, visit: (node: AstNode) => void): void { + if (Array.isArray(value)) { + for (const item of value) walkAst(item, visit); + return; + } + if (!isRecord(value)) return; + visit(value); + for (const child of Object.values(value)) walkAst(child, visit); } /** The named imports from `e2e` and its subpaths in one source file, keyed by subpath (`''` is the bare `e2e` entry). A namespace import is recorded as the name `'*'`, which the check cannot enumerate. */ @@ -54,47 +113,61 @@ export function engineImports(source: string): EngineImportMap { if (existing === undefined || kind === 'value') map.set(name, kind); } }; - const splitNames = (list: string, wholeListType: boolean): [string, ImportKind][] => - stripComments(list) - .split(',') - .map((part) => part.trim()) - .filter((part) => part.length > 0) - .map((part): [string, ImportKind] => { - const typeOnly = wholeListType || part.startsWith('type '); - const name = part.replace(/^type\s+/, '').split(/\s+as\s+/)[0]?.trim() ?? ''; - return [name, typeOnly ? 'type' : 'value']; - }) - .filter(([name]) => name.length > 0); - for (const pattern of [IMPORT_FROM, REEXPORT_FROM]) { - for (const match of source.matchAll(pattern)) { - const list = match[2]; - const subpath = (match[3] ?? '').replace(/^\//, ''); - if (list === undefined) continue; - add(subpath, splitNames(list, match[1] !== undefined)); + const parsed = parseSync('file.ts', source, { lang: 'ts', sourceType: 'module' }); + for (const statement of parsed.module.staticImports) { + const subpath = e2eSubpath(statement.moduleRequest.value); + if (subpath === undefined) continue; + for (const entry of statement.entries) { + if (entry.importName.kind === 'NamespaceObject') add(subpath, [['*', 'value']]); + else if (entry.importName.kind === 'Name' && entry.importName.name !== null) { + add(subpath, [[entry.importName.name, entry.isType ? 'type' : 'value']]); + } + // A default import names no export the check tracks, and a + // side-effect import (`import 'e2e/engine'`) has no entries. } } - for (const match of source.matchAll(NAMESPACE_FROM)) { - add((match[1] ?? '').replace(/^\//, ''), [['*', 'value']]); + // A re-export from an `e2e` entry is an import too: the package depends + // on the export existing at its floor. `export * from` cannot be + // enumerated, so it is recorded as a namespace import. + for (const statement of parsed.module.staticExports) { + for (const entry of statement.entries) { + const moduleRequest = entry.moduleRequest?.value; + if (moduleRequest === undefined) continue; + const subpath = e2eSubpath(moduleRequest); + if (subpath === undefined) continue; + if (entry.importName.kind === 'AllButDefault') add(subpath, [['*', 'value']]); + else if (entry.importName.kind === 'Name' && entry.importName.name !== null) { + add(subpath, [[entry.importName.name, entry.isType ? 'type' : 'value']]); + } + // `export * as ns` exports one name and imports no names. + } } // A dynamic import takes its names the same way, when they are - // destructured; a bare one cannot be enumerated, so it is recorded as - // the namespace name, like a namespace import. The destructured - // statements are blanked before the bare scan, so their import call is - // not also counted as a bare one. - const blanked: [number, number][] = []; - for (const match of source.matchAll(DYNAMIC_IMPORT_NAMES)) { - const list = match[1]; - const subpath = (match[2] ?? '').replace(/^\//, ''); - if (list !== undefined) add(subpath, splitNames(list, false)); - if (match.index !== undefined) blanked.push([match.index, match.index + match[0].length]); - } - let dynamicSource = source; - for (const [start, end] of blanked.toSorted((a, b) => b[0] - a[0])) { - dynamicSource = `${dynamicSource.slice(0, start)}${' '.repeat(end - start)}${dynamicSource.slice(end)}`; - } - for (const match of dynamicSource.matchAll(DYNAMIC_IMPORT)) { - add((match[1] ?? '').replace(/^\//, ''), [['*', 'value']]); - } + // destructured; any other use cannot be enumerated, so it is recorded as + // the namespace name, like a namespace import. + const handled = new Set(); + walkAst(parsed.program, (node) => { + if (node.type !== 'VariableDeclarator') return; + const sourceSpecifier = importCallSource(node.init); + if (sourceSpecifier === undefined) return; + const subpath = e2eSubpath(sourceSpecifier); + if (subpath === undefined) return; + const call = importCall(node.init); + if (call !== undefined) handled.add(call); + const names = patternNames(node.id); + add( + subpath, + names === undefined ? [['*', 'value']] : names.map((name): readonly [string, ImportKind] => [name, 'value']), + ); + }); + walkAst(parsed.program, (node) => { + if (node.type !== 'ImportExpression' || handled.has(node)) return; + const sourceSpecifier = importCallSource(node); + if (sourceSpecifier === undefined) return; + const subpath = e2eSubpath(sourceSpecifier); + if (subpath === undefined) return; + add(subpath, [['*', 'value']]); + }); return found; } @@ -113,6 +186,57 @@ export function addEngineImports(target: Map>, s } } +/** The kind of each name a top-level `export` declaration introduces. Two declarations of one name (interface plus namespace) merge to both. */ +function declarationKinds(program: ReturnType['program']): Map { + const kinds = new Map(); + const set = (name: string, kind: 'type' | 'value' | 'both'): void => { + const existing = kinds.get(name); + if (existing === undefined) kinds.set(name, kind); + else if (existing !== kind) kinds.set(name, 'both'); + }; + const collectBindings = (pattern: unknown): void => { + if (!isRecord(pattern)) return; + if (pattern.type === 'Identifier' && typeof pattern.name === 'string') { + set(pattern.name, 'value'); + return; + } + if (pattern.type === 'ObjectPattern' && Array.isArray(pattern.properties)) { + for (const property of pattern.properties) { + if (!isRecord(property)) continue; + if (property.type === 'RestElement') collectBindings(property.argument); + else if (property.type === 'Property') collectBindings(property.value); + } + return; + } + if (pattern.type === 'ArrayPattern' && Array.isArray(pattern.elements)) { + for (const element of pattern.elements) collectBindings(element); + return; + } + if (pattern.type === 'AssignmentPattern') collectBindings(pattern.left); + else if (pattern.type === 'RestElement') collectBindings(pattern.argument); + }; + for (const statement of program.body) { + const node: unknown = statement; + if (!isRecord(node) || node.type !== 'ExportNamedDeclaration') continue; + const declaration = node.declaration; + if (!isRecord(declaration)) continue; + const id = declaration.id; + const name = isRecord(id) && typeof id.name === 'string' ? id.name : undefined; + if (declaration.type === 'TSInterfaceDeclaration' || declaration.type === 'TSTypeAliasDeclaration') { + if (name !== undefined) set(name, 'type'); + } else if (declaration.type === 'ClassDeclaration' || declaration.type === 'TSEnumDeclaration') { + if (name !== undefined) set(name, 'both'); + } else if (declaration.type === 'FunctionDeclaration' || declaration.type === 'TSDeclareFunction' || declaration.type === 'TSModuleDeclaration') { + if (name !== undefined) set(name, 'value'); + } else if (declaration.type === 'VariableDeclaration' && Array.isArray(declaration.declarations)) { + for (const declarator of declaration.declarations) { + if (isRecord(declarator)) collectBindings(declarator.id); + } + } + } + return kinds; +} + /** The names one file exports, split by kind, and the relative modules its `export *` pulls in. A `type` export or declaration lands in `types`; a class or enum lands in both, since its name is usable as a type; anything else value-like lands in `values`. `export type *` targets are kept apart from value `export *` targets: the former re-export types only. */ function exportedNames(source: string): { values: ReadonlySet; @@ -120,48 +244,42 @@ function exportedNames(source: string): { starModules: readonly string[]; typeStarModules: readonly string[]; } { + const parsed = parseSync('file.ts', source, { lang: 'ts', sourceType: 'module' }); const values = new Set(); const types = new Set(); const starModules: string[] = []; const typeStarModules: string[] = []; - for (const match of source.matchAll(/export\s+(type\s+)?\{([^}]*)\}\s*(?:from\s+['"]([^'"]+)['"])?/gs)) { - const wholeListType = match[1] !== undefined; - const list = match[2]; - if (list === undefined) continue; - for (const part of stripComments(list).split(',')) { - const trimmed = part.trim(); - if (trimmed.length === 0) continue; - const typeOnly = wholeListType || trimmed.startsWith('type '); - const nameMatch = /(\w+)(?:\s+as\s+(\w+))?/.exec(trimmed.replace(/^type\s+/, '')); - if (nameMatch === null) continue; - const name = nameMatch[2] ?? nameMatch[1] ?? ''; - if (name.length === 0) continue; - (typeOnly ? types : values).add(name); - } - } - // `export * as ns` exports only the namespace name, not the module's - // names, so it is recorded as one export and its star chain is not - // followed. - for (const match of source.matchAll(/export\s+(type\s+)?\*\s*(?:as\s+(\w+)\s*)?from\s+['"]([^'"]+)['"]/g)) { - if (match[3] === undefined) continue; - if (match[2] !== undefined) { - (match[1] !== undefined ? types : values).add(match[2]); - } else if (match[1] !== undefined) { - typeStarModules.push(match[3]); - } else { - starModules.push(match[3]); + const declared = declarationKinds(parsed.program); + for (const statement of parsed.module.staticExports) { + for (const entry of statement.entries) { + const moduleRequest = entry.moduleRequest?.value; + if (moduleRequest !== undefined) { + // `export * as ns` exports only the namespace name, not the + // module's names, so it is recorded as one export and its star + // chain is not followed. + if (entry.importName.kind === 'AllButDefault') { + (entry.isType ? typeStarModules : starModules).push(moduleRequest); + } else if (entry.importName.kind === 'All') { + const name = entry.exportName.name; + if (name !== null) (entry.isType ? types : values).add(name); + } else if (entry.importName.kind === 'Name') { + const name = entry.exportName.name; + if (name !== null) (entry.isType ? types : values).add(name); + } + continue; + } + const name = entry.exportName.name; + if (entry.exportName.kind !== 'Name' || name === null) continue; + const kind = declared.get(name); + if (kind === 'type') types.add(name); + else if (kind === 'both') { + values.add(name); + types.add(name); + } else if (kind === 'value') values.add(name); + else if (entry.isType) types.add(name); + else values.add(name); } } - for (const match of source.matchAll(/export\s+(?:declare\s+)?(?:async\s+)?(?:abstract\s+)?(?:const\s+)?(interface|type|class|function|const|let|var|enum)\s+(\w+)/g)) { - const kind = match[1]; - const name = match[2]; - if (kind === undefined || name === undefined) continue; - if (kind === 'interface' || kind === 'type') types.add(name); - else if (kind === 'class' || kind === 'enum') { - values.add(name); - types.add(name); - } else values.add(name); - } return { values, types, starModules, typeStarModules }; } @@ -247,21 +365,21 @@ export function subpathEntryFile(packageJson: string, siblingDir: string, subpat } /** - * The export set of a sibling's subpath at a version, split by kind, read - * through `showFile(tag, path)`. Undefined when the tag, the manifest, or - * the entry cannot be read. + * The export set of a sibling's subpath, split by kind. `readFile` reads a + * repo path (undefined when it has none); the caller binds it to a + * version, for example `(path) => showAtTag(tag, path)` for a tag record + * or a working-tree read. */ export function tagExportsAt( - showFile: (tag: string, path: string) => string | undefined, - tag: string, + readFile: (path: string) => string | undefined, siblingDir: string, subpath: string, ): ExportSets | undefined { - const manifest = showFile(tag, `${siblingDir}/package.json`); + const manifest = readFile(`${siblingDir}/package.json`); if (manifest === undefined) return undefined; const entry = subpathEntryFile(manifest, siblingDir, subpath); if (entry === undefined) return undefined; - return resolveEntryExports((path) => showFile(tag, path), entry); + return resolveEntryExports(readFile, entry); } export interface EngineImportCheck { From 4776b1e9071f1aa80e33c433b1212a9380ff18a9 Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Tue, 10 Nov 2026 22:04:44 +0000 Subject: [PATCH 05/14] fix(release): fail imports from a subpath the floor tag never exported tagExportsAt returned undefined both when a floor version had no tag record and when the tag existed but the sibling did not export the requested subpath, so engineImportProblems reported the second case as unverifiable and pnpm check passed. It now returns empty export sets when the tag record exists but names no such export, so the existing missing-export problem is reported; a missing tag record, an unparsable manifest, or an export entry with no types target stays unverifiable. Regression tests cover the new-subpath case and the still-unverifiable missing-tag case. Signed-off-by: Varshith Puli --- scripts/engine-exports.test.ts | 73 +++++++++++++++++++++++++++++++++- scripts/engine-exports.ts | 26 ++++++++++-- 2 files changed, 95 insertions(+), 4 deletions(-) diff --git a/scripts/engine-exports.test.ts b/scripts/engine-exports.test.ts index 0104719748..5f0936b9db 100644 --- a/scripts/engine-exports.test.ts +++ b/scripts/engine-exports.test.ts @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { describe, it } from 'node:test'; -import { engineImportProblems, engineImports, resolveEntryExports, resolveModule, subpathEntryFile, type EngineImportCheck, type EngineImportMap, type ImportKind } from './engine-exports.ts'; +import { engineImportProblems, engineImports, resolveEntryExports, resolveModule, subpathEntryFile, tagExportsAt, type EngineImportCheck, type EngineImportMap, type ImportKind } from './engine-exports.ts'; describe('engineImports', () => { it('reads named, aliased, and type-only imports from e2e entries', () => { @@ -197,6 +197,77 @@ describe('exportedNames and resolveEntryExports', () => { }); }); +describe('tagExportsAt', () => { + // A tag record for a floor that exports the bare entry and ./engine, + // but no ./agent: a package importing from e2e/agent against this + // floor is a real gap, not an unverifiable floor. + const tagFiles = new Map([ + [ + 'packages/e2e/package.json', + JSON.stringify({ + exports: { + '.': { types: './dist/index.d.ts', default: './dist/index.js' }, + './engine': { types: './dist/engine/index.d.ts', default: './dist/engine/index.js' }, + }, + }), + ], + ['packages/e2e/src/index.ts', `export function test(): void {}\n`], + ['packages/e2e/src/engine/index.ts', `export function stepTimeout(): void {}\n`], + ]); + const readAtTag = (path: string): string | undefined => tagFiles.get(path); + const agentCheck: EngineImportCheck = { + packageName: '@e2e-dev/acp', + packagePath: 'packages/acp/package.json', + sibling: 'e2e', + floor: '0.22.0', + imports: new Map([['agent', new Map([['acp', 'value']])]]), + }; + + it('returns empty sets for a subpath the tag does not export', () => { + const atAgent = tagExportsAt(readAtTag, 'packages/e2e', 'agent'); + assert.notEqual(atAgent, undefined); + assert.deepEqual([...(atAgent?.values ?? [])], []); + assert.deepEqual([...(atAgent?.types ?? [])], []); + }); + + it('fails a named import from a subpath the floor tag does not export', () => { + const { problems, unverifiable, verified } = engineImportProblems( + [agentCheck], + (_sibling, subpath) => tagExportsAt(readAtTag, 'packages/e2e', subpath), + ); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /imports `acp` from e2e\/agent, but e2e@0\.22\.0 does not export it/); + assert.deepEqual(unverifiable, []); + assert.equal(verified, 1); + }); + + it('returns undefined when there is no tag record', () => { + assert.equal(tagExportsAt(() => undefined, 'packages/e2e', 'engine'), undefined); + }); + + it('still reports a floor with no tag record as unverifiable, not a problem', () => { + const { problems, unverifiable, verified } = engineImportProblems([agentCheck], () => undefined); + assert.deepEqual(problems, []); + assert.equal(unverifiable.length, 1); + assert.match(unverifiable[0]!, /cannot be verified, no tag record/); + assert.equal(verified, 0); + }); + + it('returns undefined when the manifest does not parse', () => { + assert.equal(tagExportsAt(() => 'not json', 'packages/e2e', 'agent'), undefined); + }); + + it('returns undefined for an export entry with no types target', () => { + const files = new Map([ + ['packages/e2e/package.json', JSON.stringify({ exports: { './agent': { default: './dist/agent/public.js' } } })], + ]); + assert.equal( + tagExportsAt((path) => files.get(path), 'packages/e2e', 'agent'), + undefined, + ); + }); +}); + describe('engineImportProblems', () => { const check = (floor: string, imports: EngineImportMap): EngineImportCheck => ({ packageName: '@e2e-dev/web', diff --git a/scripts/engine-exports.ts b/scripts/engine-exports.ts index b344fb6f15..79d2d7f22b 100644 --- a/scripts/engine-exports.ts +++ b/scripts/engine-exports.ts @@ -368,7 +368,14 @@ export function subpathEntryFile(packageJson: string, siblingDir: string, subpat * The export set of a sibling's subpath, split by kind. `readFile` reads a * repo path (undefined when it has none); the caller binds it to a * version, for example `(path) => showAtTag(tag, path)` for a tag record - * or a working-tree read. + * or a working-tree read. Undefined when the tag record cannot be read: + * no manifest at that version, a manifest that does not parse, or an + * entry file that cannot be read. Empty sets when the tag record exists + * but the sibling does not export that subpath at that version: every + * named import from it is then a problem, not unverifiable, since the + * floor version never had the subpath to import from. An export entry + * with no types target stays unverifiable, since no entry file can be + * found for it that way. */ export function tagExportsAt( readFile: (path: string) => string | undefined, @@ -378,8 +385,21 @@ export function tagExportsAt( const manifest = readFile(`${siblingDir}/package.json`); if (manifest === undefined) return undefined; const entry = subpathEntryFile(manifest, siblingDir, subpath); - if (entry === undefined) return undefined; - return resolveEntryExports(readFile, entry); + if (entry !== undefined) return resolveEntryExports(readFile, entry); + // No entry file for the subpath. When the manifest names no such + // export, the subpath did not exist at that version, so empty sets, + // not undefined: the caller fails every named import from it instead + // of passing the floor on an unverifiable note. A manifest that does + // not parse, or an export entry with no types target, cannot be read + // this way, so those stay unverifiable. + let parsed: { exports?: Record }; + try { + parsed = JSON.parse(manifest) as { exports?: Record }; + } catch { + return undefined; + } + if (parsed.exports?.[subpath === '' ? '.' : `./${subpath}`] !== undefined) return undefined; + return { values: new Set(), types: new Set() }; } export interface EngineImportCheck { From ef7761de37c4b3840e94b5ca45b1a4788955915e Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Wed, 11 Nov 2026 01:05:52 +0000 Subject: [PATCH 06/14] fix(release): fail namespace and side-effect imports from a subpath the floor tag never exported Namespace, side-effect, and default-only imports from e2e/* now record the subpath even though they name no exports, and engineImportProblems fails the import when the floor tag does not export that subpath. Before this, import * as nope from 'e2e/nope' passed with only a note, and import 'e2e/nope2' was not recorded at all, so a floor at 0.18.0 with import * as r from 'e2e/runner' passed even though ./runner first shipped in 0.19.0. Also addresses the rest of the review: one merge helper for the value-beats-type rule with value-then-type tests for both copies, a test for interface plus namespace counting as both type and value, dedup of the manifest parse, export-key expression, All/Name branches, the type-only and value loops, and the dynamic-import walk, roughly half the JSDoc on the header and the tagExportsAt/engineImportProblems docs, and the nits (dead RestElement check removed, allResolved test, parse errors now throw instead of reading a half-parsed file silently). oxc-parser stays pinned in both the root and packages/e2e: the package uses it at runtime (config/typescript.ts, mcp/code-parse.ts) while the scripts use the root one, and pnpm keeps their node_modules separate. The four maintainer decisions (type-only imports as floor raises, pending-runner exemption, e2e@0.15.0 tag, web/mobile import checks) are untouched. Signed-off-by: Varshith Puli --- scripts/check-helpers.ts | 8 +- scripts/engine-exports.test.ts | 131 +++++++++++++++++- scripts/engine-exports.ts | 242 +++++++++++++++++---------------- 3 files changed, 259 insertions(+), 122 deletions(-) diff --git a/scripts/check-helpers.ts b/scripts/check-helpers.ts index 31b0fcb36f..1a474b8b82 100644 --- a/scripts/check-helpers.ts +++ b/scripts/check-helpers.ts @@ -61,7 +61,13 @@ function sourceFiles(dirPath: string): string[] { export function collectEngineImports(packagePath: string): EngineImportMap { const imports = new Map>(); for (const file of sourceFiles(join(dirname(packagePath), 'src'))) { - addEngineImports(imports, engineImports(readFileSync(file, 'utf8'))); + try { + addEngineImports(imports, engineImports(readFileSync(file, 'utf8'))); + } catch (error) { + // A file that fails to parse names no file in the error from + // engineImports, so say which one it was. + throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`, { cause: error }); + } } return imports; } diff --git a/scripts/engine-exports.test.ts b/scripts/engine-exports.test.ts index 5f0936b9db..bce8156d9b 100644 --- a/scripts/engine-exports.test.ts +++ b/scripts/engine-exports.test.ts @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { describe, it } from 'node:test'; -import { engineImportProblems, engineImports, resolveEntryExports, resolveModule, subpathEntryFile, tagExportsAt, type EngineImportCheck, type EngineImportMap, type ImportKind } from './engine-exports.ts'; +import { addEngineImports, engineImportProblems, engineImports, resolveEntryExports, resolveModule, subpathEntryFile, tagExportsAt, type EngineImportCheck, type EngineImportMap, type ImportKind } from './engine-exports.ts'; describe('engineImports', () => { it('reads named, aliased, and type-only imports from e2e entries', () => { @@ -34,6 +34,25 @@ describe('engineImports', () => { assert.equal(imports.get('engine')?.get('EngineError'), 'value'); }); + it('records a value import of a name over a type import when the value comes first', () => { + const imports = engineImports(`import { EngineError } from 'e2e/engine';\nimport { type EngineError } from 'e2e/engine';\n`); + assert.equal(imports.get('engine')?.get('EngineError'), 'value'); + }); + + it('records a side-effect import as the subpath with no names', () => { + const imports = engineImports(`import 'e2e/nope2';\n`); + assert.deepEqual(imports.get('nope2'), new Map()); + }); + + it('records a default-only import as the subpath with no names', () => { + const imports = engineImports(`import def from 'e2e/nope';\n`); + assert.deepEqual(imports.get('nope'), new Map()); + }); + + it('throws when a source file fails to parse', () => { + assert.throws(() => engineImports('export const = ;\n'), /failed to parse/); + }); + it('ignores comments inside import lists', () => { const imports = engineImports(`import { stepTimeout /* the timeout */, /* leading */ EngineError, type EngineDoctorCheck // trailing\n } from 'e2e/engine';\n`); assert.deepEqual( @@ -92,6 +111,44 @@ describe('engineImports', () => { }); }); +describe('addEngineImports', () => { + it('keeps a value import over a type import in either order', () => { + const typeFirst = new Map>(); + addEngineImports( + typeFirst, + new Map([['engine', new Map([['EngineError', 'type']])]]), + ); + addEngineImports( + typeFirst, + new Map([['engine', new Map([['EngineError', 'value']])]]), + ); + assert.equal(typeFirst.get('engine')?.get('EngineError'), 'value'); + const valueFirst = new Map>(); + addEngineImports( + valueFirst, + new Map([['engine', new Map([['EngineError', 'value']])]]), + ); + addEngineImports( + valueFirst, + new Map([['engine', new Map([['EngineError', 'type']])]]), + ); + assert.equal(valueFirst.get('engine')?.get('EngineError'), 'value'); + }); + + it('merges names across subpaths without dropping any', () => { + const target = new Map>(); + addEngineImports( + target, + new Map([ + ['engine', new Map([['stepTimeout', 'value']])], + ['runner', new Map([['openHost', 'value']])], + ]), + ); + assert.deepEqual([...(target.get('engine')?.keys() ?? [])], ['stepTimeout']); + assert.deepEqual([...(target.get('runner')?.keys() ?? [])], ['openHost']); + }); +}); + describe('exportedNames and resolveEntryExports', () => { it('reads named exports, aliases, declarations, and export-star chains', () => { const files = new Map([ @@ -132,8 +189,7 @@ describe('exportedNames and resolveEntryExports', () => { assert.deepEqual([...(exported?.types ?? [])].toSorted(), []); }); - it('reads async functions and declare const enums as declarations', () => { - const files = new Map([ + it('reads async functions and declare const enums as declarations', () => { const files = new Map([ [ 'src/engine/index.ts', `export async function runCheck(): Promise {}\nexport declare const enum Mode { A = 'a' }\nexport declare function helper(): void;\n`, @@ -144,6 +200,22 @@ describe('exportedNames and resolveEntryExports', () => { assert.deepEqual([...(exported?.types ?? [])].toSorted(), ['Mode']); }); + it('counts an interface plus a namespace of the same name as both a type and a value', () => { + const files = new Map([ + [ + 'src/types.ts', + `export interface Foo { x: string }\nexport namespace Foo { export const bar = 'bar'; }\n`, + ], + ]); + const exported = resolveEntryExports((path) => files.get(path), 'src/types.ts'); + assert.deepEqual([...(exported?.values ?? [])].toSorted(), ['Foo']); + assert.deepEqual([...(exported?.types ?? [])].toSorted(), ['Foo']); + }); + + it('throws when an entry file fails to parse', () => { + assert.throws(() => resolveEntryExports(() => 'export const = ;\n', 'src/engine/index.ts'), /failed to parse/); + }); + it('ignores a commented-out export', () => { const files = new Map([['src/engine/index.ts', `export function kept(): void {}\n// export function gone(): void {}\n`]]); const exported = resolveEntryExports((path) => files.get(path), 'src/engine/index.ts'); @@ -326,13 +398,64 @@ describe('engineImportProblems', () => { it('reports a namespace import as unverifiable', () => { const { problems, unverifiable } = engineImportProblems( [check('0.23.0', new Map([['engine', new Map([['*', 'value']])]]))], - () => exported([]), + () => exported(['stepTimeout']), ); assert.deepEqual(problems, []); assert.equal(unverifiable.length, 1); assert.match(unverifiable[0]!, /imported as a namespace/); }); + it('fails a namespace import from a subpath the floor tag does not export', () => { + const { problems, unverifiable } = engineImportProblems( + [check('0.23.0', new Map([['nope', new Map([['*', 'value']])]]))], + () => exported([]), + ); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /imports from e2e\/nope, but e2e@0\.23\.0 does not export that subpath/); + assert.deepEqual(unverifiable, []); + }); + + it('fails a side-effect import from a subpath the floor tag does not export', () => { + const { problems, unverifiable } = engineImportProblems( + [check('0.23.0', new Map([['nope2', new Map()]]))], + () => exported([]), + ); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /imports from e2e\/nope2, but e2e@0\.23\.0 does not export that subpath/); + assert.deepEqual(unverifiable, []); + }); + + it('passes a side-effect import from a subpath the floor tag exports', () => { + const { problems, unverifiable, verified } = engineImportProblems( + [check('0.23.0', new Map([['engine', new Map()]]))], + () => exported(['stepTimeout']), + ); + assert.deepEqual(problems, []); + assert.deepEqual(unverifiable, []); + assert.equal(verified, 1); + }); + + it('does not count a check as verified when one of its subpaths has no tag record', () => { + const twoSubpaths: EngineImportCheck = { + packageName: '@e2e-dev/web', + packagePath: 'packages/web/package.json', + sibling: 'e2e', + floor: '0.23.0', + imports: new Map([ + ['engine', new Map([['stepTimeout', 'value']])], + ['agent', new Map([['acp', 'value']])], + ]), + }; + const { problems, unverifiable, verified } = engineImportProblems( + [twoSubpaths], + (_sibling, subpath) => (subpath === 'engine' ? exported(['stepTimeout']) : undefined), + ); + assert.deepEqual(problems, []); + assert.equal(unverifiable.length, 1); + assert.match(unverifiable[0]!, /cannot be verified, no tag record/); + assert.equal(verified, 0); + }); + it('still validates named imports beside a namespace import', () => { const { problems, unverifiable } = engineImportProblems( [check('0.23.0', new Map([['engine', new Map([['*', 'value'], ['stepTimeout', 'value']])]]))], diff --git a/scripts/engine-exports.ts b/scripts/engine-exports.ts index 79d2d7f22b..67e0cf2d0c 100644 --- a/scripts/engine-exports.ts +++ b/scripts/engine-exports.ts @@ -1,35 +1,22 @@ /** * Rule (c): an engine that starts importing a new `e2e/engine` export - * counts as raising the floor. This module verifies it: every named import - * a package takes from `e2e` or an `e2e/*` entry must be exported by `e2e` - * at the version the package's peer floor names. + * counts as raising the floor. This module verifies it: every import a + * package takes from `e2e` or an `e2e/*` entry must be exported by `e2e` + * at the version the package's peer floor names, including namespace, + * side-effect, and default-only imports, which record the subpath even + * though they name no exports. * - * Imports and exports come from oxc-parser's module info - * (`parseSync(...).module`), not from pattern matching: comments and JSDoc - * examples never count as imports or exports, destructured declarations - * are read as the names they bind, and names nested inside a namespace - * never leak out as top-level exports. A declaration's kind comes from the - * parsed declaration itself, since module info alone cannot tell a - * `declare` function from a type: interfaces and type aliases are types - * only, classes and enums are both, everything else exported is a value. + * Imports and exports come from oxc-parser's module info, not pattern + * matching, so comments and JSDoc examples never count. Declaration + * kinds come from the parsed declaration: interfaces and type aliases + * are types only, classes and enums are both, the rest are values. * - * The export set at a version comes from the `e2e@` tag: the entry - * file is read off the sibling's `package.json` `exports` at that tag (its - * `types` target, mapped from `dist/` to `src/`), and `export *` chains are - * followed. A floor whose tag does not exist cannot be verified this way; - * that floor is reported as unverifiable, not a failure, and the - * released-floor rule in `peer-ranges.ts` still applies to it. Imports and - * exports are tracked by kind, `value` or `type`: a value import needs a - * value export (a name that only reaches the entry through `export type *` - * does not satisfy one), and a type import is satisfied by either kind. - * Type-only imports count the same as value imports: the package's - * published `.d.ts` names those types, so a consumer on the floor runner - * fails typecheck when the floor version lacks them. - * - * Only imports from `e2e` itself are checked. An integration's imports - * from another engine (`@e2e-dev/web`, `@e2e-dev/mobile`) are the same - * shape but a different sibling; extending this to engine peers is a - * follow-up, not part of this change. + * The export set at a version comes from the `e2e@` tag (the + * entry file off the sibling's `package.json` `exports`, `export *` + * chains followed). A floor with no tag is unverifiable, not a failure. + * A value import needs a value export; a type import is satisfied by + * either kind. Type-only imports count as value imports, since the + * package's published `.d.ts` names those types. */ import { parseSync } from 'oxc-parser'; @@ -53,6 +40,28 @@ function isRecord(value: unknown): value is AstNode { return typeof value === 'object' && value !== null; } +/** Parses `source` as a TypeScript module, throwing when oxc-parser reports errors instead of reading a half-parsed file silently. */ +function parseModule(source: string): ReturnType { + const parsed = parseSync('file.ts', source, { lang: 'ts', sourceType: 'module' }); + if (parsed.errors.length > 0) { + throw new Error(`failed to parse TypeScript source: ${parsed.errors[0]?.message ?? 'unknown parse error'}`); + } + return parsed; +} + +/** The `exports` key for a subpath (`'.'` for the bare entry). */ +function exportKey(subpath: string): string { + return subpath === '' ? '.' : `./${subpath}`; +} + +/** Records `names` into `target`, a value import of a name winning over a type import of the same name. */ +function mergeImportKinds(target: Map, names: Iterable): void { + for (const [name, kind] of names) { + const existing = target.get(name); + if (existing === undefined || kind === 'value') target.set(name, kind); + } +} + /** The `import(...)` call in `node`, unwrapping `await` and parentheses; undefined when `node` is not one. */ function importCall(node: unknown): AstNode | undefined { let current: unknown = node; @@ -79,7 +88,6 @@ function patternNames(pattern: unknown): string[] | undefined { const names: string[] = []; for (const property of pattern.properties) { if (!isRecord(property)) return undefined; - if (property.type === 'RestElement') return undefined; if (property.type !== 'Property') return undefined; const key = property.key; if (!isRecord(key) || key.type !== 'Identifier' || typeof key.name !== 'string') return undefined; @@ -99,7 +107,7 @@ function walkAst(value: unknown, visit: (node: AstNode) => void): void { for (const child of Object.values(value)) walkAst(child, visit); } -/** The named imports from `e2e` and its subpaths in one source file, keyed by subpath (`''` is the bare `e2e` entry). A namespace import is recorded as the name `'*'`, which the check cannot enumerate. */ +/** The named imports from `e2e` and its subpaths in one source file, keyed by subpath (`''` is the bare `e2e` entry). A namespace import is recorded as the name `'*'`, which the check cannot enumerate; a side-effect or default-only import records the subpath with no names, so the check still verifies the subpath exists at the floor. */ export function engineImports(source: string): EngineImportMap { const found = new Map>(); const add = (subpath: string, names: readonly (readonly [string, ImportKind])[]): void => { @@ -108,22 +116,22 @@ export function engineImports(source: string): EngineImportMap { map = new Map(); found.set(subpath, map); } - for (const [name, kind] of names) { - const existing = map.get(name); - if (existing === undefined || kind === 'value') map.set(name, kind); - } + mergeImportKinds(map, names); }; - const parsed = parseSync('file.ts', source, { lang: 'ts', sourceType: 'module' }); + const parsed = parseModule(source); for (const statement of parsed.module.staticImports) { const subpath = e2eSubpath(statement.moduleRequest.value); if (subpath === undefined) continue; + // Record the subpath even when the import names nothing: a + // side-effect import (`import 'e2e/engine'`) has no entries, and a + // default-only import names no export the check tracks, but both + // still need the subpath to exist at the floor. + add(subpath, []); for (const entry of statement.entries) { if (entry.importName.kind === 'NamespaceObject') add(subpath, [['*', 'value']]); else if (entry.importName.kind === 'Name' && entry.importName.name !== null) { add(subpath, [[entry.importName.name, entry.isType ? 'type' : 'value']]); } - // A default import names no export the check tracks, and a - // side-effect import (`import 'e2e/engine'`) has no entries. } } // A re-export from an `e2e` entry is an import too: the package depends @@ -135,32 +143,36 @@ export function engineImports(source: string): EngineImportMap { if (moduleRequest === undefined) continue; const subpath = e2eSubpath(moduleRequest); if (subpath === undefined) continue; + add(subpath, []); if (entry.importName.kind === 'AllButDefault') add(subpath, [['*', 'value']]); else if (entry.importName.kind === 'Name' && entry.importName.name !== null) { add(subpath, [[entry.importName.name, entry.isType ? 'type' : 'value']]); } - // `export * as ns` exports one name and imports no names. + // `export * as ns` exports one name and imports no names, but the + // subpath above is still recorded, since the module must exist. } } // A dynamic import takes its names the same way, when they are // destructured; any other use cannot be enumerated, so it is recorded as - // the namespace name, like a namespace import. + // the namespace name, like a namespace import. One walk handles both: + // a declarator is visited before its `import(...)` child, so the child + // is skipped once the declarator has recorded it. const handled = new Set(); walkAst(parsed.program, (node) => { - if (node.type !== 'VariableDeclarator') return; - const sourceSpecifier = importCallSource(node.init); - if (sourceSpecifier === undefined) return; - const subpath = e2eSubpath(sourceSpecifier); - if (subpath === undefined) return; - const call = importCall(node.init); - if (call !== undefined) handled.add(call); - const names = patternNames(node.id); - add( - subpath, - names === undefined ? [['*', 'value']] : names.map((name): readonly [string, ImportKind] => [name, 'value']), - ); - }); - walkAst(parsed.program, (node) => { + if (node.type === 'VariableDeclarator') { + const sourceSpecifier = importCallSource(node.init); + if (sourceSpecifier === undefined) return; + const subpath = e2eSubpath(sourceSpecifier); + if (subpath === undefined) return; + const call = importCall(node.init); + if (call !== undefined) handled.add(call); + const names = patternNames(node.id); + add( + subpath, + names === undefined ? [['*', 'value']] : names.map((name): readonly [string, ImportKind] => [name, 'value']), + ); + return; + } if (node.type !== 'ImportExpression' || handled.has(node)) return; const sourceSpecifier = importCallSource(node); if (sourceSpecifier === undefined) return; @@ -179,10 +191,7 @@ export function addEngineImports(target: Map>, s map = new Map(); target.set(subpath, map); } - for (const [name, kind] of names) { - const existing = map.get(name); - if (existing === undefined || kind === 'value') map.set(name, kind); - } + mergeImportKinds(map, names); } } @@ -244,7 +253,7 @@ function exportedNames(source: string): { starModules: readonly string[]; typeStarModules: readonly string[]; } { - const parsed = parseSync('file.ts', source, { lang: 'ts', sourceType: 'module' }); + const parsed = parseModule(source); const values = new Set(); const types = new Set(); const starModules: string[] = []; @@ -259,10 +268,7 @@ function exportedNames(source: string): { // chain is not followed. if (entry.importName.kind === 'AllButDefault') { (entry.isType ? typeStarModules : starModules).push(moduleRequest); - } else if (entry.importName.kind === 'All') { - const name = entry.exportName.name; - if (name !== null) (entry.isType ? types : values).add(name); - } else if (entry.importName.kind === 'Name') { + } else if (entry.importName.kind === 'All' || entry.importName.kind === 'Name') { const name = entry.exportName.name; if (name !== null) (entry.isType ? types : values).add(name); } @@ -323,24 +329,18 @@ export function resolveEntryExports(readFile: (path: string) => string | undefin const source = readFile(file); if (source === undefined) return undefined; const exported = exportedNames(source); - if (typeOnly) { - for (const name of exported.types) types.add(name); - for (const specifier of [...exported.starModules, ...exported.typeStarModules]) { - const target = resolveModule(file, specifier); - if (target !== undefined) queue.push([target, true]); - } - } else { + // A file reached through `export type *` contributes its types only, + // and a value star reached that way is followed as type-only too. + for (const name of exported.types) types.add(name); + if (!typeOnly) { for (const name of exported.values) values.add(name); - for (const name of exported.types) types.add(name); - for (const specifier of exported.starModules) { - const target = resolveModule(file, specifier); - if (target !== undefined) queue.push([target, false]); - } - for (const specifier of exported.typeStarModules) { - const target = resolveModule(file, specifier); - if (target !== undefined) queue.push([target, true]); - } } + const enqueue = (specifier: string, asType: boolean): void => { + const target = resolveModule(file, specifier); + if (target !== undefined) queue.push([target, asType]); + }; + for (const specifier of exported.starModules) enqueue(specifier, typeOnly); + for (const specifier of exported.typeStarModules) enqueue(specifier, true); } return { values, types }; } @@ -352,30 +352,31 @@ export function resolveEntryExports(readFile: (path: string) => string | undefin * package has no such export, or its manifest does not parse. */ export function subpathEntryFile(packageJson: string, siblingDir: string, subpath: string): string | undefined { - let parsed: { exports?: Record }; + let exports: Record | undefined; try { - parsed = JSON.parse(packageJson) as { exports?: Record }; + exports = (JSON.parse(packageJson) as { exports?: Record }).exports; } catch { return undefined; } - const entry = parsed.exports?.[subpath === '' ? '.' : `./${subpath}`]; - const types = typeof entry === 'string' ? entry : entry?.types; - if (typeof types !== 'string') return undefined; + return entryFileFromExports(exports, siblingDir, subpath); +} + +/** The entry file for a subpath from an already-parsed `exports` map. */ +function entryFileFromExports(exports: Record | undefined, siblingDir: string, subpath: string): string | undefined { + const entry = exports?.[exportKey(subpath)]; + const types = typeof entry === 'string' ? entry : isRecord(entry) && typeof entry.types === 'string' ? entry.types : undefined; + if (types === undefined) return undefined; return `${siblingDir}/src/${types.replace(/^\.\/dist\//, '').replace(/\.d\.ts$/, '.ts')}`; } /** - * The export set of a sibling's subpath, split by kind. `readFile` reads a - * repo path (undefined when it has none); the caller binds it to a - * version, for example `(path) => showAtTag(tag, path)` for a tag record - * or a working-tree read. Undefined when the tag record cannot be read: - * no manifest at that version, a manifest that does not parse, or an - * entry file that cannot be read. Empty sets when the tag record exists - * but the sibling does not export that subpath at that version: every - * named import from it is then a problem, not unverifiable, since the - * floor version never had the subpath to import from. An export entry - * with no types target stays unverifiable, since no entry file can be - * found for it that way. + * The export set of a sibling's subpath at a version, split by kind. + * `readFile` reads a repo path at that version. Undefined when the tag + * record cannot be read (no manifest, unparseable manifest, unreadable + * entry). Empty sets when the record exists but the sibling does not + * export that subpath there: every import from it is then a problem, + * not unverifiable. An export entry with no types target stays + * unverifiable, since no entry file can be found for it that way. */ export function tagExportsAt( readFile: (path: string) => string | undefined, @@ -384,21 +385,15 @@ export function tagExportsAt( ): ExportSets | undefined { const manifest = readFile(`${siblingDir}/package.json`); if (manifest === undefined) return undefined; - const entry = subpathEntryFile(manifest, siblingDir, subpath); - if (entry !== undefined) return resolveEntryExports(readFile, entry); - // No entry file for the subpath. When the manifest names no such - // export, the subpath did not exist at that version, so empty sets, - // not undefined: the caller fails every named import from it instead - // of passing the floor on an unverifiable note. A manifest that does - // not parse, or an export entry with no types target, cannot be read - // this way, so those stay unverifiable. - let parsed: { exports?: Record }; + let exports: Record | undefined; try { - parsed = JSON.parse(manifest) as { exports?: Record }; + exports = (JSON.parse(manifest) as { exports?: Record }).exports; } catch { return undefined; } - if (parsed.exports?.[subpath === '' ? '.' : `./${subpath}`] !== undefined) return undefined; + const entry = entryFileFromExports(exports, siblingDir, subpath); + if (entry !== undefined) return resolveEntryExports(readFile, entry); + if (exports?.[exportKey(subpath)] !== undefined) return undefined; return { values: new Set(), types: new Set() }; } @@ -412,17 +407,12 @@ export interface EngineImportCheck { /** * Every import in `checks` the sibling does not export at the floor - * version, plus the floors that could not be verified. `exportsAt` - * returns the sibling's export set for a subpath at a version, or - * undefined when that version has no tag record to read; an unverifiable - * floor is a note, not a problem, since the released-floor rule still - * applies to it. A namespace import is unverifiable for the same reason: - * its names cannot be enumerated. A namespace import does not excuse the - * names imported beside it from the same subpath: those are still - * validated. A value import needs a value export; a type import is - * satisfied by a value or a type export. `verified` counts the checks - * whose named imports were all checked against a tag record: a check no - * tag record covers is not verified, even when it reports no problem. + * version, plus the floors that could not be verified. A namespace + * import is unverifiable, since its names cannot be enumerated, unless + * the floor tag does not export the subpath at all, which is a problem. + * A side-effect or default-only import is verified when the tag exports + * the subpath. `verified` counts the checks whose imports were all + * checked against a tag record. */ export function engineImportProblems( checks: readonly EngineImportCheck[], @@ -437,10 +427,28 @@ export function engineImportProblems( for (const [subpath, names] of check.imports) { const label = subpath === '' ? check.sibling : `${check.sibling}/${subpath}`; const named = [...names].filter(([name]) => name !== '*'); + if (named.length === 0) { + // No names to check, but the subpath itself must exist at the + // floor: a namespace, side-effect, or default-only import from a + // subpath the floor tag never exported fails at runtime. + const exported = exportsAt(check.sibling, subpath, check.floor); + if (exported === undefined) { + unverifiable.push(`${check.packagePath}: ${label} at ${check.sibling}@${check.floor} cannot be verified, no tag record for that version; the floor must still name a released version`); + allResolved = false; + } else if (exported.values.size === 0 && exported.types.size === 0) { + problems.push( + `${check.packagePath}: imports from ${label}, but ${check.sibling}@${check.floor} does not export that subpath; a new ${label} import counts as raising the floor, so raise the ${check.sibling} peer floor to the first version that exports it (as a **Breaking:** minor when it passes a runner minor the previous range accepted)`, + ); + } else if (names.has('*')) { + unverifiable.push(`${check.packagePath}: ${label} is imported as a namespace, so its names cannot be verified against ${check.sibling}@${check.floor}`); + } else { + checked = true; + } + continue; + } if (names.has('*')) { unverifiable.push(`${check.packagePath}: ${label} is imported as a namespace, so its names cannot be verified against ${check.sibling}@${check.floor}`); } - if (named.length === 0) continue; const exported = exportsAt(check.sibling, subpath, check.floor); if (exported === undefined) { unverifiable.push(`${check.packagePath}: ${label} at ${check.sibling}@${check.floor} cannot be verified, no tag record for that version; the floor must still name a released version`); From 9c67b3fd7aee231de98ade46c6fccfb8cfe2059f Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Wed, 11 Nov 2026 04:00:15 +0000 Subject: [PATCH 07/14] fix(release): validate the default binding in the peer-floor check A default import (import def from 'e2e/engine') was recorded with no names, so it passed whenever the floor exported any other name from that subpath, even with no default export. Record it as the `default` binding (value, or type for import type), and record `export default ...` as a `default` export on the entry side, so a floor without one now fails the check. Side-effect imports are unchanged: subpath existence only. Addresses cubic review 5852130459 on PR #1661. Signed-off-by: Varshith Puli --- scripts/engine-exports.test.ts | 82 +++++++++++++++++++++++++++++++++- scripts/engine-exports.ts | 27 ++++++----- 2 files changed, 97 insertions(+), 12 deletions(-) diff --git a/scripts/engine-exports.test.ts b/scripts/engine-exports.test.ts index bce8156d9b..3f0d3165fa 100644 --- a/scripts/engine-exports.test.ts +++ b/scripts/engine-exports.test.ts @@ -44,9 +44,30 @@ describe('engineImports', () => { assert.deepEqual(imports.get('nope2'), new Map()); }); - it('records a default-only import as the subpath with no names', () => { + it('records a default-only import as the default binding', () => { const imports = engineImports(`import def from 'e2e/nope';\n`); - assert.deepEqual(imports.get('nope'), new Map()); + assert.deepEqual(imports.get('nope'), new Map([['default', 'value']])); + }); + + it('records a default import beside named imports', () => { + const imports = engineImports(`import def, { stepTimeout } from 'e2e/engine';\n`); + assert.deepEqual( + imports.get('engine'), + new Map([ + ['default', 'value'], + ['stepTimeout', 'value'], + ]), + ); + }); + + it('records a type-only default import as a type', () => { + const imports = engineImports(`import type def from 'e2e/engine';\n`); + assert.deepEqual(imports.get('engine'), new Map([['default', 'type']])); + }); + + it('records a default imported by name', () => { + const imports = engineImports(`import { default as def } from 'e2e/engine';\n`); + assert.deepEqual(imports.get('engine'), new Map([['default', 'value']])); }); it('throws when a source file fails to parse', () => { @@ -189,6 +210,24 @@ describe('exportedNames and resolveEntryExports', () => { assert.deepEqual([...(exported?.types ?? [])].toSorted(), []); }); + it('reads a default export as the default name', () => { + const files = new Map([ + ['src/engine/index.ts', `export default function makeEngine(): void {}\nexport function stepTimeout(): void {}\n`], + ]); + const exported = resolveEntryExports((path) => files.get(path), 'src/engine/index.ts'); + assert.deepEqual([...(exported?.values ?? [])].toSorted(), ['default', 'stepTimeout']); + assert.deepEqual([...(exported?.types ?? [])].toSorted(), []); + }); + + it('reads a name exported as default', () => { + const files = new Map([ + ['src/engine/index.ts', `function makeEngine(): void {}\nexport { makeEngine as default };\n`], + ]); + const exported = resolveEntryExports((path) => files.get(path), 'src/engine/index.ts'); + assert.deepEqual([...(exported?.values ?? [])].toSorted(), ['default']); + assert.deepEqual([...(exported?.types ?? [])].toSorted(), []); + }); + it('reads async functions and declare const enums as declarations', () => { const files = new Map([ [ 'src/engine/index.ts', @@ -435,6 +474,25 @@ describe('engineImportProblems', () => { assert.equal(verified, 1); }); + it('fails a default import when the floor exports other names but no default', () => { + const { problems } = engineImportProblems( + [check('0.23.0', named([['default', 'value']]))], + () => exported(['stepTimeout']), + ); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /imports `default` from e2e\/engine, but e2e@0\.23\.0 does not export it/); + }); + + it('passes a default import when the floor exports a default', () => { + const { problems, unverifiable, verified } = engineImportProblems( + [check('0.23.0', named([['default', 'value']]))], + () => exported(['default', 'stepTimeout']), + ); + assert.deepEqual(problems, []); + assert.deepEqual(unverifiable, []); + assert.equal(verified, 1); + }); + it('does not count a check as verified when one of its subpaths has no tag record', () => { const twoSubpaths: EngineImportCheck = { packageName: '@e2e-dev/web', @@ -546,6 +604,26 @@ describe('floor export checks with in-memory fixtures', () => { assert.deepEqual(laterProblems, []); }); + it('fails a default import against an entry with no default export, and passes once one is added', () => { + const withoutDefault = new Map([ + ['src/engine/index.ts', `export function stepTimeout(): void {}\n`], + ]); + const withDefault = new Map([ + ['src/engine/index.ts', `export default function makeEngine(): void {}\nexport function stepTimeout(): void {}\n`], + ]); + const atWithout = resolveEntryExports((path) => withoutDefault.get(path), 'src/engine/index.ts'); + const atWith = resolveEntryExports((path) => withDefault.get(path), 'src/engine/index.ts'); + assert.equal(atWithout?.values.has('default'), false); + assert.equal(atWith?.values.has('default'), true); + const imports: EngineImportMap = new Map([['engine', new Map([['default', 'value']])]]); + const check = (floor: string): EngineImportCheck => ({ packageName: '@e2e-dev/web', packagePath: 'packages/web/package.json', sibling: 'e2e', floor, imports }); + const { problems: withoutProblems } = engineImportProblems([check('0.22.0')], () => atWithout); + assert.equal(withoutProblems.length, 1); + assert.match(withoutProblems[0]!, /imports `default` from e2e\/engine/); + const { problems: withProblems } = engineImportProblems([check('0.23.0')], () => atWith); + assert.deepEqual(withProblems, []); + }); + it('does not count a type-star re-export as a value export in fixture entries', () => { const files = new Map([ ['src/engine/index.ts', `export type * from './contract.ts';\nexport { parseKey } from './contract.ts';\n`], diff --git a/scripts/engine-exports.ts b/scripts/engine-exports.ts index 67e0cf2d0c..63147c03fd 100644 --- a/scripts/engine-exports.ts +++ b/scripts/engine-exports.ts @@ -2,9 +2,9 @@ * Rule (c): an engine that starts importing a new `e2e/engine` export * counts as raising the floor. This module verifies it: every import a * package takes from `e2e` or an `e2e/*` entry must be exported by `e2e` - * at the version the package's peer floor names, including namespace, - * side-effect, and default-only imports, which record the subpath even - * though they name no exports. + * at the version the package's peer floor names, including namespace and + * side-effect imports, which record the subpath even though they name no + * exports, and default imports, which record the `default` binding. * * Imports and exports come from oxc-parser's module info, not pattern * matching, so comments and JSDoc examples never count. Declaration @@ -107,7 +107,7 @@ function walkAst(value: unknown, visit: (node: AstNode) => void): void { for (const child of Object.values(value)) walkAst(child, visit); } -/** The named imports from `e2e` and its subpaths in one source file, keyed by subpath (`''` is the bare `e2e` entry). A namespace import is recorded as the name `'*'`, which the check cannot enumerate; a side-effect or default-only import records the subpath with no names, so the check still verifies the subpath exists at the floor. */ +/** The named imports from `e2e` and its subpaths in one source file, keyed by subpath (`''` is the bare `e2e` entry). A namespace import is recorded as the name `'*'`, which the check cannot enumerate; a side-effect import records the subpath with no names, so the check still verifies the subpath exists at the floor; a default import records the name `default`, so a floor without one fails the check. */ export function engineImports(source: string): EngineImportMap { const found = new Map>(); const add = (subpath: string, names: readonly (readonly [string, ImportKind])[]): void => { @@ -123,12 +123,12 @@ export function engineImports(source: string): EngineImportMap { const subpath = e2eSubpath(statement.moduleRequest.value); if (subpath === undefined) continue; // Record the subpath even when the import names nothing: a - // side-effect import (`import 'e2e/engine'`) has no entries, and a - // default-only import names no export the check tracks, but both - // still need the subpath to exist at the floor. + // side-effect import (`import 'e2e/engine'`) has no entries, but it + // still needs the subpath to exist at the floor. add(subpath, []); for (const entry of statement.entries) { if (entry.importName.kind === 'NamespaceObject') add(subpath, [['*', 'value']]); + else if (entry.importName.kind === 'Default') add(subpath, [['default', entry.isType ? 'type' : 'value']]); else if (entry.importName.kind === 'Name' && entry.importName.name !== null) { add(subpath, [[entry.importName.name, entry.isType ? 'type' : 'value']]); } @@ -275,6 +275,12 @@ function exportedNames(source: string): { continue; } const name = entry.exportName.name; + if (entry.exportName.kind === 'Default') { + // `export default ...` exports the name `default`: a default + // import of this entry is satisfied only by one. + (entry.isType ? types : values).add('default'); + continue; + } if (entry.exportName.kind !== 'Name' || name === null) continue; const kind = declared.get(name); if (kind === 'type') types.add(name); @@ -410,8 +416,9 @@ export interface EngineImportCheck { * version, plus the floors that could not be verified. A namespace * import is unverifiable, since its names cannot be enumerated, unless * the floor tag does not export the subpath at all, which is a problem. - * A side-effect or default-only import is verified when the tag exports - * the subpath. `verified` counts the checks whose imports were all + * A side-effect import is verified when the tag exports the subpath; a + * default import is checked against the `default` export like any other + * name. `verified` counts the checks whose imports were all * checked against a tag record. */ export function engineImportProblems( @@ -429,7 +436,7 @@ export function engineImportProblems( const named = [...names].filter(([name]) => name !== '*'); if (named.length === 0) { // No names to check, but the subpath itself must exist at the - // floor: a namespace, side-effect, or default-only import from a + // floor: a namespace or side-effect import from a // subpath the floor tag never exported fails at runtime. const exported = exportsAt(check.sibling, subpath, check.floor); if (exported === undefined) { From 70f1adb20c95cbb296dd3935228bea928ae7ae54 Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Wed, 11 Nov 2026 07:07:25 +0000 Subject: [PATCH 08/14] fix(release): distinguish a missing subpath from an entry that exports nothing tagExportsAt returned empty export sets both when the tag never exported a subpath and when its entry exists but exports nothing, so a side-effect or namespace import of an empty entry (import './register.ts'; export {};) was wrongly reported as "does not export that subpath". Return the distinct 'missing' state for the never-exported case and empty sets only for an entry that exports nothing, and collapse engineImportProblems to one exportsAt call per subpath: undefined is a note, missing is a problem, '*' is a note, then the named check, where an empty list is trivially fine. A named import from a never-exported subpath now gets the subpath message instead of the per-name one, and a check with one verified subpath plus one unverifiable side-effect import no longer counts as verified. Also cover the add(subpath, []) in the re-export loop: export * as ns from 'e2e/missing' only fails because of it. Add tests for the parse error file name, a value export star reached through a type star, and the shared mergeInto for the add closure and addEngineImports. Addresses review 5853794400 on PR #1661. Signed-off-by: Varshith Puli --- scripts/check-helpers.test.ts | 28 +++++++++++ scripts/check-peer-ranges.ts | 6 +-- scripts/engine-exports.test.ts | 85 +++++++++++++++++++++++++++++--- scripts/engine-exports.ts | 89 ++++++++++++++++------------------ 4 files changed, 151 insertions(+), 57 deletions(-) create mode 100644 scripts/check-helpers.test.ts diff --git a/scripts/check-helpers.test.ts b/scripts/check-helpers.test.ts new file mode 100644 index 0000000000..bae7679cb1 --- /dev/null +++ b/scripts/check-helpers.test.ts @@ -0,0 +1,28 @@ +import assert from 'node:assert/strict'; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { describe, it } from 'node:test'; +import { collectEngineImports } from './check-helpers.ts'; + +describe('collectEngineImports', () => { + it('names the file that fails to parse', () => { + const dir = mkdtempSync(join(tmpdir(), 'e2e-check-helpers-')); + try { + mkdirSync(join(dir, 'src'), { recursive: true }); + writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'pkg' })); + writeFileSync(join(dir, 'src', 'broken.ts'), 'export const = ;\n'); + assert.throws( + () => collectEngineImports(join(dir, 'package.json')), + (error: unknown) => { + assert.ok(error instanceof Error); + assert.match(error.message, /broken\.ts/); + assert.match(error.message, /failed to parse/); + return true; + }, + ); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); +}); diff --git a/scripts/check-peer-ranges.ts b/scripts/check-peer-ranges.ts index 02880891a9..5fcd7aed92 100644 --- a/scripts/check-peer-ranges.ts +++ b/scripts/check-peer-ranges.ts @@ -25,7 +25,7 @@ import { readFileSync } from 'node:fs'; import { dirname, join, relative } from 'node:path'; import { collectEngineImports, listTags, pendingChangesets, readChangelog, showAtTag } from './check-helpers.ts'; import { nextVersionAfterBump, pendingBumps } from './changeset-bumps.ts'; -import { engineImportProblems, tagExportsAt, type EngineImportCheck, type ExportSets } from './engine-exports.ts'; +import { engineImportProblems, tagExportsAt, type EngineImportCheck, type TagExports } from './engine-exports.ts'; import { peerFloor, peerRangeProblems } from './peer-ranges.ts'; import { REPO_ROOT, publicPackages, siblingPeers } from './public-packages.ts'; @@ -62,7 +62,7 @@ if (listTags('e2e@*').length === 0) { // Rule (c): every named import from `e2e/*` must be exported by `e2e` at // the package's peer floor, read off the `e2e@` tag. const siblingDirs = new Map(packages.map(({ manifest, path }) => [manifest.name, relative(REPO_ROOT, dirname(path))])); -const exportsCache = new Map(); +const exportsCache = new Map(); /** Reads `path` from the working tree, undefined when it cannot be read. */ function showWorkingTree(path: string): string | undefined { @@ -73,7 +73,7 @@ function showWorkingTree(path: string): string | undefined { } } -const exportsAt = (sibling: string, subpath: string, version: string): ExportSets | undefined => { +const exportsAt = (sibling: string, subpath: string, version: string): TagExports | undefined => { const key = `${sibling}@${version}:${subpath}`; if (exportsCache.has(key)) return exportsCache.get(key); const siblingDir = siblingDirs.get(sibling); diff --git a/scripts/engine-exports.test.ts b/scripts/engine-exports.test.ts index 3f0d3165fa..564e3b95bb 100644 --- a/scripts/engine-exports.test.ts +++ b/scripts/engine-exports.test.ts @@ -109,6 +109,11 @@ describe('engineImports', () => { assert.deepEqual(imports.get('engine'), new Map([['*', 'value']])); }); + it('records an export-star-as re-export as the subpath with no names', () => { + const imports = engineImports(`export * as ns from 'e2e/missing';\n`); + assert.deepEqual(imports.get('missing'), new Map()); + }); + it('reads names destructured from a dynamic import', () => { // A `type` modifier is not valid syntax in a destructuring pattern, so // destructured names are values. @@ -200,6 +205,17 @@ describe('exportedNames and resolveEntryExports', () => { assert.deepEqual([...(exported?.types ?? [])].toSorted(), ['KeyModifier']); }); + it('does not count a value export-star reached through a type-star as a value export', () => { + const files = new Map([ + ['src/engine/index.ts', `export type * from './mid.ts';\n`], + ['src/engine/mid.ts', `export * from './leaf.ts';\n`], + ['src/engine/leaf.ts', `export function stepTimeout(): void {}\nexport type NodeRef = string;\n`], + ]); + const exported = resolveEntryExports((path) => files.get(path), 'src/engine/index.ts'); + assert.deepEqual([...(exported?.values ?? [])], []); + assert.deepEqual([...(exported?.types ?? [])].toSorted(), ['NodeRef']); + }); + it('exports only the namespace name for export star as', () => { const files = new Map([ ['src/engine/index.ts', `export * as engine from './engine.ts';\n`], @@ -319,11 +335,14 @@ describe('tagExportsAt', () => { exports: { '.': { types: './dist/index.d.ts', default: './dist/index.js' }, './engine': { types: './dist/engine/index.d.ts', default: './dist/engine/index.js' }, + './setup': { types: './dist/setup/index.d.ts', default: './dist/setup/index.js' }, }, }), ], ['packages/e2e/src/index.ts', `export function test(): void {}\n`], ['packages/e2e/src/engine/index.ts', `export function stepTimeout(): void {}\n`], + ['packages/e2e/src/setup/index.ts', `import './register.ts';\nexport {};\n`], + ['packages/e2e/src/setup/register.ts', `export function register(): void {}\n`], ]); const readAtTag = (path: string): string | undefined => tagFiles.get(path); const agentCheck: EngineImportCheck = { @@ -334,11 +353,32 @@ describe('tagExportsAt', () => { imports: new Map([['agent', new Map([['acp', 'value']])]]), }; - it('returns empty sets for a subpath the tag does not export', () => { - const atAgent = tagExportsAt(readAtTag, 'packages/e2e', 'agent'); - assert.notEqual(atAgent, undefined); - assert.deepEqual([...(atAgent?.values ?? [])], []); - assert.deepEqual([...(atAgent?.types ?? [])], []); + it('returns missing for a subpath the tag does not export', () => { + assert.equal(tagExportsAt(readAtTag, 'packages/e2e', 'agent'), 'missing'); + }); + + it('returns empty sets, not missing, for an entry that exports nothing', () => { + const atSetup = tagExportsAt(readAtTag, 'packages/e2e', 'setup'); + if (atSetup === undefined || atSetup === 'missing') assert.fail('expected export sets for an entry that exists but exports nothing'); + assert.deepEqual([...atSetup.values], []); + assert.deepEqual([...atSetup.types], []); + }); + + it('passes a side-effect import of an entry that exports nothing', () => { + const sideEffect: EngineImportCheck = { + packageName: '@e2e-dev/web', + packagePath: 'packages/web/package.json', + sibling: 'e2e', + floor: '0.22.0', + imports: new Map([['setup', new Map()]]), + }; + const { problems, unverifiable, verified } = engineImportProblems( + [sideEffect], + (_sibling, subpath) => tagExportsAt(readAtTag, 'packages/e2e', subpath), + ); + assert.deepEqual(problems, []); + assert.deepEqual(unverifiable, []); + assert.equal(verified, 1); }); it('fails a named import from a subpath the floor tag does not export', () => { @@ -347,7 +387,7 @@ describe('tagExportsAt', () => { (_sibling, subpath) => tagExportsAt(readAtTag, 'packages/e2e', subpath), ); assert.equal(problems.length, 1); - assert.match(problems[0]!, /imports `acp` from e2e\/agent, but e2e@0\.22\.0 does not export it/); + assert.match(problems[0]!, /imports from e2e\/agent, but e2e@0\.22\.0 does not export that subpath/); assert.deepEqual(unverifiable, []); assert.equal(verified, 1); }); @@ -447,7 +487,7 @@ describe('engineImportProblems', () => { it('fails a namespace import from a subpath the floor tag does not export', () => { const { problems, unverifiable } = engineImportProblems( [check('0.23.0', new Map([['nope', new Map([['*', 'value']])]]))], - () => exported([]), + () => 'missing', ); assert.equal(problems.length, 1); assert.match(problems[0]!, /imports from e2e\/nope, but e2e@0\.23\.0 does not export that subpath/); @@ -457,13 +497,42 @@ describe('engineImportProblems', () => { it('fails a side-effect import from a subpath the floor tag does not export', () => { const { problems, unverifiable } = engineImportProblems( [check('0.23.0', new Map([['nope2', new Map()]]))], - () => exported([]), + () => 'missing', ); assert.equal(problems.length, 1); assert.match(problems[0]!, /imports from e2e\/nope2, but e2e@0\.23\.0 does not export that subpath/); assert.deepEqual(unverifiable, []); }); + it('reports a namespace import from an entry that exports nothing as unverifiable, not a problem', () => { + const { problems, unverifiable } = engineImportProblems( + [check('0.23.0', new Map([['engine', new Map([['*', 'value']])]]))], + () => exported([]), + ); + assert.deepEqual(problems, []); + assert.equal(unverifiable.length, 1); + assert.match(unverifiable[0]!, /imported as a namespace/); + }); + + it('fails a named import from an entry that exports nothing', () => { + const { problems } = engineImportProblems( + [check('0.23.0', named([['stepTimeout', 'value']]))], + () => exported([]), + ); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /imports `stepTimeout` from e2e\/engine, but e2e@0\.23\.0 does not export it/); + }); + + it('fails an export-star-as re-export from a subpath the floor tag does not export', () => { + const imports = engineImports(`export * as ns from 'e2e/missing';\n`); + const { problems } = engineImportProblems( + [{ packageName: '@e2e-dev/web', packagePath: 'packages/web/package.json', sibling: 'e2e', floor: '0.23.0', imports }], + () => 'missing', + ); + assert.equal(problems.length, 1); + assert.match(problems[0]!, /imports from e2e\/missing, but e2e@0\.23\.0 does not export that subpath/); + }); + it('passes a side-effect import from a subpath the floor tag exports', () => { const { problems, unverifiable, verified } = engineImportProblems( [check('0.23.0', new Map([['engine', new Map()]]))], diff --git a/scripts/engine-exports.ts b/scripts/engine-exports.ts index 63147c03fd..fac149bbab 100644 --- a/scripts/engine-exports.ts +++ b/scripts/engine-exports.ts @@ -62,6 +62,16 @@ function mergeImportKinds(target: Map, names: Iterable>, subpath: string, names: Iterable): void { + let map = target.get(subpath); + if (map === undefined) { + map = new Map(); + target.set(subpath, map); + } + mergeImportKinds(map, names); +} + /** The `import(...)` call in `node`, unwrapping `await` and parentheses; undefined when `node` is not one. */ function importCall(node: unknown): AstNode | undefined { let current: unknown = node; @@ -111,12 +121,7 @@ function walkAst(value: unknown, visit: (node: AstNode) => void): void { export function engineImports(source: string): EngineImportMap { const found = new Map>(); const add = (subpath: string, names: readonly (readonly [string, ImportKind])[]): void => { - let map = found.get(subpath); - if (map === undefined) { - map = new Map(); - found.set(subpath, map); - } - mergeImportKinds(map, names); + mergeInto(found, subpath, names); }; const parsed = parseModule(source); for (const statement of parsed.module.staticImports) { @@ -186,12 +191,7 @@ export function engineImports(source: string): EngineImportMap { /** Merges `source` into `target`, a value import of a name winning over a type import of the same name. */ export function addEngineImports(target: Map>, source: EngineImportMap): void { for (const [subpath, names] of source) { - let map = target.get(subpath); - if (map === undefined) { - map = new Map(); - target.set(subpath, map); - } - mergeImportKinds(map, names); + mergeInto(target, subpath, names); } } @@ -301,6 +301,9 @@ export interface ExportSets { readonly types: ReadonlySet; } +/** The export state of a subpath at a version: its export sets when the tag exports the subpath, `'missing'` when the tag record exists but the sibling does not export that subpath there. */ +export type TagExports = ExportSets | 'missing'; + /** Resolves a relative module specifier against the file that imports it; undefined for a bare specifier. */ export function resolveModule(fromFile: string, specifier: string): string | undefined { if (!specifier.startsWith('.')) return undefined; @@ -376,19 +379,21 @@ function entryFileFromExports(exports: Record | undefined, sibl } /** - * The export set of a sibling's subpath at a version, split by kind. - * `readFile` reads a repo path at that version. Undefined when the tag - * record cannot be read (no manifest, unparseable manifest, unreadable - * entry). Empty sets when the record exists but the sibling does not - * export that subpath there: every import from it is then a problem, - * not unverifiable. An export entry with no types target stays - * unverifiable, since no entry file can be found for it that way. + * The export state of a sibling's subpath at a version. `readFile` reads a + * repo path at that version. Undefined when the tag record cannot be read + * (no manifest, unparseable manifest, unreadable entry). `'missing'` when + * the record exists but the sibling does not export that subpath there: + * every import from it is then a problem, not unverifiable. Empty sets + * when the entry exists but exports nothing: a side-effect import of it + * passes, a named import still fails on the name. An export entry with no + * types target stays unverifiable, since no entry file can be found for + * it that way. */ export function tagExportsAt( readFile: (path: string) => string | undefined, siblingDir: string, subpath: string, -): ExportSets | undefined { +): TagExports | undefined { const manifest = readFile(`${siblingDir}/package.json`); if (manifest === undefined) return undefined; let exports: Record | undefined; @@ -400,7 +405,7 @@ export function tagExportsAt( const entry = entryFileFromExports(exports, siblingDir, subpath); if (entry !== undefined) return resolveEntryExports(readFile, entry); if (exports?.[exportKey(subpath)] !== undefined) return undefined; - return { values: new Set(), types: new Set() }; + return 'missing'; } export interface EngineImportCheck { @@ -423,7 +428,7 @@ export interface EngineImportCheck { */ export function engineImportProblems( checks: readonly EngineImportCheck[], - exportsAt: (sibling: string, subpath: string, version: string) => ExportSets | undefined, + exportsAt: (sibling: string, subpath: string, version: string) => TagExports | undefined, ): { problems: string[]; unverifiable: string[]; verified: number } { const problems: string[] = []; const unverifiable: string[] = []; @@ -433,36 +438,28 @@ export function engineImportProblems( let allResolved = true; for (const [subpath, names] of check.imports) { const label = subpath === '' ? check.sibling : `${check.sibling}/${subpath}`; - const named = [...names].filter(([name]) => name !== '*'); - if (named.length === 0) { - // No names to check, but the subpath itself must exist at the - // floor: a namespace or side-effect import from a - // subpath the floor tag never exported fails at runtime. - const exported = exportsAt(check.sibling, subpath, check.floor); - if (exported === undefined) { - unverifiable.push(`${check.packagePath}: ${label} at ${check.sibling}@${check.floor} cannot be verified, no tag record for that version; the floor must still name a released version`); - allResolved = false; - } else if (exported.values.size === 0 && exported.types.size === 0) { - problems.push( - `${check.packagePath}: imports from ${label}, but ${check.sibling}@${check.floor} does not export that subpath; a new ${label} import counts as raising the floor, so raise the ${check.sibling} peer floor to the first version that exports it (as a **Breaking:** minor when it passes a runner minor the previous range accepted)`, - ); - } else if (names.has('*')) { - unverifiable.push(`${check.packagePath}: ${label} is imported as a namespace, so its names cannot be verified against ${check.sibling}@${check.floor}`); - } else { - checked = true; - } - continue; - } - if (names.has('*')) { - unverifiable.push(`${check.packagePath}: ${label} is imported as a namespace, so its names cannot be verified against ${check.sibling}@${check.floor}`); - } const exported = exportsAt(check.sibling, subpath, check.floor); if (exported === undefined) { unverifiable.push(`${check.packagePath}: ${label} at ${check.sibling}@${check.floor} cannot be verified, no tag record for that version; the floor must still name a released version`); allResolved = false; continue; } - checked = true; + if (exported === 'missing') { + problems.push( + `${check.packagePath}: imports from ${label}, but ${check.sibling}@${check.floor} does not export that subpath; a new ${label} import counts as raising the floor, so raise the ${check.sibling} peer floor to the first version that exports it (as a **Breaking:** minor when it passes a runner minor the previous range accepted)`, + ); + checked = true; + continue; + } + const named = [...names].filter(([name]) => name !== '*'); + if (names.has('*')) { + unverifiable.push(`${check.packagePath}: ${label} is imported as a namespace, so its names cannot be verified against ${check.sibling}@${check.floor}`); + } + // A namespace-only import names nothing to check, so it does not + // count the check as verified; any other import was checked + // against the tag record, including a side-effect import, whose + // only question is whether the subpath exists. + if (named.length > 0 || !names.has('*')) checked = true; const missing = named .filter(([name, kind]) => (kind === 'value' ? !exported.values.has(name) : !exported.values.has(name) && !exported.types.has(name))) .map(([name]) => name) From 4272a5cea2e529725c66f2d85e6d7afe272a9248 Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Thu, 12 Nov 2026 13:01:21 +0000 Subject: [PATCH 09/14] fix(release): drop web from the engine-peer-floors changeset The rebase onto 046bd08f dropped the web package.json bump, since #1393 already raised web's e2e peer floor to >=0.23.1 on main. The changeset still listed @e2e-dev/web as patch and described a web floor raise, which would have shipped a wrong CHANGELOG line and an extra web release. Drop web from the frontmatter and the bullet; mobile, acp, and limrun are unchanged. Signed-off-by: Varshith Puli --- .changeset/engine-peer-floors.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.changeset/engine-peer-floors.md b/.changeset/engine-peer-floors.md index f6f556a34b..d1e710913a 100644 --- a/.changeset/engine-peer-floors.md +++ b/.changeset/engine-peer-floors.md @@ -1,10 +1,9 @@ --- -"@e2e-dev/web": patch "@e2e-dev/mobile": patch "@e2e-dev/acp": patch "@e2e-dev/limrun": patch --- -- web and mobile: `e2e` peer floor `>=0.22.1` to `>=0.23.0`, the first version exporting the `stepTimeout` value and the `EngineDoctorCheck` types they import. +- mobile: `e2e` peer floor `>=0.22.1` to `>=0.23.0`, the first version exporting the `stepTimeout` value and the `EngineDoctorCheck` types it imports. - acp: `e2e` peer floor `>=0.21.4` to `>=0.22.0`, the first version exporting the `e2e/agent` rules and tools it imports. - limrun: mobile peer floor `>=0.11.1` to `>=0.12.0`, the first mobile release with the provider-owned local daemon change from #988. From 7a145b2c61d9a5f0b3b00ccede679a0eb51a6ecb Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Thu, 12 Nov 2026 15:57:41 +0000 Subject: [PATCH 10/14] fix(release): drop stale stepTimeout from the mobile changeset bullet Mobile imports EngineDoctorCheck types from e2e/engine but never stepTimeout, which only web uses. The bullet claimed both, so the generated mobile changelog would describe the wrong dependency. Signed-off-by: Varshith Puli --- .changeset/engine-peer-floors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/engine-peer-floors.md b/.changeset/engine-peer-floors.md index d1e710913a..69cdf30349 100644 --- a/.changeset/engine-peer-floors.md +++ b/.changeset/engine-peer-floors.md @@ -4,6 +4,6 @@ "@e2e-dev/limrun": patch --- -- mobile: `e2e` peer floor `>=0.22.1` to `>=0.23.0`, the first version exporting the `stepTimeout` value and the `EngineDoctorCheck` types it imports. +- mobile: `e2e` peer floor `>=0.22.1` to `>=0.23.0`, the first version exporting the `EngineDoctorCheck` types it imports. - acp: `e2e` peer floor `>=0.21.4` to `>=0.22.0`, the first version exporting the `e2e/agent` rules and tools it imports. - limrun: mobile peer floor `>=0.11.1` to `>=0.12.0`, the first mobile release with the provider-owned local daemon change from #988. From 14de689406320d3b4f8414653a6f4f6d97bb2c2d Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Sun, 15 Nov 2026 07:02:22 +0000 Subject: [PATCH 11/14] fix(release): raise browser-run web peer floor to >=0.16.0 Signed-off-by: Varshith Puli --- .changeset/browser-run-web-peer-floor.md | 5 +++++ packages/browser-run/package.json | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) create mode 100644 .changeset/browser-run-web-peer-floor.md diff --git a/.changeset/browser-run-web-peer-floor.md b/.changeset/browser-run-web-peer-floor.md new file mode 100644 index 0000000000..a1bae1a5e5 --- /dev/null +++ b/.changeset/browser-run-web-peer-floor.md @@ -0,0 +1,5 @@ +--- +"@e2e-dev/browser-run": patch +--- + +Requires `@e2e-dev/web` 0.16.0 or later. diff --git a/packages/browser-run/package.json b/packages/browser-run/package.json index f8bae61bae..d33f9a59d5 100644 --- a/packages/browser-run/package.json +++ b/packages/browser-run/package.json @@ -47,7 +47,7 @@ "test:unit": "vitest run tests/unit" }, "peerDependencies": { - "@e2e-dev/web": ">=0.15.6 <1" + "@e2e-dev/web": ">=0.16.0 <1" }, "devDependencies": { "@e2e-dev/web": "workspace:*", From 74ad19374f1b67e03475cbae0e232ee56d3fa48e Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Sun, 15 Nov 2026 22:13:17 +0000 Subject: [PATCH 12/14] fix(release): follow bare re-exports and fixed groups in peer-floor checks Rebasing onto the core move (0a5ee163) left check:peer-ranges failing on the new tree, for two gaps in the check itself rather than the packages. First, e2e/agent now re-exports @e2e-dev/core through a bare specifier, and resolveEntryExports only followed relative export star chains, so every name arriving that way read as missing at the 0.23.2 floor. Bare stars now resolve through the named workspace package's exports map, including wildcard entries, read at the same version as the tag lookup. Second, @e2e-dev/core is a new package with no CHANGELOG, and the pending-version map gave it 0.0.1 from its own patch bump, while the fixed group releases it at the runner's 0.23.2. Pending versions now expand through the changesets fixed groups before the floor check runs. The mobile floor bullet leaves the engine-peer-floors changeset: the core move already raised that floor to 0.23.2, so this branch no longer changes it. 15 new regression tests; scripts suite 167 green, both release checks green, tsc and oxlint clean. Signed-off-by: Varshith Puli --- .changeset/engine-peer-floors.md | 2 - scripts/changeset-bumps.ts | 3 +- scripts/check-helpers.test.ts | 8 +- scripts/check-helpers.ts | 13 +++ scripts/check-peer-ranges.ts | 20 +++-- scripts/engine-exports.test.ts | 145 ++++++++++++++++++++++++++++++- scripts/engine-exports.ts | 91 +++++++++++++++++-- scripts/peer-ranges.test.ts | 40 ++++++++- scripts/peer-ranges.ts | 25 ++++++ 9 files changed, 329 insertions(+), 18 deletions(-) diff --git a/.changeset/engine-peer-floors.md b/.changeset/engine-peer-floors.md index 69cdf30349..517b2bbf49 100644 --- a/.changeset/engine-peer-floors.md +++ b/.changeset/engine-peer-floors.md @@ -1,9 +1,7 @@ --- -"@e2e-dev/mobile": patch "@e2e-dev/acp": patch "@e2e-dev/limrun": patch --- -- mobile: `e2e` peer floor `>=0.22.1` to `>=0.23.0`, the first version exporting the `EngineDoctorCheck` types it imports. - acp: `e2e` peer floor `>=0.21.4` to `>=0.22.0`, the first version exporting the `e2e/agent` rules and tools it imports. - limrun: mobile peer floor `>=0.11.1` to `>=0.12.0`, the first mobile release with the provider-owned local daemon change from #988. diff --git a/scripts/changeset-bumps.ts b/scripts/changeset-bumps.ts index a939783b55..d0110430c6 100644 --- a/scripts/changeset-bumps.ts +++ b/scripts/changeset-bumps.ts @@ -50,7 +50,8 @@ export function parseVersion(version: string): Semver | undefined { } /** -1, 0, or 1, semver order on `x.y.z` triples. */ -function compareVersions(a: Semver, b: Semver): number { +/** The version comparison: negative when `a` is older, 0 when equal, positive when newer. */ +export function compareVersions(a: Semver, b: Semver): number { const [aMajor, aMinor, aPatch] = a; const [bMajor, bMinor, bPatch] = b; if (aMajor !== bMajor) return aMajor < bMajor ? -1 : 1; diff --git a/scripts/check-helpers.test.ts b/scripts/check-helpers.test.ts index bae7679cb1..3835541837 100644 --- a/scripts/check-helpers.test.ts +++ b/scripts/check-helpers.test.ts @@ -3,7 +3,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { describe, it } from 'node:test'; -import { collectEngineImports } from './check-helpers.ts'; +import { collectEngineImports, fixedGroups } from './check-helpers.ts'; describe('collectEngineImports', () => { it('names the file that fails to parse', () => { @@ -26,3 +26,9 @@ describe('collectEngineImports', () => { } }); }); + +describe('fixedGroups', () => { + it('reads the fixed groups from the repo changesets config', () => { + assert.deepEqual(fixedGroups(), [['e2e', '@e2e-dev/core']]); + }); +}); diff --git a/scripts/check-helpers.ts b/scripts/check-helpers.ts index 1a474b8b82..cff29574d2 100644 --- a/scripts/check-helpers.ts +++ b/scripts/check-helpers.ts @@ -89,3 +89,16 @@ export function pendingChangesets(): { file: string; changeset: ReturnType ({ file, changeset: parseChangesetFile(readFileSync(join(dir, file), 'utf8')) })); } + +/** The changesets `fixed` groups from `.changeset/config.json`: packages that release at one version. Empty when the config cannot be read or names none. */ +export function fixedGroups(): string[][] { + try { + const config = JSON.parse(readFileSync(join(REPO_ROOT, '.changeset', 'config.json'), 'utf8')) as { fixed?: unknown }; + if (!Array.isArray(config.fixed)) return []; + return config.fixed.filter( + (group): group is string[] => Array.isArray(group) && group.every((name) => typeof name === 'string'), + ); + } catch { + return []; + } +} diff --git a/scripts/check-peer-ranges.ts b/scripts/check-peer-ranges.ts index 5fcd7aed92..e1c5ade7fe 100644 --- a/scripts/check-peer-ranges.ts +++ b/scripts/check-peer-ranges.ts @@ -23,10 +23,10 @@ import { readFileSync } from 'node:fs'; import { dirname, join, relative } from 'node:path'; -import { collectEngineImports, listTags, pendingChangesets, readChangelog, showAtTag } from './check-helpers.ts'; +import { collectEngineImports, fixedGroups, listTags, pendingChangesets, readChangelog, showAtTag } from './check-helpers.ts'; import { nextVersionAfterBump, pendingBumps } from './changeset-bumps.ts'; -import { engineImportProblems, tagExportsAt, type EngineImportCheck, type TagExports } from './engine-exports.ts'; -import { peerFloor, peerRangeProblems } from './peer-ranges.ts'; +import { engineImportProblems, resolveWorkspaceSpecifier, tagExportsAt, type EngineImportCheck, type TagExports } from './engine-exports.ts'; +import { applyFixedGroups, peerFloor, peerRangeProblems } from './peer-ranges.ts'; import { REPO_ROOT, publicPackages, siblingPeers } from './public-packages.ts'; const packages = publicPackages(); @@ -49,6 +49,11 @@ for (const [name, bump] of pendingBumps(pending.map(({ changeset }) => changeset const next = nextVersionAfterBump(version, bump); if (next !== undefined) nextVersions.set(name, next); } +// A changesets `fixed` group releases every member at one version, so a +// member's pending version is the group's highest, not its own bump alone: +// `e2e` and `@e2e-dev/core` release together, and the core package's first +// release is the runner's next version, not a `0.0.1` patch of its own. +applyFixedGroups(nextVersions, fixedGroups()); const problems = peerRangeProblems(packages, readChangelog, nextVersions); @@ -77,13 +82,18 @@ const exportsAt = (sibling: string, subpath: string, version: string): TagExport const key = `${sibling}@${version}:${subpath}`; if (exportsCache.has(key)) return exportsCache.get(key); const siblingDir = siblingDirs.get(sibling); - let resolved = siblingDir === undefined ? undefined : tagExportsAt((path) => showAtTag(`${sibling}@${version}`, path), siblingDir, subpath); + const tagRead = (path: string): string | undefined => showAtTag(`${sibling}@${version}`, path); + // A bare `export *` into another workspace package resolves through + // that package's manifest, read at the same version as the tag lookup. + const resolver = (readFile: (path: string) => string | undefined) => (specifier: string): string | undefined => + resolveWorkspaceSpecifier(readFile, siblingDirs, specifier); + let resolved = siblingDir === undefined ? undefined : tagExportsAt(tagRead, siblingDir, subpath, resolver(tagRead)); if (resolved === undefined && siblingDir !== undefined && nextVersions.get(sibling) === version) { // A floor naming the version the sibling's pending changesets will // release has no tag yet, so the tag lookup cannot verify it; the // working tree is that pending release's source, so verify against it // instead of passing the floor on an unverifiable note. - resolved = tagExportsAt(showWorkingTree, siblingDir, subpath); + resolved = tagExportsAt(showWorkingTree, siblingDir, subpath, resolver(showWorkingTree)); } exportsCache.set(key, resolved); return resolved; diff --git a/scripts/engine-exports.test.ts b/scripts/engine-exports.test.ts index 564e3b95bb..185a2843f5 100644 --- a/scripts/engine-exports.test.ts +++ b/scripts/engine-exports.test.ts @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { describe, it } from 'node:test'; -import { addEngineImports, engineImportProblems, engineImports, resolveEntryExports, resolveModule, subpathEntryFile, tagExportsAt, type EngineImportCheck, type EngineImportMap, type ImportKind } from './engine-exports.ts'; +import { addEngineImports, engineImportProblems, engineImports, resolveEntryExports, resolveModule, resolveWorkspaceSpecifier, subpathEntryFile, tagExportsAt, type EngineImportCheck, type EngineImportMap, type ImportKind } from './engine-exports.ts'; describe('engineImports', () => { it('reads named, aliased, and type-only imports from e2e entries', () => { @@ -322,6 +322,107 @@ describe('exportedNames and resolveEntryExports', () => { assert.equal(subpathEntryFile('not json', 'packages/e2e', 'engine'), undefined); assert.equal(subpathEntryFile(packageJson, 'packages/e2e', 'missing'), undefined); }); + + it('reads a wildcard entry off a sibling package.json', () => { + const packageJson = JSON.stringify({ exports: { './lib/*': { types: './dist/*.d.ts', default: './dist/*.js' } } }); + assert.equal(subpathEntryFile(packageJson, 'packages/core', 'lib/agent/public'), 'packages/core/src/agent/public.ts'); + assert.equal(subpathEntryFile(packageJson, 'packages/core', 'lib/types'), 'packages/core/src/types.ts'); + }); + + it('follows a bare export star into a workspace sibling', () => { + // The shape of the core move: e2e/agent re-exports the core package + // through a bare specifier, and the names live in the core source. + const files = new Map([ + [ + 'packages/e2e/package.json', + JSON.stringify({ exports: { './agent': { types: './dist/agent/public.d.ts', default: './dist/agent/public.js' } } }), + ], + ['packages/e2e/src/agent/public.ts', `export * from '@e2e-dev/core/lib/agent/public';\n`], + [ + 'packages/core/package.json', + JSON.stringify({ exports: { './engine': { types: './dist/engine/index.d.ts', default: './dist/engine/index.js' }, './lib/*': { types: './dist/*.d.ts', default: './dist/*.js' } } }), + ], + [ + 'packages/core/src/agent/public.ts', + `export { defineTool, type DefinedTool, type ToolAnnotations } from './tool.ts';\n`, + ], + ['packages/core/src/agent/tool.ts', `export function defineTool(): void {}\\nexport interface DefinedTool {}\\nexport interface ToolAnnotations {}\\n`], + ]); + const read = (path: string): string | undefined => files.get(path); + const dirs = new Map([ + ['e2e', 'packages/e2e'], + ['@e2e-dev/core', 'packages/core'], + ]); + const resolveBare = (specifier: string): string | undefined => resolveWorkspaceSpecifier(read, dirs, specifier); + const exported = resolveEntryExports(read, 'packages/e2e/src/agent/public.ts', resolveBare); + assert.deepEqual([...(exported?.values ?? [])].toSorted(), ['defineTool']); + assert.deepEqual([...(exported?.types ?? [])].toSorted(), ['DefinedTool', 'ToolAnnotations']); + }); + + it('does not follow a bare export star without a resolver', () => { + const files = new Map([['packages/e2e/src/agent/public.ts', `export * from '@e2e-dev/core/lib/agent/public';\n`]]); + const exported = resolveEntryExports((path) => files.get(path), 'packages/e2e/src/agent/public.ts'); + assert.deepEqual([...(exported?.values ?? [])], []); + assert.deepEqual([...(exported?.types ?? [])], []); + }); +}); + +describe('resolveWorkspaceSpecifier', () => { + const dirs = new Map([ + ['e2e', 'packages/e2e'], + ['@e2e-dev/core', 'packages/core'], + ]); + const files = new Map([ + [ + 'packages/core/package.json', + JSON.stringify({ + exports: { + '.': { types: './dist/index.d.ts', default: './dist/index.js' }, + './engine': { types: './dist/engine/index.d.ts', default: './dist/engine/index.js' }, + './lib/*': { types: './dist/*.d.ts', default: './dist/*.js' }, + }, + }), + ], + [ + 'packages/e2e/package.json', + JSON.stringify({ exports: { '.': { types: './dist/index.d.ts', default: './dist/index.js' } } }), + ], + ]); + const read = (path: string): string | undefined => files.get(path); + + it('resolves an exact subpath and the bare entry', () => { + assert.equal(resolveWorkspaceSpecifier(read, dirs, '@e2e-dev/core/engine'), 'packages/core/src/engine/index.ts'); + assert.equal(resolveWorkspaceSpecifier(read, dirs, '@e2e-dev/core'), 'packages/core/src/index.ts'); + }); + + it('resolves a wildcard subpath', () => { + assert.equal(resolveWorkspaceSpecifier(read, dirs, '@e2e-dev/core/lib/agent/public'), 'packages/core/src/agent/public.ts'); + }); + + it('answers undefined for a package outside the workspace', () => { + assert.equal(resolveWorkspaceSpecifier(read, dirs, 'zod'), undefined); + assert.equal(resolveWorkspaceSpecifier(read, dirs, '@other/core/engine'), undefined); + }); + + it('maps a wildcard subpath even when the file does not exist yet; the reader reports it missing', () => { + assert.equal(resolveWorkspaceSpecifier(read, dirs, '@e2e-dev/core/lib/missing'), 'packages/core/src/missing.ts'); + const entryFiles = new Map([ + ['packages/e2e/src/agent/public.ts', `export * from '@e2e-dev/core/lib/missing';\n`], + [ + 'packages/core/package.json', + JSON.stringify({ exports: { './lib/*': { types: './dist/*.d.ts', default: './dist/*.js' } } }), + ], + ]); + const readEntry = (path: string): string | undefined => entryFiles.get(path); + assert.equal( + resolveEntryExports(readEntry, 'packages/e2e/src/agent/public.ts', (specifier) => resolveWorkspaceSpecifier(readEntry, dirs, specifier)), + undefined, + ); + }); + + it('answers undefined when the manifest cannot be read', () => { + assert.equal(resolveWorkspaceSpecifier(() => undefined, dirs, '@e2e-dev/core/engine'), undefined); + }); }); describe('tagExportsAt', () => { @@ -417,6 +518,48 @@ describe('tagExportsAt', () => { undefined, ); }); + + it('follows a bare export star into a workspace sibling when a resolver is given', () => { + const files = new Map([ + [ + 'packages/e2e/package.json', + JSON.stringify({ exports: { './agent': { types: './dist/agent/public.d.ts', default: './dist/agent/public.js' } } }), + ], + ['packages/e2e/src/agent/public.ts', `export * from '@e2e-dev/core/lib/agent/public';\n`], + [ + 'packages/core/package.json', + JSON.stringify({ exports: { './lib/*': { types: './dist/*.d.ts', default: './dist/*.js' } } }), + ], + [ + 'packages/core/src/agent/public.ts', + `export { defineTool, type DefinedTool } from './tool.ts';\n`, + ], + ['packages/core/src/agent/tool.ts', `export function defineTool(): void {}\\nexport interface DefinedTool {}\\n`], + ]); + const read = (path: string): string | undefined => files.get(path); + const dirs = new Map([ + ['e2e', 'packages/e2e'], + ['@e2e-dev/core', 'packages/core'], + ]); + const atAgent = tagExportsAt(read, 'packages/e2e', 'agent', (specifier) => resolveWorkspaceSpecifier(read, dirs, specifier)); + if (atAgent === undefined || atAgent === 'missing') assert.fail('expected export sets through the bare re-export'); + assert.deepEqual([...atAgent.values], ['defineTool']); + assert.deepEqual([...atAgent.types], ['DefinedTool']); + }); + + it('reads no names through a bare export star without a resolver', () => { + const files = new Map([ + [ + 'packages/e2e/package.json', + JSON.stringify({ exports: { './agent': { types: './dist/agent/public.d.ts', default: './dist/agent/public.js' } } }), + ], + ['packages/e2e/src/agent/public.ts', `export * from '@e2e-dev/core/lib/agent/public';\n`], + ]); + const atAgent = tagExportsAt((path) => files.get(path), 'packages/e2e', 'agent'); + if (atAgent === undefined || atAgent === 'missing') assert.fail('expected empty export sets, not missing'); + assert.deepEqual([...atAgent.values], []); + assert.deepEqual([...atAgent.types], []); + }); }); describe('engineImportProblems', () => { diff --git a/scripts/engine-exports.ts b/scripts/engine-exports.ts index fac149bbab..353f3f6bb4 100644 --- a/scripts/engine-exports.ts +++ b/scripts/engine-exports.ts @@ -246,7 +246,7 @@ function declarationKinds(program: ReturnType['program']): Map return kinds; } -/** The names one file exports, split by kind, and the relative modules its `export *` pulls in. A `type` export or declaration lands in `types`; a class or enum lands in both, since its name is usable as a type; anything else value-like lands in `values`. `export type *` targets are kept apart from value `export *` targets: the former re-export types only. */ +/** The names one file exports, split by kind, and the modules its `export *` pulls in (relative ones, and bare ones when a resolver follows them). A `type` export or declaration lands in `types`; a class or enum lands in both, since its name is usable as a type; anything else value-like lands in `values`. `export type *` targets are kept apart from value `export *` targets: the former re-export types only. */ function exportedNames(source: string): { values: ReadonlySet; types: ReadonlySet; @@ -316,14 +316,30 @@ export function resolveModule(fromFile: string, specifier: string): string | und return parts.join('/'); } +/** + * Resolves a bare module specifier to a repo source file, or undefined + * when it names no workspace package. The check passes one built from the + * workspace manifests; tests pass a fake. + */ +export type BareSpecifierResolver = (specifier: string) => string | undefined; + /** * The export set of the entry file, split by kind, following `export *` * chains. A file reached through `export type *` contributes its types * only: a function or const there has no type meaning to re-export. * `readFile` reads a repo path (undefined when it has none); the caller * binds it to a version, for example `git show :`. + * A bare `export *` specifier is followed through `resolveBare` when one + * is given: a re-export from another workspace package (for example + * `e2e/agent` re-exporting `@e2e-dev/core/lib/agent/public`) contributes + * that package's names. Without one, bare chains are not followed, so a + * name that only arrives that way reads as missing. */ -export function resolveEntryExports(readFile: (path: string) => string | undefined, entryPath: string): ExportSets | undefined { +export function resolveEntryExports( + readFile: (path: string) => string | undefined, + entryPath: string, + resolveBare?: BareSpecifierResolver, +): ExportSets | undefined { const values = new Set(); const types = new Set(); const seen = new Set(); @@ -345,7 +361,7 @@ export function resolveEntryExports(readFile: (path: string) => string | undefin for (const name of exported.values) values.add(name); } const enqueue = (specifier: string, asType: boolean): void => { - const target = resolveModule(file, specifier); + const target = specifier.startsWith('.') ? resolveModule(file, specifier) : resolveBare?.(specifier); if (target !== undefined) queue.push([target, asType]); }; for (const specifier of exported.starModules) enqueue(specifier, typeOnly); @@ -370,14 +386,74 @@ export function subpathEntryFile(packageJson: string, siblingDir: string, subpat return entryFileFromExports(exports, siblingDir, subpath); } +/** The `types` target of an `exports` entry (a string, or its `types` field), undefined when it has none. */ +function entryTypesTarget(entry: unknown): string | undefined { + if (typeof entry === 'string') return entry; + if (isRecord(entry) && typeof entry.types === 'string') return entry.types; + return undefined; +} + +/** The `types` target for `subpath` in an `exports` map: the exact key, or a `*` key whose pattern the subpath matches with the middle substituted. Undefined when no key covers it. */ +function exportTypesTarget(exports: Record | undefined, subpath: string): string | undefined { + if (exports === undefined) return undefined; + const key = exportKey(subpath); + const exact = entryTypesTarget(exports[key]); + if (exact !== undefined) return exact; + for (const [pattern, value] of Object.entries(exports)) { + const star = pattern.indexOf('*'); + if (star === -1) continue; + const prefix = pattern.slice(0, star); + const suffix = pattern.slice(star + 1); + if (!key.startsWith(prefix) || !key.endsWith(suffix)) continue; + const target = entryTypesTarget(value); + if (target === undefined || !target.includes('*')) continue; + return target.replace('*', key.slice(prefix.length, key.length - suffix.length)); + } + return undefined; +} + +/** Whether an `exports` map covers `subpath` at all, exactly or through a `*` key. */ +function hasExportKey(exports: Record | undefined, subpath: string): boolean { + return exportTypesTarget(exports, subpath) !== undefined || exports?.[exportKey(subpath)] !== undefined; +} + /** The entry file for a subpath from an already-parsed `exports` map. */ function entryFileFromExports(exports: Record | undefined, siblingDir: string, subpath: string): string | undefined { - const entry = exports?.[exportKey(subpath)]; - const types = typeof entry === 'string' ? entry : isRecord(entry) && typeof entry.types === 'string' ? entry.types : undefined; + const types = exportTypesTarget(exports, subpath); if (types === undefined) return undefined; return `${siblingDir}/src/${types.replace(/^\.\/dist\//, '').replace(/\.d\.ts$/, '.ts')}`; } +/** + * The source file a bare specifier resolves to, through the workspace + * package it names: the longest package-name prefix wins, and the rest + * is the subpath in that package's `exports` map (`*` keys included), + * mapped from `dist/` to `src/` the same way. `readFile` reads a repo + * path at the version being verified, so a tag read resolves against + * the tag's manifests. Undefined when the specifier names no package + * in `packageDirs`, or that package has no such export. + */ +export function resolveWorkspaceSpecifier( + readFile: (path: string) => string | undefined, + packageDirs: ReadonlyMap, + specifier: string, +): string | undefined { + let matchedName: string | undefined; + let matchedDir: string | undefined; + for (const [name, dir] of packageDirs) { + if ((specifier === name || specifier.startsWith(`${name}/`)) && (matchedName === undefined || name.length > matchedName.length)) { + matchedName = name; + matchedDir = dir; + } + } + if (matchedName === undefined || matchedDir === undefined) return undefined; + const manifest = readFile(`${matchedDir}/package.json`); + if (manifest === undefined) return undefined; + const rest = specifier.slice(matchedName.length); + const subpath = rest === '' ? '' : rest.slice(1); + return subpathEntryFile(manifest, matchedDir, subpath); +} + /** * The export state of a sibling's subpath at a version. `readFile` reads a * repo path at that version. Undefined when the tag record cannot be read @@ -393,6 +469,7 @@ export function tagExportsAt( readFile: (path: string) => string | undefined, siblingDir: string, subpath: string, + resolveBare?: BareSpecifierResolver, ): TagExports | undefined { const manifest = readFile(`${siblingDir}/package.json`); if (manifest === undefined) return undefined; @@ -403,8 +480,8 @@ export function tagExportsAt( return undefined; } const entry = entryFileFromExports(exports, siblingDir, subpath); - if (entry !== undefined) return resolveEntryExports(readFile, entry); - if (exports?.[exportKey(subpath)] !== undefined) return undefined; + if (entry !== undefined) return resolveEntryExports(readFile, entry, resolveBare); + if (hasExportKey(exports, subpath)) return undefined; return 'missing'; } diff --git a/scripts/peer-ranges.test.ts b/scripts/peer-ranges.test.ts index 6f88125646..4a5efd3b94 100644 --- a/scripts/peer-ranges.test.ts +++ b/scripts/peer-ranges.test.ts @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { describe, it } from 'node:test'; -import { peerFloor, peerRangeProblems, releasedVersions, type PublicPackage } from './peer-ranges.ts'; +import { applyFixedGroups, peerFloor, peerRangeProblems, releasedVersions, type PublicPackage } from './peer-ranges.ts'; function pkg(name: string, peers: Record): PublicPackage { return { path: `/repo/packages/${name}/package.json`, manifest: { name, version: '0.1.0', peerDependencies: peers } }; @@ -89,3 +89,41 @@ describe('peerRangeProblems', () => { assert.deepEqual(peerRangeProblems(packages, read), []); }); }); + +describe('applyFixedGroups', () => { + it('releases every group member at the highest pending version', () => { + // e2e and @e2e-dev/core are a fixed group: the core package's first + // release is the runner's next version, not a 0.0.1 patch of its own. + const nextVersions = new Map([ + ['e2e', '0.23.2'], + ['@e2e-dev/core', '0.0.1'], + ]); + applyFixedGroups(nextVersions, [['e2e', '@e2e-dev/core']]); + assert.equal(nextVersions.get('e2e'), '0.23.2'); + assert.equal(nextVersions.get('@e2e-dev/core'), '0.23.2'); + }); + + it('releases an unbumped member alongside the bumped one', () => { + const nextVersions = new Map([['e2e', '0.23.2']]); + applyFixedGroups(nextVersions, [['e2e', '@e2e-dev/core']]); + assert.equal(nextVersions.get('@e2e-dev/core'), '0.23.2'); + }); + + it('leaves a group with no pending member alone', () => { + const nextVersions = new Map([['@e2e-dev/web', '0.16.1']]); + applyFixedGroups(nextVersions, [['e2e', '@e2e-dev/core']]); + assert.equal(nextVersions.has('e2e'), false); + assert.equal(nextVersions.has('@e2e-dev/core'), false); + assert.equal(nextVersions.get('@e2e-dev/web'), '0.16.1'); + }); + + it('lets a fixed-group floor pass peerRangeProblems for a sibling with no changelog yet', () => { + const packages = [pkg('e2e', {}), pkg('@e2e-dev/core', {}), pkg('@e2e-dev/web', { '@e2e-dev/core': '>=0.23.2 <1' })]; + const nextVersions = new Map([ + ['e2e', '0.23.2'], + ['@e2e-dev/core', '0.0.1'], + ]); + applyFixedGroups(nextVersions, [['e2e', '@e2e-dev/core']]); + assert.deepEqual(peerRangeProblems(packages, () => undefined, nextVersions), []); + }); +}); diff --git a/scripts/peer-ranges.ts b/scripts/peer-ranges.ts index 5f1ddacd06..e8b7b8e3fb 100644 --- a/scripts/peer-ranges.ts +++ b/scripts/peer-ranges.ts @@ -17,6 +17,7 @@ */ import { relative } from 'node:path'; +import { compareVersions, parseVersion, type Semver } from './changeset-bumps.ts'; import { REPO_ROOT, isWidePeerRange, type PackageManifest } from './public-packages.ts'; export interface PublicPackage { @@ -82,3 +83,27 @@ export function peerRangeProblems( } return problems; } + +/** + * The version each member of a changesets `fixed` group will release at: + * a fixed group releases every member at one version, the highest next + * version any member's pending bump computes. Mutates `nextVersions` in + * place, setting every group member to that version, including one with + * no pending bump of its own: the group releases it alongside the bumped + * member. A group with no member in `nextVersions` is left alone. + */ +export function applyFixedGroups(nextVersions: Map, fixedGroups: readonly (readonly string[])[]): void { + for (const group of fixedGroups) { + let max: Semver | undefined; + for (const name of group) { + const version = nextVersions.get(name); + if (version === undefined) continue; + const parsed = parseVersion(version); + if (parsed === undefined) continue; + if (max === undefined || compareVersions(parsed, max) > 0) max = parsed; + } + if (max === undefined) continue; + const release = max.join('.'); + for (const name of group) nextVersions.set(name, release); + } +} From f00791e762435e5bdb56451081d35a415b97803b Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Mon, 16 Nov 2026 07:14:44 +0000 Subject: [PATCH 13/14] fix(release): version fixed groups with changesets and match Node exports patterns Compute pending release versions with @changesets/assemble-release-plan instead of hand-rolling them, so a fixed group releases every member at the group's highest current version with the group's highest bump: a core minor now puts e2e and core at 0.24.0, not 0.23.2. The config read fails loudly when .changeset/config.json is missing or malformed. Match Node's subpath-pattern rules in the exports lookup: longest wildcard prefix wins, a null target excludes the subpath, the key must be at least as long as the pattern, and every star in the target is substituted. Build the bare-specifier resolver inside tagExportsAt from its own read, so the tag lookup and the bare re-export cannot read different versions. Merge the stacked JSDoc on compareVersions. Signed-off-by: Varshith Puli --- package.json | 2 + pnpm-lock.yaml | 6 ++ scripts/changeset-bumps.test.ts | 19 +---- scripts/changeset-bumps.ts | 29 +------ scripts/check-helpers.test.ts | 65 +++++++++++++- scripts/check-helpers.ts | 100 +++++++++++++++++++--- scripts/check-peer-ranges.ts | 32 ++----- scripts/engine-exports.test.ts | 145 +++++++++++++++++++++++++++++++- scripts/engine-exports.ts | 88 ++++++++++++++----- scripts/peer-ranges.test.ts | 35 +------- scripts/peer-ranges.ts | 25 ------ 11 files changed, 385 insertions(+), 161 deletions(-) diff --git a/package.json b/package.json index 21ba667488..634ae2bce0 100644 --- a/package.json +++ b/package.json @@ -43,8 +43,10 @@ "Szymon Rybczak " ], "devDependencies": { + "@changesets/assemble-release-plan": "7.0.0", "@changesets/changelog-github": "1.0.1", "@changesets/cli": "3.0.3", + "@changesets/config": "4.0.1", "@changesets/parse": "1.0.0", "@mdx-js/mdx": "3.1.1", "@oxlint/plugins": "1.93.0", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 07d5bf742c..7431a18ab2 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -124,12 +124,18 @@ importers: .: devDependencies: + '@changesets/assemble-release-plan': + specifier: 7.0.0 + version: 7.0.0 '@changesets/changelog-github': specifier: 1.0.1 version: 1.0.1 '@changesets/cli': specifier: 3.0.3 version: 3.0.3 + '@changesets/config': + specifier: 4.0.1 + version: 4.0.1 '@changesets/parse': specifier: 1.0.0 version: 1.0.0 diff --git a/scripts/changeset-bumps.test.ts b/scripts/changeset-bumps.test.ts index 8a67a68daa..1b653ca053 100644 --- a/scripts/changeset-bumps.test.ts +++ b/scripts/changeset-bumps.test.ts @@ -7,9 +7,7 @@ import { floorRaiseProblems, floorRaisesPastMinor, latestReleaseVersion, - nextVersionAfterBump, parseVersion, - pendingBumps, versionBumpAnnounces, type FloorRaiseInput, } from './changeset-bumps.ts'; @@ -192,21 +190,10 @@ describe('latestReleaseVersion', () => { }); }); -describe('pendingBumps and nextVersionAfterBump', () => { it('takes the highest bump per package', () => { - const bumps = pendingBumps([ - parseChangesetFile('---\n"e2e": patch\n---\n\nA fix.\n'), - parseChangesetFile('---\n"e2e": minor\n"@e2e-dev/web": patch\n---\n\n**Breaking:** a break.\n'), - ]); - assert.equal(bumps.get('e2e'), 'minor'); - assert.equal(bumps.get('@e2e-dev/web'), 'patch'); - }); - - it('bumps versions the way changesets does', () => { - assert.equal(nextVersionAfterBump('0.23.0', 'patch'), '0.23.1'); - assert.equal(nextVersionAfterBump('0.23.0', 'minor'), '0.24.0'); - assert.equal(nextVersionAfterBump('0.23.0', 'major'), '1.0.0'); - assert.equal(nextVersionAfterBump('not semver', 'patch'), undefined); +describe('parseVersion', () => { + it('parses strict x.y.z and nothing else', () => { assert.deepEqual(parseVersion('0.23.0'), [0, 23, 0]); assert.equal(parseVersion('0.23.0-canary-x'), undefined); + assert.equal(parseVersion('not semver'), undefined); }); }); diff --git a/scripts/changeset-bumps.ts b/scripts/changeset-bumps.ts index d0110430c6..2aa417bcc7 100644 --- a/scripts/changeset-bumps.ts +++ b/scripts/changeset-bumps.ts @@ -49,9 +49,8 @@ export function parseVersion(version: string): Semver | undefined { return [Number(major), Number(minor), Number(patch)]; } -/** -1, 0, or 1, semver order on `x.y.z` triples. */ -/** The version comparison: negative when `a` is older, 0 when equal, positive when newer. */ -export function compareVersions(a: Semver, b: Semver): number { +/** The version comparison: -1, 0, or 1, semver order on `x.y.z` triples. Negative when `a` is older, 0 when equal, positive when newer. */ +function compareVersions(a: Semver, b: Semver): number { const [aMajor, aMinor, aPatch] = a; const [bMajor, bMinor, bPatch] = b; if (aMajor !== bMajor) return aMajor < bMajor ? -1 : 1; @@ -113,30 +112,6 @@ export function latestReleaseVersion(tags: readonly string[], name: string): str const BUMP_RANK: Record = { patch: 0, minor: 1, major: 2 }; -/** The highest bump each package gets across `changesets`; a release type that bumps nothing is skipped. */ -export function pendingBumps(changesets: readonly Changeset[]): Map { - const bumps = new Map(); - for (const changeset of changesets) { - for (const { name, type } of changeset.releases) { - if (!(type in BUMP_RANK)) continue; - const bump = type as BumpType; - const current = bumps.get(name); - if (current === undefined || BUMP_RANK[bump] > BUMP_RANK[current]) bumps.set(name, bump); - } - } - return bumps; -} - -/** The version a `type` bump of `version` releases; undefined when `version` is not `x.y.z`. */ -export function nextVersionAfterBump(version: string, type: BumpType): string | undefined { - const parsed = parseVersion(version); - if (parsed === undefined) return undefined; - const [major, minor, patch] = parsed; - if (type === 'patch') return `${major}.${minor}.${patch + 1}`; - if (type === 'minor') return `${major}.${minor + 1}.0`; - return `${major + 1}.0.0`; -} - export interface FloorRaiseInput { readonly name: string; readonly path: string; diff --git a/scripts/check-helpers.test.ts b/scripts/check-helpers.test.ts index 3835541837..cd8a9aeaaa 100644 --- a/scripts/check-helpers.test.ts +++ b/scripts/check-helpers.test.ts @@ -3,7 +3,8 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { describe, it } from 'node:test'; -import { collectEngineImports, fixedGroups } from './check-helpers.ts'; +import { parseChangesetFile } from '@changesets/parse'; +import { collectEngineImports, nextReleaseVersions, workspacePackages, type ReleasePlanPackage } from './check-helpers.ts'; describe('collectEngineImports', () => { it('names the file that fails to parse', () => { @@ -27,8 +28,64 @@ describe('collectEngineImports', () => { }); }); -describe('fixedGroups', () => { - it('reads the fixed groups from the repo changesets config', () => { - assert.deepEqual(fixedGroups(), [['e2e', '@e2e-dev/core']]); +describe('workspacePackages', () => { + it('reads the workspace packages with their versions', () => { + const packages = workspacePackages(); + const byName = new Map(packages.map((pkg) => [pkg.packageJson.name, pkg.packageJson.version])); + assert.equal(byName.get('e2e'), '0.23.1'); + assert.equal(byName.get('@e2e-dev/core'), '0.0.0'); + }); +}); + +describe('nextReleaseVersions', () => { + // The fixed group in the repo config: e2e and @e2e-dev/core release at + // one version, the group's highest current version with its highest bump. + const e2e: ReleasePlanPackage = { + dir: 'packages/e2e', + packageJson: { name: 'e2e', version: '0.23.1', dependencies: { '@e2e-dev/core': 'workspace:*' } }, + }; + const core: ReleasePlanPackage = { dir: 'packages/core', packageJson: { name: '@e2e-dev/core', version: '0.0.0' } }; + const web: ReleasePlanPackage = { + dir: 'packages/web', + packageJson: { name: '@e2e-dev/web', version: '0.16.0', peerDependencies: { e2e: '>=0.23.2 <1', '@e2e-dev/core': '>=0.23.2 <1' } }, + }; + const changeset = (file: string, frontmatter: string) => ({ + file, + changeset: parseChangesetFile(`---\n${frontmatter}\n---\n\nA change.\n`), + }); + + it('versions a fixed group the way changesets does: highest current version plus highest bump', async () => { + // The repro from review: a core minor on top of the pending e2e patch + // releases both at 0.24.0, not at the 0.23.2 the hand-rolled math gave. + const versions = await nextReleaseVersions( + [e2e, core], + [changeset('e2e-patch.md', '"e2e": patch'), changeset('core-minor.md', '"@e2e-dev/core": minor')], + ); + assert.equal(versions.get('e2e'), '0.24.0'); + assert.equal(versions.get('@e2e-dev/core'), '0.24.0'); + }); + + it('releases an unbumped fixed-group member alongside the bumped one', async () => { + const versions = await nextReleaseVersions([e2e, core], [changeset('core-minor.md', '"@e2e-dev/core": minor')]); + assert.equal(versions.get('e2e'), '0.24.0'); + assert.equal(versions.get('@e2e-dev/core'), '0.24.0'); + }); + + it('leaves packages outside the release alone', async () => { + const versions = await nextReleaseVersions([e2e, core, web], [changeset('web-patch.md', '"@e2e-dev/web": patch')]); + assert.equal(versions.get('@e2e-dev/web'), '0.16.1'); + assert.equal(versions.has('e2e'), false); + assert.equal(versions.has('@e2e-dev/core'), false); + }); + + it('throws when the changesets config is malformed instead of reading it as no fixed groups', async () => { + const dir = mkdtempSync(join(tmpdir(), 'e2e-changesets-config-')); + try { + mkdirSync(join(dir, '.changeset'), { recursive: true }); + writeFileSync(join(dir, '.changeset', 'config.json'), '{not json'); + await assert.rejects(nextReleaseVersions([e2e, core], [], dir), /cannot read \.changeset\/config\.json/); + } finally { + rmSync(dir, { recursive: true, force: true }); + } }); }); diff --git a/scripts/check-helpers.ts b/scripts/check-helpers.ts index cff29574d2..ec3e835fb1 100644 --- a/scripts/check-helpers.ts +++ b/scripts/check-helpers.ts @@ -1,16 +1,19 @@ /** * Shared file and git reads for the release check scripts: the tag lookup, - * the source walk and import collection, the changelog read, and the - * pending changesets. One place, so the check scripts and their tests do - * not each reimplement them. + * the source walk and import collection, the changelog read, the pending + * changesets, and the versions those changesets will release at. One place, + * so the check scripts and their tests do not each reimplement them. */ import { execFileSync } from 'node:child_process'; import { readdirSync, readFileSync, statSync } from 'node:fs'; import { dirname, join } from 'node:path'; +import { assembleReleasePlan } from '@changesets/assemble-release-plan'; +import { readConfig } from '@changesets/config'; import { parseChangesetFile } from '@changesets/parse'; import { addEngineImports, engineImports, type EngineImportMap, type ImportKind } from './engine-exports.ts'; import { REPO_ROOT } from './public-packages.ts'; +import type { Changeset } from './changeset-bumps.ts'; /** Reads `path` at `tag` (`git show`), undefined when the tag or the file does not exist. */ export function showAtTag(tag: string, path: string): string | undefined { @@ -90,15 +93,90 @@ export function pendingChangesets(): { file: string; changeset: ReturnType ({ file, changeset: parseChangesetFile(readFileSync(join(dir, file), 'utf8')) })); } -/** The changesets `fixed` groups from `.changeset/config.json`: packages that release at one version. Empty when the config cannot be read or names none. */ -export function fixedGroups(): string[][] { +/** A workspace package for the changesets release plan: its directory and manifest, dependency ranges included, since the plan bumps dependents whose ranges go out of range. */ +export interface ReleasePlanPackage { + readonly dir: string; + readonly packageJson: { + readonly name: string; + readonly version: string; + readonly dependencies?: Record; + readonly devDependencies?: Record; + readonly peerDependencies?: Record; + readonly optionalDependencies?: Record; + readonly private?: boolean; + }; +} + +/** Every named package under `packages/`, private ones included: the release plan needs the whole workspace, since a changeset may name any of them. */ +export function workspacePackages(): ReleasePlanPackage[] { + const packages: ReleasePlanPackage[] = []; + for (const dir of readdirSync(join(REPO_ROOT, 'packages'))) { + const path = join(REPO_ROOT, 'packages', dir, 'package.json'); + let manifest: Partial; + try { + manifest = JSON.parse(readFileSync(path, 'utf8')) as Partial; + } catch { + continue; + } + if (manifest.name === undefined || manifest.version === undefined) continue; + packages.push({ dir: join(REPO_ROOT, 'packages', dir), packageJson: manifest as ReleasePlanPackage['packageJson'] }); + } + return packages; +} + +/** + * The version each package's pending changesets will release at, computed + * by changesets itself (`assembleReleasePlan`): a `fixed` group releases + * every member at the group's highest current version with the group's + * highest bump, and a dependent whose range goes out of range gets a + * patch. Only packages the plan releases are in the map. Throws when + * `.changeset/config.json` cannot be read or is malformed: a broken + * config must fail the check loudly, not read as no fixed groups. + */ +export async function nextReleaseVersions( + packages: readonly ReleasePlanPackage[], + changesets: readonly { file: string; changeset: Changeset }[], + cwd: string = REPO_ROOT, +): Promise> { + // The dependents graph is empty without a root package, so the plan + // cannot see dependents at all; read the root manifest for it. + let rootManifest: { name: string; version: string }; try { - const config = JSON.parse(readFileSync(join(REPO_ROOT, '.changeset', 'config.json'), 'utf8')) as { fixed?: unknown }; - if (!Array.isArray(config.fixed)) return []; - return config.fixed.filter( - (group): group is string[] => Array.isArray(group) && group.every((name) => typeof name === 'string'), - ); + rootManifest = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')) as { name: string; version: string }; } catch { - return []; + rootManifest = { name: '', version: '0.0.0' }; + } + const planPackages = { + rootDir: cwd, + rootPackage: { dir: cwd, packageJson: rootManifest }, + packages: packages.map((pkg) => ({ dir: pkg.dir, packageJson: pkg.packageJson })), + tool: { type: 'pnpm' }, + } as Parameters[1]; + let read: Awaited>; + try { + read = await readConfig(cwd, planPackages); + } catch (error) { + // A malformed config throws out of readConfig instead of returning + // errors, so catch it here and report it as a config failure. + throw new Error(`cannot read .changeset/config.json: ${error instanceof Error ? error.message : String(error)}`, { cause: error }); + } + const { config, errors } = read; + if (config === undefined || errors !== undefined) { + throw new Error(`cannot read .changeset/config.json: ${(errors ?? ['unknown error']).join('; ')}`); + } + const plan = assembleReleasePlan( + changesets.map(({ file, changeset }) => ({ + id: file.replace(/\.md$/, ''), + summary: changeset.summary, + releases: changeset.releases, + })), + planPackages, + config, + undefined, + ); + const versions = new Map(); + for (const release of plan.releases) { + if (release.type !== 'none' && release.newVersion !== undefined) versions.set(release.name, release.newVersion); } + return versions; } diff --git a/scripts/check-peer-ranges.ts b/scripts/check-peer-ranges.ts index e1c5ade7fe..84a6da6ba1 100644 --- a/scripts/check-peer-ranges.ts +++ b/scripts/check-peer-ranges.ts @@ -23,10 +23,9 @@ import { readFileSync } from 'node:fs'; import { dirname, join, relative } from 'node:path'; -import { collectEngineImports, fixedGroups, listTags, pendingChangesets, readChangelog, showAtTag } from './check-helpers.ts'; -import { nextVersionAfterBump, pendingBumps } from './changeset-bumps.ts'; -import { engineImportProblems, resolveWorkspaceSpecifier, tagExportsAt, type EngineImportCheck, type TagExports } from './engine-exports.ts'; -import { applyFixedGroups, peerFloor, peerRangeProblems } from './peer-ranges.ts'; +import { collectEngineImports, listTags, nextReleaseVersions, pendingChangesets, readChangelog, showAtTag, workspacePackages } from './check-helpers.ts'; +import { engineImportProblems, tagExportsAt, type EngineImportCheck, type TagExports } from './engine-exports.ts'; +import { peerFloor, peerRangeProblems } from './peer-ranges.ts'; import { REPO_ROOT, publicPackages, siblingPeers } from './public-packages.ts'; const packages = publicPackages(); @@ -39,21 +38,12 @@ for (const { manifest } of packages) { } // The version each sibling's pending changesets will release: a floor may -// name it as the sibling's version in the same release. -const pending = pendingChangesets(); -const versions = new Map(packages.map(({ manifest }) => [manifest.name, manifest.version])); -const nextVersions = new Map(); -for (const [name, bump] of pendingBumps(pending.map(({ changeset }) => changeset))) { - const version = versions.get(name); - if (version === undefined) continue; - const next = nextVersionAfterBump(version, bump); - if (next !== undefined) nextVersions.set(name, next); -} -// A changesets `fixed` group releases every member at one version, so a -// member's pending version is the group's highest, not its own bump alone: +// name it as the sibling's version in the same release. Computed by +// changesets itself, so a fixed group releases together at one version: // `e2e` and `@e2e-dev/core` release together, and the core package's first // release is the runner's next version, not a `0.0.1` patch of its own. -applyFixedGroups(nextVersions, fixedGroups()); +const pending = pendingChangesets(); +const nextVersions = await nextReleaseVersions(workspacePackages(), pending); const problems = peerRangeProblems(packages, readChangelog, nextVersions); @@ -83,17 +73,13 @@ const exportsAt = (sibling: string, subpath: string, version: string): TagExport if (exportsCache.has(key)) return exportsCache.get(key); const siblingDir = siblingDirs.get(sibling); const tagRead = (path: string): string | undefined => showAtTag(`${sibling}@${version}`, path); - // A bare `export *` into another workspace package resolves through - // that package's manifest, read at the same version as the tag lookup. - const resolver = (readFile: (path: string) => string | undefined) => (specifier: string): string | undefined => - resolveWorkspaceSpecifier(readFile, siblingDirs, specifier); - let resolved = siblingDir === undefined ? undefined : tagExportsAt(tagRead, siblingDir, subpath, resolver(tagRead)); + let resolved = siblingDir === undefined ? undefined : tagExportsAt(tagRead, siblingDir, subpath, siblingDirs); if (resolved === undefined && siblingDir !== undefined && nextVersions.get(sibling) === version) { // A floor naming the version the sibling's pending changesets will // release has no tag yet, so the tag lookup cannot verify it; the // working tree is that pending release's source, so verify against it // instead of passing the floor on an unverifiable note. - resolved = tagExportsAt(showWorkingTree, siblingDir, subpath, resolver(showWorkingTree)); + resolved = tagExportsAt(showWorkingTree, siblingDir, subpath, siblingDirs); } exportsCache.set(key, resolved); return resolved; diff --git a/scripts/engine-exports.test.ts b/scripts/engine-exports.test.ts index 185a2843f5..9d1b9c47ec 100644 --- a/scripts/engine-exports.test.ts +++ b/scripts/engine-exports.test.ts @@ -329,6 +329,43 @@ describe('exportedNames and resolveEntryExports', () => { assert.equal(subpathEntryFile(packageJson, 'packages/core', 'lib/types'), 'packages/core/src/types.ts'); }); + it('prefers the longest wildcard prefix, like Node', () => { + // In insertion order the short key comes first; Node still picks + // ./lib/agent/* for lib/agent/public, not ./lib/*. + const packageJson = JSON.stringify({ + exports: { + './lib/*': { types: './dist/lib/*.d.ts', default: './dist/lib/*.js' }, + './lib/agent/*': { types: './dist/agent/*.d.ts', default: './dist/agent/*.js' }, + }, + }); + assert.equal(subpathEntryFile(packageJson, 'packages/core', 'lib/agent/public'), 'packages/core/src/agent/public.ts'); + }); + + it('does not resolve a subpath the wildcard key is too short for', () => { + // ./lib/ is shorter than ./lib/*, so Node does not match it, and it + // must not resolve to src/.ts. + const packageJson = JSON.stringify({ exports: { './lib/*': { types: './dist/*.d.ts', default: './dist/*.js' } } }); + assert.equal(subpathEntryFile(packageJson, 'packages/core', 'lib/'), undefined); + }); + + it('substitutes every star in a wildcard target', () => { + const packageJson = JSON.stringify({ exports: { './multi/*': { types: './dist/*-*.d.ts', default: './dist/*-*.js' } } }); + assert.equal(subpathEntryFile(packageJson, 'packages/core', 'multi/x-y'), 'packages/core/src/x-y-x-y.ts'); + }); + + it('does not resolve a subpath whose wildcard suffix does not match', () => { + const packageJson = JSON.stringify({ exports: { './lib/*-test': { types: './dist/*.d.ts', default: './dist/*.js' } } }); + // Long enough to pass the key-length check, so only the suffix can + // refuse it: without the suffix check this would resolve to src/abcd.ts. + assert.equal(subpathEntryFile(packageJson, 'packages/core', 'lib/abcdefgh'), undefined); + assert.equal(subpathEntryFile(packageJson, 'packages/core', 'lib/foo-test'), 'packages/core/src/foo.ts'); + }); + + it('does not resolve a wildcard key whose types target names no per-subpath file', () => { + const packageJson = JSON.stringify({ exports: { './lib/*': { types: './dist/index.d.ts', default: './dist/index.js' } } }); + assert.equal(subpathEntryFile(packageJson, 'packages/core', 'lib/foo'), undefined); + }); + it('follows a bare export star into a workspace sibling', () => { // The shape of the core move: e2e/agent re-exports the core package // through a bare specifier, and the names live in the core source. @@ -365,6 +402,31 @@ describe('exportedNames and resolveEntryExports', () => { assert.deepEqual([...(exported?.values ?? [])], []); assert.deepEqual([...(exported?.types ?? [])], []); }); + + it('follows a relative export star through the relative file, never the bare resolver', () => { + const files = new Map([ + ['src/engine/index.ts', `export * from './local.ts';\n`], + ['src/engine/local.ts', `export function fromRelative(): void {}\n`], + ['packages/other/src/x.ts', `export function fromBare(): void {}\n`], + ]); + const seen: string[] = []; + const resolveBare = (specifier: string): string | undefined => { + seen.push(specifier); + return specifier === './local.ts' ? 'packages/other/src/x.ts' : undefined; + }; + const exported = resolveEntryExports((path) => files.get(path), 'src/engine/index.ts', resolveBare); + assert.deepEqual([...(exported?.values ?? [])], ['fromRelative']); + assert.deepEqual(seen, []); + }); + + it('does not fall through to the bare resolver when a relative export star has no file', () => { + const files = new Map([ + ['src/engine/index.ts', `export * from './gone.ts';\n`], + ['packages/other/src/x.ts', `export function fromBare(): void {}\n`], + ]); + const resolveBare = (specifier: string): string | undefined => (specifier === './gone.ts' ? 'packages/other/src/x.ts' : undefined); + assert.equal(resolveEntryExports((path) => files.get(path), 'src/engine/index.ts', resolveBare), undefined); + }); }); describe('resolveWorkspaceSpecifier', () => { @@ -404,6 +466,33 @@ describe('resolveWorkspaceSpecifier', () => { assert.equal(resolveWorkspaceSpecifier(read, dirs, '@other/core/engine'), undefined); }); + it('does not match a package name without a slash boundary', () => { + assert.equal(resolveWorkspaceSpecifier(read, dirs, '@e2e-dev/core2/engine'), undefined); + assert.equal(resolveWorkspaceSpecifier(read, dirs, '@e2e-dev/corex'), undefined); + // Without the boundary, @e2e-dev/core2 would read as the core package + // with the rest cut off, resolving its bare entry. + assert.equal(resolveWorkspaceSpecifier(read, dirs, '@e2e-dev/core2'), undefined); + }); + + it('prefers the longest package-name prefix', () => { + const nestedFiles = new Map([ + ...files, + [ + 'packages/nested/package.json', + JSON.stringify({ exports: { './engine': { types: './dist/engine/index.d.ts', default: './dist/engine/index.js' } } }), + ], + ]); + const nestedDirs = new Map([ + ...dirs, + ['@e2e-dev/core/nested', 'packages/nested'], + ]); + const nestedRead = (path: string): string | undefined => nestedFiles.get(path); + assert.equal( + resolveWorkspaceSpecifier(nestedRead, nestedDirs, '@e2e-dev/core/nested/engine'), + 'packages/nested/src/engine/index.ts', + ); + }); + it('maps a wildcard subpath even when the file does not exist yet; the reader reports it missing', () => { assert.equal(resolveWorkspaceSpecifier(read, dirs, '@e2e-dev/core/lib/missing'), 'packages/core/src/missing.ts'); const entryFiles = new Map([ @@ -519,7 +608,55 @@ describe('tagExportsAt', () => { ); }); - it('follows a bare export star into a workspace sibling when a resolver is given', () => { + it('returns undefined, not missing, for a subpath a wildcard key covers without a types target', () => { + // The entry exists, only its types target is missing, so the floor is + // unverifiable, not a gap: hasExportKey must look past exact keys. + const files = new Map([ + ['packages/e2e/package.json', JSON.stringify({ exports: { './lib/*': { default: './dist/*.js' } } })], + ]); + assert.equal( + tagExportsAt((path) => files.get(path), 'packages/e2e', 'lib/agent'), + undefined, + ); + }); + + it('returns missing for a subpath a null target excludes', () => { + const files = new Map([ + [ + 'packages/e2e/package.json', + JSON.stringify({ exports: { './lib/*': { types: './dist/*.d.ts', default: './dist/*.js' }, './null/*': null } }), + ], + ]); + assert.equal( + tagExportsAt((path) => files.get(path), 'packages/e2e', 'null/anything'), + 'missing', + ); + }); + + it('lets a null target on the longest match exclude the subpath even when a shorter key matches', () => { + const files = new Map([ + [ + 'packages/e2e/package.json', + JSON.stringify({ exports: { './*': { types: './dist/*.d.ts', default: './dist/*.js' }, './null/*': null } }), + ], + ]); + assert.equal( + tagExportsAt((path) => files.get(path), 'packages/e2e', 'null/anything'), + 'missing', + ); + }); + + it('returns missing for a subpath the wildcard key is too short for', () => { + const files = new Map([ + ['packages/e2e/package.json', JSON.stringify({ exports: { './lib/*': { types: './dist/*.d.ts', default: './dist/*.js' } } })], + ]); + assert.equal( + tagExportsAt((path) => files.get(path), 'packages/e2e', 'lib/'), + 'missing', + ); + }); + + it('follows a bare export star into a workspace sibling through the same read', () => { const files = new Map([ [ 'packages/e2e/package.json', @@ -541,13 +678,15 @@ describe('tagExportsAt', () => { ['e2e', 'packages/e2e'], ['@e2e-dev/core', 'packages/core'], ]); - const atAgent = tagExportsAt(read, 'packages/e2e', 'agent', (specifier) => resolveWorkspaceSpecifier(read, dirs, specifier)); + // The core manifest is read through the same `read` as the tag + // lookup, so the bare target cannot resolve against another version. + const atAgent = tagExportsAt(read, 'packages/e2e', 'agent', dirs); if (atAgent === undefined || atAgent === 'missing') assert.fail('expected export sets through the bare re-export'); assert.deepEqual([...atAgent.values], ['defineTool']); assert.deepEqual([...atAgent.types], ['DefinedTool']); }); - it('reads no names through a bare export star without a resolver', () => { + it('reads no names through a bare export star without package dirs', () => { const files = new Map([ [ 'packages/e2e/package.json', diff --git a/scripts/engine-exports.ts b/scripts/engine-exports.ts index 353f3f6bb4..b4c95aed27 100644 --- a/scripts/engine-exports.ts +++ b/scripts/engine-exports.ts @@ -393,28 +393,70 @@ function entryTypesTarget(entry: unknown): string | undefined { return undefined; } -/** The `types` target for `subpath` in an `exports` map: the exact key, or a `*` key whose pattern the subpath matches with the middle substituted. Undefined when no key covers it. */ -function exportTypesTarget(exports: Record | undefined, subpath: string): string | undefined { - if (exports === undefined) return undefined; +/** + * The `exports` keys covering `subpath`, best first: the exact key, then + * `*` keys by longest prefix before `*`, ties broken by longest key, the + * order Node resolves subpath patterns in. A `*` key covers the subpath + * only when the key is at least as long as the pattern (the `*` matches at + * least one character, so `./lib/` does not match `./lib/*`) and starts + * with the prefix and ends with the suffix. + */ +function coveringExportKeys(exports: Record | undefined, subpath: string): string[] { + if (exports === undefined) return []; const key = exportKey(subpath); - const exact = entryTypesTarget(exports[key]); - if (exact !== undefined) return exact; - for (const [pattern, value] of Object.entries(exports)) { + if (exports[key] !== undefined) return [key]; + const patterns: { pattern: string; prefix: string }[] = []; + for (const pattern of Object.keys(exports)) { const star = pattern.indexOf('*'); if (star === -1) continue; const prefix = pattern.slice(0, star); const suffix = pattern.slice(star + 1); - if (!key.startsWith(prefix) || !key.endsWith(suffix)) continue; - const target = entryTypesTarget(value); + if (key.length < pattern.length || !key.startsWith(prefix) || !key.endsWith(suffix)) continue; + patterns.push({ pattern, prefix }); + } + patterns.sort((a, b) => b.prefix.length - a.prefix.length || b.pattern.length - a.pattern.length); + return patterns.map(({ pattern }) => pattern); +} + +/** + * The `types` target for `subpath` in an `exports` map, following Node's + * subpath-pattern rules: the exact key wins, then the best `*` key, and + * every `*` in the target is replaced by the matched middle. A `null` + * target excludes the subpath outright, even when a shorter key would + * match. A key whose target has no `types` entry, or no `*` to substitute + * a per-subpath file, falls through to the next covering key. Undefined + * when no key covers it, or the covering key excludes it. + */ +function exportTypesTarget(exports: Record | undefined, subpath: string): string | undefined { + if (exports === undefined) return undefined; + const key = exportKey(subpath); + const exact = exports[key]; + if (exact !== undefined) { + // The exact key wins outright: a null target excludes the subpath, + // and a plain string target names the entry file as it is. + if (exact === null) return undefined; + return entryTypesTarget(exact); + } + for (const pattern of coveringExportKeys(exports, subpath)) { + const entry = exports[pattern]; + if (entry === null) return undefined; + const target = entryTypesTarget(entry); + // A pattern key with no `types` entry, or one that names no + // per-subpath file, falls through to the next covering key. if (target === undefined || !target.includes('*')) continue; - return target.replace('*', key.slice(prefix.length, key.length - suffix.length)); + const star = pattern.indexOf('*'); + const prefix = pattern.slice(0, star); + const suffix = pattern.slice(star + 1); + return target.replaceAll('*', key.slice(prefix.length, key.length - suffix.length)); } return undefined; } -/** Whether an `exports` map covers `subpath` at all, exactly or through a `*` key. */ +/** Whether an `exports` map covers `subpath` at all: an exact key or a `*` key, with a target that is not `null`. Only the best covering key counts: a `null` target on it excludes the subpath, even when a shorter key would match. */ function hasExportKey(exports: Record | undefined, subpath: string): boolean { - return exportTypesTarget(exports, subpath) !== undefined || exports?.[exportKey(subpath)] !== undefined; + if (exports === undefined) return false; + const [best] = coveringExportKeys(exports, subpath); + return best !== undefined && exports[best] !== null; } /** The entry file for a subpath from an already-parsed `exports` map. */ @@ -456,20 +498,24 @@ export function resolveWorkspaceSpecifier( /** * The export state of a sibling's subpath at a version. `readFile` reads a - * repo path at that version. Undefined when the tag record cannot be read - * (no manifest, unparseable manifest, unreadable entry). `'missing'` when - * the record exists but the sibling does not export that subpath there: - * every import from it is then a problem, not unverifiable. Empty sets - * when the entry exists but exports nothing: a side-effect import of it - * passes, a named import still fails on the name. An export entry with no - * types target stays unverifiable, since no entry file can be found for - * it that way. + * repo path at that version. `packageDirs` maps workspace package names to + * their directories: a bare `export *` into another workspace package is + * resolved through that package's manifest read by the same `readFile`, + * so the bare target is read at the same version as the tag lookup and + * the two reads cannot diverge. Undefined when the tag record cannot be + * read (no manifest, unparseable manifest, unreadable entry). `'missing'` + * when the record exists but the sibling does not export that subpath + * there: every import from it is then a problem, not unverifiable. Empty + * sets when the entry exists but exports nothing: a side-effect import of + * it passes, a named import still fails on the name. An export entry with + * no types target stays unverifiable, since no entry file can be found + * for it that way. */ export function tagExportsAt( readFile: (path: string) => string | undefined, siblingDir: string, subpath: string, - resolveBare?: BareSpecifierResolver, + packageDirs?: ReadonlyMap, ): TagExports | undefined { const manifest = readFile(`${siblingDir}/package.json`); if (manifest === undefined) return undefined; @@ -480,6 +526,8 @@ export function tagExportsAt( return undefined; } const entry = entryFileFromExports(exports, siblingDir, subpath); + const resolveBare: BareSpecifierResolver | undefined = + packageDirs === undefined ? undefined : (specifier: string): string | undefined => resolveWorkspaceSpecifier(readFile, packageDirs, specifier); if (entry !== undefined) return resolveEntryExports(readFile, entry, resolveBare); if (hasExportKey(exports, subpath)) return undefined; return 'missing'; diff --git a/scripts/peer-ranges.test.ts b/scripts/peer-ranges.test.ts index 4a5efd3b94..d538977e38 100644 --- a/scripts/peer-ranges.test.ts +++ b/scripts/peer-ranges.test.ts @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { describe, it } from 'node:test'; -import { applyFixedGroups, peerFloor, peerRangeProblems, releasedVersions, type PublicPackage } from './peer-ranges.ts'; +import { peerFloor, peerRangeProblems, releasedVersions, type PublicPackage } from './peer-ranges.ts'; function pkg(name: string, peers: Record): PublicPackage { return { path: `/repo/packages/${name}/package.json`, manifest: { name, version: '0.1.0', peerDependencies: peers } }; @@ -88,42 +88,13 @@ describe('peerRangeProblems', () => { const packages = [pkg('@e2e-dev/web', { e2e: '>=9.9.9 <1', zod: '^3.0.0' })]; assert.deepEqual(peerRangeProblems(packages, read), []); }); -}); - -describe('applyFixedGroups', () => { - it('releases every group member at the highest pending version', () => { - // e2e and @e2e-dev/core are a fixed group: the core package's first - // release is the runner's next version, not a 0.0.1 patch of its own. - const nextVersions = new Map([ - ['e2e', '0.23.2'], - ['@e2e-dev/core', '0.0.1'], - ]); - applyFixedGroups(nextVersions, [['e2e', '@e2e-dev/core']]); - assert.equal(nextVersions.get('e2e'), '0.23.2'); - assert.equal(nextVersions.get('@e2e-dev/core'), '0.23.2'); - }); - - it('releases an unbumped member alongside the bumped one', () => { - const nextVersions = new Map([['e2e', '0.23.2']]); - applyFixedGroups(nextVersions, [['e2e', '@e2e-dev/core']]); - assert.equal(nextVersions.get('@e2e-dev/core'), '0.23.2'); - }); - - it('leaves a group with no pending member alone', () => { - const nextVersions = new Map([['@e2e-dev/web', '0.16.1']]); - applyFixedGroups(nextVersions, [['e2e', '@e2e-dev/core']]); - assert.equal(nextVersions.has('e2e'), false); - assert.equal(nextVersions.has('@e2e-dev/core'), false); - assert.equal(nextVersions.get('@e2e-dev/web'), '0.16.1'); - }); - it('lets a fixed-group floor pass peerRangeProblems for a sibling with no changelog yet', () => { + it('lets a fixed-group floor pass for a sibling with no changelog yet', () => { const packages = [pkg('e2e', {}), pkg('@e2e-dev/core', {}), pkg('@e2e-dev/web', { '@e2e-dev/core': '>=0.23.2 <1' })]; const nextVersions = new Map([ ['e2e', '0.23.2'], - ['@e2e-dev/core', '0.0.1'], + ['@e2e-dev/core', '0.23.2'], ]); - applyFixedGroups(nextVersions, [['e2e', '@e2e-dev/core']]); assert.deepEqual(peerRangeProblems(packages, () => undefined, nextVersions), []); }); }); diff --git a/scripts/peer-ranges.ts b/scripts/peer-ranges.ts index e8b7b8e3fb..5f1ddacd06 100644 --- a/scripts/peer-ranges.ts +++ b/scripts/peer-ranges.ts @@ -17,7 +17,6 @@ */ import { relative } from 'node:path'; -import { compareVersions, parseVersion, type Semver } from './changeset-bumps.ts'; import { REPO_ROOT, isWidePeerRange, type PackageManifest } from './public-packages.ts'; export interface PublicPackage { @@ -83,27 +82,3 @@ export function peerRangeProblems( } return problems; } - -/** - * The version each member of a changesets `fixed` group will release at: - * a fixed group releases every member at one version, the highest next - * version any member's pending bump computes. Mutates `nextVersions` in - * place, setting every group member to that version, including one with - * no pending bump of its own: the group releases it alongside the bumped - * member. A group with no member in `nextVersions` is left alone. - */ -export function applyFixedGroups(nextVersions: Map, fixedGroups: readonly (readonly string[])[]): void { - for (const group of fixedGroups) { - let max: Semver | undefined; - for (const name of group) { - const version = nextVersions.get(name); - if (version === undefined) continue; - const parsed = parseVersion(version); - if (parsed === undefined) continue; - if (max === undefined || compareVersions(parsed, max) > 0) max = parsed; - } - if (max === undefined) continue; - const release = max.join('.'); - for (const name of group) nextVersions.set(name, release); - } -} From 0692ef58df033fbd51be4a68dd658425a8c45733 Mon Sep 17 00:00:00 2001 From: Varshith Puli Date: Mon, 16 Nov 2026 19:03:10 +0000 Subject: [PATCH 14/14] fix(release): compare workspace package versions against their own manifests The workspacePackages test pinned e2e at 0.23.1 and @e2e-dev/core at 0.0.0, so the next Version Packages run would fail it. Read the expected version from each package's own package.json instead; the test still fails if the helper drops a package or reads a wrong version (verified by mutating the helper to return 9.9.9). Signed-off-by: Varshith Puli --- scripts/check-helpers.test.ts | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/scripts/check-helpers.test.ts b/scripts/check-helpers.test.ts index cd8a9aeaaa..f6c6f023ed 100644 --- a/scripts/check-helpers.test.ts +++ b/scripts/check-helpers.test.ts @@ -1,10 +1,11 @@ import assert from 'node:assert/strict'; -import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { describe, it } from 'node:test'; import { parseChangesetFile } from '@changesets/parse'; import { collectEngineImports, nextReleaseVersions, workspacePackages, type ReleasePlanPackage } from './check-helpers.ts'; +import { REPO_ROOT } from './public-packages.ts'; describe('collectEngineImports', () => { it('names the file that fails to parse', () => { @@ -32,8 +33,18 @@ describe('workspacePackages', () => { it('reads the workspace packages with their versions', () => { const packages = workspacePackages(); const byName = new Map(packages.map((pkg) => [pkg.packageJson.name, pkg.packageJson.version])); - assert.equal(byName.get('e2e'), '0.23.1'); - assert.equal(byName.get('@e2e-dev/core'), '0.0.0'); + // Compare against each package's own manifest, not pinned versions: + // the next Version Packages run bumps both, and a pinned version + // here would fail there. The check still bites: a helper that drops + // a package, or reads a wrong version for one, fails against its + // own manifest. + for (const dir of ['e2e', 'core']) { + const manifest = JSON.parse(readFileSync(join(REPO_ROOT, 'packages', dir, 'package.json'), 'utf8')) as { + name: string; + version: string; + }; + assert.equal(byName.get(manifest.name), manifest.version); + } }); });