@webjsdev/server 0.8.63 → 0.8.65

package/src/check/rules-routing.js

@@ -0,0 +1,224 @@
+/**
+ * Routing and template rules: what a route handler may throw, 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
+ * in one 900-line function. Each rule keeps its original comment header, its
+ * logic, and its position in the run order.
+ */
+import {
+  isServerActionFile, isComponentFile,
+} from './helpers.js';
+
+/**
+ * @typedef {import('./rules.js').Violation} Violation
+ * @typedef {{ abs: string, rel: string, content: string, scan: string }} ScannedFile
+ */
+
+
+/**
+ * Rule: `no-redirect-in-api-route`.
+ *
+ * @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 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;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `no-interpolation-in-raw-text-element`.
+ *
+ * @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 checkNoInterpolationInRawTextElement(files, violations) {
+  // --- Rule: no-interpolation-in-raw-text-element ---
+  // A `${...}` hole inside a `<style>` or `<script>` element in an `html`
+  // template is an SSR/client asymmetry: `renderToString` emits it, but the
+  // client parser drops a raw-text hole as a `noop` (the compile cache is keyed
+  // on the static strings, so a per-render value cannot be baked in), so the
+  // element paints at SSR then wipes to empty on hydration.
+  //
+  // Scoped to COMPONENTS. The drop only happens on the CLIENT renderer, which
+  // runs for components (hydration + re-render). Pages and layouts render
+  // server-only (never hydrate), so a page's `<style>${STYLES.text}</style>` is
+  // a legitimate, taught pattern and must NOT be flagged. Scan raw source with
+  // comments stripped (the tag text lives in a template string, which the
+  // redacted `scan` view blanks). One violation per file.
+  {
+    for (const { rel, content } of files) {
+      // Only files that define a hydrating custom element. A page/layout that
+      // interpolates a `css` result into a `<style>` is server-only and fine.
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(content)) continue;
+      const stripped = content
+        .replace(/\/\/.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\//g, '');
+      for (const tag of ['style', 'script']) {
+        // `<tag ...> ... ${ ... </tag>`, where the hole sits before the close
+        // tag. The negative lookahead keeps the match from crossing `</tag>`.
+        const re = new RegExp(
+          `<${tag}\\b[^>]*>(?:(?!<\\/${tag}>)[\\s\\S])*?\\$\\{(?:(?!<\\/${tag}>)[\\s\\S])*?<\\/${tag}>`,
+          'i',
+        );
+        if (re.test(stripped)) {
+          violations.push({
+            rule: 'no-interpolation-in-raw-text-element',
+            file: rel,
+            message: `An interpolation (\`\${...}\`) sits inside a <${tag}> element in an html template. The server renderer emits it but the client renderer drops it, so it paints at SSR then wipes to empty on hydration.`,
+            fix:
+              tag === 'style'
+                ? `Move the CSS out of the raw-text hole: use \`static styles\` (shadow DOM) or a \`css\` template for a component, or put page CSS in the layout. Static \`<style>...</style>\` with no \`\${}\` is fine.`
+                : `Build the script body outside the raw-text element (set attributes/properties via bindings, or compute the value before the template). Static \`<script>...</script>\` with no \`\${}\` is fine.`,
+          });
+          break; // one violation per file is enough
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `no-server-env-in-components`.
+ *
+ * @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 checkNoServerEnvInComponents(files, violations) {
+  // --- 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.`,
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `shell-in-non-root-layout`.
+ *
+ * @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 checkShellInNonRootLayout(files, violations) {
+  // --- Rule: shell-in-non-root-layout ---
+  // Only app/layout.{js,ts} may write <!doctype>/<html>/<head>/<body>. The
+  // framework auto-emits the shell around the whole composition; a nested
+  // shell ends up duplicated and silently dropped by the HTML parser.
+  {
+    // Root layout = exactly "app/layout.js" or "app/layout.ts".
+    const ROOT_LAYOUT = /^app\/layout\.(?:js|mjs|ts|mts)$/;
+    // Any other layout or page under app/ (including pages, nested layouts).
+    const LAYOUT_OR_PAGE = /^app\/(?:.+\/)?(?:layout|page)\.(?:js|mjs|ts|mts)$/;
+    // Shell tags. Case-insensitive, allow whitespace, allow attributes for <html>/<body>.
+    const SHELL_RE = /<!doctype\b|<html\b|<head\b|<body\b/i;
+    for (const { rel, content } of files) {
+      if (ROOT_LAYOUT.test(rel)) continue;
+      if (!LAYOUT_OR_PAGE.test(rel)) continue;
+      // Strip line comments + /* … */ block comments + ` ` string-template
+      // tag content is fine: we're looking at the literal HTML in the
+      // returned `html` template, which won't be inside a code comment.
+      // A naive substring scan is good enough; false positives only when
+      // someone genuinely embeds `<html>` inside a string literal that
+      // isn't a layout shell (rare and probably an honest code smell).
+      const stripped = content
+        .replace(/\/\/.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\//g, '');
+      const m = stripped.match(SHELL_RE);
+      if (m) {
+        violations.push({
+          rule: 'shell-in-non-root-layout',
+          file: rel,
+          message:
+            `Non-root layout/page contains ${m[0]}: only the root layout (app/layout.{js,ts}) may write the shell. The framework auto-emits <!doctype>/<html>/<head>/<body> around the whole composition; a nested shell ends up duplicated and dropped by the HTML parser.`,
+          fix:
+            'Remove the <!doctype>/<html>/<head>/<body> wrapper from this file. Use the `metadata` export for <title>/<meta>/og/twitter, return inline <link>/<style>/<script> for head-bound resources (they auto-hoist), and put any `<html lang>` / `<body class>` overrides in app/layout.{js,ts} instead.',
+        });
+      }
+    }
+  }
+}

