@wular/pnext 0.0.10 → 0.0.11

package/src/runtime/modules.ts

@@ -23,6 +23,7 @@ import {
 } from './loader'
 import { externalServerPackageHref, runtimeServerImportTarget } from '../runtime/vendor-build'
 import { writeFileAtomic } from '../utils/fs'
+import { traceEnabled, traceValue } from '../utils/trace-flags'
 import { createHash } from 'node:crypto'
 import {
   extraLoadableExtensions,
@@ -39,12 +40,13 @@ import {
   type CompatAliasTarget,
   type ResolvedConfig,
 } from '../config'
-import { readText, toPosixPath } from '../utils/fs'
+import { readText, toPosixPath, writeText } from '../utils/fs'
 import {
   type ExternalLoadTarget,
   externalPackageImportTarget,
   getExternalPackagePolicy,
   isCommonJsModuleSource,
+  isEsmModuleFile,
   packageNameOfSpecifier,
   resolveImport,
   resolveExternalLoadTarget,
@@ -99,7 +101,7 @@ const buildQueue: (() => void)[] = []
 const moduleBuilds = new Map<string, Promise<string>>()
 const routeBundleBuilds = new Map<string, Promise<string>>()
 
-// PNEXT_DEV_MODULE_STATS=1: attribute every per-module compile to its profile,
+// PNEXT_TRACE=server: attribute every per-module compile to its profile,
 // so cross-profile duplicate work is countable rather than inferred. Counts are
 // load-insensitive, which is what makes them usable on a contended box.
 interface ModuleStat {
@@ -109,9 +111,9 @@ interface ModuleStat {
 }
 // `${profile}:${file}` of modules that fell off the oxc fast path onto esbuild.
 const esbuildFallbacks = new Set<string>()
-const moduleStats: Map<string, ModuleStat[]> | undefined =
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  process.env.PNEXT_DEV_MODULE_STATS === '1' ? new Map() : undefined
+const moduleStats: Map<string, ModuleStat[]> | undefined = traceEnabled('server')
+  ? new Map()
+  : undefined
 let moduleStatsFlush: Timer | undefined
 
 function noteModuleCompile(file: string, profile: string, ms: number, esbuild: boolean) {
@@ -163,10 +165,11 @@ function reportModuleStats() {
         `${duplicateCompiles} redundant compiles, ${duplicateMs.toFixed(0)} ms nested-wall`,
     ].join('\n'),
   )
-  // PNEXT_DEV_MODULE_STATS_OUT=<path>: also dump the per-file list, so a floor
-  // bench can replay the exact module set a route compiles in each profile.
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  const out = process.env.PNEXT_DEV_MODULE_STATS_OUT
+  // PNEXT_TRACE=server=<path>: also dump the per-file list, so a floor bench can
+  // replay the exact module set a route compiles in each profile. A `.jsonl` path
+  // belongs to the heavy-package profile instead (see vendor.ts).
+  const out = traceValue('server')
+  if (out?.endsWith('.jsonl')) return
   if (!out) return
   const files = [...moduleStats.entries()].flatMap(([file, entries]) =>
     entries.map(entry => ({ file, profile: entry.profile, ms: entry.ms, esbuild: entry.esbuild })),
@@ -571,8 +574,7 @@ function startRouteVendorStage(config: ResolvedConfig, route: RouteManifestEntry
       }
     }
     for (const specifier of demand) dropped.delete(specifier)
-    // eslint-disable-next-line turbo/no-undeclared-env-vars
-    if (process.env.PNEXT_DEV_PROFILE) {
+    if (traceEnabled('server')) {
       console.log(
         `dev-import vendor seed walk ${route.route} in ${formatDuration(performance.now() - seedT0)} (kept ${demand.size}, dropped ${dropped.size})`,
       )
@@ -1873,26 +1875,21 @@ async function resolveDevModuleSpecifier(
     )
     return { path: `${pathToFileHref(stub)}${hash}`, external: true }
   }
-  // The compiled-path rewrite below is only safe for imports the WRITE pass walks:
-  // writeDevModuleUncached compiles the entry source's own local import targets, nothing deeper. A
-  // first-party compat runtime file pulled in by an alias that esbuild BUNDLES contributes its own
-  // relative imports through this hook, and nothing ever writes those into the profile cache - the
-  // import would resolve to a file that does not exist. Point such a transitive import at its own
-  // source instead; Bun compiles the `.ts` on import.
+  // A `require()` of an ES module cannot take the compiled-path rewrite: the artifact is ESM, and
+  // requiring one throws the moment it is not synchronously evaluable. Let esbuild bundle it and do
+  // the interop, exactly as the alias branch above already does for a require-call. Under an
+  // npm-layout install this is the common case - node_modules is INSIDE workspaceRoot, so a
+  // package's own ESM file counts as first-party source here.
+  if (kind === 'require-call' && isEsmModuleFile(resolved)) return { path: resolved }
   const importerFile = importer && !importer.startsWith('<') ? path.resolve(importer) : ''
+  // `importerFile !== file` keeps this to imports the write pass misses: the entry's OWN local
+  // imports are already walked by writeDevModuleUncached, so another importer means esbuild INLINED
+  // that module here and nobody compiles its relative siblings. It can never also key on the importer
+  // being out-of-workspace - under an npm-layout install pnext's runtime files live in the app's
+  // node_modules, and the sibling was then silently never written. Recompiling is not a risk:
+  // writeDevModule returns an already-written output as-is, so island identity survives navigation.
   const bundledCompatImporter =
-    isLocalSourceSpecifier &&
-    importerFile !== '' &&
-    importerFile !== path.resolve(file) &&
-    !isInside(config.workspaceRoot, importerFile) &&
-    !isInside(config.workspaceRoot, resolved)
-  // The `importerFile !== file` term above keeps this to imports the write pass misses: the entry's
-  // OWN local imports are already walked by writeDevModuleUncached. Everything deeper - a relative
-  // sibling of a compat file esbuild inlined into the entry - is nobody's job but this one, whether
-  // the entry is a workspace module or a node_modules-nested 'use client' component. Gating on an
-  // in-workspace entry left those nested client references importing a file that was never written.
-  // Recompiling is not a risk: writeDevModule returns an already-written output as-is, so island
-  // identity across a soft navigation is preserved.
+    isLocalSourceSpecifier && importerFile !== '' && importerFile !== path.resolve(file)
   if (bundledCompatImporter) {
     // Compile it here, keeping the same compiled-path rewrite so the module stays a single instance -
     // pointing at the raw source instead would load a SECOND copy of the compat runtime graph and split its
@@ -2422,6 +2419,14 @@ async function linkDirectoryAssetContext(
       }
       if (existsSync(target)) return
       await mkdir(path.dirname(target), { recursive: true })
+      // A package manifest linked whole makes the staged mirror a RESOLVABLE package: a bare
+      // `pkg/sub` import from a compiled artifact finds this copy first and fails on an `exports`
+      // subpath that only exists in the real tree. Stage the one field the mirror needs (`type`,
+      // which decides how a compiled `.js` sibling parses) and none of the resolution map.
+      if (entry.name === 'package.json') {
+        await writeText(target, await stagedManifestSource(source))
+        return
+      }
       try {
         await symlink(source, target, 'file')
       } catch {
@@ -2431,6 +2436,15 @@ async function linkDirectoryAssetContext(
   )
 }
 
+async function stagedManifestSource(file: string) {
+  try {
+    const manifest = JSON.parse(await readText(file)) as { type?: unknown }
+    return JSON.stringify(typeof manifest.type === 'string' ? { type: manifest.type } : {})
+  } catch {
+    return '{}'
+  }
+}
+
 // Recursively stage an asset directory: link non-code leaf files and recurse
 // into subdirectories, but never link code files — those compile through the
 // module graph into their own staged output and must not be shadowed by a raw
@@ -2535,8 +2549,7 @@ function uniqueFiles(files: string[]) {
 }
 
 async function profileDevImport<T>(label: string, task: () => Promise<T>) {
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  if (!process.env.PNEXT_DEV_PROFILE) return task()
+  if (!traceEnabled('server')) return task()
   const start = performance.now()
   try {
     return await task()

package/src/runtime/vendor-build.ts

@@ -41,6 +41,7 @@ import {
 } from '../resolve/imports'
 import { clearNodeModulesResolutionCache } from '../resolve/engine'
 import { cachedExistsSync, clearNodeModulesFsCache } from '../utils/fs-cache'
+import { traceEnabled } from '../utils/trace-flags'
 import {
   clientReferenceExportNames,
   clientReferenceModuleSource,
@@ -729,8 +730,7 @@ export function vendorPreplanReport() {
   return { ...vendorPreplanStats, reasons: vendorPreplanStats.reasons.slice(0, 60) }
 }
 
-// eslint-disable-next-line turbo/no-undeclared-env-vars
-const vendorPreplanDebug = () => process.env.PNEXT_VENDOR_PREPLAN_DEBUG === '1'
+const vendorPreplanDebug = () => traceEnabled('vendor')
 let preplanReportFlush: ReturnType<typeof setTimeout> | undefined
 function schedulePreplanReport() {
   if (!vendorPreplanDebug()) return
@@ -1130,12 +1130,11 @@ async function buildVendorGroup(
   await emitNestedExternalTraceCopies(built[0]!.file, context.nestedExternalFiles)
 }
 
-// vendor plugin-callback attribution (PNEXT_VENDOR_PROFILE=1, dormant otherwise). Every
+// vendor plugin-callback attribution (PNEXT_TRACE=vendor, dormant otherwise). Every
 // onResolve/onLoad is an IPC round trip esbuild's bundler blocks on, against the one JS thread that
 // answers them; counts separate "our callbacks are slow" from "we answer many questions".
 
-// eslint-disable-next-line turbo/no-undeclared-env-vars
-const vendorProfileEnabled = process.env.PNEXT_VENDOR_PROFILE === '1'
+const vendorProfileEnabled = traceEnabled('vendor')
 const vendorProfileTotals = new Map<string, number>()
 
 function vendorProfileCount(key: string, by = 1) {
@@ -2532,8 +2531,7 @@ function isResolveFailure(error: unknown) {
 }
 
 async function profileRuntimeStep<T>(label: string, task: () => Promise<T>) {
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  if (!process.env.PNEXT_DEV_PROFILE) return task()
+  if (!traceEnabled('server')) return task()
   const start = performance.now()
   try {
     return await task()

package/src/runtime/vendor.ts

@@ -42,6 +42,7 @@ import { isCommonJsModuleSource } from '../resolve/imports'
 import { outputSpecifiers } from './module-transform'
 import { escapeRegex, isIdentifier, uniqueIdentifier } from '../utils/code'
 import { cachedExistsSync } from '../utils/fs-cache'
+import { traceEnabled, traceValue } from '../utils/trace-flags'
 import { writeFileAtomic } from '../utils/fs'
 
 // --------------------------------------------------------------------------
@@ -217,7 +218,7 @@ function promoteVendorWork(work: VendorPromotable | undefined) {
 }
 
 // --------------------------------------------------------------------------
-// saturation trace (PNEXT_VENDOR_TRACE=1)
+// saturation trace (PNEXT_TRACE=vendor)
 // --------------------------------------------------------------------------
 
 /** One build's occupancy of a worker slot — the active-builds-over-time input. */
@@ -230,8 +231,7 @@ export interface VendorBuildSpan {
 
 const vendorSpans: VendorBuildSpan[] = []
 
-// eslint-disable-next-line turbo/no-undeclared-env-vars
-const vendorTracing = () => process.env.PNEXT_VENDOR_TRACE === '1'
+const vendorTracing = () => traceEnabled('vendor')
 
 function openVendorSpan(label: string, nested: boolean) {
   if (!vendorTracing()) return undefined
@@ -245,14 +245,13 @@ function closeVendorSpan(span: VendorBuildSpan | undefined) {
 }
 
 // --------------------------------------------------------------------------
-// TEMPORARY JSONL workload trace (PNEXT_VENDOR_TRACE=<path>)
+// TEMPORARY JSONL workload trace (PNEXT_TRACE=vendor=<path>)
 // --------------------------------------------------------------------------
 
-// A PATH-valued PNEXT_VENDOR_TRACE appends build/request/edge rows for
-// bench/tools/vendor-analyze.ts; `=1` still means the in-memory spans only.
+// A path-valued `vendor` scope appends build/request/edge rows for
+// bench/tools/vendor-analyze.ts; a bare `vendor` means the in-memory spans only.
 const vendorTraceFile = (() => {
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  const value = process.env.PNEXT_VENDOR_TRACE
+  const value = traceValue('vendor')
   if (!value || !(value.includes('/') || value.endsWith('.jsonl'))) return undefined
   return path.resolve(value)
 })()
@@ -881,7 +880,10 @@ const ESM_DIST_ENTRY_MARKER = 'entry'
 
 const esmDists = new Map<string, Promise<string | undefined>>()
 
-export function copyBrowserReadyEsmDist(entry: string, distDir: string) {
+export function copyBrowserReadyEsmDist(
+  entry: string,
+  distDir: string,
+): Promise<string | undefined> {
   // One copy per destination: a second copier would rewrite files the first has
   // already published, and copyFile is not atomic against a concurrent import.
   let dist = esmDists.get(distDir)
@@ -889,14 +891,24 @@ export function copyBrowserReadyEsmDist(entry: string, distDir: string) {
     dist = copyBrowserReadyEsmDistUncached(entry, distDir)
     esmDists.set(distDir, dist)
   }
-  return dist
+  // A `pnext build` wiping `.pnext` under this server deletes published copies out from under the
+  // memo; a bundle repointed at a vanished dist 500s on every import. Re-verify against disk and
+  // re-copy - the same only-the-stale-holder-evicts rule dropVendorBundle applies to bundles.
+  return dist.then(published => {
+    if (published === undefined || existsSync(published)) return published
+    if (esmDists.get(distDir) === dist) esmDists.delete(distDir)
+    return copyBrowserReadyEsmDist(entry, distDir)
+  })
 }
 
 async function copyBrowserReadyEsmDistUncached(entry: string, distDir: string) {
   const existing = await readFile(path.join(distDir, ESM_DIST_ENTRY_MARKER), 'utf8').catch(
     () => undefined,
   )
-  if (existing !== undefined) return path.join(distDir, existing)
+  // The marker without its entry is a half-deleted copy: fall through and rewrite it.
+  if (existing !== undefined && existsSync(path.join(distDir, existing))) {
+    return path.join(distDir, existing)
+  }
 
   const closure = await collectBrowserReadyEsmClosure(entry)
   if (!closure) return undefined
@@ -1050,8 +1062,12 @@ export function cjsNoFacadeMarker(bundleFile: string) {
 
 const facades = new Map<string, Promise<string | undefined>>()
 
-// eslint-disable-next-line turbo/no-undeclared-env-vars
-const heavyProfFile = process.env.PNEXT_HEAVY_PROF
+// A `.jsonl` value on the server scope selects this profile; any other path is the
+// per-module stats dump (runtime/modules.ts).
+const heavyProfFile = (() => {
+  const value = traceValue('server')
+  return value?.endsWith('.jsonl') ? value : undefined
+})()
 export function heavyProfRow(row: Record<string, unknown>) {
   if (!heavyProfFile) return
   try {

package/src/types.ts

@@ -56,11 +56,20 @@ export interface PNextAdapterConfig {
 }
 
 export interface PNextCompatConfig {
-  next?: boolean
+  next?: boolean | PNextNextCompatConfig
   react?: boolean
   reactCompiler?: boolean
 }
 
+/** Opt-in Next-compat behaviours. Everything here defaults off. */
+export interface PNextNextCompatConfig {
+  /**
+   * Next 15's transitional sync request APIs: cookies()/headers()/draftMode() return a Promise that
+   * also carries the sync surface, warning once per callsite. Off by default (Next 16 semantics).
+   */
+  legacyRequestAPIs?: boolean
+}
+
 export interface MetadataLink {
   rel: string
   url: string

package/src/utils/code.ts

@@ -36,3 +36,8 @@ export function uniqueIdentifier(source: string, base: string, ...used: string[]
 export function isIdentifier(value: string) {
   return /^[A-Za-z_$][\w$]*$/.test(value)
 }
+
+/** Source with comments removed; the `[^:]` guard keeps `://` inside string URLs intact. */
+export function stripComments(source: string): string {
+  return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1')
+}

package/src/utils/dev-profile.ts

@@ -1,5 +1,5 @@
 /**
- * Buffered sink for PNEXT_DEV_PROFILE lines. A warm request emits many phase lines, and writing each
+ * Buffered sink for PNEXT_TRACE=server lines. A warm request emits many phase lines, and writing each
  * straight to stdout inflated every enclosing span it sat inside - the measurement changed what it
  * measured. Lines accumulate here and the request handler flushes them in one write.
  */

package/src/utils/trace-flags.ts

@@ -0,0 +1,66 @@
+/**
+ * `PNEXT_TRACE=<comma-separated scopes>` - the single umbrella for pnext's diagnostic output.
+ * The variable is parsed once, on first use; every later check is a map lookup on a boolean test,
+ * so a build with tracing off pays nothing.
+ *
+ * Grammar: entries are `scope` or `scope=value`, comma separated. `1` is an alias for `boot`
+ * (`PNEXT_TRACE=1` keeps its old meaning) and `all` turns on every scope.
+ * Example: `PNEXT_TRACE=boot,server=/tmp/modules.json`.
+ *
+ * A scope is all-or-nothing: turning one on turns on everything it covers.
+ *
+ * | scope    | prints / does                                                                     |
+ * | -------- | --------------------------------------------------------------------------------- |
+ * | `boot`   | boot-phase timings and memory readings                                            |
+ * | `server` | dev request / render / build timings, per-module compile attribution, route-facts and global-css hit/miss, cache-invalidation reasons, load-plugin registrations |
+ * | `vendor` | vendor saturation spans, esbuild plugin-callback attribution, preplan/native report |
+ * | `client` | client-build phase timings, and the esbuild metafile written to the output dir     |
+ * | `all`    | the four above                                                                    |
+ *
+ * Two scopes take a `=<path>` value:
+ * - `server=<path>` dumps the per-module compile list as JSON; a `.jsonl` path instead collects the
+ *   heavy-package facade profile (they are never wanted at once, and the suffix picks between them).
+ * - `vendor=<path>` appends the JSONL workload trace bench/tools/vendor-analyze.ts reads.
+ */
+
+/** Parse one raw `PNEXT_TRACE` value into scope -> value (`''` when the entry carried none). */
+export function parseTraceFlags(raw: string | undefined): Map<string, string> {
+  const scopes = new Map<string, string>()
+  for (const entry of raw?.split(',') ?? []) {
+    const trimmed = entry.trim()
+    if (!trimmed) continue
+    const eq = trimmed.indexOf('=')
+    const name = eq === -1 ? trimmed : trimmed.slice(0, eq).trim()
+    if (!name) continue
+    scopes.set(name === '1' ? 'boot' : name, eq === -1 ? '' : trimmed.slice(eq + 1).trim())
+  }
+  return scopes
+}
+
+let scopes: Map<string, string> | undefined
+let all = false
+
+function flags() {
+  if (!scopes) {
+    // eslint-disable-next-line turbo/no-undeclared-env-vars
+    scopes = parseTraceFlags(process.env.PNEXT_TRACE)
+    all = scopes.has('all')
+  }
+  return scopes
+}
+
+/** Drop the memoized parse - for tests and benches that flip PNEXT_TRACE in-process. */
+export function resetTraceFlags() {
+  scopes = undefined
+  all = false
+}
+
+/** True when `scope` (or `all`) is listed in PNEXT_TRACE, with or without a value. */
+export function traceEnabled(scope: string): boolean {
+  return flags().has(scope) || all
+}
+
+/** The `scope=<value>` payload, or undefined when the scope is absent or valueless. */
+export function traceValue(scope: string): string | undefined {
+  return flags().get(scope) || undefined
+}