veryfront 0.1.367 → 0.1.369

package/src/src/extensions/bundler.ts

@@ -0,0 +1,85 @@
+/**
+ * Bundler contract resolution helper.
+ *
+ * Core code uses this thin wrapper instead of importing `esbuild` directly,
+ * so the bundler implementation lives in `@veryfront/ext-esbuild` (or any
+ * other extension that satisfies the contract).
+ *
+ * @module extensions/bundler
+ */
+
+import { resolve as resolveContract } from "./contracts.js";
+import type {
+  BuildContext,
+  BundleOptions,
+  Bundler,
+  BundleResult,
+  TransformOptions,
+  TransformResult,
+} from "./interfaces/bundler.js";
+
+/** Resolve the registered `Bundler` contract. Throws if no extension provides it. */
+export function getBundler(): Bundler {
+  return resolveContract<Bundler>("Bundler");
+}
+
+/** Convenience wrapper: `bundler.bundle(opts)`. */
+export function build(options: BundleOptions): Promise<BundleResult> {
+  return getBundler().bundle(options);
+}
+
+/**
+ * Convenience wrapper that mirrors esbuild's `transform(code, options)`
+ * positional signature so call-sites migrating off esbuild keep their shape.
+ */
+export function transform(
+  code: string,
+  options: Omit<TransformOptions, "code"> = {},
+): Promise<TransformResult> {
+  return getBundler().transform({ code, ...options });
+}
+
+/**
+ * Stop the bundler. Optional — extension teardown will also call this. Provided
+ * so tests that previously called `esbuild.stop()` keep working.
+ */
+export async function stop(): Promise<void> {
+  const b = getBundler();
+  if (b.stop) await b.stop();
+}
+
+/** Create an incremental build context (watch/rebuild mode). */
+export function context(options: BundleOptions): Promise<BuildContext> {
+  const b = getBundler();
+  if (!b.context) {
+    throw new Error("Registered Bundler extension does not support context() (incremental builds)");
+  }
+  return b.context(options);
+}
+
+export type {
+  BuildContext,
+  BuildFailure,
+  BundleOptions,
+  BundleOptions as BuildOptions,
+  BundleOutput,
+  Bundler,
+  BundleResult,
+  BundleResult as BuildResult,
+  BundlerMessage,
+  BundlerMessage as Message,
+  BundlerPlugin,
+  BundlerPlugin as Plugin,
+  BundlerPluginBuild,
+  BundlerPluginBuild as PluginBuild,
+  Loader,
+  Metafile,
+  OnLoadArgs,
+  OnLoadResult,
+  OnResolveArgs,
+  OnResolveResult,
+  OnResolveResult as ResolveResult,
+  StdinOptions,
+  TransformOptions,
+  TransformResult,
+} from "./interfaces/bundler.js";

package/src/src/extensions/interfaces/bundler.ts

@@ -6,12 +6,61 @@
  * @module extensions/interfaces/bundler
  */
 
