@webjsdev/server 0.8.19 → 0.8.21

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.
@@ -63,6 +67,11 @@ export const RULES = [
     description:
       'Static tag = \'...\' in component files must contain a hyphen (HTML custom element spec).',
   },
+  {
+    name: 'no-duplicate-tag',
+    description:
+      'A custom-element tag name must be registered exactly once across the app. Two `Class.register(\'tag\')` / `customElements.define(\'tag\', …)` calls for the SAME tag resolve INCONSISTENTLY at runtime: SSR overwrites the registry (last registration wins) while the browser keeps the first native upgrade, so the rendered element and the webjs registry disagree. Rename one tag.',
+  },
   {
     name: 'reactive-props-use-declare',
     description:
@@ -89,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',
@@ -751,76 +760,319 @@ 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`.
-  //
-  // 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).
+  // --- Rule: no-duplicate-tag ---
+  // Two registrations of the SAME tag string anywhere in the app resolve
+  // inconsistently at runtime (SSR last-wins, browser first-wins), so flag
+  // every colliding site naming the others. Scans EVERY source file, not just
+  // components/, because a duplicate is a runtime hazard regardless of where
+  // the register/define call lives (a page, a lib, a module can register a
+  // tag too); this keeps the rule in lockstep with the editor's 9004
+  // diagnostic, which is likewise project-wide. Reuses the same
+  // register/define extraction as tag-name-has-hyphen, over the redacted
+  // source so a tag in a docs-page tagged-template example does not count.
+  // Only hyphenated tags are considered (a non-hyphenated tag is already
+  // flagged by tag-name-has-hyphen / invariant 3), matching the 9004 filter.
   {
-    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).',
-        });
+    // Generated / gitignored files (e.g. a `webjs ui add`-regenerated
+    // `components/` dir) are not committed source the rule should police;
+    // counting them would flag a collision between a hand-written component
+    // and its generated copy. Skip anything git reports as ignored.
+    // Best-effort: a non-git project (or absent git) scans everything.
+    const ignored = await gitIgnoredSet(appDir, files.map((f) => f.rel));
+    /** @type {Map<string, string[]>} tag -> rel files that register it (with repeats) */
+    const tagSites = new Map();
+    const patterns = [
+      /\b[A-Z][A-Za-z0-9_$]*\.register\s*\(\s*(['"`])([^'"`]+)\1/g,
+      /\bcustomElements\.define\s*\(\s*(['"`])([^'"`]+)\1/g,
+    ];
+    for (const { scan, rel } of files) {
+      if (ignored.has(rel)) continue;
+      for (const re of patterns) {
+        let match;
+        while ((match = re.exec(scan)) !== null) {
+          const tagName = match[2];
+          if (!tagName.includes('-')) continue;
+          const arr = tagSites.get(tagName) || [];
+          arr.push(rel);
+          tagSites.set(tagName, arr);
+        }
       }
     }
+    for (const [tagName, sites] of tagSites) {
+      if (sites.length < 2) continue;
+      // Report once per DISTINCT file, naming the others.
+      for (const file of new Set(sites)) {
+        const others = [...new Set(sites)].filter((f) => f !== file);
+        const where = others.length
+          ? `also registered in ${others.join(', ')}`
+          : 'registered more than once in this file';
+        violations.push({
+          rule: 'no-duplicate-tag',
+          file,
+          message: `Custom element tag "${tagName}" is registered more than once (${where}). A tag must be registered exactly once; the runtime resolves a duplicate inconsistently (SSR keeps the last registration, the browser keeps the first).`,
+          fix: `Rename one registration so each "${tagName}" is unique, e.g. "${tagName}-2".`,
+        });
+      }
     }
   }
 
+  // --- 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.
+  //
+  // 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,
+    });
+  }
+}
+
+/**
+ * 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;
+}
+
 /**
  * Async fs.exists shim. Returns true if the path exists at all (file
  * or directory), false on ENOENT or any other stat failure.
@@ -836,3 +1088,50 @@ async function pathExists(p) {
     return false;
   }
 }
+
+/**
+ * The subset of `rels` (appDir-relative paths) that git reports as ignored,
+ * via a single batched `git check-ignore --stdin`. Best-effort: returns an
+ * empty Set when the directory is not a git repo, git is absent, or the
+ * spawn fails, so a non-git project scans every file as before. Runs with
+ * `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 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.
+ *
+ * @param {string} appDir absolute app directory
+ * @param {string[]} rels appDir-relative file paths
+ * @returns {Promise<Set<string>>}
+ */
+async function gitIgnoredSet(appDir, rels) {
+  /** @type {Set<string>} */
+  const out = new Set();
+  if (!rels.length) return out;
+  try {
+    const { spawnSync } = await import('node:child_process');
+    const {
+      GIT_DIR: _gd, GIT_WORK_TREE: _gwt, GIT_INDEX_FILE: _gif, GIT_PREFIX: _gp,
+      ...gitEnv
+    } = process.env;
+    // `git check-ignore --stdin` exits 0 when ≥1 path is ignored (those
+    // paths are echoed on stdout), 1 when none are ignored, >1 on error.
+    const res = spawnSync('git', ['check-ignore', '--stdin'], {
+      cwd: appDir,
+      input: rels.join('\n'),
+      encoding: 'utf8',
+      env: gitEnv,
+    });
+    if (res.status === 0 && typeof res.stdout === 'string') {
+      for (const line of res.stdout.split('\n')) {
+        const p = line.trim();
+        if (p) out.add(p);
+      }
+    }
+  } catch {
+    // git missing or spawn failure: scan everything (no filter).
+  }
+  return out;
+}

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)) {

package/src/page-action.js

@@ -196,9 +196,11 @@ export async function runPageAction(route, params, url, loaded, req, ssrOpts) {
   } catch (err) {
     if (isRedirect(err)) {
       const e = /** @type any */ (err);
-      // A thrown redirect from an action is honored as the page render does.
-      // Use the action's chosen status (307/308) so an explicit redirect()
-      // keeps its semantics; PRG (303) is the SUCCESS-result path below.
+      // A thrown redirect from an action (a POST) defaults to 307 Temporary
+      // Redirect, which is method-preserving so the action's intent survives
+      // the bounce; an explicit `redirect(url, status)` overrides it. This is
+      // deliberately NOT the GET gate's 302 default (see ssr.js). PRG (303) is
+      // the SUCCESS-result path below.
       return new Response(null, { status: e.status || 307, headers: { location: e.url } });
     }
     if (isNotFound(err)) {

package/src/ssr.js

@@ -198,7 +198,12 @@ export async function ssrPage(route, params, url, opts) {
   } catch (err) {
     if (isRedirect(err)) {
       const e = /** @type any */ (err);
-      return new Response(null, { status: e.status || 307, headers: { location: e.url } });
+      // A redirect thrown during a GET page/layout render is a GET-to-GET
+      // navigation (an auth bounce, a gate). 302 Found is the conventional
+      // code there, so it is the default when the caller did not pick one. An
+      // explicit `redirect(url, status)` overrides it. (Action redirects, a
+      // POST, default to 307 in page-action.js so the method is preserved.)
+      return new Response(null, { status: e.status || 302, headers: { location: e.url } });
     }
     if (isNotFound(err)) {
       const html = await ssrNotFoundHtml(null, opts);