@wular/pnext 0.0.1

package/src/dynamic/source.ts

@@ -0,0 +1,307 @@
+import { rewriteFacts } from '../resolve/scan-facts';
+
+export interface DynamicCall {
+  index: number;
+  name: string;
+  open: number;
+  close: number;
+  source: string;
+}
+
+/** Cheap gate: a `dynamic` binding can only come from one of these specifiers. */
+export function sourceHasDynamicImport(source: string) {
+  return source.includes('@wular/pnext') || source.includes('next/dynamic');
+}
+
+/**
+ * Local names bound to `dynamic()`. The import edge is module-record-shaped and
+ * comes off the memoized parse; only the call-site
+ * scanning below stays textual.
+ */
+export function pnextDynamicImportNames(source: string, file = 'module.tsx') {
+  const names = new Set<string>();
+  if (!sourceHasDynamicImport(source)) return names;
+  for (const statement of rewriteFacts(file, source).imports) {
+    const { specifier } = statement;
+    const pnext = specifier === '@wular/pnext' || specifier === '@wular/pnext/dynamic';
+    // The compat alias rewrite may already have turned `next/dynamic` into the
+    // shim's own file path/href before this scan runs.
+    const nextDynamic =
+      specifier === 'next/dynamic' || /compat\/next\/dynamic(?:\.tsx)?$/.test(specifier);
+    if (!pnext && !nextDynamic) continue;
+    for (const binding of statement.bindings) {
+      if (binding.type) continue;
+      if (pnext ? binding.imported === 'dynamic' : binding.imported === 'default') {
+        names.add(binding.local);
+      }
+    }
+  }
+  return names;
+}
+
+export function dynamicCallsFromSource(source: string, dynamicNames: Set<string>) {
+  const calls: DynamicCall[] = [];
+  if (dynamicNames.size === 0) return calls;
+
+  let index = 0;
+
+  while ((index = nextDynamicCallIndex(source, dynamicNames, index)) !== -1) {
+    const name = dynamicNameAt(source, dynamicNames, index);
+    if (!name) {
+      index += 1;
+      continue;
+    }
+    const before = source[index - 1];
+    const after = source[index + name.length];
+    if ((before && /[\w$]/.test(before)) || (after && /[\w$]/.test(after))) {
+      index += name.length;
+      continue;
+    }
+
+    const open = source.indexOf('(', index + name.length);
+    if (open === -1 || source.slice(index + name.length, open).trim()) {
+      index += name.length;
+      continue;
+    }
+
+    const close = matchingParen(source, open);
+    if (close === -1) {
+      index = open + 1;
+      continue;
+    }
+
+    calls.push({
+      index,
+      name,
+      open,
+      close,
+      source: source.slice(index, close + 1),
+    });
+    index = close + 1;
+  }
+
+  return calls;
+}
+
+export function rewriteLiteralDynamicCalls(source: string, file?: string) {
+  const dynamicNames = pnextDynamicImportNames(source, file);
+  if (dynamicNames.size === 0) return source;
+
+  const edits: { start: number; end: number; value: string }[] = [];
+  for (const call of dynamicCallsFromSource(source, dynamicNames)) {
+    const args = source.slice(call.open + 1, call.close);
+    const literal = /^(\s*)(['"])([^'"]+)\2(?=\s*(?:,|$))/.exec(args);
+    if (!literal) continue;
+    const [match, leading = '', quote = "'", specifier] = literal;
+    if (!specifier) continue;
+    const start = call.open + 1 + leading.length;
+    edits.push({
+      start,
+      end: call.open + 1 + match.length,
+      value: `() => import(${quote}${specifier}${quote})`,
+    });
+  }
+
+  if (edits.length === 0) return source;
+
+  let next = source;
+  for (const edit of edits.reverse()) {
+    next = `${next.slice(0, edit.start)}${edit.value}${next.slice(edit.end)}`;
+  }
+  return next;
+}
+
+// Server compiles append the statically-resolved import target as a third
+// dynamic() argument, so the renderer can match the call to its scanned client
+// reference without importing the module. Instance identity is useless for
+// that match: dev route bundles, per-module compiles, and the client-SSR
+// profile each produce their own copy of the target module.
+export function rewriteDynamicCallTargets(
+  source: string,
+  resolve: (specifier: string) => string | undefined,
+  file?: string,
+) {
+  const dynamicNames = pnextDynamicImportNames(source, file);
+  if (dynamicNames.size === 0) return source;
+
+  const edits: { at: number; value: string }[] = [];
+  for (const call of dynamicCallsFromSource(source, dynamicNames)) {
+    const target = dynamicImportTarget.exec(call.source);
+    if (!target?.[2]) continue;
+    const file = resolve(target[2]);
+    if (!file) continue;
+
+    const args = source.slice(call.open + 1, call.close);
+    const argCount = topLevelArgCount(args);
+    if (argCount < 1 || argCount > 2) continue;
+    const literal = JSON.stringify({ file, exportName: target[4] ?? 'default' });
+    const separator = /,\s*$/.test(args) ? '' : ', ';
+    edits.push({
+      at: call.close,
+      value: `${separator}${argCount === 1 ? 'undefined, ' : ''}${literal}`,
+    });
+  }
+
+  if (edits.length === 0) return source;
+
+  let next = source;
+  for (const edit of edits.reverse()) {
+    next = `${next.slice(0, edit.at)}${edit.value}${next.slice(edit.at)}`;
+  }
+  return next;
+}
+
+const dynamicImportTarget =
+  /import\s*\(\s*(['"])([^'"]+)\1\s*\)(?:\s*\.then\s*\(\s*([A-Za-z_$][\w$]*)\s*=>\s*\3\.([A-Za-z_$][\w$]*)\s*\))?/;
+
+/** Dev split of `dynamic(ssr:false)` targets; `PNEXT_DYNAMIC_SPLIT=0` restores eager builds. */
+export function devDynamicSplitEnabled() {
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  return process.env.PNEXT_DYNAMIC_SPLIT !== '0';
+}
+
+/**
+ * Rewrite each deferred dynamic() import in a CLIENT-BUILD source to the served
+ * chunk URL `href` names, so the entry build never bundles the target's graph.
+ * Callers register the (file, exportName) behind each URL as `href` is asked.
+ */
+export function rewriteDeferredDynamicImports(
+  source: string,
+  file: string | undefined,
+  resolve: (specifier: string) => string | undefined,
+  href: (target: { file: string; exportName: string }) => string | undefined,
+) {
+  const dynamicNames = pnextDynamicImportNames(source, file);
+  if (dynamicNames.size === 0) return source;
+  const deferred = deferredDynamicImportSpecifiers(source, file);
+  if (deferred.size === 0) return source;
+
+  const edits: { start: number; end: number; value: string }[] = [];
+  for (const call of dynamicCallsFromSource(source, dynamicNames)) {
+    const target = dynamicImportTarget.exec(call.source);
+    if (!target?.[2] || !deferred.has(target[2])) continue;
+    const resolved = resolve(target[2]);
+    if (!resolved) continue;
+    const url = href({ file: resolved, exportName: target[4] ?? 'default' });
+    if (!url) continue;
+    const specifierAt = call.index + target.index + target[0].indexOf(target[2]);
+    edits.push({ start: specifierAt, end: specifierAt + target[2].length, value: url });
+  }
+  if (edits.length === 0) return source;
+  let next = source;
+  for (const edit of edits.sort((a, b) => b.start - a.start)) {
+    next = `${next.slice(0, edit.start)}${edit.value}${next.slice(edit.end)}`;
+  }
+  return next;
+}
+
+/**
+ * Import specifiers of `dynamic()` calls the SSR layer never executes (`ssr: false`, or `load: 'visible'`
+ * without `ssr: true`) - the dev split points: their target modules compile on browser demand, not eagerly.
+ */
+export function deferredDynamicImportSpecifiers(source: string, file?: string) {
+  const deferred = new Set<string>();
+  const dynamicNames = pnextDynamicImportNames(source, file);
+  if (dynamicNames.size === 0) return deferred;
+
+  // `const opts = { ssr: false }` option objects referenced by name.
+  const optionConsts = new Map<string, string>();
+  const constPattern = /const\s+([A-Za-z_$][\w$]*)\s*=\s*({[\s\S]*?})\s*(?:as\s+const\s*)?;/g;
+  let constMatch: RegExpExecArray | null;
+  while ((constMatch = constPattern.exec(source))) {
+    if (constMatch[1] && constMatch[2]) optionConsts.set(constMatch[1], constMatch[2]);
+  }
+
+  for (const call of dynamicCallsFromSource(source, dynamicNames)) {
+    const target = dynamicImportTarget.exec(call.source);
+    if (!target?.[2]) continue;
+    // Token scan over the call plus any named option consts it references —
+    // tolerant of the compile-appended target argument (rewriteDynamicCallTargets).
+    const args = source.slice(call.open + 1, call.close);
+    const tail = args.slice(args.indexOf(target[0]) + target[0].length);
+    let options = tail;
+    for (const identifier of tail.match(/[A-Za-z_$][\w$]*/g) ?? []) {
+      const named = optionConsts.get(identifier);
+      if (named) options += `\n${named}`;
+    }
+    const ssrFalse = /\bssr\s*:\s*false\b/.test(options);
+    const visible =
+      /\bload\s*:\s*['"]visible['"]/.test(options) && !/\bssr\s*:\s*true\b/.test(options);
+    if (ssrFalse || visible) deferred.add(target[2]);
+  }
+  return deferred;
+}
+
+function topLevelArgCount(args: string) {
+  let count = 0;
+  let depth = 0;
+  let quote: string | null = null;
+  let sawArg = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const char = args[index];
+    if (quote) {
+      if (char === quote && args[index - 1] !== '\\') quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === '`') {
+      quote = char;
+      sawArg = true;
+      continue;
+    }
+    if (char === '(' || char === '[' || char === '{') depth += 1;
+    if (char === ')' || char === ']' || char === '}') depth -= 1;
+    if (char === ',' && depth === 0) {
+      if (sawArg) count += 1;
+      sawArg = false;
+      continue;
+    }
+    if (!/\s/.test(char ?? '')) sawArg = true;
+  }
+
+  return sawArg ? count + 1 : count;
+}
+
+function matchingParen(source: string, open: number) {
+  let depth = 0;
+  let quote: string | null = null;
+
+  for (let index = open; index < source.length; index += 1) {
+    const char = source[index];
+    const previous = source[index - 1];
+
+    if (quote) {
+      if (char === quote && previous !== '\\') quote = null;
+      continue;
+    }
+
+    if (char === '"' || char === "'" || char === '`') {
+      quote = char;
+      continue;
+    }
+
+    if (char === '(') depth += 1;
+    if (char === ')') {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+
+  return -1;
+}
+
+function nextDynamicCallIndex(source: string, dynamicNames: Set<string>, fromIndex: number) {
+  let next = -1;
+  for (const name of dynamicNames) {
+    const index = source.indexOf(name, fromIndex);
+    if (index !== -1 && (next === -1 || index < next)) next = index;
+  }
+  return next;
+}
+
+function dynamicNameAt(source: string, dynamicNames: Set<string>, index: number) {
+  for (const name of dynamicNames) {
+    if (source.startsWith(name, index)) return name;
+  }
+  return undefined;
+}

package/src/dynamic/tree-shake.ts

@@ -0,0 +1,262 @@
+// Tree-shaking for destructured dynamic imports (mirrors webpack's `import()` export usage analysis).
+//
+// `const { used } = await import('./mod')` only ever touches `used`, so the unused exports of './mod' are
+// dead. esbuild cannot see this across the dynamic-import boundary (each module is compiled standalone and
+// keeps every export), so the server module compiler rewrites the qualifying `import()` to a per-usage
+// facade module that re-exports ONLY the destructured names, letting esbuild drop the rest when it inlines
+// the target.
+//
+// Only the syntactic forms webpack tree-shakes are recognized:
+//   - `const|let|var { a, b: c } = await import('lit')`   (named / renamed)
+//   - `const { nested: { inner } } = await import('lit')` (top-level key kept)
+//   - `const { default: d } = await import('lit')`        (default kept)
+//   - `const {} = await import('lit')`                    (all exports dropped; side effects kept)
+//   - `/* webpackExports: [...] */` magic comment overrides the used set.
+//
+// A rest element, member access, re-assignment and `.then(({ ... }) => ...)` destructuring are NOT
+// tree-shaken by webpack, so they never match here and the target keeps all exports.
+
+export interface ShakeableDynamicImport {
+  /** Absolute index (inclusive) of the specifier string literal, quote included. */
+  literalStart: number;
+  /** Absolute index (exclusive) just past the closing quote. */
+  literalEnd: number;
+  /** The import specifier (without quotes). */
+  specifier: string;
+  /**
+   * Export names the destructuring keeps. An empty array means the module is
+   * imported purely for side effects (`const {} = ...`): drop every export.
+   */
+  usedExports: string[];
+}
+
+const declStart = /\b(?:const|let|var)\s+\{/g;
+
+export function findShakeableDynamicImports(source: string): ShakeableDynamicImport[] {
+  const results: ShakeableDynamicImport[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = declStart.exec(source))) {
+    const braceOpen = match.index + match[0].length - 1;
+    const braceClose = matchDelimiter(source, braceOpen, '{', '}');
+    if (braceClose < 0) continue;
+
+    let index = skipTrivia(source, braceClose + 1);
+    if (source[index] !== '=') continue;
+    index = skipTrivia(source, index + 1);
+    if (!matchesWord(source, index, 'await')) continue;
+    index = skipTrivia(source, index + 'await'.length);
+    if (!matchesWord(source, index, 'import')) continue;
+    index = skipTrivia(source, index + 'import'.length);
+    if (source[index] !== '(') continue;
+
+    const parenClose = matchDelimiter(source, index, '(', ')');
+    if (parenClose < 0) continue;
+    const argStart = index + 1;
+    const argText = source.slice(argStart, parenClose);
+
+    const literal = firstStringLiteral(argText);
+    if (!literal || hasTrailingArgument(argText, literal.end)) continue;
+
+    const patternExports = usedExportsFromPattern(source.slice(braceOpen, braceClose + 1));
+    if (patternExports === null) continue; // rest element — not shakeable
+
+    const webpackExports = webpackExportsFromArg(argText);
+    results.push({
+      literalStart: argStart + literal.start,
+      literalEnd: argStart + literal.end,
+      specifier: literal.value,
+      usedExports: webpackExports ?? patternExports,
+    });
+    declStart.lastIndex = parenClose + 1;
+  }
+
+  return results;
+}
+
+// Parse an object destructuring pattern (braces included) into the top-level
+// export names it binds. Returns null when a rest element is present (webpack
+// gives up on tree-shaking then).
+function usedExportsFromPattern(pattern: string): string[] | null {
+  const inner = pattern.slice(1, -1);
+  const names: string[] = [];
+
+  for (const rawPart of splitTopLevel(inner)) {
+    const part = rawPart.trim();
+    if (!part) continue;
+    if (part.startsWith('...')) return null;
+
+    const colon = topLevelColonIndex(part);
+    const keyRegion = colon >= 0 ? part.slice(0, colon) : part;
+    // `{ a = fallback }` shorthand with a default — the key is before `=`.
+    const eq = colon >= 0 ? -1 : keyRegion.indexOf('=');
+    const name = (eq >= 0 ? keyRegion.slice(0, eq) : keyRegion).trim();
+    if (!/^[A-Za-z_$][\w$]*$/.test(name)) return null; // computed/string key — bail
+    names.push(name);
+  }
+
+  return names;
+}
+
+function webpackExportsFromArg(argText: string): string[] | undefined {
+  const match = /webpackExports\s*:\s*\[([^\]]*)\]/.exec(argText);
+  if (!match) return undefined;
+  const names: string[] = [];
+  const namePattern = /['"]([^'"]+)['"]/g;
+  let entry: RegExpExecArray | null;
+  while ((entry = namePattern.exec(match[1] ?? ''))) {
+    if (entry[1]) names.push(entry[1]);
+  }
+  return names;
+}
+
+// Split a comma-separated list at top level, ignoring commas nested in braces,
+// brackets, parens, strings, or comments.
+function splitTopLevel(source: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let start = 0;
+  let index = 0;
+
+  while (index < source.length) {
+    const skipped = skipStringOrComment(source, index);
+    if (skipped > index) {
+      index = skipped;
+      continue;
+    }
+    const char = source[index];
+    if (char === '{' || char === '[' || char === '(') depth += 1;
+    else if (char === '}' || char === ']' || char === ')') depth -= 1;
+    else if (char === ',' && depth === 0) {
+      parts.push(source.slice(start, index));
+      start = index + 1;
+    }
+    index += 1;
+  }
+  parts.push(source.slice(start));
+  return parts;
+}
+
+function topLevelColonIndex(source: string): number {
+  let depth = 0;
+  let index = 0;
+  while (index < source.length) {
+    const skipped = skipStringOrComment(source, index);
+    if (skipped > index) {
+      index = skipped;
+      continue;
+    }
+    const char = source[index];
+    if (char === '{' || char === '[' || char === '(') depth += 1;
+    else if (char === '}' || char === ']' || char === ')') depth -= 1;
+    else if (char === ':' && depth === 0) return index;
+    index += 1;
+  }
+  return -1;
+}
+
+// Index of the matching close delimiter for the open delimiter at `open`,
+// respecting nested delimiters, strings, and comments. Returns -1 if unbalanced.
+function matchDelimiter(source: string, open: number, openChar: string, closeChar: string): number {
+  let depth = 0;
+  let index = open;
+  while (index < source.length) {
+    const skipped = skipStringOrComment(source, index);
+    if (skipped > index) {
+      index = skipped;
+      continue;
+    }
+    const char = source[index];
+    if (char === openChar) depth += 1;
+    else if (char === closeChar) {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+    index += 1;
+  }
+  return -1;
+}
+
+// Locate the first string literal in `text`, skipping leading whitespace and
+// comments. Returns its bounds (quotes included, `end` exclusive) and value.
+function firstStringLiteral(text: string): { start: number; end: number; value: string } | undefined {
+  let index = skipTrivia(text, 0);
+  const quote = text[index];
+  if (quote !== '"' && quote !== "'" && quote !== '`') return undefined;
+  const start = index;
+  index += 1;
+  let value = '';
+  while (index < text.length) {
+    const char = text[index];
+    if (char === '\\') {
+      value += text[index + 1] ?? '';
+      index += 2;
+      continue;
+    }
+    if (char === quote) return { start, end: index + 1, value };
+    value += char;
+    index += 1;
+  }
+  return undefined;
+}
+
+// True when a second top-level argument follows the specifier — `import('x', y)`
+// is not a bare specifier import and is left untouched.
+function hasTrailingArgument(argText: string, afterLiteral: number): boolean {
+  const index = skipTrivia(argText, afterLiteral);
+  return index < argText.length && argText[index] === ',' && Boolean(argText.slice(index + 1).trim());
+}
+
+function matchesWord(source: string, index: number, word: string): boolean {
+  if (!source.startsWith(word, index)) return false;
+  const after = source[index + word.length];
+  return after === undefined || !/[\w$]/.test(after);
+}
+
+// Skip whitespace and `//`/`/* */` comments starting at `index`.
+function skipTrivia(source: string, index: number): number {
+  let current = index;
+  for (;;) {
+    while (current < source.length && /\s/.test(source[current] ?? '')) current += 1;
+    const skipped = skipComment(source, current);
+    if (skipped === current) return current;
+    current = skipped;
+  }
+}
+
+// If `index` starts a string or comment, return the index just past it;
+// otherwise return `index` unchanged.
+function skipStringOrComment(source: string, index: number): number {
+  const comment = skipComment(source, index);
+  if (comment > index) return comment;
+  const char = source[index];
+  if (char === '"' || char === "'" || char === '`') {
+    let current = index + 1;
+    while (current < source.length) {
+      if (source[current] === '\\') {
+        current += 2;
+        continue;
+      }
+      if (source[current] === char) return current + 1;
+      current += 1;
+    }
+    return source.length;
+  }
+  return index;
+}
+
+function skipComment(source: string, index: number): number {
+  if (source[index] === '/' && source[index + 1] === '/') {
+    let current = index + 2;
+    while (current < source.length && source[current] !== '\n') current += 1;
+    return current;
+  }
+  if (source[index] === '/' && source[index + 1] === '*') {
+    let current = index + 2;
+    while (current < source.length && !(source[current] === '*' && source[current + 1] === '/')) {
+      current += 1;
+    }
+    return Math.min(source.length, current + 2);
+  }
+  return index;
+}

package/src/env.ts

@@ -0,0 +1,92 @@
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { parse } from 'dotenv';
+
+type EnvMap = Record<string, string>;
+
+export interface LoadedEnvFile {
+  env: EnvMap;
+  path: string;
+}
+
+export interface LoadEnvResult {
+  loadedEnvFiles: LoadedEnvFile[];
+  mode: string;
+}
+
+export async function loadEnv(root: string, options: { dev?: boolean } = {}): Promise<LoadEnvResult> {
+  const nodeEnvKey = 'NODE_ENV';
+  const env = process.env as Record<string, string | undefined>;
+  if (!env[nodeEnvKey]) env[nodeEnvKey] = options.dev ? 'development' : 'production';
+
+  const mode = process.env[nodeEnvKey] ?? 'production';
+  const loadedEnvFiles: LoadedEnvFile[] = [];
+  for (const file of envFilesForMode(mode)) {
+    const filePath = path.join(root, file);
+    if (!(await isEnvFile(filePath))) continue;
+
+    const parsed = parse(await readFile(filePath, 'utf8'));
+    const env = expandEnv(parsed);
+    for (const [key, value] of Object.entries(env)) {
+      if (process.env[key] === undefined) process.env[key] = value;
+    }
+    loadedEnvFiles.push({ path: file, env });
+  }
+
+  return { mode, loadedEnvFiles };
+}
+
+function envFilesForMode(mode: string) {
+  return [
+    `.env.${mode}.local`,
+    mode === 'test' ? undefined : '.env.local',
+    `.env.${mode}`,
+    '.env',
+  ].filter((file): file is string => Boolean(file));
+}
+
+async function isEnvFile(file: string) {
+  try {
+    const info = await stat(file);
+    return info.isFile();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+function expandEnv(parsed: EnvMap) {
+  const env: EnvMap = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    env[key] = expandValue(value, { ...parsed, ...env });
+  }
+  return env;
+}
+
+function expandValue(value: string, parsed: EnvMap): string {
+  let result = value;
+  for (
+    let index = searchLastEnvReference(result), attempts = 0;
+    index !== -1 && attempts < 100;
+    index = searchLastEnvReference(result), attempts += 1
+  ) {
+    const match = result.slice(index).match(/^\$({?)([\w]+)(?::-([^}]*))?}?/);
+    if (!match) break;
+
+    const token = match[0] ?? '';
+    const braced = match[1] ?? '';
+    const key = match[2] ?? '';
+    const fallback = match[3] ?? '';
+    const hasClosingBrace = braced ? token.endsWith('}') : true;
+    if (!hasClosingBrace) break;
+
+    const replacement = process.env[key] || fallback || parsed[key] || '';
+    result = `${result.slice(0, index)}${replacement}${result.slice(index + token.length)}`;
+  }
+  return result.replace(/\\\$/g, '$');
+}
+
+function searchLastEnvReference(value: string) {
+  const matches = [...value.matchAll(/(?<!\\)\$/g)];
+  return matches.length > 0 ? (matches.at(-1)?.index ?? -1) : -1;
+}