refactor(modules): classify-and-dispatch serveModule and one shared module transform

src/modules/server/classify.test.ts

@@ -0,0 +1,158 @@
+import "#veryfront/schemas/_test-setup.ts";
+/**
+ * classify.ts unit tests
+ *
+ * Table-driven tests over every URL pattern that classifyModuleRequest
+ * recognises, plus rejection of non-module URLs.
+ *
+ * @module modules/server/classify.test
+ */
+
+import { assertEquals } from "#veryfront/testing/assert.ts";
+import { describe, it } from "#veryfront/testing/bdd.ts";
+import { classifyModuleRequest } from "./classify.ts";
+
+function url(pathname: string, host = "localhost:3000"): URL {
+  return new URL(`http://${host}${pathname}`);
+}
+
+describe("classifyModuleRequest", () => {
+  describe("not-module", () => {
+    for (
+      const pathname of [
+        "/",
+        "/api/data",
+        "/pages/index",
+        "/_vf_mod",
+        "/_veryfront/mod",
+        "/vf_modules/page.js",
+      ]
+    ) {
+      it(`returns not-module for ${pathname}`, () => {
+        const result = classifyModuleRequest(url(pathname));
+        assertEquals(result.kind, "not-module");
+      });
+    }
+  });
+
+  describe("snippet", () => {
+    it("classifies /_vf_modules/_snippets/<hash>.js as snippet", () => {
+      const result = classifyModuleRequest(
+        url("/_vf_modules/_snippets/abc123def456.js"),
+      );
+      assertEquals(result.kind, "snippet");
+      if (result.kind === "snippet") {
+        assertEquals(result.hash, "abc123def456");
+      }
+    });
+
+    it("classifies full hex hash in snippet URL", () => {
+      const hash = "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4";
+      const result = classifyModuleRequest(url(`/_vf_modules/_snippets/${hash}.js`));
+      assertEquals(result.kind, "snippet");
+      if (result.kind === "snippet") {
+        assertEquals(result.hash, hash);
+      }
+    });
+
+    it("does NOT classify _snippets path without .js extension as snippet", () => {
+      // Falls through to dev-module since DEV_MODULE_PREFIX matches
+      const result = classifyModuleRequest(url("/_vf_modules/_snippets/abc123.ts"));
+      assertEquals(result.kind, "dev-module");
+    });
+  });
+
+  describe("cross-project-versioned", () => {
+    it("classifies /_vf_modules/_cross/<slug>@<version>/@/<path>", () => {
+      const result = classifyModuleRequest(
+        url("/_vf_modules/_cross/my-project@1.2.3/@/components/Button.js"),
+      );
+      assertEquals(result.kind, "cross-project-versioned");
+      if (result.kind === "cross-project-versioned") {
+        assertEquals(result.slug, "my-project");
+        assertEquals(result.version, "1.2.3");
+        assertEquals(result.path, "components/Button.js");
+      }
+    });
+
+    it("handles semver range version like ^1.0.0", () => {
+      const result = classifyModuleRequest(
+        url("/_vf_modules/_cross/demo@^1.0.0/@/lib/utils.js"),
+      );
+      assertEquals(result.kind, "cross-project-versioned");
+      if (result.kind === "cross-project-versioned") {
+        assertEquals(result.version, "^1.0.0");
+      }
+    });
+
+    it("handles x-range version like 1.x", () => {
+      const result = classifyModuleRequest(
+        url("/_vf_modules/_cross/demo@1.x/@/lib/utils.js"),
+      );
+      assertEquals(result.kind, "cross-project-versioned");
+      if (result.kind === "cross-project-versioned") {
+        assertEquals(result.version, "1.x");
+      }
+    });
+  });
+
+  describe("cross-project-latest", () => {
+    it("classifies /_vf_modules/_cross/<slug>/@/<path>", () => {
+      const result = classifyModuleRequest(
+        url("/_vf_modules/_cross/my-project/@/components/Button.js"),
+      );
+      assertEquals(result.kind, "cross-project-latest");
+      if (result.kind === "cross-project-latest") {
+        assertEquals(result.slug, "my-project");
+        assertEquals(result.path, "components/Button.js");
+      }
+    });
+
+    it("preserves nested path", () => {
+      const result = classifyModuleRequest(
+        url("/_vf_modules/_cross/acme-corp/@/a/b/c/deep.js"),
+      );
+      assertEquals(result.kind, "cross-project-latest");
+      if (result.kind === "cross-project-latest") {
+        assertEquals(result.path, "a/b/c/deep.js");
+      }
+    });
+  });
+
+  describe("dev-module", () => {
+    for (
+      const pathname of [
+        "/_vf_modules/components/Button.js",
+        "/_vf_modules/_veryfront/utils/index.js",
+        "/_veryfront/modules/lib/utils.ts",
+        "/_vf_modules/_dnt.shims.js",
+        "/_vf_modules/page.tsx",
+      ]
+    ) {
+      it(`classifies ${pathname} as dev-module`, () => {
+        const result = classifyModuleRequest(url(pathname));
+        assertEquals(result.kind, "dev-module");
+      });
+    }
+
+    it("classifies /_vf_modules/ with query params as dev-module", () => {
+      const result = classifyModuleRequest(url("/_vf_modules/file.tsx?t=123&ssr=true"));
+      assertEquals(result.kind, "dev-module");
+    });
+  });
+
+  describe("precedence", () => {
+    it("snippet prefix takes priority over dev-module", () => {
+      const result = classifyModuleRequest(url("/_vf_modules/_snippets/deadbeef.js"));
+      assertEquals(result.kind, "snippet");
+    });
+
+    it("versioned cross-project takes priority over latest cross-project", () => {
+      // If a slug contains @ it should match versioned, not latest
+      const result = classifyModuleRequest(
+        url("/_vf_modules/_cross/proj@2.0.0/@/index.js"),
+      );
+      assertEquals(result.kind, "cross-project-versioned");
+    });
+  });
+});

