@sarj/eslint-plugin 15.2.0 → 15.4.0

package/dist/index.cjs

@@ -104,6 +104,7 @@ ${missing.join("\n")}`);
 function publicExample(example) {
   return {
     id: example.id,
+    scenarioId: example.scenarioId ?? "primary",
     title: example.title,
     outcome: example.outcome,
     files: example.files.map(publicFile),
@@ -148,9 +149,14 @@ function nativeSpec(config, documentation) {
   const examples = [...documentation.examples ?? []];
   examples.forEach(validateExample);
   assertUnique(examples.map((example) => example.id), "rule example IDs");
-  const publicOutcomes = new Set(examples.filter((example) => example.public === true).map((example) => example.outcome));
-  if (publicOutcomes.size > 0 && !(publicOutcomes.has("match") && publicOutcomes.has("no-match"))) {
-    throw new TypeError("published rule examples must include matching and non-matching cases");
+  const publicExamples = examples.filter((example) => example.public === true);
+  const scenarios = new Set(publicExamples.map((example) => example.scenarioId ?? "primary"));
+  for (const scenario of scenarios) {
+    const pair = publicExamples.filter((example) => (example.scenarioId ?? "primary") === scenario);
+    const outcomes = new Set(pair.map((example) => example.outcome));
+    if (pair.length !== 2 || !outcomes.has("match") || !outcomes.has("no-match")) {
+      throw new TypeError(`published example scenario ${scenario} must contain both matching and non-matching cases exactly once`);
+    }
   }
   const messageIds = Object.keys(meta2.messages).sort();
   const schema = optionsSchema(meta2.schema);
@@ -171,7 +177,7 @@ function nativeSpec(config, documentation) {
     references,
     since: documentation.since ?? null,
     examples,
-    publicExamples: examples.filter((example) => example.public === true),
+    publicExamples,
     messageIds,
     optionsSchema: schema
   };
@@ -191,6 +197,9 @@ function validateExample(example) {
   if (!KEBAB_CASE.test(example.id)) {
     throw new TypeError("example ID must be lowercase kebab-case");
   }
+  if (!KEBAB_CASE.test(example.scenarioId ?? "primary")) {
+    throw new TypeError("example scenario must be lowercase kebab-case");
+  }
   if (example.title.trim().length === 0) {
     throw new TypeError("example title must not be empty");
   }
@@ -3264,14 +3273,12 @@ var noJsonStringifyErrorDocumentation = {
   rationale: "Native Error details are non-enumerable, so generic JSON serialization discards diagnostic information.",
   remediation: "Serialize explicit error fields or use an error-aware serializer.",
   category: "correctness",
-  limitations: ["The rule uses local syntax and naming evidence rather than type information."],
+  limitations: ["The rule uses local catch-binding and constructor provenance rather than type information."],
   examples: [
     { id: "explicit-error-message", title: "Serialize an enumerable error field", outcome: "no-match", files: [{ path: "src/report.ts", source: "try { f(); } catch (err) { JSON.stringify({ error: err.message }); }" }], focusPath: "src/report.ts", expectedCount: 0, public: true },
     { id: "stringified-error", title: "Do not stringify an Error object", outcome: "match", files: [{ path: "src/report.ts", source: "try { f(); } catch (err) { JSON.stringify({ error: err }); }" }], focusPath: "src/report.ts", expectedCount: 1, public: true }
   ]
 };
-var ERROR_NAME_PATTERN = /^(e|err|error|ex|exc)$/i;
-var ERROR_PROP_PATTERN = /^(cause|lastError|error|err|exception|originalError|innerError)$/i;
 var SAFE_STRING_PROPS = /* @__PURE__ */ new Set(["message", "stack", "name"]);
 var PAYLOAD_PROPS = /* @__PURE__ */ new Set([
   "data",
@@ -3299,6 +3306,21 @@ var BUILTIN_ERROR_CONSTRUCTORS = /* @__PURE__ */ new Set([
   "TypeError",
   "URIError"
 ]);
+function identifierIsProvenError(identifier, scope) {
+  if (isCatchBinding(scope, identifier.name)) return true;
+  let current = scope;
+  while (current !== null && !current.set.has(identifier.name)) {
+    current = current.upper;
+  }
+  const variable = current?.set.get(identifier.name);
+  if (variable === void 0 || variable.defs.length !== 1) return false;
+  const definition = variable.defs[0];
+  if (definition?.type !== "Variable") return false;
+  const initializer = definition.node.init;
+  return initializer?.type === "NewExpression" && initializer.callee.type === "Identifier" && BUILTIN_ERROR_CONSTRUCTORS.has(initializer.callee.name) && variable.references.every(
+    (reference) => !reference.isWrite() || reference.init === true
+  );
+}
 function isCatchBinding(scope, name) {
   let current = scope;
   while (current) {
@@ -3314,22 +3336,6 @@ function isCatchBinding(scope, name) {
   }
   return false;
 }
-function memberSuggestsError(member, scope) {
-  const propName2 = !member.computed && member.property.type === "Identifier" ? member.property.name : null;
-  if (propName2 !== null && ERROR_PROP_PATTERN.test(propName2)) {
-    return true;
-  }
-  const base = member.object;
-  const baseSuggestsError = base.type === "Identifier" && (ERROR_NAME_PATTERN.test(base.name) || isCatchBinding(scope, base.name));
-  if (baseSuggestsError) {
-    if (propName2 === null) {
-      return true;
-    }
-    const lowered = propName2.toLowerCase();
-    return !SAFE_STRING_PROPS.has(lowered) && !PAYLOAD_PROPS.has(lowered);
-  }
-  return false;
-}
 function positiveErrorSubject(test) {
   return instanceofErrorSubject(test) ?? typeGuardSubject(test);
 }
@@ -3433,27 +3439,25 @@ function directLiteralValues(argument) {
 }
 function expressionSuggestsError(expression, scope) {
   if (expression.type === "Identifier") {
-    return ERROR_NAME_PATTERN.test(expression.name) || isCatchBinding(scope, expression.name);
+    return identifierIsProvenError(expression, scope);
+  }
+  if (expression.type === "NewExpression" && expression.callee.type === "Identifier") {
+    return BUILTIN_ERROR_CONSTRUCTORS.has(expression.callee.name);
   }
   return expression.type === "MemberExpression" && memberSuggestsError(expression, scope);
 }
-function nestedExpressionSuggestsError(expression, scope) {
-  if (expression.type === "Identifier") {
-    if (isCatchBinding(scope, expression.name)) return true;
-    let current = scope;
-    while (current !== null && !current.set.has(expression.name)) {
-      current = current.upper;
-    }
-    const variable = current?.set.get(expression.name);
-    if (variable === void 0 || variable.defs.length !== 1) return false;
-    const definition = variable.defs[0];
-    if (definition?.type !== "Variable") return false;
-    const initializer = definition.node.init;
-    return initializer?.type === "NewExpression" && initializer.callee.type === "Identifier" && BUILTIN_ERROR_CONSTRUCTORS.has(initializer.callee.name) && variable.references.every(
-      (reference) => !reference.isWrite() || reference.init === true
-    );
+function memberSuggestsError(member, scope) {
+  const propName2 = !member.computed && member.property.type === "Identifier" ? member.property.name : null;
+  const base = member.object;
+  const baseSuggestsError = base.type === "Identifier" && identifierIsProvenError(base, scope);
+  if (baseSuggestsError) {
+    if (propName2 === null) {
+      return true;
+    }
+    const lowered = propName2.toLowerCase();
+    return !SAFE_STRING_PROPS.has(lowered) && !PAYLOAD_PROPS.has(lowered);
   }
-  return expression.type === "MemberExpression" && memberSuggestsError(expression, scope);
+  return false;
 }
 var no_json_stringify_error_default = createRule({
   name: "no-json-stringify-error",
@@ -3480,9 +3484,8 @@ var no_json_stringify_error_default = createRule({
           return;
         }
         const scope = context.sourceCode.getScope(firstArg);
-        const isNestedLiteral = firstArg.type === "ObjectExpression" || firstArg.type === "ArrayExpression";
         const unsafeValue = directLiteralValues(firstArg).find(
-          (value) => (isNestedLiteral ? nestedExpressionSuggestsError(value, scope) : expressionSuggestsError(value, scope)) && !isGuardedByInstanceofError(node, value, context.sourceCode) && !isNarrowedByEarlyReturn(node, value, context.sourceCode)
+          (value) => expressionSuggestsError(value, scope) && !isGuardedByInstanceofError(node, value, context.sourceCode) && !isNarrowedByEarlyReturn(node, value, context.sourceCode)
         );
         if (unsafeValue === void 0) {
           return;
@@ -4941,6 +4944,7 @@ var ANALYTICS_SEGMENTS2 = /* @__PURE__ */ new Set([
 ]);
 var SERVER_ACTION_SKIP_FILE_RE = /(?:\.test\.[jt]sx?$|\.spec\.[jt]sx?$|-(?:test|spec)\.[jt]sx?$|\/tests?\/|\/__tests__\/|\/__testfixtures__\/|\/scripts?\/|\/app\/api\/.*\/route\.[jt]sx?$|\/pages\/api\/)/;
 var NON_REACT_FRAMEWORK_RE = /^(?:@angular\/|@nestjs\/|vue$|vue\/|svelte$|svelte\/|solid-js$|solid-js\/|@ember\/|rxjs$|rxjs\/)/;
+var NEXT_MODULE_PATH_RE = /(?:^|[/\\])(?:app|pages)[/\\]/u;
 function isGlobalFetchCall(node, resolvesToGlobal) {
   const callee = node.callee;
   if (callee.type === "Identifier") {
@@ -5056,6 +5060,13 @@ var no_raw_fetch_outside_clients_default = createRule({
     const nonReactFramework = context.sourceCode.ast.body.some(
       (statement) => statement.type === import_utils25.AST_NODE_TYPES.ImportDeclaration && typeof statement.source.value === "string" && NON_REACT_FRAMEWORK_RE.test(statement.source.value)
     );
+    const hasUseClientDirective = context.sourceCode.ast.body.some(
+      (statement) => statement.type === import_utils25.AST_NODE_TYPES.ExpressionStatement && statement.expression.type === import_utils25.AST_NODE_TYPES.Literal && statement.expression.value === "use client"
+    );
+    const hasNextImport = context.sourceCode.ast.body.some(
+      (statement) => statement.type === import_utils25.AST_NODE_TYPES.ImportDeclaration && typeof statement.source.value === "string" && (statement.source.value === "next" || statement.source.value.startsWith("next/"))
+    );
+    const hasNextEvidence = hasNextImport || hasUseClientDirective && NEXT_MODULE_PATH_RE.test(filename);
     function resolvesToGlobal(identifier) {
       const variable = import_utils25.ASTUtils.findVariable(
         context.sourceCode.getScope(identifier),
@@ -5116,7 +5127,7 @@ var no_raw_fetch_outside_clients_default = createRule({
       return resolved?.type === import_utils25.AST_NODE_TYPES.LogicalExpression && resolved.operator === "||" && (isMutationMethod2(resolved.left) || isMutationMethod2(resolved.right));
     }
     function serverActionOwns(node) {
-      if (node.callee.type !== import_utils25.AST_NODE_TYPES.Identifier || SERVER_ACTION_SKIP_FILE_RE.test(filename) || nonReactFramework) {
+      if (node.callee.type !== import_utils25.AST_NODE_TYPES.Identifier || !hasNextEvidence || SERVER_ACTION_SKIP_FILE_RE.test(filename) || nonReactFramework) {
         return false;
       }
       const url = node.arguments[0];
@@ -6335,6 +6346,20 @@ var SAFE_PARSE_CONSTRUCTORS = /* @__PURE__ */ new Set([
 function isBodyDecodeNode(node) {
   return node.type === import_utils32.AST_NODE_TYPES.CallExpression && node.callee.type === import_utils32.AST_NODE_TYPES.MemberExpression && !node.callee.computed && node.callee.property.type === import_utils32.AST_NODE_TYPES.Identifier && BODY_DECODE_METHODS.has(node.callee.property.name);
 }
+function isSafeParseSupportCall(node) {
+  const callee = node.callee;
+  if (callee.type !== import_utils32.AST_NODE_TYPES.MemberExpression || callee.computed || callee.property.type !== import_utils32.AST_NODE_TYPES.Identifier) {
+    return false;
+  }
+  if (callee.property.name === "isArray" && callee.object.type === import_utils32.AST_NODE_TYPES.Identifier && callee.object.name === "Array") {
+    return true;
+  }
+  if (callee.property.name !== "getItem") return false;
+  if (callee.object.type === import_utils32.AST_NODE_TYPES.Identifier && (callee.object.name === "localStorage" || callee.object.name === "sessionStorage")) {
+    return true;
+  }
+  return callee.object.type === import_utils32.AST_NODE_TYPES.MemberExpression && !callee.object.computed && callee.object.object.type === import_utils32.AST_NODE_TYPES.Identifier && (callee.object.object.name === "window" || callee.object.object.name === "globalThis") && callee.object.property.type === import_utils32.AST_NODE_TYPES.Identifier && (callee.object.property.name === "localStorage" || callee.object.property.name === "sessionStorage");
+}
 var BODY_DECODE_METHODS = /* @__PURE__ */ new Set([
   "json",
   "text",
@@ -6403,6 +6428,7 @@ function tryReturnsSafeParse(catchNode) {
     if (current.type === import_utils32.AST_NODE_TYPES.CallExpression || current.type === import_utils32.AST_NODE_TYPES.NewExpression) {
       if (isParseShapedNode(current) || isBodyDecodeNode(current)) {
         sawSafeParse = true;
+      } else if (current.type === import_utils32.AST_NODE_TYPES.CallExpression && isSafeParseSupportCall(current)) {
       } else {
         sawUnsafeOperation = true;
         return;
@@ -10926,7 +10952,70 @@ var bindingValidationPolarity = (test, bindingName) => {
   }
   return test.type === import_utils57.AST_NODE_TYPES.CallExpression && test.arguments.length === 1 && test.arguments[0]?.type === import_utils57.AST_NODE_TYPES.Identifier && test.arguments[0].name === bindingName && test.callee.type === import_utils57.AST_NODE_TYPES.MemberExpression && !test.callee.computed && test.callee.object.type === import_utils57.AST_NODE_TYPES.Identifier && test.callee.object.name === "Array" && test.callee.property.type === import_utils57.AST_NODE_TYPES.Identifier && test.callee.property.name === "isArray" ? "valid-when-true" : null;
 };
+var plainMemberAccess = (node) => node.type === import_utils57.AST_NODE_TYPES.MemberExpression && !node.computed && node.object.type === import_utils57.AST_NODE_TYPES.Identifier && node.property.type === import_utils57.AST_NODE_TYPES.Identifier ? { object: node.object.name, property: node.property.name } : null;
+var isSamePlainMember = (node, access) => {
+  const candidate = plainMemberAccess(node);
+  return candidate !== null && candidate.object === access.object && candidate.property === access.property;
+};
 var nodeWithin2 = (node, container) => node.range[0] >= container.range[0] && node.range[1] <= container.range[1];
+var isUseWithinValidatedBranch = (node, bindingName) => {
+  for (let current = node.parent; current !== void 0 && current !== null; current = current.parent) {
+    if (current.type === import_utils57.AST_NODE_TYPES.ConditionalExpression) {
+      const polarity = bindingValidationPolarity(current.test, bindingName);
+      if (polarity === "valid-when-true" && nodeWithin2(node, current.consequent) || polarity === "valid-when-false" && nodeWithin2(node, current.alternate)) {
+        return true;
+      }
+    }
+    if (current.type === import_utils57.AST_NODE_TYPES.IfStatement) {
+      const polarity = bindingValidationPolarity(current.test, bindingName);
+      if (polarity === "valid-when-true" && nodeWithin2(node, current.consequent) || polarity === "valid-when-false" && current.alternate !== null && nodeWithin2(node, current.alternate)) {
+        return true;
+      }
+    }
+    if (current.type === import_utils57.AST_NODE_TYPES.FunctionDeclaration || current.type === import_utils57.AST_NODE_TYPES.FunctionExpression || current.type === import_utils57.AST_NODE_TYPES.ArrowFunctionExpression) {
+      return false;
+    }
+  }
+  return false;
+};
+var isMemberUseWithinValidatedBranch = (node, access) => {
+  for (let current = node.parent; current !== void 0 && current !== null; current = current.parent) {
+    if (current.type === import_utils57.AST_NODE_TYPES.ConditionalExpression) {
+      const polarity = memberValidationPolarity(current.test, access);
+      if (polarity === "valid-when-true" && nodeWithin2(node, current.consequent) || polarity === "valid-when-false" && nodeWithin2(node, current.alternate)) {
+        return true;
+      }
+    }
+    if (current.type === import_utils57.AST_NODE_TYPES.IfStatement) {
+      const polarity = memberValidationPolarity(current.test, access);
+      if (polarity === "valid-when-true" && nodeWithin2(node, current.consequent) || polarity === "valid-when-false" && current.alternate !== null && nodeWithin2(node, current.alternate)) {
+        return true;
+      }
+    }
+    if (current.type === import_utils57.AST_NODE_TYPES.FunctionDeclaration || current.type === import_utils57.AST_NODE_TYPES.FunctionExpression || current.type === import_utils57.AST_NODE_TYPES.ArrowFunctionExpression) {
+      return false;
+    }
+  }
+  return false;
+};
+var memberValidationPolarity = (test, access) => {
+  if (test.type === import_utils57.AST_NODE_TYPES.UnaryExpression && test.operator === "!") {
+    const inner = memberValidationPolarity(test.argument, access);
+    return inner === "valid-when-true" ? "valid-when-false" : inner === "valid-when-false" ? "valid-when-true" : null;
+  }
+  if (test.type === import_utils57.AST_NODE_TYPES.BinaryExpression) {
+    const isMatchingTypeof = (node) => node.type === import_utils57.AST_NODE_TYPES.UnaryExpression && node.operator === "typeof" && isSamePlainMember(node.argument, access);
+    const isPrimitiveType = (node) => node.type === import_utils57.AST_NODE_TYPES.Literal && typeof node.value === "string" && PRIMITIVE_TYPEOF_RESULTS.has(node.value);
+    if (!(isMatchingTypeof(test.left) && isPrimitiveType(test.right) || isMatchingTypeof(test.right) && isPrimitiveType(test.left))) {
+      return null;
+    }
+    if (test.operator === "===" || test.operator === "==") {
+      return "valid-when-true";
+    }
+    return test.operator === "!==" || test.operator === "!=" ? "valid-when-false" : null;
+  }
+  return test.type === import_utils57.AST_NODE_TYPES.CallExpression && test.arguments.length === 1 && test.arguments[0] !== void 0 && test.arguments[0].type !== import_utils57.AST_NODE_TYPES.SpreadElement && isSamePlainMember(test.arguments[0], access) && test.callee.type === import_utils57.AST_NODE_TYPES.MemberExpression && !test.callee.computed && test.callee.object.type === import_utils57.AST_NODE_TYPES.Identifier && test.callee.object.name === "Array" && test.callee.property.type === import_utils57.AST_NODE_TYPES.Identifier && test.callee.property.name === "isArray" ? "valid-when-true" : null;
+};
 var isFullyValidatedExtractedBinding = (member, source, context) => {
   const isValidationReference = (identifier) => {
     for (let current = identifier.parent; current !== void 0 && current !== null; current = current.parent) {
@@ -11196,7 +11285,14 @@ var prefer_schema_for_api_payload_default = createRule({
           return;
         }
         const variable = obj?.type === import_utils57.AST_NODE_TYPES.Identifier ? unvalidatedVariableRef(obj, scope, unvalidatedVariables) : null;
-        if (variable !== null) {
+        if (variable !== null && obj?.type === import_utils57.AST_NODE_TYPES.Identifier) {
+          if (isUseWithinValidatedBranch(node, obj.name)) {
+            return;
+          }
+          const access = plainMemberAccess(node);
+          if (access !== null && isMemberUseWithinValidatedBranch(node, access)) {
+            return;
+          }
           if (isFullyValidatedExtractedBinding(node, variable, context)) {
             return;
           }
@@ -11648,16 +11744,17 @@ var preferServerActionsDocumentation = {
   rationale: "Server Actions preserve typed application calls and avoid an internal JSON request-response boundary.",
   remediation: "Move the mutation into a Server Action and invoke that action from the React client.",
   category: "architecture",
-  limitations: ["Only statically recognizable /api/ mutations in applicable React modules are reported."],
+  limitations: ["Only statically recognizable /api/ mutations in modules with positive Next.js evidence are reported: an explicit next import, or an app/pages path with a top-level use-client directive."],
   examples: [
     { id: "server-action-call", title: "Call a Server Action", outcome: "no-match", files: [{ path: "app/tasks/page.tsx", source: "import { createTask } from './actions'; await createTask(input);" }], focusPath: "app/tasks/page.tsx", expectedCount: 0, public: true },
-    { id: "api-mutation", title: "Do not mutate through an API route", outcome: "match", files: [{ path: "app/tasks/page.tsx", source: "await fetch('/api/tasks', { method: 'POST', body });" }], focusPath: "app/tasks/page.tsx", expectedCount: 1, public: true }
+    { id: "api-mutation", title: "Do not mutate through an API route", outcome: "match", files: [{ path: "app/tasks/page.tsx", source: "'use client'; await fetch('/api/tasks', { method: 'POST', body });" }], focusPath: "app/tasks/page.tsx", expectedCount: 1, public: true }
   ]
 };
 var MUTATION_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "DELETE", "PATCH"]);
 var AXIOS_MUTATION_METHODS = /* @__PURE__ */ new Set(["post", "put", "delete", "patch"]);
 var SKIP_FILE_REGEX = /(?:\.test\.[jt]sx?$|\.spec\.[jt]sx?$|-(?:test|spec)\.[jt]sx?$|\/tests?\/|\/__tests__\/|\/__testfixtures__\/|\/scripts?\/|\/app\/api\/.*\/route\.[jt]sx?$|\/pages\/api\/)/;
 var NON_REACT_FRAMEWORK_RE2 = /^(?:@angular\/|@nestjs\/|vue$|vue\/|svelte$|svelte\/|solid-js$|solid-js\/|@ember\/|rxjs$|rxjs\/)/;
+var NEXT_MODULE_PATH_RE2 = /(?:^|[/\\])(?:app|pages)[/\\]/u;
 function getScope(context, node) {
   return context.sourceCode.getScope(node);
 }
@@ -11771,6 +11868,16 @@ var prefer_server_actions_default = createRule({
     const isNonReactFramework = context.sourceCode.ast.body.some(
       (node) => node.type === "ImportDeclaration" && typeof node.source.value === "string" && NON_REACT_FRAMEWORK_RE2.test(node.source.value)
     );
+    const hasUseClientDirective = context.sourceCode.ast.body.some(
+      (node) => node.type === "ExpressionStatement" && node.expression.type === "Literal" && node.expression.value === "use client"
+    );
+    const hasNextImport = context.sourceCode.ast.body.some(
+      (node) => node.type === "ImportDeclaration" && typeof node.source.value === "string" && (node.source.value === "next" || node.source.value.startsWith("next/"))
+    );
+    const hasNextEvidence = hasNextImport || hasUseClientDirective && NEXT_MODULE_PATH_RE2.test(filename);
+    if (!hasNextEvidence) {
+      return {};
+    }
     return {
       CallExpression(node) {
         if (isNonReactFramework) return;
@@ -14338,7 +14445,7 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.2.0"
+  version: "15.4.0"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",

package/dist/index.d.cts

@@ -25,6 +25,7 @@ interface ExampleFile {
 /** A reviewed example. It remains private unless `public: true` is explicit. */
 interface RuleExample {
     readonly id: string;
+    readonly scenarioId?: string;
     readonly title: string;
     readonly outcome: ExampleOutcome;
     readonly files: readonly ExampleFile[];
@@ -414,7 +415,7 @@ type FlatPreset = {
 declare const plugin: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.2.0";
+        readonly version: "15.4.0";
     };
     readonly rules: {
         readonly "duplicate-test-body": DocumentedRule<readonly [], "duplicateTestBody">;

package/dist/index.d.ts

@@ -25,6 +25,7 @@ interface ExampleFile {
 /** A reviewed example. It remains private unless `public: true` is explicit. */
 interface RuleExample {
     readonly id: string;
+    readonly scenarioId?: string;
     readonly title: string;
     readonly outcome: ExampleOutcome;
     readonly files: readonly ExampleFile[];
@@ -414,7 +415,7 @@ type FlatPreset = {
 declare const plugin: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.2.0";
+        readonly version: "15.4.0";
     };
     readonly rules: {
         readonly "duplicate-test-body": DocumentedRule<readonly [], "duplicateTestBody">;

package/dist/index.js

@@ -61,6 +61,7 @@ ${missing.join("\n")}`);
 function publicExample(example) {
   return {
     id: example.id,
+    scenarioId: example.scenarioId ?? "primary",
     title: example.title,
     outcome: example.outcome,
     files: example.files.map(publicFile),
@@ -105,9 +106,14 @@ function nativeSpec(config, documentation) {
   const examples = [...documentation.examples ?? []];
   examples.forEach(validateExample);
   assertUnique(examples.map((example) => example.id), "rule example IDs");
-  const publicOutcomes = new Set(examples.filter((example) => example.public === true).map((example) => example.outcome));
-  if (publicOutcomes.size > 0 && !(publicOutcomes.has("match") && publicOutcomes.has("no-match"))) {
-    throw new TypeError("published rule examples must include matching and non-matching cases");
+  const publicExamples = examples.filter((example) => example.public === true);
+  const scenarios = new Set(publicExamples.map((example) => example.scenarioId ?? "primary"));
+  for (const scenario of scenarios) {
+    const pair = publicExamples.filter((example) => (example.scenarioId ?? "primary") === scenario);
+    const outcomes = new Set(pair.map((example) => example.outcome));
+    if (pair.length !== 2 || !outcomes.has("match") || !outcomes.has("no-match")) {
+      throw new TypeError(`published example scenario ${scenario} must contain both matching and non-matching cases exactly once`);
+    }
   }
   const messageIds = Object.keys(meta2.messages).sort();
   const schema = optionsSchema(meta2.schema);
@@ -128,7 +134,7 @@ function nativeSpec(config, documentation) {
     references,
     since: documentation.since ?? null,
     examples,
-    publicExamples: examples.filter((example) => example.public === true),
+    publicExamples,
     messageIds,
     optionsSchema: schema
   };
@@ -148,6 +154,9 @@ function validateExample(example) {
   if (!KEBAB_CASE.test(example.id)) {
     throw new TypeError("example ID must be lowercase kebab-case");
   }
+  if (!KEBAB_CASE.test(example.scenarioId ?? "primary")) {
+    throw new TypeError("example scenario must be lowercase kebab-case");
+  }
   if (example.title.trim().length === 0) {
     throw new TypeError("example title must not be empty");
   }
@@ -3224,14 +3233,12 @@ var noJsonStringifyErrorDocumentation = {
   rationale: "Native Error details are non-enumerable, so generic JSON serialization discards diagnostic information.",
   remediation: "Serialize explicit error fields or use an error-aware serializer.",
   category: "correctness",
-  limitations: ["The rule uses local syntax and naming evidence rather than type information."],
+  limitations: ["The rule uses local catch-binding and constructor provenance rather than type information."],
   examples: [
     { id: "explicit-error-message", title: "Serialize an enumerable error field", outcome: "no-match", files: [{ path: "src/report.ts", source: "try { f(); } catch (err) { JSON.stringify({ error: err.message }); }" }], focusPath: "src/report.ts", expectedCount: 0, public: true },
     { id: "stringified-error", title: "Do not stringify an Error object", outcome: "match", files: [{ path: "src/report.ts", source: "try { f(); } catch (err) { JSON.stringify({ error: err }); }" }], focusPath: "src/report.ts", expectedCount: 1, public: true }
   ]
 };
-var ERROR_NAME_PATTERN = /^(e|err|error|ex|exc)$/i;
-var ERROR_PROP_PATTERN = /^(cause|lastError|error|err|exception|originalError|innerError)$/i;
 var SAFE_STRING_PROPS = /* @__PURE__ */ new Set(["message", "stack", "name"]);
 var PAYLOAD_PROPS = /* @__PURE__ */ new Set([
   "data",
@@ -3259,6 +3266,21 @@ var BUILTIN_ERROR_CONSTRUCTORS = /* @__PURE__ */ new Set([
   "TypeError",
   "URIError"
 ]);
+function identifierIsProvenError(identifier, scope) {
+  if (isCatchBinding(scope, identifier.name)) return true;
+  let current = scope;
+  while (current !== null && !current.set.has(identifier.name)) {
+    current = current.upper;
+  }
+  const variable = current?.set.get(identifier.name);
+  if (variable === void 0 || variable.defs.length !== 1) return false;
+  const definition = variable.defs[0];
+  if (definition?.type !== "Variable") return false;
+  const initializer = definition.node.init;
+  return initializer?.type === "NewExpression" && initializer.callee.type === "Identifier" && BUILTIN_ERROR_CONSTRUCTORS.has(initializer.callee.name) && variable.references.every(
+    (reference) => !reference.isWrite() || reference.init === true
+  );
+}
 function isCatchBinding(scope, name) {
   let current = scope;
   while (current) {
@@ -3274,22 +3296,6 @@ function isCatchBinding(scope, name) {
   }
   return false;
 }
-function memberSuggestsError(member, scope) {
-  const propName2 = !member.computed && member.property.type === "Identifier" ? member.property.name : null;
-  if (propName2 !== null && ERROR_PROP_PATTERN.test(propName2)) {
-    return true;
-  }
-  const base = member.object;
-  const baseSuggestsError = base.type === "Identifier" && (ERROR_NAME_PATTERN.test(base.name) || isCatchBinding(scope, base.name));
-  if (baseSuggestsError) {
-    if (propName2 === null) {
-      return true;
-    }
-    const lowered = propName2.toLowerCase();
-    return !SAFE_STRING_PROPS.has(lowered) && !PAYLOAD_PROPS.has(lowered);
-  }
-  return false;
-}
 function positiveErrorSubject(test) {
   return instanceofErrorSubject(test) ?? typeGuardSubject(test);
 }
@@ -3393,27 +3399,25 @@ function directLiteralValues(argument) {
 }
 function expressionSuggestsError(expression, scope) {
   if (expression.type === "Identifier") {
-    return ERROR_NAME_PATTERN.test(expression.name) || isCatchBinding(scope, expression.name);
+    return identifierIsProvenError(expression, scope);
+  }
+  if (expression.type === "NewExpression" && expression.callee.type === "Identifier") {
+    return BUILTIN_ERROR_CONSTRUCTORS.has(expression.callee.name);
   }
   return expression.type === "MemberExpression" && memberSuggestsError(expression, scope);
 }
-function nestedExpressionSuggestsError(expression, scope) {
-  if (expression.type === "Identifier") {
-    if (isCatchBinding(scope, expression.name)) return true;
-    let current = scope;
-    while (current !== null && !current.set.has(expression.name)) {
-      current = current.upper;
-    }
-    const variable = current?.set.get(expression.name);
-    if (variable === void 0 || variable.defs.length !== 1) return false;
-    const definition = variable.defs[0];
-    if (definition?.type !== "Variable") return false;
-    const initializer = definition.node.init;
-    return initializer?.type === "NewExpression" && initializer.callee.type === "Identifier" && BUILTIN_ERROR_CONSTRUCTORS.has(initializer.callee.name) && variable.references.every(
-      (reference) => !reference.isWrite() || reference.init === true
-    );
+function memberSuggestsError(member, scope) {
+  const propName2 = !member.computed && member.property.type === "Identifier" ? member.property.name : null;
+  const base = member.object;
+  const baseSuggestsError = base.type === "Identifier" && identifierIsProvenError(base, scope);
+  if (baseSuggestsError) {
+    if (propName2 === null) {
+      return true;
+    }
+    const lowered = propName2.toLowerCase();
+    return !SAFE_STRING_PROPS.has(lowered) && !PAYLOAD_PROPS.has(lowered);
   }
-  return expression.type === "MemberExpression" && memberSuggestsError(expression, scope);
+  return false;
 }
 var no_json_stringify_error_default = createRule({
   name: "no-json-stringify-error",
@@ -3440,9 +3444,8 @@ var no_json_stringify_error_default = createRule({
           return;
         }
         const scope = context.sourceCode.getScope(firstArg);
-        const isNestedLiteral = firstArg.type === "ObjectExpression" || firstArg.type === "ArrayExpression";
         const unsafeValue = directLiteralValues(firstArg).find(
-          (value) => (isNestedLiteral ? nestedExpressionSuggestsError(value, scope) : expressionSuggestsError(value, scope)) && !isGuardedByInstanceofError(node, value, context.sourceCode) && !isNarrowedByEarlyReturn(node, value, context.sourceCode)
+          (value) => expressionSuggestsError(value, scope) && !isGuardedByInstanceofError(node, value, context.sourceCode) && !isNarrowedByEarlyReturn(node, value, context.sourceCode)
         );
         if (unsafeValue === void 0) {
           return;
@@ -4903,6 +4906,7 @@ var ANALYTICS_SEGMENTS2 = /* @__PURE__ */ new Set([
 ]);
 var SERVER_ACTION_SKIP_FILE_RE = /(?:\.test\.[jt]sx?$|\.spec\.[jt]sx?$|-(?:test|spec)\.[jt]sx?$|\/tests?\/|\/__tests__\/|\/__testfixtures__\/|\/scripts?\/|\/app\/api\/.*\/route\.[jt]sx?$|\/pages\/api\/)/;
 var NON_REACT_FRAMEWORK_RE = /^(?:@angular\/|@nestjs\/|vue$|vue\/|svelte$|svelte\/|solid-js$|solid-js\/|@ember\/|rxjs$|rxjs\/)/;
+var NEXT_MODULE_PATH_RE = /(?:^|[/\\])(?:app|pages)[/\\]/u;
 function isGlobalFetchCall(node, resolvesToGlobal) {
   const callee = node.callee;
   if (callee.type === "Identifier") {
@@ -5018,6 +5022,13 @@ var no_raw_fetch_outside_clients_default = createRule({
     const nonReactFramework = context.sourceCode.ast.body.some(
       (statement) => statement.type === AST_NODE_TYPES18.ImportDeclaration && typeof statement.source.value === "string" && NON_REACT_FRAMEWORK_RE.test(statement.source.value)
     );
+    const hasUseClientDirective = context.sourceCode.ast.body.some(
+      (statement) => statement.type === AST_NODE_TYPES18.ExpressionStatement && statement.expression.type === AST_NODE_TYPES18.Literal && statement.expression.value === "use client"
+    );
+    const hasNextImport = context.sourceCode.ast.body.some(
+      (statement) => statement.type === AST_NODE_TYPES18.ImportDeclaration && typeof statement.source.value === "string" && (statement.source.value === "next" || statement.source.value.startsWith("next/"))
+    );
+    const hasNextEvidence = hasNextImport || hasUseClientDirective && NEXT_MODULE_PATH_RE.test(filename);
     function resolvesToGlobal(identifier) {
       const variable = ASTUtils5.findVariable(
         context.sourceCode.getScope(identifier),
@@ -5078,7 +5089,7 @@ var no_raw_fetch_outside_clients_default = createRule({
       return resolved?.type === AST_NODE_TYPES18.LogicalExpression && resolved.operator === "||" && (isMutationMethod2(resolved.left) || isMutationMethod2(resolved.right));
     }
     function serverActionOwns(node) {
-      if (node.callee.type !== AST_NODE_TYPES18.Identifier || SERVER_ACTION_SKIP_FILE_RE.test(filename) || nonReactFramework) {
+      if (node.callee.type !== AST_NODE_TYPES18.Identifier || !hasNextEvidence || SERVER_ACTION_SKIP_FILE_RE.test(filename) || nonReactFramework) {
         return false;
       }
       const url = node.arguments[0];
@@ -6297,6 +6308,20 @@ var SAFE_PARSE_CONSTRUCTORS = /* @__PURE__ */ new Set([
 function isBodyDecodeNode(node) {
   return node.type === AST_NODE_TYPES23.CallExpression && node.callee.type === AST_NODE_TYPES23.MemberExpression && !node.callee.computed && node.callee.property.type === AST_NODE_TYPES23.Identifier && BODY_DECODE_METHODS.has(node.callee.property.name);
 }
+function isSafeParseSupportCall(node) {
+  const callee = node.callee;
+  if (callee.type !== AST_NODE_TYPES23.MemberExpression || callee.computed || callee.property.type !== AST_NODE_TYPES23.Identifier) {
+    return false;
+  }
+  if (callee.property.name === "isArray" && callee.object.type === AST_NODE_TYPES23.Identifier && callee.object.name === "Array") {
+    return true;
+  }
+  if (callee.property.name !== "getItem") return false;
+  if (callee.object.type === AST_NODE_TYPES23.Identifier && (callee.object.name === "localStorage" || callee.object.name === "sessionStorage")) {
+    return true;
+  }
+  return callee.object.type === AST_NODE_TYPES23.MemberExpression && !callee.object.computed && callee.object.object.type === AST_NODE_TYPES23.Identifier && (callee.object.object.name === "window" || callee.object.object.name === "globalThis") && callee.object.property.type === AST_NODE_TYPES23.Identifier && (callee.object.property.name === "localStorage" || callee.object.property.name === "sessionStorage");
+}
 var BODY_DECODE_METHODS = /* @__PURE__ */ new Set([
   "json",
   "text",
@@ -6365,6 +6390,7 @@ function tryReturnsSafeParse(catchNode) {
     if (current.type === AST_NODE_TYPES23.CallExpression || current.type === AST_NODE_TYPES23.NewExpression) {
       if (isParseShapedNode(current) || isBodyDecodeNode(current)) {
         sawSafeParse = true;
+      } else if (current.type === AST_NODE_TYPES23.CallExpression && isSafeParseSupportCall(current)) {
       } else {
         sawUnsafeOperation = true;
         return;
@@ -10895,7 +10921,70 @@ var bindingValidationPolarity = (test, bindingName) => {
   }
   return test.type === AST_NODE_TYPES45.CallExpression && test.arguments.length === 1 && test.arguments[0]?.type === AST_NODE_TYPES45.Identifier && test.arguments[0].name === bindingName && test.callee.type === AST_NODE_TYPES45.MemberExpression && !test.callee.computed && test.callee.object.type === AST_NODE_TYPES45.Identifier && test.callee.object.name === "Array" && test.callee.property.type === AST_NODE_TYPES45.Identifier && test.callee.property.name === "isArray" ? "valid-when-true" : null;
 };
+var plainMemberAccess = (node) => node.type === AST_NODE_TYPES45.MemberExpression && !node.computed && node.object.type === AST_NODE_TYPES45.Identifier && node.property.type === AST_NODE_TYPES45.Identifier ? { object: node.object.name, property: node.property.name } : null;
+var isSamePlainMember = (node, access) => {
+  const candidate = plainMemberAccess(node);
+  return candidate !== null && candidate.object === access.object && candidate.property === access.property;
+};
 var nodeWithin2 = (node, container) => node.range[0] >= container.range[0] && node.range[1] <= container.range[1];
+var isUseWithinValidatedBranch = (node, bindingName) => {
+  for (let current = node.parent; current !== void 0 && current !== null; current = current.parent) {
+    if (current.type === AST_NODE_TYPES45.ConditionalExpression) {
+      const polarity = bindingValidationPolarity(current.test, bindingName);
+      if (polarity === "valid-when-true" && nodeWithin2(node, current.consequent) || polarity === "valid-when-false" && nodeWithin2(node, current.alternate)) {
+        return true;
+      }
+    }
+    if (current.type === AST_NODE_TYPES45.IfStatement) {
+      const polarity = bindingValidationPolarity(current.test, bindingName);
+      if (polarity === "valid-when-true" && nodeWithin2(node, current.consequent) || polarity === "valid-when-false" && current.alternate !== null && nodeWithin2(node, current.alternate)) {
+        return true;
+      }
+    }
+    if (current.type === AST_NODE_TYPES45.FunctionDeclaration || current.type === AST_NODE_TYPES45.FunctionExpression || current.type === AST_NODE_TYPES45.ArrowFunctionExpression) {
+      return false;
+    }
+  }
+  return false;
+};
+var isMemberUseWithinValidatedBranch = (node, access) => {
+  for (let current = node.parent; current !== void 0 && current !== null; current = current.parent) {
+    if (current.type === AST_NODE_TYPES45.ConditionalExpression) {
+      const polarity = memberValidationPolarity(current.test, access);
+      if (polarity === "valid-when-true" && nodeWithin2(node, current.consequent) || polarity === "valid-when-false" && nodeWithin2(node, current.alternate)) {
+        return true;
+      }
+    }
+    if (current.type === AST_NODE_TYPES45.IfStatement) {
+      const polarity = memberValidationPolarity(current.test, access);
+      if (polarity === "valid-when-true" && nodeWithin2(node, current.consequent) || polarity === "valid-when-false" && current.alternate !== null && nodeWithin2(node, current.alternate)) {
+        return true;
+      }
+    }
+    if (current.type === AST_NODE_TYPES45.FunctionDeclaration || current.type === AST_NODE_TYPES45.FunctionExpression || current.type === AST_NODE_TYPES45.ArrowFunctionExpression) {
+      return false;
+    }
+  }
+  return false;
+};
+var memberValidationPolarity = (test, access) => {
+  if (test.type === AST_NODE_TYPES45.UnaryExpression && test.operator === "!") {
+    const inner = memberValidationPolarity(test.argument, access);
+    return inner === "valid-when-true" ? "valid-when-false" : inner === "valid-when-false" ? "valid-when-true" : null;
+  }
+  if (test.type === AST_NODE_TYPES45.BinaryExpression) {
+    const isMatchingTypeof = (node) => node.type === AST_NODE_TYPES45.UnaryExpression && node.operator === "typeof" && isSamePlainMember(node.argument, access);
+    const isPrimitiveType = (node) => node.type === AST_NODE_TYPES45.Literal && typeof node.value === "string" && PRIMITIVE_TYPEOF_RESULTS.has(node.value);
+    if (!(isMatchingTypeof(test.left) && isPrimitiveType(test.right) || isMatchingTypeof(test.right) && isPrimitiveType(test.left))) {
+      return null;
+    }
+    if (test.operator === "===" || test.operator === "==") {
+      return "valid-when-true";
+    }
+    return test.operator === "!==" || test.operator === "!=" ? "valid-when-false" : null;
+  }
+  return test.type === AST_NODE_TYPES45.CallExpression && test.arguments.length === 1 && test.arguments[0] !== void 0 && test.arguments[0].type !== AST_NODE_TYPES45.SpreadElement && isSamePlainMember(test.arguments[0], access) && test.callee.type === AST_NODE_TYPES45.MemberExpression && !test.callee.computed && test.callee.object.type === AST_NODE_TYPES45.Identifier && test.callee.object.name === "Array" && test.callee.property.type === AST_NODE_TYPES45.Identifier && test.callee.property.name === "isArray" ? "valid-when-true" : null;
+};
 var isFullyValidatedExtractedBinding = (member, source, context) => {
   const isValidationReference = (identifier) => {
     for (let current = identifier.parent; current !== void 0 && current !== null; current = current.parent) {
@@ -11165,7 +11254,14 @@ var prefer_schema_for_api_payload_default = createRule({
           return;
         }
         const variable = obj?.type === AST_NODE_TYPES45.Identifier ? unvalidatedVariableRef(obj, scope, unvalidatedVariables) : null;
-        if (variable !== null) {
+        if (variable !== null && obj?.type === AST_NODE_TYPES45.Identifier) {
+          if (isUseWithinValidatedBranch(node, obj.name)) {
+            return;
+          }
+          const access = plainMemberAccess(node);
+          if (access !== null && isMemberUseWithinValidatedBranch(node, access)) {
+            return;
+          }
           if (isFullyValidatedExtractedBinding(node, variable, context)) {
             return;
           }
@@ -11617,16 +11713,17 @@ var preferServerActionsDocumentation = {
   rationale: "Server Actions preserve typed application calls and avoid an internal JSON request-response boundary.",
   remediation: "Move the mutation into a Server Action and invoke that action from the React client.",
   category: "architecture",
-  limitations: ["Only statically recognizable /api/ mutations in applicable React modules are reported."],
+  limitations: ["Only statically recognizable /api/ mutations in modules with positive Next.js evidence are reported: an explicit next import, or an app/pages path with a top-level use-client directive."],
   examples: [
     { id: "server-action-call", title: "Call a Server Action", outcome: "no-match", files: [{ path: "app/tasks/page.tsx", source: "import { createTask } from './actions'; await createTask(input);" }], focusPath: "app/tasks/page.tsx", expectedCount: 0, public: true },
-    { id: "api-mutation", title: "Do not mutate through an API route", outcome: "match", files: [{ path: "app/tasks/page.tsx", source: "await fetch('/api/tasks', { method: 'POST', body });" }], focusPath: "app/tasks/page.tsx", expectedCount: 1, public: true }
+    { id: "api-mutation", title: "Do not mutate through an API route", outcome: "match", files: [{ path: "app/tasks/page.tsx", source: "'use client'; await fetch('/api/tasks', { method: 'POST', body });" }], focusPath: "app/tasks/page.tsx", expectedCount: 1, public: true }
   ]
 };
 var MUTATION_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "DELETE", "PATCH"]);
 var AXIOS_MUTATION_METHODS = /* @__PURE__ */ new Set(["post", "put", "delete", "patch"]);
 var SKIP_FILE_REGEX = /(?:\.test\.[jt]sx?$|\.spec\.[jt]sx?$|-(?:test|spec)\.[jt]sx?$|\/tests?\/|\/__tests__\/|\/__testfixtures__\/|\/scripts?\/|\/app\/api\/.*\/route\.[jt]sx?$|\/pages\/api\/)/;
 var NON_REACT_FRAMEWORK_RE2 = /^(?:@angular\/|@nestjs\/|vue$|vue\/|svelte$|svelte\/|solid-js$|solid-js\/|@ember\/|rxjs$|rxjs\/)/;
+var NEXT_MODULE_PATH_RE2 = /(?:^|[/\\])(?:app|pages)[/\\]/u;
 function getScope(context, node) {
   return context.sourceCode.getScope(node);
 }
@@ -11740,6 +11837,16 @@ var prefer_server_actions_default = createRule({
     const isNonReactFramework = context.sourceCode.ast.body.some(
       (node) => node.type === "ImportDeclaration" && typeof node.source.value === "string" && NON_REACT_FRAMEWORK_RE2.test(node.source.value)
     );
+    const hasUseClientDirective = context.sourceCode.ast.body.some(
+      (node) => node.type === "ExpressionStatement" && node.expression.type === "Literal" && node.expression.value === "use client"
+    );
+    const hasNextImport = context.sourceCode.ast.body.some(
+      (node) => node.type === "ImportDeclaration" && typeof node.source.value === "string" && (node.source.value === "next" || node.source.value.startsWith("next/"))
+    );
+    const hasNextEvidence = hasNextImport || hasUseClientDirective && NEXT_MODULE_PATH_RE2.test(filename);
+    if (!hasNextEvidence) {
+      return {};
+    }
     return {
       CallExpression(node) {
         if (isNonReactFramework) return;
@@ -14316,7 +14423,7 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.2.0"
+  version: "15.4.0"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarj/eslint-plugin",
-  "version": "15.2.0",
+  "version": "15.4.0",
   "packageManager": "npm@11.19.0",
   "description": "Custom ESLint rules for hypermodern TypeScript / React / Next.js projects",
   "type": "module",