@agjs/tsforge 0.1.18 → 0.2.0

package/src/rule-packs/jwt-cookies/rules/jwt-must-verify-not-decode.ts

@@ -0,0 +1,124 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "jwt-must-verify-not-decode";
+
+export interface IJwtMustVerifyNotDecodeOptions {
+  readonly jwtObjectNames?: readonly string[];
+  readonly decodeMethods?: readonly string[];
+}
+
+type RuleOptions = [IJwtMustVerifyNotDecodeOptions];
+type MessageIds = "useVerifyNotDecode";
+
+const DEFAULT_JWT_OBJECTS: readonly string[] = ["jwt", "jsonwebtoken"];
+const DEFAULT_DECODE_METHODS: readonly string[] = ["decode", "decodeJwt"];
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    jwtObjectNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    decodeMethods: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+  },
+};
+
+function getMemberPropertyName(
+  member: TSESTree.MemberExpression
+): string | null {
+  if (!member.computed && member.property.type === AST_NODE_TYPES.Identifier) {
+    return member.property.name;
+  }
+
+  if (
+    member.computed &&
+    member.property.type === AST_NODE_TYPES.Literal &&
+    typeof member.property.value === "string"
+  ) {
+    return member.property.value;
+  }
+
+  return null;
+}
+
+function isJwtDecodeCall(
+  node: TSESTree.CallExpression,
+  jwtObjects: ReadonlySet<string>,
+  decodeMethods: ReadonlySet<string>
+): boolean {
+  const callee = node.callee;
+
+  if (callee.type !== AST_NODE_TYPES.MemberExpression || callee.computed) {
+    return false;
+  }
+
+  const method = getMemberPropertyName(callee);
+
+  if (method === null || !decodeMethods.has(method)) {
+    return false;
+  }
+
+  const receiver = callee.object;
+
+  if (receiver.type === AST_NODE_TYPES.Identifier) {
+    return jwtObjects.has(receiver.name);
+  }
+
+  if (
+    receiver.type === AST_NODE_TYPES.MemberExpression &&
+    !receiver.computed &&
+    receiver.property.type === AST_NODE_TYPES.Identifier
+  ) {
+    return jwtObjects.has(receiver.property.name);
+  }
+
+  return false;
+}
+
+export const jwtMustVerifyNotDecodeRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow `jwt.decode` / `decodeJwt` — decoding without verification accepts forged tokens. Use `jwt.verify` or `jwtVerify` instead.",
+    },
+    schema: [optionSchema],
+    messages: {
+      useVerifyNotDecode:
+        "Do not decode JWTs without verification — use `jwt.verify(...)` or `jwtVerify(...)` so signatures are checked.",
+    },
+  },
+  defaultOptions: [
+    {
+      jwtObjectNames: [...DEFAULT_JWT_OBJECTS],
+      decodeMethods: [...DEFAULT_DECODE_METHODS],
+    },
+  ],
+  create(context, [options]) {
+    const jwtObjects = new Set(options.jwtObjectNames ?? DEFAULT_JWT_OBJECTS);
+    const decodeMethods = new Set(
+      options.decodeMethods ?? DEFAULT_DECODE_METHODS
+    );
+
+    return {
+      CallExpression(node) {
+        if (isJwtDecodeCall(node, jwtObjects, decodeMethods)) {
+          context.report({ node, messageId: "useVerifyNotDecode" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/module-boundaries/index.ts

@@ -2,11 +2,13 @@ import type { TSESLint } from "@typescript-eslint/utils";
 
 import { noImportBuildOutputRule } from "./rules/no-import-build-output";
 import { noImportTestFromSourceRule } from "./rules/no-import-test-from-source";
+import { noReactInServicesRule } from "./rules/no-react-in-services";
 import type { IRulePack } from "../rule-packs.types";
 
 const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
   "no-import-build-output": noImportBuildOutputRule,
   "no-import-test-from-source": noImportTestFromSourceRule,
+  "no-react-in-services": noReactInServicesRule,
 };
 
 export const moduleBoundariesPack: IRulePack = {
@@ -17,6 +19,7 @@ export const moduleBoundariesPack: IRulePack = {
   rulesConfig: {
     "no-import-build-output": "error",
     "no-import-test-from-source": "error",
+    "no-react-in-services": "error",
   },
 };
 

package/src/rule-packs/module-boundaries/rules/no-react-in-services.ts

@@ -0,0 +1,111 @@
+import type { TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import { matchesAnyGlobPattern, toPosixRelative } from "../../utils";
+
+export const RULE_NAME = "no-react-in-services";
+
+export interface INoReactInServicesOptions {
+  readonly serviceGlobs?: readonly string[];
+  readonly forbiddenModules?: readonly string[];
+}
+
+type RuleOptions = [INoReactInServicesOptions];
+type MessageIds = "reactInService";
+
+const DEFAULT_SERVICE_GLOBS = [
+  "**/services/**",
+  "**/*.service.ts",
+  "**/*.queries.ts",
+] as const;
+
+const DEFAULT_FORBIDDEN = ["react", "react-dom"] as const;
+
+const DEFAULT_SERVICE_PATH_PATTERNS = [
+  /(^|\/)services\//,
+  /\.service\.tsx?$/,
+  /\.queries\.ts$/,
+] as const;
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    serviceGlobs: {
+      type: "array",
+      items: { type: "string" },
+    },
+    forbiddenModules: {
+      type: "array",
+      items: { type: "string" },
+    },
+  },
+};
+
+function isServiceFile(
+  filename: string,
+  cwd: string,
+  globs: readonly string[]
+): boolean {
+  const rel = toPosixRelative(filename, cwd);
+
+  if (DEFAULT_SERVICE_PATH_PATTERNS.some((pattern) => pattern.test(rel))) {
+    return true;
+  }
+
+  return matchesAnyGlobPattern(rel, globs);
+}
+
+export const noReactInServicesRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Service and data-fetch modules must not import React — keep business logic decoupled from the view layer.",
+    },
+    schema: [optionSchema],
+    messages: {
+      reactInService:
+        "Service/data layer file must not import `{{module}}` — keep React in components and hooks only.",
+    },
+  },
+  defaultOptions: [
+    {
+      serviceGlobs: [...DEFAULT_SERVICE_GLOBS],
+      forbiddenModules: [...DEFAULT_FORBIDDEN],
+    },
+  ],
+  create(context, [options]) {
+    const serviceGlobs = options.serviceGlobs ?? DEFAULT_SERVICE_GLOBS;
+    const forbidden = new Set(options.forbiddenModules ?? DEFAULT_FORBIDDEN);
+    const cwd = context.cwd;
+
+    if (!isServiceFile(context.filename, cwd, serviceGlobs)) {
+      return {};
+    }
+
+    return {
+      ImportDeclaration(node: TSESTree.ImportDeclaration) {
+        const source = node.source.value;
+
+        if (typeof source !== "string") {
+          return;
+        }
+
+        const base = source.split("/")[0];
+
+        if (base === undefined || !forbidden.has(base)) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "reactInService",
+          data: { module: base },
+        });
+      },
+    };
+  },
+});

