@agjs/tsforge 0.1.18 → 0.2.0

package/src/rule-packs/nextjs/rules/no-internal-api-fetch.ts

@@ -0,0 +1,126 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { calleeName, isServerAppFile } from "../utils";
+
+export const RULE_NAME = "no-internal-api-fetch";
+
+type MessageIds = "internalApiFetch";
+
+function urlLooksLikeInternalApi(value: string): boolean {
+  const trimmed = value.trim();
+
+  if (trimmed.startsWith("/api/") || trimmed === "/api") {
+    return true;
+  }
+
+  return /localhost(?::\d+)?\/api\b/.test(trimmed);
+}
+
+function literalApiUrl(node: TSESTree.Expression): boolean {
+  if (node.type === AST_NODE_TYPES.Literal && typeof node.value === "string") {
+    return urlLooksLikeInternalApi(node.value);
+  }
+
+  return false;
+}
+
+function templateApiUrl(node: TSESTree.TemplateLiteral): boolean {
+  const cooked = node.quasis.map((q) => q.value.cooked ?? "").join("");
+
+  return urlLooksLikeInternalApi(cooked);
+}
+
+function firstArgLooksLikeInternalApi(
+  args: readonly TSESTree.CallExpressionArgument[]
+): boolean {
+  const first = args[0];
+
+  if (first === undefined || first.type === AST_NODE_TYPES.SpreadElement) {
+    return false;
+  }
+
+  if (literalApiUrl(first)) {
+    return true;
+  }
+
+  if (first.type === AST_NODE_TYPES.TemplateLiteral) {
+    return templateApiUrl(first);
+  }
+
+  return false;
+}
+
+function isFetchCall(node: TSESTree.CallExpression): boolean {
+  const name = calleeName(node.callee);
+
+  return name === "fetch";
+}
+
+function isAxiosApiCall(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  if (callee.type !== AST_NODE_TYPES.MemberExpression || callee.computed) {
+    return false;
+  }
+
+  if (
+    callee.object.type !== AST_NODE_TYPES.Identifier ||
+    callee.object.name !== "axios"
+  ) {
+    return false;
+  }
+
+  if (callee.property.type !== AST_NODE_TYPES.Identifier) {
+    return false;
+  }
+
+  const method = callee.property.name;
+
+  return (
+    method === "get" ||
+    method === "post" ||
+    method === "put" ||
+    method === "patch" ||
+    method === "delete" ||
+    method === "request"
+  );
+}
+
+export const noInternalApiFetchRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow Server Components from fetching the app's own /api routes — import services or ORM modules directly to avoid loopback HTTP overhead.",
+    },
+    schema: [],
+    messages: {
+      internalApiFetch:
+        "Do not fetch `/api/*` from a Server Component — import the data/service module directly instead of loopback HTTP.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    let serverFile = false;
+
+    return {
+      Program(node: TSESTree.Program) {
+        serverFile = isServerAppFile(context.filename, node);
+      },
+      CallExpression(node: TSESTree.CallExpression) {
+        if (!serverFile) {
+          return;
+        }
+
+        if (
+          (isFetchCall(node) || isAxiosApiCall(node)) &&
+          firstArgLooksLikeInternalApi(node.arguments)
+        ) {
+          context.report({ node, messageId: "internalApiFetch" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/nextjs/rules/no-secret-props-to-client.ts

@@ -0,0 +1,118 @@
+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 { isServerAppFile } from "../utils";
+
+export const RULE_NAME = "no-secret-props-to-client";
+
+export interface INoSecretPropsToClientOptions {
+  readonly secretPropPatterns?: readonly string[];
+}
+
+type RuleOptions = [INoSecretPropsToClientOptions];
+type MessageIds = "secretPropToClient";
+
+const DEFAULT_SECRET_PROP_PATTERNS = [
+  "secret",
+  "password",
+  "token",
+  "apiKey",
+  "api_key",
+  "privateKey",
+  "private_key",
+  "credential",
+  "authToken",
+  "accessToken",
+  "refreshToken",
+] as const;
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    secretPropPatterns: {
+      type: "array",
+      items: { type: "string", minLength: 1 },
+      uniqueItems: true,
+      minItems: 1,
+    },
+  },
+};
+
+function propNameLooksSecret(
+  name: string,
+  patterns: readonly string[]
+): boolean {
+  const lower = name.toLowerCase();
+
+  return patterns.some((pattern) => lower.includes(pattern.toLowerCase()));
+}
+
+function getJsxAttributeName(
+  attribute: TSESTree.JSXAttribute | TSESTree.JSXSpreadAttribute
+): string | null {
+  if (attribute.type === AST_NODE_TYPES.JSXSpreadAttribute) {
+    return null;
+  }
+
+  const name = attribute.name;
+
+  if (name.type === AST_NODE_TYPES.JSXIdentifier) {
+    return name.name;
+  }
+
+  if (name.type === AST_NODE_TYPES.JSXNamespacedName) {
+    return name.name.name;
+  }
+
+  return null;
+}
+
+export const noSecretPropsToClientRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Warn when Server Components pass secret-looking props to JSX — values may cross the client boundary.",
+    },
+    schema: [optionSchema],
+    messages: {
+      secretPropToClient:
+        "Prop `{{name}}` looks like a secret — do not pass it from Server Components to client-rendered JSX.",
+    },
+  },
+  defaultOptions: [{ secretPropPatterns: [...DEFAULT_SECRET_PROP_PATTERNS] }],
+  create(context, [options]) {
+    const patterns = options.secretPropPatterns ?? DEFAULT_SECRET_PROP_PATTERNS;
+    let serverFile = false;
+
+    return {
+      Program(node: TSESTree.Program) {
+        serverFile = isServerAppFile(context.filename, node);
+      },
+      JSXOpeningElement(node) {
+        if (!serverFile) {
+          return;
+        }
+
+        for (const attr of node.attributes) {
+          const propName = getJsxAttributeName(attr);
+
+          if (propName === null) {
+            continue;
+          }
+
+          if (propNameLooksSecret(propName, patterns)) {
+            context.report({
+              node: attr,
+              messageId: "secretPropToClient",
+              data: { name: propName },
+            });
+          }
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/nextjs/rules/no-sensitive-next-public-env.ts

@@ -0,0 +1,72 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-sensitive-next-public-env";
+
+type MessageIds = "sensitiveNextPublic";
+
+const SENSITIVE_NAME = /(?:SECRET|PRIVATE|PASSWORD|TOKEN|DATABASE|STRIPE|KEY)/i;
+
+function isProcessEnvMember(node: TSESTree.MemberExpression): string | null {
+  if (node.computed) {
+    return null;
+  }
+
+  if (
+    node.object.type !== AST_NODE_TYPES.MemberExpression ||
+    node.object.computed ||
+    node.object.object.type !== AST_NODE_TYPES.Identifier ||
+    node.object.object.name !== "process" ||
+    node.object.property.type !== AST_NODE_TYPES.Identifier ||
+    node.object.property.name !== "env"
+  ) {
+    return null;
+  }
+
+  if (node.property.type !== AST_NODE_TYPES.Identifier) {
+    return null;
+  }
+
+  return node.property.name;
+}
+
+function isSensitiveNextPublicName(name: string): boolean {
+  if (!name.startsWith("NEXT_PUBLIC_")) {
+    return false;
+  }
+
+  return SENSITIVE_NAME.test(name);
+}
+
+export const noSensitiveNextPublicEnvRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow NEXT_PUBLIC_* env vars whose names suggest secrets — public build-time vars are visible in the client bundle.",
+    },
+    schema: [],
+    messages: {
+      sensitiveNextPublic:
+        "`process.env.{{name}}` looks like a secret exposed to the browser — remove NEXT_PUBLIC_ or keep it server-only.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      MemberExpression(node: TSESTree.MemberExpression) {
+        const envName = isProcessEnvMember(node);
+
+        if (envName !== null && isSensitiveNextPublicName(envName)) {
+          context.report({
+            node,
+            messageId: "sensitiveNextPublic",
+            data: { name: envName },
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/nextjs/rules/prefer-lazy-use-state-init.ts

@@ -0,0 +1,85 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { walkSome } from "../../utils";
+import { calleeName } from "../utils";
+
+export const RULE_NAME = "prefer-lazy-use-state-init";
+
+type MessageIds = "preferLazyInit";
+
+function isExpression(node: TSESTree.Node): node is TSESTree.Expression {
+  return node.type !== AST_NODE_TYPES.SpreadElement;
+}
+
+function touchesBrowserStorage(node: TSESTree.Node): boolean {
+  return walkSome(node, (current) => {
+    if (current.type !== AST_NODE_TYPES.MemberExpression || current.computed) {
+      return false;
+    }
+
+    if (current.object.type !== AST_NODE_TYPES.Identifier) {
+      return false;
+    }
+
+    return (
+      current.object.name === "localStorage" ||
+      current.object.name === "sessionStorage"
+    );
+  });
+}
+
+function isLazyInitializer(
+  init: TSESTree.Expression | null | undefined
+): boolean {
+  if (init === null || init === undefined) {
+    return false;
+  }
+
+  return (
+    init.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+    init.type === AST_NODE_TYPES.FunctionExpression
+  );
+}
+
+export const preferLazyUseStateInitRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Prefer lazy useState initializers when parsing localStorage/sessionStorage — avoids re-parsing on every render.",
+    },
+    schema: [],
+    messages: {
+      preferLazyInit:
+        "Wrap expensive storage parsing in a lazy initializer: `useState(() => JSON.parse(localStorage.getItem('key') ?? '{}'))`.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        const name = calleeName(node.callee);
+
+        if (name !== "useState") {
+          return;
+        }
+
+        const init = node.arguments[0];
+
+        if (init === undefined || !isExpression(init)) {
+          return;
+        }
+
+        if (isLazyInitializer(init)) {
+          return;
+        }
+
+        if (touchesBrowserStorage(init)) {
+          context.report({ node, messageId: "preferLazyInit" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/nextjs/rules/server-action-requires-authz-and-validation.ts

@@ -0,0 +1,178 @@
+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 {
+  containsAuthzCall,
+  defaultAuthzOptions,
+  getFunctionLikeBody,
+  hasUseServerDirective,
+  isDbMutationCall,
+  resolveAuthzFunctions,
+  type FunctionLike,
+  type IAuthzOptions,
+} from "../../authorization/utils";
+
+export const RULE_NAME = "server-action-requires-authz-and-validation";
+
+export interface IServerActionRequiresAuthzAndValidationOptions extends IAuthzOptions {
+  readonly parseMethods?: readonly string[];
+}
+
+type RuleOptions = [IServerActionRequiresAuthzAndValidationOptions];
+type MessageIds = "missingAuthz" | "missingValidation";
+
+const DEFAULT_PARSE_METHODS = ["parse", "safeParse"] as const;
+
+const extendedOptionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    authzFunctions: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    parseMethods: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+  },
+};
+
+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 "server action";
+}
+
+function containsParseCall(
+  root: TSESTree.Node,
+  parseMethods: 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.MemberExpression &&
+      !callee.computed &&
+      callee.property.type === AST_NODE_TYPES.Identifier &&
+      parseMethods.has(callee.property.name)
+    ) {
+      return true;
+    }
+
+    if (
+      callee.type === AST_NODE_TYPES.Identifier &&
+      parseMethods.has(callee.name)
+    ) {
+      return true;
+    }
+
+    return false;
+  });
+}
+
+export const serverActionRequiresAuthzAndValidationRule = createRule<
+  RuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        'Server actions (`"use server"`) that mutate the database must call authorization helpers and validate input with `.parse()` / `.safeParse()`.',
+    },
+    schema: [extendedOptionSchema],
+    messages: {
+      missingAuthz:
+        'Server action "{{name}}" performs a database mutation but does not call an authorization helper (e.g. {{examples}}).',
+      missingValidation:
+        'Server action "{{name}}" performs a database mutation but does not validate input with `.parse()` / `.safeParse()`.',
+    },
+  },
+  defaultOptions: [
+    {
+      ...defaultAuthzOptions(),
+      parseMethods: [...DEFAULT_PARSE_METHODS],
+    },
+  ],
+  create(context, [options]) {
+    const authzNames = resolveAuthzFunctions(options);
+    const parseMethods = new Set(options.parseMethods ?? DEFAULT_PARSE_METHODS);
+    const examples = [...authzNames].slice(0, 2).join(", ");
+    let useServerFile = false;
+
+    function visitFunction(node: FunctionLike): void {
+      if (!useServerFile) {
+        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;
+      }
+
+      const name = getFunctionName(node);
+      const hasAuthz = containsAuthzCall(body, authzNames);
+      const hasValidation = containsParseCall(body, parseMethods);
+
+      if (!hasAuthz) {
+        context.report({
+          node,
+          messageId: "missingAuthz",
+          data: { name, examples },
+        });
+      }
+
+      if (!hasValidation) {
+        context.report({
+          node,
+          messageId: "missingValidation",
+          data: { name },
+        });
+      }
+    }
+
+    return {
+      Program(node: TSESTree.Program) {
+        useServerFile = hasUseServerDirective(node);
+      },
+      FunctionDeclaration: visitFunction,
+      FunctionExpression: visitFunction,
+      ArrowFunctionExpression: visitFunction,
+    };
+  },
+});

package/src/rule-packs/nextjs/rules/server-only-modules-import-server-only.ts

@@ -0,0 +1,87 @@
+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 { hasDirective, isAppRouterFile } from "../utils";
+
+export const RULE_NAME = "server-only-modules-import-server-only";
+
+export interface IServerOnlyModulesImportServerOnlyOptions {
+  readonly serverOnlyModule?: string;
+}
+
+type RuleOptions = [IServerOnlyModulesImportServerOnlyOptions];
+type MessageIds = "missingServerOnlyImport";
+
+const DEFAULT_SERVER_ONLY_MODULE = "server-only";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    serverOnlyModule: { type: "string", minLength: 1 },
+  },
+};
+
+function hasServerOnlyImport(
+  program: TSESTree.Program,
+  moduleName: string
+): boolean {
+  for (const stmt of program.body) {
+    if (stmt.type !== AST_NODE_TYPES.ImportDeclaration) {
+      continue;
+    }
+
+    if (stmt.source.value === moduleName) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export const serverOnlyModulesImportServerOnlyRule = createRule<
+  RuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        'App-router server modules must import `"server-only"` so accidental client bundling fails at build time.',
+    },
+    schema: [optionSchema],
+    messages: {
+      missingServerOnlyImport:
+        'Add `import "{{module}}";` — server modules under `app/` should fail fast if bundled for the client.',
+    },
+  },
+  defaultOptions: [{ serverOnlyModule: DEFAULT_SERVER_ONLY_MODULE }],
+  create(context, [options]) {
+    const serverOnlyModule =
+      options.serverOnlyModule ?? DEFAULT_SERVER_ONLY_MODULE;
+
+    return {
+      Program(node) {
+        if (!isAppRouterFile(context.filename)) {
+          return;
+        }
+
+        if (hasDirective(node, "use client")) {
+          return;
+        }
+
+        if (hasServerOnlyImport(node, serverOnlyModule)) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "missingServerOnlyImport",
+          data: { module: serverOnlyModule },
+        });
+      },
+    };
+  },
+});

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

@@ -36,6 +36,24 @@ export function hasDirective(
   return false;
 }
 
+/** True if the file is a Next.js error boundary route file. */
+export function isErrorBoundaryFile(filename: string): boolean {
+  const base = filename.split(/[\\/]/).pop() ?? "";
+
+  return (
+    isAppRouterFile(filename) &&
+    /^(?:error|global-error)\.(?:tsx|ts|jsx|js)$/.test(base)
+  );
+}
+
+/** True if the file is an app-router file defaulting to a Server Component. */
+export function isServerAppFile(
+  filename: string,
+  program: TSESTree.Program
+): boolean {
+  return isAppRouterFile(filename) && !hasDirective(program, "use client");
+}
+
 /** Resolve a call's callee to a simple name: `useState` or `React.useState`
  *  → "useState". Returns null for computed or complex callees. */
 export function calleeName(callee: TSESTree.Node): string | null {