@webjsdev/server 0.8.63 → 0.8.64

package/index.d.ts

@@ -336,8 +336,13 @@ export declare function setVendorEntries(
 // vendor.js (the `webjs vendor` CLI surface)
 // ---------------------------------------------------------------------------
 
-/** Scan a directory's source for bare-specifier npm imports. */
-export declare function scanBareImports(dir: string, skipFiles?: Set<string>): Promise<Set<string>>;
+/**
+ * Bare-specifier npm imports an app could load in the browser, found by walking
+ * the module graph from every browser-bound entry rather than by scanning the
+ * directory. Applies no elision pruning, so the result is a superset of what the
+ * running server serves.
+ */
+export declare function scanBareImports(dir: string): Promise<Set<string>>;
 /** Extract the package name from an import specifier (`dayjs/plugin/utc` -> `dayjs`). */
 export declare function extractPackageName(spec: string): string | null;
 /** Resolve bare imports to CDN importmap entries. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.63",
+  "version": "0.8.64",
   "type": "module",
   "description": "The server for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Provides the file-based router, SSR, server actions, route handlers, middleware, and live reload on Node 24+ or Bun.",
   "main": "index.js",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjsdev/core": "^0.7.50",
+    "@webjsdev/core": "^0.7.51",
     "ws": "^8.20.0"
   },
   "publishConfig": {

package/src/browser-entries.js

@@ -0,0 +1,64 @@
+/**
+ * The browser-bound ENTRY files of an app: every module the client boot can
+ * import directly.
+ *
+ * Feeding these to `reachableFromEntries` produces webjs's equivalent of
+ * Next.js's bundler-produced page manifest, derived lazily on the first
+ * request (and re-derived on every rebuild) instead of at compile time. The
+ * dev server uses that closure as an authorization gate on its source-file
+ * branch: in-set is served (subject to the `.server.{js,ts}` stub guardrail),
+ * out-of-set 404s. Feeding them to `reachableBareSpecifiers` produces the
+ * vendor importmap, which is why this half is its own module: the CLI-side
+ * vendor paths (`pinAll`, `webjs doctor`) root at exactly the entries the gate
+ * does, without booting a server.
+ *
+ * Entries:
+ *   - page / layout (both re-run on the client for hydration)
+ *   - the error / loading / not-found / forbidden / unauthorized boundaries
+ *   - the two root-only boundaries (global-error, global-not-found)
+ *   - instrumentation-client (imported first in the boot)
+ *   - every discovered component (a `static lazy` one is fetched by the lazy
+ *     loader rather than imported by a page, so the component scan is an entry
+ *     source in its own right)
+ *
+ * NOT entries, because the browser never fetches them as a module:
+ *   - route.{js,ts} (API handlers) and middleware.{js,ts}
+ *   - metadata routes (sitemap.js, robots.js, manifest.js, …)
+ *   - .server.{js,ts} files (the browser gets a stub, not the source)
+ */
+
+/**
+ * Components are passed in (rather than rescanned) so the caller can share one
+ * scan with `primeComponentRegistry`, saving a full appDir walk per analysis.
+ *
+ * @param {Awaited<ReturnType<typeof import('./router.js').buildRouteTable>>} routeTable
+ * @param {Awaited<ReturnType<typeof import('./component-scanner.js').scanComponents>>} components
+ * @returns {Set<string>}
+ */
+export function browserEntryFiles(routeTable, components) {
+  /** @type {Set<string>} */
+  const entries = new Set();
+  for (const page of routeTable.pages) {
+    if (page.file) entries.add(page.file);
+    for (const f of page.layouts || []) entries.add(f);
+    for (const f of page.errors || []) entries.add(f);
+    for (const f of page.loadings || []) entries.add(f);
+    for (const f of page.forbiddens || []) entries.add(f);
+    for (const f of page.unauthorizeds || []) entries.add(f);
+  }
+  if (routeTable.notFound) entries.add(routeTable.notFound);
+  if (routeTable.notFounds) {
+    for (const f of routeTable.notFounds.values()) entries.add(f);
+  }
+  if (routeTable.globalError) entries.add(routeTable.globalError);
+  if (routeTable.globalNotFound) entries.add(routeTable.globalNotFound);
+  // instrumentation-client is browser-bound (imported first in the boot), so it
+  // must be servable through the gate.
+  if (routeTable.instrumentationClient) entries.add(routeTable.instrumentationClient);
+  // Lazy components live in the registry but no page imports their
+  // class directly; the lazy-loader fetches their module URLs on
+  // viewport entry. Add every discovered component file as an entry so
+  // the graph walk covers both eager and lazy paths.
+  for (const c of components) entries.add(c.file);
+  return entries;
+}

package/src/check/helpers.js

@@ -0,0 +1,365 @@
+import { sep } from 'node:path';
+import { matchClosingBrace } from '../js-scan.js';
+
+/**
+ * Check whether a file has the `'use server'` directive in its first
+ * five lines. Used by the `use-server-needs-extension` rule, and by
+ * `isServerActionFile` below.
+ * @param {string} content file content (already read)
+ * @returns {boolean}
+ */
+export function hasUseServerDirective(content) {
+  const head = content.split('\n').slice(0, 5).join('\n');
+  return /^\s*(['"])use server\1\s*;?\s*$/m.test(head);
+}
+
+/**
+ * Check whether a file is a server action. A server action requires
+ * BOTH the `.server.{js,ts,mts,mjs}` extension AND the `'use server'`
+ * directive in the file head. Either alone is not enough: bare `.server.ts`
+ * is a server-only utility (no RPC), and bare `'use server'` is a lint
+ * violation (use-server-needs-extension).
+ * @param {string} filePath absolute path
+ * @param {string} content file content (already read)
+ * @returns {boolean}
+ */
+export function isServerActionFile(filePath, content) {
+  if (!/\.server\.m?[jt]s$/.test(filePath)) return false;
+  return hasUseServerDirective(content);
+}
+
+/**
+ * Check whether a file resides under a components/ directory (shared or
+ * module-scoped).
+ * @param {string} relPath Path relative to appDir
+ * @returns {boolean}
+ */
+export function isComponentFile(relPath) {
+  const segments = relPath.split(sep);
+  return segments.includes('components');
+}
+
+/**
+ * Scan a class body for class-field initializers naming any of `props`.
+ * "Class-field" means: at the top of the class body (brace depth 0
+ * relative to the body), at the start of a line, NOT prefixed with
+ * `declare`, `static`, or `this.`.
+ *
+ * Returns the offending property names. The caller maps these to
+ * Violation objects.
+ *
+ * @param {string} classBody
+ * @param {Set<string>} props
+ * @returns {string[]}
+ */
+/**
+ * True when a factory prop value is an array-typed `prop<…>(…)` whose
+ * runtime constructor argument is `Object`. The generic and the
+ * constructor sit in the same call, so it is decidable from the value
+ * text alone. The match is greedy on the generic so a nested generic
+ * (`prop<Array<X>>(Object)`) closes at the outer `>` that precedes the
+ * `(Object` call. A bare constructor (`Object`, with no generic) or a
+ * non-array generic (`prop<Foo>(Object)`) returns false.
+ *
+ * @param {string} value the raw prop value text, e.g. `prop<Tag[]>(Object)`
+ * @returns {boolean}
+ */
+export function arrayPropUsesObject(value) {
+  const m = /^prop\s*<([\s\S]*)>\s*\(\s*Object\s*[,)]/.exec(value.trim());
+  if (!m) return false;
+  return isArrayTypeText(m[1]);
+}
+
+/**
+ * True when a TypeScript type expression denotes an array: `T[]`,
+ * `readonly T[]`, `T[][]`, `Array<T>`, or `ReadonlyArray<T>`.
+ *
+ * @param {string} type
+ * @returns {boolean}
+ */
+export function isArrayTypeText(type) {
+  const bare = type.trim().replace(/^readonly\s+/, '');
+  if (/\[\s*\]$/.test(bare)) return true;
+  if (/^(?:Readonly)?Array\s*<[\s\S]*>$/.test(bare)) return true;
+  return false;
+}
+
+export function findFieldInitializers(classBody, props) {
+  /** @type {string[]} */
+  const out = [];
+  const n = classBody.length;
+  // Match class-field declarations. Two shapes:
+  // 1. With initializer: `count = 0`, `count: number = 0`, `public count = 0`
+  // 2. Type-only (no initializer): `count!: number`, `count?: number`, `count: number`
+  // Both compile to Object.defineProperty after super() under modern class-field
+  // semantics, clobbering the reactive accessor.
+  // The initializer regex: optional modifier, identifier, optional type, then `=`.
+  const initRe = /^\s*(?:(public|private|protected|readonly)\s+)?([A-Za-z_$][\w$]*)\s*(?::\s*[^=;]+)?\s*=\s*[^=>]/;
+  // The type-only regex: optional modifier, identifier, then `!:` or `?:` or `:` with a type.
+  const typeOnlyRe = /^\s*(?:(public|private|protected|readonly)\s+)?([A-Za-z_$][\w$]*)\s*[!?]?\s*:\s*\S/;
+  const examineLine = (lineStart) => {
+    let j = lineStart;
+    while (j < n && classBody[j] !== '\n') j++;
+    const line = classBody.slice(lineStart, j);
+    const initM = initRe.exec(line);
+    const typeM = typeOnlyRe.exec(line);
+    // Prefer the initializer match; if neither, skip.
+    const name = initM ? initM[2] : (typeM ? typeM[2] : null);
+    // `declare`, `static`, and `this.` patterns shouldn't reach here
+    // (declare/static start with their keyword, this.x has the dot in
+    // the regex group), but guard against matching keywords as names:
+    if (name && name !== 'declare' && name !== 'static' && props.has(name)) out.push(name);
+  };
+  // Walk the body char by char, tracking brace depth. A class field lives at
+  // the class-body top level (depth 0). We examine a line ONCE, at its first
+  // non-whitespace char, only while depth is 0, and WITHOUT skipping the braces
+  // on that line: an opening brace on the line (`method() {`, `field = {`) must
+  // still be counted so the lines inside its block are seen at depth > 0. The
+  // earlier version jumped `i` past the whole examined line, which dropped that
+  // line's braces and let object-literal keys inside a method body (`{ game:
+  // ..., scoreboard: ... }`) be misread as depth-0 class fields (#934).
+  let depth = 0;
+  let i = 0;
+  let lineStart = 0;
+  let examined = false;
+  let str = '';
+  while (i < n) {
+    const c = classBody[i];
+    if (str) {
+      if (c === '\\') { i += 2; continue; }
+      if (c === str) str = '';
+      i++;
+      continue;
+    }
+    if (c === '\n') { lineStart = i + 1; examined = false; i++; continue; }
+    if (c === '/' && classBody[i + 1] === '/') {
+      while (i < n && classBody[i] !== '\n') i++;
+      continue;
+    }
+    if (c === '/' && classBody[i + 1] === '*') {
+      i += 2;
+      while (i < n && !(classBody[i] === '*' && classBody[i + 1] === '/')) i++;
+      i += 2;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') { str = c; i++; continue; }
+    // First non-whitespace char of a class-body top-level line: examine it for
+    // a field declaration BEFORE consuming any brace it opens.
+    if (depth === 0 && !examined && !/\s/.test(c)) {
+      examined = true;
+      examineLine(lineStart);
+    }
+    if (c === '{') { depth++; i++; continue; }
+    if (c === '}') { depth--; i++; continue; }
+    i++;
+  }
+  return out;
+}
+
+// Browser-only globals that are undefined during SSR (the server-side
+// WebComponent base is a bare class with no DOM). High-confidence names only
+// (unlikely to be ordinary local variables), so the rule stays low-noise.
+const BROWSER_GLOBALS = [
+  'document', 'window', 'localStorage', 'sessionStorage', 'navigator',
+  'matchMedia', 'requestAnimationFrame', 'getComputedStyle',
+  'IntersectionObserver', 'MutationObserver', 'ResizeObserver',
+];
+
+// HTMLElement instance members that do not exist on the server element shim,
+// so `this.<member>` throws (a method call) or is `undefined` (a property) at
+// SSR. The attribute methods (get/set/has/remove/toggleAttribute), the event
+// methods (add/removeEventListener, dispatchEvent), and attachInternals are
+// backed by the shim and run server-side, so they are intentionally NOT
+// flagged: a component may read attributes in render and reflect properties
+// during the SSR update cycle. What stays is the genuinely browser-only
+// surface (DOM querying, layout reads, shadow construction, focus).
+const HTMLELEMENT_MEMBERS = [
+  'attachShadow', 'shadowRoot', 'classList',
+  'querySelector', 'querySelectorAll', 'getBoundingClientRect',
+  'focus', 'blur', 'scrollIntoView',
+];
+
+/**
+ * Extract the body text of a named method from a (redacted) class body, or
+ * '' if absent. Handles `async`, a TS return-type annotation, and params.
+ * @param {string} classBody
+ * @param {string} name
+ */
+export function methodBodyOf(classBody, name) {
+  const re = new RegExp(`(?:^|[\\s;}])(?:async\\s+)?${name}\\s*\\([^)]*\\)\\s*(?::[^{]*)?\\{`, 'g');
+  const m = re.exec(classBody);
+  if (!m) return '';
+  const open = classBody.indexOf('{', m.index + m[0].length - 1);
+  if (open === -1) return '';
+  const close = matchClosingBrace(classBody, open + 1);
+  return close === -1 ? '' : classBody.slice(open + 1, close);
+}
+
+/**
+ * Find browser-only globals and HTMLElement `this.<member>` accesses in a
+ * (redacted) method body. Returns one entry per distinct member.
+ * @param {string} code
+ * @returns {{ member: string, kind: string }[]}
+ */
+export function findBrowserMemberUses(code) {
+  // The class body arrives template-redacted, but `redactStringsAndTemplates`
+  // keeps single/double-quoted string CONTENT (real specifiers ride strings).
+  // Blank that too so a browser word inside a string literal (e.g. a label
+  // `'open the document'`) is not mistaken for a real global access.
+  code = code
+    .replace(/'(?:[^'\\]|\\.)*'/g, (s) => `'${' '.repeat(Math.max(0, s.length - 2))}'`)
+    .replace(/"(?:[^"\\]|\\.)*"/g, (s) => `"${' '.repeat(Math.max(0, s.length - 2))}"`);
+  const out = [];
+  const seen = new Set();
+  const gRe = new RegExp(`(?<![.\\w$])(${BROWSER_GLOBALS.join('|')})\\b`, 'g');
+  let m;
+  while ((m = gRe.exec(code)) !== null) {
+    if (seen.has(m[1])) continue;
+    seen.add(m[1]);
+    out.push({ member: m[1], kind: 'a browser global' });
+  }
+  const hRe = new RegExp(`\\bthis\\.(${HTMLELEMENT_MEMBERS.join('|')})\\b`, 'g');
+  while ((m = hRe.exec(code)) !== null) {
+    const key = `this.${m[1]}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ member: key, kind: 'an HTMLElement member' });
+  }
+  return out;
+}
+
+/**
+ * True if any `export const/let/var` declares more than one binding
+ * (`export const a = 1, b = 2`), which the single-name collector would
+ * under-count. Depth-aware: a comma inside an initializer (`f(a, b)`, `[a, b]`,
+ * `{ a, b }`) does not count, only a top-level comma before the statement end.
+ * Bailing the whole module on this errs toward a false negative (safe), never a
+ * false positive. Runs on the string/comment-redacted `scan`.
+ * @param {string} scan
+ * @returns {boolean}
+ */
+export function hasMultiDeclaratorExport(scan) {
+  const re = /\bexport\s+(?:const|let|var)\b/g;
+  let m;
+  while ((m = re.exec(scan))) {
+    let depth = 0;      // () [] {} nesting
+    let angle = 0;      // <> generics, tracked ONLY inside a type annotation
+    let seenEq = false; // passed this declarator's `=` (now in the initializer)
+    let inType = false; // inside a `: Type` annotation (before the `=`)
+    for (let i = m.index + m[0].length; i < scan.length; i++) {
+      const ch = scan[i];
+      if (ch === '(' || ch === '[' || ch === '{') { depth++; continue; }
+      if (ch === ')' || ch === ']' || ch === '}') { if (depth === 0) break; depth--; continue; }
+      if (depth !== 0) continue;
+      if (ch === ';') break;
+      // A plain `=` ends the type annotation and enters the initializer. `<=`,
+      // `>=`, `=>`, `==` are harmless here (seenEq only latches true).
+      if (ch === '=') { seenEq = true; inType = false; angle = 0; continue; }
+      // A `:` BEFORE the `=` opens the type annotation. A `:` after `=` (a
+      // ternary in the initializer) is NOT a type and must not suppress a real
+      // declarator comma.
+      if (ch === ':' && !seenEq) { inType = true; continue; }
+      // Inside a type annotation `<` / `>` are generic delimiters (a comparison
+      // only appears in the initializer, after `=`). Track their depth so a
+      // generic's comma (`Map<string, number>`) is skipped while a real
+      // declarator comma (`a: number, b: number`) still counts. A `>` that is
+      // part of a `=>` function-type arrow is not a generic close.
+      if (inType && ch === '<') { angle++; continue; }
+      if (inType && ch === '>' && scan[i - 1] !== '=') { if (angle > 0) angle--; continue; }
+      // A top-level comma starts a second declarator UNLESS it is a generic's
+      // comma inside a type annotation.
+      if (ch === ',' && !(inType && angle > 0)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Enumerate a module's provable named exports from its redacted `scan`, for the
+ * `no-missing-local-import` rule. Returns `null` when the export list is NOT
+ * fully enumerable (a `export *` star re-export, a destructuring export, or a
+ * multi-declarator `export const a = .., b = ..`), which tells the rule to treat
+ * the module as unknowable and flag nothing from it. Otherwise returns the set
+ * of exported names (the alias after `as` for a clause, and type/interface/enum
+ * names too, so a value import of a type is not falsely flagged; tsc owns that).
+ * @param {string} scan  string/template/comment-redacted source
+ * @returns {Set<string>|null}
+ */
+export function enumerableExports(scan) {
+  // Unknowable export shapes: bail so the rule never false-positives.
+  if (/\bexport\s*\*/.test(scan)) return null;                       // export * from
+  if (/\bexport\s+(?:const|let|var)\s*[{[]/.test(scan)) return null; // destructuring export
+  if (hasMultiDeclaratorExport(scan)) return null;                   // export const a=1, b=2
+  const names = new Set();
+  let m;
+  const collect = (re) => { while ((m = re.exec(scan))) names.add(m[1]); };
+  collect(/\bexport\s+(?:async\s+)?function\b\s*\*?\s*([A-Za-z_$][\w$]*)/g);
+  collect(/\bexport\s+(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/g);
+  collect(/\bexport\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)/g);
+  collect(/\bexport\s+(?:type|interface|enum|namespace)\s+([A-Za-z_$][\w$]*)/g);
+  // A named-default import (`import { default as Foo }`) is legal against an
+  // `export default` module, so record the `default` name when present.
+  if (/\bexport\s+default\b/.test(scan)) names.add('default');
+  // `export { a, b as c }` / `export type { ... }` / `export { x } from '...'`:
+  // the EXPORTED name is the alias after `as`, else the bare name.
+  const reClause = /\bexport\s+(?:type\s+)?\{([^}]*)\}/g;
+  while ((m = reClause.exec(scan))) {
+    for (let part of m[1].split(',')) {
+      part = part.trim().replace(/^type\s+/, '');
+      if (!part) continue;
+      const name = part.split(/\s+as\s+/).pop().trim();
+      if (/^[A-Za-z_$][\w$]*$/.test(name)) names.add(name);
+    }
+  }
+  return names;
+}
+
+/**
+ * The NAMED VALUE names a single `import { ... } from` clause pulls in, for the
+ * `no-missing-local-import` rule. Returns `null` for an `import type { ... }`
+ * (all type, skip), and `[]` for a default / namespace / side-effect import
+ * (nothing named to verify). A per-specifier inline `type` marker is dropped,
+ * and for `a as b` the IMPORTED name is `a` (what the target must export).
+ * @param {string} clause  the text between `import` and `from`
+ * @returns {string[]|null}
+ */
+/**
+ * The `{ local, imported }` pairs a named import clause binds, for a rule that
+ * has to match the LOCAL name against code (`action=${reader}`) while reporting
+ * the IMPORTED one (`readIt`, which is what the target module calls it).
+ *
+ * `importedValueNames` cannot serve here: it returns only the imported side,
+ * which is the wrong name to match against a template hole under `as`.
+ *
+ * @param {string} clause  the text between `import` and `from`
+ * @returns {{ local: string, imported: string }[]}
+ */
+export function importedLocalNames(clause) {
+  if (/^\s*type\b/.test(clause)) return [];
+  const brace = clause.match(/\{([^}]*)\}/);
+  if (!brace) return [];
+  /** @type {{ local: string, imported: string }[]} */
+  const out = [];
+  for (const part of brace[1].split(',')) {
+    const seg = part.trim().replace(/^type\s+/, '');
+    if (!seg) continue;
+    const as = seg.split(/\s+as\s+/);
+    const imported = as[0].trim();
+    const local = (as[1] || as[0]).trim();
+    if (/^[A-Za-z_$][\w$]*$/.test(local) && /^[A-Za-z_$][\w$]*$/.test(imported)) {
+      out.push({ local, imported });
+    }
+  }
+  return out;
+}
+
+export function importedValueNames(clause) {
+  if (/^\s*type\b/.test(clause)) return null; // import type { ... }
+  const brace = clause.match(/\{([^}]*)\}/);
+  if (!brace) return []; // default / namespace only
+  return brace[1].split(',')
+    .map((s) => s.trim())
+    .filter((s) => s && !/^type\s/.test(s))
+    .map((s) => s.split(/\s+as\s+/)[0].trim())
+    .filter((n) => /^[A-Za-z_$][\w$]*$/.test(n));
+}

package/src/check/rules-actions.js

@@ -0,0 +1,174 @@
+/**
+ * Server-action rules: where `'use server'` is honoured, what its exports must
+ * look like, and what a configured action file may contain.
+ *
+ * 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, basename } from 'node:path';
+import { RESERVED_CONFIG } from '../action-config.js';
+import {
+  hasUseServerDirective,
+} from './helpers.js';
+
+/**
+ * @typedef {import('./rules.js').Violation} Violation
+ * @typedef {{ abs: string, rel: string, content: string, scan: string }} ScannedFile
+ */
+
+
+/**
+ * Rule: `use-server-needs-extension`.
+ *
+ * @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 checkUseServerNeedsExtension(files, violations) {
+  // --- 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
+  // directive alone does nothing (the file is served to the browser as
+  // plain source and exports are not registered as RPC), which is a
+  // silent footgun. The fix is mechanical: rename the file.
+  {
+    for (const { rel, content } of files) {
+      if (!hasUseServerDirective(content)) continue;
+      if (/\.server\.m?[jt]s$/.test(rel)) continue; // OK: has both markers
+      const fileBase = basename(rel);
+      const renamedBase = fileBase.replace(/\.(m?[jt]sx?)$/, '.server.$1');
+      violations.push({
+        rule: 'use-server-needs-extension',
+        file: rel,
+        message:
+          "File declares `'use server'` but its name does not match `.server.{js,ts,mts,mjs}`. The directive is silently ignored: the file is served to the browser as plain source and its exports are not RPC-callable. Code the developer expects to run on the server actually runs in the browser.",
+        fix: `Rename to ${renamedBase} (add the .server. infix before the extension)`,
+      });
+    }
+  }
+}
+
+/**
+ * Rule: `use-server-exports-callable`.
+ *
+ * @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 checkUseServerExportsCallable(files, violations) {
+  // --- Rule: use-server-exports-callable (#464) ---
+  // A `.server.{js,ts}` file with the `'use server'` directive registers only
+  // its FUNCTION exports as RPC actions (the registrar checks `typeof === 'function'`).
+  // A file that declares the directive but exports no callable registers nothing,
+  // silently: the developer thinks they exposed an action, and the only signal is
+  // a 404 / undefined at the first call site. Flag it. The complement of
+  // use-server-needs-extension (the directive without the extension) and of
+  // one-action-per-configured-file (more than one action).
+  {
+    for (const { rel, content, scan } of files) {
+      // Only properly-marked action files (the extension boundary). A `'use
+      // server'` file WITHOUT the .server. extension is the use-server-needs-
+      // extension rule's job; do not double-flag it here.
+      if (!/\.server\.m?[jt]s$/.test(rel)) continue;
+      if (!hasUseServerDirective(content)) continue;
+      // Count function-shaped EXPORTED callables, the SAME way the action
+      // registrar sees them: function declarations + arrow / function-expression
+      // consts (with an optional `: Type` annotation, #495). Reserved verb-config
+      // names (method/cache/...) are config, never a callable action.
+      const names = new Set();
+      let m;
+      const reFn = /\bexport\s+(?:async\s+)?function\s*\*?\s+([A-Za-z_$][\w$]*)/g;
+      while ((m = reFn.exec(scan))) names.add(m[1]);
+      const reArrow = /\bexport\s+const\s+([A-Za-z_$][\w$]*)\s*(?::(?:[^=]|=>)*?)?=(?!>)\s*(?:async\s+)?(?:function\b|(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>)/g;
+      while ((m = reArrow.exec(scan))) names.add(m[1]);
+      const callables = [...names].filter((n) => !RESERVED_CONFIG.has(n));
+      if (callables.length > 0) continue; // exports at least one callable -> fine
+      // A default export is assumed callable (an action commonly default-exports).
+      if (/\bexport\s+default\b/.test(scan)) continue;
+      // Conservative, avoid a FALSE POSITIVE: the runtime registrar
+      // (`actionFunctionNames`) keeps EVERY export whose value is a function at
+      // load time, regardless of the export syntax, so any export shape these
+      // patterns cannot prove is non-callable must NOT be flagged. Skip when the
+      // file has:
+      //   - a named-export clause `export { a, b as c }` (with or WITHOUT `from`):
+      //     it can surface a local function (`function getX(){}; export { getX }`)
+      //     or a re-exported / imported function, neither matched above;
+      //   - a star re-export `export * from ...`;
+      //   - a destructuring export `export const { x } = obj` / `export const [x] = arr`,
+      //     which may bind a function;
+      //   - an `export const NAME = <identifier-or-call>`, a factory-produced
+      //     function (`export const get = cache(fetch)`).
+      // A sole `export { aConst }` of a non-function is then a tolerated FALSE
+      // NEGATIVE, which is the right bias for a non-overridable correctness rule.
+      if (/\bexport\s*\{/.test(scan)) continue;
+      if (/\bexport\s*\*/.test(scan)) continue;
+      if (/\bexport\s+(?:const|let|var)\s*[{[]/.test(scan)) continue;
+      // A factory / identifier-valued const could be a callable ACTION, so skip,
+      // BUT only when its name is NOT a reserved config key: the registrar
+      // excludes reserved names from actions (`actionFunctionNames`), so a file
+      // whose only ambiguous const is `validate` / `tags` / ... (config produced
+      // by an arrow or a factory) still has zero actions and must flag. Skip only
+      // for a NON-reserved ambiguous const (a real possible action).
+      const reFactory = /\bexport\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::(?:[^=]|=>)*?)?=\s*[A-Za-z_$(]/g;
+      let ambiguousAction = false;
+      while ((m = reFactory.exec(scan))) { if (!RESERVED_CONFIG.has(m[1])) { ambiguousAction = true; break; } }
+      if (ambiguousAction) continue;
+      // Every export is provably non-callable (a literal const, a type) or there
+      // are none: the directive exposes nothing.
+      violations.push({
+        rule: 'use-server-exports-callable',
+        file: rel,
+        message:
+          "File declares `'use server'` but exports no callable action. The `'use server'` directive registers FUNCTION exports as RPC-callable; a file exporting only a non-function (a `const` / a type / only verb config) registers nothing, so a client import resolves to nothing and the call 404s.",
+        fix: "Export an `async function` action from this file, or remove the `'use server'` directive if it is a plain server-only utility.",
+      });
+    }
+  }
+}
+
+/**
+ * Rule: `one-action-per-configured-file`.
+ *
+ * @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 checkOneActionPerConfiguredFile(files, violations) {
+  // --- Rule: one-action-per-configured-file (#488) ---
+  // A `'use server'` file that declares HTTP-verb config (method/cache/tags/
+  // invalidates/validate) must export exactly one callable action; the config
+  // is file-level, so a second exported function would silently inherit it.
+  {
+    for (const { rel, content, scan } of files) {
+      if (!/\.server\.m?[jt]s$/.test(rel)) continue;
+      if (!hasUseServerDirective(content)) continue;
+      if (!/\bexport\s+const\s+(?:method|cache|tags|invalidates|validate|middleware)\b/.test(scan)) continue;
+      const names = new Set();
+      let m;
+      const reFn = /\bexport\s+(?:async\s+)?function\s*\*?\s+([A-Za-z_$][\w$]*)/g;
+      while ((m = reFn.exec(scan))) names.add(m[1]);
+      // An arrow-const action: `export const x = (...) => ...`, the paren-less
+      // `export const x = id => ...`, or a function expression. The `=>` /
+      // `function` anchor keeps a plain `export const N = 5` from counting.
+      // An OPTIONAL `: Type` annotation may sit between the name and the `=`
+      // (#495); the type itself can contain a function-type `=>`, so the
+      // annotation matcher consumes any non-`=` char OR a literal `=>`, and the
+      // assignment is the first `=` NOT followed by `>` (`=(?!>)`). The
+      // alternation is unambiguous at each position (a `=` can only start `=>`),
+      // so there is no catastrophic backtracking.
+      const reArrow = /\bexport\s+const\s+([A-Za-z_$][\w$]*)\s*(?::(?:[^=]|=>)*?)?=(?!>)\s*(?:async\s+)?(?:function\b|(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>)/g;
+      while ((m = reArrow.exec(scan))) names.add(m[1]);
+      if (/\bexport\s+default\b/.test(scan)) names.add('default');
+      const actions = [...names].filter((n) => !RESERVED_CONFIG.has(n));
+      if (actions.length > 1) {
+        violations.push({
+          rule: 'one-action-per-configured-file',
+          file: rel,
+          message: `Configured action file exports ${actions.length} callable functions (${actions.join(', ')}); the verb/cache config is file-level, so only one action per file is allowed.`,
+          fix: 'Move the extra function to its own .server.{js,ts} file, or keep it private (do not export it).',
+        });
+      }
+    }
+  }
+}