src/modules/server/classify.ts

@@ -0,0 +1,101 @@
+/**
+ * Module Request Classification
+ *
+ * Classifies incoming module request URLs into a discriminated union, moving
+ * the four URL-pattern regexes out of `serveModule` and providing a single
+ * pure function that callers can switch on.
+ *
+ * @module modules/server/classify
+ */
+
+/** Prefix for dev-module URLs; exported for path stripping in module-server. */
+export const DEV_MODULE_PREFIX = /^\/(?:_vf_modules|_veryfront\/modules)\//;
+const SNIPPET_MODULE_PREFIX = /^\/_vf_modules\/_snippets\/([a-f0-9]+)\.js/;
+// Cross-project import patterns: /_vf_modules/_cross/<slug>[@<version>]/@/<path>
+const CROSS_PROJECT_VERSIONED_PREFIX =
+  /^\/_vf_modules\/_cross\/([a-z0-9-]+)@([\d^~x][\d.x^~-]*)\/\@\/(.+)$/;
+const CROSS_PROJECT_LATEST_PREFIX = /^\/_vf_modules\/_cross\/([a-z0-9-]+)\/\@\/(.+)$/;
+
+/** URL does not start with any module prefix — not a module request. */
+export interface NotModuleKind {
+  kind: "not-module";
+}
+
+/** A compiled snippet module identified by its content hash. */
+export interface SnippetKind {
+  kind: "snippet";
+  /** Hex hash of the snippet source. */
+  hash: string;
+}
+
+/** A cross-project import pinned to a specific semver / range version. */
+export interface CrossProjectVersionedKind {
+  kind: "cross-project-versioned";
+  slug: string;
+  version: string;
+  path: string;
+}
+
+/** A cross-project import resolved to the latest published version. */
+export interface CrossProjectLatestKind {
+  kind: "cross-project-latest";
+  slug: string;
+  path: string;
+}
+
+/** A regular project dev-module (including framework modules). */
+export interface DevModuleKind {
+  kind: "dev-module";
+}
+
+/**
+ * Discriminated union of all recognised module URL shapes.
+ *
+ * Switch on `kind` to dispatch to the appropriate handler.
+ */
+export type ModuleRequestKind =
+  | NotModuleKind
+  | SnippetKind
+  | CrossProjectVersionedKind
+  | CrossProjectLatestKind
+  | DevModuleKind;
+
+/**
+ * Classify a module request URL into one of the known module kinds.
+ *
+ * This is a pure function — it performs no I/O and has no side-effects.
+ *
+ * @param url - The parsed request URL.
+ * @returns A `ModuleRequestKind` discriminated union.
+ */
+export function classifyModuleRequest(url: URL): ModuleRequestKind {
+  if (!DEV_MODULE_PREFIX.test(url.pathname)) {
+    return { kind: "not-module" };
+  }
+
+  const snippetMatch = url.pathname.match(SNIPPET_MODULE_PREFIX);
+  if (snippetMatch) {
+    return { kind: "snippet", hash: snippetMatch[1] ?? "" };
+  }
+
+  const versionedMatch = url.pathname.match(CROSS_PROJECT_VERSIONED_PREFIX);
+  if (versionedMatch) {
+    return {
+      kind: "cross-project-versioned",
+      slug: versionedMatch[1] ?? "",
+      version: versionedMatch[2] ?? "",
+      path: versionedMatch[3] ?? "",
+    };
+  }
+
+  const latestMatch = url.pathname.match(CROSS_PROJECT_LATEST_PREFIX);
+  if (latestMatch) {
+    return {
+      kind: "cross-project-latest",
+      slug: latestMatch[1] ?? "",
+      path: latestMatch[2] ?? "",
+    };
+  }
+
+  return { kind: "dev-module" };
+}

