@webjsdev/server 0.9.0 → 0.10.0

package/src/check/rules-route-modules.js

@@ -0,0 +1,200 @@
+/**
+ * Rules for the line between server-only route modules and browser code
+ * (#1686). A page, layout or boundary runs only on the server, like a Next.js
+ * server component, and never loads in a browser. These rules refuse the
+ * shapes that would fail silently because of it: a component defined in a
+ * route file (its tag never upgrades), an event binding in a route template
+ * (its handler never runs), a browser module importing a route file (the
+ * import 404s), and a Node builtin reached from browser code (it can never
+ * resolve there).
+ *
+ * @module
+ */
+import { builtinModules } from 'node:module';
+import { relative } from 'node:path';
+
+import { maskComments, redactToPlaceholders } from '../js-scan.js';
+import { hasUseServerDirective } from './helpers.js';
+import { EVENT_BINDING_RE, REACTIVE_IMPORTS, extractRenderedTags } from '../client-signals.js';
+
+/**
+ * @typedef {import('./rules.js').Violation} Violation
+ * @typedef {{ abs: string, rel: string, content: string, scan: string }} ScannedFile
+ */
+
+const BUILTINS = new Set(builtinModules);
+const SERVER_FILE_RE = /\.server\.m?[jt]s$/;
+/** A registration with a literal tag: `X.register('tag')` or `customElements.define('tag', X)`. */
+const REGISTER_RE = /(?:\.register|customElements\.define)\(\s*(['"])([a-z][a-z0-9]*-[a-z0-9-]*)\1/g;
+/** Lifecycle hooks that only ever run in a browser (`willUpdate` also runs during SSR, so it is not here). */
+const CLIENT_ONLY_HOOKS = ['connectedCallback', 'disconnectedCallback', 'attributeChangedCallback', 'adoptedCallback',
+  'firstUpdated', 'updated', 'renderFallback', 'scheduleUpdate', 'performUpdate'];
+const HOOK_RE = new RegExp(`^\\s*(?:async\\s+)?(${CLIENT_ONLY_HOOKS.join('|')})\\s*\\(`, 'm');
+/** A named import of a reactive primitive from core: `import { signal } from '@webjsdev/core'`. */
+const CORE_NAMED_IMPORT_RE = /import\s*\{([^}]*)\}\s*from\s*['"]@webjsdev\/core(?:\/[a-z-]+)?['"]/g;
+/** A `'use client'` directive in a module's prologue (comments and blank lines may precede it). */
+const USE_CLIENT_RE = /^(?:\s*(?:\/\/[^\n]*|\/\*[\s\S]*?\*\/))*\s*(['"])use client\1\s*;?/;
+const IMPORT_RE = /(?:^|[;\n])\s*(?:import|export)\s+(type\s+)?(?:[^'"`;]*?\s+from\s+)?['"]__STR_(\d+)__['"]/g;
+
+/**
+ * The first event binding that sits inside a real open tag. A binding written
+ * as escaped text (`<button @click=...`, a docs sample) is not one: the
+ * nearest `<` before it must open a tag, with no `>` in between.
+ * @param {string} src
+ * @returns {{ index: number, text: string } | null}
+ */
+function firstTagBinding(src) {
+  const re = new RegExp(EVENT_BINDING_RE.source, 'g');
+  for (const m of src.matchAll(re)) {
+    const lt = src.lastIndexOf('<', m.index);
+    if (lt === -1 || src.lastIndexOf('>', m.index) > lt) continue;
+    if (!/[A-Za-z]/.test(src[lt + 1] || '')) continue;
+    return { index: /** @type {number} */ (m.index), text: m[0] };
+  }
+  return null;
+}
+
+/** 1-based line of `index` in `src`. */
+const lineOf = (src, index) => src.slice(0, index).split('\n').length;
+
+/**
+ * @param {string} appDir
+ * @param {ScannedFile[]} files
+ * @param {Violation[]} violations
+ * @param {{ routeFiles: Set<string>, componentFiles: Set<string>, moduleGraph: Map<string, Set<string>>, shipped: Set<string> }} ctx
+ */
+export function checkRouteModuleBoundaries(appDir, files, violations, ctx) {
+  const { routeFiles, componentFiles, moduleGraph, shipped } = ctx;
+  // Tags registered by components in `*.server.*` files: rendered on the
+  // server, never defined in the browser (#1686).
+  /** @type {Map<string, string>} tag -> the file that registers it */
+  const serverTags = new Map();
+  for (const { rel, content } of files) {
+    if (!SERVER_FILE_RE.test(rel) || !/extends\s+WebComponent\b/.test(content)) continue;
+    // --- no-component-in-use-server-file ---
+    // Every function export of a `'use server'` file is wrapped as an action
+    // (a class is a function), so a component there is neither a component
+    // nor a usable action.
+    if (hasUseServerDirective(content)) {
+      violations.push({
+        rule: 'no-component-in-use-server-file',
+        file: rel,
+        message: "This `'use server'` file defines a component. Every function export of a `'use server'` file is wrapped as a server action, and a class is a function, so the component is neither a working component nor a usable action.",
+        fix: "Drop `'use server'` to make it a server-only component (a component in a `.server` file without the directive renders on the server and ships nothing), or move the class to an ordinary file to make it a component that runs in the browser. Keep the actions in their own `'use server'` file.",
+      });
+      continue;
+    }
+    for (const m of maskComments(content).matchAll(REGISTER_RE)) serverTags.set(m[2], rel);
+    checkServerComponent(rel, content, violations);
+  }
+  for (const { abs, rel, content } of files) {
+    if (routeFiles.has(abs)) {
+      // --- no-use-client-in-route-module ---
+      // The Next.js way to make a page interactive. In WebJs the client part
+      // is a component (Lit's APIs), so the directive maps to one message
+      // rather than a page model neither habit predicts. In a component file
+      // the directive is true already and is left alone.
+      if (USE_CLIENT_RE.test(content)) {
+        violations.push({
+          rule: 'no-use-client-in-route-module',
+          file: rel,
+          message: "`'use client'` marks this page, layout or boundary as client code, the Next.js way. In WebJs a route module is always a server component and the client part of a page is a component, so the directive does nothing here.",
+          fix: "Move the interactive part into a component in its own file (`components/my-widget.ts`, a `WebComponent` using Lit's APIs: reactive properties, `@click`, the lifecycle), render its tag from this page, and drop `'use client'`. Pass server data in as properties.",
+        });
+      }
+      // --- no-component-in-route-module ---
+      if (componentFiles.has(abs)) {
+        violations.push({
+          rule: 'no-component-in-route-module',
+          file: rel,
+          message: 'This page, layout or boundary defines a component. A route module runs only on the server and never loads in the browser, so the element renders its server markup and never upgrades.',
+          fix: 'Move the component class into its own file (for example `components/my-widget.ts`) and import that file here.',
+        });
+      }
+      // --- no-event-binding-in-route-module ---
+      const masked = maskComments(content);
+      const m = firstTagBinding(masked);
+      if (m) {
+        const binding = m.text.replace(/\s*=.*$/, '');
+        violations.push({
+          rule: 'no-event-binding-in-route-module',
+          file: rel,
+          message: `\`${binding}\` (line ${lineOf(masked, m.index)}) is bound in a page, layout or boundary template. A route module renders only on the server and never hydrates, so the handler never runs (the same reason Next.js refuses an event handler in a server component).`,
+          fix: 'Put the interactive part in a component and render its tag here, or use a plain `<form action=${action}>` / `<a href>` that works without JavaScript.',
+        });
+      }
+    }
+    if (!shipped.has(abs) || routeFiles.has(abs)) continue;
+    // --- no-server-component-in-client-template ---
+    if (serverTags.size) {
+      for (const tag of extractRenderedTags(content)) {
+        const owner = serverTags.get(tag);
+        if (!owner) continue;
+        violations.push({
+          rule: 'no-server-component-in-client-template',
+          file: rel,
+          message: `This module loads in the browser and renders <${tag}>, a server-only component (${owner}). It is never defined in the browser, so it renders on the server and comes back empty after a client re-render, the reason Next.js does not let a client component render a server component.`,
+          fix: `Render <${tag}> from the page and pass it into this component as a child (it lands in the component's <slot>), as Next.js passes a server component to a client one as children. Or, if it needs to run in the browser, move it out of the .server file.`,
+        });
+        break;
+      }
+    }
+    // --- no-route-module-import-in-browser-module ---
+    for (const dep of moduleGraph.get(abs) || []) {
+      if (!routeFiles.has(dep)) continue;
+      violations.push({
+        rule: 'no-route-module-import-in-browser-module',
+        file: rel,
+        message: `This module loads in the browser but imports the route module ${relative(appDir, dep)}. Pages, layouts and boundaries run only on the server, so the import 404s in the browser and this module fails to load.`,
+        fix: 'Move what you need from the route module into a shared file (a helper under `lib/`, or a component) and import that from both.',
+      });
+      break;
+    }
+    // --- no-node-builtin-in-browser-module ---
+    const { redacted, literals } = redactToPlaceholders(content);
+    for (const im of redacted.matchAll(IMPORT_RE)) {
+      if (im[1]) continue; // `import type` is erased
+      const spec = literals[Number(im[2])];
+      if (!spec || !(spec.startsWith('node:') || BUILTINS.has(spec))) continue;
+      violations.push({
+        rule: 'no-node-builtin-in-browser-module',
+        file: rel,
+        message: `This module loads in the browser but imports \`${spec}\` (line ${lineOf(redacted, im.index + (im[0].length - im[0].trimStart().length))}), a Node builtin that cannot resolve there, so the module fails to load.`,
+        fix: 'Do the work on the server: read it in the page (pages run only on the server) and pass the result in as a property, or put it behind a `\'use server\'` action in a `.server.ts` file.',
+      });
+      break;
+    }
+  }
+}
+
+/**
+ * `no-interactivity-in-server-component`: a component in a `*.server.*` file
+ * renders on the server only and is never defined in the browser (#1686), so
+ * an event binding, a reactive primitive or a client-only lifecycle hook in it
+ * never runs.
+ * @param {string} rel @param {string} content @param {Violation[]} violations
+ */
+function checkServerComponent(rel, content, violations) {
+  const masked = maskComments(content);
+  /** @type {string|null} */
+  let what = null;
+  const binding = firstTagBinding(masked);
+  if (binding) what = `\`${binding.text.replace(/\s*=.*$/, '')}\` (line ${lineOf(masked, binding.index)})`;
+  if (!what) {
+    for (const m of masked.matchAll(CORE_NAMED_IMPORT_RE)) {
+      const name = m[1].split(',').map((x) => x.trim().split(/\s+as\s+/)[0].replace(/^type\s+/, '')).find((x) => REACTIVE_IMPORTS.has(x));
+      if (name) { what = `\`${name}\``; break; }
+    }
+  }
+  if (!what) {
+    const hook = HOOK_RE.exec(masked);
+    if (hook) what = `\`${hook[1]}()\``;
+  }
+  if (!what) return;
+  violations.push({
+    rule: 'no-interactivity-in-server-component',
+    file: rel,
+    message: `This component is in a \`.server\` file, so it renders on the server only and is never defined in the browser, but it uses ${what}, which only runs in a browser.`,
+    fix: 'Move the component out of the `.server` file (a component in an ordinary file always ships and runs in the browser), and keep its server data access in a `\'use server\'` action or pass the data in from the page.',
+  });
+}

package/src/check/rules-routes.js

@@ -0,0 +1,55 @@
+/**
+ * Rule: `no-conflicting-routes` (#1686). Two files that resolve to ONE url, the
+ * two conflicts Next.js fails the build on:
+ *
+ *   - two pages, typically in different route groups (`app/(marketing)/page.ts`
+ *     and `app/(app)/page.ts` both serve `/`), or the same dynamic position
+ *     spelled with different param names (`[id]` beside `[slug]`);
+ *   - a `page` and a `route` handler at the same url.
+ *
+ * WebJs used to accept either silently and serve whichever the matcher met
+ * first, so one of the two files was dead code that looked live.
+ *
+ * @module
+ */
+import { relative, sep } from 'node:path';
+import { buildRouteTable } from '../router.js';
+
+/**
+ * @param {string} appDir
+ * @param {import('./rules.js').Violation[]} violations
+ */
+export async function checkNoConflictingRoutes(appDir, violations) {
+  let table;
+  try { table = await buildRouteTable(appDir); } catch { return; }
+  const rel = (f) => relative(appDir, f).split(sep).join('/');
+  /** @type {Map<string, string[]>} url pattern -> page files */
+  const pages = new Map();
+  for (const p of table.pages || []) {
+    const key = p.pattern.source;
+    if (!pages.has(key)) pages.set(key, []);
+    pages.get(key).push(rel(p.file));
+  }
+  for (const files of pages.values()) {
+    if (files.length < 2) continue;
+    const [first, ...rest] = files.sort();
+    for (const file of rest) {
+      violations.push({
+        rule: 'no-conflicting-routes',
+        file,
+        message: `This page resolves to the same URL as ${first} (route groups and param names do not change a URL), so only one of them can ever be served. Next.js refuses this at build time.`,
+        fix: 'Give one of the pages a different path, merge the two, or, for a dynamic segment, use one param name at that position.',
+      });
+    }
+  }
+  for (const api of table.apis || []) {
+    const page = pages.get(api.pattern.source);
+    if (!page) continue;
+    violations.push({
+      rule: 'no-conflicting-routes',
+      file: rel(api.file),
+      message: `This route handler shares its URL with the page ${page[0]}, so one of them is never reached. Next.js refuses a page and a route at the same path.`,
+      fix: 'Move the handler under app/api/ (or another path no page uses), or turn the page into the handler.',
+    });
+  }
+}

package/src/check/rules-routing.js

@@ -1,5 +1,5 @@
 /**
- * Routing and template rules: what a route handler may throw, what a non-root
+ * Routing and template rules: what a non-root
  * layout may emit, and which holes a template may carry.
  *
  * Lifted verbatim out of checkConventions, which held all twenty rules inline
@@ -9,83 +9,63 @@
 import {
   isServerActionFile, isComponentFile,
 } from './helpers.js';
+import { buildRouteTable } from '../router.js';
+import { maskComments, redactStringsAndTemplates } from '../js-scan.js';
+import { validateAppLayout } from '../app-layout.js';
+import { buildPublicIndex } from '../public-files.js';
+import { findJsxIsm } from '@webjsdev/core/server';
+import { htmlTemplateStrings } from '../dev-source-locations.js';
 
 /**
- * @typedef {import('./rules.js').Violation} Violation
- * @typedef {{ abs: string, rel: string, content: string, scan: string }} ScannedFile
+ * Rule: `no-jsx-attributes`.
+ *
+ * `className=`, `htmlFor=`, or a capitalised component tag (`<Link>`) in an
+ * `html` template: JSX that HTML silently ignores. Both renderers refuse it
+ * when the template first compiles; this reports it ahead of time, with the
+ * line the template starts on.
+ *
+ * @param {ScannedFile[]} files
+ * @param {import('./rules.js').Violation[]} violations
  */
-
+export function checkNoJsxAttributes(files, violations) {
+  for (const { rel, content } of files) {
+    for (const t of htmlTemplateStrings(content)) {
+      const ism = findJsxIsm(t.strings);
+      if (!ism) continue;
+      violations.push({
+        rule: 'no-jsx-attributes',
+        file: rel,
+        message: ism.kind === 'attr'
+          ? `The html template at line ${t.line} uses \`${ism.name}=\`, a JSX spelling HTML reads as an unknown attribute, so it does nothing (the render throws).`
+          : `The html template at line ${t.line} uses \`<${ism.name}>\`, a JSX component HTML lowercases into an unknown element (the render throws).`,
+        fix: ism.kind === 'attr'
+          ? `Write \`${ism.name === 'className' ? 'class' : 'for'}=\` instead.`
+          : `Render the custom element's registered tag (with a hyphen, such as \`<my-${ism.name.toLowerCase()}>\`), or a plain element such as \`<a href>\` for a link.`,
+      });
+    }
+  }
+}
 
 /**
- * Rule: `no-redirect-in-api-route`.
+ * Rules fed by the route table: `no-page-route-conflict` and the other file
+ * arrangements `validateAppLayout` refuses at boot. The check reports exactly
+ * what boot would refuse, so a clean `webjs check` means a clean boot.
  *
- * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
- * @param {Violation[]} violations  accumulator the rule pushes onto
- * @returns {void}
+ * @param {string} appDir
+ * @param {import('./rules.js').Violation[]} violations
  */
-export function checkNoRedirectInApiRoute(files, violations) {
-  // --- Rule: no-redirect-in-api-route ---
-  // `redirect()` from `@webjsdev/core` throws a control-flow signal designed
-  // for the SSR page renderer. In a `route.ts` API handler it goes uncaught
-  // and produces a 500. API handlers must use `Response.redirect(url, 303)`
-  // instead. Page functions, layouts, and server actions may still use
-  // `redirect()` (caught by the SSR / action pipeline).
-  {
-    const ROUTE_FILE = /(?:^|\/)route\.m?[jt]s$/;
-    for (const { rel, scan } of files) {
-      if (!ROUTE_FILE.test(rel)) continue;
-      // `redirect` reaches the route file in one of two statically-visible ways:
-      //   1. A NAMED import from `@webjsdev/core` (possibly aliased):
-      //      `import { redirect }`, `import { redirect as r }`, `import { …, redirect, … }`.
-      //   2. A NAMESPACE import then a member call:
-      //      `import * as core from '@webjsdev/core'` then `core.redirect(...)`.
-      // The named case flags a bare `redirect(` call; the namespace case flags
-      // `<ns>.redirect(`. `Response.redirect(` and any other `obj.redirect(` are
-      // the standard API and stay fine. A `redirect()` thrown inside a
-      // '`use server`' action the route calls DIRECTLY (an uncaught 500) needs
-      // cross-file analysis and is left to the AST rework (#753).
-      const namedM = /\bimport\s+\{[^}]*\bredirect\b(?:\s+as\s+(\w+))?\s*[^}]*\}\s+from\s+['"]@webjsdev\/core['"]/.exec(scan);
-      const nsM = /\bimport\s+\*\s+as\s+(\w+)\s+from\s+['"]@webjsdev\/core['"]/.exec(scan);
-      // A file can carry BOTH a named `redirect` import AND a namespace import,
-      // so check every matcher independently (not mutually exclusive): a named
-      // import means a bare `<localName>(`, a namespace import means
-      // `<ns>.redirect(`. The `member` flag distinguishes the two so a bare
-      // named call can screen out `Response.redirect(` / `obj.redirect(`.
-      /** @type {Array<{ re: RegExp, member: boolean }>} */
-      const matchers = [];
-      if (namedM) {
-        const localName = namedM[1] || 'redirect';
-        matchers.push({ re: new RegExp(`(?<!\\.)\\b${localName}\\s*\\(`, 'g'), member: false });
-      }
-      if (nsM) {
-        matchers.push({ re: new RegExp(`\\b${nsM[1]}\\.redirect\\s*\\(`, 'g'), member: true });
-      }
-      let flagged = false;
-      for (const { re, member } of matchers) {
-        if (flagged) break;
-        let m;
-        while ((m = re.exec(scan)) !== null) {
-          if (!member) {
-            // Screen out `Response.redirect(` / `someObj.redirect(` sharing the
-            // local name: a preceding member-access dot means it is not the import.
-            const before = scan.slice(Math.max(0, m.index - 20), m.index);
-            if (/\w\.$/.test(before)) continue;
-          }
-          violations.push({
-            rule: 'no-redirect-in-api-route',
-            file: rel,
-            message:
-              `\`redirect()\` from \`@webjsdev/core\` throws a control-flow signal for the SSR page renderer; in a \`route.ts\` handler it goes uncaught and returns a 500.`,
-            fix: `Use \`Response.redirect(url, 303)\` for external redirects, or return a 3xx Response directly. The \`redirect()\` sentinel is only valid in page functions, layouts, and server actions (where the SSR pipeline catches it).`,
-          });
-          flagged = true; // one violation per file is enough
-          break;
-        }
-      }
-    }
-  }
+export async function checkAppLayout(appDir, violations) {
+  let table;
+  try { table = await buildRouteTable(appDir); } catch { return; }
+  for (const p of validateAppLayout(appDir, table, buildPublicIndex(appDir))) violations.push(p);
 }
 
+/**
+ * @typedef {import('./rules.js').Violation} Violation
+ * @typedef {{ abs: string, rel: string, content: string, scan: string }} ScannedFile
+ */
+
+
 /**
  * Rule: `no-interpolation-in-raw-text-element`.
  *
@@ -146,37 +126,105 @@ export function checkNoInterpolationInRawTextElement(files, violations) {
  * @param {Violation[]} violations  accumulator the rule pushes onto
  * @returns {void}
  */
-export function checkNoServerEnvInComponents(files, violations) {
+export function checkNoServerEnvInComponents(files, violations, shipped = new Set(), routeFiles = new Set()) {
   // --- Rule: no-server-env-in-components ---
-  // Catches `process.env.X` reads in component files where X is not a
-  // WEBJS_PUBLIC_* var and not NODE_ENV. The SSR shim only exposes those
-  // two categories to the browser; any other read either leaks a secret
-  // into the SSR'd HTML or reads as undefined after hydration.
-  {
-    for (const { abs, rel, content } of files) {
-      if (!isComponentFile(rel)) continue;
-      if (isServerActionFile(abs, content)) continue;
-
-      const re = /\bprocess\.env\.([A-Z][A-Z0-9_]*)\b/g;
-      const seen = new Set();
-      let m;
-      while ((m = re.exec(content)) !== null) {
-        const name = m[1];
-        if (name.startsWith('WEBJS_PUBLIC_')) continue;
-        if (name === 'NODE_ENV') continue;
-        if (seen.has(name)) continue;
-        seen.add(name);
-        violations.push({
-          rule: 'no-server-env-in-components',
-          file: rel,
-          message: `Component reads process.env.${name}; server-only env vars must not be read in components (would leak into SSR'd HTML and read as undefined after hydration)`,
-          fix: `Either rename to WEBJS_PUBLIC_${name} if the value is intended for the browser, or read process.env.${name} in a page function / server action / middleware and pass a derived value to the component as an attribute.`,
-        });
-      }
+  // Catches `process.env.X` reads in code the BROWSER runs, where X is not a
+  // WEBJS_PUBLIC_* var and not NODE_ENV: every component file, plus every
+  // module the build ships to the browser (a util a component imports). The
+  // browser env shim only exposes those two categories; any other read either
+  // leaks a secret into the SSR'd HTML or reads as undefined after hydration.
+  // A page / layout / boundary function runs on the server only, so its reads
+  // are fine and it is not scanned. Next.js's NEXT_PUBLIC_ prefix gets a
+  // targeted fix, since it is the usual cause.
+  for (const { abs, rel, content } of files) {
+    if (!isComponentFile(rel) && !shipped.has(abs)) continue;
+    if (/\.server\.m?[jt]s$/.test(rel) || isServerActionFile(abs, content)) continue;
+    // Route-ness comes from the route table, never a file name (#1686).
+    if (!isComponentFile(rel) && routeFiles.has(abs)) continue;
+    const masked = maskComments(content);
+    const re = /\bprocess\.env\.([A-Za-z_][A-Za-z0-9_]*)\b/g;
+    const seen = new Set();
+    let m;
+    while ((m = re.exec(masked)) !== null) {
+      const name = m[1];
+      if (name.startsWith('WEBJS_PUBLIC_')) continue;
+      if (name === 'NODE_ENV') continue;
+      if (seen.has(name)) continue;
+      seen.add(name);
+      const where = isComponentFile(rel) ? 'Component' : 'Browser-shipped module';
+      const nextPublic = name.startsWith('NEXT_PUBLIC_');
+      violations.push({
+        rule: 'no-server-env-in-components',
+        file: rel,
+        message: nextPublic
+          ? `${where} reads process.env.${name}. NEXT_PUBLIC_ is Next.js's browser prefix; WebJs exposes only WEBJS_PUBLIC_* (and NODE_ENV) to the browser, so this reads as undefined there.`
+          : `${where} reads process.env.${name}; server-only env vars must not be read in code the browser runs (it would leak into the SSR'd HTML and read as undefined after hydration)`,
+        fix: nextPublic
+          ? `Rename the variable to WEBJS_PUBLIC_${name.slice('NEXT_PUBLIC_'.length)} in your .env files and here.`
+          : `Either rename to WEBJS_PUBLIC_${name} if the value is intended for the browser, or read process.env.${name} in a page function / server action / middleware and pass a derived value to the component as an attribute.`,
+      });
     }
   }
 }
 
+/**
+ * Rule: `no-next-runtime-guard`.
+ *
+ * `process.env.NEXT_RUNTIME` is set by Next.js only (to 'nodejs' or 'edge'),
+ * typically as `if (process.env.NEXT_RUNTIME === 'nodejs')` around an
+ * instrumentation `register()`. Under WebJs it is undefined, so the guarded
+ * code silently never runs.
+ *
+ * @param {ScannedFile[]} files
+ * @param {Violation[]} violations
+ */
+export function checkNoNextRuntimeGuard(files, violations) {
+  for (const { rel, scan } of files) {
+    // `scan` blanks comments and template bodies (a docs page quoting the
+    // guard is not code).
+    const masked = scan;
+    if (!/\bprocess\.env\.NEXT_RUNTIME\b/.test(masked)) continue;
+    violations.push({
+      rule: 'no-next-runtime-guard',
+      file: rel,
+      message: 'Reads process.env.NEXT_RUNTIME, which only Next.js sets. Under WebJs it is undefined, so code guarded by it (an instrumentation register(), say) silently never runs.',
+      fix: "Drop the guard: WebJs runs instrumentation.ts register() once, on the server only. To tell the runtimes apart use process.versions.bun (Bun) and process.versions.node (Node).",
+    });
+  }
+}
+
+/**
+ * Rule: `no-next-url`.
+ *
+ * `request.nextUrl` is Next.js's extended URL. WebJs hands middleware and
+ * route handlers the platform Request, so the property throws in dev with the
+ * fix (and answers a plain URL in production rather than crashing a live app).
+ * Matched as `req.nextUrl` / `request.nextUrl` anywhere, and as any
+ * `.nextUrl` inside a middleware or proxy file, so an app's own `nextUrl`
+ * (a pagination cursor on a response object) is left alone.
+ *
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {void}
+ */
+export function checkNoNextUrl(files, violations) {
+  for (const { rel, content } of files) {
+    if (!content.includes('nextUrl')) continue;
+    // Fully blanked (comment, string and template bodies), so a mention in
+    // prose or a docs sample is not code.
+    const code = redactStringsAndTemplates(content, true);
+    const isMiddleware = /(^|\/)(middleware|proxy)\.(?:m?[jt]s)$/.test(rel);
+    const hit = isMiddleware ? /\.nextUrl\b/.test(code) : /\b(?:req|request)\.nextUrl\b/.test(code);
+    if (!hit) continue;
+    violations.push({
+      rule: 'no-next-url',
+      file: rel,
+      message: 'Reads request.nextUrl, Next.js\'s extended URL. WebJs passes the platform Request, so it throws in dev.',
+      fix: 'Use new URL(request.url) (its pathname and searchParams are what nextUrl offered).',
+    });
+  }
+}
+
 /**
  * Rule: `shell-in-non-root-layout`.
  *

package/src/check/rules-typescript.js

@@ -12,6 +12,7 @@ import { walk } from '../fs-walk.js';
 import {
   redactStringsAndTemplates,
 } from '../js-scan.js';
+import { findDecorator, decoratorReport } from '../lit-hints.js';
 
 /**
  * @typedef {import('./rules.js').Violation} Violation
@@ -134,8 +135,11 @@ export async function checkNoNonErasableTypescript(appDir, violations) {
     // Walk every .ts / .mts file under appDir, skipping node_modules,
     // build outputs, version control, and the framework's own private
     // folders. Match the conventional excludes that fs-walk.js's caller
-    // contract expects.
-    for await (const abs of walk(appDir, (p) => /\.m?ts$/.test(p))) {
+    // contract expects. Plain .js / .mjs files are walked too, for the
+    // decorator scan alone: no JavaScript runtime WebJs serves to runs
+    // decorators either, so `@customElement` in a .js component is the same
+    // load-time SyntaxError.
+    for await (const abs of walk(appDir, (p) => /\.m?[jt]s$/.test(p))) {
       // Skip anything inside node_modules or common build / cache dirs.
       const relPath = relative(appDir, abs);
       if (
@@ -148,6 +152,10 @@ export async function checkNoNonErasableTypescript(appDir, violations) {
       ) {
         continue;
       }
+      const isTs = /\.m?ts$/.test(abs);
+      // A .js file under public/ is a static asset (a service worker, a
+      // vendored script), never an app module the server loads.
+      if (!isTs && relPath.startsWith('public' + sep)) continue;
       let content;
       try {
         content = await readFile(abs, 'utf8');
@@ -159,6 +167,20 @@ export async function checkNoNonErasableTypescript(appDir, violations) {
       // inside `html\`...\`` template literals don't trip the rule.
       // The redactor preserves line + column so the reported line
       // number still maps to the right place in the original.
+      // Decorators: Lit's `@customElement` / `@property` / `@state` /
+      // `@query` habit. Node's stripper passes them through untouched, so the
+      // module dies at load with a bare SyntaxError that names neither the
+      // decorator nor the fix. Scanned on the fully blanked mask (string
+      // bodies too), so `@click=${...}` in an html template, `@media` in a
+      // css template, and `@param` in a JSDoc block never match.
+      if (content.includes('@')) {
+        const hit = findDecorator(content);
+        if (hit) {
+          const { message, fix } = decoratorReport(hit);
+          violations.push({ rule: 'no-non-erasable-typescript', file: relPath, message, fix });
+        }
+      }
+      if (!isTs) continue;
       const scan = redactStringsAndTemplates(content);
       for (const { name, regex, fix } of NON_ERASABLE_PATTERNS) {
         const m = scan.match(regex);