+/** Location of an error or warning in source. */
+export interface BundlerMessageLocation {
+  file: string;
+  line: number;
+  column: number;
+  length?: number;
+  lineText?: string;
+}
+
+/** A diagnostic message (error or warning) from a bundler. */
+export interface BundlerMessage {
+  text: string;
+  location?: BundlerMessageLocation | null;
+  notes?: { text: string; location?: BundlerMessageLocation | null }[];
+  pluginName?: string;
+  detail?: unknown;
+}
+
+/** Input file entry in a {@link Metafile}. */
+export interface MetafileInput {
+  bytes: number;
+  imports: { path: string; kind?: string; external?: boolean; original?: string }[];
+  format?: "cjs" | "esm";
+}
+
+/** Output file entry in a {@link Metafile}. */
+export interface MetafileOutput {
+  bytes: number;
+  inputs: Record<string, { bytesInOutput: number }>;
+  imports: { path: string; kind?: string; external?: boolean }[];
+  exports: string[];
+  entryPoint?: string;
+  cssBundle?: string;
+}
+
+/** Dependency-graph metadata produced by a bundler when `metafile: true`. */
+export interface Metafile {
+  inputs: Record<string, MetafileInput>;
+  outputs: Record<string, MetafileOutput>;
+}
+
+/** In-memory source input for {@link BundleOptions.stdin}. */
+export interface StdinOptions {
+  contents: string;
+  resolveDir?: string;
+  sourcefile?: string;
+  loader?: Loader | string;
+}
+
 /** Options passed to {@link Bundler.bundle}. */
 export interface BundleOptions {
-  /** Entry point file paths. */
-  entryPoints: string[];
+  /** Entry point file paths, or a `{ outputName: inputPath }` map. */
+  entryPoints?: string[] | Record<string, string>;
   /** Output directory. */
-  outdir: string;
+  outdir?: string;
   /** Bundle format (`esm`, `cjs`, `iife`). */
   format?: "esm" | "cjs" | "iife";
   /** Target environment(s). */
@@ -19,11 +68,37 @@ export interface BundleOptions {
   /** Enable minification. */
   minify?: boolean;
   /** Enable source maps. */
-  sourcemap?: boolean | "inline" | "external";
+  sourcemap?: boolean | "inline" | "external" | "linked" | "both";
   /** Enable code splitting. */
   splitting?: boolean;
   /** Additional plugins. */
   plugins?: BundlerPlugin[];
+
+  /** Whether to bundle dependencies into the output (vs. leaving imports as-is). */
+  bundle?: boolean;
+  /** Write output to disk; when false, returns bytes in-memory only. */
+  write?: boolean;
+  /** Target platform influencing default externals and resolution. */
+  platform?: "browser" | "node" | "neutral";
+  /** Packages/paths to exclude from the bundle. */
+  external?: string[];
+  /** Bundle an in-memory source string instead of reading from disk. */
+  stdin?: StdinOptions;
+  /** Compile-time constant replacements, e.g. `{ "process.env.NODE_ENV": '"production"' }`. */
+  define?: Record<string, string>;
+  /** JSX transform mode. */
+  jsx?: "transform" | "preserve" | "automatic";
+  /** Module specifier used for the automatic JSX runtime import. */
+  jsxImportSource?: string;
+  /** File extensions to try during import resolution. */
+  resolveExtensions?: string[];
+  /** Drop unused exports and dead code. */
+  treeShaking?: boolean;
+  /** Verbosity of diagnostic output. */
+  logLevel?: "silent" | "error" | "warning" | "info" | "debug" | "verbose";
+  /** Emit a dependency-graph {@link Metafile} in the result. */
+  metafile?: boolean;
+
   /** Extra implementation-specific options. */
   [key: string]: unknown;
 }
@@ -34,24 +109,47 @@ export interface BundleOutput {
   path: string;
   /** Raw byte content. */
   contents: Uint8Array;
+  /** Lazy-decoded UTF-8 string view of `contents`. */
+  text: string;
+  /** Optional content hash. */
+  hash?: string;
 }
 
 /** Result returned from {@link Bundler.bundle}. */
 export interface BundleResult {
   /** Output files produced by the bundle. */
-  outputs: BundleOutput[];
+  outputFiles: BundleOutput[];
   /** Warnings emitted during bundling. */
-  warnings: string[];
+  warnings: BundlerMessage[];
   /** Errors encountered during bundling. */
-  errors: string[];
+  errors: BundlerMessage[];
+  /** Dependency-graph metadata, populated when `metafile: true`. */
+  metafile?: Metafile;
 }
 
+/** Loader hint for source files. Mirrors esbuild's `Loader` type. */
+export type Loader =
+  | "js"
+  | "jsx"
+  | "ts"
+  | "tsx"
+  | "css"
+  | "json"
+  | "text"
+  | "base64"
+  | "file"
+  | "dataurl"
+  | "binary"
+  | "default"
+  | "empty"
+  | "copy";
+
 /** Options passed to {@link Bundler.transform}. */
 export interface TransformOptions {
   /** Source code to transform. */
   code: string;
   /** Loader hint (`ts`, `tsx`, `jsx`, `css`, etc.). */
-  loader?: string;
+  loader?: Loader;
   /** Output format. */
   format?: "esm" | "cjs" | "iife";
   /** Target environment(s). */
@@ -60,6 +158,14 @@ export interface TransformOptions {
   minify?: boolean;
   /** Enable source maps. */
   sourcemap?: boolean | "inline" | "external";
+  /** JSX transform mode. */
+  jsx?: "transform" | "preserve" | "automatic";
+  /** Module specifier used for the automatic JSX runtime import. */
+  jsxImportSource?: string;
+  /** Drop unused exports and dead code. */
+  treeShaking?: boolean;
+  /** Preserve original identifier names through minification. */
+  keepNames?: boolean;
   /** Extra implementation-specific options. */
   [key: string]: unknown;
 }
@@ -74,30 +180,95 @@ export interface TransformResult {
   warnings: string[];
 }
 
+/** Arguments passed to an `onResolve` callback. */
+export interface OnResolveArgs {
+  path: string;
+  importer: string;
+  namespace: string;
+  resolveDir: string;
+  /** e.g. "import-statement", "dynamic-import", "require-call", "entry-point". */
+  kind: string;
+  pluginData?: unknown;
+}
+
+/** Result returned from an `onResolve` callback. */
+export interface OnResolveResult {
+  path?: string;
+  namespace?: string;
+  external?: boolean;
+  errors?: BundlerMessage[];
+  warnings?: BundlerMessage[];
+  pluginData?: unknown;
+  sideEffects?: boolean;
+  watchFiles?: string[];
+}
+
+/** Arguments passed to an `onLoad` callback. */
+export interface OnLoadArgs {
+  path: string;
+  namespace: string;
+  suffix?: string;
+  pluginData?: unknown;
+}
+
+/** Result returned from an `onLoad` callback. */
+export interface OnLoadResult {
+  contents?: string | Uint8Array;
+  loader?: string;
+  resolveDir?: string;
+  errors?: BundlerMessage[];
+  warnings?: BundlerMessage[];
+  pluginData?: unknown;
+  watchFiles?: string[];
+}
+
 /** Build context exposed to bundler plugins. */
 export interface BundlerPluginBuild {
-  /** Register a resolver callback for the given filter. */
   onResolve(
     options: { filter: RegExp; namespace?: string },
     callback: (
-      args: { path: string; namespace: string },
-    ) => { path?: string; namespace?: string; external?: boolean } | undefined,
+      args: OnResolveArgs,
+    ) =>
+      | OnResolveResult
+      | null
+      | undefined
+      | void
+      | Promise<OnResolveResult | null | undefined | void>,
   ): void;
-  /** Register a loader callback for the given filter. */
   onLoad(
     options: { filter: RegExp; namespace?: string },
     callback: (
-      args: { path: string; namespace: string },
-    ) => { contents?: string; loader?: string } | undefined,
+      args: OnLoadArgs,
+    ) =>
+      | OnLoadResult
+      | null
+      | undefined
+      | void
+      | Promise<OnLoadResult | null | undefined | void>,
   ): void;
+  onDispose(callback: () => void): void;
 }
 
 /** A bundler plugin that hooks into the build pipeline. */
 export interface BundlerPlugin {
   /** Unique plugin name. */
   name: string;
-  /** Called once when the plugin is registered. */
-  setup(build: BundlerPluginBuild): void;
+  /** Called once when the plugin is registered. May be async. */
+  setup(build: BundlerPluginBuild): void | Promise<void>;
+}
+
+/** Incremental/rebuild context produced by {@link Bundler.context}. */
+export interface BuildContext {
+  /** Re-run the build with cached state. */
+  rebuild(): Promise<BundleResult>;
+  /** Release context resources. */
+  dispose(): Promise<void>;
+}
+
+/** Failure thrown by {@link Bundler.bundle} or {@link Bundler.transform}. */
+export interface BuildFailure extends Error {
+  errors: BundlerMessage[];
+  warnings: BundlerMessage[];
 }
 
 /**
@@ -111,6 +282,8 @@ export interface Bundler {
   bundle(options: BundleOptions): Promise<BundleResult>;
   /** Transform a single source string without writing to disk. */
   transform(options: TransformOptions): Promise<TransformResult>;