src/modules/server/module-batch-handler.ts

@@ -25,15 +25,14 @@ import {
 } from "#veryfront/utils";
 import type { RuntimeAdapter } from "#veryfront/platform/adapters/base.ts";
 import { createSecureFs } from "#veryfront/security";
-import { transformToESM } from "#veryfront/transforms/esm-transform.ts";
 import { createFileSystem } from "#veryfront/platform/compat/fs.ts";
 import { join } from "#veryfront/compat/path/index.ts";
 import {
-  applySSRImportRewritesAsync,
   resolveSSRImportTargetModulePath,
   type SSRImportRewriteTarget,
   stripSSRModuleJsExtension,
 } from "./ssr-import-rewriter.ts";
+import { transformModuleToServable } from "./module-transform.ts";
 import { buildModuleTransformCacheKey } from "#veryfront/cache/keys.ts";
 import { withSpan } from "#veryfront/observability/tracing/otlp-setup.ts";
 import { getFrameworkSourceLookupDirs } from "#veryfront/platform/compat/framework-source-resolver.ts";
@@ -397,26 +396,33 @@ async function transformModule(
     reactVersion?: string;
   },
 ): Promise<string> {
-  let code = await transformToESM(source, sourceFile, projectDir, adapter, {
-    projectId: options.projectId ?? projectDir,
-    dev: options.dev,
-    ssr: options.ssr,
-    reactVersion: options.reactVersion,
+  return transformModuleToServable({
+    source,
+    sourceFile,
+    projectDir,
+    adapter,
+    transformOpts: {
+      projectId: options.projectId ?? projectDir,
+      dev: options.dev,
+      ssr: options.ssr,
+      reactVersion: options.reactVersion,
+    },
+    isSSR: options.ssr,
+    ssrRewriteOptions: options.ssr
+      ? {
+        projectSlug: options.projectSlug,
+        branch: options.branch,
+        resolveCacheBuster: createBatchSSRTargetCacheBusterResolver({
+          projectDir,
+          secureFs,
+          currentModulePath: modulePath,
+        }),
+      }
+      : undefined,
+    // No releaseRewriteOptions: the batch handler does not rewrite release
+    // dependency imports on the non-SSR path (intentional difference vs
+    // the module-server paths; noted in module-transform.ts JSDoc).
   });
-
-  if (options.ssr) {
-    code = await applySSRImportRewritesAsync(code, {
-      projectSlug: options.projectSlug,
-      branch: options.branch,
-      resolveCacheBuster: createBatchSSRTargetCacheBusterResolver({
-        projectDir,
-        secureFs,
-        currentModulePath: modulePath,
-      }),
-    });
-  }
-
-  return code;
 }
 
 async function readBatchTargetSource(