@agjs/tsforge 0.1.19 → 0.2.1

package/src/rule-packs/react-component-architecture/index.ts

@@ -1,23 +1,35 @@
 import type { TSESLint } from "@typescript-eslint/utils";
 
+import { dangerousHtmlRequiresSanitizeRule } from "./rules/dangerous-html-requires-sanitize";
 import { componentFolderStructureRule } from "./rules/component-folder-structure";
 import { forwardrefDisplayNameRule } from "./rules/forwardref-display-name";
 import { indexMustReexportDefaultRule } from "./rules/index-must-reexport-default";
 import { maxHooksPerFileRule } from "./rules/max-hooks-per-file";
+import { noAnonymousUseEffectRule } from "./rules/no-anonymous-useEffect";
+import { noComponentInvocationRule } from "./rules/no-component-invocation";
 import { noCrossFeatureImportsRule } from "./rules/no-cross-feature-imports";
+import { noDerivedStateInEffectRule } from "./rules/no-derived-state-in-effect";
 import { noInlineJsxFunctionsRule } from "./rules/no-inline-jsx-functions";
 import { noJsxComputationRule } from "./rules/no-jsx-computation";
+import { noNestedComponentRule } from "./rules/no-nested-component";
+import { noReactFcRule } from "./rules/no-react-fc";
 import { noStateInComponentBodyRule } from "./rules/no-state-in-component-body";
 import type { IRulePack } from "../rule-packs.types";
 
 const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
   "component-folder-structure": componentFolderStructureRule,
+  "dangerous-html-requires-sanitize": dangerousHtmlRequiresSanitizeRule,
   "forwardref-display-name": forwardrefDisplayNameRule,
   "index-must-reexport-default": indexMustReexportDefaultRule,
   "max-hooks-per-file": maxHooksPerFileRule,
+  "no-anonymous-useEffect": noAnonymousUseEffectRule,
+  "no-component-invocation": noComponentInvocationRule,
   "no-cross-feature-imports": noCrossFeatureImportsRule,
+  "no-derived-state-in-effect": noDerivedStateInEffectRule,
   "no-inline-jsx-functions": noInlineJsxFunctionsRule,
   "no-jsx-computation": noJsxComputationRule,
+  "no-nested-component": noNestedComponentRule,
+  "no-react-fc": noReactFcRule,
   "no-state-in-component-body": noStateInComponentBodyRule,
 };
 
@@ -28,12 +40,18 @@ export const reactComponentArchitecturePack: IRulePack = {
   rules,
   rulesConfig: {
     "component-folder-structure": "error",
+    "dangerous-html-requires-sanitize": "error",
     "forwardref-display-name": "error",
     "index-must-reexport-default": "error",
     "max-hooks-per-file": "warn",
+    "no-anonymous-useEffect": "warn",
+    "no-component-invocation": "error",
     "no-cross-feature-imports": "error",
+    "no-derived-state-in-effect": "warn",
     "no-inline-jsx-functions": "warn",
     "no-jsx-computation": "error",
+    "no-nested-component": "error",
+    "no-react-fc": "error",
     "no-state-in-component-body": "error",
   },
 };

package/src/rule-packs/react-component-architecture/rules/dangerous-html-requires-sanitize.ts