+  /** Create an incremental build context (watch/rebuild mode). */
+  context?(options: BundleOptions): Promise<BuildContext>;
   /** Release bundler resources (child processes, watchers, etc.). */
   stop?(): Promise<void>;
 }

package/src/src/extensions/interfaces/index.ts

@@ -10,16 +10,32 @@
 import "../../../_dnt.polyfills.js";
 
 export type {
+  BuildContext,
+  BuildFailure,
   BundleOptions,
   BundleOutput,
   Bundler,
   BundleResult,
+  BundlerMessage,
+  BundlerMessageLocation,
   BundlerPlugin,
   BundlerPluginBuild,
+  Loader,
+  Metafile,
+  MetafileInput,
+  MetafileOutput,
+  OnLoadArgs,
+  OnLoadResult,
+  OnResolveArgs,
+  OnResolveResult,
+  StdinOptions,
   TransformOptions,
   TransformResult,
 } from "./bundler.js";
 
+// Module lexer
+export type { ImportSpecifier, ModuleLexer } from "./module-lexer.js";
+
 // Cache store
 export type { CacheStore } from "./cache-store.js";
 

package/src/src/extensions/interfaces/module-lexer.ts

@@ -0,0 +1,46 @@
+/**
+ * Contract interface for ES module lexers.
+ *
+ * Parses ES module import/export specifiers from source code.
+ * Kept separate from {@link Bundler} because the surfaces are orthogonal:
+ * a lexer only inspects specifier positions, while a bundler compiles and
+ * emits output.
+ *
+ * Default implementation: `@veryfront/ext-esbuild` (backed by `es-module-lexer`).
+ *
+ * @module extensions/interfaces/module-lexer
+ */
+
+/**
+ * A single import specifier position record, matching the shape produced by
+ * `es-module-lexer`.
+ */
+export interface ImportSpecifier {
+  /** Module specifier (e.g. "react"). Undefined when the specifier cannot be statically resolved (dynamic import with non-literal expression, or import.meta). */
+  n: string | undefined;
+  /** Start of module specifier. */
+  s: number;
+  /** End of module specifier. */
+  e: number;
+  /** Start of import statement. */
+  ss: number;
+  /** End of import statement. */
+  se: number;
+  /** Index of the dynamic import token in the source; -1 for static imports, -2 for import.meta. */
+  d: number;
+  /** Start position of the import attributes (with/assert) block in the source; -1 if none. */
+  a: number;
+}
+
+/**
+ * Module lexer contract interface.
+ *
+ * Implementations parse ES module import specifiers from source code and
+ * return positional records suitable for further rewriting.
+ */
+export interface ModuleLexer {
+  /** Optional async initialization (e.g., loading WASM). Called lazily by the default impl before first parse. */
+  init?(): Promise<void>;
+  /** Parse ES module import/export specifiers from source code. */
+  parse(code: string): readonly ImportSpecifier[];
+}

