@webjsdev/server 0.7.2 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # @webjsdev/server
 
-Dev + production server for [webjs](https://github.com/vivek7405/webjs):
+Dev + production server for [webjs](https://github.com/webjsdev/webjs):
 file-based routing, streaming SSR, server actions, WebSocket upgrades, and
 live reload.
 
@@ -18,8 +18,13 @@ to scaffold and run an app, which pulls this package in as a dependency.
 - **WebSockets**: export `WS` from `route.ts` and it becomes a WebSocket
   endpoint on the same path.
 - **Live reload** for dev.
-- **Bare-specifier auto-bundling** for npm packages via import maps, backed
-  by esbuild (Vite-style `optimizeDeps`).
+- **Bare-specifier resolution** for npm packages via import maps,
+  resolved through jspm.io at runtime (Rails 7 + importmap-rails
+  posture). Browser fetches bundles directly from `ga.jspm.io` CDN;
+  webjs's server does not bundle vendor packages. Run `webjs vendor
+  pin` to commit resolved URLs to `.webjs/vendor/importmap.json`
+  (deterministic deploys), or `--download` to additionally vendor
+  bundle bytes for offline-capable production.
 
 ## Install
 
@@ -41,10 +46,10 @@ Or programmatically:
 ```js
 import { startServer } from '@webjsdev/server';
 
-await startServer({ port: 3000, appDir: process.cwd(), dev: true });
+await startServer({ port: 8080, appDir: process.cwd(), dev: true });
 ```
 
-See the full framework docs at https://github.com/vivek7405/webjs.
+See the full framework docs at https://github.com/webjsdev/webjs.
 
 ## License
 

package/index.js

@@ -11,12 +11,30 @@ export {
   invokeAction,
 } from './src/actions.js';
 export { buildImportMap, importMapTag, setVendorEntries } from './src/importmap.js';
-export { scanBareImports, extractPackageName, bundlePackage, vendorImportMapEntries, clearVendorCache, serveVendorBundle } from './src/vendor.js';
+export {
+  scanBareImports,
+  extractPackageName,
+  vendorImportMapEntries,
+  resolveVendorImports,
+  clearVendorCache,
+  getPackageVersion,
+  jspmGenerate,
+  pinAll,
+  unpinPackage,
+  listPinned,
+  auditPinned,
+  findOutdated,
+  updatePinned,
+  readPinFile,
+  serveDownloadedBundle,
+  SUPPORTED_PROVIDERS,
+  normalizeProvider,
+} from './src/vendor.js';
 export { buildModuleGraph, transitiveDeps } from './src/module-graph.js';
 export { scanComponents, primeComponentRegistry, extractComponents, findOrphanComponents } from './src/component-scanner.js';
-export { headers, cookies, getRequest, withRequest } from './src/context.js';
+export { headers, cookies, getRequest, withRequest, cspNonce } from './src/context.js';
 export { defaultLogger } from './src/logger.js';
-export { rateLimit, parseWindow } from './src/rate-limit.js';
+export { rateLimit, parseWindow, clientIp, stampRemoteIp } from './src/rate-limit.js';
 export { memoryStore, redisStore, getStore, setStore } from './src/cache.js';
 export { cache } from './src/cache-fn.js';
 export { Session, session, cookieSessionStorage, storeSessionStorage, cookieSession, storeSession, getSession } from './src/session.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",
@@ -15,8 +15,6 @@
   ],
   "dependencies": {
     "@webjsdev/core": "^0.7.1",
-    "chokidar": "^3.6.0",
-    "esbuild": "^0.28.0",
     "ws": "^8.20.0"
   },
   "publishConfig": {
@@ -24,11 +22,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vivek7405/webjs.git",
+    "url": "git+https://github.com/webjsdev/webjs.git",
     "directory": "packages/server"
   },
-  "homepage": "https://github.com/vivek7405/webjs#readme",
-  "bugs": "https://github.com/vivek7405/webjs/issues",
+  "homepage": "https://github.com/webjsdev/webjs#readme",
+  "bugs": "https://github.com/webjsdev/webjs/issues",
   "license": "MIT",
   "keywords": [
     "webjs",

package/src/actions.js

@@ -1,4 +1,4 @@
-import { createHash } from 'node:crypto';
+import { digestHex } from './crypto-utils.js';
 import { pathToFileURL } from 'node:url';
 import { readFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
@@ -103,7 +103,7 @@ export async function buildActionIndex(appDir, dev) {
     // throw-at-load stub via `serveServerOnlyStub` instead.
     if (!(await hasUseServerDirective(file))) continue;
 
-    const h = hashFile(file);
+    const h = await hashFile(file);
     hashToFile.set(h, file);
     fileToHash.set(file, h);
     // Load module once at scan time to pick up any expose() tags.
@@ -132,9 +132,9 @@ export async function buildActionIndex(appDir, dev) {
   return { hashToFile, fileToHash, httpRoutes, appDir, dev };
 }
 
-/** @param {string} file */
-export function hashFile(file) {
-  return createHash('sha256').update(file).digest('hex').slice(0, 10);
+/** @param {string} file @returns {Promise<string>} */
+export async function hashFile(file) {
+  return (await digestHex('SHA-256', file)).slice(0, 10);
 }
 
 /**
@@ -222,7 +222,7 @@ throw new Error(${JSON.stringify(msg)});
  */
 export async function serveActionStub(idx, absFile) {
   const mod = await loadModule(absFile, idx.dev);
-  const hash = idx.fileToHash.get(absFile) || hashFile(absFile);
+  const hash = idx.fileToHash.get(absFile) || await hashFile(absFile);
   const fnNames = Object.keys(mod).filter((k) => typeof mod[k] === 'function');
   if (typeof mod.default === 'function' && !fnNames.includes('default')) {
     fnNames.push('default');

package/src/auth.js

@@ -299,7 +299,7 @@ export function createAuth(config) {
 
   async function oauthRedirect(provider, opts) {
     const req = opts.req || getRequest();
-    const origin = req ? new URL(req.url).origin : 'http://localhost:3000';
+    const origin = req ? new URL(req.url).origin : 'http://localhost:8080';
     const state = randomId();
 
     const url = new URL(provider.authorizationUrl);

package/src/cache.js

@@ -47,6 +47,17 @@ export function memoryStore(opts = {}) {
     return entry.expiresAt !== null && Date.now() > entry.expiresAt;
   }
 
+  // Only a finite, positive ttlMs sets an expiration. NaN, Infinity,
+  // 0, negative, or non-number all fall back to "no TTL" (null).
+  // Without this, NaN slips past the truthiness check and entries
+  // silently live forever, which masks bugs in caller code that
+  // computes ttl from arithmetic.
+  function expiresAtFrom(ttlMs) {
+    return typeof ttlMs === 'number' && Number.isFinite(ttlMs) && ttlMs > 0
+      ? Date.now() + ttlMs
+      : null;
+  }
+
   return {
     async get(key) {
       const entry = map.get(key);
@@ -61,7 +72,7 @@ export function memoryStore(opts = {}) {
       map.delete(key); // remove old position
       map.set(key, {
         value,
-        expiresAt: ttlMs ? Date.now() + ttlMs : null,
+        expiresAt: expiresAtFrom(ttlMs),
       });
       evict();
     },
@@ -73,12 +84,18 @@ export function memoryStore(opts = {}) {
       if (!entry || isExpired(entry)) {
         map.set(key, {
           value: '1',
-          expiresAt: ttlMs ? Date.now() + ttlMs : null,
+          expiresAt: expiresAtFrom(ttlMs),
         });
         return 1;
       }
       const next = parseInt(entry.value, 10) + 1;
+      // Mutate value + re-insert so the bumped key counts as recent
+      // for LRU eviction. Without the re-insert, a hot rate-limit
+      // bucket stays at its original position and gets evicted ahead
+      // of less-active keys.
       entry.value = String(next);
+      map.delete(key);
+      map.set(key, entry);
       return next;
     },
   };

package/src/check.js

@@ -1,6 +1,11 @@
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join, relative, sep, basename, dirname } from 'node:path';
 import { walk } from './fs-walk.js';
+import {
+  redactStringsAndTemplates,
+  extractWebComponentClassBodies,
+  matchClosingBrace,
+} from './js-scan.js';
 
 /**
  * Convention validator for webjs apps.
@@ -92,13 +97,23 @@ export const RULES = [
   {
     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 fall back to esbuild + inline sourcemap, which is supported as a safety net for third-party deps but should not be the path your own code takes. 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.',
+      '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: '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: 'gitignore-vendor-not-ignored',
+    description:
+      'Verifies the `.gitignore` exception for `.webjs/vendor/` is structurally correct via `git check-ignore`. The intended pattern is `.webjs/*` (NOT `.webjs/`) plus `!.webjs/vendor/` plus `!.webjs/vendor/**`. The common-looking pattern `.webjs/` excludes the directory itself, after which git cannot re-include children (gitignore semantics: a parent exclusion blocks child negations). Without this rule, an AI agent or human editor would silently break `webjs vendor pin` by simplifying the pattern; the failure is invisible until production. Rule fires when the working directory is a git repo and a `.gitignore` exists; skipped when neither is true.',
+  },
 ];
 
 /** Set of all known rule names for fast lookup. */
@@ -241,72 +256,6 @@ function countExportedFunctions(content) {
   return seen.size;
 }
 
-/**
- * Extract the body of every `class … extends WebComponent { … }` block.
- * Brace-counts to handle nested template literals, methods, and arrow
- * functions. String state is tracked so braces inside strings/templates
- * don't shift depth.
- *
- * @param {string} content
- * @returns {string[]}
- */
-function extractWebComponentClassBodies(content) {
-  const bodies = [];
-  const re = /class\s+\w+\s+extends\s+WebComponent\s*\{/g;
-  let m;
-  while ((m = re.exec(content)) !== null) {
-    const bodyStart = m.index + m[0].length;
-    const end = matchClosingBrace(content, bodyStart);
-    if (end !== -1) bodies.push(content.slice(bodyStart, end));
-  }
-  return bodies;
-}
-
-/**
- * Walk forward from `start` (just after an opening `{`) and return the
- * index of the matching `}`. Tracks string/template-literal state so
- * `}` inside `'…'`, `"…"`, or backtick templates don't decrement depth.
- * Returns -1 if no balanced brace is found.
- *
- * @param {string} s
- * @param {number} start
- */
-function matchClosingBrace(s, start) {
-  let depth = 1;
-  let i = start;
-  let str = ''; // '', "'", '"', or '`'
-  while (i < s.length) {
-    const c = s[i];
-    if (str) {
-      if (c === '\\') { i += 2; continue; }
-      if (c === str) str = '';
-      else if (str === '`' && c === '$' && s[i + 1] === '{') {
-        // template hole: count its closing `}` toward our brace depth.
-        depth++;
-        i += 2;
-        continue;
-      }
-      i++;
-      continue;
-    }
-    if (c === "'" || c === '"' || c === '`') { str = c; i++; continue; }
-    if (c === '/' && s[i + 1] === '/') { // line comment
-      while (i < s.length && s[i] !== '\n') i++;
-      continue;
-    }
-    if (c === '/' && s[i + 1] === '*') { // block comment
-      i += 2;
-      while (i < s.length && !(s[i] === '*' && s[i + 1] === '/')) i++;
-      i += 2;
-      continue;
-    }
-    if (c === '{') depth++;
-    else if (c === '}') { depth--; if (depth === 0) return i; }
-    i++;
-  }
-  return -1;
-}
-
 /**
  * Find every `<key>:` entry inside the first `static properties = { … }`
  * literal in `classBody`. Returns the bare property names: the keys
@@ -492,8 +441,15 @@ export async function checkConventions(appDir, opts) {
     }
   }
 
-  // Collect all JS/TS files in the app directory
-  /** @type {{ abs: string, rel: string, content: string }[]} */
+  // Collect all JS/TS files in the app directory. Each entry carries
+  // both the raw `content` (for rules that need verbatim source: the
+  // `'use server'` directive detector, the `.gitignore` reader, etc.)
+  // and a `scan` view with comments, string contents, and
+  // template-literal bodies redacted to whitespace. Rules that
+  // pattern-match across raw source should consume `scan` so docs-
+  // page code-block examples and JSDoc samples don't trigger false
+  // positives.
+  /** @type {{ abs: string, rel: string, content: string, scan: string }[]} */
   const files = [];
   for await (const abs of walk(appDir, (p) => /\.m?[jt]sx?$/.test(p))) {
     const rel = relative(appDir, abs);
@@ -503,7 +459,7 @@ export async function checkConventions(appDir, opts) {
     } catch {
       continue;
     }
-    files.push({ abs, rel, content });
+    files.push({ abs, rel, content, scan: redactStringsAndTemplates(content) });
   }
 
   // --- Rule: actions-in-modules ---
@@ -556,15 +512,19 @@ export async function checkConventions(appDir, opts) {
 
   // --- Rule: components-have-register ---
   if (isRuleEnabled('components-have-register', overrides)) {
-    for (const { rel, content } of files) {
+    for (const { rel, scan } of files) {
       if (!isComponentFile(rel)) continue;
-      // Check if it defines a class extending WebComponent
-      if (!/class\s+\w+\s+extends\s+WebComponent/.test(content)) continue;
+      // Use redacted source so a code-example string like
+      // `Foo.register('bar')` inside a tagged template literal does
+      // not falsely satisfy the rule for a sibling unregistered
+      // class. Real register() calls live at top level where the
+      // redactor leaves them alone.
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
       // Accept either registration pattern:
       //   Counter.register('tag')                    (webjs idiom)
       //   customElements.define('tag', Counter)      (native)
-      if (/\b[A-Z][A-Za-z0-9_$]*\.register\s*\(\s*['"]/.test(content)) continue;
-      if (/\bcustomElements\.define\s*\(/.test(content)) continue;
+      if (/\b[A-Z][A-Za-z0-9_$]*\.register\s*\(\s*['"`]/.test(scan)) continue;
+      if (/\bcustomElements\.define\s*\(/.test(scan)) continue;
       violations.push({
         rule: 'components-have-register',
         file: rel,
@@ -576,9 +536,13 @@ export async function checkConventions(appDir, opts) {
 
   // --- Rule: reactive-props-use-declare ---
   if (isRuleEnabled('reactive-props-use-declare', overrides)) {
-    for (const { rel, content } of files) {
-      if (!/class\s+\w+\s+extends\s+WebComponent/.test(content)) continue;
-      for (const body of extractWebComponentClassBodies(content)) {
+    for (const { rel, scan } of files) {
+      // Use redacted source so test-fixture-style strings like
+      // `class X extends WebComponent { x = 0 }` inside template
+      // literals don't trip the rule. Real declarations live at
+      // top-level code where the redactor leaves them alone.
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const body of extractWebComponentClassBodies(scan)) {
         const propNames = extractStaticPropertyNames(body);
         if (propNames.size === 0) continue;
         for (const bad of findFieldInitializers(body, propNames)) {
@@ -737,8 +701,8 @@ export async function checkConventions(appDir, opts) {
       violations.push({
         rule: 'no-json-data-files',
         file: s.rel,
-        message: `${s.why}. webjs apps must persist data with Prisma + SQLite (already wired up: see prisma/schema.prisma and lib/prisma.ts), not JSON files.`,
-        fix: `Define a Prisma model in prisma/schema.prisma for this data, run \`webjs db migrate <name>\` to create the migration, then read/write via \`import { prisma } from 'lib/prisma.ts'\`. Delete ${s.rel} once the data has moved.`,
+        message: `${s.why}. webjs apps must persist data with Prisma + SQLite (already wired up: see prisma/schema.prisma and lib/prisma.server.ts), not JSON files.`,
+        fix: `Define a Prisma model in prisma/schema.prisma for this data, run \`webjs db migrate <name>\` to create the migration, then read/write via \`import { prisma } from 'lib/prisma.server.ts'\`. Delete ${s.rel} once the data has moved.`,
       });
     }
   }
@@ -781,15 +745,16 @@ export async function checkConventions(appDir, opts) {
   }
 
   // --- Rule: erasable-typescript-only ---
-  // The dev server's primary type-stripper is Node's built-in
+  // 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`). The fallback path is esbuild +
-  // inline sourcemap, which is a real ~3x wire-byte hit on every .ts
-  // request that takes it. 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.
+  // 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.
   if (isRuleEnabled('erasable-typescript-only', overrides)) {
     let tsconfigContent = null;
     try {
@@ -816,8 +781,8 @@ export async function checkConventions(appDir, opts) {
           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) falls back to esbuild + inline sourcemap on every request, costing ~3x wire bytes and losing byte-exact stack-trace positions.'
-              : '`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 slower runtime fallback.',
+              ? '`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.',
         });
@@ -825,6 +790,99 @@ export async function checkConventions(appDir, opts) {
     }
   }
 
+  // --- 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.
+  if (isRuleEnabled('no-non-erasable-typescript', overrides)) {
+    /** @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; }`. The reactive-props-use-declare rule has the framework-specific shape: `declare x: number;` (no value) plus the assignment in the constructor body.',
+      },
+      {
+        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,
+          });
+        }
+      }
+    }
+  }
+
   // --- Rule: use-server-needs-extension ---
   // Catch files that declare `'use server'` at the top but lack the
   // `.server.{js,ts}` extension. Under the two-marker convention the
@@ -849,17 +907,23 @@ export async function checkConventions(appDir, opts) {
 
   // --- Rule: tag-name-has-hyphen ---
   if (isRuleEnabled('tag-name-has-hyphen', overrides)) {
-    for (const { rel, content } of files) {
+    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')
-        /\b[A-Z][A-Za-z0-9_$]*\.register\s*\(\s*(['"])([^'"]+)\1/g,
-        // customElements.define('tag', Class)
-        /\bcustomElements\.define\s*\(\s*(['"])([^'"]+)\1/g,
+        // 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(content)) !== null) {
+        while ((match = re.exec(scan)) !== null) {
           const tagName = match[2];
           if (!tagName.includes('-')) {
             violations.push({
@@ -874,5 +938,72 @@ export async function checkConventions(appDir, opts) {
     }
   }
 
+  // --- Rule: gitignore-vendor-not-ignored ---
+  // The .gitignore pattern for .webjs/vendor/ is subtle: `.webjs/`
+  // alone excludes the directory entirely and git can't re-include
+  // children of an excluded parent. The correct pattern is `.webjs/*`
+  // plus `!.webjs/vendor/` plus `!.webjs/vendor/**`. AI agents
+  // and human reviewers frequently "simplify" this back to `.webjs/`,
+  // silently breaking `webjs vendor pin`.
+  //
+  // This rule verifies the actual gitignore behavior by spawning
+  // `git check-ignore` against a representative pin-file path. If
+  // git reports the file as ignored, the pattern is broken.
+  //
+  // Skipped when the directory isn't a git repo or has no .gitignore
+  // (the user hasn't opted into version control yet).
+  if (isRuleEnabled('gitignore-vendor-not-ignored', overrides)) {
+    const hasGit = await pathExists(join(appDir, '.git'));
+    const hasGitignore = await pathExists(join(appDir, '.gitignore'));
+    if (hasGit && hasGitignore) {
+      const { spawnSync } = await import('node:child_process');
+      // Check two representative paths: the pin manifest AND a sample
+      // downloaded bundle. A `.gitignore` that allows the manifest
+      // but blocks bundles (e.g. `*.js` higher up) would still break
+      // `webjs vendor pin --download`. `git check-ignore -q` exits 0
+      // when ignored, 1 when not ignored.
+      const probes = [
+        '.webjs/vendor/importmap.json',
+        '.webjs/vendor/sample-pkg@1.0.0.js',
+      ];
+      for (const probe of probes) {
+        const result = spawnSync('git', ['check-ignore', '-q', probe], {
+          cwd: appDir,
+          stdio: 'pipe',
+        });
+        if (result.status === 0) {
+          violations.push({
+            rule: 'gitignore-vendor-not-ignored',
+            file: '.gitignore',
+            message:
+              `${probe} is gitignored, but \`webjs vendor pin\` writes files under .webjs/vendor/ and they MUST be committed for production deploys to use the pin (instead of calling api.jspm.io on every cold start). The most common cause: a \`.webjs/\` line in .gitignore that excludes the parent directory before the \`!.webjs/vendor/\` exception can take effect (git semantics: a parent exclusion blocks child negations). A second possible cause is a broader rule (e.g. \`*.js\` at root) that hides bundle files added by \`webjs vendor pin --download\`.`,
+          fix:
+            'Replace `.webjs/` in your .gitignore with this three-line pattern:\n' +
+            '  .webjs/*\n' +
+            '  !.webjs/vendor/\n' +
+            '  !.webjs/vendor/**\n' +
+            'Verify with `git check-ignore -q .webjs/vendor/importmap.json` (exit 1 means correctly un-ignored).',
+        });
+      }
+    }
+    }
+  }
+
   return violations;
 }
+
+/**
+ * Async fs.exists shim. Returns true if the path exists at all (file
+ * or directory), false on ENOENT or any other stat failure.
+ *
+ * @param {string} p absolute path
+ * @returns {Promise<boolean>}
+ */
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}