@slip-stream-kit/eslint-plugin 0.1.17 → 0.1.20

package/dist/index.js

@@ -40,18 +40,18 @@ var getComponentName = (node) => {
   }
   return null;
 };
-var returnsJsx = (node) => {
+var collectOwnReturnArguments = (node) => {
   if (node.body.type !== "BlockStatement") {
-    return isJsxNode(node.body);
+    return [node.body];
   }
-  let found = false;
+  const args = [];
   const visit = (current) => {
-    if (found || !current || NESTED_SCOPES.has(current.type)) {
+    if (!current || NESTED_SCOPES.has(current.type)) {
       return;
     }
     if (current.type === "ReturnStatement") {
-      if (isJsxNode(current.argument)) {
-        found = true;
+      if (current.argument) {
+        args.push(current.argument);
       }
       return;
     }
@@ -81,7 +81,10 @@ var returnsJsx = (node) => {
     }
   };
   node.body.body.forEach(visit);
-  return found;
+  return args;
+};
+var returnsJsx = (node) => {
+  return collectOwnReturnArguments(node).some(isJsxNode);
 };
 var isComponent = (node) => {
   const name = getComponentName(node);
@@ -226,7 +229,7 @@ var matchesAnyGlob = (filename, patterns) => {
   });
 };
 
-// src/rules/component-arrow-function.ts
+// src/rules/component-arrow-function/component-arrow-function.ts
 var ANONYMOUS_NAME = "component";
 var reportName = (fn) => {
   return getComponentName(fn) ?? ANONYMOUS_NAME;
@@ -272,7 +275,7 @@ var componentArrowFunction = {
     docs: {
       description: "Enforce that React components are declared as arrow functions, not `function` declarations or function expressions.",
       recommended: true,
-      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin"
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#component-arrow-function"
     },
     schema: [
       {
@@ -317,7 +320,7 @@ var componentArrowFunction = {
   }
 };
 
-// src/rules/component-file-order.ts
+// src/rules/component-file-order/component-file-order.ts
 var PROPS_SUFFIX = "Props";
 var getDirectivePrologueCount = (body) => {
   let count = 0;
@@ -371,6 +374,7 @@ var hasStrayBefore = (body, boundary, directiveCount, skipIndex) => {
     return index < boundary && index >= directiveCount && index !== skipIndex && statement.type !== "ImportDeclaration";
   });
 };
+var ANONYMOUS_COMPONENT = "component";
 var findImportOrderViolations = (importIndices, importBoundary) => {
   return importIndices.filter((importIndex) => {
     return importIndex > importBoundary;
@@ -393,7 +397,11 @@ var findAdjacencyViolations = (components, declIndexByName) => {
     }
     const propsIndex = declIndexByName.get(propsName);
     if (propsIndex !== void 0 && propsIndex !== component.index - 1) {
-      violations.push({ index: propsIndex, messageId: "interfaceImmediatelyBeforeComponent" });
+      violations.push({
+        index: propsIndex,
+        messageId: "interfaceImmediatelyBeforeComponent",
+        data: { interface: propsName, component: component.name ?? ANONYMOUS_COMPONENT }
+      });
     }
   }
   return violations;
@@ -404,14 +412,24 @@ var findAnchorViolations = (body, directiveCount, importIndices, first, firstPro
     return importIndex < firstPropsIndex;
   });
   if (importsBeforeInterface && hasStrayBefore(body, firstPropsIndex, directiveCount, first.index)) {
-    violations.push({ index: firstPropsIndex, messageId: "interfaceImmediatelyAfterImports" });
+    violations.push({
+      index: firstPropsIndex,
+      messageId: "interfaceImmediatelyAfterImports",
+      // `firstPropsIndex !== undefined` implies `firstPropsName !== null` (it is derived from it).
+      data: { interface: firstPropsName, component: first.name ?? ANONYMOUS_COMPONENT }
+    });
   }
   const firstPropsImported = firstPropsIndex === void 0 && firstPropsName !== null && importedNames.has(firstPropsName);
   const importsBeforeComponent = importIndices.every((importIndex) => {
     return importIndex < first.index;
   });
   if (firstPropsImported && importsBeforeComponent && hasStrayBefore(body, first.index, directiveCount)) {
-    violations.push({ index: first.index, messageId: "componentImmediatelyAfterImports" });
+    violations.push({
+      index: first.index,
+      messageId: "componentImmediatelyAfterImports",
+      // `firstPropsImported` requires `firstPropsName !== null`.
+      data: { interface: firstPropsName, component: first.name ?? ANONYMOUS_COMPONENT }
+    });
   }
   return violations;
 };
@@ -421,7 +439,7 @@ var componentFileOrder = {
     docs: {
       description: "Enforce a strict top-level order in React component files: imports first, then \u2014 for each component \u2014 its props interface/type declared immediately before the component.",
       recommended: true,
-      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin"
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#component-file-order"
     },
     schema: [
       {
@@ -442,10 +460,14 @@ var componentFileOrder = {
       }
     ],
     messages: {
+      // Generic on purpose: fires on a misplaced import, and the constraint is "before *every*
+      // component", so naming a single component would mislead in a multi-component file.
       importsFirst: "Imports must come before the component interface and declaration.",
-      interfaceImmediatelyBeforeComponent: "The component props interface must be declared immediately before the component.",
-      interfaceImmediatelyAfterImports: "The component props interface must be declared immediately after the imports, with no other declarations in between.",
-      componentImmediatelyAfterImports: "When the component props type is imported, the component must be declared immediately after the imports, with no other declarations in between."
+      // "props type" (not "interface"): the rule matches both `interface` and `type` alias props
+      // declarations, so the neutral term reads correctly for either.
+      interfaceImmediatelyBeforeComponent: "Declare the props type `{{interface}}` immediately before component `{{component}}` (no declarations between them).",
+      interfaceImmediatelyAfterImports: "Declare the props type `{{interface}}` (for component `{{component}}`) immediately after the imports, with no other declarations in between.",
+      componentImmediatelyAfterImports: "Props type `{{interface}}` is imported, so declare component `{{component}}` immediately after the imports, with no other declarations in between."
     }
   },
   create(context) {
@@ -484,14 +506,274 @@ var componentFileOrder = {
           )
         ];
         for (const violation of violations) {
-          context.report({ node: body[violation.index], messageId: violation.messageId });
+          context.report({ node: body[violation.index], messageId: violation.messageId, data: violation.data });
+        }
+      }
+    };
+  }
+};
+
+// src/rules/max-components-per-file/max-components-per-file.ts
+var DEFAULT_MAX_COMPONENTS = 4;
+var ANONYMOUS_NAME2 = "component";
+var componentFunctionsIn = (declaration) => {
+  if (declaration.type === "FunctionDeclaration") {
+    return isComponent(declaration) ? [declaration] : [];
+  }
+  if (declaration.type === "VariableDeclaration") {
+    return declaration.declarations.map((declarator) => {
+      return getComponentFunction(declarator.init);
+    }).filter((fn2) => {
+      return fn2 !== null && isComponent(fn2);
+    });
+  }
+  const fn = getComponentFunction(declaration);
+  return fn && isComponent(fn) ? [fn] : [];
+};
+var collectComponents = (body) => {
+  return body.flatMap((statement) => {
+    const declaration = unwrapExport(statement);
+    return declaration ? componentFunctionsIn(declaration) : [];
+  });
+};
+var maxComponentsPerFile = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Limit the number of React components declared in a single file; move extra components into their own files.",
+      recommended: true,
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#max-components-per-file"
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          maxComponents: {
+            type: "integer",
+            minimum: 1,
+            description: "Maximum number of component declarations a single file may contain before the rule reports."
+          },
+          paths: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional glob patterns. When provided, the rule only runs for files whose path matches one of them."
+          },
+          ignore: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional glob patterns. The rule is skipped for files whose path matches one of them, even if it also matches `paths`."
+          }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      // File-scoped problem → reported once, anchored to the first component over
+      // the limit so a human or AI fix loop has a concrete node to move out.
+      tooManyComponents: "This file declares {{count}} components (max {{max}}); move components such as {{name}} into separate files."
+    }
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const max = options.maxComponents ?? DEFAULT_MAX_COMPONENTS;
+    const paths = options.paths ?? [];
+    const ignore = options.ignore ?? [];
+    if (ignore.length > 0 && matchesAnyGlob(context.filename, ignore)) {
+      return {};
+    }
+    if (paths.length > 0 && !matchesAnyGlob(context.filename, paths)) {
+      return {};
+    }
+    return {
+      Program(program) {
+        const components = collectComponents(program.body);
+        if (components.length <= max) {
+          return;
+        }
+        const offender = components[max];
+        if (!offender) {
+          return;
         }
+        const name = getComponentName(offender) ?? ANONYMOUS_NAME2;
+        context.report({
+          node: offender,
+          messageId: "tooManyComponents",
+          data: { count: components.length, max, name }
+        });
       }
     };
   }
 };
 