package/src/check/rules-typescript.js

@@ -0,0 +1,177 @@
+/**
+ * TypeScript rules. WebJs strips types rather than compiling them, so
+ * non-erasable syntax is a 500 at strip time, not a build error.
+ *
+ * Lifted verbatim out of checkConventions, which held all twenty rules inline
+ * in one 900-line function. Each rule keeps its original comment header, its
+ * logic, and its position in the run order.
+ */
+import { readFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { walk } from '../fs-walk.js';
+import {
+  redactStringsAndTemplates,
+} from '../js-scan.js';
+
+/**
+ * @typedef {import('./rules.js').Violation} Violation
+ * @typedef {{ abs: string, rel: string, content: string, scan: string }} ScannedFile
+ */
+
+
+/**
+ * Rule: `erasable-typescript-only`.
+ *
+ * @param {string} appDir  absolute path to the app root
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {Promise<void>}
+ */
+export async function checkErasableTypescriptOnly(appDir, violations) {
+  // --- Rule: erasable-typescript-only ---
+  // The dev server's type-stripper is Node's built-in
+  // module.stripTypeScriptTypes, which rejects non-erasable TS (enum,
+  // namespace with values, constructor parameter properties, legacy
+  // decorators, `import = require`). There is no fallback: non-erasable
+  // syntax is rejected at request time with a 500. Enforce TS-side
+  // rejection of those patterns via `compilerOptions.erasableSyntaxOnly:
+  // true` in tsconfig.json so violations surface as red squiggles in
+  // the editor before they ever hit the dev server. The companion
+  // no-non-erasable-typescript rule (below) catches violations even if
+  // the tsconfig flag is unset.
+  {
+    let tsconfigContent = null;
+    try {
+      tsconfigContent = await readFile(join(appDir, 'tsconfig.json'), 'utf8');
+    } catch {
+      // No tsconfig.json (pure JS app). Skip the rule.
+    }
+    if (tsconfigContent != null) {
+      let parsed = null;
+      try {
+        const stripped = tsconfigContent
+          .replace(/\/\/.*$/gm, '')
+          .replace(/\/\*[\s\S]*?\*\//g, '')
+          .replace(/,(\s*[}\]])/g, '$1');
+        parsed = JSON.parse(stripped);
+      } catch {
+        parsed = null;
+      }
+      const compilerOptions = parsed && typeof parsed === 'object' ? parsed.compilerOptions : null;
+      const flag = compilerOptions && typeof compilerOptions === 'object' ? compilerOptions.erasableSyntaxOnly : undefined;
+      if (flag !== true) {
+        violations.push({
+          rule: 'erasable-typescript-only',
+          file: 'tsconfig.json',
+          message:
+            flag === false
+              ? '`compilerOptions.erasableSyntaxOnly` is `false`. The framework strips TypeScript via Node\'s built-in stripper, which only supports erasable TS. Non-erasable syntax (enum, namespace with values, constructor parameter properties, legacy decorators) fails at strip time and the dev server returns a 500. webjs is buildless end-to-end and has no bundler fallback; turn the flag on so the TypeScript compiler catches non-erasable constructs as red squiggles at edit time.'
+              : '`compilerOptions.erasableSyntaxOnly` is not set. The framework strips TypeScript via Node\'s built-in stripper, which only supports erasable TS. Setting this flag makes the TypeScript compiler flag non-erasable syntax as a red squiggle in the editor instead of letting it silently slip through to a 500 at runtime.',
+          fix:
+            'Set `"erasableSyntaxOnly": true` under `compilerOptions` in tsconfig.json. Replace any existing `enum` declarations with `const X = { ... } as const` plus a `type X = typeof X[keyof typeof X]` union. Replace constructor parameter properties with explicit field declarations + assignments.',
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `no-non-erasable-typescript`.
+ *
+ * @param {string} appDir  absolute path to the app root
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {Promise<void>}
+ */
+export async function checkNoNonErasableTypescript(appDir, violations) {
+  // --- Rule: no-non-erasable-typescript ---
+  // Scans .ts source for the four non-erasable TypeScript constructs
+  // that the runtime stripper rejects. Complement to
+  // erasable-typescript-only: the flag check catches the case where
+  // the user opts into the tsconfig flag; this scan catches the
+  // case where the flag is missing OR the user has bypassed it and
+  // written offending syntax anyway. Both rules ship enabled by
+  // default so violators get the strongest signal possible.
+  {
+    /** @type {Array<{ name: string, regex: RegExp, fix: string }>} */
+    const NON_ERASABLE_PATTERNS = [
+      {
+        name: 'enum',
+        // Matches `enum X {`, `export enum X {`, `const enum X {`,
+        // `declare enum X {`. Requires uppercase first letter on the
+        // identifier to avoid matching variables literally named "enum"
+        // in user code (rare but possible).
+        regex: /^[ \t]*(?:export[ \t]+)?(?:declare[ \t]+)?(?:const[ \t]+)?enum[ \t]+[A-Z]\w*[ \t]*\{/m,
+        fix: 'Replace `enum Foo { A, B }` with `const Foo = { A: "A", B: "B" } as const; type Foo = typeof Foo[keyof typeof Foo];`.',
+      },
+      {
+        name: 'namespace with values',
+        // Matches `namespace Foo { ... <value statement> ... }` at top
+        // level. Type-only namespaces (which ARE erasable) won't contain
+        // `let|const|var|function|class` as statements, so this catches
+        // only the value-carrying form. False positives possible for
+        // type-only namespaces that contain those words in type aliases;
+        // accept this as a soft warning.
+        regex: /^[ \t]*(?:export[ \t]+)?namespace[ \t]+\w+[ \t]*\{[\s\S]*?\b(?:let|const|var|function|class)\b/m,
+        fix: 'Replace `namespace Foo { export const x = 1 }` with `export const Foo = { x: 1 } as const;` or split the contents into separate modules.',
+      },
+      {
+        name: 'constructor parameter property',
+        // Matches `constructor(public x: T)`, `constructor(private foo, ...)`,
+        // `constructor(readonly bar)`. Looks for one of the four access
+        // modifiers immediately followed by an identifier inside the
+        // constructor's parameter list.
+        regex: /constructor[ \t]*\([^)]*\b(?:public|private|protected|readonly)[ \t]+\w+/,
+        fix: 'Replace `constructor(public x: number)` with `x: number; constructor(x: number) { this.x = x; }`.',
+      },
+      {
+        name: 'import = require',
+        // TypeScript-style CommonJS import. Catches `import foo =
+        // require("bar")` and `export import foo = require("bar")`.
+        regex: /^[ \t]*(?:export[ \t]+)?import[ \t]+\w+[ \t]*=[ \t]*require[ \t]*\(/m,
+        fix: 'Replace `import foo = require("bar")` with `import * as foo from "bar"` or `import { something } from "bar"`.',
+      },
+    ];
+
+    // 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))) {
+      // Skip anything inside node_modules or common build / cache dirs.
+      const relPath = relative(appDir, abs);
+      if (
+        relPath.includes('node_modules' + sep) ||
+        relPath.startsWith('dist' + sep) ||
+        relPath.startsWith('build' + sep) ||
+        relPath.startsWith('.next' + sep) ||
+        relPath.startsWith('.git' + sep) ||
+        relPath.split(sep).some((s) => s.startsWith('_'))
+      ) {
+        continue;
+      }
+      let content;
+      try {
+        content = await readFile(abs, 'utf8');
+      } catch {
+        continue;
+      }
+      // Redact comments, string contents, and template-literal bodies
+      // so docs-page code examples like `<pre>enum Direction { ... }</pre>`
+      // 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.
+      const scan = redactStringsAndTemplates(content);
+      for (const { name, regex, fix } of NON_ERASABLE_PATTERNS) {
+        const m = scan.match(regex);
+        if (m && typeof m.index === 'number') {
+          const line = content.slice(0, m.index).split('\n').length;
+          violations.push({
+            rule: 'no-non-erasable-typescript',
+            file: relPath,
+            message: `Non-erasable TypeScript construct (${name}) detected at line ${line}. The framework's type-stripper rejects this at request time with a 500.`,
+            fix,
+          });
+        }
+      }
+    }
+  }
+}

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