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

package/build/framework-imports.mjs

@@ -1,4 +1,10 @@
+import {fileURLToPath} from 'node:url';
+import {dirname} from 'node:path';
+import {readFile} from 'node:fs/promises';
+import {analyzeSource} from './source-analysis.mjs';
+import {cachedTransform} from './transform-cache.mjs';
 const adapters = new Map([
+  ['cache/redis','redis-cache'],
   ['dist/shared/lib/router-context.shared-runtime','next-router-context'],
   ['dist/shared/lib/router-context','next-router-context'],
   ['dist/shared/lib/app-router-context.shared-runtime','next-app-router-context'],
@@ -15,3 +21,47 @@ export function frameworkImportName(specifier) {
   const name=specifier.replace(frameworkSubpathPattern, '').replace(/\.js$/,'');
   return adapters.get(name) || name;
 }
+
+// Application graphs must not traverse the programmatic build API's native tools.
+// Outside a compiled application, the package root retains its full Node API.
+export function applicationEntry(builder,readSource=(file,override)=>override??readFile(file,'utf8'),{transformTypedHelpers=false}={}){
+  // Server/client module boundaries in .mts/.cts are not supported. Never
+  // silently bundle a server implementation or misclassify a client boundary.
+  builder.onLoad({filter:/\.[cm]ts$/i,namespace:'file'},async args=>{
+    // Loader bridges dispatch framework callbacks independently of their filters.
+    if(!/\.[cm]ts$/i.test(args.path))return;
+    const source=await readSource(args.path,args.prnextSource);
+    const original=args.prnextSource===undefined?source:await readSource(args.path);
+    let nativeDecorators=false;
+    // A loader may remove a directive as well as introduce one. Both versions
+    // must be safe before its output can become an ordinary browser module.
+    for(const candidate of new Set([original,source])){
+     const unsupported=cachedTransform('unsupported-framework-directives',candidate,[args.path,'v4-native-decorators'],()=>{
+      const analysis=analyzeSource(candidate,args.path);
+      if(analysis.frameworkBoundary)return 'yes';
+      const pending=[analysis.program];let decorators=false;
+      while(pending.length){
+        const node=pending.pop();
+        if(node.type==='ExpressionStatement'&&node.directive==='use server')return 'yes';
+        if(node.type==='Decorator'||node.decorators?.length)decorators=true;
+        for(const value of Object.values(node)){
+          if(Array.isArray(value)){for(const item of value)if(item?.type)pending.push(item);}
+          else if(value&&typeof value==='object'&&value.type)pending.push(value);
+        }
+      }
+      return decorators?'decorated':'no';
+     });
+     if(unsupported==='yes')throw new Error(`React server/client directives are not supported in ${args.path}. Rename this file to .ts or .tsx.`);
+     nativeDecorators ||= unsupported==='decorated';
+    }
+    // Compiler-enabled render graphs can transform ordinary typed helpers after
+    // this boundary check. Other consumers keep the historical esbuild path.
+    // Decorated typed helpers already have a native esbuild implementation.
+    // Keep that path instead of widening the syntax accepted by every Babel
+    // transform, while their importing React components can still be compiled.
+    if(transformTypedHelpers && !nativeDecorators)return;
+    return {contents:source,loader:args.prnextSource===undefined?'ts':'tsx',resolveDir:dirname(args.path)};
+  });
+  builder.onResolve({filter:/^(?:prnext|@thomas\.f\/prnext)(?:\/route(?:\.js)?)?$/},()=>
+    ({path:fileURLToPath(new URL('../runtime/typed-route.mjs',import.meta.url))}));
+}

package/build/html-only-config.mjs

@@ -0,0 +1,53 @@
+import {assertHtmlOnlyDocument} from '../runtime/html-only.mjs';
+const MAX_PATTERNS = 128;
+
+export function validateHtmlOnly(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > MAX_PATTERNS) throw new TypeError('htmlOnly must be an array of at most 128 App route patterns.');
+  for (const pattern of value) {
+    if (typeof pattern !== 'string' || pattern.length > 512 || !pattern.startsWith('/') || pattern.startsWith('//') ||
+        /[\s\\?#\u0000-\u001f\u007f]/.test(pattern) || /%(?![\da-f]{2})/i.test(pattern)) throw new TypeError('htmlOnly entries must be clean absolute route patterns without queries, fragments, whitespace or backslashes.');
+    const pathname = pattern.endsWith('/**') ? pattern.slice(0, -3) || '/' : pattern;
+    if (pathname.includes('*') || (pathname !== '/' && pathname.endsWith('/')) || pathname.slice(1).includes('//')) throw new TypeError('htmlOnly supports exact registered route patterns and a final /** subtree suffix only.');
+    for (const segment of pathname.split('/').slice(1)) {
+      let decoded;
+      try { decoded = decodeURIComponent(segment); } catch { throw new TypeError('htmlOnly patterns must use valid URL encoding.'); }
+      if (decoded === '.' || decoded === '..' || /[\\/\u0000-\u001f\u007f]/.test(decoded)) throw new TypeError('htmlOnly patterns cannot contain dot segments or encoded path separators.');
+    }
+  }
+  return [...new Set(value)];
+}
+
+export function matchesHtmlOnly(pattern, routePattern) {
+  if (!pattern.endsWith('/**')) return pattern === routePattern;
+  const prefix = pattern.slice(0, -3);
+  return !prefix || routePattern === prefix || routePattern.startsWith(prefix + '/');
+}
+
+export function selectHtmlOnlyRoutes(routes, patterns, { cacheComponents = false } = {}) {
+  const selected = new Set();
+  for (const pattern of validateHtmlOnly(patterns)) {
+    const matches = routes.filter(route => !route.internal && matchesHtmlOnly(pattern, route.pattern));
+    if (!matches.length) throw new Error(`htmlOnly pattern ${JSON.stringify(pattern)} does not match a registered route.`);
+    for (const route of matches) {
+      if (route.router !== 'app' || route.kind !== 'page') throw new Error(`htmlOnly route ${route.pattern} must be an App Router page; Pages Router and Route Handlers are not supported.`);
+      const config = route.cacheConfig || {};
+      if (cacheComponents || config.runtime === 'edge' || config.dynamic === 'force-dynamic' || config.forceNoStore || (config.revalidate !== undefined && config.revalidate !== false)) {
+        throw new Error(`htmlOnly route ${route.pattern} must be fully prerendered without Edge, Cache Components/PPR, dynamic rendering or ISR.`);
+      }
+      if (route.parallel || route.interception) throw new Error(`htmlOnly route ${route.pattern} does not support parallel or intercepted routing.`);
+      if (route.pattern.includes('[') && config.dynamicParams !== false) throw new Error(`htmlOnly route ${route.pattern} requires dynamicParams: false and complete generateStaticParams results.`);
+      selected.add(route.id);
+    }
+  }
+  return selected;
+}
+
+export function validateHtmlOnlyPrerender(route, rendered) {
+  if (!route.htmlOnly) return;
+  if (rendered.dynamic || rendered.partial || rendered.revalidate !== false || (rendered.status ?? 200) !== 200) {
+    throw new Error(`htmlOnly route ${route.pattern} must produce a complete successful static HTML document without dynamic data, partial rendering, redirects or ISR.`);
+  }
+  const html = Buffer.isBuffer(rendered.body) ? rendered.body.toString('utf8') : rendered.body;
+  assertHtmlOnlyDocument(html, route.pattern);
+}

package/build/html-only-graph.mjs

@@ -0,0 +1,67 @@
+import path from 'node:path';
+import { builtinModules } from 'node:module';
+import { analyzeSource } from './source-analysis.mjs';
+import { frameworkImportName, frameworkImportPattern } from './framework-imports.mjs';
+
+const builtins = new Set([...builtinModules, ...builtinModules.map(name => 'node:' + name)]);
+const interactive = new Set(['link','image','head','script','dynamic','router','compat/router','next-router-context','next-app-router-context']);
+const namespace = /^prnext-(?:css-mapping|compiled-css|app-empty|edge-empty):/;
+
+export function createHtmlOnlyGraph(root) {
+  const graph = new Map(), issues = new Map();
+  const file = value => path.resolve(root, value.replace(namespace, ''));
+  function issue(filename, reason) {
+    const key = file(filename);
+    if (!issues.has(key)) issues.set(key, reason);
+  }
+  return {
+    issue,
+    alias(source, target) {
+      if (file(source) !== file(target)) graph.set(file(source), [{ path:file(target) }]);
+    },
+    source(filename, source) {
+      const { program, directives, computedRequire, imports } = analyzeSource(source, filename);
+      if (directives.includes('use client')) issue(filename, 'a Client Component (use client)');
+      if (computedRequire) issue(filename, 'a computed require() whose dependencies cannot be validated');
+      for (const dependency of imports) if (frameworkImportPattern.test(dependency.path) && interactive.has(frameworkImportName(dependency.path))) issue(filename, `interactive framework import ${dependency.path}; use ordinary HTML elements instead`);
+      const pending = [program];
+      while (pending.length) {
+        const node = pending.pop();
+        if (node.directive === 'use server') issue(filename, 'a Server Action (use server)');
+        if (node.type === 'ImportExpression' && typeof node.source?.value !== 'string') issue(filename, 'a computed import() whose dependencies cannot be validated');
+        if (node.type === 'JSXOpeningElement' && node.name?.type === 'JSXIdentifier' && ['script','iframe','object','embed'].includes(node.name.name.toLowerCase())) issue(filename, `a <${node.name.name}> element`);
+        if (node.type === 'JSXAttribute' && node.name?.type === 'JSXIdentifier' && /^on[A-Z]/.test(node.name.name)) issue(filename, `interactive event property ${node.name.name}`);
+        for (const value of Object.values(node)) {
+          if (Array.isArray(value)) { for (const child of value) if (child?.type) pending.push(child); }
+          else if (value && typeof value === 'object' && value.type) pending.push(value);
+        }
+      }
+    },
+    record(metafile) {
+      for (const [name, input] of Object.entries(metafile?.inputs || {})) {
+        const key=file(name), dependencies=graph.get(key) || [];
+        for (const dependency of input.imports || []) {
+          if (!dependency.external) dependencies.push({path:file(dependency.path)});
+          else if (!builtins.has(dependency.path) && !/^(?:react|react-dom|react-server-dom-webpack)(?:\/|$)/.test(dependency.path) && !/^\.\.\/compat\/(?:navigation|headers|cache|server|font-local|font-google|og)\.cjs$/.test(dependency.path)) {
+            dependencies.push({external:dependency.path});
+          }
+        }
+        graph.set(key,dependencies);
+      }
+    },
+    validate(route) {
+      const roots = new Set([route.file, ...Object.values(route.segments || {}).flatMap(segment => Object.values(segment).filter(value => typeof value === 'string' && /\.[cm]?[jt]sx?$/.test(value))), ...(route.metadataFiles || []).map(item => item.file)].filter(Boolean));
+      const pending=[...roots].map(file), seen=new Set();
+      while (pending.length) {
+        const current=pending.pop();
+        if (seen.has(current)) continue;
+        seen.add(current);
+        if (issues.has(current)) throw new Error(`htmlOnly route ${route.pattern} reaches ${issues.get(current)} in ${path.relative(root,current)}.`);
+        for (const dependency of graph.get(current) || []) {
+          if (dependency.external) throw new Error(`htmlOnly route ${route.pattern} reaches unverified external dependency ${dependency.external} from ${path.relative(root,current)}. Bundle a static server dependency or remove it from this HTML-only route.`);
+          pending.push(dependency.path);
+        }
+      }
+    },
+  };
+}

package/build/incremental.mjs

@@ -3,13 +3,17 @@ import { readFile, writeFile, mkdir, realpath } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import {clearDirectoryCache} from './directory-cache.mjs';
+import {closeWebpackCompiler,webpackCompilerStats} from './webpack-graph.mjs';
 const contexts = new Map();
 const LIMIT = 8;
 let created = 0, reused = 0;
-export const incrementalCompilerStats = () => ({contexts:contexts.size, created, reused});
-export async function closeIncrementalCompiler() {
+export const incrementalCompilerStats = () => ({contexts:contexts.size, created, reused,webpack:webpackCompilerStats()});
+export async function closeIncrementalCompiler(root) {
   clearDirectoryCache();
-  const active=[...contexts.values()];contexts.clear();await Promise.all(active.map(slot=>slot.context.dispose()));
+  const active=[];for(const [key,slot] of contexts)if(root===undefined||slot.root===root){contexts.delete(key);active.push(slot);}
+  const results=await Promise.allSettled([...active.map(slot=>slot.context.dispose()),closeWebpackCompiler(root)]);
+  const errors=results.filter(result=>result.status==='rejected').map(result=>result.reason);
+  if(errors.length)throw new AggregateError(errors,'Unable to dispose incremental compiler sessions');
 }
 /** Retain esbuild's parsed module graphs while rebinding per-build framework plugins. */
 export async function incrementalBuild(options, {root,stage,group='project',run=callback=>callback()}) {
@@ -40,7 +44,7 @@ export async function incrementalBuild(options, {root,stage,group='project',run=
   if(slot){contexts.delete(key);reused++;}
   else {
     while([...contexts.values()].filter(slot=>slot.group===group).length>=(group==='auxiliary'?2:LIMIT)){const [oldest,previous]=[...contexts].find(([,slot])=>slot.group===group);contexts.delete(oldest);await previous.context.dispose();}
-    created++;slot={group};
+    created++;slot={group,root};
     slot.current={hooks,run,toVirtual,fromVirtual,virtualResult,stage};
     slot.context=await context({...normalized,plugins:[{name:'prnext-incremental-delegates',setup(builder){
       slot.builder=builder;