@thomas.f/prnext 0.1.17-alpha → 0.1.19-alpha

package/build/lazy-dynamic-imports.mjs

@@ -0,0 +1,137 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {createHash} from 'node:crypto';
+import {readFile,writeFile} from 'node:fs/promises';
+import {parse} from '@babel/parser';
+import traverseModule from '@babel/traverse';
+import generateModule from '@babel/generator';
+import * as t from '@babel/types';
+import {generateMapped} from './source-maps.mjs';
+
+const traverse=traverseModule.default||traverseModule;
+const generate=generateModule.default||generateModule;
+const packageRoot=fileURLToPath(new URL('../',import.meta.url));
+const client=fileURLToPath(new URL('../runtime/lazy-import-client.mjs',import.meta.url));
+export const LAZY_IMPORT_LIMIT=128;
+export const LAZY_BRIDGE_LIMIT=4096;
+const javascript=/\.(?:[cm]?[jt]s|[jt]sx)$/;
+// esbuild exposes JSON as an ESM entry with a shared default object and named
+// exports. Give it the same native URL identity as JavaScript export bridges.
+const bridgeable=file=>javascript.test(file)||file.endsWith('.json');
+const digest=value=>createHash('sha256').update(value).digest('hex').slice(0,24);
+const suffixError=()=>({errors:[{text:'lazyDynamicImports cannot safely defer a module with a query or fragment suffix. Disable experimental.lazyDynamicImports to compile this graph normally.'}]});
+
+/** Development-only graph boundaries. No source path is sent to the browser. */
+export function createLazyDynamicImports({root,stage,manifest,request,activated=[]}){
+  const modules=new Map(),bridges=new Map(),shared=new Set(),existingShared=new Set(),entries=new Map(),targetFiles=new Map(),nativeOutputs=new Map(),outputs={};
+  const active=new Set(activated);
+  if(active.size>LAZY_IMPORT_LIMIT)throw Error(`lazyDynamicImports supports at most ${LAZY_IMPORT_LIMIT} active imports`);
+  if(request){
+    if(!/^[a-f0-9]{24}$/.test(request.id)||!Array.isArray(request.modules)||request.modules.length>LAZY_IMPORT_LIMIT||!Array.isArray(request.bridges)||request.bridges.length>LAZY_BRIDGE_LIMIT||!Array.isArray(request.shared)||request.shared.length>LAZY_BRIDGE_LIMIT)throw Error('Invalid deferred import compiler descriptor');
+    for(const item of request.modules){
+      const file=path.resolve(root,item.importer);
+      if(!file.startsWith(root+path.sep)||file.includes(`${path.sep}node_modules${path.sep}`)||!javascript.test(file)||typeof item.request!=='string'||item.request.length>4096||item.id!==digest(item.importer+'\0'+item.request))throw Error('Invalid deferred import registration');
+      modules.set(item.id,item);
+    }
+    if(!modules.has(request.id))throw Error('Unknown deferred import identifier');
+    for(const item of request.bridges){
+      if(typeof item.file!=='string'||typeof item.url!=='string'||!item.url.startsWith(manifest.config.assetBase+'/')||/[\r\n\0]/.test(item.url))throw Error('Invalid deferred module bridge');
+      bridges.set(path.resolve(root,item.file),item.url);
+    }
+    for(const file of request.shared){const absolute=path.resolve(root,file);shared.add(absolute);existingShared.add(absolute);}
+    active.clear();active.add(request.id);
+  }
+  const sourceAst=(source,file)=>parse(source,{sourceType:'unambiguous',sourceFilename:file,plugins:['jsx',...(/\.[cm]?tsx?$/.test(file)?['typescript']:[])]});
+  const eligible=file=>file.startsWith(root+path.sep)&&!file.includes(`${path.sep}node_modules${path.sep}`)&&!file.includes(`${path.sep}.prnext-build-`);
+  function transform(source,file){
+    if(!eligible(file)||!source.includes('import'))return source;
+    const ast=sourceAst(source,file);let binding,changed=false;
+    const replace=node=>{
+      const value=t.isStringLiteral(node)?node.value:t.isTemplateLiteral(node)&&!node.expressions.length?node.quasis[0].value.cooked:undefined;
+      // Suffixes are part of ESM identity; path-only export bridges cannot
+      // represent them. Keep explicit suffixes in the ordinary compiler graph.
+      if(!value||value.length>4096||/[?#]/.test(value)||/^(?:[a-z]+:|\/\/)/i.test(value))return;
+      const importer=path.relative(root,file).split(path.sep).join('/'),id=digest(importer+'\0'+value);
+      if(!modules.has(id)&&modules.size>=LAZY_IMPORT_LIMIT)throw Error(`lazyDynamicImports supports at most ${LAZY_IMPORT_LIMIT} registered imports per generation`);
+      modules.set(id,{id,importer,request:value});
+      changed=true;return id;
+    };
+    traverse(ast,{Program(p){binding=p.scope.generateUidIdentifier('prnextLazyImport');},CallExpression(p){
+      if(!t.isImport(p.node.callee)||p.node.arguments.length!==1)return;
+      const id=replace(p.node.arguments[0]);if(id)p.replaceWith(t.callExpression(t.cloneNode(binding),[t.stringLiteral(id),t.stringLiteral(manifest.config.basePath||'')]));
+    },ImportExpression(p){if(p.node.options)return;const id=replace(p.node.source);if(id)p.replaceWith(t.callExpression(t.cloneNode(binding),[t.stringLiteral(id),t.stringLiteral(manifest.config.basePath||'')]));}});
+    if(!changed)return source;
+    ast.program.body.unshift(t.importDeclaration([t.importSpecifier(t.cloneNode(binding),t.identifier('lazyImport'))],t.stringLiteral(client)));
+    return generateMapped(generate,ast,{comments:true},source,file);
+  }
+  async function discover(metafile){
+    for(const input of Object.keys(metafile.inputs)){
+      const file=path.resolve(root,input);
+      if(!bridgeable(file)||input.startsWith('prnext-')||file.startsWith(packageRoot)||file.startsWith(stage+path.sep)||/\/node_modules\/(?:react|react-dom|react-refresh|react-server-dom-webpack)\//.test(file.split(path.sep).join('/'))||shared.has(file))continue;
+      if(shared.size>=LAZY_BRIDGE_LIMIT)throw Error(`lazyDynamicImports supports at most ${LAZY_BRIDGE_LIMIT} static JavaScript modules`);
+      shared.add(file);
+      // Real ESM entries expose live bindings. CommonJS named exports cannot be
+      // approximated with snapshots: a deferred graph sharing one is rejected.
+      if(file.endsWith('.json')||sourceAst(await readFile(file,'utf8'),file).program.sourceType==='module')bridges.set(file,undefined);
+    }
+  }
+  async function targetEntries(){
+    const result={};
+    for(const id of active){
+      if(!modules.has(id))continue;
+      const name='lazy-'+id,file=path.join(stage,'.entries',name+'.mjs');
+      await writeFile(file,`import * as namespace from ${JSON.stringify('prnext-lazy-entry:'+id)};export {namespace as __prnextLazyModule};`);
+      entries.set(file,{kind:'target',id});result[name]=file;
+    }
+    return result;
+  }
+  function bridgeEntries(){
+    const result=Object.fromEntries([...bridges].filter(([,url])=>!url).map(([file])=>{entries.set(file,{kind:'bridge',file});return ['lazy-bridge-'+digest(file),file];}));
+    for(const file of targetFiles.values())if(!bridges.has(file)&&bridgeable(file)){
+      entries.set(file,{kind:'native',file});result['lazy-native-'+digest(file)]=file;
+    }
+    return result;
+  }
+  function plugin(){return {name:'prnext-lazy-dynamic-boundaries',setup(builder){
+    builder.onResolve({filter:/^prnext-lazy-entry:/},async args=>{
+      const item=modules.get(args.path.slice('prnext-lazy-entry:'.length));
+      if(!item)return {errors:[{text:'Unknown deferred module entry'}]};
+      const result=await builder.resolve(item.request,{resolveDir:path.dirname(path.resolve(root,item.importer)),kind:'dynamic-import',pluginData:{prnextLazyEntry:true}});
+      if(!result.errors.length&&result.suffix)return suffixError();
+      const file=path.resolve(result.path||root),url=bridges.get(file);
+      if(!result.errors.length&&result.namespace==='file')targetFiles.set(item.id,file);
+      if(existingShared.has(file)&&!url)return {errors:[{text:`lazyDynamicImports cannot safely reuse the shared CommonJS module ${path.relative(root,file)}. Convert it to ESM or disable experimental.lazyDynamicImports.`}]};
+      return url?{path:url,external:true}:result;
+    });
+    if(request)builder.onResolve({filter:/.*/},async args=>{
+      if(args.pluginData?.prnextLazyResolving||args.pluginData?.prnextLazyEntry||args.kind==='entry-point'||args.namespace&&args.namespace!=='file')return;
+      const result=await builder.resolve(args.path,{resolveDir:args.resolveDir,importer:args.importer,kind:args.kind,with:args.with,pluginData:{...args.pluginData,prnextLazyResolving:true}});
+      // Aliases and transitive imports may introduce a suffix even when the
+      // registered literal had none. Reject it before looking up a bare bridge.
+      if(!result.errors.length&&result.suffix)return suffixError();
+      if(result.errors.length||result.external||result.namespace!=='file')return;
+      const file=path.resolve(result.path);
+      if(bridges.get(file))return {path:bridges.get(file),external:true};
+      if(existingShared.has(file))return {errors:[{text:`lazyDynamicImports cannot safely reuse the shared CommonJS module ${path.relative(root,file)}. Convert it to ESM or disable experimental.lazyDynamicImports.`}]};
+    });
+  }};}
+  function record(metadata,output){
+    const entry=entries.get(path.resolve(root,metadata.entryPoint||''));
+    if(!entry||!output.endsWith('.js'))return false;
+    const url=manifest.config.assetBase+'/'+path.basename(output);
+    if(entry.kind==='bridge'||entry.kind==='native'){
+      if(entry.kind==='bridge')bridges.set(entry.file,url);
+      nativeOutputs.set(entry.file,{url,css:metadata.cssBundle?[manifest.config.assetBase+'/'+path.basename(metadata.cssBundle)]:[]});
+    }
+    else outputs[entry.id]={url,css:metadata.cssBundle?[manifest.config.assetBase+'/'+path.basename(metadata.cssBundle)]:[]};
+    return true;
+  }
+  function finish(){
+    for(const [id,file]of targetFiles){
+      const native=nativeOutputs.get(file),url=native?.url||bridges.get(file);
+      if(url&&outputs[id])outputs[id]={url,native:true,css:[...new Set([...outputs[id].css,...(native?.css||[])])]};
+    }
+    manifest.devLazy={modules:[...modules.values()],bridges:[...bridges].filter(([,url])=>url).map(([file,url])=>({file:path.relative(root,file).split(path.sep).join('/'),url})),shared:[...shared].map(file=>path.relative(root,file).split(path.sep).join('/')),outputs};
+  }
+  return {transform,discover,targetEntries,bridgeEntries,plugin,record,finish};
+}

package/build/metadata-routes.mjs

@@ -60,7 +60,7 @@ export async function prepareMetadataRoutes(project, stage) {
     let source;
     if (dynamic) {
       const config = await validateAppConfig(route.file);
-      source = `import * as source from ${JSON.stringify(route.file)};import {metadataHandler,metadataStaticParams} from '../runtime/metadata-route.mjs';export * from ${JSON.stringify(route.file)};\n`;
+      source = `import * as source from ${JSON.stringify(route.file)};import {metadataHandler,metadataStaticParams} from 'prnext-internal:metadata-route';export * from ${JSON.stringify(route.file)};\n`;
       if (config.revalidate === undefined) source += 'export const revalidate=false;\n';
       const options = JSON.stringify({ kind, image, multiple, contentType });
       source += `export const GET=metadataHandler(source,${options});\n`;

package/build/migrate.mjs

@@ -19,18 +19,18 @@ export function parseMigrationArgs(args) {
     const arg = args[index];
     if (arg === '--dry-run') options.dryRun = true;
     else if (arg === '--check') options.check = true;
-    else if (['--against', '--candidate', '--routes', '--timeout'].includes(arg)) {
+    else if (['--against', '--candidate', '--routes', '--timeout', '--browser-scenarios'].includes(arg)) {
       const value = args[++index];
       if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value.`);
-      options[arg.slice(2)] = arg === '--timeout' ? Number(value) : value;
+      options[arg === '--browser-scenarios' ? 'browserScenarios' : arg.slice(2)] = arg === '--timeout' ? Number(value) : value;
     }
     else if (arg === '--no-install') options.install = false;
     else if (arg === '--json') options.json = true;
-    else if (arg.startsWith('-')) throw new Error(`Unknown migrate option: ${arg}. Use --check, --dry-run, --no-install or --json.`);
+    else if (arg.startsWith('-')) throw new Error(`Unknown migrate option: ${arg}. Use --check, --dry-run, --no-install, --browser-scenarios or --json.`);
     else if (directory === undefined) directory = arg;
     else throw new Error('migrate accepts a single project directory.');
   }
-  if ((options.against || options.candidate || options.routes || options.timeout !== undefined) && (!options.check || !options.against || !options.candidate)) throw new Error('Server comparison requires --check, --against and --candidate.');
+  if ((options.against || options.candidate || options.routes || options.timeout !== undefined || options.browserScenarios) && (!options.check || !options.against || !options.candidate)) throw new Error('Server comparison or browser execution requires --check, --against and --candidate.');
   return { directory: path.resolve(directory || '.'), options };
 }
 

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 => 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);
+  }
+});