@howells/lint 0.2.6 → 0.2.8

package/README.md

@@ -101,7 +101,11 @@ Use this lane when a project wants Oxlint and Oxfmt instead of Biome. React and
 
 React Doctor severities are passed through as published by React Doctor. Native Oxlint Next.js severities come from Oxlint's official `nextjs` plugin via Ultracite's Next preset. `@howells/lint` adds canonical Howells policy on top for file naming, barrel files, env access, file size, function size, complexity, and tests.
 
-The core Oxlint preset enables native Oxlint rules that keep code files navigable: `max-lines` errors above 600 non-comment, non-blank lines; `max-lines-per-function` errors above 120 non-comment, non-blank lines; `max-statements` errors above 45 statements per function; and `complexity` errors above cyclomatic complexity 15. Test files keep the file-level `max-lines` guard but disable function-size, statement-count, and complexity limits, because test framework callbacks naturally wrap many independent cases. Generated files should be ignored at the project level; rare intentional exceptions should use an exact-file override with a short refactor note.
+The core Oxlint preset enables native Oxlint rules that keep code files navigable: `max-lines` errors above 600 non-comment, non-blank lines; `max-lines-per-function` warns above 120 non-comment, non-blank lines; `max-statements` warns above 45 statements per function; and `complexity` warns above cyclomatic complexity 15. React projects promote React Doctor's `react-doctor/no-giant-component` rule to an error, so genuinely oversized components still block CI. Test files keep the file-level `max-lines` guard but disable function-size, statement-count, and complexity limits, because test framework callbacks naturally wrap many independent cases. Generated files should be ignored at the project level; rare intentional exceptions should use an exact-file override with a short refactor note.
+
+React and Next presets also reject generic component suffixes that tend to hide responsibility: `wrapper`, `client`, `page`, `component`, `container`, and `manager`. The rule checks `.jsx` and `.tsx` filenames and PascalCase component declarations. It allows real Next App Router `app/**/page.tsx` files and their conventional `Page` export.
+
+Next presets reject App Router pages that only pass through to one imported client component. Route pages should keep server composition, data loading, and route-level structure in the page, then push only the interactive leaves behind a client boundary.
 
 Choose the closest preset:
 

package/oxlint/core.mjs