package/src/rule-packs/nextjs/index.ts

@@ -1,14 +1,36 @@
 import type { TSESLint } from "@typescript-eslint/utils";
 
+import { awaitDynamicRequestApisRule } from "./rules/await-dynamic-request-apis";
 import { clientHooksRequireUseClientRule } from "./rules/client-hooks-require-use-client";
+import { errorBoundaryRequireUseClientRule } from "./rules/error-boundary-require-use-client";
+import { mutationShouldRevalidateCacheRule } from "./rules/mutation-should-revalidate-cache";
+import { noHtmlImgElementRule } from "./rules/no-html-img-element";
+import { noInternalApiFetchRule } from "./rules/no-internal-api-fetch";
 import { noNextHeadInAppRule } from "./rules/no-next-head-in-app";
 import { noPagesRouterDataFetchingInAppRule } from "./rules/no-pages-router-data-fetching-in-app";
+import { noSecretPropsToClientRule } from "./rules/no-secret-props-to-client";
+import { noSensitiveNextPublicEnvRule } from "./rules/no-sensitive-next-public-env";
+import { preferLazyUseStateInitRule } from "./rules/prefer-lazy-use-state-init";
+import { serverActionRequiresAuthzAndValidationRule } from "./rules/server-action-requires-authz-and-validation";
+import { serverOnlyModulesImportServerOnlyRule } from "./rules/server-only-modules-import-server-only";
 import type { IRulePack } from "../rule-packs.types";
 
 const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "await-dynamic-request-apis": awaitDynamicRequestApisRule,
   "client-hooks-require-use-client": clientHooksRequireUseClientRule,
+  "error-boundary-require-use-client": errorBoundaryRequireUseClientRule,
+  "mutation-should-revalidate-cache": mutationShouldRevalidateCacheRule,
+  "no-html-img-element": noHtmlImgElementRule,
+  "no-internal-api-fetch": noInternalApiFetchRule,
   "no-next-head-in-app": noNextHeadInAppRule,
   "no-pages-router-data-fetching-in-app": noPagesRouterDataFetchingInAppRule,