-// src/rules/props-destructuring-blank-line.ts
+// src/rules/max-jsx-return-size/max-jsx-return-size.ts
+var DEFAULT_MAX_ELEMENTS = 20;
+var ANONYMOUS_NAME3 = "component";
+var isNode = (value) => {
+  return typeof value === "object" && value !== null && typeof value.type === "string";
+};
+var childNodes = (node, visitorKeys) => {
+  const children = [];
+  const keys = visitorKeys[node.type] ?? Object.keys(node);
+  for (const key of keys) {
+    if (key === "parent") {
+      continue;
+    }
+    const value = node[key];
+    if (Array.isArray(value)) {
+      children.push(...value.filter(isNode));
+    } else if (isNode(value)) {
+      children.push(value);
+    }
+  }
+  return children;
+};
+var countJsxElements = (node, visitorKeys) => {
+  const self = node.type === "JSXElement" ? 1 : 0;
+  return childNodes(node, visitorKeys).reduce((total, child) => {
+    return total + countJsxElements(child, visitorKeys);
+  }, self);
+};
+var jsxNameToString = (node) => {
+  const name = node;
+  switch (name?.type) {
+    case "JSXIdentifier":
+      return typeof name.name === "string" ? name.name : "element";
+    case "JSXMemberExpression":
+      return `${jsxNameToString(name.object)}.${jsxNameToString(name.property)}`;
+    case "JSXNamespacedName":
+      return `${jsxNameToString(name.namespace)}:${jsxNameToString(name.name)}`;
+    default:
+      return "element";
+  }
+};
+var topLevelElements = (root, visitorKeys) => {
+  const elements = [];
+  const walk2 = (node, isRoot) => {
+    if (!isRoot && node.type === "JSXElement") {
+      elements.push(node);
+      return;
+    }
+    for (const child of childNodes(node, visitorKeys)) {
+      walk2(child, false);
+    }
+  };
+  walk2(root, true);
+  return elements;
+};
+var largestBlock = (root, visitorKeys) => {
+  let best = null;
+  for (const element2 of topLevelElements(root, visitorKeys)) {
+    const count = countJsxElements(element2, visitorKeys);
+    if (!best || count > best.count) {
+      best = { node: element2, count };
+    }
+  }
+  if (!best) {
+    return null;
+  }
+  const element = best.node;
+  return { name: jsxNameToString(element.openingElement?.name), line: element.loc?.start.line ?? 0, count: best.count };
+};
+var componentFunctionsIn2 = (declaration) => {
+  if (declaration.type === "FunctionDeclaration") {
+    return isComponent(declaration) ? [declaration] : [];
+  }
+  if (declaration.type === "VariableDeclaration") {
+    return declaration.declarations.map((declarator) => {
+      return getComponentFunction(declarator.init);
+    }).filter((fn2) => {
+      return fn2 !== null && isComponent(fn2);
+    });
+  }
+  const fn = getComponentFunction(declaration);
+  return fn && isComponent(fn) ? [fn] : [];
+};
+var collectComponents2 = (body) => {
+  return body.flatMap((statement) => {
+    const declaration = unwrapExport(statement);
+    return declaration ? componentFunctionsIn2(declaration) : [];
+  });
+};
+var maxJsxReturnSize = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Warn when a component return renders too many JSX elements; extract parts into variables or sub-components.",
+      recommended: true,
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#max-jsx-return-size"
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          maxElements: {
+            type: "integer",
+            minimum: 1,
+            description: "Maximum number of JSX elements a single return may render before the rule reports."
+          },
+          paths: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional glob patterns. When provided, the rule only runs for files whose path matches one of them."
+          },
+          ignore: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional glob patterns. The rule is skipped for files whose path matches one of them, even if it also matches `paths`."
+          }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      // Points at the single biggest block so a human or AI fix loop knows
+      // exactly what to lift out.
+      tooManyElements: "{{name}} renders {{count}} JSX elements in one return (max {{max}}). Extract the largest block \u2014 <{{largest}}> at line {{line}} ({{largestCount}} elements) \u2014 into a variable or a sub-component.",
+      // Fallback when no single block dominates (e.g. many flat siblings): there is
+      // nothing meaningful to point at, so advise splitting.
+      tooManyElementsFlat: "{{name}} renders {{count}} JSX elements in one return (max {{max}}). Split it into smaller sub-components or extract groups of elements into variables."
+    }
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const max = options.maxElements ?? DEFAULT_MAX_ELEMENTS;
+    const paths = options.paths ?? [];
+    const ignore = options.ignore ?? [];
+    if (ignore.length > 0 && matchesAnyGlob(context.filename, ignore)) {
+      return {};
+    }
+    if (paths.length > 0 && !matchesAnyGlob(context.filename, paths)) {
+      return {};
+    }
+    const visitorKeys = context.sourceCode.visitorKeys;
+    const checkComponent = (fn) => {
+      const name = getComponentName(fn) ?? ANONYMOUS_NAME3;
+      for (const argument of collectOwnReturnArguments(fn)) {
+        const count = countJsxElements(argument, visitorKeys);
+        if (count <= max) {
+          continue;
+        }
+        const largest = largestBlock(argument, visitorKeys);
+        if (largest && largest.count >= 2) {
+          context.report({
+            node: argument,
+            messageId: "tooManyElements",
+            data: { count, max, name, largest: largest.name, line: largest.line, largestCount: largest.count }
+          });
+        } else {
+          context.report({ node: argument, messageId: "tooManyElementsFlat", data: { count, max, name } });
+        }
+      }
+    };
+    return {
+      Program(program) {
+        collectComponents2(program.body).forEach(checkComponent);
+      }
+    };
+  }
+};
+
+// src/rules/props-destructuring-blank-line/props-destructuring-blank-line.ts
 var isPropsDestructuring = (statement) => {
   if (statement.type !== "VariableDeclaration") {
     return false;
@@ -506,7 +788,7 @@ var propsDestructuringBlankLine = {
     docs: {
       description: "Require a blank line after the `const { ... } = props` destructuring statement at the top of a React component body.",
       recommended: true,
-      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin"
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#props-destructuring-blank-line"
     },
     fixable: "whitespace",
     schema: [],
@@ -554,7 +836,7 @@ var propsDestructuringBlankLine = {
   }
 };
 
-// src/rules/props-destructuring-newline.ts
+// src/rules/props-destructuring-newline/props-destructuring-newline.ts
 var collectBoundNames = (node, names) => {
   if (!node) {
     return;
@@ -588,7 +870,7 @@ var propsDestructuringNewline = {
     docs: {
       description: "Require React components to accept a single props parameter and destructure it on its own line in the body, rather than destructuring inline in the parameter list.",
       recommended: true,
-      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin"
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#props-destructuring-newline"
     },
     fixable: "code",
     schema: [],
@@ -665,7 +947,7 @@ ${baseIndent}}`
   }
 };
 
-// src/rules/props-type-name.ts
+// src/rules/props-type-name/props-type-name.ts
 var PROPS_SUFFIX2 = "Props";
 var propsTypeName = {
   meta: {
@@ -673,7 +955,7 @@ var propsTypeName = {
     docs: {
       description: "Require a React component's props type to be named `<ComponentName>Props` (e.g. `ButtonProps` for `Button`).",
       recommended: true,
-      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin"
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#props-type-name"
     },
     schema: [
       {
@@ -737,7 +1019,7 @@ var propsTypeName = {
   }
 };
 
-// src/rules/props-type-reference.ts
+// src/rules/props-type-reference/props-type-reference.ts
 var INLINE_OBJECT_TYPE = "TSTypeLiteral";
 var propsTypeReference = {
   meta: {
@@ -745,7 +1027,7 @@ var propsTypeReference = {
     docs: {
       description: "Require a React component's props parameter to use a named type (e.g. `ButtonProps`) instead of an inline object type literal.",
       recommended: true,
-      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin"
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#props-type-reference"
     },
     schema: [
       {
@@ -803,7 +1085,7 @@ var propsTypeReference = {
   }
 };
 
-// src/rules/require-component-stories.ts
+// src/rules/require-component-stories/require-component-stories.ts
 import { existsSync } from "node:fs";
 import path2 from "node:path";
 
@@ -879,7 +1161,7 @@ var deriveExpectedStoryPaths = (filePath, opts) => {
   });
 };
 
-// src/rules/require-component-stories.ts
+// src/rules/require-component-stories/require-component-stories.ts
 var toStoryPathOptions = (options) => {
   const picked = {};
   if (options.storiesDir !== void 0) {
@@ -905,7 +1187,7 @@ var requireComponentStories = {
     docs: {
       description: "Require a co-located Storybook story for every dumb component.",
       recommended: true,
-      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin"
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#require-component-stories"
     },
     schema: [
       {
@@ -1004,6 +1286,282 @@ var requireComponentStories = {
   }
 };
 
+// src/utils/cognitive-complexity.ts
+var NON_CHILD_KEYS = /* @__PURE__ */ new Set(["parent", "loc", "range", "type"]);
+var LOOP_TYPES = /* @__PURE__ */ new Set(["ForStatement", "ForInStatement", "ForOfStatement", "WhileStatement", "DoWhileStatement"]);
+var NESTED_FUNCTION_TYPES = /* @__PURE__ */ new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
+var isNode2 = (value) => {
+  return typeof value === "object" && value !== null && typeof value.type === "string";
+};
+var childrenOf = (node) => {
+  const children = [];
+  for (const key of Object.keys(node)) {
+    if (NON_CHILD_KEYS.has(key)) {
+      continue;
+    }
+    const value = node[key];
+    if (Array.isArray(value)) {
+      children.push(...value.filter(isNode2));
+    } else if (isNode2(value)) {
+      children.push(value);
+    }
+  }
+  return children;
+};
+var flattenLogicalOperators = (node, operators) => {
+  if (node.type !== "LogicalExpression") {
+    return [node];
+  }
+  const left = flattenLogicalOperators(node.left, operators);
+  operators.push(node.operator);
+  const right = flattenLogicalOperators(node.right, operators);
+  return [...left, ...right];
+};
+var countOperatorRuns = (operators) => {
+  let runs = 0;
+  let previous = null;
+  for (const operator of operators) {
+    if (operator !== previous) {
+      runs += 1;
+      previous = operator;
+    }
+  }
+  return runs;
+};
+var recurseChildren = (ctx, node, nesting) => {
+  for (const child of childrenOf(node)) {
+    walk(ctx, child, nesting);
+  }
+};
+var handleLogical = (ctx, node, nesting) => {
+  const operators = [];
+  const operands = flattenLogicalOperators(node, operators);
+  ctx.score += countOperatorRuns(operators);
+  for (const operand of operands) {
+    walk(ctx, operand, nesting);
+  }
+};
+var handleAlternate = (ctx, alternate, nesting) => {
+  if (!alternate) {
+    return;
+  }
+  if (alternate.type === "IfStatement") {
+    ctx.score += 1;
+    walk(ctx, alternate.test, nesting);
+    walk(ctx, alternate.consequent, nesting + 1);
+    handleAlternate(ctx, alternate.alternate, nesting);
+    return;
+  }
+  ctx.score += 1;
+  walk(ctx, alternate, nesting + 1);
+};
+var handleIf = (ctx, node, nesting) => {
+  ctx.score += 1 + nesting;
+  walk(ctx, node.test, nesting);
+  walk(ctx, node.consequent, nesting + 1);
+  handleAlternate(ctx, node.alternate, nesting);
+};
+var handleTernary = (ctx, node, nesting) => {
+  ctx.score += 1 + nesting;
+  walk(ctx, node.test, nesting);
+  walk(ctx, node.consequent, nesting + 1);
+  walk(ctx, node.alternate, nesting + 1);
+};
+var handleSwitch = (ctx, node, nesting) => {
+  ctx.score += 1 + nesting;
+  walk(ctx, node.discriminant, nesting);
+  for (const switchCase of node.cases) {
+    if (switchCase.test) {
+      walk(ctx, switchCase.test, nesting);
+    }
+    for (const statement of switchCase.consequent) {
+      walk(ctx, statement, nesting + 1);
+    }
+  }
+};
+var handleLoop = (ctx, node, nesting) => {
+  ctx.score += 1 + nesting;
+  const body = node.body;
+  for (const child of childrenOf(node)) {
+    walk(ctx, child, child === body ? nesting + 1 : nesting);
+  }
+};
+var handleTry = (ctx, node, nesting) => {
+  walk(ctx, node.block, nesting);
+  if (node.handler) {
+    ctx.score += 1 + nesting;
+    walk(ctx, node.handler.body, nesting + 1);
+  }
+  if (node.finalizer) {
+    walk(ctx, node.finalizer, nesting);
+  }
+};
+var handleCall = (ctx, node, nesting) => {
+  if (ctx.name && node.callee.type === "Identifier" && node.callee.name === ctx.name) {
+    ctx.score += 1;
+  }
+  recurseChildren(ctx, node, nesting);
+};
+function walk(ctx, node, nesting) {
+  const type = node.type;
+  if (type === "LogicalExpression") {
+    handleLogical(ctx, node, nesting);
+  } else if (type === "IfStatement") {
+    handleIf(ctx, node, nesting);
+  } else if (type === "ConditionalExpression") {
+    handleTernary(ctx, node, nesting);
+  } else if (type === "SwitchStatement") {
+    handleSwitch(ctx, node, nesting);
+  } else if (LOOP_TYPES.has(type)) {
+    handleLoop(ctx, node, nesting);
+  } else if (type === "TryStatement") {
+    handleTry(ctx, node, nesting);
+  } else if (NESTED_FUNCTION_TYPES.has(type)) {
+    walk(ctx, node.body, nesting + 1);
+  } else if (type === "CallExpression") {
+    handleCall(ctx, node, nesting);
+  } else {
+    recurseChildren(ctx, node, nesting);
+  }
+}
+var cognitiveComplexity = (fn, enclosingName) => {
+  const fallbackName = fn.type === "FunctionDeclaration" ? fn.id?.name ?? null : null;
+  const ctx = { score: 0, name: enclosingName ?? fallbackName };
+  walk(ctx, fn.body, 0);
+  return ctx.score;
+};
+
+// src/rules/require-jsdoc-example/require-jsdoc-example.ts
+var DEFAULT_MIN_COMPLEXITY = 8;
+var DEFAULT_EXAMPLE_COMPLEXITY = 12;
+var isTargetFn = (node) => {
+  return node?.type === "ArrowFunctionExpression" || node?.type === "FunctionExpression";
+};
+var getExportInfo = (statement) => {
+  if (statement.type === "ExportNamedDeclaration" || statement.type === "ExportDefaultDeclaration") {
+    return { exportStmt: statement, declaration: statement.declaration ?? null };
+  }
+  return { exportStmt: null, declaration: statement };
+};
+var targetsFromDeclaration = (declaration, anchors) => {
+  if (declaration.type === "FunctionDeclaration") {
+    return declaration.id ? [{ fn: declaration, name: declaration.id.name, anchors }] : [];
+  }
+  if (declaration.type === "VariableDeclaration") {
+    return declaration.declarations.flatMap((declarator) => {
+      return declarator.id.type === "Identifier" && isTargetFn(declarator.init) ? [{ fn: declarator.init, name: declarator.id.name, anchors }] : [];
+    });
+  }
+  return [];
+};
+var collectTargets = (body) => {
+  return body.flatMap((statement) => {
+    const { exportStmt, declaration } = getExportInfo(statement);
+    if (!declaration) {
+      return [];
+    }
+    const anchors = exportStmt ? [exportStmt, declaration] : [declaration];
+    return targetsFromDeclaration(declaration, anchors);
+  });
+};
+var hasJsdocBlock = (sourceCode, anchors) => {
+  return anchors.some((anchor) => {
+    return sourceCode.getCommentsBefore(anchor).some((comment) => {
+      return comment.type === "Block" && comment.value.startsWith("*");
+    });
+  });
+};
+var hasJsdocExample = (sourceCode, anchors) => {
+  return anchors.some((anchor) => {
+    return sourceCode.getCommentsBefore(anchor).some((comment) => {
+      return comment.type === "Block" && comment.value.startsWith("*") && comment.value.includes("@example");
+    });
+  });
+};
+var decideViolation = (target, settings, sourceCode) => {
+  const complexity = cognitiveComplexity(target.fn, target.name);
+  const { minComplexity, exampleComplexity } = settings;
+  if (complexity < minComplexity) {
+    return null;
+  }
+  const { name } = target;
+  if (!hasJsdocBlock(sourceCode, target.anchors)) {
+    return { messageId: "missingJsdoc", data: { name, complexity, minComplexity } };
+  }
+  if (complexity >= exampleComplexity && !hasJsdocExample(sourceCode, target.anchors)) {
+    return { messageId: "missingExample", data: { name, complexity, exampleComplexity } };
+  }
+  return null;
+};
+var requireJsdocExample = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Graduated JSDoc requirement by cognitive complexity: at or above `minComplexity` a function must carry a leading JSDoc block, and at or above `exampleComplexity` that block must also include an `@example` tag.",
+      recommended: true,
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#require-jsdoc-example"
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          minComplexity: {
+            type: "integer",
+            minimum: 1,
+            description: "Cognitive complexity at or above which a function must carry a leading JSDoc block."
+          },
+          exampleComplexity: {
+            type: "integer",
+            minimum: 1,
+            description: "Cognitive complexity at or above which the JSDoc block must also include an `@example` tag."
+          },
+          paths: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional glob patterns. When provided, the rule only runs for files whose path matches one of them."
+          },
+          ignore: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional glob patterns. The rule is skipped for files whose path matches one of them, even if it also matches `paths`."
+          }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      missingJsdoc: 'function "{{name}}" has cognitive complexity {{complexity}} (>= {{minComplexity}}); add a JSDoc block documenting it.',
+      missingExample: 'function "{{name}}" has cognitive complexity {{complexity}} (>= {{exampleComplexity}}); its JSDoc block needs an `@example` documenting usage.'
+    }
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const paths = options.paths ?? [];
+    const ignore = options.ignore ?? [];
+    if (ignore.length > 0 && matchesAnyGlob(context.filename, ignore)) {
+      return {};
+    }
+    if (paths.length > 0 && !matchesAnyGlob(context.filename, paths)) {
+      return {};
+    }
+    const settings = {
+      minComplexity: options.minComplexity ?? DEFAULT_MIN_COMPLEXITY,
+      exampleComplexity: options.exampleComplexity ?? DEFAULT_EXAMPLE_COMPLEXITY
+    };
+    const { sourceCode } = context;
+    return {
+      Program(program) {
+        for (const target of collectTargets(program.body)) {
+          const violation = decideViolation(target, settings, sourceCode);
+          if (violation) {
+            context.report({ node: target.fn, messageId: violation.messageId, data: violation.data });
+          }
+        }
+      }
+    };
+  }
+};
+
 // src/rules/index.ts
 var rules = {
   "props-destructuring-newline": propsDestructuringNewline,
@@ -1012,7 +1570,10 @@ var rules = {
   "props-type-name": propsTypeName,
   "component-file-order": componentFileOrder,
   "component-arrow-function": componentArrowFunction,
-  "require-component-stories": requireComponentStories
+  "max-components-per-file": maxComponentsPerFile,
+  "max-jsx-return-size": maxJsxReturnSize,
+  "require-component-stories": requireComponentStories,
+  "require-jsdoc-example": requireJsdocExample
 };
 
 // src/index.ts
@@ -1020,7 +1581,7 @@ var PLUGIN_NAME = "@wl";
 var plugin = {
   meta: {
     name: "@wl/eslint-plugin",
-    version: "0.1.14"
+    version: "0.1.20"
   },
   rules,
   configs: {}
@@ -1040,7 +1601,16 @@ plugin.configs.recommended = [
       // Pages and routes are excluded: route/page modules commonly use `function`
       // declarations (and framework conventions like default-exported page functions).
       [`${PLUGIN_NAME}/component-arrow-function`]: ["error", { ignore: ["**/pages/**", "**/routes/**"] }],
-      [`${PLUGIN_NAME}/require-component-stories`]: "error"
+      [`${PLUGIN_NAME}/require-component-stories`]: "error",
+      // Advisory: flags returns that render too many JSX elements; extract into a
+      // variable or sub-component. Warn-class by nature (`type: 'suggestion'`);
+      // severity confirmed against a repo-wide dry run at the default ceiling.
+      [`${PLUGIN_NAME}/max-jsx-return-size`]: "error",
+      // Caps component declarations per file; extra components belong in their own
+      // files. Pages and routes are excluded (framework conventions co-locate
+      // route trees and default-exported page functions). Ceiling confirmed
+      // against a repo-wide dry run at the default.
+      [`${PLUGIN_NAME}/max-components-per-file`]: ["error", { ignore: ["**/pages/**", "**/routes/**"] }]
     }
   },
   // Storybook stories legitimately deviate from the component conventions: the
@@ -1055,6 +1625,38 @@ plugin.configs.recommended = [
       [`${PLUGIN_NAME}/component-file-order`]: "off",
       [`${PLUGIN_NAME}/props-type-name`]: "off"
     }
+  },
+  // Dumb presentational files (`*-component.tsx`) follow the one-component-per-file
+  // convention the props/order/stories rules already assume, so they get a tighter
+  // ceiling of 1. This MUST come AFTER the global `**/*.tsx` block: flat config
+  // REPLACES rule options across matching blocks (it does not merge), and `ignore`
+  // is re-declared here so pages/routes dumb-components keep their exemption.
+  // A repo-wide dry run found zero `*-component.tsx` files declaring >1 component.
+  {
+    files: ["**/*-component.tsx"],
+    rules: {
+      [`${PLUGIN_NAME}/max-components-per-file`]: [
+        "error",
+        { maxComponents: 1, ignore: ["**/pages/**", "**/routes/**"] }
+      ]
+    }
+  },
+  // `require-jsdoc-example` targets named functions, which overwhelmingly live in
+  // plain `.ts` lib/util modules (not just `.tsx`), so it gets its OWN block scoped
+  // to both extensions — the tsx-only blocks above would never reach where it
+  // matters. Severity is `warn` (not `error`) so first adoption does not break
+  // consumers' CI; the graduated defaults (minComplexity 8 → require a JSDoc block,
+  // exampleComplexity 12 → also require `@example`) are left implicit. Flat config
+  // REPLACES rule options across matching blocks, so this rule lives only here and
+  // relies on no option merging.
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    plugins: {
+      [PLUGIN_NAME]: plugin
+    },
+    rules: {
+      [`${PLUGIN_NAME}/require-jsdoc-example`]: "warn"
+    }
   }
 ];
 var meta = plugin.meta;