@webjsdev/server 0.8.62 → 0.8.64

package/src/check/rules-registry.js

@@ -0,0 +1,128 @@
+/**
+ * Custom-element registry rules: tag-name validity and uniqueness across the app.
+ *
+ * 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 { join } from 'node:path';
+import {
+  isComponentFile,
+} from './helpers.js';
+import {
+  gitIgnoredSet,
+} from './runner-support.js';
+
+/**
+ * @typedef {import('./rules.js').Violation} Violation
+ * @typedef {{ abs: string, rel: string, content: string, scan: string }} ScannedFile
+ */
+
+
+/**
+ * Rule: `tag-name-has-hyphen`.
+ *
+ * @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 checkTagNameHasHyphen(files, violations) {
+  // --- Rule: tag-name-has-hyphen ---
+  {
+    for (const { rel, scan } of files) {
+      if (!isComponentFile(rel)) continue;
+      // Use redacted source. A `register('tag')` call inside a
+      // TAGGED template literal (docs-page code example) is blanked.
+      // Calls at top level keep their structure AND their string
+      // argument. Quote style can be ', ", or ` (untagged backtick
+      // literals survive the redactor, like single/double-quote
+      // strings).
+      const patterns = [
+        // Class.register('tag') / register("tag") / register(`tag`)
+        /\b[A-Z][A-Za-z0-9_$]*\.register\s*\(\s*(['"`])([^'"`]+)\1/g,
+        // customElements.define('tag', Class) and quote variants
+        /\bcustomElements\.define\s*\(\s*(['"`])([^'"`]+)\1/g,
+      ];
+      for (const re of patterns) {
+        let match;
+        while ((match = re.exec(scan)) !== null) {
+          const tagName = match[2];
+          if (!tagName.includes('-')) {
+            violations.push({
+              rule: 'tag-name-has-hyphen',
+              file: rel,
+              message: `Custom element tag "${tagName}" must contain a hyphen`,
+              fix: `Rename to a hyphenated tag name, e.g. "app-${tagName}" or "${tagName}-element"`,
+            });
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `no-duplicate-tag`.
+ *
+ * @param {string} appDir  absolute path to the app root
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {Promise<void>}
+ */
+export async function checkNoDuplicateTag(appDir, files, violations) {
+  // --- Rule: no-duplicate-tag ---
+  // Two registrations of the SAME tag string anywhere in the app resolve
+  // inconsistently at runtime (SSR last-wins, browser first-wins), so flag
+  // every colliding site naming the others. Scans EVERY source file, not just
+  // components/, because a duplicate is a runtime hazard regardless of where
+  // the register/define call lives (a page, a lib, a module can register a
+  // tag too); this keeps the rule in lockstep with the editor's 9004
+  // diagnostic, which is likewise project-wide. Reuses the same
+  // register/define extraction as tag-name-has-hyphen, over the redacted
+  // source so a tag in a docs-page tagged-template example does not count.
+  // Only hyphenated tags are considered (a non-hyphenated tag is already
+  // flagged by tag-name-has-hyphen / invariant 3), matching the 9004 filter.
+  {
+    // Generated / gitignored files (e.g. a `webjs ui add`-regenerated
+    // `components/` dir) are not committed source the rule should police;
+    // counting them would flag a collision between a hand-written component
+    // and its generated copy. Skip anything git reports as ignored.
+    // Best-effort: a non-git project (or absent git) scans everything.
+    const ignored = await gitIgnoredSet(appDir, files.map((f) => f.rel));
+    /** @type {Map<string, string[]>} tag -> rel files that register it (with repeats) */
+    const tagSites = new Map();
+    const patterns = [
+      /\b[A-Z][A-Za-z0-9_$]*\.register\s*\(\s*(['"`])([^'"`]+)\1/g,
+      /\bcustomElements\.define\s*\(\s*(['"`])([^'"`]+)\1/g,
+    ];
+    for (const { scan, rel } of files) {
+      if (ignored.has(rel)) continue;
+      for (const re of patterns) {
+        let match;
+        while ((match = re.exec(scan)) !== null) {
+          const tagName = match[2];
+          if (!tagName.includes('-')) continue;
+          const arr = tagSites.get(tagName) || [];
+          arr.push(rel);
+          tagSites.set(tagName, arr);
+        }
+      }
+    }
+    for (const [tagName, sites] of tagSites) {
+      if (sites.length < 2) continue;
+      // Report once per DISTINCT file, naming the others.
+      for (const file of new Set(sites)) {
+        const others = [...new Set(sites)].filter((f) => f !== file);
+        const where = others.length
+          ? `also registered in ${others.join(', ')}`
+          : 'registered more than once in this file';
+        violations.push({
+          rule: 'no-duplicate-tag',
+          file,
+          message: `Custom element tag "${tagName}" is registered more than once (${where}). A tag must be registered exactly once; the runtime resolves a duplicate inconsistently (SSR keeps the last registration, the browser keeps the first).`,
+          fix: `Rename one registration so each "${tagName}" is unique, e.g. "${tagName}-2".`,
+        });
+      }
+    }
+  }
+}

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,
+          });
+        }
+      }
+    }
+  }
+}