@wular/pnext 0.0.1

package/src/resolve/scan-facts.ts

@@ -0,0 +1,474 @@
+// One oxc-parser pass per unique source, memoized by content: every module fact the scanners need (imports,
+// re-exports, `export *`, own export names, the `'use client'` directive) comes from that single parse
+// instead of the regex passes and transpiler scan they replace. Regexes read comments and strings as code
+// (phantom `type` imports, `'use client'` inside a comment) and never saw `export * from`; the transpiler
+// scan reports its own injected JSX-runtime imports and throws on a shebang.
+//
+// Expression-shaped facts (dynamic() options, segment config, request-API use) stay on their gated string
+// passes - materializing the full AST for them is slower than the passes they would replace.
+//
+// The same parse also backs `rewriteFacts`: the record-shaped rewrite passes (specifier aliasing, namespace
+// imports, import.meta.url) splice byte spans off it instead of re-scanning the source with their own
+// regexes.
+import { parseSync } from 'oxc-parser';
+import { spliceSource } from '../dev/module-transform';
+
+export interface ScanEdge {
+  specifier: string;
+  /** Bound names: `default`, `*` (namespace object), or the imported names. */
+  exports: string[];
+  /** Byte offset of the statement — edges are consumed in true source order. */
+  index: number;
+  /** `export * from`: binds every named export of the target, none of them known here. */
+  star?: boolean;
+  /** `export … from` rather than `import`. */
+  reexport?: boolean;
+}
+
+/** One module specifier literal, with the span of its quoted text. */
+export interface SpecifierEdge {
+  specifier: string;
+  /** Span of the quoted literal, quotes included. */
+  start: number;
+  end: number;
+  /** `side-effect` is `import 'x'`: no clause, so no `from` for a textual pass to key on. */
+  kind: 'import' | 'side-effect' | 'export' | 'dynamic' | 'require';
+}
+
+export interface ImportBinding {
+  /** Name in the target module; `default`/`*` for the default/namespace forms. */
+  imported: string;
+  local: string;
+  /** `import type …` / `{ type X }`: erased, but part of the statement's text. */
+  type: boolean;
+}
+
+/** A static `import` statement, spans included — the unit the folded passes splice. */
+export interface ImportStatement {
+  specifier: string;
+  /** Statement span (`import` … `;`). */
+  start: number;
+  end: number;
+  /** Span of the quoted specifier literal inside the statement. */
+  specifierStart: number;
+  specifierEnd: number;
+  bindings: ImportBinding[];
+}
+
+/**
+ * The module-record projection the rewrite passes splice against: specifier literals, import statements and
+ * `import.meta` spans, all exact - never a match inside a string or comment. Shares `scanFacts`' memoized
+ * parse, so a folded pass on an already-scanned source costs nothing beyond the lookup.
+ */
+export interface RewriteFacts {
+  edges: SpecifierEdge[];
+  imports: ImportStatement[];
+  importMetas: { start: number; end: number }[];
+  /**
+   * The parse recovered from errors, so the record may be incomplete — folded
+   * passes fall back to their textual form rather than silently under-rewrite.
+   */
+  unreliable: boolean;
+}
+
+export interface ScanFacts {
+  /** Static value imports and `export … from` re-exports, in source order. */
+  imports: ScanEdge[];
+  /** `import('literal')` expressions, in source order. */
+  dynamicImports: { specifier: string; index: number }[];
+  /** `require('literal')` calls — CJS sources still reach these scanners. */
+  requires: { specifier: string; index: number; specifierStart: number }[];
+  /** This module's own value export names, `default` included. */
+  exportNames: string[];
+  /** Specifiers of `export * from` (whose names live in the target). */
+  exportStars: string[];
+  /** A real `'use client'` directive — prologue position only, never a comment. */
+  useClient: boolean;
+}
+
+const stylesheetOrData = /\.(?:css|scss|sass|less|styl|json)$/;
+
+const emptyFacts: ScanFacts = {
+  imports: [],
+  dynamicImports: [],
+  requires: [],
+  exportNames: [],
+  exportStars: [],
+  useClient: false,
+};
+
+const emptyRewriteFacts: RewriteFacts = {
+  edges: [],
+  imports: [],
+  importMetas: [],
+  unreliable: false,
+};
+
+const memo = new Map<string, { scan: ScanFacts; rewrite: RewriteFacts }>();
+let hits = 0;
+let misses = 0;
+
+export function scanFacts(file: string, source: string): ScanFacts {
+  // The module walk reaches stylesheets/data as ordinary edges; they hold no
+  // module facts and are not parseable as script.
+  if (stylesheetOrData.test(file)) return emptyFacts;
+  return parsed(file, source).scan;
+}
+
+/** Every specifier a module pulls in — static, dynamic and `require`, in source order. */
+export function importSpecifiers(source: string, sourcefile = 'source') {
+  const facts = scanFacts(sourcefile, source);
+  return [
+    ...facts.imports.map(edge => edge.specifier),
+    ...facts.dynamicImports.map(entry => entry.specifier),
+    ...facts.requires.map(entry => entry.specifier),
+  ];
+}
+
+export function moduleExportNames(source: string, sourcefile = 'source.tsx') {
+  return scanFacts(sourcefile, source).exportNames;
+}
+
+/** Specifiers of `export * from` — their names live in the target module. */
+export function moduleExportStars(source: string, sourcefile = 'source.tsx') {
+  return scanFacts(sourcefile, source).exportStars;
+}
+
+/** Module-record spans for the rewrite passes (see `RewriteFacts`). */
+export function rewriteFacts(file: string, source: string): RewriteFacts {
+  if (stylesheetOrData.test(file)) return emptyRewriteFacts;
+  return parsed(file, source).rewrite;
+}
+
+function parsed(file: string, source: string, lang = langForFile(file)) {
+  const key = `${lang}\0${source.length}\0${Bun.hash(source).toString()}`;
+  const cached = memo.get(key);
+  if (cached) {
+    hits += 1;
+    return cached;
+  }
+  misses += 1;
+  const facts = parseFacts(file, source, lang);
+  memo.set(key, facts);
+  return facts;
+}
+
+/**
+ * Splice every module specifier `replace` answers for, in place. The span is
+ * the quoted literal, so formatting and comments around it are untouched, and
+ * a specifier appearing in a string or a comment is never seen at all.
+ * `replace` returns the REPLACEMENT LITERAL (quotes included) or undefined.
+ */
+export function rewriteSpecifierLiterals(
+  source: string,
+  file: string,
+  replace: (specifier: string, kind: SpecifierEdge['kind']) => string | undefined,
+): string {
+  const facts = rewriteFacts(file, source);
+  // A partially recovered parse has a partial record; the textual scan the
+  // folded passes replaced is the safe answer there.
+  const edges = facts.unreliable ? textualEdges(source) : facts.edges;
+  const edits: { start: number; end: number; value: string }[] = [];
+  for (const edge of edges) {
+    const value = replace(edge.specifier, edge.kind);
+    if (value !== undefined) edits.push({ start: edge.start, end: edge.end, value });
+  }
+  return edits.length > 0 ? spliceSource(source, edits) : source;
+}
+
+const textualSpecifier = /(\bfrom\s*|\b(?:import|require)\s*\(\s*)(['"])([^'"]+)\2/g;
+
+function textualEdges(source: string): SpecifierEdge[] {
+  const edges: SpecifierEdge[] = [];
+  textualSpecifier.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = textualSpecifier.exec(source))) {
+    const start = match.index + match[1]!.length;
+    edges.push({
+      specifier: match[3]!,
+      start,
+      end: start + match[3]!.length + 2,
+      kind: match[1]!.includes('require') ? 'require' : match[1]!.includes('import') ? 'dynamic' : 'import',
+    });
+  }
+  return edges;
+}
+
+/** Memo effectiveness, for the dev-boot benches. */
+export function scanFactsStats() {
+  return { hits, misses, sources: memo.size };
+}
+
+function parseFacts(file: string, source: string, lang: ParserLang) {
+  // Parse errors are recovered, never thrown: a scan of a half-typed file in
+  // the dev watcher must still yield whatever the parser did understand.
+  const result = parseSync(file, source, { lang });
+  const imports: ScanEdge[] = [];
+  const exportNames: string[] = [];
+  const exportStars: string[] = [];
+  const edges: SpecifierEdge[] = [];
+  const importStatements: ImportStatement[] = [];
+
+  for (const statement of result.module.staticImports) {
+    const names: string[] = [];
+    const bindings: ImportBinding[] = [];
+    let bindsValue = statement.entries.length === 0;
+    for (const entry of statement.entries) {
+      const kind: string = entry.importName.kind;
+      bindings.push({
+        imported:
+          kind === 'Default' ? 'default' : kind === 'NamespaceObject' ? '*' : (entry.importName.name ?? ''),
+        local: entry.localName.value ?? '',
+        type: entry.isType,
+      });
+      if (entry.isType) continue;
+      bindsValue = true;
+      if (kind === 'Default') names.push('default');
+      else if (kind === 'NamespaceObject') names.push('*');
+      else if (entry.importName.name) names.push(entry.importName.name);
+    }
+    importStatements.push({
+      specifier: statement.moduleRequest.value,
+      start: statement.start,
+      end: statement.end,
+      specifierStart: statement.moduleRequest.start,
+      specifierEnd: statement.moduleRequest.end,
+      bindings,
+    });
+    edges.push({
+      specifier: statement.moduleRequest.value,
+      start: statement.moduleRequest.start,
+      end: statement.moduleRequest.end,
+      kind: statement.entries.length === 0 ? 'side-effect' : 'import',
+    });
+    // `import type { … }` binds nothing at runtime: not an edge.
+    if (!bindsValue) continue;
+    imports.push({
+      specifier: statement.moduleRequest.value,
+      exports: names,
+      index: statement.start,
+    });
+  }
+
+  // One `export { a, b } from 'x'` reports the same moduleRequest per entry.
+  const seenExportRequests = new Set<number>();
+  for (const statement of result.module.staticExports) {
+    for (const entry of statement.entries) {
+      const request = entry.moduleRequest;
+      if (!request || seenExportRequests.has(request.start)) continue;
+      seenExportRequests.add(request.start);
+      edges.push({ specifier: request.value, start: request.start, end: request.end, kind: 'export' });
+    }
+  }
+
+  for (const statement of result.module.staticExports) {
+    const edges = new Map<string, ScanEdge>();
+    for (const entry of statement.entries) {
+      if (entry.isType) continue;
+      const exportKind: string = entry.exportName.kind;
+      if (exportKind === 'Default') exportNames.push('default');
+      else if (entry.exportName.name) exportNames.push(entry.exportName.name);
+
+      const specifier = entry.moduleRequest?.value;
+      if (!specifier) continue;
+      const importKind: string = entry.importName.kind;
+      const star = importKind === 'AllButDefault';
+      if (star) exportStars.push(specifier);
+      let edge = edges.get(specifier);
+      if (!edge) {
+        edge = { specifier, exports: [], index: statement.start, reexport: true };
+        edges.set(specifier, edge);
+        imports.push(edge);
+      }
+      if (star) edge.star = true;
+      else if (importKind === 'All') edge.exports.push('*');
+      else if (entry.importName.name) edge.exports.push(entry.importName.name);
+    }
+  }
+
+  imports.sort((a, b) => a.index - b.index);
+
+  const dynamicImports: { specifier: string; index: number }[] = [];
+  for (const entry of result.module.dynamicImports) {
+    const raw = source.slice(entry.moduleRequest.start, entry.moduleRequest.end);
+    const specifier = literalSpecifier(raw);
+    if (specifier === undefined) continue;
+    dynamicImports.push({ specifier, index: entry.start });
+    // The literal's own span, without the whitespace `moduleRequest` includes.
+    const lead = raw.length - raw.trimStart().length;
+    edges.push({
+      specifier,
+      start: entry.moduleRequest.start + lead,
+      end: entry.moduleRequest.start + lead + specifier.length + 2,
+      kind: 'dynamic',
+    });
+  }
+
+  const requires = requireCalls(source, result.comments);
+  for (const call of requires) {
+    edges.push({
+      specifier: call.specifier,
+      start: call.specifierStart,
+      end: call.specifierStart + call.specifier.length + 2,
+      kind: 'require',
+    });
+  }
+  edges.sort((a, b) => a.start - b.start);
+
+  return {
+    scan: {
+      imports,
+      dynamicImports,
+      requires,
+      exportNames,
+      exportStars,
+      useClient: hasUseClient(source, result),
+    },
+    rewrite: {
+      edges,
+      imports: importStatements,
+      importMetas: result.module.importMetas.map(meta => ({ start: meta.start, end: meta.end })),
+      unreliable: result.errors.length > 0,
+    },
+  };
+}
+
+/**
+ * `result.program.body` deserializes the whole AST across the NAPI boundary, and the prologue sniff
+ * was its only consumer. The raw-source scanner answers it without the AST; the AST is still
+ * consulted for the prologue shapes the scanner will not commit to.
+ */
+function hasUseClient(source: string, result: { program: { body: readonly Directive[] } }) {
+  const sniffed = sniffDirective(source, 'use client');
+  if (sniffed !== undefined) return sniffed;
+  // Uncertain, but a directive is its raw text: no occurrence, no directive.
+  if (!source.includes('use client')) return false;
+  return hasDirective(result.program.body, 'use client');
+}
+
+interface Directive {
+  type: string;
+  directive?: string | null;
+}
+
+// A string literal is only a directive if what follows it ends the statement; a
+// continuation token means it was an expression (`'use client' + x`).
+const continuesExpression = /[+\-*/%.,?:=<>!&|^~([`)\]}]/;
+const wordContinuation = /^(?:in|instanceof)\b/;
+const lineTerminator = /[\n\r\u2028\u2029]/;
+
+/**
+ * Directive-prologue sniff over raw source. Returns undefined - not a guess - for any shape it cannot decide
+ * exactly (escaped literal, unterminated string or comment, ambiguous ASI), so the caller falls back to the
+ * AST.
+ */
+function sniffDirective(source: string, directive: string): boolean | undefined {
+  let index = 0;
+  if (source.startsWith('#!')) {
+    const nl = source.search(lineTerminator);
+    if (nl < 0) return false;
+    index = nl + 1;
+  }
+  for (;;) {
+    index = skipTrivia(source, index);
+    if (index < 0) return undefined;
+    const quote = source[index];
+    if (quote !== '"' && quote !== "'") return false; // prologue is over
+
+    let end = index + 1;
+    while (end < source.length) {
+      const char = source[end]!;
+      // An escape makes the raw text differ from the directive, but decoding it
+      // exactly is the AST's job, not this scanner's.
+      if (char === '\\' || lineTerminator.test(char)) return undefined;
+      if (char === quote) break;
+      end += 1;
+    }
+    if (end >= source.length) return undefined; // unterminated literal
+    const raw = source.slice(index + 1, end);
+
+    const after = skipTrivia(source, end + 1);
+    if (after < 0) return undefined;
+    const next = source[after];
+    let terminated = after >= source.length || next === ';';
+    if (!terminated && lineTerminator.test(source.slice(end + 1, after))) {
+      // ASI closes the statement unless the next token continues the expression.
+      terminated = !continuesExpression.test(next!) && !wordContinuation.test(source.slice(after, after + 11));
+    }
+    if (!terminated) return undefined;
+    if (raw === directive) return true;
+    index = next === ';' ? after + 1 : after;
+    if (index >= source.length) return false;
+  }
+}
+
+/** Past whitespace and comments; -1 for an unterminated block comment. */
+function skipTrivia(source: string, index: number) {
+  for (;;) {
+    while (index < source.length && /\s/.test(source[index]!)) index += 1;
+    if (source[index] !== '/') return index;
+    if (source[index + 1] === '/') {
+      let end = index + 2;
+      while (end < source.length && !lineTerminator.test(source[end]!)) end += 1;
+      index = end;
+      continue;
+    }
+    if (source[index + 1] === '*') {
+      const end = source.indexOf('*/', index + 2);
+      if (end < 0) return -1;
+      index = end + 2;
+      continue;
+    }
+    return index;
+  }
+}
+
+function hasDirective(body: readonly { type: string; directive?: string | null }[], directive: string) {
+  // The prologue ends at the first non-directive statement; comments and other
+  // directives before it do not.
+  for (const statement of body) {
+    if (statement.type !== 'ExpressionStatement' || typeof statement.directive !== 'string') return false;
+    if (statement.directive === directive) return true;
+  }
+  return false;
+}
+
+const requirePattern = /\brequire\s*\(\s*(['"])([^'"]+)\1\s*\)/g;
+
+/**
+ * CJS `require` is an ordinary call, not a module record entry, so it stays on a regex - but a regex reads
+ * comments as code, and a prose `require('x')` in a doc comment became a real graph edge, an unresolvable
+ * one aborting the whole module compile. The parse's comment spans are already in hand, so drop every match
+ * that lands inside one.
+ */
+function requireCalls(source: string, comments: readonly { start: number; end: number }[]) {
+  const calls: { specifier: string; index: number; specifierStart: number }[] = [];
+  if (!source.includes('require')) return calls;
+  requirePattern.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  // Both comments and matches ascend, so one shared cursor walks them together.
+  let cursor = 0;
+  while ((match = requirePattern.exec(source))) {
+    const index = match.index;
+    while (cursor < comments.length && comments[cursor]!.end <= index) cursor += 1;
+    if (cursor < comments.length && index >= comments[cursor]!.start) continue;
+    calls.push({
+      specifier: match[2]!,
+      index,
+      specifierStart: index + match[0].indexOf(match[1]!),
+    });
+  }
+  return calls;
+}
+
+function literalSpecifier(raw: string) {
+  return /^\s*(['"])([^'"]*)\1\s*$/.exec(raw)?.[2] || undefined;
+}
+
+type ParserLang = 'ts' | 'tsx';
+
+// `.ts` forbids JSX (`<T>value` is a type assertion there); everything else —
+// including extensionless scan inputs — parses as the tsx superset.
+function langForFile(file: string): ParserLang {
+  return /\.[mc]?ts$/.test(file) ? 'ts' : 'tsx';
+}

package/src/resolve/source-text.ts

@@ -0,0 +1,86 @@
+// One read per first-party source per build. A build has three consumers of the same app sources -
+// the route-fact walk (sync), action discovery (async) and the client loader (async) - and each used
+// to read the file itself. Whoever asks first pays; everyone after gets the same string. This buys
+// reads, not parses: `scanFacts`' memo is keyed on content, so the three already shared one parse
+// per source.
+//
+// Scoped, not global: `beginSourceScope`/`endSourceScope` bracket a single build, so the map is
+// released when it ends and nothing outside a build is cached at all. That is what keeps the dev
+// watcher out of it - dev reads go straight to the filesystem, so a save is never served a stale
+// string, and content-keyed invalidation downstream is untouched.
+import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+
+// eslint-disable-next-line turbo/no-undeclared-env-vars
+const disabled = process.env.PNEXT_SRC_CACHE === '0';
+
+const contents = new Map<string, string>();
+// Reads still in flight: two async consumers asking at once share one read
+// rather than racing two. Resolved entries move to `contents`.
+const inflight = new Map<string, Promise<string>>();
+let scoped = false;
+let reads = 0;
+let hits = 0;
+
+/**
+ * Start caching source reads. Two builds in one process (the test runner) share the map - keyed by absolute
+ * path, so a shared entry is the same file - and whichever ends first drops it; the other keeps building,
+ * uncached.
+ */
+export function beginSourceScope() {
+  if (disabled) return;
+  scoped = true;
+}
+
+/** End the scope and drop everything it held. */
+export function endSourceScope() {
+  scoped = false;
+  contents.clear();
+  inflight.clear();
+}
+
+export function readSourceSync(file: string): string {
+  if (!scoped) return readFileSync(file, 'utf8');
+  const cached = contents.get(file);
+  if (cached !== undefined) {
+    hits += 1;
+    return cached;
+  }
+  reads += 1;
+  const source = readFileSync(file, 'utf8');
+  contents.set(file, source);
+  return source;
+}
+
+export async function readSourceText(file: string): Promise<string> {
+  if (!scoped) return readFile(file, 'utf8');
+  const cached = contents.get(file);
+  if (cached !== undefined) {
+    hits += 1;
+    return cached;
+  }
+  const pending = inflight.get(file);
+  if (pending) {
+    hits += 1;
+    return pending;
+  }
+  reads += 1;
+  // A read that fails is dropped from `inflight` too: the next asker retries and
+  // sees the error at its own call site, as it would without the cache.
+  const read = (async () => {
+    try {
+      const source = await readFile(file, 'utf8');
+      contents.set(file, source);
+      return source;
+    } finally {
+      inflight.delete(file);
+    }
+  })();
+  inflight.set(file, read);
+  return read;
+}
+
+/** Read effectiveness, for the build benches. */
+export function sourceCacheStats() {
+  return { reads, hits, files: contents.size };
+}

package/src/routing/forwarded.ts

@@ -0,0 +1,41 @@
+// x-forwarded-* request header injection (CORE HTTP correctness).
+//
+// Before route matching / render, the server records the observed host, port,
+// and protocol on the incoming request headers so headers() during render and
+// any request-header reader (middleware, route handlers) see them. Client-sent
+// x-forwarded-* values are never overridden (a trusted proxy already set them),
+// including multi-value forms like "https, https".
+
+const FORWARDED_HOST = 'x-forwarded-host';
+const FORWARDED_PORT = 'x-forwarded-port';
+const FORWARDED_PROTO = 'x-forwarded-proto';
+
+/**
+ * Return the request with x-forwarded-host/port/proto injected from the request
+ * URL + Host header, preserving any client-sent values. Returns the same
+ * request when every value was already present (no allocation on the hot path).
+ */
+export function withForwardedHeaders(request: Request): Request {
+  const headers = request.headers;
+  const hasHost = headers.has(FORWARDED_HOST);
+  const hasPort = headers.has(FORWARDED_PORT);
+  const hasProto = headers.has(FORWARDED_PROTO);
+  if (hasHost && hasPort && hasProto) return request;
+
+  let url: URL;
+  try {
+    url = new URL(request.url);
+  } catch {
+    return request;
+  }
+  const host = headers.get('host') ?? url.host;
+  const proto = url.protocol.replace(':', '');
+  // The server's own listen port (reflected in the request URL by the runtime).
+  const port = url.port;
+
+  const next = new Headers(headers);
+  if (!hasHost) next.set(FORWARDED_HOST, host);
+  if (!hasPort) next.set(FORWARDED_PORT, port);
+  if (!hasProto) next.set(FORWARDED_PROTO, proto);
+  return new Request(request, { headers: next });
+}