@webjsdev/server 0.8.62 → 0.8.64

package/src/check/rules.js

@@ -0,0 +1,127 @@
+/**
+ * @typedef {{
+ *   rule: string,
+ *   file: string,
+ *   message: string,
+ *   fix: string,
+ * }} Violation
+ */
+
+/**
+ * @typedef {{
+ *   name: string,
+ *   description: string,
+ * }} RuleDescriptor
+ */
+
+/**
+ * All available rule names with descriptions. Useful for help text and
+ * documentation generators.
+ *
+ * @type {RuleDescriptor[]}
+ */
+export const RULES = [
+  {
+    name: 'components-have-register',
+    description:
+      'Component files that define a class extending WebComponent must register the class with ClassName.register(\'tag\') (or customElements.define). The server-side scanner derives the module URL from the file path.',
+  },
+  {
+    name: 'no-server-env-in-components',
+    description:
+      'Component files (under components/ or modules/*/components/) must not read non-public environment variables. process.env.X is allowed when X starts with WEBJS_PUBLIC_ (exposed to the browser via the SSR shim) or equals NODE_ENV (also defined in the browser). Any other process.env read in a component would leak the server-side value into the SSR\'d HTML, then read as undefined after hydration. Read server-only env vars in a page function, server action, or middleware (which never reach the browser as source) and pass derived values to the component as attributes.',
+  },
+  {
+    name: 'tag-name-has-hyphen',
+    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: 'no-static-properties',
+    description:
+      'Reactive properties must be declared via the `extends WebComponent({ … })` factory, never a hand-written `static properties = { … }` field in the class body. The factory types each field for you (no `declare` needed) and the runtime throws on a direct `static properties`. Migrate `class X extends WebComponent { static properties = { count: { type: Number } } }` to `class X extends WebComponent({ count: Number })`; use the `prop()` helper for options (`prop(Number, { reflect: true })`) and set defaults in the constructor after super().',
+  },
+  {
+    name: 'reactive-props-no-class-field',
+    description:
+      'A reactive property declared via the `extends WebComponent({ … })` factory must NOT also have a plain class-field declaration (`count = 0`, `count: number = 0`, `count!: number`, or `count?: number`) in the class body. Under modern class-field semantics (including `erasableSyntaxOnly: true`) every class-field declaration compiles to Object.defineProperty *after* super(), clobbering the framework\'s reactive accessor and silently breaking re-renders. Set the default by assigning in the constructor after super().',
+  },
+  {
+    name: 'array-prop-uses-array-type',
+    description:
+      'An array-typed reactive property declared via the `extends WebComponent({ … })` factory must pass the `Array` runtime constructor, not `Object`: `count: prop<Tag[]>(Array)`, never `prop<Tag[]>(Object)`. The two share one converter (both JSON-encode the value), so the wrong one does not crash, but `Object` misstates the prop contract to the next reader and diverges from the documented built-in set (String/Number/Boolean/Object/Array). Fires only when the factory generic is itself an array type (`T[]`, `readonly T[]`, `Array<T>`, `ReadonlyArray<T>`) AND the constructor argument is `Object`; a bare `foo: Object` with no generic is never flagged. Fix: change the constructor to `Array`.',
+  },
+  {
+    name: 'shell-in-non-root-layout',
+    description:
+      'Only the root layout (app/layout.{js,ts}) may write a <!doctype>/<html>/<head>/<body> shell to override default <html lang>, <body class>, etc. Non-root layouts (app/<segment>/layout.{js,ts}) and pages (app/**/page.{js,ts}) must not: the framework auto-emits the wrapper around the whole composition, so a nested shell ends up nested inside <body> where browsers drop it. Triggers on any of <!doctype>, <html, <head, <body in a non-root layout or page.',
+  },
+  {
+    name: 'erasable-typescript-only',
+    description:
+      'Apps must opt into TypeScript\'s `erasableSyntaxOnly: true` so the compiler rejects non-erasable syntax (enum, namespace with values, constructor parameter properties, legacy decorators with emitDecoratorMetadata, import = require) at edit time. webjs strips types via Node\'s built-in `module.stripTypeScriptTypes`, which only supports erasable TypeScript and produces byte-exact position preservation (no sourcemap overhead). Files using non-erasable syntax fail at strip time and the dev server returns a 500 pointing at the no-non-erasable-typescript rule; webjs is buildless end-to-end and has no bundler fallback. The rule checks the project\'s tsconfig.json and warns when `erasableSyntaxOnly` is missing or set to false. Set `compilerOptions.erasableSyntaxOnly: true` in tsconfig.json to comply.',
+  },
+  {
+    name: 'use-server-needs-extension',
+    description:
+      'Files that declare the `\'use server\'` directive at the top must also have the `.server.{js,ts,mts,mjs}` extension. The two markers are complementary, not interchangeable: `.server.ts` is the path-level boundary that triggers source protection by the file router; `\'use server\'` is the semantic opt-in that registers exports as RPC-callable from client code. A `\'use server\'` directive without the extension is silently ignored: the file is served to the browser as plain source, exports are NOT registered as RPC, and code the developer expects to run on the server actually runs in the browser. Rename the file to add the `.server.` infix.',
+  },
+  {
+    name: 'use-server-exports-callable',
+    description:
+      'A `.server.{js,ts}` file that declares the `\'use server\'` directive registers its function exports as RPC-callable server actions, but only its FUNCTION exports: `buildActionIndex` / the stub generator register an export only when `typeof export === \'function\'`, so a `\'use server\'` file that exports zero functions (or only a non-function `const` / a type / only verb config like `method` / `cache`) registers NOTHING and gives no signal. The developer believes they exposed an action; nothing did, and the failure only surfaces as a 404 / undefined at the first call site. This is the complement of `use-server-needs-extension` (the directive without the extension) and of `one-action-per-configured-file` (more than one action in a configured file); this rule catches the directive-present-but-nothing-callable case. The rule asserts only that the file exports at least one callable, NOT that the action returns a value (a server action may be a void side-effect or throw `redirect()` / `notFound()` and never return). Conservative: a re-export (`export ... from`, `export *`) or an `export const NAME = <identifier-or-call>` (a possible factory-produced function such as `export const get = cache(fetch)`) is treated as a possible callable and NOT flagged, so the rule fires only when every export is provably non-callable. Fix: export an `async function` action, or drop the `\'use server\'` directive if the file is a plain server-only utility.',
+  },
+  {
+    name: 'no-non-erasable-typescript',
+    description:
+      '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: 'no-browser-globals-in-render',
+    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).',
+  },
+  {
+    name: 'no-shadowed-native-member',
+    description:
+      'Flags a WebComponent class method whose name collides with a native DOM mutation method that WebJs relies on and INSTRUMENTS on every light-DOM host for the slot API (#1021): append, prepend, before, after, replaceWith, replaceChildren, remove, appendChild, insertBefore, removeChild, replaceChild. A method of the same name is SHADOWED at runtime (the instrumented native method wins), so the component method silently never runs, while TypeScript stays green because a zero/one-arg override is assignable to the native signature. Found dogfooding the stream demo (#248): a component named its button handler `append()`, so clicking Append called the slot-append no-op instead of the handler. Rename the handler to a non-native name (appendRow / prependRow / removeItem). The `render` / lifecycle hooks are MEANT to be overridden and are not flagged; only the native DOM mutation members are.',
+  },
+  {
+    name: 'no-server-import-in-browser-module',
+    description:
+      '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 module never loads client-side: a display-only page is elided, and a page whose only client relevance is importing shipping components is import-only (#605/#963), dropped from the boot in favour of its components. But the moment the page does its OWN client work (the client router, a reactive primitive, a module-scope browser-global access, a client-effecting non-component util) it ships whole, 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; an elided, inert, or import-only page 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 move the module\'s own client work into a component so the page is dropped again. Server-to-server imports (`.server.ts` importing `.server.ts`) and `middleware.ts` / `route.ts` (never shipped) are never flagged.',
+  },
+  {
+    name: 'one-action-per-configured-file',
+    description:
+      'A `\'use server\'` action file that declares HTTP-verb config (any of `method` / `cache` / `tags` / `invalidates` / `validate`, #488) must export exactly ONE callable action function. The config is file-level (it applies to the action in the file), so a second exported function would silently inherit the same verb / cache, which is almost never intended and makes the contract ambiguous. Move the extra function to its own `.server.ts` file (the one-function-per-file convention), or, if it is a private helper, do not export it. Files with no verb config are unaffected.',
+  },
+  {
+    name: 'form-action-not-a-get-action',
+    description:
+      'Flags `<form action=${someAction}>` bound to a `\'use server\'` action whose file declares `export const method = \'GET\'` (#488). A GET action is a READ: it is CSRF-exempt and rides its arguments in the url, while a form submission is a CSRF-checked POST carrying a body, so the two contracts contradict each other and the submission is answered with a 405 at runtime. The rule reads the imported action\'s own file, so it only fires when the binding really does resolve to a GET-declared action. Fix by dropping the `method` export (an action with no `method` is a POST, which is what a form wants) or by binding a different action; if the form really is a read, use a plain `<form method="get" action="/search">` with no bound action.',
+  },
+  {
+    name: 'no-redirect-in-api-route',
+    description:
+      'API route handlers (`route.{js,ts}`) must NOT call `redirect()` from `@webjsdev/core`. That function throws a control-flow signal designed for the SSR page renderer; in a route handler it goes uncaught and produces a 500. Use `Response.redirect(url, 303)` for external redirects or return a 3xx Response directly. Page functions, layouts, and server actions may still use `redirect()` (caught by the SSR pipeline).',
+  },
+  {
+    name: 'no-interpolation-in-raw-text-element',
+    description:
+      'Flags a template interpolation (`${...}`) placed as a child of a `<style>` or `<script>` element inside a COMPONENT `html` template. Raw-text elements are an SSR/client asymmetry trap: the server renderer emits the interpolated content, but the client renderer drops it (a raw-text hole is a `noop`, since the compile cache is keyed on the static strings), so the element renders correctly on the server and then wipes to empty on hydration. Scoped to components (files with a `WebComponent` class), which hydrate; pages and layouts render server-only and never hydrate, so a page interpolating a `css` result into a `<style>` is a legitimate pattern and is not flagged. In a component, author scoped CSS with `static styles` (shadow DOM) or a `css` template. Found dogfooding a tic-tac-toe app (#845): a `<style>${STYLE}</style>` painted at SSR then vanished on hydrate.',
+  },
+  {
+    name: 'no-missing-local-import',
+    description:
+      'Flags a NAMED value import of a symbol that a resolvable app-internal module does not export (`import { todos } from \'#db/schema.server.ts\'` when the schema no longer exports `todos`). The binding is `undefined` at runtime and crashes on first use, yet the rest of `webjs check` (elision-based, it does not compile types) misses it, so a schema swap that orphans a gallery module can pass `check` while `typecheck` is red. This is the runtime-crash class `check` exists to catch, filling that gap so an agent running only `check` cannot ship a broken import. Deliberately conservative to never false-positive on a valid app: it only inspects app-internal specifiers (a relative `./` path or a `#` alias) that resolve to a file in the app, only NAMED value imports (a `type` import, a default import, a namespace import, and any bare / `node:` / npm-package specifier are skipped), and it treats a module as UNKNOWABLE (never flags imports from it) when its exports are not fully enumerable: a `export * from ...` star re-export, a destructuring `export const { a } = ...`, or a multi-declarator `export const a = .., b = ..`. It reads names from `export function/class/const/let/var/type/interface/enum` and from `export { a, b as c }` / `export { x } from ...` clauses (the alias after `as` is the exported name). A re-export barrel therefore resolves correctly, and a `\'use server\'` action file exports its function names normally. Found dogfooding a tic-tac-toe app: dropping the example `todos` table left a gallery module importing it, green under `check` but red under `typecheck`.',
+  },
+];
+
+/** Set of all known rule names for fast lookup. */
+export const RULE_NAMES = new Set(RULES.map((r) => r.name));

