@kernlang/review 3.2.3 → 3.3.5

package/dist/rules/nextjs-app-router.js

@@ -5,9 +5,10 @@
  * These rules require import-graph awareness — they gracefully no-op when run
  * in single-file mode (no ctx.fileContext).
  */
-import { basename } from 'path';
-import { Node, SyntaxKind } from 'ts-morph';
-import { finding } from './utils.js';
+import { existsSync } from 'fs';
+import { basename, dirname, resolve } from 'path';
+import { Node, Project, SyntaxKind } from 'ts-morph';
+import { finding, span } from './utils.js';
 // ── Helpers ──────────────────────────────────────────────────────────────
 const CLIENT_HOOKS = new Set([
     'useState',
@@ -40,17 +41,32 @@ const CLIENT_EVENT_HANDLERS = new Set([
     'onDrag',
 ]);
 const BROWSER_GLOBALS = /\b(window|document|localStorage|sessionStorage|navigator|history|location)\b/;
+const BROWSER_GLOBAL_NAMES = [
+    'window',
+    'document',
+    'localStorage',
+    'sessionStorage',
+    'navigator',
+    'history',
+    'location',
+];
+const ACTION_STATE_HOOKS = new Set(['useActionState']);
 function hasClientDirective(fullText) {
     return /^['"]use client['"];?\s*$/m.test(fullText.substring(0, 200));
 }
 function hasServerDirective(fullText) {
     return /^['"]use server['"];?\s*$/m.test(fullText.substring(0, 200));
 }
+function isHookLikeName(name) {
+    return CLIENT_HOOKS.has(name) || /^use[A-Z0-9]/.test(name);
+}
 /** Does this file itself use any client-only API (hooks, browser globals, event handlers)? */
 function fileUsesClientApi(ctx) {
-    const fullText = ctx.sourceFile.getFullText();
-    if (BROWSER_GLOBALS.test(fullText))
-        return true;
+    for (const identifier of ctx.sourceFile.getDescendantsOfKind(SyntaxKind.Identifier)) {
+        const name = identifier.getText();
+        if (BROWSER_GLOBAL_NAMES.includes(name) && isBrowserGlobalReference(identifier, name))
+            return true;
+    }
     // JSX event handlers
     for (const attr of ctx.sourceFile.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
         const name = attr.getNameNode().getText();
@@ -61,17 +77,619 @@ function fileUsesClientApi(ctx) {
     for (const call of ctx.sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
         const expr = call.getExpression();
         if (expr.getKind() === SyntaxKind.Identifier) {
-            if (CLIENT_HOOKS.has(expr.getText()))
+            if (isHookLikeName(expr.getText()))
                 return true;
         }
         else if (expr.getKind() === SyntaxKind.PropertyAccessExpression) {
             const prop = expr.asKind(SyntaxKind.PropertyAccessExpression);
-            if (prop && CLIENT_HOOKS.has(prop.getName()))
+            if (prop && isHookLikeName(prop.getName()))
+                return true;
+        }
+    }
+    return false;
+}
+function isClientBoundary(ctx, fullText) {
+    return (hasClientDirective(fullText) || ctx.fileContext?.isClientBoundary === true || ctx.fileContext?.boundary === 'client');
+}
+function unwrapParens(node) {
+    let current = node;
+    while (Node.isParenthesizedExpression(current)) {
+        current = current.getExpression();
+    }
+    return current;
+}
+function isNodeWithin(node, container) {
+    if (!container)
+        return false;
+    return node.getStart() >= container.getStart() && node.getEnd() <= container.getEnd();
+}
+function getTypeofGuardState(node, globalName) {
+    const expr = unwrapParens(node);
+    if (!Node.isBinaryExpression(expr))
+        return undefined;
+    const operator = expr.getOperatorToken().getText();
+    if (operator !== '===' && operator !== '==' && operator !== '!==' && operator !== '!=')
+        return undefined;
+    const left = unwrapParens(expr.getLeft());
+    const right = unwrapParens(expr.getRight());
+    const isTypeofGlobal = (candidate) => Node.isTypeOfExpression(candidate) &&
+        Node.isIdentifier(candidate.getExpression()) &&
+        candidate.getExpression().getText() === globalName;
+    const isUndefinedLiteral = (candidate) => Node.isStringLiteral(candidate) && candidate.getLiteralText() === 'undefined';
+    if (!((isTypeofGlobal(left) && isUndefinedLiteral(right)) || (isUndefinedLiteral(left) && isTypeofGlobal(right)))) {
+        return undefined;
+    }
+    return operator === '!==' || operator === '!=' ? 'defined' : 'undefined';
+}
+function conditionGuaranteesBrowserGlobal(node, globalName, branch) {
+    const expr = unwrapParens(node);
+    const state = getTypeofGuardState(expr, globalName);
+    if (state)
+        return branch === 'true' ? state === 'defined' : state === 'undefined';
+    if (Node.isPrefixUnaryExpression(expr) && expr.getOperatorToken() === SyntaxKind.ExclamationToken) {
+        return conditionGuaranteesBrowserGlobal(expr.getOperand(), globalName, branch === 'true' ? 'false' : 'true');
+    }
+    if (!Node.isBinaryExpression(expr))
+        return false;
+    const operator = expr.getOperatorToken().getText();
+    if (branch === 'true' && operator === '&&') {
+        return (conditionGuaranteesBrowserGlobal(expr.getLeft(), globalName, 'true') ||
+            conditionGuaranteesBrowserGlobal(expr.getRight(), globalName, 'true'));
+    }
+    if (branch === 'false' && operator === '||') {
+        return (conditionGuaranteesBrowserGlobal(expr.getLeft(), globalName, 'false') ||
+            conditionGuaranteesBrowserGlobal(expr.getRight(), globalName, 'false'));
+    }
+    return false;
+}
+function isBrowserGlobalReference(node, globalName) {
+    if (!Node.isIdentifier(node) || node.getText() !== globalName)
+        return false;
+    const parent = node.getParent();
+    if (!parent)
+        return false;
+    if (parent.getKind() === SyntaxKind.TypeOfExpression)
+        return false;
+    if (Node.isPropertyAccessExpression(parent) && parent.getNameNode() === node)
+        return false;
+    if (Node.isPropertyAssignment(parent) && parent.getNameNode() === node)
+        return false;
+    if (Node.isPropertyDeclaration(parent) && parent.getNameNode() === node)
+        return false;
+    if (Node.isPropertySignature(parent) && parent.getNameNode() === node)
+        return false;
+    if (Node.isMethodDeclaration(parent) && parent.getNameNode() === node)
+        return false;
+    if (Node.isShorthandPropertyAssignment(parent) && parent.getNameNode() === node) {
+        const decls = node.getSymbol()?.getDeclarations() ?? [];
+        return decls.every((decl) => decl.getSourceFile() !== node.getSourceFile());
+    }
+    if (Node.isImportSpecifier(parent) || Node.isBindingElement(parent) || Node.isParameterDeclaration(parent))
+        return false;
+    if (Node.isVariableDeclaration(parent) && parent.getNameNode() === node)
+        return false;
+    if (Node.isFunctionDeclaration(parent) && parent.getNameNode() === node)
+        return false;
+    if (Node.isClassDeclaration(parent) && parent.getNameNode() === node)
+        return false;
+    if (Node.isTypeReference(parent) || Node.isQualifiedName(parent) || Node.isTypeAliasDeclaration(parent))
+        return false;
+    const declarations = node.getSymbol()?.getDeclarations() ?? [];
+    if (declarations.some((decl) => decl.getSourceFile() === node.getSourceFile()))
+        return false;
+    return true;
+}
+function isGuardedBrowserGlobalUse(node, globalName) {
+    let current = node;
+    while ((current = current.getParent())) {
+        if (Node.isIfStatement(current)) {
+            if (isNodeWithin(node, current.getThenStatement()) &&
+                conditionGuaranteesBrowserGlobal(current.getExpression(), globalName, 'true')) {
+                return true;
+            }
+            if (isNodeWithin(node, current.getElseStatement()) &&
+                conditionGuaranteesBrowserGlobal(current.getExpression(), globalName, 'false')) {
+                return true;
+            }
+        }
+        if (Node.isConditionalExpression(current)) {
+            if (isNodeWithin(node, current.getWhenTrue()) &&
+                conditionGuaranteesBrowserGlobal(current.getCondition(), globalName, 'true')) {
+                return true;
+            }
+            if (isNodeWithin(node, current.getWhenFalse()) &&
+                conditionGuaranteesBrowserGlobal(current.getCondition(), globalName, 'false')) {
+                return true;
+            }
+        }
+        if (Node.isBinaryExpression(current) && isNodeWithin(node, current.getRight())) {
+            const operator = current.getOperatorToken().getText();
+            if (operator === '&&' && conditionGuaranteesBrowserGlobal(current.getLeft(), globalName, 'true'))
                 return true;
+            if (operator === '||' && conditionGuaranteesBrowserGlobal(current.getLeft(), globalName, 'false'))
+                return true;
+        }
+    }
+    return false;
+}
+function getReactActionStateBindings(ctx) {
+    const reactImports = ctx.sourceFile
+        .getImportDeclarations()
+        .filter((decl) => decl.getModuleSpecifierValue() === 'react');
+    if (reactImports.length === 0)
+        return [];
+    const importedHookNames = new Set();
+    const namespaceImports = new Set();
+    for (const decl of reactImports) {
+        for (const named of decl.getNamedImports()) {
+            if (ACTION_STATE_HOOKS.has(named.getName())) {
+                importedHookNames.add(named.getAliasNode()?.getText() ?? named.getName());
+            }
+        }
+        const namespace = decl.getNamespaceImport();
+        if (namespace)
+            namespaceImports.add(namespace.getText());
+    }
+    if (importedHookNames.size === 0 && namespaceImports.size === 0)
+        return [];
+    const bindings = [];
+    for (const decl of ctx.sourceFile.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+        const nameNode = decl.getNameNode();
+        const init = decl.getInitializer();
+        if (!Node.isArrayBindingPattern(nameNode) || !init || !Node.isCallExpression(init))
+            continue;
+        const expr = init.getExpression();
+        let isActionStateCall = false;
+        if (Node.isIdentifier(expr)) {
+            isActionStateCall = importedHookNames.has(expr.getText());
+        }
+        else if (Node.isPropertyAccessExpression(expr)) {
+            isActionStateCall =
+                namespaceImports.has(expr.getExpression().getText()) && ACTION_STATE_HOOKS.has(expr.getName());
+        }
+        if (!isActionStateCall)
+            continue;
+        const elements = nameNode.getElements();
+        if (elements.length < 2)
+            continue;
+        const actionElement = elements[1];
+        if (!Node.isBindingElement(actionElement))
+            continue;
+        const actionNameNode = actionElement.getNameNode();
+        if (!Node.isIdentifier(actionNameNode))
+            continue;
+        const pendingElement = elements[2];
+        const hasPendingBinding = pendingElement !== undefined &&
+            Node.isBindingElement(pendingElement) &&
+            Node.isIdentifier(pendingElement.getNameNode()) &&
+            pendingElement.getNameNode().getText().trim().length > 0;
+        const stateElement = elements[0];
+        const stateNameNode = stateElement !== undefined &&
+            Node.isBindingElement(stateElement) &&
+            Node.isIdentifier(stateElement.getNameNode()) &&
+            stateElement.getNameNode().getText().trim().length > 0
+            ? stateElement.getNameNode()
+            : undefined;
+        bindings.push({
+            decl,
+            stateNameNode,
+            actionName: actionNameNode.getText(),
+            hasPendingBinding,
+        });
+    }
+    return bindings;
+}
+function isActionBoundInJsx(ctx, actionName) {
+    return ctx.sourceFile.getDescendantsOfKind(SyntaxKind.JsxAttribute).some((attr) => {
+        const attrName = attr.getNameNode().getText();
+        if (attrName !== 'action' && attrName !== 'formAction')
+            return false;
+        const initNode = attr.getInitializer();
+        if (!initNode || !Node.isJsxExpression(initNode))
+            return false;
+        const expression = initNode.getExpression();
+        return expression?.getText() === actionName;
+    });
+}
+function hasNonDeclarationReferenceInFile(ctx, identifier) {
+    if (!Node.isIdentifier(identifier))
+        return false;
+    const declarations = identifier.getSymbol()?.getDeclarations() ?? [];
+    if (declarations.length === 0)
+        return false;
+    for (const candidate of ctx.sourceFile.getDescendantsOfKind(SyntaxKind.Identifier)) {
+        if (candidate === identifier)
+            continue;
+        if (candidate.getText() !== identifier.getText())
+            continue;
+        const candidateDeclarations = candidate.getSymbol()?.getDeclarations() ?? [];
+        if (candidateDeclarations.length === 0)
+            continue;
+        const sameBinding = candidateDeclarations.some((decl) => declarations.includes(decl));
+        if (!sameBinding)
+            continue;
+        return true;
+    }
+    return false;
+}
+function getJsxTagName(node) {
+    return node.getTagNameNode().getText();
+}
+function getJsxAttributes(node) {
+    return node.getAttributes();
+}
+function getJsxExpressionAttribute(node, attrName) {
+    for (const attr of getJsxAttributes(node)) {
+        if (!Node.isJsxAttribute(attr) || attr.getNameNode().getText() !== attrName)
+            continue;
+        const init = attr.getInitializer();
+        if (!init || !Node.isJsxExpression(init))
+            return undefined;
+        return init.getExpression() ?? undefined;
+    }
+    return undefined;
+}
+function getStringAttribute(node, attrName) {
+    for (const attr of getJsxAttributes(node)) {
+        if (!Node.isJsxAttribute(attr) || attr.getNameNode().getText() !== attrName)
+            continue;
+        const init = attr.getInitializer();
+        if (!init || !Node.isStringLiteral(init))
+            return undefined;
+        return init.getLiteralText();
+    }
+    return undefined;
+}
+function isSubmitControl(node) {
+    const tagName = getJsxTagName(node);
+    if (tagName === 'button') {
+        const typeAttr = getStringAttribute(node, 'type');
+        return typeAttr === undefined || typeAttr === 'submit';
+    }
+    if (tagName === 'input') {
+        const typeAttr = getStringAttribute(node, 'type');
+        return typeAttr === 'submit' || typeAttr === 'image';
+    }
+    return false;
+}
+function fileUsesUseFormStatus(ctx) {
+    const imports = ctx.sourceFile
+        .getImportDeclarations()
+        .filter((decl) => decl.getModuleSpecifierValue() === 'react-dom');
+    if (imports.length === 0)
+        return false;
+    const importedHookNames = new Set();
+    const namespaceImports = new Set();
+    for (const decl of imports) {
+        for (const named of decl.getNamedImports()) {
+            if (named.getName() === 'useFormStatus')
+                importedHookNames.add(named.getAliasNode()?.getText() ?? named.getName());
+        }
+        const namespace = decl.getNamespaceImport();
+        if (namespace)
+            namespaceImports.add(namespace.getText());
+    }
+    for (const call of ctx.sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const expr = call.getExpression();
+        if (Node.isIdentifier(expr) && importedHookNames.has(expr.getText()))
+            return true;
+        if (Node.isPropertyAccessExpression(expr) &&
+            namespaceImports.has(expr.getExpression().getText()) &&
+            expr.getName() === 'useFormStatus') {
+            return true;
+        }
+    }
+    return false;
+}
+function functionLikeHasUseServerDirective(node) {
+    if (!Node.isFunctionDeclaration(node) && !Node.isFunctionExpression(node) && !Node.isArrowFunction(node))
+        return false;
+    const body = node.getBody();
+    if (!body)
+        return false;
+    return /['"]use server['"]/.test(body.getText().substring(0, 100));
+}
+function functionLikeIsAsync(node) {
+    if (Node.isFunctionDeclaration(node) || Node.isFunctionExpression(node) || Node.isArrowFunction(node)) {
+        return node.isAsync();
+    }
+    return false;
+}
+function resolveImportSourceFile(ctx, importDecl) {
+    let resolvedSourceFile;
+    try {
+        resolvedSourceFile = importDecl.getModuleSpecifierSourceFile() ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+    if (resolvedSourceFile) {
+        // The shared fsProject caches resolved source files across reviewFile calls; refresh so edits
+        // in the imported file (watch mode, repeated reviewFile invocations) are picked up.
+        try {
+            resolvedSourceFile.refreshFromFileSystemSync();
+        }
+        catch {
+            // File may have been deleted — leave the (now-stale) reference; caller decides what to do.
+        }
+        return resolvedSourceFile;
+    }
+    const specifier = importDecl.getModuleSpecifierValue();
+    if (!specifier.startsWith('.'))
+        return undefined;
+    const project = ctx.sourceFile.getProject();
+    const fromDir = dirname(ctx.sourceFile.getFilePath());
+    const fallbackCandidates = [specifier];
+    if (specifier.endsWith('.js')) {
+        fallbackCandidates.push(`${specifier.slice(0, -3)}.ts`, `${specifier.slice(0, -3)}.tsx`);
+    }
+    else if (specifier.endsWith('.jsx')) {
+        fallbackCandidates.push(`${specifier.slice(0, -4)}.tsx`);
+    }
+    else {
+        fallbackCandidates.push(`${specifier}.ts`, `${specifier}.tsx`, `${specifier}/index.ts`, `${specifier}/index.tsx`);
+    }
+    for (const candidate of fallbackCandidates) {
+        const fullPath = resolve(fromDir, candidate);
+        if (!existsSync(fullPath))
+            continue;
+        const sourceFile = project.getSourceFile(fullPath);
+        if (sourceFile)
+            return sourceFile;
+        try {
+            return project.addSourceFileAtPath(fullPath);
+        }
+        catch {
+            try {
+                return new Project({
+                    compilerOptions: {
+                        strict: true,
+                        target: 99,
+                        module: 99,
+                        moduleResolution: 100,
+                        jsx: 4 /* Preserve */,
+                        allowJs: true,
+                        esModuleInterop: true,
+                        allowSyntheticDefaultImports: true,
+                    },
+                }).addSourceFileAtPath(fullPath);
+            }
+            catch {
+                // Keep trying other extension fallbacks.
+            }
+        }
+    }
+    return undefined;
+}
+function resolveExportedServerActionFunctions(sourceFile, exportName) {
+    const resolved = [];
+    if (!sourceFile)
+        return resolved;
+    const fileHasUseServer = hasServerDirective(sourceFile.getFullText());
+    for (const fn of sourceFile.getFunctions()) {
+        if (!fn.isExported() || fn.getName() !== exportName || !fn.isAsync())
+            continue;
+        if (functionLikeHasUseServerDirective(fn) || (fileHasUseServer && fn.isExported()))
+            resolved.push(fn);
+    }
+    for (const stmt of sourceFile.getVariableStatements()) {
+        if (!stmt.isExported())
+            continue;
+        for (const decl of stmt.getDeclarations()) {
+            if (decl.getName() !== exportName)
+                continue;
+            const init = decl.getInitializer();
+            if (!init || (!Node.isArrowFunction(init) && !Node.isFunctionExpression(init)) || !init.isAsync())
+                continue;
+            if (functionLikeHasUseServerDirective(init) || fileHasUseServer)
+                resolved.push(init);
+        }
+    }
+    return resolved;
+}
+function resolveImportedServerActionFunctions(ctx, decl) {
+    if (Node.isImportSpecifier(decl)) {
+        return resolveExportedServerActionFunctions(resolveImportSourceFile(ctx, decl.getImportDeclaration()), decl.getName());
+    }
+    if (Node.isNamespaceImport(decl))
+        return [];
+    return [];
+}
+function resolveDirectImportedServerActionFunctions(ctx, expr) {
+    if (Node.isIdentifier(expr)) {
+        for (const decl of ctx.sourceFile.getImportDeclarations()) {
+            for (const named of decl.getNamedImports()) {
+                const localName = named.getAliasNode()?.getText() ?? named.getName();
+                if (localName !== expr.getText())
+                    continue;
+                return resolveExportedServerActionFunctions(resolveImportSourceFile(ctx, decl), named.getName());
+            }
+        }
+        return [];
+    }
+    if (Node.isPropertyAccessExpression(expr) && Node.isIdentifier(expr.getExpression())) {
+        const namespaceName = expr.getExpression().getText();
+        for (const decl of ctx.sourceFile.getImportDeclarations()) {
+            const namespaceImport = decl.getNamespaceImport();
+            if (!namespaceImport || namespaceImport.getText() !== namespaceName)
+                continue;
+            return resolveExportedServerActionFunctions(resolveImportSourceFile(ctx, decl), expr.getName());
+        }
+    }
+    return [];
+}
+function resolveServerActionFunctions(ctx, expr) {
+    const resolved = [];
+    if (!expr)
+        return resolved;
+    const candidate = unwrapParens(expr);
+    if ((Node.isFunctionExpression(candidate) || Node.isArrowFunction(candidate)) && functionLikeIsAsync(candidate)) {
+        if (functionLikeHasUseServerDirective(candidate))
+            resolved.push(candidate);
+        return resolved;
+    }
+    const directImportedActions = resolveDirectImportedServerActionFunctions(ctx, candidate);
+    if (directImportedActions.length > 0)
+        return directImportedActions;
+    if (Node.isPropertyAccessExpression(candidate)) {
+        const objectExpr = candidate.getExpression();
+        if (!Node.isIdentifier(objectExpr))
+            return resolved;
+        const declarations = objectExpr.getSymbol()?.getDeclarations() ?? [];
+        for (const decl of declarations) {
+            if (!Node.isNamespaceImport(decl))
+                continue;
+            const importDecl = decl.getFirstAncestorByKind(SyntaxKind.ImportDeclaration);
+            const sourceFile = importDecl ? resolveImportSourceFile(ctx, importDecl) : undefined;
+            resolved.push(...resolveExportedServerActionFunctions(sourceFile, candidate.getName()));
+        }
+        return resolved;
+    }
+    if (!Node.isIdentifier(candidate))
+        return resolved;
+    const declarations = candidate.getSymbol()?.getDeclarations() ?? [];
+    for (const decl of declarations) {
+        if (Node.isImportSpecifier(decl)) {
+            resolved.push(...resolveImportedServerActionFunctions(ctx, decl));
+            continue;
+        }
+        if (decl.getSourceFile() !== ctx.sourceFile) {
+            resolved.push(...resolveImportedServerActionFunctions(ctx, decl));
+            continue;
+        }
+        if (Node.isFunctionDeclaration(decl) && decl.isAsync()) {
+            const fileHasUseServer = hasServerDirective(ctx.sourceFile.getFullText());
+            if (functionLikeHasUseServerDirective(decl) || (fileHasUseServer && decl.isExported()))
+                resolved.push(decl);
+        }
+        if (Node.isVariableDeclaration(decl)) {
+            const init = decl.getInitializer();
+            if (!init || (!Node.isArrowFunction(init) && !Node.isFunctionExpression(init)) || !init.isAsync())
+                continue;
+            const fileHasUseServer = hasServerDirective(ctx.sourceFile.getFullText());
+            const variableStatement = decl.getVariableStatement();
+            if (functionLikeHasUseServerDirective(init) || (fileHasUseServer && variableStatement?.isExported())) {
+                resolved.push(init);
+            }
+        }
+    }
+    return resolved;
+}
+function isServerActionReference(ctx, expr) {
+    return resolveServerActionFunctions(ctx, expr).length > 0;
+}
+function hasNativeSubmitDescendant(form) {
+    const opening = form.getOpeningElement();
+    if (isSubmitControl(opening))
+        return true;
+    for (const child of form.getDescendants()) {
+        if (Node.isJsxOpeningElement(child) && isSubmitControl(child))
+            return true;
+        if (Node.isJsxSelfClosingElement(child) && isSubmitControl(child))
+            return true;
+    }
+    return false;
+}
+function functionReturnsValue(node) {
+    const body = node.getBody();
+    if (!body || !Node.isBlock(body))
+        return false;
+    for (const stmt of body.getDescendantsOfKind(SyntaxKind.ReturnStatement)) {
+        const expr = stmt.getExpression();
+        if (!expr)
+            continue;
+        if (Node.isIdentifier(expr) && expr.getText() === 'undefined')
+            continue;
+        if (Node.isVoidExpression(expr))
+            continue;
+        if (Node.isCallExpression(expr) &&
+            Node.isIdentifier(expr.getExpression()) &&
+            ['redirect', 'permanentRedirect', 'notFound'].includes(expr.getExpression().getText())) {
+            continue;
         }
+        return true;
+    }
+    return false;
+}
+const POST_SUBMIT_CLOSURE_CALLS = new Set([
+    'revalidatePath',
+    'revalidateTag',
+    'updateTag',
+    'refresh',
+    'redirect',
+    'permanentRedirect',
+    'notFound',
+]);
+const MUTATION_CALL_RE = /\b(create|update|delete|remove|insert|upsert|save|write|publish|archive|destroy|replace)\b/i;
+const MUTATION_FETCH_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+function functionCallsPostSubmitClosure(node) {
+    const body = node.getBody();
+    if (!body)
+        return false;
+    for (const call of body.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const expr = call.getExpression();
+        if (Node.isIdentifier(expr) && POST_SUBMIT_CLOSURE_CALLS.has(expr.getText()))
+            return true;
+        if (Node.isPropertyAccessExpression(expr) && POST_SUBMIT_CLOSURE_CALLS.has(expr.getName()))
+            return true;
     }
     return false;
 }
+function isKnownInputCarrier(node) {
+    if (!Node.isIdentifier(node))
+        return false;
+    const typeText = node.getType().getText(node);
+    return (typeText.includes('FormData') ||
+        typeText.includes('URLSearchParams') ||
+        typeText.includes('Headers') ||
+        ['formData', 'searchParams', 'headers'].includes(node.getText()));
+}
+function getMutationCall(node) {
+    const body = node.getBody();
+    if (!body)
+        return undefined;
+    for (const call of body.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const expr = call.getExpression();
+        if (Node.isIdentifier(expr)) {
+            if (expr.getText() === 'fetch') {
+                const options = call.getArguments()[1];
+                if (!options || !Node.isObjectLiteralExpression(options))
+                    continue;
+                const methodProp = options
+                    .getProperties()
+                    .find((prop) => Node.isPropertyAssignment(prop) &&
+                    prop.getName() === 'method' &&
+                    Node.isStringLiteral(prop.getInitializer() ?? undefined));
+                if (!methodProp || !Node.isPropertyAssignment(methodProp))
+                    continue;
+                const methodInit = methodProp.getInitializer();
+                if (!methodInit || !Node.isStringLiteral(methodInit))
+                    continue;
+                if (MUTATION_FETCH_METHODS.has(methodInit.getLiteralText().toUpperCase()))
+                    return call;
+                continue;
+            }
+            if (MUTATION_CALL_RE.test(expr.getText()))
+                return call;
+            continue;
+        }
+        if (!Node.isPropertyAccessExpression(expr))
+            continue;
+        if (isKnownInputCarrier(expr.getExpression()))
+            continue;
+        if (MUTATION_CALL_RE.test(expr.getName()))
+            return call;
+    }
+    return undefined;
+}
+function getFunctionLikeName(node) {
+    if (Node.isFunctionDeclaration(node))
+        return node.getName() ?? '<anon>';
+    const parent = node.getParent();
+    if (Node.isVariableDeclaration(parent))
+        return parent.getName();
+    return '<anon>';
+}
 // ── Rule: use-client-drilled-too-high ────────────────────────────────────
 // File has 'use client' but doesn't actually use any client API itself.
 // Its children do. Moving the directive down would preserve RSC benefits.
@@ -88,28 +706,69 @@ function useClientDrilledTooHigh(ctx) {
     // when the file has child imports that DO use client APIs — but we can't
     // cheaply check that without the full fileContextMap. Fire as a warning
     // either way; severity bumps to error when we can prove a child needs it.
-    let severity = 'warning';
+    const severity = 'warning';
     let detail = 'File has "use client" but uses no hooks, event handlers, or browser APIs itself.';
-    const fileContextMap = ctx.config?.fileContextMap;
-    if (fileContextMap) {
-        // If at least one imported child has its own 'use client' or needs one, this is a drilled directive.
-        const gfImports = [...fileContextMap.entries()]
-            .filter(([, v]) => v.importedBy.includes(ctx.filePath))
-            .map(([k]) => k);
-        if (gfImports.length > 0) {
-            severity = 'warning';
-            detail += ` Imported children: ${gfImports
-                .slice(0, 3)
-                .map((p) => basename(p))
-                .join(', ')}${gfImports.length > 3 ? '…' : ''}.`;
+    let importedChildren = [];
+    const graphFile = ctx.config?.graphFileMap?.get(ctx.filePath);
+    if (graphFile && graphFile.imports.length > 0) {
+        importedChildren = graphFile.imports;
+        detail += ` Imported children: ${importedChildren
+            .slice(0, 3)
+            .map((p) => basename(p))
+            .join(', ')}${importedChildren.length > 3 ? '…' : ''}.`;
+    }
+    else {
+        const fileContextMap = ctx.config?.fileContextMap;
+        if (fileContextMap) {
+            // Fallback for older graph-aware callers that only provide fileContextMap.
+            importedChildren = [...fileContextMap.entries()]
+                .filter(([, v]) => v.importedBy.includes(ctx.filePath))
+                .map(([k]) => k);
+            if (importedChildren.length > 0) {
+                detail += ` Imported children: ${importedChildren
+                    .slice(0, 3)
+                    .map((p) => basename(p))
+                    .join(', ')}${importedChildren.length > 3 ? '…' : ''}.`;
+            }
         }
     }
     const line = 1;
-    return [
-        finding('use-client-drilled-too-high', severity, 'pattern', `'use client' directive is drilled too high — ${detail} Move it to the leaf component that actually uses client APIs to preserve Server Component benefits.`, ctx.filePath, line, 1, {
-            suggestion: 'Remove the top-level "use client" and add it to only the child component(s) that use hooks or browser APIs',
-        }),
-    ];
+    const result = finding('use-client-drilled-too-high', severity, 'pattern', `'use client' directive is drilled too high — ${detail} Move it to the leaf component that actually uses client APIs to preserve Server Component benefits.`, ctx.filePath, line, 1, {
+        suggestion: 'Remove the top-level "use client" and add it to only the child component(s) that use hooks or browser APIs',
+    });
+    result.relatedSpans = importedChildren.slice(0, 3).map((child) => ({
+        file: child,
+        startLine: 1,
+        startCol: 1,
+        endLine: 1,
+        endCol: 1,
+    }));
+    result.provenance = {
+        summary: importedChildren.length > 0
+            ? `"use client" sits above ${importedChildren.length} imported child${importedChildren.length === 1 ? '' : 'ren'} while this file uses no client-only APIs itself.`
+            : '"use client" is present, but the file itself has no local client-only API usage.',
+        steps: [
+            {
+                kind: 'boundary',
+                location: { file: ctx.filePath, startLine: 1, startCol: 1, endLine: 1, endCol: 1 },
+                label: `'use client'`,
+                detail: 'Client boundary is declared at the top of this file.',
+            },
+            {
+                kind: 'boundary',
+                location: { file: ctx.filePath, startLine: 1, startCol: 1, endLine: 1, endCol: 1 },
+                label: 'no local client API usage',
+                detail: 'This file does not use hooks, event handlers, or browser globals directly.',
+            },
+            ...importedChildren.slice(0, 3).map((child) => ({
+                kind: 'import',
+                location: { file: child, startLine: 1, startCol: 1, endLine: 1, endCol: 1 },
+                label: basename(child),
+                detail: 'Imported child under the same declared client boundary.',
+            })),
+        ],
+    };
+    return [result];
 }
 // ── Rule: server-api-in-client ───────────────────────────────────────────
 // Client Component imports or calls server-only APIs:
@@ -121,7 +780,7 @@ function serverApiInClient(ctx) {
     if (ctx.fileRole !== 'runtime')
         return [];
     const fullText = ctx.sourceFile.getFullText();
-    const isClient = hasClientDirective(fullText) || ctx.fileContext?.isClientBoundary === true;
+    const isClient = isClientBoundary(ctx, fullText);
     if (!isClient)
         return [];
     const findings = [];
@@ -129,9 +788,33 @@ function serverApiInClient(ctx) {
     for (const imp of ctx.sourceFile.getImportDeclarations()) {
         const mod = imp.getModuleSpecifierValue();
         if (mod === 'next/headers' || mod === 'server-only') {
-            findings.push(finding('server-api-in-client', 'error', 'bug', `Client Component imports '${mod}' — this will fail at build time. Server-only APIs cannot run in a client boundary.`, ctx.filePath, imp.getStartLineNumber(), 1, {
+            const hit = finding('server-api-in-client', 'error', 'bug', `Client Component imports '${mod}' — this will fail at build time. Server-only APIs cannot run in a client boundary.`, ctx.filePath, imp.getStartLineNumber(), 1, {
                 suggestion: `Move this logic to a Server Component or a server action, or drop the 'use client' directive if this file does not need it`,
-            }));
+            });
+            hit.provenance = {
+                summary: `Client boundary imports server-only module '${mod}'.`,
+                steps: [
+                    {
+                        kind: 'boundary',
+                        location: { file: ctx.filePath, startLine: 1, startCol: 1, endLine: 1, endCol: 1 },
+                        label: `'use client'`,
+                        detail: 'This file is treated as a Client Component.',
+                    },
+                    {
+                        kind: 'import',
+                        location: {
+                            file: ctx.filePath,
+                            startLine: imp.getStartLineNumber(),
+                            startCol: 1,
+                            endLine: imp.getStartLineNumber(),
+                            endCol: 1,
+                        },
+                        label: mod,
+                        detail: 'Server-only module imported into a client boundary.',
+                    },
+                ],
+            };
+            findings.push(hit);
         }
     }
     // Call check: cookies()/headers()/draftMode() invocation in client code
@@ -150,7 +833,219 @@ function serverApiInClient(ctx) {
             .some((imp) => imp.getModuleSpecifierValue() === 'next/headers' && imp.getNamedImports().some((ni) => ni.getName() === name));
         if (!fromNextHeaders)
             continue;
-        findings.push(finding('server-api-in-client', 'error', 'bug', `'${name}()' called in Client Component — next/headers APIs are server-only and will throw at runtime`, ctx.filePath, call.getStartLineNumber(), 1, { suggestion: `Call '${name}()' in a Server Component or server action, then pass the result as a prop` }));
+        const hit = finding('server-api-in-client', 'error', 'bug', `'${name}()' called in Client Component — next/headers APIs are server-only and will throw at runtime`, ctx.filePath, call.getStartLineNumber(), 1, {
+            suggestion: `Call '${name}()' in a Server Component or server action, then pass the result as a prop`,
+        });
+        hit.provenance = {
+            summary: `Client boundary calls server-only API ${name}().`,
+            steps: [
+                {
+                    kind: 'boundary',
+                    location: { file: ctx.filePath, startLine: 1, startCol: 1, endLine: 1, endCol: 1 },
+                    label: `'use client'`,
+                    detail: 'This file is treated as a Client Component.',
+                },
+                {
+                    kind: 'call',
+                    location: {
+                        file: ctx.filePath,
+                        startLine: call.getStartLineNumber(),
+                        startCol: 1,
+                        endLine: call.getStartLineNumber(),
+                        endCol: 1,
+                    },
+                    label: `${name}()`,
+                    detail: `Call is only valid from 'next/headers' on the server.`,
+                },
+            ],
+        };
+        findings.push(hit);
+    }
+    return findings;
+}
+// ── Rule: browser-api-in-server ──────────────────────────────────────────
+// Browser globals used directly in a Server Component / server boundary.
+function browserApiInServer(ctx) {
+    if (ctx.fileRole !== 'runtime')
+        return [];
+    const fullText = ctx.sourceFile.getFullText();
+    if (isClientBoundary(ctx, fullText))
+        return [];
+    if (!BROWSER_GLOBALS.test(fullText))
+        return [];
+    const findings = [];
+    const reported = new Set();
+    for (const identifier of ctx.sourceFile.getDescendantsOfKind(SyntaxKind.Identifier)) {
+        const globalName = identifier.getText();
+        if (!BROWSER_GLOBAL_NAMES.includes(globalName))
+            continue;
+        if (reported.has(globalName))
+            continue;
+        if (!isBrowserGlobalReference(identifier, globalName))
+            continue;
+        if (isGuardedBrowserGlobalUse(identifier, globalName))
+            continue;
+        reported.add(globalName);
+        findings.push(finding('browser-api-in-server', 'error', 'bug', `'${globalName}' is used in a Server Component/server boundary — browser APIs require 'use client' or a Client Component`, ctx.filePath, identifier.getStartLineNumber(), 1, {
+            suggestion: 'Move this logic into a Client Component, or pass a server-safe value down as a prop instead of reading browser globals here',
+        }));
+    }
+    return findings;
+}
+// ── Rule: use-action-state-missing-pending ───────────────────────────────
+// useActionState bound to form action but pending tuple value is not captured.
+function useActionStateMissingPending(ctx) {
+    if (ctx.fileRole !== 'runtime')
+        return [];
+    const fullText = ctx.sourceFile.getFullText();
+    if (!isClientBoundary(ctx, fullText))
+        return [];
+    const findings = [];
+    for (const binding of getReactActionStateBindings(ctx)) {
+        if (binding.hasPendingBinding)
+            continue;
+        if (!isActionBoundInJsx(ctx, binding.actionName))
+            continue;
+        findings.push(finding('use-action-state-missing-pending', 'warning', 'pattern', `useActionState is bound to '${binding.actionName}' without capturing the pending tuple value — server action submits have no in-flight UI state`, ctx.filePath, binding.decl.getStartLineNumber(), 1, {
+            suggestion: 'Capture the third tuple value from useActionState, e.g. const [state, formAction, pending] = useActionState(...), then disable the submit button or show loading UI while pending',
+        }));
+    }
+    return findings;
+}
+// ── Rule: use-action-state-missing-feedback ──────────────────────────────
+// useActionState bound to form action but returned state is never read.
+function useActionStateMissingFeedback(ctx) {
+    if (ctx.fileRole !== 'runtime')
+        return [];
+    const fullText = ctx.sourceFile.getFullText();
+    if (!isClientBoundary(ctx, fullText))
+        return [];
+    const findings = [];
+    for (const binding of getReactActionStateBindings(ctx)) {
+        if (!isActionBoundInJsx(ctx, binding.actionName))
+            continue;
+        if (binding.stateNameNode && hasNonDeclarationReferenceInFile(ctx, binding.stateNameNode))
+            continue;
+        findings.push(finding('use-action-state-missing-feedback', 'warning', 'pattern', `useActionState is bound to '${binding.actionName}' but its state value is never read — server action success/error feedback is not surfaced`, ctx.filePath, binding.decl.getStartLineNumber(), 1, {
+            suggestion: 'Read the first tuple value from useActionState and surface result state in the UI or a side effect (for example an error message, success state, toast, or redirect)',
+        }));
+    }
+    return findings;
+}
+// ── Rule: server-action-form-missing-pending ─────────────────────────────
+// Native submit control is wired directly to a Server Action but no pending
+// state substrate (useActionState / useFormStatus) is present in the file.
+function serverActionFormMissingPending(ctx) {
+    if (ctx.fileRole !== 'runtime')
+        return [];
+    const actionStateBindings = getReactActionStateBindings(ctx);
+    const actionStateNames = new Set(actionStateBindings.map((binding) => binding.actionName));
+    if (fileUsesUseFormStatus(ctx))
+        return [];
+    const findings = [];
+    for (const form of ctx.sourceFile.getDescendantsOfKind(SyntaxKind.JsxElement)) {
+        if (getJsxTagName(form.getOpeningElement()) !== 'form')
+            continue;
+        const actionExpr = getJsxExpressionAttribute(form.getOpeningElement(), 'action');
+        if (!actionExpr)
+            continue;
+        if (Node.isIdentifier(actionExpr) && actionStateNames.has(actionExpr.getText()))
+            continue;
+        if (!isServerActionReference(ctx, actionExpr))
+            continue;
+        if (!hasNativeSubmitDescendant(form))
+            continue;
+        findings.push(finding('server-action-form-missing-pending', 'warning', 'pattern', 'Form is wired directly to a Server Action with a native submit control but no pending-state UX was detected — users can resubmit while the action is in flight', ctx.filePath, form.getStartLineNumber(), 1, {
+            suggestion: 'Render the submit button from a Client Component that uses useFormStatus(), then disable it or show loading text while pending. If you need result state too, consider useActionState().',
+        }));
+    }
+    return findings;
+}
+// ── Rule: server-action-form-return-value-ignored ────────────────────────
+// Direct form actions do not surface returned values. If a same-file Server
+// Action returns data, it should usually be wired through useActionState.
+function serverActionFormReturnValueIgnored(ctx) {
+    if (ctx.fileRole !== 'runtime')
+        return [];
+    const actionStateBindings = getReactActionStateBindings(ctx);
+    const actionStateNames = new Set(actionStateBindings.map((binding) => binding.actionName));
+    const findings = [];
+    for (const form of ctx.sourceFile.getDescendantsOfKind(SyntaxKind.JsxElement)) {
+        if (getJsxTagName(form.getOpeningElement()) !== 'form')
+            continue;
+        const actionExpr = getJsxExpressionAttribute(form.getOpeningElement(), 'action');
+        if (!actionExpr)
+            continue;
+        if (Node.isIdentifier(actionExpr) && actionStateNames.has(actionExpr.getText()))
+            continue;
+        const serverActions = resolveServerActionFunctions(ctx, actionExpr);
+        if (serverActions.length === 0)
+            continue;
+        if (!serverActions.some((fn) => functionReturnsValue(fn)))
+            continue;
+        findings.push(finding('server-action-form-return-value-ignored', 'warning', 'bug', 'Form posts directly to a Server Action that returns a value, but plain form actions do not surface returned state — the result is ignored unless you use useActionState()', ctx.filePath, form.getStartLineNumber(), 1, {
+            suggestion: 'If the action result drives success/error UI, wrap it in useActionState() and render the returned state. Otherwise remove the unused return value and redirect/revalidate explicitly.',
+        }));
+    }
+    return findings;
+}
+// ── Rule: server-action-form-mutation-missing-invalidation ───────────────
+// Direct form action posts to a mutating Server Action that neither revalidates
+// cache nor redirects, so the submit likely completes with stale UI.
+function serverActionFormMutationMissingInvalidation(ctx) {
+    if (ctx.fileRole !== 'runtime')
+        return [];
+    const actionStateBindings = getReactActionStateBindings(ctx);
+    const actionStateNames = new Set(actionStateBindings.map((binding) => binding.actionName));
+    const findings = [];
+    for (const form of ctx.sourceFile.getDescendantsOfKind(SyntaxKind.JsxElement)) {
+        if (getJsxTagName(form.getOpeningElement()) !== 'form')
+            continue;
+        const actionExpr = getJsxExpressionAttribute(form.getOpeningElement(), 'action');
+        if (!actionExpr)
+            continue;
+        if (Node.isIdentifier(actionExpr) && actionStateNames.has(actionExpr.getText()))
+            continue;
+        const candidate = resolveServerActionFunctions(ctx, actionExpr).find((fn) => {
+            if (functionReturnsValue(fn))
+                return false;
+            if (functionCallsPostSubmitClosure(fn))
+                return false;
+            return !!getMutationCall(fn);
+        });
+        if (!candidate)
+            continue;
+        const actionFile = candidate.getSourceFile().getFilePath();
+        const actionName = getFunctionLikeName(candidate);
+        const mutationCall = getMutationCall(candidate);
+        const actionLine = candidate.getStartLineNumber();
+        const mutationLine = mutationCall?.getStartLineNumber();
+        const hit = finding('server-action-form-mutation-missing-invalidation', 'warning', 'bug', `Form posts directly to mutating Server Action '${actionName}' but no redirect or cache invalidation was detected — the submit can complete with stale UI`, ctx.filePath, form.getStartLineNumber(), 1, {
+            suggestion: 'After a successful mutation, call revalidatePath(), revalidateTag(), updateTag(), redirect(), or return state through useActionState() so the UI closes the loop.',
+        });
+        hit.relatedSpans = [span(actionFile, actionLine), ...(mutationLine ? [span(actionFile, mutationLine)] : [])];
+        hit.provenance = {
+            summary: `Form action resolves to ${actionName}(), which performs a likely mutation but does not redirect or refresh server data.`,
+            steps: [
+                {
+                    kind: 'call',
+                    location: span(actionFile, actionLine),
+                    label: `${actionName}()`,
+                    detail: 'Resolved Server Action bound to the form action.',
+                },
+                ...(mutationLine
+                    ? [
+                        {
+                            kind: 'call',
+                            location: span(actionFile, mutationLine),
+                            label: mutationCall?.getExpression().getText() ?? 'mutation call',
+                            detail: 'Likely mutating operation inside the Server Action body.',
+                        },
+                    ]
+                    : []),
+            ],
+        };
+        findings.push(hit);
     }
     return findings;
 }
@@ -273,5 +1168,15 @@ function serverActionUnvalidatedInput(ctx) {
     return findings;
 }
 // ── Exported App Router Rules ────────────────────────────────────────────
-export const nextjsAppRouterRules = [useClientDrilledTooHigh, serverApiInClient, serverActionUnvalidatedInput];
+export const nextjsAppRouterRules = [
+    useClientDrilledTooHigh,
+    serverApiInClient,
+    browserApiInServer,
+    useActionStateMissingPending,
+    useActionStateMissingFeedback,
+    serverActionFormMissingPending,
+    serverActionFormReturnValueIgnored,
+    serverActionFormMutationMissingInvalidation,
+    serverActionUnvalidatedInput,
+];
 //# sourceMappingURL=nextjs-app-router.js.map