@@ -16,7 +16,7 @@ export default defineConfig({
   plugins: [...new Set([...(ultraciteCore.plugins ?? []), "vitest"])],
   rules: {
     complexity: [
-      "error",
+      "warn",
       {
         max: 15,
       },
@@ -30,7 +30,7 @@ export default defineConfig({
       },
     ],
     "max-lines-per-function": [
-      "error",
+      "warn",
       {
         IIFEs: true,
         max: 120,
@@ -39,7 +39,7 @@ export default defineConfig({
       },
     ],
     "max-statements": [
-      "error",
+      "warn",
       {
         max: 45,
       },

package/oxlint/howells-policy-plugin.mjs

@@ -0,0 +1,289 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const BANNED_SUFFIXES = [
+  { kebab: "wrapper", pascal: "Wrapper" },
+  { kebab: "client", pascal: "Client" },
+  { kebab: "page", pascal: "Page" },
+  { kebab: "component", pascal: "Component" },
+  { kebab: "container", pascal: "Container" },
+  { kebab: "manager", pascal: "Manager" },
+];
+
+const COMPONENT_FILE_PATTERN = /\.[jt]sx$/u;
+const PASCAL_CASE_PATTERN = /^[A-Z]/u;
+const RELATIVE_IMPORT_PATTERN = /^\.{1,2}(?:\/|$)/u;
+const MODULE_EXTENSIONS = [".tsx", ".jsx", ".ts", ".js", ".mts", ".mjs"];
+
+function normalizeFilename(filename) {
+  return filename.replaceAll("\\", "/");
+}
+
+function basename(filename) {
+  const normalized = normalizeFilename(filename);
+  const lastSlash = normalized.lastIndexOf("/");
+  return lastSlash === -1 ? normalized : normalized.slice(lastSlash + 1);
+}
+
+function withoutExtension(filename) {
+  return filename.replace(/\.[^.]+$/u, "");
+}
+
+function isNextAppPageFile(filename) {
+  return /(?:^|\/)(?:src\/)?app\/(?:.*\/)?page\.[jt]sx$/u.test(normalizeFilename(filename));
+}
+
+function findFilenameSuffix(filename) {
+  if (!COMPONENT_FILE_PATTERN.test(filename)) {
+    return null;
+  }
+
+  if (isNextAppPageFile(filename)) {
+    return null;
+  }
+
+  const stem = withoutExtension(basename(filename)).toLowerCase();
+  return BANNED_SUFFIXES.find(({ kebab }) => stem === kebab || stem.endsWith(`-${kebab}`));
+}
+
+function findComponentNameSuffix(name) {
+  if (!PASCAL_CASE_PATTERN.test(name)) {
+    return null;
+  }
+
+  return BANNED_SUFFIXES.find(({ pascal }) => name === pascal || name.endsWith(pascal));
+}
+
+function isAllowedNextPageComponent(name, filename) {
+  return name === "Page" && isNextAppPageFile(filename);
+}
+
+function hasUseClientDirective(source) {
+  return /^(?:\uFEFF)?\s*["']use client["']\s*;/u.test(source);
+}
+
+function resolveRelativeModule(filename, specifier) {
+  const basePath = path.resolve(path.dirname(filename), specifier);
+  const candidates = path.extname(basePath)
+    ? [basePath]
+    : [
+        ...MODULE_EXTENSIONS.map((extension) => `${basePath}${extension}`),
+        ...MODULE_EXTENSIONS.map((extension) => path.join(basePath, `index${extension}`)),
+      ];
+
+  return candidates.find((candidate) => fs.existsSync(candidate));
+}
+
+function isClientComponentModule(filename, specifier) {
+  if (!RELATIVE_IMPORT_PATTERN.test(specifier)) {
+    return false;
+  }
+
+  const modulePath = resolveRelativeModule(filename, specifier);
+  if (!modulePath) {
+    return false;
+  }
+
+  return hasUseClientDirective(fs.readFileSync(modulePath, "utf8"));
+}
+
+function isPascalCaseJsxName(nameNode) {
+  return nameNode?.type === "JSXIdentifier" && PASCAL_CASE_PATTERN.test(nameNode.name);
+}
+
+function getSingleJsxElement(expression) {
+  if (!expression) {
+    return null;
+  }
+
+  if (expression.type === "JSXElement") {
+    return expression;
+  }
+
+  if (expression.type === "ParenthesizedExpression") {
+    return getSingleJsxElement(expression.expression);
+  }
+
+  if (expression.type !== "JSXFragment") {
+    return null;
+  }
+
+  const elementChildren = expression.children.filter(
+    (child) => child.type === "JSXElement" || child.type === "JSXFragment",
+  );
+  const meaningfulTextChildren = expression.children.filter(
+    (child) => child.type === "JSXText" && child.value.trim() !== "",
+  );
+
+  if (elementChildren.length !== 1 || meaningfulTextChildren.length > 0) {
+    return null;
+  }
+
+  return getSingleJsxElement(elementChildren[0]);
+}
+
+function getSingleReturnedComponentName(body) {
+  if (!body || body.type !== "BlockStatement" || body.body.length !== 1) {
+    return null;
+  }
+
+  const statement = body.body[0];
+  if (statement.type !== "ReturnStatement") {
+    return null;
+  }
+
+  const element = getSingleJsxElement(statement.argument);
+  const jsxName = element?.openingElement?.name;
+  if (!isPascalCaseJsxName(jsxName)) {
+    return null;
+  }
+
+  return jsxName.name;
+}
+
+function createNoGenericComponentSuffixRule(context) {
+  const filename = normalizeFilename(context.filename ?? "");
+  const reportedNodes = new WeakSet();
+
+  function reportFilename(programNode) {
+    const suffix = findFilenameSuffix(filename);
+    if (!suffix) {
+      return;
+    }
+
+    context.report({
+      node: programNode,
+      message: `Avoid generic component suffix "${suffix.kebab}" in filename "${basename(filename)}". Name the component after the specific UI, behavior, or domain responsibility it owns.`,
+    });
+  }
+
+  function reportComponentName(nameNode) {
+    if (!nameNode || reportedNodes.has(nameNode)) {
+      return;
+    }
+
+    const suffix = findComponentNameSuffix(nameNode.name);
+    if (!suffix || isAllowedNextPageComponent(nameNode.name, filename)) {
+      return;
+    }
+
+    reportedNodes.add(nameNode);
+    context.report({
+      node: nameNode,
+      message: `Avoid generic component suffix "${suffix.kebab}" in component "${nameNode.name}". Name the component after the specific UI, behavior, or domain responsibility it owns.`,
+    });
+  }
+
+  if (!COMPONENT_FILE_PATTERN.test(filename)) {
+    return {};
+  }
+
+  return {
+    Program: reportFilename,
+    ClassDeclaration(node) {
+      reportComponentName(node.id);
+    },
+    FunctionDeclaration(node) {
+      reportComponentName(node.id);
+    },
+    VariableDeclarator(node) {
+      if (node.id?.type === "Identifier") {
+        reportComponentName(node.id);
+      }
+    },
+    ExportDefaultDeclaration(node) {
+      const declaration = node.declaration;
+      if (declaration?.type === "FunctionDeclaration" || declaration?.type === "ClassDeclaration") {
+        reportComponentName(declaration.id);
+      }
+    },
+  };
+}
+
+function createNoSingleClientComponentPageRule(context) {
+  const filename = normalizeFilename(context.filename ?? "");
+  const importedComponentSources = new Map();
+
+  function reportSingleClientComponentPage(node, componentName) {
+    const source = importedComponentSources.get(componentName);
+    if (!source || !isClientComponentModule(filename, source)) {
+      return;
+    }
+
+    context.report({
+      node,
+      message: `Avoid making a Next page a pass-through to one client component "${componentName}". Keep route-level data loading and server composition in the page, and move only interactive leaves behind the client boundary.`,
+    });
+  }
+
+  function checkPageFunction(node) {
+    const componentName = getSingleReturnedComponentName(node.body);
+    if (!componentName) {
+      return;
+    }
+
+    reportSingleClientComponentPage(node, componentName);
+  }
+
+  if (!isNextAppPageFile(filename)) {
+    return {};
+  }
+
+  return {
+    ImportDeclaration(node) {
+      if (
+        typeof node.source?.value !== "string" ||
+        !RELATIVE_IMPORT_PATTERN.test(node.source.value)
+      ) {
+        return;
+      }
+
+      for (const specifier of node.specifiers ?? []) {
+        if (specifier.type === "ImportSpecifier" && specifier.local?.type === "Identifier") {
+          importedComponentSources.set(specifier.local.name, node.source.value);
+        }
+
+        if (specifier.type === "ImportDefaultSpecifier" && specifier.local?.type === "Identifier") {
+          importedComponentSources.set(specifier.local.name, node.source.value);
+        }
+      }
+    },
+    ExportDefaultDeclaration(node) {
+      if (node.declaration?.type === "FunctionDeclaration") {
+        checkPageFunction(node.declaration);
+      }
+    },
+  };
+}
+
+const plugin = {
+  meta: {
+    name: "howells",
+  },
+  rules: {
+    "no-generic-component-suffix": {
+      meta: {
+        type: "suggestion",
+        docs: {
+          description: "Disallow generic React component suffixes that hide responsibility.",
+        },
+        messages: {},
+        schema: [],
+      },
+      create: createNoGenericComponentSuffixRule,
+    },
+    "no-single-client-component-page": {
+      meta: {
+        type: "problem",
+        docs: {
+          description: "Disallow Next page files that only pass through to one client component.",
+        },
+        messages: {},
+        schema: [],
+      },
+      create: createNoSingleClientComponentPageRule,
+    },
+  },
+};
+
+export default plugin;

package/oxlint/next.mjs

@@ -4,6 +4,9 @@ import ultraciteNext from "ultracite/oxlint/next";
 import react from "./react.mjs";
 
 export default defineConfig({
-	extends: [react, ultraciteNext],
-	rules: NEXTJS_RULES,
+  extends: [react, ultraciteNext],
+  rules: {
+    ...NEXTJS_RULES,
+    "howells/no-single-client-component-page": "error",
+  },
 });

package/oxlint/react.mjs

@@ -3,10 +3,18 @@ import { RECOMMENDED_RULES } from "oxlint-plugin-react-doctor";
 import ultraciteReact from "ultracite/oxlint/react";
 import core from "./core.mjs";
 
+const reactDoctorPluginSpecifier = import.meta.resolve("oxlint-plugin-react-doctor");
+const howellsPolicyPluginSpecifier = new URL("./howells-policy-plugin.mjs", import.meta.url).href;
+
 export default defineConfig({
-	extends: [core, ultraciteReact],
-	jsPlugins: [
-		{ name: "react-doctor", specifier: "oxlint-plugin-react-doctor" },
-	],
-	rules: RECOMMENDED_RULES,
+  extends: [core, ultraciteReact],
+  jsPlugins: [
+    { name: "react-doctor", specifier: reactDoctorPluginSpecifier },
+    { name: "howells", specifier: howellsPolicyPluginSpecifier },
+  ],
+  rules: {
+    ...RECOMMENDED_RULES,
+    "howells/no-generic-component-suffix": "error",
+    "react-doctor/no-giant-component": "error",
+  },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/lint",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Pinned Biome, Oxlint/Oxfmt, Ultracite, and React Doctor presets for Howells projects.",
   "keywords": [],
   "homepage": "https://github.com/howells/lint#readme",
@@ -87,6 +87,6 @@
     "node": ">=22.18.0"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test"
   }
 }