package/src/src/extensions/loader.ts

@@ -253,7 +253,12 @@ export class ExtensionLoader {
         }
       }
     }
+    const hadSetupExtensions = this.setupOrder.length > 0;
     this.setupOrder = [];
-    reset();
+    // Only clear the contract registry when this loader actually registered
+    // contracts via setupAll(). Otherwise an idempotent teardown on an empty
+    // loader would wipe contracts registered out-of-band (e.g. by the test
+    // harness in `tests/_helpers/contract-init.ts`).
+    if (hadSetupExtensions) reset();
   }
 }

package/src/src/extensions/recommendations.ts

@@ -6,6 +6,9 @@
 
 const recommendations = new Map<string, string>([
   ["Bundler", "@veryfront/ext-esbuild"],
+  // ModuleLexer ships in the same package as Bundler (es-module-lexer +
+  // esbuild are co-bundled into ext-esbuild).
+  ["ModuleLexer", "@veryfront/ext-esbuild"],
   ["CacheStore", "@veryfront/ext-redis"],
   ["TokenCacheStore", "@veryfront/ext-redis"],
   ["CSSProcessor", "@veryfront/ext-tailwind"],

package/src/src/platform/compat/esbuild.ts

@@ -1,165 +1,53 @@
 /**
- * esbuild compatibility layer with deno compile support.
- * Extracts esbuild binary from VFS to temp dir on first use in compiled binaries.
- * Sets ESBUILD_BINARY_PATH in both Deno.env and process.env (esbuild reads process.env).
+ * Compatibility shim for code that previously imported esbuild via this path.
+ *
+ * The actual esbuild runtime now lives in the `@veryfront/ext-esbuild`
+ * extension; this module forwards to the registered `Bundler` contract so
+ * legacy callers keep working without importing `esbuild` directly.
  */
-import * as dntShim from "../../../_dnt.shims.js";
 
-
-export type { BuildOptions, BuildResult, TransformOptions, TransformResult } from "esbuild";
-
-import nodeProcess from "node:process";
-import { serverLogger } from "../../utils/logger/logger.js";
-import { getEnv, setEnv } from "./process.js";
-import { isDenoCompiled } from "./runtime.js";
-import { ESBUILD_VERSION, getEsbuildBinaryName, getVFSBasePath } from "./esbuild-shared.js";
-import { FILE_NOT_FOUND } from "../../errors/index.js";
-
-function getTempDir(): string {
-  return getEnv("TMPDIR") ?? getEnv("TEMP") ?? getEnv("TMP") ?? "/tmp";
-}
-
-function getEsbuildCacheDir(): string {
-  return `${getTempDir()}/veryfront-esbuild`;
-}
-
-let esbuildModule: typeof import("esbuild") | null = null;
-let setupComplete = false;
-let setupPromise: Promise<void> | null = null;
-
-async function isFile(path: string): Promise<boolean> {
-  try {
-    const stat = await dntShim.Deno.stat(path);
-    return stat.isFile;
-  } catch (_) {
-    /* expected: file may not exist */
-    return false;
-  }
-}
-
-async function findEsbuildInVFS(): Promise<string | null> {
-  const binaryName = getEsbuildBinaryName();
-  const vfsBase = getVFSBasePath(new URL(import.meta.url).pathname, getTempDir());
-
-  const possiblePaths = [
-    `${vfsBase}/node_modules/${binaryName}/bin/esbuild`,
-    `${vfsBase}/node_modules/.deno/${binaryName}@${ESBUILD_VERSION}/node_modules/${binaryName}/bin/esbuild`,
-    `${vfsBase}/node_modules/.deno/esbuild@${ESBUILD_VERSION}/node_modules/${binaryName}/bin/esbuild`,
-    `${vfsBase}/node_modules/esbuild/bin/esbuild`,
-    `${vfsBase}/node_modules/.package/esbuild@${ESBUILD_VERSION}/bin/esbuild`,
-    `${vfsBase}/node_modules/.package/${binaryName}@${ESBUILD_VERSION}/bin/esbuild`,
-  ];
-
-  for (const vfsPath of possiblePaths) {
-    if (await isFile(vfsPath)) return vfsPath;
-  }
-
-  try {
-    const nodeModulesPath = `${vfsBase}/node_modules`;
-    for await (const entry of dntShim.Deno.readDir(nodeModulesPath)) {
-      if (entry.name !== binaryName && !entry.name.startsWith("@esbuild")) continue;
-
-      const binPath = `${nodeModulesPath}/${entry.name}/bin/esbuild`;
-      if (await isFile(binPath)) return binPath;
-    }
-  } catch (_) {
-    /* expected: node_modules directory may not be readable in VFS */
-  }
-
-  return null;
-}
-
-async function extractEsbuildBinary(): Promise<string> {
-  const cacheDir = getEsbuildCacheDir();
-  const targetPath = `${cacheDir}/esbuild-${ESBUILD_VERSION}`;
-
-  try {
-    const stat = await dntShim.Deno.stat(targetPath);
-    if (stat.isFile && stat.mode && (stat.mode & 0o111)) return targetPath;
-  } catch (_) {
-    /* expected: cached binary does not exist yet, need to extract */
-  }
-
-  const vfsPath = await findEsbuildInVFS();
-  if (!vfsPath) {
-    const vfsBase = getVFSBasePath(new URL(import.meta.url).pathname, getTempDir());
-    throw FILE_NOT_FOUND.create({
-      detail: `Could not find esbuild binary in deno compile VFS.\n` +
-        `  Platform: ${getEsbuildBinaryName()}\n` +
-        `  VFS base: ${vfsBase}\n` +
-        `  Tip: Ensure esbuild is in dependencies and deno compile includes node_modules.`,
-    });
-  }
-
-  await dntShim.Deno.mkdir(cacheDir, { recursive: true });
-
-  const binary = await dntShim.Deno.readFile(vfsPath);
-  await dntShim.Deno.writeFile(targetPath, binary, { mode: 0o755 });
-
-  return targetPath;
-}
-
-async function ensureEsbuildBinary(): Promise<void> {
-  if (setupComplete) return;
-
-  if (setupPromise) {
-    await setupPromise;
-    return;
-  }
-
-  setupPromise = (async () => {
-    if (getEnv("ESBUILD_BINARY_PATH") || !isDenoCompiled) {
-      setupComplete = true;
-      return;
-    }
-
-    try {
-      const binaryPath = await extractEsbuildBinary();
-      setEnv("ESBUILD_BINARY_PATH", binaryPath);
-      nodeProcess.env.ESBUILD_BINARY_PATH = binaryPath;
-    } catch (error) {
-      serverLogger.error("[esbuild] Binary extraction failed", error);
-    } finally {
-      setupComplete = true;
-    }
-  })();
-
-  try {
-    await setupPromise;
-  } finally {
-    setupPromise = null;
-  }
-}
-
-export async function getEsbuild(): Promise<typeof import("esbuild")> {
-  await ensureEsbuildBinary();
-  if (esbuildModule) return esbuildModule;
-
-  esbuildModule = await import("esbuild");
-  return esbuildModule;
-}
-
-export async function transform(
-  code: string,
-  options?: import("esbuild").TransformOptions,
-): Promise<import("esbuild").TransformResult> {
-  const esbuild = await getEsbuild();
-  return esbuild.transform(code, options);
-}
-
-export async function build(
-  options: import("esbuild").BuildOptions,
-): Promise<import("esbuild").BuildResult> {
-  const esbuild = await getEsbuild();
-  return esbuild.build(options);
-}
-
-export async function stop(): Promise<void> {
-  const esbuild = await getEsbuild();
-  esbuild.stop();
-}
-
-/** Eager initialization for server startup. */
+import {
+  build as bundlerBuild,
+  getBundler,
+  stop as bundlerStop,
+  transform as bundlerTransform,
+} from "../../extensions/bundler.js";
+import type {
+  BundleOptions,
+  BundleResult,
+  TransformOptions,
+  TransformResult,
+} from "../../extensions/bundler.js";
+
+export type {
+  BundleOptions as BuildOptions,
+  BundleResult as BuildResult,
+  TransformOptions,
+  TransformResult,
+} from "../../extensions/bundler.js";
+
+/** esbuild-shaped facade backed by the registered `Bundler` contract. */
+export function getEsbuild(): {
+  build: (opts: BundleOptions) => Promise<BundleResult>;
+  transform: (
+    code: string,
+    opts?: Omit<TransformOptions, "code">,
+  ) => Promise<TransformResult>;
+  stop: () => Promise<void>;
+} {
+  getBundler();
+  return {
+    build: bundlerBuild,
+    transform: bundlerTransform,
+    stop: bundlerStop,
+  };
+}
+
+export const transform = bundlerTransform;
+export const build = bundlerBuild;
+export const stop = bundlerStop;
+
+/** No-op kept for backwards compatibility with legacy bootstrap callers. */
 export async function initializeEsbuild(): Promise<void> {
-  await ensureEsbuildBinary();
+  getBundler();
 }