@@ -0,0 +1,83 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "dangerous-html-requires-sanitize";
+
+type MessageIds = "missingSanitize";
+
+const SANITIZE_IMPORTS = new Set([
+  "dompurify",
+  "isomorphic-dompurify",
+  "sanitize-html",
+]);
+
+function fileImportsSanitizer(program: TSESTree.Program): boolean {
+  for (const statement of program.body) {
+    if (statement.type !== AST_NODE_TYPES.ImportDeclaration) {
+      continue;
+    }
+
+    const source = statement.source.value;
+
+    if (typeof source !== "string") {
+      continue;
+    }
+
+    const base = source.split("/")[0];
+
+    if (base !== undefined && SANITIZE_IMPORTS.has(base)) {
+      return true;
+    }
+
+    for (const spec of statement.specifiers) {
+      if (
+        spec.type === AST_NODE_TYPES.ImportSpecifier &&
+        spec.imported.type === AST_NODE_TYPES.Identifier &&
+        spec.imported.name.toLowerCase().includes("sanitize")
+      ) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+export const dangerousHtmlRequiresSanitizeRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "dangerouslySetInnerHTML requires a sanitization library (DOMPurify or equivalent) imported in the same file.",
+    },
+    schema: [],
+    messages: {
+      missingSanitize:
+        "`dangerouslySetInnerHTML` requires sanitizing HTML first — import DOMPurify (or isomorphic-dompurify) and pass sanitized markup.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    let hasSanitizerImport = false;
+
+    return {
+      Program(program: TSESTree.Program) {
+        hasSanitizerImport = fileImportsSanitizer(program);
+      },
+      JSXAttribute(node: TSESTree.JSXAttribute) {
+        if (
+          node.name.type !== AST_NODE_TYPES.JSXIdentifier ||
+          node.name.name !== "dangerouslySetInnerHTML"
+        ) {
+          return;
+        }
+
+        if (!hasSanitizerImport) {
+          context.report({ node, messageId: "missingSanitize" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/react-component-architecture/rules/no-anonymous-useEffect.ts

@@ -0,0 +1,61 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-anonymous-useEffect";
+
+type MessageIds = "anonymousEffect";
+
+function isUseEffectCall(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  if (
+    callee.type === AST_NODE_TYPES.Identifier &&
+    callee.name === "useEffect"
+  ) {
+    return true;
+  }
+
+  if (
+    callee.type === AST_NODE_TYPES.MemberExpression &&
+    !callee.computed &&
+    callee.property.type === AST_NODE_TYPES.Identifier &&
+    callee.property.name === "useEffect"
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+export const noAnonymousUseEffectRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow anonymous arrow functions passed to useEffect — use a named function for debuggable stack traces.",
+    },
+    schema: [],
+    messages: {
+      anonymousEffect:
+        "Pass a named function to `useEffect` (e.g. `useEffect(function syncSession() { ... }, deps)`) instead of an anonymous arrow.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        if (!isUseEffectCall(node)) {
+          return;
+        }
+
+        const effectFn = node.arguments[0];
+
+        if (effectFn?.type === AST_NODE_TYPES.ArrowFunctionExpression) {
+          context.report({ node: effectFn, messageId: "anonymousEffect" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/react-component-architecture/rules/no-component-invocation.ts

@@ -0,0 +1,55 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-component-invocation";
+
+type MessageIds = "componentInvocation";
+
+function isComponentName(name: string): boolean {
+  return /^[A-Z]/.test(name);
+}
+
+export const noComponentInvocationRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow invoking React components as plain functions — use JSX (`<Header />`) instead of `{Header()}`.",
+    },
+    schema: [],
+    messages: {
+      componentInvocation:
+        "Do not call `{{name}}()` as a function — render it as JSX: `<{{name}} />`.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      JSXExpressionContainer(node: TSESTree.JSXExpressionContainer) {
+        const expression = node.expression;
+
+        if (expression.type !== AST_NODE_TYPES.CallExpression) {
+          return;
+        }
+
+        const callee = expression.callee;
+
+        if (callee.type !== AST_NODE_TYPES.Identifier) {
+          return;
+        }
+
+        if (!isComponentName(callee.name)) {
+          return;
+        }
+
+        context.report({
+          node: expression,
+          messageId: "componentInvocation",
+          data: { name: callee.name },
+        });
+      },
+    };
+  },
+});

package/src/rule-packs/react-component-architecture/rules/no-derived-state-in-effect.ts

@@ -0,0 +1,204 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { walkSome } from "../../utils";
+
+export const RULE_NAME = "no-derived-state-in-effect";
+
+type MessageIds = "derivedStateInEffect";
+
+function isUseStateSetterName(name: string): boolean {
+  return /^set[A-Z]/.test(name);
+}
+
+function collectUseStateSetters(
+  node: TSESTree.FunctionDeclaration | TSESTree.ArrowFunctionExpression
+): Set<string> {
+  const setters = new Set<string>();
+  const body =
+    node.type === AST_NODE_TYPES.ArrowFunctionExpression
+      ? node.body.type === AST_NODE_TYPES.BlockStatement
+        ? node.body
+        : null
+      : node.body;
+
+  if (body === null) {
+    return setters;
+  }
+
+  walkSome(body, (current) => {
+    if (current.type !== AST_NODE_TYPES.VariableDeclarator) {
+      return false;
+    }
+
+    if (
+      current.id.type !== AST_NODE_TYPES.ArrayPattern ||
+      current.init?.type !== AST_NODE_TYPES.CallExpression
+    ) {
+      return false;
+    }
+
+    const initCallee = current.init.callee;
+
+    if (
+      initCallee.type !== AST_NODE_TYPES.Identifier ||
+      initCallee.name !== "useState"
+    ) {
+      return false;
+    }
+
+    const setter = current.id.elements[1];
+
+    if (setter?.type === AST_NODE_TYPES.Identifier) {
+      setters.add(setter.name);
+    }
+
+    return false;
+  });
+
+  return setters;
+}
+
+function isInsideNode(node: TSESTree.Node, ancestor: TSESTree.Node): boolean {
+  let current: TSESTree.Node | null | undefined = node;
+
+  while (current !== undefined && current !== null) {
+    if (current === ancestor) {
+      return true;
+    }
+
+    current = current.parent;
+  }
+
+  return false;
+}
+
+function setterCalledOutsideEffect(
+  root: TSESTree.Node,
+  setterName: string,
+  effectNode: TSESTree.CallExpression
+): boolean {
+  return walkSome(root, (current) => {
+    if (current.type !== AST_NODE_TYPES.CallExpression) {
+      return false;
+    }
+
+    if (isInsideNode(current, effectNode)) {
+      return false;
+    }
+
+    const callee = current.callee;
+
+    return (
+      callee.type === AST_NODE_TYPES.Identifier && callee.name === setterName
+    );
+  });
+}
+
+function effectCallsSetter(
+  effectFn: TSESTree.ArrowFunctionExpression | TSESTree.FunctionExpression,
+  setterName: string
+): boolean {
+  return walkSome(effectFn.body, (current) => {
+    if (current.type !== AST_NODE_TYPES.CallExpression) {
+      return false;
+    }
+
+    const callee = current.callee;
+
+    return (
+      callee.type === AST_NODE_TYPES.Identifier && callee.name === setterName
+    );
+  });
+}
+
+export const noDerivedStateInEffectRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow setting local state inside useEffect when the value can be derived during render (or memoized with useMemo).",
+    },
+    schema: [],
+    messages: {
+      derivedStateInEffect:
+        "Do not call `{{setter}}` only inside `useEffect` — compute derived values during render or wrap expensive work in `useMemo`.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    function checkFunction(
+      node: TSESTree.FunctionDeclaration | TSESTree.ArrowFunctionExpression
+    ): void {
+      const setters = collectUseStateSetters(node);
+
+      if (setters.size === 0) {
+        return;
+      }
+
+      const body =
+        node.type === AST_NODE_TYPES.ArrowFunctionExpression
+          ? node.body.type === AST_NODE_TYPES.BlockStatement
+            ? node.body
+            : null
+          : node.body;
+
+      if (body === null) {
+        return;
+      }
+
+      walkSome(body, (current) => {
+        if (current.type !== AST_NODE_TYPES.CallExpression) {
+          return false;
+        }
+
+        const callee = current.callee;
+
+        if (
+          callee.type !== AST_NODE_TYPES.Identifier ||
+          callee.name !== "useEffect"
+        ) {
+          return false;
+        }
+
+        const effectFn = current.arguments[0];
+
+        if (
+          effectFn?.type !== AST_NODE_TYPES.ArrowFunctionExpression &&
+          effectFn?.type !== AST_NODE_TYPES.FunctionExpression
+        ) {
+          return false;
+        }
+
+        for (const setterName of setters) {
+          if (!isUseStateSetterName(setterName)) {
+            continue;
+          }
+
+          if (
+            effectCallsSetter(effectFn, setterName) &&
+            !setterCalledOutsideEffect(body, setterName, current)
+          ) {
+            context.report({
+              node: current,
+              messageId: "derivedStateInEffect",
+              data: { setter: setterName },
+            });
+          }
+        }
+
+        return false;
+      });
+    }
+
+    return {
+      FunctionDeclaration: checkFunction,
+      ArrowFunctionExpression(node: TSESTree.ArrowFunctionExpression) {
+        if (node.parent?.type === AST_NODE_TYPES.VariableDeclarator) {
+          checkFunction(node);
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/react-component-architecture/rules/no-nested-component.ts

@@ -0,0 +1,152 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { walkAll } from "../../utils";
+import {
+  isComponentFile,
+  isJsxReturningFunction,
+  isStoryFile,
+  isTestFile,
+} from "../utils";
+
+export const RULE_NAME = "no-nested-component";
+
+type MessageIds = "nestedComponent";
+
+function isComponentName(name: string): boolean {
+  return /^[A-Z]/.test(name);
+}
+
+function returnsJsx(
+  node:
+    | TSESTree.FunctionDeclaration
+    | TSESTree.ArrowFunctionExpression
+    | TSESTree.FunctionExpression
+): boolean {
+  if (node.type === AST_NODE_TYPES.ArrowFunctionExpression) {
+    return isJsxReturningFunction(node);
+  }
+
+  const body = node.body;
+
+  if (body.type !== AST_NODE_TYPES.BlockStatement) {
+    return false;
+  }
+
+  for (const stmt of body.body) {
+    if (stmt.type !== AST_NODE_TYPES.ReturnStatement) {
+      continue;
+    }
+
+    const arg = stmt.argument;
+
+    if (
+      arg &&
+      (arg.type === AST_NODE_TYPES.JSXElement ||
+        arg.type === AST_NODE_TYPES.JSXFragment)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function isNestedComponentDeclaration(node: TSESTree.Node): boolean {
+  if (
+    node.type === AST_NODE_TYPES.FunctionDeclaration &&
+    node.id !== null &&
+    isComponentName(node.id.name) &&
+    returnsJsx(node)
+  ) {
+    return true;
+  }
+
+  if (node.type === AST_NODE_TYPES.VariableDeclaration) {
+    for (const decl of node.declarations) {
+      if (decl.id.type !== AST_NODE_TYPES.Identifier) {
+        continue;
+      }
+
+      if (!isComponentName(decl.id.name) || decl.init === null) {
+        continue;
+      }
+
+      if (
+        (decl.init.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+          decl.init.type === AST_NODE_TYPES.FunctionExpression) &&
+        returnsJsx(decl.init)
+      ) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+export const noNestedComponentRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow declaring React components inside another component body — nested components reset state on every parent render.",
+    },
+    schema: [],
+    messages: {
+      nestedComponent:
+        "Do not declare a component inside another component — move it to its own file or to module scope.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    const filename = context.filename;
+
+    if (
+      !isComponentFile(filename) ||
+      isStoryFile(filename) ||
+      isTestFile(filename)
+    ) {
+      return {};
+    }
+
+    function checkOuterComponent(
+      node:
+        | TSESTree.FunctionDeclaration
+        | TSESTree.ArrowFunctionExpression
+        | TSESTree.FunctionExpression
+    ): void {
+      if (!returnsJsx(node)) {
+        return;
+      }
+
+      const body =
+        node.type === AST_NODE_TYPES.ArrowFunctionExpression
+          ? node.body.type === AST_NODE_TYPES.BlockStatement
+            ? node.body
+            : null
+          : node.body;
+
+      if (body?.type !== AST_NODE_TYPES.BlockStatement) {
+        return;
+      }
+
+      walkAll(body, (nested) => {
+        if (nested === body) {
+          return;
+        }
+
+        if (isNestedComponentDeclaration(nested)) {
+          context.report({ node: nested, messageId: "nestedComponent" });
+        }
+      });
+    }
+
+    return {
+      FunctionDeclaration: checkOuterComponent,
+      FunctionExpression: checkOuterComponent,
+      ArrowFunctionExpression: checkOuterComponent,
+    };
+  },
+});

package/src/rule-packs/react-component-architecture/rules/no-react-fc.ts

@@ -0,0 +1,57 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-react-fc";
+
+type MessageIds = "noReactFc";
+
+function isReactFcType(node: TSESTree.TSTypeReference): boolean {
+  const typeName = node.typeName;
+
+  if (typeName.type === AST_NODE_TYPES.TSQualifiedName) {
+    const left = typeName.left;
+    const right = typeName.right.name;
+
+    if (left.type === AST_NODE_TYPES.Identifier && left.name === "React") {
+      return right === "FC" || right === "FunctionComponent";
+    }
+  }
+
+  if (typeName.type === AST_NODE_TYPES.Identifier) {
+    return (
+      typeName.name === "FC" ||
+      typeName.name === "FunctionComponent" ||
+      typeName.name === "VFC" ||
+      typeName.name === "VoidFunctionComponent"
+    );
+  }
+
+  return false;
+}
+
+export const noReactFcRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow React.FC / FunctionComponent — type props explicitly on the function parameter instead.",
+    },
+    schema: [],
+    messages: {
+      noReactFc:
+        "Do not use `React.FC` or `FunctionComponent` — declare props explicitly on the function (e.g. `function Button({ onClick }: IButtonProps)`).",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      TSTypeReference(node: TSESTree.TSTypeReference) {
+        if (isReactFcType(node)) {
+          context.report({ node, messageId: "noReactFc" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/rule-catalog.types.ts

@@ -0,0 +1,21 @@
+/** Adoption tier: safety rules default on; architecture rules opt-in via profile. */
+export type RuleTier = "safety" | "framework" | "architecture" | "experimental";
+
+export type FalsePositiveRisk = "low" | "medium" | "high";
+
+/** Catalog metadata for a single ESLint pack rule or meta-rule. */
+export interface IRuleCatalogEntry {
+  readonly tier: RuleTier;
+  readonly tags?: readonly string[];
+  readonly falsePositiveRisk?: FalsePositiveRisk;
+  readonly requiresTypeInfo?: boolean;
+  readonly profiles?: readonly ProfileId[];
+}
+
+export type ProfileId =
+  | "recommended"
+  | "strict"
+  | "security"
+  | "frontend"
+  | "backend"
+  | "opinionated";