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

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/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 walk = (node, isRoot) => {
+    if (!isRoot && node.type === "JSXElement") {
+      elements.push(node);
+      return;
+    }
+    for (const child of childNodes(node, visitorKeys)) {
+      walk(child, false);
+    }
+  };
+  walk(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.ts
+// 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: [
       {
@@ -1012,6 +1294,8 @@ var rules = {
   "props-type-name": propsTypeName,
   "component-file-order": componentFileOrder,
   "component-arrow-function": componentArrowFunction,
+  "max-components-per-file": maxComponentsPerFile,
+  "max-jsx-return-size": maxJsxReturnSize,
   "require-component-stories": requireComponentStories
 };
 
@@ -1040,7 +1324,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 +1348,21 @@ 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/**"] }
+      ]
+    }
   }
 ];
 var meta = plugin.meta;