@webjsdev/server 0.8.62 → 0.8.64

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

package/src/check/rules-components.js

@@ -0,0 +1,275 @@
+/**
+ * Component-authoring rules: registration, reactive-property declaration, and
+ * the SSR-safety of a component body.
+ *
+ * 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 {
+  extractWebComponentClassBodies, matchClosingBrace, parsePropEntries,
+} from '../js-scan.js';
+import {
+  isComponentFile, arrayPropUsesObject, findFieldInitializers, methodBodyOf,
+  findBrowserMemberUses,
+} from './helpers.js';
+
+/**
+ * @typedef {import('./rules.js').Violation} Violation
+ * @typedef {{ abs: string, rel: string, content: string, scan: string }} ScannedFile
+ */
+
+
+/**
+ * Rule: `components-have-register`.
+ *
+ * @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 checkComponentsHaveRegister(files, violations) {
+  // --- Rule: components-have-register ---
+  {
+    for (const { rel, scan } of files) {
+      if (!isComponentFile(rel)) 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(scan)) continue;
+      if (/\bcustomElements\.define\s*\(/.test(scan)) continue;
+      violations.push({
+        rule: 'components-have-register',
+        file: rel,
+        message: "Component extends WebComponent but is never registered. Call ClassName.register('tag-name') at the bottom of the file.",
+        fix: "Add `ClassName.register('tag-name')` after the class definition",
+      });
+    }
+  }
+}
+
+/**
+ * Rule: `no-static-properties`.
+ *
+ * @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 checkNoStaticProperties(files, violations) {
+  // --- Rule: no-static-properties ---
+  // A hand-written `static properties = { … }` in a WebComponent class body is
+  // no longer supported: reactive properties are declared via the
+  // `extends WebComponent({ … })` factory (the runtime throws on a direct
+  // `static properties`). Flag it statically so the editor catches it before
+  // the page 500s.
+  {
+    for (const { rel, scan } of files) {
+      // Use redacted source so fixture-style strings like
+      // `class X extends WebComponent { static properties = {…} }` 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)) {
+        if (!/static\s+properties\s*=\s*\{/.test(body)) continue;
+        violations.push({
+          rule: 'no-static-properties',
+          file: rel,
+          message:
+            '`static properties = { … }` is no longer supported; declare reactive properties via the `extends WebComponent({ … })` factory instead.',
+          fix: 'Move the properties into the factory call: `class X extends WebComponent({ count: Number })`. Use `prop(Number, { reflect: true })` for options and set defaults in the constructor after super(). Delete the `static properties` block and any `declare` fields for those props.',
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `reactive-props-no-class-field`.
+ *
+ * @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 checkReactivePropsNoClassField(files, violations) {
+  // --- Rule: reactive-props-no-class-field ---
+  // A reactive property declared via the factory must not also carry a plain
+  // class-field declaration (initializer OR type-only): under modern class-field
+  // semantics (including `erasableSyntaxOnly: true`) every class-field declaration
+  // compiles to Object.defineProperty after super() and clobbers the framework's
+  // reactive accessor (silent broken re-renders). Catches `count = 0`,
+  // `count: number = 0`, `count!: number`, and `count?: number`.
+  {
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { body, factoryProps } of extractWebComponentClassBodies(scan)) {
+        if (factoryProps.size === 0) continue;
+        for (const bad of findFieldInitializers(body, factoryProps)) {
+          violations.push({
+            rule: 'reactive-props-no-class-field',
+            file: rel,
+            message: `Reactive prop \`${bad}\` uses a class-field declaration (initializer or type-only); this clobbers the framework's reactive accessor under modern class-field semantics.`,
+            fix: `Delete the class-field declaration and set the default by assigning \`this.${bad} = <value>\` inside \`constructor()\` after \`super()\`.`,
+          });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `array-prop-uses-array-type`.
+ *
+ * @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 checkArrayPropUsesArrayType(files, violations) {
+  // --- Rule: array-prop-uses-array-type ---
+  // An array-typed reactive prop declared via the factory should pass the
+  // `Array` runtime constructor, not `Object`. Both share one converter
+  // (JSON encode/decode), so `Object` does not crash, but it misstates the
+  // prop contract and diverges from the documented built-in set. Fires only
+  // when the factory generic is itself an array type AND the constructor is
+  // `Object`; a bare `foo: Object` (no generic to prove array-ness) is left
+  // alone to avoid false positives. Uses the redacted `scan`, so a
+  // `prop<X[]>(Object)` shown inside an html`` example string never fires.
+  {
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { factoryArg } of extractWebComponentClassBodies(scan)) {
+        const objStart = factoryArg.indexOf('{');
+        if (objStart === -1) continue;
+        const objEnd = matchClosingBrace(factoryArg, objStart + 1);
+        if (objEnd === -1) continue;
+        const objContent = factoryArg.slice(objStart + 1, objEnd);
+        for (const { key, value } of parsePropEntries(objContent)) {
+          if (!arrayPropUsesObject(value)) continue;
+          violations.push({
+            rule: 'array-prop-uses-array-type',
+            file: rel,
+            message: `Array-typed reactive prop \`${key}\` is declared with the \`Object\` constructor (\`prop<…[]>(Object)\`); use \`Array\` so the runtime converter matches the declared shape.`,
+            fix: `Change the constructor to \`Array\`: \`${key}: prop<…[]>(Array)\`. Object and Array share one converter so behaviour is unchanged, but \`Array\` states the prop's shape correctly.`,
+          });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `no-browser-globals-in-render`.
+ *
+ * @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 checkNoBrowserGlobalsInRender(files, violations) {
+  // --- Rule: no-browser-globals-in-render ---
+  // The SSR pipeline runs the constructor (`new Cls()`), willUpdate, and
+  // render() on the server element shim (attribute methods backed, but no real
+  // DOM). A genuinely browser-only global or an unshimmed HTMLElement member on
+  // `this` touched in any of those throws at SSR time. Those belong in
+  // connectedCallback / post-render hooks, which SSR never calls. willUpdate is
+  // scanned because it now runs at SSR (issue #217).
+  {
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { body } of extractWebComponentClassBodies(scan)) {
+        for (const method of ['constructor', 'willUpdate', 'render']) {
+          const code = methodBodyOf(body, method);
+          if (!code) continue;
+          for (const { member, kind } of findBrowserMemberUses(code)) {
+            violations.push({
+              rule: 'no-browser-globals-in-render',
+              file: rel,
+              message: `\`${member}\` (${kind}) is used in ${method}(), which runs during SSR where it is not available, so it throws and the component fails to server-render.`,
+              fix: `Move browser-only work to connectedCallback() or a lifecycle hook (firstUpdated/updated), which SSR never calls. Seed first-paint defaults in the constructor only from server-known inputs (attributes / props), then refine in connectedCallback by writing to a signal.`,
+            });
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `no-shadowed-native-member`.
+ *
+ * @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 checkNoShadowedNativeMember(files, violations) {
+  // --- Rule: no-shadowed-native-member ---
+  // A WebComponent method named after a native DOM mutation method WebJs
+  // instruments on every light-DOM host for the slot API (#1021) is SHADOWED at
+  // runtime (the native/instrumented method wins), so the component method never
+  // runs, while TypeScript stays green (a shorter override is assignable). Rename
+  // the handler. The lifecycle hooks are meant to be overridden, so only the DOM
+  // mutation members are reserved.
+  {
+    const NATIVE_MEMBERS = [
+      'append', 'prepend', 'before', 'after', 'replaceWith', 'replaceChildren', 'remove',
+      'appendChild', 'insertBefore', 'removeChild', 'replaceChild',
+    ];
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { body } of extractWebComponentClassBodies(scan)) {
+        // The slot interception installs only on LIGHT-DOM hosts (the shadow
+        // branch keeps the true native methods), so a shadow component's method
+        // is never shadowed. Skip the whole class.
+        if (/static\s+shadow\s*=\s*true/.test(body)) continue;
+        // Brace-depth map over the (already string/comment-masked) class body,
+        // so only TOP-LEVEL class members flag: a same-named object-literal
+        // shorthand or function expression nested inside a method body is a
+        // different object's property and shadows nothing.
+        const depth = new Int32Array(body.length);
+        {
+          let d = 0;
+          for (let i = 0; i < body.length; i++) {
+            if (body[i] === '{') { depth[i] = d; d++; }
+            else if (body[i] === '}') { d--; depth[i] = d; }
+            else depth[i] = d;
+          }
+        }
+        for (const name of NATIVE_MEMBERS) {
+          // Two shadowed-definition shapes, both instance-level: the method /
+          // accessor form (`remove() {`, `get remove() {`), and the class-field
+          // FUNCTION form (`remove = () => {}` / `= function () {}`), which the
+          // connect-time interception install overwrites just the same. A
+          // `static` member lives on the constructor and shadows nothing.
+          const methodRe = new RegExp(
+            `(?:^|[\\s;}])((?:static\\s+)?)(?:async\\s+)?(?:get\\s+|set\\s+)?(${name})\\s*\\([^)]*\\)\\s*(?::[^{]*)?\\{`,
+            'g',
+          );
+          const fieldRe = new RegExp(
+            `(?:^|[\\s;}])((?:static\\s+)?)(${name})\\s*=\\s*(?:async\\s*)?(?:function\\b|\\([^)]*\\)\\s*(?::[^=]*)?=>|[\\w$]+\\s*=>)`,
+            'g',
+          );
+          let flagged = false;
+          for (const re of [methodRe, fieldRe]) {
+            let m;
+            while (!flagged && (m = re.exec(body)) !== null) {
+              if (m[1]) continue;                       // static: not shadowed
+              const nameIdx = m.index + m[0].indexOf(m[2]);
+              if (depth[nameIdx] !== 0) continue;       // nested: another object's property
+              flagged = true;
+              violations.push({
+                rule: 'no-shadowed-native-member',
+                file: rel,
+                message: `Component member \`${name}\` shadows the native DOM method WebJs instruments for the slot API, so it silently never runs (the native method wins) and TypeScript does not catch it.`,
+                fix: `Rename the member to a non-native name (e.g. \`${name}Row()\` / \`${name}Item()\`) and update its call sites.`,
+              });
+            }
+            if (flagged) break;
+          }
+        }
+      }
+    }
+  }
+}

package/src/check/rules-imports.js

@@ -0,0 +1,166 @@
+/**
+ * Import-graph rules: what a browser-bound module may reach, whether a local
+ * specifier resolves, and whether a bound form action can answer a POST.
+ *
+ * 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 { relative } from 'node:path';
+import {
+  redactStringsAndTemplates, redactToPlaceholders, classifyActionHole,
+} from '../js-scan.js';
+import { resolveImport } from '../module-graph.js';
+import {
+  hasUseServerDirective, enumerableExports, importedLocalNames, importedValueNames,
+} from './helpers.js';
+
+/**
+ * @typedef {import('./rules.js').Violation} Violation
+ * @typedef {{ abs: string, rel: string, content: string, scan: string }} ScannedFile
+ */
+
+/**
+ * Rule: `no-missing-local-import`.
+ *
+ * @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 {void}
+ */
+export function checkNoMissingLocalImport(appDir, files, violations) {
+  // --- Rule: no-missing-local-import ---
+  // A named value import of a symbol an app-internal module does not export is a
+  // runtime crash (the binding is undefined) that the elision-based checks miss,
+  // so `check` can stay green while `typecheck` is red (a dropped schema table
+  // orphaning a gallery module is the motivating dogfood case). Conservative by
+  // construction: only app-internal specifiers resolving to a known app file,
+  // only named value imports, and only when the target's exports are fully
+  // enumerable (see enumerableExports / importedValueNames).
+  {
+    // Fully-blanked view (blankStrings=true): string AND template AND comment
+    // bodies blank to spaces, position-preserving. The default `scan` keeps
+    // plain-string bodies VERBATIM (so callers can read `register('tag')`),
+    // which would let an `import`/`export` inside a string be matched, so use
+    // the fully-blanked view for both the export map and the import scan. The
+    // real specifier is read back from `content` at the same (length-preserved)
+    // offset.
+    const maskedByAbs = new Map();
+    for (const f of files) maskedByAbs.set(f.abs, redactStringsAndTemplates(f.content, true));
+    const exportsByAbs = new Map();
+    for (const f of files) exportsByAbs.set(f.abs, enumerableExports(maskedByAbs.get(f.abs)));
+    // `import\s+` excludes `import.meta` and a dynamic `import(`. The clause is
+    // `[^'";]*?` so it cannot swallow a side-effect `import '...'` (its quote) or
+    // bridge across a `;` into the next statement's `from`.
+    const reImport = /\bimport\s+([^'";]*?)\bfrom\s*(['"])/g;
+    for (const { abs, rel, content } of files) {
+      const masked = maskedByAbs.get(abs);
+      reImport.lastIndex = 0;
+      let m;
+      while ((m = reImport.exec(masked))) {
+        const quote = m[2];
+        const specStart = reImport.lastIndex;           // just past the opening quote
+        const specEnd = content.indexOf(quote, specStart);
+        if (specEnd < 0) continue;
+        const spec = content.slice(specStart, specEnd);
+        if (!/^(?:\.|#)/.test(spec)) continue; // app-internal only (relative or #alias)
+        const names = importedValueNames(m[1]);
+        if (!names || names.length === 0) continue;
+        const target = resolveImport(spec, abs, appDir);
+        const exp = exportsByAbs.get(target);
+        if (exp == null) continue; // not an app file, or exports not enumerable
+        for (const name of names) {
+          if (exp.has(name)) continue;
+          violations.push({
+            rule: 'no-missing-local-import',
+            file: rel,
+            message: `Imports \`${name}\` from \`${spec}\`, but that module does not export \`${name}\`. The binding is undefined at runtime and crashes on first use (often a renamed or removed export, e.g. a dropped schema table).`,
+            fix: `Add \`${name}\` to \`${spec}\`, correct the imported name, or remove the import.`,
+          });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `form-action-not-a-get-action`.
+ *
+ * @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 {void}
+ */
+export function checkFormActionNotAGetAction(appDir, files, violations) {
+  // --- Rule: form-action-not-a-get-action (#1155) ---
+  // `<form action=${fn}>` binds a server action to a POST submission. An action
+  // declaring `method = 'GET'` cannot serve one: it is CSRF-exempt and takes its
+  // args in the url, so the dispatcher answers 405. Catch it at edit time.
+  {
+    // A `'use server'` file's declared method, or absent when it declares none.
+    const methodByAbs = new Map();
+    for (const f of files) {
+      if (!/\.server\.m?[jt]s$/.test(f.rel)) continue;
+      if (!hasUseServerDirective(f.content)) continue;
+      const m = /\bexport\s+const\s+method\s*(?::[^=]*)?=\s*['"`]([A-Za-z]+)['"`]/.exec(f.scan);
+      if (m) methodByAbs.set(f.abs, m[1].toUpperCase());
+    }
+    if (methodByAbs.size) {
+      const reImport = /\bimport\s+([^'";]*?)\bfrom\s*(['"])/g;
+      for (const { abs, rel, content } of files) {
+        // PLACEHOLDER redaction, not either mask, and the choice is forced.
+        // The default mask blanks a tagged template outright, so a real
+        // `html`<form action=${fn}>`` disappears and the rule could never fire;
+        // the fully-blanked mask does the same. Placeholder mode keeps `${...}`
+        // holes as REAL code while turning each literal BODY into one opaque
+        // `__STR_n__` token, so a live binding is readable and a `<form
+        // action=${x}>` shown as text inside a docs sample is a single token
+        // with no hole in it. That distinction is the whole carve-out: the
+        // framework's own website renders this exact shape as a code sample.
+        const { redacted, literals } = redactToPlaceholders(content);
+        // Both binding shapes count the same here: `action=` on a `<form>`
+        // (#1155) and `formaction=` on a `<button>` / `<input>` submitter
+        // (#1207) each put the named action behind a form submission, and a
+        // GET-declared action cannot serve either. `classifyActionHole` owns
+        // the tag-and-attribute pairing (js-scan.js).
+        const bound = new Set();
+        for (const m of redacted.matchAll(/__STR_(\d+)__\$\{\s*([A-Za-z_$][\w$]*)\s*\}/g)) {
+          if (!classifyActionHole(literals[Number(m[1])] || '')) continue;
+          bound.add(m[2]);
+        }
+        if (!bound.size) continue;
+        reImport.lastIndex = 0;
+        let im;
+        while ((im = reImport.exec(redacted))) {
+          // The specifier is a placeholder token in this view, so read the real
+          // one back out of `literals`.
+          const tok = /__STR_(\d+)__/.exec(redacted.slice(reImport.lastIndex, reImport.lastIndex + 24));
+          if (!tok) continue;
+          const spec = literals[Number(tok[1])] || '';
+          if (!/^(?:\.|#)/.test(spec)) continue;
+          const names = importedLocalNames(im[1]);
+          if (!names.length) continue;
+          const target = resolveImport(spec, abs, appDir);
+          // ONLY a GET is contradictory, and the rule must say exactly what the
+          // dispatcher does or it is a false positive. A browser form always
+          // submits as a POST, and the dispatcher runs a PUT / PATCH / DELETE
+          // action on that POST: the declared verb governs the RPC transport,
+          // not whether the function can serve a form. A GET is different in
+          // kind (CSRF-exempt, args in the url, no body), which is why it is
+          // the one the dispatcher answers with a 405.
+          const method = target ? methodByAbs.get(target) : undefined;
+          if (method !== 'GET') continue;
+          for (const { local, imported } of names) {
+            if (!bound.has(local)) continue;
+            violations.push({
+              rule: 'form-action-not-a-get-action',
+              file: rel,
+              message: `Binds \`${imported}\` to a form, but \`${spec}\` declares \`method = 'GET'\`. A GET action rides its arguments in the url and skips the CSRF check, so it cannot answer a form POST; the submission is a 405.`,
+              fix: `Drop the \`method\` export from \`${spec}\` (an action with no method is a POST, which is what a form submits), or bind an action that takes a POST.`,
+            });
+          }
+        }
+      }
+    }
+  }
+}