package/src/check/runner-support.js

@@ -0,0 +1,405 @@
+/**
+ * Shared machinery behind the check rules: the module-graph walk for the
+ * server-import rule, the git-ignore probe, and the small fs predicates.
+ *
+ * Its own module rather than private to runner.js, because the rules call it
+ * and runner.js calls the rules. Parked in runner.js it made that a cycle.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { join, relative, basename } from 'node:path';
+import { walk } from '../fs-walk.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';
+import {
+  hasUseServerDirective,
+} from './helpers.js';
+
+/**
+ * @typedef {import('./rules.js').Violation} Violation
+ * @typedef {{ abs: string, rel: string, content: string, scan: string }} ScannedFile
+ */
+
+/**
+ * BFS the module graph for the shortest import path from `from` to `to`,
+ * returning every hop `[from, ..., to]` so the `no-server-import-in-browser-module`
+ * message can print the FULL chain instead of an opaque `… ->` truncation (#804).
+ * Falls back to `[from, to]` if no path is found (defensive; the caller only
+ * calls this once `to` is known reachable).
+ *
+ * @param {Map<string, Set<string>>} graph
+ * @param {string} from
+ * @param {string} to
+ * @returns {string[]}
+ */
+export function findImportChain(graph, from, to) {
+  const prev = new Map();
+  const seen = new Set([from]);
+  const queue = [from];
+  while (queue.length) {
+    const cur = queue.shift();
+    const deps = graph.get(cur);
+    if (!deps) continue;
+    for (const dep of deps) {
+      if (seen.has(dep)) continue;
+      seen.add(dep);
+      prev.set(dep, cur);
+      if (dep === to) {
+        const path = [];
+        for (let n = to; n !== undefined; n = prev.get(n)) path.unshift(n);
+        return path;
+      }
+      queue.push(dep);
+    }
+  }
+  return [from, to];
+}
+
+/**
+ * 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).
+ *
+ * Scope note for dynamic imports: a string-literal `import('./widget.ts')` IS
+ * tracked by the module graph now (#751), but only as a GATE edge (so the
+ * lazily-imported module is servable); this rule's server-import detection
+ * still runs over STATIC edges only (`transitiveDeps`), so a dynamic
+ * `import('./x.server.ts')` of a no-`'use server'` utility is not flagged here.
+ * That is deliberate: the throw-at-load crash is deferred to call time (when
+ * the module is actually fetched), not module load, and a dynamic import is
+ * also not elided framework-wide. A computed `import(expr)` cannot be resolved
+ * statically at all; rather than a false-positive-prone check rule (a computed
+ * import of an npm specifier or an otherwise-reachable app module is perfectly
+ * valid, so it fails the check-is-correctness-only dividing line), the dev
+ * server surfaces it with a 404 hint when the target 404s (see dev.js #751).
+ *
+ * @param {string} appDir
+ * @param {Violation[]} violations  appended to in place
+ */
+// --- 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
+// module never loads client-side: a display-only page is elided, and an
+// import-only page (#605/#963) is dropped from the boot in favour of its
+// components. But the moment the page does its OWN client work (the client
+// router, a reactive primitive, module-scope code, a client-effecting util
+// on a component-free path) it ships whole, 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.
+export 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');
+    // forbidden / unauthorized joined this set with #1298. They used to render
+    // with an empty boot set, so their modules never reached the browser and
+    // omitting them here was harmless. They now render inside their layout
+    // chain AND ship, so a `forbidden.ts` doing `import { auth } from
+    // '#lib/auth.server.ts'` (a natural thing on a 403: "signed in as X, but
+    // not permitted") is a real throw-at-load crash that takes every sibling
+    // registration in the same module script with it.
+    for (const f of page.forbiddens || []) alwaysShipRouteModules.set(f, 'forbidden boundary');
+    for (const f of page.unauthorizeds || []) alwaysShipRouteModules.set(f, 'unauthorized 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');
+    }
+  }
+  // global-not-found ships for the same reason: a thrown notFound() with no
+  // nearer boundary renders it against the matched route, so it wraps and
+  // boots. global-ERROR is deliberately absent: it returns its own document
+  // verbatim with no importmap and no boot script, so nothing of it ever
+  // reaches the browser.
+  if (routeTable.globalNotFound) {
+    alwaysShipRouteModules.set(routeTable.globalNotFound, 'global-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, importOnlyRouteModules } = elideEnabled
+    ? await analyzeElision(components, routeModules, moduleGraph, (f) => readFile(f, 'utf8'), appDir)
+    : { elidableComponents: new Set(), inertRouteModules: new Set(), importOnlyRouteModules: new Map() };
+
+  // Candidate browser-shipped modules: components that are NOT elided, plus
+  // route modules that are NOT inert and NOT import-only (an import-only
+  // module is dropped from the boot in favour of its component frontier,
+  // #605/#963, so its own imports never load in a browser and a bare
+  // server-only import in it is harmless). 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) || importOnlyRouteModules.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 chainFiles = findImportChain(moduleGraph, file, serverDep);
+    const chain = chainFiles.map((f) => relative(appDir, f)).join(' -> ');
+    // If the edge into the server file comes from a types-shaped module, the
+    // idiomatic fix is to relocate that type to a browser-safe typedef (#804).
+    const importer = chainFiles.length >= 2 ? chainFiles[chainFiles.length - 2] : null;
+    const viaTypesModule = importer && /(^|\/)types(\.m?[jt]s$|\/)/.test(relative(appDir, importer));
+
+    // The "elides again" remedy only applies to a page / layout: since the
+    // path-aware import-only verdict (#963), a page importing a component to
+    // register is dropped from the boot, so a page/layout on this rule ships
+    // because of its OWN client work (or a client-effecting non-component in
+    // its closure); moving that work into a component makes it a dropped
+    // carrier again and the server import never loads. 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 kind.
+    const canElide = kind === 'page' || kind === 'layout';
+    const typesHint = viaTypesModule
+      ? `The edge enters via a types-shaped module (${relative(appDir, importer)}); if it re-exports a runtime VALUE from a \`.server.{ts,js}\` file, relocate that to a browser-safe typedef (a plain \`interface\` / JSDoc, or an \`import type\` which the stripper erases) so the type is shared without pinning the module. `
+      : '';
+    const fixText = canElide
+      ? `${typesHint}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) move this ${kind}'s own client work (the module-scope call, browser-global access, or client-effecting util import that pins it) into a component, so the ${kind} elides again as a dropped carrier and its server import never loads.`
+      : `${typesHint}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>}
+ */
+export async function isUseServerActionFile(file) {
+  try {
+    const content = await readFile(file, 'utf8');
+    return hasUseServerDirective(content);
+  } catch {
+    return false;
+  }
+}
+
+export 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.
+ *
+ * @param {string} p absolute path
+ * @returns {Promise<boolean>}
+ */
+export async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    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>>}
+ */
+export 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/check/runner.js

@@ -0,0 +1,113 @@
+import { readFile } from 'node:fs/promises';
+import { relative } from 'node:path';
+import { walk } from '../fs-walk.js';
+import {
+  redactStringsAndTemplates,
+} from '../js-scan.js';
+import {
+  checkComponentsHaveRegister,
+  checkNoStaticProperties,
+  checkReactivePropsNoClassField,
+  checkArrayPropUsesArrayType,
+  checkNoBrowserGlobalsInRender,
+  checkNoShadowedNativeMember,
+} from './rules-components.js';
+import {
+  checkNoRedirectInApiRoute,
+  checkNoInterpolationInRawTextElement,
+  checkNoServerEnvInComponents,
+  checkShellInNonRootLayout,
+} from './rules-routing.js';
+import {
+  checkErasableTypescriptOnly,
+  checkNoNonErasableTypescript,
+} from './rules-typescript.js';
+import {
+  checkUseServerNeedsExtension,
+  checkUseServerExportsCallable,
+  checkOneActionPerConfiguredFile,
+} from './rules-actions.js';
+import {
+  checkTagNameHasHyphen,
+  checkNoDuplicateTag,
+} from './rules-registry.js';
+import { checkServerImportInBrowserModule } from './runner-support.js';
+import {
+  checkNoMissingLocalImport,
+  checkFormActionNotAGetAction,
+} from './rules-imports.js';
+
+/**
+ * @typedef {import('./rules.js').Violation} Violation
+ */
+
+/**
+ * Scan a WebJs app directory and report convention violations.
+ *
+ * Every rule is a correctness check (a crash, a security leak, a reactive
+ * prop that silently stops re-rendering, or a build/type-strip failure), so
+ * they all run unconditionally. There is no
+ * per-project disabling: project conventions (layout, style, process) live in
+ * CONVENTIONS.md as guidance, not in this tool.
+ *
+ * @param {string} appDir  absolute path to the app root (the directory
+ *   containing `app/`, `modules/`, `components/`, etc.)
+ * @returns {Promise<Violation[]>}
+ *
+ * @example
+ * ```js
+ * import { checkConventions } from '@webjsdev/server';
+ * const violations = await checkConventions('/path/to/myapp');
+ * for (const v of violations) {
+ *   console.warn(`[${v.rule}] ${v.file}: ${v.message}`);
+ * }
+ * ```
+ */
+export async function checkConventions(appDir) {
+  /** @type {Violation[]} */
+  const violations = [];
+
+  // Collect all JS/TS files in the app directory. Each entry carries
+  // both the raw `content` (for rules that need verbatim source: the
+  // `'use server'` directive detector, the `.gitignore` reader, etc.)
+  // and a `scan` view with comments, string contents, and
+  // template-literal bodies redacted to whitespace. Rules that
+  // pattern-match across raw source should consume `scan` so docs-
+  // page code-block examples and JSDoc samples don't trigger false
+  // positives.
+  /** @type {{ abs: string, rel: string, content: string, scan: string }[]} */
+  const files = [];
+  for await (const abs of walk(appDir, (p) => /\.m?[jt]sx?$/.test(p))) {
+    const rel = relative(appDir, abs);
+    let content;
+    try {
+      content = await readFile(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    files.push({ abs, rel, content, scan: redactStringsAndTemplates(content) });
+  }
+
+  checkComponentsHaveRegister(files, violations);
+  checkNoStaticProperties(files, violations);
+  checkReactivePropsNoClassField(files, violations);
+  checkArrayPropUsesArrayType(files, violations);
+  checkNoBrowserGlobalsInRender(files, violations);
+  checkNoShadowedNativeMember(files, violations);
+  checkNoRedirectInApiRoute(files, violations);
+  checkNoInterpolationInRawTextElement(files, violations);
+  checkNoServerEnvInComponents(files, violations);
+  checkShellInNonRootLayout(files, violations);
+  await checkErasableTypescriptOnly(appDir, violations);
+  await checkNoNonErasableTypescript(appDir, violations);
+  checkUseServerNeedsExtension(files, violations);
+  checkUseServerExportsCallable(files, violations);
+  checkOneActionPerConfiguredFile(files, violations);
+  checkTagNameHasHyphen(files, violations);
+  await checkNoDuplicateTag(appDir, files, violations);
+  await checkServerImportInBrowserModule(appDir, violations);
+  checkNoMissingLocalImport(appDir, files, violations);
+  checkFormActionNotAGetAction(appDir, files, violations);
+
+  return violations;
+}