+  "no-secret-props-to-client": noSecretPropsToClientRule,
+  "no-sensitive-next-public-env": noSensitiveNextPublicEnvRule,
+  "prefer-lazy-use-state-init": preferLazyUseStateInitRule,
+  "server-action-requires-authz-and-validation":
+    serverActionRequiresAuthzAndValidationRule,
+  "server-only-modules-import-server-only":
+    serverOnlyModulesImportServerOnlyRule,
 };
 
 export const nextjsPack: IRulePack = {
@@ -17,9 +39,19 @@ export const nextjsPack: IRulePack = {
     "Next.js app-router correctness: server/client component boundaries and dead pages-router APIs.",
   rules,
   rulesConfig: {
+    "await-dynamic-request-apis": "error",
     "client-hooks-require-use-client": "error",
+    "error-boundary-require-use-client": "error",
+    "mutation-should-revalidate-cache": "warn",
+    "no-html-img-element": "warn",
+    "no-internal-api-fetch": "error",
     "no-next-head-in-app": "error",
     "no-pages-router-data-fetching-in-app": "error",
+    "no-secret-props-to-client": "warn",
+    "no-sensitive-next-public-env": "error",
+    "prefer-lazy-use-state-init": "warn",
+    "server-action-requires-authz-and-validation": "error",
+    "server-only-modules-import-server-only": "error",
   },
 };
 

package/src/rule-packs/nextjs/rules/await-dynamic-request-apis.ts

@@ -0,0 +1,65 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { calleeName, isServerAppFile } from "../utils";
+
+export const RULE_NAME = "await-dynamic-request-apis";
+
+type MessageIds = "mustAwait";
+
+const DYNAMIC_REQUEST_APIS = new Set(["cookies", "headers", "draftMode"]);
+
+function isAwaited(node: TSESTree.Node): boolean {
+  let current: TSESTree.Node | null | undefined = node.parent;
+
+  while (current !== undefined && current !== null) {
+    if (current.type === AST_NODE_TYPES.AwaitExpression) {
+      return true;
+    }
+
+    current = current.parent;
+  }
+
+  return false;
+}
+
+export const awaitDynamicRequestApisRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require awaiting Next.js dynamic request APIs (cookies, headers, draftMode) in app-router Server Components.",
+    },
+    schema: [],
+    messages: {
+      mustAwait:
+        "`{{api}}()` must be awaited in Server Components — use `await {{api}}()` (Next.js 15+ async request APIs).",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    let serverFile = false;
+
+    return {
+      Program(node: TSESTree.Program) {
+        serverFile = isServerAppFile(context.filename, node);
+      },
+      CallExpression(node: TSESTree.CallExpression) {
+        if (!serverFile || isAwaited(node)) {
+          return;
+        }
+
+        const name = calleeName(node.callee);
+
+        if (name !== null && DYNAMIC_REQUEST_APIS.has(name)) {
+          context.report({
+            node,
+            messageId: "mustAwait",
+            data: { api: name },
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/nextjs/rules/error-boundary-require-use-client.ts

@@ -0,0 +1,38 @@
+import type { TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { hasDirective, isErrorBoundaryFile } from "../utils";
+
+export const RULE_NAME = "error-boundary-require-use-client";
+
+type MessageIds = "missingUseClient";
+
+export const errorBoundaryRequireUseClientRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require 'use client' in app-router error.tsx and global-error.tsx — Next.js error boundaries must be Client Components.",
+    },
+    schema: [],
+    messages: {
+      missingUseClient:
+        "Error boundaries under app/ must start with `'use client'` — Next.js requires Client Components for error.tsx and global-error.tsx.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    if (!isErrorBoundaryFile(context.filename)) {
+      return {};
+    }
+
+    return {
+      Program(node: TSESTree.Program) {
+        if (!hasDirective(node, "use client")) {
+          context.report({ node, messageId: "missingUseClient" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/nextjs/rules/mutation-should-revalidate-cache.ts

@@ -0,0 +1,152 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import { walkSome } from "../../utils";
+import {
+  getFunctionLikeBody,
+  hasUseServerDirective,
+  isDbMutationCall,
+  isRouteHandlerFile,
+  type FunctionLike,
+} from "../../authorization/utils";
+
+export const RULE_NAME = "mutation-should-revalidate-cache";
+
+export interface IMutationShouldRevalidateCacheOptions {
+  readonly revalidateFunctions?: readonly string[];
+}
+
+type RuleOptions = [IMutationShouldRevalidateCacheOptions];
+type MessageIds = "missingRevalidation";
+
+const DEFAULT_REVALIDATE_FUNCTIONS = [
+  "revalidatePath",
+  "revalidateTag",
+] as const;
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    revalidateFunctions: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+  },
+};
+
+function containsRevalidateCall(
+  root: TSESTree.Node,
+  names: ReadonlySet<string>
+): boolean {
+  return walkSome(root, (node) => {
+    if (node.type !== AST_NODE_TYPES.CallExpression) {
+      return false;
+    }
+
+    const callee = node.callee;
+
+    if (callee.type === AST_NODE_TYPES.Identifier) {
+      return names.has(callee.name);
+    }
+
+    if (
+      callee.type === AST_NODE_TYPES.MemberExpression &&
+      !callee.computed &&
+      callee.property.type === AST_NODE_TYPES.Identifier
+    ) {
+      return names.has(callee.property.name);
+    }
+
+    return false;
+  });
+}
+
+function getFunctionName(node: FunctionLike): string {
+  if (node.type === AST_NODE_TYPES.FunctionDeclaration && node.id !== null) {
+    return node.id.name;
+  }
+
+  const parent = node.parent;
+
+  if (
+    parent?.type === AST_NODE_TYPES.VariableDeclarator &&
+    parent.id.type === AST_NODE_TYPES.Identifier
+  ) {
+    return parent.id.name;
+  }
+
+  return "handler";
+}
+
+export const mutationShouldRevalidateCacheRule = createRule<
+  RuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "After database mutations in server actions or route handlers, call `revalidatePath` or `revalidateTag` so cached pages reflect the change.",
+    },
+    schema: [optionSchema],
+    messages: {
+      missingRevalidation:
+        "{{name}} mutates data but does not call `revalidatePath` or `revalidateTag` — stale cached pages may be served.",
+    },
+  },
+  defaultOptions: [{ revalidateFunctions: [...DEFAULT_REVALIDATE_FUNCTIONS] }],
+  create(context, [options]) {
+    const revalidateFunctions = new Set(
+      options.revalidateFunctions ?? DEFAULT_REVALIDATE_FUNCTIONS
+    );
+    let useServerFile = false;
+    const isRouteHandler = isRouteHandlerFile(context.filename);
+
+    function visitFunction(node: FunctionLike): void {
+      if (!useServerFile && !isRouteHandler) {
+        return;
+      }
+
+      const body = getFunctionLikeBody(node);
+
+      if (body === null) {
+        return;
+      }
+
+      const hasMutation = walkSome(
+        body,
+        (child) =>
+          child.type === AST_NODE_TYPES.CallExpression &&
+          isDbMutationCall(child)
+      );
+
+      if (!hasMutation) {
+        return;
+      }
+
+      if (containsRevalidateCall(body, revalidateFunctions)) {
+        return;
+      }
+
+      context.report({
+        node,
+        messageId: "missingRevalidation",
+        data: { name: getFunctionName(node) },
+      });
+    }
+
+    return {
+      Program(node: TSESTree.Program) {
+        useServerFile = hasUseServerDirective(node);
+      },
+      FunctionDeclaration: visitFunction,
+      FunctionExpression: visitFunction,
+      ArrowFunctionExpression: visitFunction,
+    };
+  },
+});

package/src/rule-packs/nextjs/rules/no-html-img-element.ts

@@ -0,0 +1,45 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-html-img-element";
+
+type MessageIds = "useNextImage";
+
+function isHtmlImgElement(name: TSESTree.JSXTagNameExpression): boolean {
+  if (name.type === AST_NODE_TYPES.JSXIdentifier) {
+    return name.name === "img";
+  }
+
+  return false;
+}
+
+export const noHtmlImgElementRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Prefer next/image over raw <img> elements for optimized responsive images and Core Web Vitals.",
+    },
+    schema: [],
+    messages: {
+      useNextImage:
+        "Use `next/image` `<Image />` instead of `<img>` — it optimizes formats, sizing, and LCP preload.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    if (!context.filename.endsWith(".tsx")) {
+      return {};
+    }
+
+    return {
+      JSXOpeningElement(node: TSESTree.JSXOpeningElement) {
+        if (isHtmlImgElement(node.name)) {
+          context.report({ node, messageId: "useNextImage" });
+        }
+      },
+    };
+  },
+});