@thomas.f/prnext 0.1.18-alpha → 0.1.20-alpha

package/build/migration-audit.mjs

@@ -1,36 +1,27 @@
-import { parse } from '@babel/parser';
-import { readdir, readFile, stat } from 'node:fs/promises';
+import { readdir, readFile, realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { checkProject } from './check.mjs';
-import { frameworkImportName } from './framework-imports.mjs';
 import { packageManifest } from '../native/resolve.mjs';
+import { auditImportGraph } from './migration-imports.mjs';
 
-const supported = new Set([...Object.keys(packageManifest.exports).map(name => frameworkImportName(name.slice(2))), 'font/google', 'font/local', 'next-router-context', 'next-app-router-context']);
 const ignored = new Set(['node_modules', '.git', '.next', '.prnext', '.prnext-cache', 'dist', 'build', 'out', 'coverage', 'test-results', '__tests__']);
 const code = /\.(?:[cm]?[jt]s|[jt]sx)$/;
-function walkAst(node, visit) {
-  if (!node || typeof node !== 'object') return;
-  if (typeof node.type === 'string') visit(node);
-  for (const [key, value] of Object.entries(node)) {
-    if (['loc', 'comments', 'tokens', 'extra'].includes(key)) continue;
-    if (Array.isArray(value)) for (const child of value) walkAst(child, visit);
-    else if (value && typeof value === 'object') walkAst(value, visit);
-  }
-}
 
 /** A bounded source audit. It never runs a build, installs packages, or edits the project. */
 export async function auditMigration(directory) {
-  const root = path.resolve(directory);
+  const requestedRoot = path.resolve(directory);
+  const root = await realpath(requestedRoot).catch(() => requestedRoot);
   const preflight = await checkProject(root, { validateDependencies: false });
-  const report = { version: 1, root, ok: false, status: 'checked', files: 0, routes: preflight.routes,
+  const report = { version: 2, root, ok: false, status: 'checked', files: 0, routes: preflight.routes,
     versions: preflight.versions, findings: [], imports: [], notes: [
-      'This source audit does not execute application routes or inspect every installed dependency. Run a production build and browser tests before switching.',
+      'This source audit follows imported dependencies without executing them. A checked import is not proof that the application works. Run a production build and browser tests before switching.',
       'Configuration files are evaluated by preflight. Application sources and package files are not modified.',
     ] };
   const finding = (severity, id, file, line, message, action) => report.findings.push({ severity, id, file, line, message, action });
   for (const error of preflight.errors) finding('error', 'preflight', null, null, error, 'Fix the configuration or route convention, then run the check again.');
   let bytes = 0;
+  const sources = [];
   async function scan(dir) {
     for (const item of (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
       if (ignored.has(item.name) || item.name.startsWith('.prnext-')) continue;
@@ -39,25 +30,22 @@ export async function auditMigration(directory) {
       if (item.isDirectory()) { await scan(filename); continue; }
       if (!item.isFile() || !code.test(item.name) || /(?:\.d|\.test|\.spec)\.[cm]?[jt]sx?$/.test(item.name)) continue;
       if (++report.files > 5000 || (bytes += (await stat(filename)).size) > 32 * 1024 ** 2) throw new Error('Source audit exceeds 5000 files or 32 MiB. Choose the application directory.');
-      const source = await readFile(filename, 'utf8');
-      let ast;
-      try { ast = parse(source, { sourceType: 'unambiguous', plugins: ['jsx', ...( /\.[cm]?tsx?$/.test(item.name) ? ['typescript'] : []), 'decorators-legacy'] }); }
-      catch (error) { finding('warning', 'source-syntax', file, error.loc?.line || 1, 'The audit could not parse this source file.', 'Validate it with the production compiler; custom loaders may be required.'); continue; }
-      const client = ast.program.directives.some(directive => directive.value.value === 'use client');
-      walkAst(ast.program, node => {
-        const specifier = ['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration'].includes(node.type) && node.importKind !== 'type' && node.exportKind !== 'type' ? node.source?.value
-          : node.type === 'CallExpression' && (node.callee.type === 'Import' || node.callee.name === 'require') ? node.arguments[0]?.value : undefined;
-        if (typeof specifier !== 'string' || !(specifier === 'next' || specifier.startsWith('next/'))) return;
-        if (node.type === 'ImportDeclaration' && node.specifiers.length && node.specifiers.every(value => value.importKind === 'type')) return;
-        const name = frameworkImportName(specifier), available = supported.has(name);
-        report.imports.push({ file, line: node.loc.start.line, specifier, supported: available });
-        if (!available) finding('error', 'unsupported-import', file, node.loc.start.line, `No PRNext runtime adapter for ${specifier}.`, 'Replace this import with a supported public API or keep this route on Next.js.');
-        else if (client && ['headers', 'cache', 'server', 'og'].includes(name)) finding('error', 'server-import-in-client', file, node.loc.start.line, `${specifier} is imported by a client module.`, 'Move the server operation into a Server Component or Server Action.');
-      });
+      sources.push(filename);
     }
   }
   try { await scan(root); }
   catch (error) { finding('error', 'scan-incomplete', null, null, error.message, 'Resolve the file access or size limit and run the check again.'); }
+  try {
+    const graph = await auditImportGraph(root, sources);
+    report.imports = graph.imports;
+    report.findings.push(...graph.findings);
+    report.dependencies = graph.dependencies;
+    report.evidence = graph.evidence;
+    if (report.findings.some(item => ['linked-source', 'scan-incomplete'].includes(item.id))) report.evidence.state = 'unknown';
+  } catch {
+    finding('warning', 'import-graph-incomplete', null, null, 'The imported dependency graph could not be checked.', 'Run a production build and application tests before migrating.');
+    report.evidence = { state: 'unknown', scope: 'The imported dependency graph could not be checked.' };
+  }
   let pkg = {};
   try { pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8')); }
   catch (error) { finding('error', 'package-json', 'package.json', null, error.message, 'Provide a valid package.json in the application directory.'); }

package/build/migration-imports.mjs

@@ -0,0 +1,245 @@
+import { parse } from '@babel/parser';
+import { context as esbuildContext } from 'esbuild';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { builtinModules } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { frameworkImportName, frameworkRuntimeImportPattern } from './framework-imports.mjs';
+import { packageManifest } from '../native/resolve.mjs';
+
+const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+const builtins = new Set(builtinModules.flatMap(name => [name, `node:${name}`]));
+const code = /\.(?:[cm]?[jt]s|[jt]sx)$/;
+const slash = name => name.split(path.sep).join('/');
+const limits = Object.freeze({ modules: 2000, edges: 12000, bytes: 32 * 1024 ** 2, depth: 32, findings: 2000 });
+const isType = node => node.importKind === 'type' || node.exportKind === 'type';
+const literal = node => node?.type === 'StringLiteral' ? node.value : undefined;
+const property = node => node && (!node.computed && node.property?.name || literal(node.property));
+
+function walk(node, visit) {
+  if (!node || typeof node !== 'object') return;
+  if (typeof node.type === 'string') visit(node);
+  for (const [key, value] of Object.entries(node)) {
+    if (['loc', 'comments', 'tokens', 'extra'].includes(key)) continue;
+    if (Array.isArray(value)) for (const child of value) walk(child, visit);
+    else if (value && typeof value === 'object') walk(value, visit);
+  }
+}
+
+function sourceImports(ast) {
+  const found = [], calls = new Map();
+  walk(ast.program, node => {
+    if (isType(node)) return;
+    if (['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration'].includes(node.type) && node.source) {
+      const entries = (node.specifiers || []).filter(item => !isType(item));
+      if (node.specifiers?.length && !entries.length) return;
+      const names = entries.filter(item => item.type !== 'ImportNamespaceSpecifier').map(item => item.type === 'ImportDefaultSpecifier' ? 'default' : item.imported?.name || item.imported?.value || item.local?.name).filter(Boolean);
+      found.push({ specifier: node.source.value, line: node.loc.start.line, names, kind: 'import-statement' });
+    }
+    if (node.type === 'CallExpression' && (node.callee.type === 'Import' || node.callee.type === 'Identifier' && node.callee.name === 'require')) {
+      const specifier = literal(node.arguments[0]);
+      if (specifier !== undefined) { const item = { specifier, line: node.loc.start.line, names: [], kind: node.callee.type === 'Import' ? 'dynamic-import' : 'require-call' }; found.push(item); calls.set(node, item); }
+      else if (node.arguments.length) found.push({ specifier: null, line: node.loc.start.line, names: [], kind: 'computed-import' });
+    }
+  });
+  walk(ast.program, node => {
+    if (node.type !== 'VariableDeclarator' || node.id.type !== 'ObjectPattern' || !calls.has(node.init)) return;
+    calls.get(node.init).names = node.id.properties.filter(item => item.type === 'ObjectProperty' && !item.computed).map(item => item.key.name || item.key.value);
+  });
+  return found;
+}
+
+// Read adapter declarations, never require an adapter or execute application code.
+async function adapterExports(filename) {
+  const ast = parse(await readFile(filename, 'utf8'), { sourceType: 'unambiguous', plugins: ['jsx'] });
+  const names = new Set(), cjs = filename.endsWith('.cjs');
+  let complete = true;
+  walk(ast.program, node => {
+    if (node.type === 'AssignmentExpression' && node.left.type === 'MemberExpression') {
+      const left = node.left, object = left.object;
+      const moduleExports = object?.type === 'Identifier' && object.name === 'module' && property(left) === 'exports';
+      const named = object?.type === 'Identifier' && object.name === 'exports' || object?.type === 'MemberExpression' && object.object?.name === 'module' && property(object) === 'exports';
+      if (moduleExports) {
+        names.add('default');
+        if (node.right.type === 'ObjectExpression') for (const item of node.right.properties) {
+          if (item.type === 'SpreadElement' || item.computed) complete = false;
+          else names.add(item.key.name || item.key.value);
+        }
+        else if (!['Identifier', 'FunctionExpression', 'ArrowFunctionExpression', 'ClassExpression'].includes(node.right.type)) complete = false;
+      }
+      else if (named && property(left)) names.add(property(left));
+    }
+    if (node.type === 'ExportDefaultDeclaration') names.add('default');
+    if (node.type === 'ExportAllDeclaration') complete = false;
+    if (node.type === 'ExportNamedDeclaration') {
+      for (const item of node.specifiers) names.add(item.exported?.name || item.exported?.value);
+      const declaration = node.declaration;
+      if (declaration?.id?.name) names.add(declaration.id.name);
+      for (const item of declaration?.declarations || []) if (item.id.type === 'Identifier') names.add(item.id.name); else complete = false;
+    }
+  });
+  if (cjs) names.add('default');
+  return { names, complete };
+}
+
+function adapterFile(name) {
+  if (name === 'next-router-context' || name === 'next-app-router-context') return path.join(packageRoot, `compat/${name}.cjs`);
+  const exported = name === 'redis-cache' ? 'cache/redis' : name;
+  let target = packageManifest.exports[`./${exported}`];
+  if (target && typeof target === 'object') target = target.default;
+  return typeof target === 'string' && code.test(target) ? path.resolve(packageRoot, target) : null;
+}
+
+/** Follow only imported modules. Resolution reads package metadata; no module is loaded. */
+export async function auditImportGraph(root, sourceFiles) {
+  // Resolved modules already use physical paths. Match the root to that same
+  // coordinate system (Windows DOS aliases and macOS /var links included).
+  // A missing/unreadable root retains the existing unknown/error diagnostics.
+  root = await realpath(path.resolve(root)).catch(() => path.resolve(root));
+  const findings = [], imports = [], dependencies = new Map(), seen = new Set(), physical = new Set(), adapters = new Map();
+  const queue = sourceFiles.map(filename => ({ filename, chain: [], realm: 'node', package: null }));
+  let bytes = 0, edges = 0, unknown = 0, limited = false;
+  const emitted = new Set(), resolvers = new Map();
+  const fileLabel = item => item.package ? `npm:${item.package.name}/${slash(path.relative(item.package.root, item.filename))}` : slash(path.relative(root, item.filename));
+  function finding(item, entry, id, severity, message, action) {
+    const key = `${fileLabel(item)}:${entry?.line || 0}:${id}:${entry?.specifier || ''}:${message}`;
+    if (emitted.has(key)) return;
+    if (findings.length >= limits.findings) { limited = true; return; }
+    emitted.add(key);
+    findings.push({ severity, id, file: fileLabel(item), line: entry?.line || 1, message, action, chain: item.chain });
+  }
+  async function resolve(specifier, item, kind, realm) {
+    if (!resolvers.has(realm)) {
+      let builder;
+      const context = await esbuildContext({ absWorkingDir: root, stdin: { contents: '', resolveDir: root }, bundle: true, write: false, logLevel: 'silent', platform: realm === 'browser' ? 'browser' : 'node', conditions: realm === 'rsc' ? ['react-server'] : [], plugins: [{ name: 'migration-resolver', setup(build) { builder = build; } }] });
+      resolvers.set(realm, { context, builder });
+    }
+    return resolvers.get(realm).builder.resolve(specifier, { resolveDir: path.dirname(item.filename), importer: item.filename, kind });
+  }
+  async function packageFor(filename, specifier, inherited) {
+    if (specifier.startsWith('.') || path.isAbsolute(specifier)) return inherited;
+    // Package roots are discovered upward from the resolved file, including pnpm
+    // stores and workspace symlinks. Never enumerate their sibling packages.
+    const name = specifier.startsWith('@') ? specifier.split('/').slice(0, 2).join('/') : specifier.split('/')[0];
+    let directory = path.dirname(filename);
+    for (let depth = 0; depth < 32; depth++) {
+      try {
+        const metadata = JSON.parse(await readFile(path.join(directory, 'package.json'), 'utf8'));
+        if (metadata.name === name) return { name, version: typeof metadata.version === 'string' ? metadata.version : null, root: directory };
+      } catch {}
+      const parent = path.dirname(directory); if (parent === directory) break; directory = parent;
+    }
+    return null;
+  }
+  try {
+    for (let index = 0; index < queue.length; index++) {
+      const item = queue[index];
+      if (physical.size >= limits.modules || edges >= limits.edges || bytes >= limits.bytes) { limited = true; break; }
+      let filename, source, ast;
+      try {
+        filename = await realpath(item.filename);
+        const key = `${filename}:${item.realm}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        const info = await stat(filename);
+        if (!info.isFile() || info.size > limits.bytes - bytes) { limited = true; break; }
+        bytes += info.size; physical.add(filename);
+        source = await readFile(filename, 'utf8');
+        ast = parse(source, { sourceType: 'unambiguous', plugins: ['jsx', ...( /\.[cm]?tsx?$/.test(filename) ? ['typescript'] : []), 'decorators-legacy'] });
+      } catch {
+        unknown++;
+        finding(item, null, 'source-syntax', 'warning', 'This imported source could not be read or parsed.', 'Run a production build with the application loaders to validate this module.');
+        continue;
+      }
+      item.filename = filename;
+      const client = ast.program.directives.some(value => value.value.value === 'use client');
+      const action = ast.program.directives.some(value => value.value.value === 'use server');
+      if (/\.[cm]ts$/i.test(filename)) {
+        let directive = ast.program.directives.find(value => ['use client', 'use server'].includes(value.value.value));
+        walk(ast.program, node => { if (!directive && node.type === 'Directive' && node.value.value === 'use server') directive = node; });
+        if (directive) finding(item, { line: directive.loc.start.line }, 'unsupported-boundary-extension', 'error',
+          'React server/client directives are not supported in .mts or .cts modules.', 'Rename this boundary module to .ts or .tsx, then run the audit again.');
+      }
+      // App rendering entries execute with react-server conditions; Route
+      // Handlers and ordinary Node helpers do not. Keep the Node oracle too.
+      const relative = slash(path.relative(root, filename));
+      if (item.realm === 'node' && !client && !item.package && /^(?:src\/)?app\/(?:[^/]+\/)*(?:page|layout|template|loading|error|global-error|not-found|default)\.[cm]?[jt]sx?$/.test(relative)) {
+        queue.push({ ...item, realm: 'rsc' });
+      }
+      // The browser compiler replaces a module-level Server Action with client
+      // references; its implementation and imports execute in the RSC graph.
+      // Continue auditing that graph instead of either reporting client-only
+      // violations or skipping server dependencies. A function-body directive
+      // is not an importable boundary, and 'use client' still takes precedence.
+      const realm = client ? 'browser' : action && item.realm === 'browser' ? 'rsc' : item.realm;
+      for (const entry of sourceImports(ast)) {
+        if (++edges > limits.edges) { limited = true; break; }
+        if (!entry.specifier) { unknown++; finding(item, entry, 'computed-import', 'info', 'A computed import needs runtime validation.', 'Exercise this code path in the production build and application tests.'); continue; }
+        // These are compiler markers, not packages to execute or traverse.
+        if (entry.specifier === 'server-only' || entry.specifier === 'client-only') {
+          if (entry.specifier === 'server-only' && realm === 'browser') finding(item, entry, 'server-only-in-client', 'error',
+            'A server-only module is reachable from a Client Component.', 'Move this import behind a Server Component or module-level Server Action boundary.');
+          if (entry.specifier === 'client-only' && realm === 'rsc') finding(item, entry, 'client-only-in-server', 'error',
+            'A client-only module is reachable from a Server Component.', "Add a 'use client' boundary around this browser code.");
+          continue;
+        }
+        if (frameworkRuntimeImportPattern.test(entry.specifier)) {
+          const name = frameworkImportName(entry.specifier), target = adapterFile(name), available = !!target;
+          imports.push({ file: fileLabel(item), line: entry.line, specifier: entry.specifier, supported: available, exports: entry.names, chain: item.chain });
+          if (!available) finding(item, entry, 'unsupported-import', 'error', `No PRNext runtime adapter for ${entry.specifier}.`, 'Replace this import with a supported public API or keep this route on Next.js.');
+          else {
+            if (!adapters.has(target)) adapters.set(target, await adapterExports(target));
+            const adapter = adapters.get(target);
+            const compilerOwned = ['font/google', 'font/local'].includes(name);
+            if (compilerOwned) {
+              unknown++;
+              finding(item, entry, 'compiler-import', 'info', `${entry.specifier} is resolved by the production font transform.`, 'Run a production build to validate this font name and its options.');
+            }
+            for (const name of entry.names) if (!adapter.names.has(name) && !compilerOwned) {
+              if (adapter.complete) finding(item, entry, 'unsupported-export', 'error', `${entry.specifier} does not provide the runtime export "${name}" in this PRNext release.`, 'Use an export provided by this release or retain the original framework for this code path.');
+              else { unknown++; finding(item, entry, 'unknown-export', 'warning', `The runtime export "${name}" from ${entry.specifier} could not be checked statically.`, 'Validate this import with a production build.'); }
+            }
+            if (realm === 'browser' && ['headers', 'cache', 'server', 'og', 'redis-cache'].includes(name)) finding(item, entry, 'server-import-in-client', 'error', `${entry.specifier} is imported by a client module.`, 'Move the server operation into a Server Component or Server Action.');
+          }
+          continue;
+        }
+        let browserBuiltin;
+        if (builtins.has(entry.specifier)) {
+          if (realm !== 'browser') continue;
+          // The App browser compiler does not inject Node polyfills. Resolve
+          // first so npm shims and package browser mappings remain valid.
+          browserBuiltin = await resolve(entry.specifier, item, entry.kind, realm);
+          // esbuild returns browser:false as the unchanged specifier with no
+          // file namespace, rather than a physical module to traverse.
+          if (!browserBuiltin.errors.length && !browserBuiltin.external && browserBuiltin.namespace === '' && browserBuiltin.path === entry.specifier) continue;
+          if (browserBuiltin.errors.length || browserBuiltin.external || !browserBuiltin.path) {
+            finding(item, entry, 'node-builtin-in-client', 'error', `${entry.specifier} is a Node builtin imported by a client module without a browser implementation.`, 'Move this operation into a Server Component or Server Action, or configure and validate a browser implementation.');
+            continue;
+          }
+        }
+        if (/^(?:react|react-dom|react-server-dom-webpack)(?:\/|$)/.test(entry.specifier)) continue;
+        // CSS, images and native addons are owned by loaders/native packaging.
+        if (/\.(?:css|s[ac]ss|less|png|jpe?g|gif|webp|avif|svg|ico|woff2?|ttf|json)$/.test(entry.specifier)) continue;
+        if (item.chain.length >= limits.depth) { unknown++; limited = true; continue; }
+        const resolution = browserBuiltin || await resolve(entry.specifier, item, entry.kind, realm);
+        if (resolution.errors.length || resolution.external || !resolution.path) {
+          unknown++;
+          finding(item, entry, 'unresolved-import', 'warning', `The imported module "${entry.specifier}" could not be resolved for this audit.`, 'Install the application dependencies and run a production build; custom aliases and optional imports may need application-specific validation.');
+          continue;
+        }
+        if (!code.test(resolution.path)) { unknown++; finding(item, entry, 'loader-import', 'info', `The imported module "${entry.specifier}" requires loader or native validation.`, 'Validate it with a production build and deployed application tests.'); continue; }
+        const dependency = await packageFor(resolution.path, entry.specifier, item.package);
+        if (dependency) {
+          const key = `${dependency.name}@${dependency.version || 'unknown'}`;
+          if (!dependencies.has(key)) dependencies.set(key, { name: dependency.name, version: dependency.version, state: 'checked', importedBy: [] });
+          const record = dependencies.get(key);
+          if (record.importedBy.length < 16 && !record.importedBy.some(value => value.file === fileLabel(item) && value.line === entry.line)) record.importedBy.push({ file: fileLabel(item), line: entry.line, specifier: entry.specifier });
+        }
+        queue.push({ filename: resolution.path, realm, package: dependency, chain: [...item.chain, { file: fileLabel(item), line: entry.line, specifier: entry.specifier }] });
+      }
+      if (limited && edges >= limits.edges) break;
+    }
+  } finally { await Promise.all([...resolvers.values()].map(value => value.context.dispose())); }
+  if (limited) findings.push({ severity: 'warning', id: 'import-graph-limit', file: null, line: null, message: 'The imported dependency graph exceeded an audit limit.', action: 'Run a production build and application tests; this audit does not cover the remaining modules.' });
+  return { imports, findings, dependencies: [...dependencies.values()].sort((a, b) => a.name.localeCompare(b.name)), evidence: { state: unknown || limited ? 'unknown' : 'checked', modules: physical.size, edges, bytes, limits, unknown, limited, scope: 'Static imports and selected Node, browser and React Server Component package conditions. A checked module is not a compatibility certification; custom loaders, aliases, runtime branches and behavior still require a production build and application tests.' } };
+}

package/build/migration-scenarios-runner.mjs

@@ -0,0 +1,73 @@
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import path from 'node:path';
+
+let browser, browserServer, activeContext, closing = false;
+async function close() {
+  if (closing) return;
+  closing = true;
+  await activeContext?.close().catch(() => {});
+  await browser?.close().catch(() => {});
+  await browserServer?.close().catch(() => {});
+  if (process.connected) process.send({ type: 'browser-closed' });
+}
+process.on('disconnect', () => { void close().finally(() => process.exit(1)); });
+process.on('SIGTERM', () => { void close().finally(() => process.exit(1)); });
+process.on('message', async message => {
+  if (message?.type === 'close') { await close(); process.exit(0); }
+  if (message?.type !== 'run') return;
+  const results = [];
+  let report;
+  const unknown = reason => ({ ok: false, state: 'unknown', reason, results });
+  try {
+    const require = createRequire(path.join(message.root, 'package.json'));
+    let playwright;
+    for (const name of ['playwright', '@playwright/test']) {
+      try { playwright = await import(pathToFileURL(require.resolve(name)).href); break; } catch {}
+    }
+    if (!playwright?.chromium && !playwright?.default?.chromium) { report = unknown('playwright-unavailable'); return; }
+    let scenarios, importTimer, expiredImport = false;
+    try { scenarios = (await Promise.race([
+      import(pathToFileURL(message.filename).href),
+      new Promise((_, reject) => { importTimer = setTimeout(() => { expiredImport = true; reject(new Error('timeout')); }, Math.min(10000, Math.max(1000, message.timeout))); }),
+    ])).default; }
+    catch { report = unknown(expiredImport ? 'scenario-module-timeout' : 'scenario-module-failed'); return; }
+    finally { clearTimeout(importTimer); }
+    if (!Array.isArray(scenarios) || !scenarios.length || scenarios.length > 20 || scenarios.some(item => !item || typeof item.run !== 'function')) { report = unknown('invalid-scenarios'); return; }
+    try {
+      const chromium = playwright.chromium || playwright.default.chromium;
+      browserServer = await chromium.launchServer({ headless: true, timeout: 10000 });
+      // The parent can stop the specifically owned browser even when a trusted
+      // callback blocks this worker's event loop with synchronous JavaScript.
+      if (process.connected) process.send({ type: 'browser-started', pid: browserServer.process().pid });
+      browser = await chromium.connect(browserServer.wsEndpoint(), { timeout: 10000 });
+    }
+    catch { report = unknown('browser-unavailable'); return; }
+    for (let index = 0; index < scenarios.length; index++) {
+      for (const target of ['reference', 'candidate']) {
+        let timer, expired = false;
+        try {
+          activeContext = await browser.newContext({ serviceWorkers: 'block' });
+          const page = await activeContext.newPage();
+          page.setDefaultTimeout(message.timeout);
+          page.setDefaultNavigationTimeout(message.timeout);
+          await Promise.race([
+            Promise.resolve().then(() => scenarios[index].run({ page, baseURL: target === 'reference' ? message.reference : message.candidate })),
+            new Promise((_, reject) => { timer = setTimeout(() => { expired = true; reject(new Error('timeout')); }, message.timeout); }),
+          ]);
+          results.push({ scenario: index + 1, target, status: 'passed' });
+        } catch { results.push({ scenario: index + 1, target, status: 'failed', reason: expired ? 'timeout' : 'assertion-or-runtime-failure' }); }
+        finally { clearTimeout(timer); await activeContext?.close().catch(() => {}); activeContext = undefined; }
+        // An expired callback may continue running its own JavaScript. Stop this
+        // worker after closing its browser instead of starting another target.
+        if (expired) { report = unknown('worker-failed'); return; }
+      }
+    }
+    report = { ok: results.every(item => item.status === 'passed'), state: 'checked', results };
+  } catch { report = unknown('worker-failed'); }
+  finally {
+    await close();
+    if (process.connected) process.send({ type: 'result', report: report || unknown('worker-failed') });
+    else process.exit(1);
+  }
+});

package/build/migration-scenarios.mjs

@@ -0,0 +1,72 @@
+import { execFile, fork } from 'node:child_process';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const runner = fileURLToPath(new URL('./migration-scenarios-runner.mjs', import.meta.url));
+const scope = 'Application-provided browser scenarios run independently against each server in isolated contexts. Passing both servers does not establish full application equivalence. Application code is explicitly executed and may submit forms or change test data. Browser messages, request data and raw errors are excluded from this report.';
+function origin(value) {
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.pathname !== '/' || url.search || url.hash) throw new Error('Scenario servers must be HTTP(S) origins without credentials, paths, or queries.');
+  return url.origin;
+}
+
+/** The explicit scenario option is the only path that loads application test code. */
+export async function runMigrationScenarios({ directory, against, candidate, scenarios, timeout = 10000 }) {
+  const root = await realpath(path.resolve(directory));
+  const reference = origin(against), current = origin(candidate);
+  if (typeof scenarios !== 'string' || !scenarios || !/\.[cm]?js$/.test(scenarios)) throw new Error('Provide an application browser scenario module ending in .mjs, .cjs or .js.');
+  const filename = await realpath(path.resolve(root, scenarios));
+  const relative = path.relative(root, filename);
+  if (!relative || relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative)) throw new Error('The browser scenario module must be inside the application directory.');
+  if (!(await stat(filename)).isFile()) throw new Error('The browser scenario module must be a regular file.');
+  if (!Number.isInteger(timeout) || timeout < 100 || timeout > 60000) throw new Error('Scenario timeout must be 100–60000 milliseconds.');
+  // Require an application manifest, without loading it as executable code.
+  JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+  return new Promise(resolve => {
+    const child = fork(runner, [], { cwd: root, execArgv: [], stdio: ['ignore', 'ignore', 'ignore', 'ipc'], windowsHide: true });
+    let settled = false, report, timer, killTimer, browserPid, termination = Promise.resolve();
+    const incomplete = reason => ({ ok: false, state: 'unknown', reason, results: [], scope });
+    const finish = value => {
+      if (settled) return;
+      settled = true; clearTimeout(timer); clearTimeout(killTimer);
+      child.removeAllListeners('message');
+      resolve({ ...value, scope });
+    };
+    // The worker has 20 scenarios maximum, two targets each, plus a bounded
+    // startup/teardown budget. A hung module import cannot hold the CLI open.
+    const terminate = () => {
+      if (child.exitCode !== null || child.signalCode !== null || !child.pid) return;
+      // Kill only this worker's descendants on Windows. A synchronous user test
+      // cannot process SIGTERM or close its browser itself.
+      if (process.platform === 'win32') termination = new Promise(done => execFile('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true }, () => { if (child.exitCode === null) child.kill(); done(); }));
+      else {
+        // BrowserServer owns this process, and Chromium closes its subprocesses
+        // when that browser process exits. No shared browser is ever connected.
+        if (browserPid) { try { process.kill(browserPid, 'SIGKILL'); } catch {} }
+        child.kill('SIGTERM'); killTimer = setTimeout(() => child.kill('SIGKILL'), 1000);
+      }
+    };
+    const budget = Math.min(300000, 20000 + timeout * 40);
+    timer = setTimeout(() => { report = incomplete('worker-timeout'); terminate(); }, budget);
+    child.on('message', message => {
+      if (message?.type === 'browser-started' && Number.isInteger(message.pid) && message.pid > 0 && message.pid !== process.pid && message.pid !== child.pid) { browserPid = message.pid; return; }
+      if (message?.type === 'browser-closed') { browserPid = undefined; return; }
+      if (message?.type !== 'result' || !message.report || report) return;
+      // Never forward arbitrary fields from application code or a compromised
+      // IPC message: the public report has a fixed, deliberately small schema.
+      const input = message.report;
+      if (!Array.isArray(input.results) || input.results.length > 40 || input.results.some(item => !item || !Number.isInteger(item.scenario) || item.scenario < 1 || item.scenario > 20 || !['reference', 'candidate'].includes(item.target) || !['passed', 'failed'].includes(item.status))) { report = incomplete('invalid-result'); terminate(); return; }
+      const results = input.results.map(item => ({ scenario: Number.isInteger(item.scenario) ? item.scenario : 0, target: item.target === 'reference' ? 'reference' : 'candidate', status: item.status === 'passed' ? 'passed' : 'failed', ...(item.reason === 'timeout' ? { reason: 'timeout' } : item.status !== 'passed' ? { reason: 'assertion-or-runtime-failure' } : {}) }));
+      const allowed = new Set(['playwright-unavailable', 'invalid-scenarios', 'scenario-module-failed', 'scenario-module-timeout', 'browser-unavailable', 'worker-failed']);
+      report = { ok: input.ok === true && results.length > 0 && results.every(item => item.status === 'passed'), state: input.state === 'checked' ? 'checked' : 'unknown', ...(allowed.has(input.reason) ? { reason: input.reason } : {}), results };
+      child.send({ type: 'close' }, () => {});
+      // A module can leave its own timers running. Once the owned browser has
+      // closed, exit the worker rather than waiting for application handles.
+      clearTimeout(timer); timer = setTimeout(terminate, 5000);
+    });
+    child.once('error', () => finish(incomplete('worker-failed')));
+    child.once('close', () => { void termination.then(() => finish(report || incomplete('worker-failed'))); });
+    child.send({ type: 'run', root, filename, reference, candidate: current, timeout }, error => { if (error) { report = incomplete('worker-failed'); terminate(); } });
+  });
+}

package/build/native-discovery.mjs

@@ -1,6 +1,9 @@
 import { readdir, readFile, realpath } from 'node:fs/promises';
-import { createRequire } from 'node:module';
+import { builtinModules, createRequire } from 'node:module';
 import path from 'node:path';
+import { analyzeSource } from './source-analysis.mjs';
+
+const builtins = new Set([...builtinModules, ...builtinModules.map(name => 'node:' + name)]);
 
 /** Inspect only packages reached through imports and declared runtime dependencies. */
 export function createNativeDiscovery({ projectRoot, isClientSource }) {
@@ -9,6 +12,27 @@ export function createNativeDiscovery({ projectRoot, isClientSource }) {
   const packageFiles = new Map();
   const dependencyRoots = new Map();
   const clientBoundaries = new Map();
+  const sourceImports = new Map(), entryNative = new Map(), declaredNative = new Map();
+  const resolvers = new Map();
+  let sourceBytes = 0;
+  const isApplication = directory => {
+    const relative = path.relative(directory, projectRoot);
+    return relative === '' || (!relative.startsWith('..' + path.sep) && relative !== '..' && !path.isAbsolute(relative));
+  };
+
+  function importsFor(file) {
+    if (!sourceImports.has(file)) sourceImports.set(file, (async () => {
+      if (!/\.(?:[cm]?[jt]s|jsx|tsx)$/.test(file) || /\.d\.[cm]?ts$/.test(file)) return { imports: [], computedRequire: false };
+      const source = await readFile(file, 'utf8');
+      const size = Buffer.byteLength(source);
+      if (size > 8 * 1024 ** 2 || (sourceBytes += size) > 64 * 1024 ** 2) throw new Error('Native npm import analysis exceeds its 8 MiB file / 64 MiB source budget. Separate the native loader into a server-only package.');
+      // The compiler accepts JSX in JavaScript npm entries, including .js.
+      const { imports, computedRequire } = analyzeSource(source, /\.[cm]?js$/.test(file) ? file + '.jsx' : file);
+      // Keep edges, not the AST, so the shared parser can bound its retained cache.
+      return { imports, computedRequire };
+    })());
+    return sourceImports.get(file);
+  }
 
   function readMetadata(directory) {
     if (!metadata.has(directory)) metadata.set(directory, readFile(path.join(directory, 'package.json'), 'utf8').then(JSON.parse).catch(error => {
@@ -53,7 +77,7 @@ export function createNativeDiscovery({ projectRoot, isClientSource }) {
           else if (entry.isFile() || entry.isSymbolicLink()) {
             if (entry.name.endsWith('.node')) result.native = true;
             if (/\.(?:css|scss|sass)$/i.test(entry.name)) result.css = true;
-            if (/\.(?:[cm]?js|jsx|tsx?)$/.test(entry.name) && !entry.name.endsWith('.d.ts')) result.sources.push(file);
+            if (/\.(?:[cm]?[jt]s|jsx|tsx)$/.test(entry.name) && !/\.d\.[cm]?ts$/.test(entry.name)) result.sources.push(file);
           }
         }
       }
@@ -99,6 +123,38 @@ export function createNativeDiscovery({ projectRoot, isClientSource }) {
     return false;
   }
 
+  function declaredNativeFor(owner) {
+    if (!declaredNative.has(owner.directory)) declaredNative.set(owner.directory, nativeReachable(owner));
+    return declaredNative.get(owner.directory);
+  }
+
+  function nativeFromEntry(file, mode) {
+    const key = mode + '\0' + file;
+    if (!entryNative.has(key)) entryNative.set(key, (async () => {
+      const pending = [file], visited = new Set();
+      while (pending.length) {
+        const current = pending.pop();
+        if (visited.has(current)) continue;
+        visited.add(current);
+        if (visited.size > 4096) throw new Error('Native npm import analysis exceeds 4096 reached modules. Separate the native loader into a server-only package.');
+        const owner = await packageFor(current);
+        if (!owner || isApplication(owner.directory)) continue;
+        if ((await filesFor(owner.directory)).native) return true;
+        const source = await importsFor(current);
+        // A runtime loader may compute a declared package name. Preserve its
+        // original npm boundary when that unknown name can reach an addon.
+        if (source.computedRequire && await declaredNativeFor(owner)) return true;
+        for (const dependency of source.imports) {
+          if (builtins.has(dependency.path)) continue;
+          const resolved = await resolvers.get(mode)(dependency.path, current, dependency.kind);
+          if (!resolved.errors?.length && !resolved.external && resolved.namespace === 'file') pending.push(resolved.path);
+        }
+      }
+      return false;
+    })());
+    return entryNative.get(key);
+  }
+
   function hasClientBoundary(directory, sources) {
     if (!clientBoundaries.has(directory)) clientBoundaries.set(directory, (async () => {
       for (const file of sources) {
@@ -116,13 +172,17 @@ export function createNativeDiscovery({ projectRoot, isClientSource }) {
   }
 
   return {
+    setResolver(mode, resolve) { resolvers.set(mode, resolve); },
     canExternalizeDirectory,
     async externalOwner(file, mode) {
       const owner = await packageFor(file);
       if (!owner) return;
-      const application = path.relative(owner.directory, projectRoot);
-      if (application === '' || (!application.startsWith('..' + path.sep) && application !== '..' && !path.isAbsolute(application))) return;
-      if (!await nativeReachable(owner)) return;
+      if (isApplication(owner.directory)) return;
+      if (!await declaredNativeFor(owner)) return;
+      // A package can declare build tools with native dependencies that its
+      // runtime entry never imports (for example an i18n extractor). Follow
+      // that entry's real compiler resolution before externalizing its parent.
+      if (resolvers.has(mode) && !await nativeFromEntry(file, mode)) return;
       // Keep CSS extraction and Server Component client-reference transforms in
       // the compiler. A native dependency imported by this package is examined
       // separately when its own entry is resolved.

package/build/native-packages.mjs

@@ -66,6 +66,8 @@ export function createNativePackages(projectRoot, { isClientSource }) {
       return {
         name: `prnext-native-packages-${mode}`,
         setup(esbuild) {
+          discovery.setResolver(mode, (name, importer, kind) => esbuild.resolve(name, { importer, resolveDir: path.dirname(importer), kind,
+            pluginData: { prnextNativeResolving: true, prnextNpmResolving: true } }));
           esbuild.onResolve({ filter: /\.node$/ }, async args => {
             if (args.pluginData?.prnextNativeResolving) return;
             if (mode === 'browser') return { errors: [{ text: `Native Node addon ${args.path} cannot run in a Client Component (${args.importer}). Keep the native dependency in a Server Component or route handler.` }] };

package/build/native-ppr.mjs

@@ -0,0 +1,32 @@
+import {readFile, writeFile, stat} from 'node:fs/promises';
+import path from 'node:path';
+import {partialShell, sha256, NATIVE_PPR_ARTIFACT_BYTES, NATIVE_PPR_PREFIX_BYTES} from '../runtime/native-ppr.mjs';
+
+// Only concrete build-time shells are certified. Runtime regeneration, generic
+// params, middleware and external caches stay on the authoritative Node path.
+export async function prepareNativePprShells(stage, manifest) {
+  delete manifest.config.nativePprArtifacts;
+  if (!manifest.config.nativePprShell || !manifest.config.cacheComponents || manifest.dev || manifest.middleware || manifest.config.basePath || manifest.config.cacheHandler || Object.keys(manifest.config.cacheHandlers || {}).length) return;
+  const descriptors = [];
+  let total = 0;
+  for (const route of [...manifest.routes].sort((a, b) => a.id.localeCompare(b.id))) {
+    if (route.kind !== 'page' || route.router !== 'app' || route.internal || route.parallel || route.cacheConfig?.runtime === 'edge') continue;
+    for (const [pathname, artifactFile] of Object.entries(route.ppr || {}).sort(([a], [b]) => a.localeCompare(b))) {
+      if (descriptors.length >= 32) break;
+      const file = path.resolve(stage, artifactFile);
+      if (!artifactFile.startsWith('static/') || !file.startsWith(path.resolve(stage) + path.sep) || (await stat(file)).size > NATIVE_PPR_ARTIFACT_BYTES) continue;
+      const bytes = await readFile(file);
+      const artifact = JSON.parse(bytes);
+      if (artifact.version !== 1 || !artifact.postponed || artifact.complete || artifact.generic || artifact.externalCache || artifact.revalidate === 0 || typeof artifact.flight !== 'string' || Object.keys(artifact.headers || {}).length) continue;
+      const prefix = Buffer.from(partialShell(artifact, route).replace(/<\/body><\/html>$/i, ''));
+      if (prefix.length > NATIVE_PPR_PREFIX_BYTES || total + prefix.length > 4 * 1024 * 1024) continue;
+      if (!Number.isSafeInteger(artifact.generatedAt) || artifact.generatedAt < 0 || !(artifact.revalidate == null || artifact.revalidate === false || Number.isSafeInteger(artifact.revalidate) && artifact.revalidate > 0)) continue;
+      const prefixHash = sha256(prefix);
+      const prefixFile = `static/native-ppr-${prefixHash}.html`;
+      await writeFile(path.join(stage, prefixFile), prefix);
+      descriptors.push({routeId: route.id, path: pathname, artifact: artifactFile, artifactHash: sha256(bytes), prefix: prefixFile, prefixHash, identity: sha256(artifact.flight), generatedAt: artifact.generatedAt, revalidate: artifact.revalidate ?? false});
+      total += prefix.length;
+    }
+  }
+  manifest.config.nativePprArtifacts = descriptors;
+}