@webjsdev/server 0.8.20 → 0.8.21

package/index.d.ts

@@ -312,6 +312,11 @@ export declare function resolveVendorImports(
 export declare function clearVendorCache(): void;
 /** Read a package's installed version from `node_modules`, or null. */
 export declare function getPackageVersion(pkgName: string, appDir: string): string | null;
+/** Read a package's installed `dependencies` + `peerDependencies` (hoist-aware), or null. */
+export declare function getPackageManifest(
+  pkgName: string,
+  appDir: string,
+): { dependencies: Record<string, string>; peerDependencies: Record<string, string> } | null;
 /** Resolve a list of `pkg@version` installs to importmap entries via a provider. */
 export declare function jspmGenerate(installs: string[], provider?: string): Promise<Record<string, string>>;
 /** Pin every (or the named) bare imports to `.webjs/vendor/importmap.json`. */
@@ -340,6 +345,14 @@ export declare function updatePinned(appDir: string, opts?: { from?: string }):
 export declare function readPinFile(
   appDir: string,
 ): Promise<{ imports: Record<string, string>; integrity?: Record<string, string>; provider?: string } | null>;
+/**
+ * Make the opt-in `webjs vendor pin` output committable. Heals an app's
+ * `.gitignore` when a `.webjs` exclusion would swallow the pins, and is a
+ * no-op when they are already committable. Called only from `vendor pin`.
+ */
+export declare function ensureVendorCommittable(
+  appDir: string,
+): Promise<{ ignored: boolean; patched: boolean; gitignorePath: string | null }>;
 /** Serve a downloaded `/__webjs/vendor/*` bundle file (`--download` mode). */
 export declare function serveDownloadedBundle(
   appDir: string,
@@ -349,6 +362,50 @@ export declare function serveDownloadedBundle(
 export declare const SUPPORTED_PROVIDERS: Set<string>;
 /** Normalize / validate a provider name. */
 export declare function normalizeProvider(name: string): string;
+/**
+ * Validate a produced importmap's pinned dependency graph for coherence
+ * (issue #450). For each resolved package, checks that the version pinned for
+ * every OTHER resolved package it depends on satisfies the declared range.
+ * Pure in `(imports, getManifest)`, so the same dep set yields the same verdict
+ * over a live importmap and a vendored one. Degrades to `unverified` when a
+ * manifest is unavailable.
+ */
+export declare function checkImportmapCoherence(
+  imports: Record<string, string>,
+  opts: {
+    getManifest: (
+      pkg: string,
+      version: string,
+    ) =>
+      | { dependencies?: Record<string, string>; peerDependencies?: Record<string, string> }
+      | null
+      | Promise<{ dependencies?: Record<string, string>; peerDependencies?: Record<string, string> } | null>;
+  },
+): Promise<{
+  conflicts: Array<{
+    pkg: string;
+    version: string;
+    dependsOn: string;
+    kind: 'dependency' | 'peerDependency';
+    requiredRange: string;
+    pinnedVersion: string;
+  }>;
+  unverified: Array<{ pkg: string; reason: string }>;
+  checked: number;
+}>;
+/** Extract `{ basePackage -> pinned version }` from an importmap's `imports` map. */
+export declare function extractPinnedVersions(
+  imports: Record<string, string>,
+): Map<string, string>;
+/**
+ * Does `version` satisfy the npm `range`? Pragmatic, dependency-free. Returns
+ * `null` for a range shape it cannot statically evaluate (the "could not
+ * verify" signal).
+ */
+export declare function satisfiesSemverRange(
+  version: string,
+  range: string,
+): boolean | null;
 
 // ---------------------------------------------------------------------------
 // module-graph.js
@@ -701,6 +758,43 @@ export interface ProviderConfig {
   [key: string]: unknown;
 }
 
+/**
+ * The augmentable session-user interface (#451), NextAuth/Auth.js style.
+ *
+ * It is EMPTY by default. An app declares the fields its `session`/`jwt`
+ * callbacks set (e.g. crisp sets `session.user.id = token.uid`) by augmenting
+ * it, which then types every `auth()` call globally with no cast and catches
+ * typos:
+ *
+ * ```ts
+ * declare module '@webjsdev/server' {
+ *   interface AuthUser {
+ *     id: string;
+ *     username: string;
+ *   }
+ * }
+ * ```
+ *
+ * Left un-augmented, `auth().user` falls back to `Record<string, unknown>` (see
+ * {@link ResolvedAuthUser}), so every pre-#451 app that reads `user.<field>`
+ * without declaring a shape keeps compiling unchanged. For per-instance typing
+ * instead of a global augmentation, parameterise the factory:
+ * `createAuth<MyUser>(...)`, whose `auth()` returns `{ user: MyUser }`.
+ */
+export interface AuthUser {}
+
+/**
+ * The resolved session-user shape used when `createAuth` is called WITHOUT an
+ * explicit type argument: the augmented {@link AuthUser} when an app declared
+ * one, else the open `Record<string, unknown>` (the pre-#451 default). The
+ * `keyof` probe is how the un-augmented empty interface degrades to the loose
+ * record so existing untyped code is unaffected, while an augmented interface
+ * gives precise, typo-catching fields.
+ */
+export type ResolvedAuthUser = keyof AuthUser extends never
+  ? Record<string, unknown>
+  : AuthUser;
+
 /** Auth configuration for `createAuth`. */
 export interface AuthConfig {
   providers: ProviderConfig[];
@@ -711,9 +805,15 @@ export interface AuthConfig {
   pages?: { signIn?: string; signOut?: string; error?: string };
 }
 
-/** The auth system created by `createAuth`. */
-export interface AuthInstance {
-  auth: (req?: Request) => Promise<{ user: Record<string, unknown> } | null>;
+/**
+ * The auth system created by `createAuth`. `TUser` is the resolved session-user
+ * shape; it defaults to {@link ResolvedAuthUser} (the augmented {@link AuthUser}
+ * if an app declared one, else `Record<string, unknown>`) so a module
+ * augmentation flows to every `auth()` call, and can be overridden per instance
+ * via `createAuth<MyUser>(...)`.
+ */
+export interface AuthInstance<TUser = ResolvedAuthUser> {
+  auth: (req?: Request) => Promise<{ user: TUser } | null>;
   signIn: (
     provider: string,
     data?: Record<string, unknown>,
@@ -723,8 +823,14 @@ export interface AuthInstance {
   handlers: { GET: (req: Request) => Promise<Response>; POST: (req: Request) => Promise<Response> };
 }
 
-/** Create the auth system. */
-export declare function createAuth(config: AuthConfig): AuthInstance;
+/**
+ * Create the auth system. Parameterise with the session-user shape
+ * (`createAuth<MyUser>(...)`) for per-instance typing, or augment the
+ * {@link AuthUser} interface for global typing; both make `auth().user` typed
+ * with no cast. Defaults to the open {@link AuthUser}, so existing untyped code
+ * keeps compiling unchanged.
+ */
+export declare function createAuth<TUser = ResolvedAuthUser>(config: AuthConfig): AuthInstance<TUser>;
 /** The credentials (email/password) provider. */
 export declare function Credentials(opts: Record<string, unknown>): ProviderConfig;
 /** The Google OAuth provider. */

package/index.js

@@ -21,6 +21,7 @@ export {
   resolveVendorImports,
   clearVendorCache,
   getPackageVersion,
+  getPackageManifest,
   jspmGenerate,
   pinAll,
   unpinPackage,
@@ -30,9 +31,13 @@ export {
   hasVendorPin,
   updatePinned,
   readPinFile,
+  ensureVendorCommittable,
   serveDownloadedBundle,
   SUPPORTED_PROVIDERS,
   normalizeProvider,
+  checkImportmapCoherence,
+  extractPinnedVersions,
+  satisfiesSemverRange,
 } from './src/vendor.js';
 export { buildModuleGraph, transitiveDeps } from './src/module-graph.js';
 export { scanComponents, primeComponentRegistry, extractComponents, findOrphanComponents } from './src/component-scanner.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.20",
+  "version": "0.8.21",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/auth.js

@@ -192,6 +192,13 @@ export function GitHub(opts = {}) {
 
 /**
  * Create the auth system.
+ *
+ * The session-user shape is typed via the `@webjsdev/server` overlay: augment
+ * its `AuthUser` interface (NextAuth/Auth.js style) for global typing, or call
+ * `createAuth<MyUser>(...)` from TypeScript for per-instance typing. See #451
+ * and the auth recipe. This JSDoc keeps the loose runtime shape; the precise
+ * typing lives in `index.d.ts` (types-only, no runtime effect).
+ *
  * @param {AuthConfig} config
  * @returns {{
  *   auth: (req?: Request) => Promise<{ user: Record<string,unknown> }|null>,

package/src/check.js

@@ -6,6 +6,10 @@ import {
   extractWebComponentClassBodies,
   matchClosingBrace,
 } from './js-scan.js';
+import { buildModuleGraph, transitiveDeps } from './module-graph.js';
+import { scanComponents } from './component-scanner.js';
+import { buildRouteTable } from './router.js';
+import { analyzeElision } from './component-elision.js';
 
 /**
  * Convention validator for webjs apps.
@@ -94,14 +98,14 @@ export const RULES = [
       'Scans .ts / .mts source for the four non-erasable TypeScript constructs (enum declarations, namespace blocks with value statements, constructor parameter properties, and `import = require`) that the framework\'s type-stripper rejects at request time. Companion to `erasable-typescript-only`: that rule checks the tsconfig flag, this rule checks the actual source. Both run by default so the flag check catches violations early in the editor while the source scan catches violations even if the tsconfig flag is missing or the rule is bypassed. Skips node_modules, dist, build, .git, .next, and _private folders.',
   },
   {
-    name: 'gitignore-vendor-not-ignored',
+    name: 'no-browser-globals-in-render',
     description:
-      'Verifies the `.gitignore` exception for `.webjs/vendor/` is structurally correct via `git check-ignore`. The intended pattern is `**/.webjs/*` (NOT `.webjs/`) plus `!**/.webjs/vendor/` plus `!**/.webjs/vendor/**`. The `**/` prefix matches `.webjs/` at any depth so a nested / monorepo app does not leak its generated `.webjs/routes.d.ts`; the older root-anchored `.webjs/*` also passes this rule (the probe is run from the app root). The common-looking pattern `.webjs/` excludes the directory itself, after which git cannot re-include children (gitignore semantics: a parent exclusion blocks child negations). Without this rule, an AI agent or human editor would silently break `webjs vendor pin` by simplifying the pattern; the failure is invisible until production. Rule fires when the working directory is a git repo and a `.gitignore` exists; skipped when neither is true.',
+      'Flags genuinely browser-only APIs used in a WebComponent constructor, willUpdate, or render() method. The SSR pipeline instantiates the component, runs willUpdate plus controllers\' hostUpdate, reflects properties, and calls render() to produce HTML, on a server element shim that backs the attribute methods but has no real DOM. So a browser global (document, window, localStorage, sessionStorage, navigator, location, matchMedia, screen, history) or an unshimmed HTMLElement member on `this` (attachShadow, shadowRoot, classList, querySelector, querySelectorAll, getBoundingClientRect, focus, blur, scrollIntoView) touched there throws at SSR time (the isomorphic footgun). The attribute methods (getAttribute/setAttribute/hasAttribute/removeAttribute/toggleAttribute), the event methods (addEventListener/removeEventListener/dispatchEvent), and attachInternals are shim-backed and run server-side, so they are NOT flagged. The flagged APIs belong in connectedCallback() or a lifecycle hook (firstUpdated/updated), which SSR never calls; seed first-paint defaults in the constructor (or derive them in willUpdate) only from server-known inputs (attributes, props). Conservative: only the constructor, willUpdate, and render bodies are scanned, and only direct references, so helper indirection is not flagged (the runtime SSR error covers that case).',
   },
   {
-    name: 'no-browser-globals-in-render',
+    name: 'no-server-import-in-browser-module',
     description:
-      'Flags genuinely browser-only APIs used in a WebComponent constructor, willUpdate, or render() method. The SSR pipeline instantiates the component, runs willUpdate plus controllers\' hostUpdate, reflects properties, and calls render() to produce HTML, on a server element shim that backs the attribute methods but has no real DOM. So a browser global (document, window, localStorage, sessionStorage, navigator, location, matchMedia, screen, history) or an unshimmed HTMLElement member on `this` (attachShadow, shadowRoot, classList, querySelector, querySelectorAll, getBoundingClientRect, focus, blur, scrollIntoView) touched there throws at SSR time (the isomorphic footgun). The attribute methods (getAttribute/setAttribute/hasAttribute/removeAttribute/toggleAttribute), the event methods (addEventListener/removeEventListener/dispatchEvent), and attachInternals are shim-backed and run server-side, so they are NOT flagged. The flagged APIs belong in connectedCallback() or a lifecycle hook (firstUpdated/updated), which SSR never calls; seed first-paint defaults in the constructor (or derive them in willUpdate) only from server-known inputs (attributes, props). Conservative: only the constructor, willUpdate, and render bodies are scanned, and only direct references, so helper indirection is not flagged (the runtime SSR error covers that case).',
+      'A page / layout / component module that SHIPS to the browser (the build does NOT elide it) must not transitively import a server-only `.server.{ts,js}` module. The server module is replaced by a stub in the browser, so the import is fine while the page is display-only and elided (its server import is stripped), but the moment the page also does client work (it imports a component to register, enables the client router, uses a reactive primitive, …) it stops being elided and must load in the browser, dragging the server import with it. The stub then throws (or a server-only export like `auth` is missing) the instant the module loads, a runtime browser crash that `webjs typecheck` and the rest of `webjs check` miss. The rule reuses the build\'s own elision verdict, so it ONLY fires on modules that genuinely ship; a display-only page the framework elides is never flagged. The fix is to keep the server call off the browser-shipped module: gate the route in `middleware.ts`, call the server through a `\'use server\'` action, or register the component in a layout so the page elides again. Server-to-server imports (`.server.ts` importing `.server.ts`) and `middleware.ts` / `route.ts` (never shipped) are never flagged.',
   },
   {
     name: 'no-scaffold-placeholder',
@@ -812,74 +816,261 @@ export async function checkConventions(appDir) {
     }
   }
 
-  // --- Rule: gitignore-vendor-not-ignored ---
-  // The .gitignore pattern for .webjs/vendor/ is subtle: `.webjs/`
-  // alone excludes the directory entirely and git can't re-include
-  // children of an excluded parent. The correct pattern is `**/.webjs/*`
-  // plus `!**/.webjs/vendor/` plus `!**/.webjs/vendor/**` (the `**/`
-  // prefix ignores `.webjs/` at any depth so a nested app does not leak
-  // its generated routes.d.ts; the older root-anchored `.webjs/*` also
-  // passes, since this probe runs from the app root). AI agents and
-  // human reviewers frequently "simplify" this back to `.webjs/`,
-  // silently breaking `webjs vendor pin`.
+  // --- Rule: no-server-import-in-browser-module ---
+  // A page / layout / component module that SHIPS to the browser must not
+  // transitively import a server-only `.server.{ts,js}` module. The browser
+  // gets a stub for the server file, so the import is harmless while the page
+  // is display-only and the framework ELIDES it (its server import is stripped
+  // from the served source). But the moment the page also does client work
+  // (imports a component to register, enables the client router, uses a
+  // reactive primitive, …) it stops being elided, must load in the browser,
+  // and drags the server import with it: the stub throws (or a server-only
+  // export like `auth` is missing) the instant the module loads. That crash
+  // only surfaces at runtime; typecheck and every other check pass.
   //
-  // This rule verifies the actual gitignore behavior by spawning
-  // `git check-ignore` against a representative pin-file path. If
-  // git reports the file as ignored, the pattern is broken.
-  //
-  // Skipped when the directory isn't a git repo or has no .gitignore
-  // (the user hasn't opted into version control yet).
-  {
-    const hasGit = await pathExists(join(appDir, '.git'));
-    const hasGitignore = await pathExists(join(appDir, '.gitignore'));
-    if (hasGit && hasGitignore) {
-      const { spawnSync } = await import('node:child_process');
-      // Strip inherited git env vars so `cwd` is the sole authority on
-      // which repo `git check-ignore` consults. Git exports GIT_DIR /
-      // GIT_WORK_TREE / GIT_INDEX_FILE / GIT_PREFIX into hook processes
-      // (notably a pre-commit hook run from a linked worktree exports
-      // GIT_WORK_TREE), and those OVERRIDE cwd-based discovery, so
-      // without this the probe would consult the outer repo instead of
-      // `appDir`. See the gitignore-vendor-not-ignored regression test.
-      const {
-        GIT_DIR: _gd, GIT_WORK_TREE: _gwt, GIT_INDEX_FILE: _gif, GIT_PREFIX: _gp,
-        ...gitEnv
-      } = process.env;
-      // Check two representative paths: the pin manifest AND a sample
-      // downloaded bundle. A `.gitignore` that allows the manifest
-      // but blocks bundles (e.g. `*.js` higher up) would still break
-      // `webjs vendor pin --download`. `git check-ignore -q` exits 0
-      // when ignored, 1 when not ignored.
-      const probes = [
-        '.webjs/vendor/importmap.json',
-        '.webjs/vendor/sample-pkg@1.0.0.js',
-      ];
-      for (const probe of probes) {
-        const result = spawnSync('git', ['check-ignore', '-q', probe], {
-          cwd: appDir,
-          stdio: 'pipe',
-          env: gitEnv,
-        });
-        if (result.status === 0) {
-          violations.push({
-            rule: 'gitignore-vendor-not-ignored',
-            file: '.gitignore',
-            message:
-              `${probe} is gitignored, but \`webjs vendor pin\` writes files under .webjs/vendor/ and they MUST be committed for production deploys to use the pin (instead of calling api.jspm.io on every cold start). The most common cause: a \`.webjs/\` line in .gitignore that excludes the parent directory before the \`!.webjs/vendor/\` exception can take effect (git semantics: a parent exclusion blocks child negations). A second possible cause is a broader rule (e.g. \`*.js\` at root) that hides bundle files added by \`webjs vendor pin --download\`.`,
-          fix:
-            'Replace `.webjs/` in your .gitignore with this three-line pattern:\n' +
-            '  **/.webjs/*\n' +
-            '  !**/.webjs/vendor/\n' +
-            '  !**/.webjs/vendor/**\n' +
-            'The `**/` prefix ignores `.webjs/` at any depth (so a nested / monorepo app does not leak its generated `.webjs/routes.d.ts`) while still re-including the committed vendor pin. ' +
-            'Verify with `git check-ignore -q .webjs/vendor/importmap.json` (exit 1 means correctly un-ignored).',
-        });
-      }
+  // The rule reuses the BUILD'S elision verdict (analyzeElision) instead of
+  // re-deriving it, so it fires ONLY on modules that genuinely ship: a
+  // display-only page the framework elides is never flagged (that is the
+  // legitimate pattern). The motivating case (crisp dogfood): a page that does
+  // `await auth()` (import from `lib/auth.server.ts`) AND imports a component
+  // directly, so it is not elided and ships the server import.
+  await checkServerImportInBrowserModule(appDir, violations);
+
+  return violations;
+}
+
+/**
+ * Implements `no-server-import-in-browser-module`. Factored into its own
+ * function (rather than an inline block) because it does the heavier
+ * whole-app analysis the other rules avoid: it builds the module graph,
+ * scans components, builds the route table, and runs the framework's own
+ * elision analysis so the rule's notion of "ships to the browser" is
+ * byte-for-byte the build's.
+ *
+ * A module is flagged when BOTH hold:
+ *   1. It SHIPS to the browser. For a component that means it is NOT in the
+ *      elidable set; for a page / layout that means it is NOT in the inert
+ *      route-module set. (Pages and layouts that do real client work are not
+ *      inert and therefore ship.)
+ *   2. Its transitive import closure reaches a `.server.{ts,js}` module.
+ *      `transitiveDeps` stops AT a server file (it is included but not walked
+ *      into), so a server file pulled in only through another server file is
+ *      not attributed to a browser module that never reaches it directly.
+ *
+ * Also flagged: error / loading / not-found modules. These ship to the browser
+ * too (the dev server's `computeBrowserBoundFiles` adds them unconditionally)
+ * and are never elided, so a server import reaching one of them is the same
+ * throw-at-load crash.
+ *
+ * Never flagged: a `.server.ts` importing another `.server.ts` (server-to-
+ * server, and `.server.*` modules are not components nor route modules), and
+ * `middleware.ts` / `route.ts` (server-only, never page/layout/component
+ * entries, so they are not in the candidate set to begin with).
+ *
+ * Known limitation: a DYNAMIC `import('./x.server.ts')` is invisible to this
+ * rule. The framework's import scanner (`IMPORT_RE` in module-graph.js) matches
+ * only static `import`/`export … from`, not the `import(` call form, so a
+ * dynamic server import is not a graph edge here. This is deliberate and
+ * consistent with the framework-wide graph: a dynamic import is also not elided
+ * framework-wide, and its crash is deferred to call time (when the chunk is
+ * fetched), not module load. Catching it would mean teaching the shared scanner
+ * about `import(`, which is out of scope for this rule.
+ *
+ * @param {string} appDir
+ * @param {Violation[]} violations  appended to in place
+ */
+async function checkServerImportInBrowserModule(appDir, violations) {
+  // No `app/` directory means this is not a routable webjs app (e.g. a bare
+  // component library, or a fixture with only `lib/`); nothing ships, so the
+  // rule has nothing to police. Skip rather than do the heavy analysis.
+  if (!(await pathExists(join(appDir, 'app')))) return;
+
+  let moduleGraph, components, routeTable;
+  try {
+    moduleGraph = await buildModuleGraph(appDir);
+    components = await scanComponents(appDir);
+    routeTable = await buildRouteTable(appDir);
+  } catch {
+    // A malformed app the analysis can't process is left to the other rules
+    // (and the dev server) to surface; this rule degrades to a no-op.
+    return;
+  }
+
+  // Page + layout modules that the router treats as route modules, exactly the
+  // set the dev server feeds to analyzeElision (so the inert verdict matches).
+  /** @type {Set<string>} */
+  const routeModuleSet = new Set();
+  for (const page of routeTable.pages || []) {
+    if (page.file) routeModuleSet.add(page.file);
+    for (const f of page.layouts || []) routeModuleSet.add(f);
+  }
+  const routeModules = [...routeModuleSet];
+
+  // error / loading / not-found modules ALSO ship to the browser, but unlike
+  // pages + layouts they are never elided: the dev server's
+  // `computeBrowserBoundFiles` adds them to the browser-bound entry set
+  // unconditionally (only ELIDABLE-COMPONENT imports are ever stripped, and
+  // these modules have no component to strip). So a personalized 404 that does
+  // `await auth()` is a real throw-at-load crash the page+layout-only candidate
+  // set would miss. Collect them here and add them to the candidate set as
+  // always-shipping (no elision verdict to consult).
+  /** @type {Map<string, string>} abs file -> kind */
+  const alwaysShipRouteModules = new Map();
+  for (const page of routeTable.pages || []) {
+    for (const f of page.errors || []) alwaysShipRouteModules.set(f, 'error boundary');
+    for (const f of page.loadings || []) alwaysShipRouteModules.set(f, 'loading boundary');
+  }
+  if (routeTable.notFound) alwaysShipRouteModules.set(routeTable.notFound, 'not-found page');
+  if (routeTable.notFounds) {
+    for (const f of routeTable.notFounds.values()) {
+      alwaysShipRouteModules.set(f, 'not-found page');
     }
+  }
+
+  // The elision flag mirrors `dev.js`: respect `webjs.elide === false` and the
+  // WEBJS_ELIDE override. When elision is OFF, the build ships EVERY component
+  // and route module, so the verdict is "nothing is elidable / inert" and the
+  // rule treats every candidate as shipping (which is correct: with elision
+  // off, a display-only page really does ship its server import too).
+  const elideEnabled = await readElideEnabledForCheck(appDir);
+  const { elidableComponents, inertRouteModules } = elideEnabled
+    ? await analyzeElision(components, routeModules, moduleGraph, (f) => readFile(f, 'utf8'), appDir)
+    : { elidableComponents: new Set(), inertRouteModules: new Set() };
+
+  // Candidate browser-shipped modules: components that are NOT elided, plus
+  // route modules that are NOT inert. A `.server.*` file is never a component
+  // (the scanner skips it) nor a route module the browser loads, so it cannot
+  // enter this set; server-to-server imports are excluded by construction.
+  /** @type {Map<string, { kind: string }>} relFile is keyed by ABS path */
+  const candidates = new Map();
+  for (const c of components) {
+    if (!elidableComponents.has(c.file)) candidates.set(c.file, { kind: 'component' });
+  }
+  for (const file of routeModules) {
+    if (inertRouteModules.has(file)) continue;
+    const base = basename(file);
+    const kind = /^layout\./.test(base) ? 'layout' : 'page';
+    candidates.set(file, { kind });
+  }
+  // error / loading / not-found modules always ship (never elided), so they are
+  // candidates unconditionally. A page/layout entry already in `candidates`
+  // wins (it is the more specific kind); these only add files not already seen.
+  for (const [file, kind] of alwaysShipRouteModules) {
+    if (!candidates.has(file)) candidates.set(file, { kind });
+  }
+
+  // Report at most once per module (a page importing two server modules is one
+  // finding, naming the first reached). Sorted for deterministic output.
+  for (const file of [...candidates.keys()].sort()) {
+    // `transitiveDeps` skips nothing here, so it includes (but does not walk
+    // into) any `.server.*` file reachable from this module. The module itself
+    // is not in the result. A direct OR indirect server import both surface,
+    // because the closure walks every non-server edge until it hits one.
+    const closure = transitiveDeps(moduleGraph, [file], appDir);
+    // Of the reachable server files, find one that is a genuine throw-at-load
+    // crash in the browser. TWO kinds of `.server.*` import are NOT crashes and
+    // must be skipped, or the rule false-positives on legitimate code:
+    //   - A `'use server'` ACTION. The browser receives a working RPC stub
+    //     whose exports POST to the server, so calling it from a shipping
+    //     module is the intended pattern (the issue even lists it as a fix).
+    //     Only a bare `.server.*` utility (no directive) gets the
+    //     throw-at-module-load stub that crashes the page.
+    //   - A PHANTOM edge to a file that does not exist on disk. The module
+    //     graph keeps quoted-string CONTENT verbatim, so an `import` written
+    //     inside a code-example string (the docs / website `<pre>` samples)
+    //     resolves to a non-existent path. That import never runs, so it is
+    //     not a crash; require the server file to actually exist.
+    let serverDep = null;
+    for (const d of closure) {
+      if (!/\.server\.m?[jt]s$/.test(d)) continue;
+      if (await isUseServerActionFile(d)) continue; // working RPC stub, not a crash
+      if (!(await pathExists(d))) continue;          // phantom edge from a string sample
+      serverDep = d;
+      break;
     }
+    if (!serverDep) continue;
+
+    const { kind } = candidates.get(file);
+    const relFile = relative(appDir, file);
+    const relServer = relative(appDir, serverDep);
+    // Name the import chain: if the server file is a DIRECT import of this
+    // module, the chain is just the two; otherwise show one intermediate hop
+    // so the diagnostic points at where the edge enters (the full path is
+    // recoverable from the graph, but one hop is enough to locate it).
+    const directDeps = moduleGraph.get(file);
+    const directlyImported = directDeps && directDeps.has(serverDep);
+    const chain = directlyImported
+      ? `${relFile} -> ${relServer}`
+      : `${relFile} -> … -> ${relServer}`;
+
+    // The "register the component in a layout so it elides again" remedy only
+    // applies to a page / layout, which CAN elide (it became browser-bound by
+    // importing a component). The error / loading / not-found boundaries always
+    // ship and are never elided, so offering them an "elides again" fix is
+    // wrong. Branch the fix text on whether the kind can elide.
+    const canElide = kind === 'page' || kind === 'layout';
+    const fixText = canElide
+      ? `Keep the server call off this browser-shipped ${kind}. Options: (1) gate the route in \`middleware.ts\` (runs server-side, never ships); (2) move the server-only call behind a \`'use server'\` action in a \`.server.{ts,js}\` file and call it as an RPC; or (3) if this ${kind} only became browser-bound because it imports a component to register, register that component in a \`layout.{ts,js}\` instead so the ${kind} elides again and its server import is stripped.`
+      : `Keep the server call off this browser-shipped ${kind} (it always ships and is never elided). Options: (1) gate the route in \`middleware.ts\` (runs server-side, never ships); or (2) move the server-only call behind a \`'use server'\` action in a \`.server.{ts,js}\` file and call it as an RPC.`;
+
+    violations.push({
+      rule: 'no-server-import-in-browser-module',
+      file: relFile,
+      message:
+        `This ${kind} ships to the browser (the build does not elide it) but transitively imports the server-only module ${relServer} (${chain}). In the browser that import resolves to a stub, so the module crashes at load (the stub throws, or a server-only export such as \`auth\` is missing). \`webjs typecheck\` and the rest of \`webjs check\` pass; only the running ${kind} fails.`,
+      fix: fixText,
+    });
   }
+}
 
-  return violations;
+/**
+ * Read whether component elision is enabled for `appDir`, mirroring
+ * `dev.js`'s `readElideEnabled` so the check's notion of "ships" matches the
+ * dev server's. Elision is ON unless `webjs.elide === false` in package.json or
+ * the `WEBJS_ELIDE` env var forces it off (`0` / `false` / `off` / `no`). A
+ * missing or malformed package.json keeps the default (on). Inlined rather
+ * than imported from `dev.js` so the check tool does not pull the whole dev
+ * server module just for this flag.
+ *
+ * @param {string} appDir
+ * @returns {Promise<boolean>}
+ */
+/**
+ * True if `file` is a `'use server'` action: a `.server.{ts,js}` module that
+ * declares the `'use server'` directive. The dev server rewrites its browser
+ * import into a working RPC stub (exports POST to the server), so importing it
+ * from a shipping module is legitimate, NOT the throw-at-load crash the
+ * no-server-import-in-browser-module rule catches. A bare `.server.*` utility
+ * (no directive) instead gets a stub that throws when the module loads, which
+ * IS the crash. Returns false on any read failure (treat an unreadable server
+ * file as a potential crash, the conservative direction for this rule).
+ *
+ * @param {string} file absolute path to a `.server.*` file
+ * @returns {Promise<boolean>}
+ */
+async function isUseServerActionFile(file) {
+  try {
+    const content = await readFile(file, 'utf8');
+    return hasUseServerDirective(content);
+  } catch {
+    return false;
+  }
+}
+
+async function readElideEnabledForCheck(appDir) {
+  const raw = process.env.WEBJS_ELIDE;
+  if (raw != null) {
+    const v = raw.trim().toLowerCase();
+    if (v === '0' || v === 'false' || v === 'off' || v === 'no') return false;
+    if (v === '1' || v === 'true' || v === 'on' || v === 'yes') return true;
+  }
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    if (pkg && pkg.webjs && pkg.webjs.elide === false) return false;
+  } catch {
+    // No package.json, malformed JSON, or unreadable: keep the default.
+  }
+  return true;
 }
 
 /**
@@ -906,7 +1097,8 @@ async function pathExists(p) {
  * `cwd: appDir` and the inherited GIT_* env stripped so cwd is the sole
  * authority on which repo + .gitignore stack is consulted (a pre-commit
  * hook from a linked worktree exports GIT_WORK_TREE, which would otherwise
- * override cwd-based discovery; same reason as gitignore-vendor-not-ignored).
+ * override cwd-based discovery; same reason the doctor vendor-gitignore check
+ * strips them).
  * Works for an in-repo sub-package with no nested `.git` too: git walks up
  * to the monorepo root and resolves the relative paths against cwd.
  *

package/src/module-graph.js

@@ -262,13 +262,22 @@ async function parseFile(file, appDir, graph, seen) {
   // Mask of `src` with all string / template-literal / comment / regex
   // CONTENT blanked to spaces (positions preserved). Used to reject an
   // `import '…'` / `export … from '…'` that appears as TEXT inside a
-  // template literal (e.g. example code shown in a `<pre>` inside an
-  // `html\`\`` template, as the docs site does) rather than as a real
-  // statement. We still read the specifier from the RAW `src` (the
-  // specifier is itself a string, blanked in the mask), and only consult
-  // the mask to confirm the `import` / `export` KEYWORD survived
-  // redaction, i.e. sits in code position and not inside a literal.
-  const masked = redactStringsAndTemplates(src);
+  // literal (e.g. example code shown in a `<pre>` inside an `html\`\``
+  // template, as the docs site does, OR a code-example written as a plain
+  // quoted string) rather than as a real statement. We still read the
+  // specifier from the RAW `src` (the specifier is itself a string,
+  // blanked in the mask), and only consult the mask to confirm the
+  // `import` / `export` KEYWORD survived redaction, i.e. sits in code
+  // position and not inside a literal.
+  //
+  // `blankStrings: true` is load-bearing: the default mask keeps PLAIN
+  // string + verbatim-template bodies verbatim (so `register('tag')` stays
+  // readable for other scanners), which would leave an `import` written
+  // inside a plain string looking like a real keyword and create a phantom
+  // graph edge to whatever path that string names. Since this caller only
+  // checks keyword-in-code-position, blank every literal body so a
+  // code-example `import` string never becomes an edge.
+  const masked = redactStringsAndTemplates(src, true);
   const deps = new Set();
   for (const re of [IMPORT_RE, EXPORT_FROM_RE]) {
     for (const m of src.matchAll(re)) {