[PR #461] [CLOSED] feat: track stable Next.js API surface and contract coverage #588

New issue

Closed

opened 2026-05-06 13:08:55 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 13:08:55 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/461
Author: @Divkix
Created: 3/11/2026
Status: ❌ Closed

Base: main ← Head: feat/api-surface-tracking

📝 Commits (7)

d05744b feat: add Next.js API surface tracking system
bff631a fix: address review findings in API tracking system
1201980 feat: finish issue 454 API tracking follow-up
27ca2c5 fix: restore CI manifest fixtures and snapshots
1f813ac style: format manifest fixture dist files
307272e fix: silence lint in manifest fixtures
578e7f5 style: format lint-suppressed manifest fixtures

📊 Changes

54 files changed (+2353 additions, -92 deletions)

View changed files

📝 .github/workflows/ci.yml (+8 -0)
➕ .github/workflows/nextjs-api-track.yml (+108 -0)
📝 .github/workflows/tip.yml (+20 -0)
📝 .gitignore (+2 -0)
➕ api-manifest.json (+152 -0)
➕ known-gaps.json (+72 -0)
📝 packages/vinext/src/entries/app-rsc-entry.ts (+1 -1)
📝 packages/vinext/src/index.ts (+2 -83)
➕ packages/vinext/src/shims/coverage.ts (+139 -0)
➕ packages/vinext/src/shims/registry.ts (+116 -0)
➕ scripts/check-shim-coverage.ts (+71 -0)
➕ scripts/diff-nextjs-api.ts (+156 -0)
➕ scripts/extract-nextjs-api.ts (+234 -0)
📝 tests/__snapshots__/entry-templates.test.ts.snap (+6 -6)
➕ tests/api-manifest.test.ts (+340 -0)
📝 tests/app-router.test.ts (+28 -0)
➕ tests/contracts/_helpers.ts (+166 -0)
➕ tests/contracts/http.contract.test.ts (+44 -0)
➕ tests/fixtures/app-basic/app/contracts/api/cookies-mutable/route.ts (+8 -0)
➕ tests/fixtures/app-basic/app/contracts/api/headers-readonly/route.ts (+13 -0)

...and 34 more files

📄 Description

Closes #454

Summary

This PR finishes the stable API-tracking work for vinext's Next.js compatibility layer.

It adds three things that now work together:

discovery-based API manifest extraction from the published next package
strict shim coverage enforcement against that manifest plus known-gaps.json
a real dual-target HTTP contract suite that runs against vinext and real next dev

It also moves the server-action redirect 303 assertion out of the shared contract layer and into the regular App Router regression suite, because that flow depends on vinext's action transport details.

What Changed

replaced the extractor's hard-coded module lists with published-package discovery and directory re-export support
regenerated api-manifest.json for next@16.1.6
expanded known-gaps.json for intentional gaps surfaced by discovery (next/babel and experimental test helpers)
hardened .github/workflows/nextjs-api-track.yml to work from npm pack output and de-dupe issues by version marker
replaced the vinext-only behavioral contract file with a shared dual-target HTTP contract suite
moved the 303 server-action redirect assertion into tests/app-router.test.ts
pinned the shared fixture server helper to 127.0.0.1 for reliable local server boot in tests

Scope Notes

manifest enforcement is runtime-only in v1
extra migration shims may still exist outside manifest coverage when they are not part of the stable published runtime surface
server-action redirect coverage stays in the vinext regression suite, not the shared contract suite

Verification

pnpm test tests/api-manifest.test.ts tests/manifest-diff.test.ts tests/shim-coverage.test.ts
pnpm test tests/app-router.test.ts -t "uses 303 for server action redirects"
pnpm test tests/contracts/http.contract.test.ts
CONTRACT_TARGET=nextjs pnpm test tests/contracts/http.contract.test.ts
pnpm test tests/shims.test.ts
manifest parity against the published next@16.1.6 package
coverage parity check against the updated manifest
pnpm run typecheck
pnpm run lint
pnpm run fmt:check

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/cloudflare/vinext/pull/461 **Author:** [@Divkix](https://github.com/Divkix) **Created:** 3/11/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `feat/api-surface-tracking` --- ### 📝 Commits (7) - [`d05744b`](https://github.com/cloudflare/vinext/commit/d05744bc638ab88dd9af5af6b0095f69f3d717e6) feat: add Next.js API surface tracking system - [`bff631a`](https://github.com/cloudflare/vinext/commit/bff631a14ed881442db3508ea10619c6f5aae744) fix: address review findings in API tracking system - [`1201980`](https://github.com/cloudflare/vinext/commit/1201980d416bd4720e1c93a91bcbe08c09e04849) feat: finish issue 454 API tracking follow-up - [`27ca2c5`](https://github.com/cloudflare/vinext/commit/27ca2c526d9a9e33993fdb5695c1a23e1d54f136) fix: restore CI manifest fixtures and snapshots - [`1f813ac`](https://github.com/cloudflare/vinext/commit/1f813acfd40459adca34145c6e2e82e19e5a383d) style: format manifest fixture dist files - [`307272e`](https://github.com/cloudflare/vinext/commit/307272e14d005a1b77430a593211073435c233ed) fix: silence lint in manifest fixtures - [`578e7f5`](https://github.com/cloudflare/vinext/commit/578e7f5160c784bcaf4daf4e1eacc80376f0bde7) style: format lint-suppressed manifest fixtures ### 📊 Changes **54 files changed** (+2353 additions, -92 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/ci.yml` (+8 -0) ➕ `.github/workflows/nextjs-api-track.yml` (+108 -0) 📝 `.github/workflows/tip.yml` (+20 -0) 📝 `.gitignore` (+2 -0) ➕ `api-manifest.json` (+152 -0) ➕ `known-gaps.json` (+72 -0) 📝 `packages/vinext/src/entries/app-rsc-entry.ts` (+1 -1) 📝 `packages/vinext/src/index.ts` (+2 -83) ➕ `packages/vinext/src/shims/coverage.ts` (+139 -0) ➕ `packages/vinext/src/shims/registry.ts` (+116 -0) ➕ `scripts/check-shim-coverage.ts` (+71 -0) ➕ `scripts/diff-nextjs-api.ts` (+156 -0) ➕ `scripts/extract-nextjs-api.ts` (+234 -0) 📝 `tests/__snapshots__/entry-templates.test.ts.snap` (+6 -6) ➕ `tests/api-manifest.test.ts` (+340 -0) 📝 `tests/app-router.test.ts` (+28 -0) ➕ `tests/contracts/_helpers.ts` (+166 -0) ➕ `tests/contracts/http.contract.test.ts` (+44 -0) ➕ `tests/fixtures/app-basic/app/contracts/api/cookies-mutable/route.ts` (+8 -0) ➕ `tests/fixtures/app-basic/app/contracts/api/headers-readonly/route.ts` (+13 -0) _...and 34 more files_ </details> ### 📄 Description Closes #454 ## Summary This PR finishes the stable API-tracking work for vinext's Next.js compatibility layer. It adds three things that now work together: - discovery-based API manifest extraction from the published `next` package - strict shim coverage enforcement against that manifest plus `known-gaps.json` - a real dual-target HTTP contract suite that runs against vinext and real `next dev` It also moves the server-action redirect `303` assertion out of the shared contract layer and into the regular App Router regression suite, because that flow depends on vinext's action transport details. ## What Changed - replaced the extractor's hard-coded module lists with published-package discovery and directory re-export support - regenerated `api-manifest.json` for `next@16.1.6` - expanded `known-gaps.json` for intentional gaps surfaced by discovery (`next/babel` and experimental test helpers) - hardened `.github/workflows/nextjs-api-track.yml` to work from `npm pack` output and de-dupe issues by version marker - replaced the vinext-only behavioral contract file with a shared dual-target HTTP contract suite - moved the `303` server-action redirect assertion into `tests/app-router.test.ts` - pinned the shared fixture server helper to `127.0.0.1` for reliable local server boot in tests ## Scope Notes - manifest enforcement is runtime-only in v1 - extra migration shims may still exist outside manifest coverage when they are not part of the stable published runtime surface - server-action redirect coverage stays in the vinext regression suite, not the shared contract suite ## Verification - `pnpm test tests/api-manifest.test.ts tests/manifest-diff.test.ts tests/shim-coverage.test.ts` - `pnpm test tests/app-router.test.ts -t "uses 303 for server action redirects"` - `pnpm test tests/contracts/http.contract.test.ts` - `CONTRACT_TARGET=nextjs pnpm test tests/contracts/http.contract.test.ts` - `pnpm test tests/shims.test.ts` - manifest parity against the published `next@16.1.6` package - coverage parity check against the updated manifest - `pnpm run typecheck` - `pnpm run lint` - `pnpm run fmt:check` --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>