diff --git a/.changeset/browser-run-web-peer-floor.md b/.changeset/browser-run-web-peer-floor.md new file mode 100644 index 000000000..a1bae1a5e --- /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/.changeset/engine-peer-floors.md b/.changeset/engine-peer-floors.md new file mode 100644 index 000000000..517b2bbf4 --- /dev/null +++ b/.changeset/engine-peer-floors.md @@ -0,0 +1,7 @@ +--- +"@e2e-dev/acp": patch +"@e2e-dev/limrun": patch +--- + +- 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/AGENTS.md b/AGENTS.md index e1d50d851..6f2479cf0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -719,7 +719,14 @@ 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 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 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/package.json b/package.json index dd8e1e076..634ae2bce 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", @@ -52,6 +54,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/packages/acp/package.json b/packages/acp/package.json index c804bf40f..d4606cb12 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/browser-run/package.json b/packages/browser-run/package.json index f8bae61ba..d33f9a59d 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:*", diff --git a/packages/limrun/package.json b/packages/limrun/package.json index 3c419263d..785319b63 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.12.0 <1", "@limrun/api": ">=0.59.0 <1", "e2e": ">=0.15.0 <1" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c161c1ef1..7431a18ab 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 @@ -151,6 +157,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.test.ts b/scripts/changeset-bumps.test.ts index 5af9d0fe5..1b653ca05 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, + latestReleaseVersion, + parseVersion, + versionBumpAnnounces, + type FloorRaiseInput, +} from './changeset-bumps.ts'; const versions = new Map([ ['e2e', '0.20.0'], @@ -36,3 +45,155 @@ 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 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.'), false); + 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, + announcedByVersionBump: 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('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', () => { + assert.deepEqual( + floorRaiseProblems([input([{ type: 'patch', summary: 'Names the released floor.' }], { previousFloor: '0.22.1' })]), + [], + ); + }); + + 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 })]), + [], + ); + }); +}); + +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']; + + 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('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 2d2fa960c..2aa417bcc 100644 --- a/scripts/changeset-bumps.ts +++ b/scripts/changeset-bumps.ts @@ -9,6 +9,17 @@ * 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): 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'; @@ -25,3 +36,122 @@ 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 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); + 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; + 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 }; + +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; + /** 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. 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( + (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 037084c48..d2bcdc978 100644 --- a/scripts/check-changeset-bumps.ts +++ b/scripts/check-changeset-bumps.ts @@ -1,32 +1,115 @@ /** * 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; 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 { readFileSync, readdirSync } from 'node:fs'; -import { join } 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 { relative } from 'node:path'; +import { listTags, pendingChangesets, readChangelog, showAtTag } from './check-helpers.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'; + +/** 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 { + 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 pending = pendingChangesets(); 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 { file, changeset } of pending) { + 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 pending) { + 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); + } +} + +// 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)); +const inputs: FloorRaiseInput[] = []; +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)); + const fellBack = tagManifest === undefined; + if (fellBack) tagManifest = previousReleaseManifest(manifest.name, 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; + const changelog = readChangelog(sibling.path); + 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), + announcedByVersionBump: fellBack && previous.version !== undefined && versionBumpAnnounces(previous.version, manifest.version), + }); + } +} +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: ${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.test.ts b/scripts/check-helpers.test.ts new file mode 100644 index 000000000..f6c6f023e --- /dev/null +++ b/scripts/check-helpers.test.ts @@ -0,0 +1,102 @@ +import assert from 'node:assert/strict'; +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', () => { + 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 }); + } + }); +}); + +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])); + // 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); + } + }); +}); + +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 new file mode 100644 index 000000000..ec3e835fb --- /dev/null +++ b/scripts/check-helpers.ts @@ -0,0 +1,182 @@ +/** + * Shared file and git reads for the release check scripts: the tag lookup, + * 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 { + 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'))) { + 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; +} + +/** 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, 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') + .toSorted(); + return files.map((file) => ({ file, changeset: parseChangesetFile(readFileSync(join(dir, file), 'utf8')) })); +} + +/** 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 { + rootManifest = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')) as { name: string; version: string }; + } catch { + 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 dc573ebee..84a6da6ba 100644 --- a/scripts/check-peer-ranges.ts +++ b/scripts/check-peer-ranges.ts @@ -1,41 +1,109 @@ /** * 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 (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 - * 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. + * 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 { relative } from 'node:path'; -import { REPO_ROOT, isWidePeerRange, publicPackages, siblingPeers } from './public-packages.ts'; +import { readFileSync } from 'node:fs'; +import { dirname, join, relative } from 'node:path'; +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(); 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 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. +const pending = pendingChangesets(); +const nextVersions = await nextReleaseVersions(workspacePackages(), pending); + +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. +const siblingDirs = new Map(packages.map(({ manifest, path }) => [manifest.name, relative(REPO_ROOT, dirname(path))])); +const exportsCache = new Map(); + +/** Reads `path` from the working tree, undefined when it cannot be read. */ +function showWorkingTree(path: string): string | undefined { + try { + return readFileSync(join(REPO_ROOT, path), 'utf8'); + } catch { + return 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); + const tagRead = (path: string): string | undefined => showAtTag(`${sibling}@${version}`, path); + 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, siblingDirs); + } + 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 = 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, 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\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 new file mode 100644 index 000000000..9d1b9c47e --- /dev/null +++ b/scripts/engine-exports.test.ts @@ -0,0 +1,992 @@ +import assert from 'node:assert/strict'; +import { describe, it } from 'node:test'; +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', () => { + 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 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 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('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 default binding', () => { + const imports = engineImports(`import def from 'e2e/nope';\n`); + 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', () => { + 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( + imports.get('engine'), + new Map([ + ['stepTimeout', 'value'], + ['EngineError', 'value'], + ['EngineDoctorCheck', 'type'], + ]), + ); + }); + + 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([ + ['stepTimeout', 'value'], + ['EngineDoctorCheck', 'type'], + ]), + ); + }); + + 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('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. + 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']])); + }); + + it('ignores imports from other packages', () => { + assert.equal(engineImports(`import { z } from 'zod';\n`).size, 0); + }); +}); + +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([ + [ + '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?.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('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`], + ['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 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', + `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('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'); + 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`], + ['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); + }); + + 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); + }); + + 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('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. + 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 ?? [])], []); + }); + + 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', () => { + 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('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([ + ['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', () => { + // 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' }, + './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 = { + 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 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', () => { + const { problems, unverifiable, verified } = engineImportProblems( + [agentCheck], + (_sibling, subpath) => tagExportsAt(readAtTag, 'packages/e2e', subpath), + ); + assert.equal(problems.length, 1); + 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); + }); + + 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, + ); + }); + + 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', + 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'], + ]); + // 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 package dirs', () => { + 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', () => { + 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 { 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 { 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', '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', () => { + 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 Map([['*', 'value']])]]))], + () => 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']])]]))], + () => 'missing', + ); + 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()]]))], + () => '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()]]))], + () => exported(['stepTimeout']), + ); + assert.deepEqual(problems, []); + assert.deepEqual(unverifiable, []); + 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', + 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']])]]))], + () => 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/); + }); + + 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('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 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('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`], + [ + '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 new file mode 100644 index 000000000..b4c95aed2 --- /dev/null +++ b/scripts/engine-exports.ts @@ -0,0 +1,601 @@ +/** + * 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 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 + * 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 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'; + +/** 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>; + +/** 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; +} + +/** 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); + } +} + +/** Merges `names` into `target`'s map for `subpath`, creating it when absent. */ +function mergeInto(target: Map>, 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; + 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 !== '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; 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 => { + mergeInto(found, subpath, names); + }; + 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, 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']]); + } + } + } + // 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; + 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, 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. 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') { + 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; + const subpath = e2eSubpath(sourceSpecifier); + if (subpath === undefined) return; + add(subpath, [['*', 'value']]); + }); + return found; +} + +/** 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) { + mergeInto(target, subpath, names); + } +} + +/** 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 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; + starModules: readonly string[]; + typeStarModules: readonly string[]; +} { + const parsed = parseModule(source); + const values = new Set(); + const types = new Set(); + const starModules: string[] = []; + const typeStarModules: string[] = []; + 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' || 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 === '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); + 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); + } + } + return { values, types, starModules, typeStarModules }; +} + +/** The names an entry exports, split by kind. */ +export interface ExportSets { + readonly values: ReadonlySet; + 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; + 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('/'); +} + +/** + * 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, + resolveBare?: BareSpecifierResolver, +): ExportSets | undefined { + const values = new Set(); + const types = new Set(); + const seen = new Set(); + const queue: [string, boolean][] = [[entryPath, false]]; + while (queue.length > 0) { + 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 exported = exportedNames(source); + // 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); + } + const enqueue = (specifier: string, asType: boolean): void => { + 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); + for (const specifier of exported.typeStarModules) enqueue(specifier, true); + } + return { values, types }; +} + +/** + * 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 exports: Record | undefined; + try { + exports = (JSON.parse(packageJson) as { exports?: Record }).exports; + } catch { + return undefined; + } + 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 `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); + 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.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; + 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: 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 { + 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. */ +function entryFileFromExports(exports: Record | undefined, siblingDir: string, subpath: string): string | 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. `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, + packageDirs?: ReadonlyMap, +): TagExports | undefined { + const manifest = readFile(`${siblingDir}/package.json`); + if (manifest === undefined) return undefined; + let exports: Record | undefined; + try { + exports = (JSON.parse(manifest) as { exports?: Record }).exports; + } catch { + 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'; +} + +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. 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 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( + checks: readonly EngineImportCheck[], + exportsAt: (sibling: string, subpath: string, version: string) => TagExports | undefined, +): { 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 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; + } + 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) + .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)`, + ); + } + } + if (checked && allResolved) verified += 1; + } + return { problems, unverifiable, verified }; +} diff --git a/scripts/peer-ranges.test.ts b/scripts/peer-ranges.test.ts new file mode 100644 index 000000000..d538977e3 --- /dev/null +++ b/scripts/peer-ranges.test.ts @@ -0,0 +1,100 @@ +import assert from 'node:assert/strict'; +import { describe, it } from 'node:test'; +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('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), []); + }); + + 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.23.2'], + ]); + assert.deepEqual(peerRangeProblems(packages, () => undefined, nextVersions), []); + }); +}); diff --git a/scripts/peer-ranges.ts b/scripts/peer-ranges.ts new file mode 100644 index 000000000..5f1ddacd0 --- /dev/null +++ b/scripts/peer-ranges.ts @@ -0,0 +1,84 @@ +/** + * 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 + * 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'; +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 sibling's 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) { + 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 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`, + ); + } + } + } + return problems; +}