@agjs/tsforge 0.1.0

package/src/rule-packs/elysia/rules/prefer-direct-return.ts

@@ -0,0 +1,176 @@
+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 {
+  collectElysiaVariables,
+  findEnclosingRouteHandler,
+  findObjectProperty,
+  isElysiaRouteCall,
+} from "../utils/elysiaChain";
+
+export const RULE_NAME = "prefer-direct-return";
+
+export interface PreferDirectReturnOptions {
+  readonly allowWithHeaders?: boolean;
+}
+
+type RuleOptions = [PreferDirectReturnOptions];
+type MessageIds = "preferDirectReturn";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    allowWithHeaders: { type: "boolean" },
+  },
+};
+
+export const preferDirectReturnRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Inside Elysia route handlers, return values directly instead of wrapping them in `new Response(...)` or `Response.json(...)` — Elysia handles serialization and content-type automatically.",
+    },
+    schema: [optionSchema],
+    messages: {
+      preferDirectReturn:
+        "Return the value directly — Elysia will serialize it and set the correct content-type. Wrapping in `new Response(...)` is only necessary for streams or custom headers.",
+    },
+  },
+  defaultOptions: [{ allowWithHeaders: true }],
+  create(context, [options]) {
+    const allowWithHeaders = options.allowWithHeaders !== false;
+    let elysiaVars = new Set<string>();
+
+    return {
+      Program(program) {
+        elysiaVars = collectElysiaVariables(program);
+      },
+      ReturnStatement(node) {
+        if (!node.argument) {
+          return;
+        }
+
+        if (!findEnclosingRouteHandler(node, elysiaVars)) {
+          return;
+        }
+
+        checkExpression(node.argument);
+      },
+      ArrowFunctionExpression(node) {
+        if (node.body.type === AST_NODE_TYPES.BlockStatement) {
+          return;
+        }
+
+        if (!isRouteHandlerArg(node, elysiaVars)) {
+          return;
+        }
+
+        checkExpression(node.body);
+      },
+    };
+
+    function checkExpression(arg: TSESTree.Expression): void {
+      if (arg.type === AST_NODE_TYPES.NewExpression) {
+        if (
+          arg.callee.type !== AST_NODE_TYPES.Identifier ||
+          arg.callee.name !== "Response"
+        ) {
+          return;
+        }
+
+        const bodyArg = arg.arguments[0];
+
+        if (!bodyArg || !isSimpleBody(bodyArg)) {
+          return;
+        }
+
+        const optionsArg = arg.arguments[1];
+
+        if (
+          allowWithHeaders &&
+          optionsArg &&
+          hasHeadersOrContentType(optionsArg)
+        ) {
+          return;
+        }
+
+        context.report({ node: arg, messageId: "preferDirectReturn" });
+
+        return;
+      }
+
+      if (
+        arg.type === AST_NODE_TYPES.CallExpression &&
+        arg.callee.type === AST_NODE_TYPES.MemberExpression &&
+        arg.callee.object.type === AST_NODE_TYPES.Identifier &&
+        arg.callee.object.name === "Response" &&
+        arg.callee.property.type === AST_NODE_TYPES.Identifier &&
+        arg.callee.property.name === "json"
+      ) {
+        context.report({ node: arg, messageId: "preferDirectReturn" });
+      }
+    }
+  },
+});
+
+function isRouteHandlerArg(
+  fn: TSESTree.ArrowFunctionExpression | TSESTree.FunctionExpression,
+  elysiaVars: Set<string>
+): boolean {
+  const parent = fn.parent;
+
+  if (parent?.type !== AST_NODE_TYPES.CallExpression) {
+    return false;
+  }
+
+  if (!parent.arguments.includes(fn)) {
+    return false;
+  }
+
+  return isElysiaRouteCall(parent, elysiaVars);
+}
+
+function isSimpleBody(node: TSESTree.Node): boolean {
+  if (node.type === AST_NODE_TYPES.SpreadElement) {
+    return false;
+  }
+
+  if (
+    node.type === AST_NODE_TYPES.Literal ||
+    node.type === AST_NODE_TYPES.TemplateLiteral
+  ) {
+    return true;
+  }
+
+  if (
+    node.type === AST_NODE_TYPES.CallExpression &&
+    node.callee.type === AST_NODE_TYPES.MemberExpression &&
+    node.callee.object.type === AST_NODE_TYPES.Identifier &&
+    node.callee.object.name === "JSON" &&
+    node.callee.property.type === AST_NODE_TYPES.Identifier &&
+    node.callee.property.name === "stringify"
+  ) {
+    return true;
+  }
+
+  if (
+    node.type === AST_NODE_TYPES.ObjectExpression ||
+    node.type === AST_NODE_TYPES.ArrayExpression
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+function hasHeadersOrContentType(opts: TSESTree.Node): boolean {
+  if (opts.type !== AST_NODE_TYPES.ObjectExpression) {
+    return false;
+  }
+
+  return findObjectProperty(opts, "headers") !== null;
+}

package/src/rule-packs/elysia/rules/prefer-static-services.ts

@@ -0,0 +1,159 @@
+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 {
+  collectElysiaVariables,
+  findEnclosingRouteHandler,
+} from "../utils/elysiaChain";
+
+export const RULE_NAME = "prefer-static-services";
+
+export interface PreferStaticServicesOptions {
+  readonly classNamePattern?: string;
+}
+
+type RuleOptions = [PreferStaticServicesOptions];
+type MessageIds = "preferStaticService";
+
+const DEFAULT_PATTERN = "(Service|Controller|Manager|Repository)$";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    classNamePattern: { type: "string", minLength: 1 },
+  },
+};
+
+export const preferStaticServicesRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Discourage `new Service()` inside Elysia route handlers when the class is stateless — prefer static methods or a singleton.",
+    },
+    schema: [optionSchema],
+    messages: {
+      preferStaticService:
+        "Avoid `new {{name}}()` inside an Elysia route handler — '{{name}}' has no instance state, so allocating per request is wasteful. Use static methods or a module-level singleton.",
+    },
+  },
+  defaultOptions: [{ classNamePattern: DEFAULT_PATTERN }],
+  create(context, [options]) {
+    const pattern = compilePattern(options.classNamePattern ?? DEFAULT_PATTERN);
+
+    if (!pattern) {
+      return {};
+    }
+
+    let elysiaVars = new Set<string>();
+    const classes = new Map<string, TSESTree.ClassDeclaration>();
+    const newExpressions: TSESTree.NewExpression[] = [];
+
+    return {
+      Program(program) {
+        elysiaVars = collectElysiaVariables(program);
+      },
+      ClassDeclaration(node) {
+        if (node.id) {
+          classes.set(node.id.name, node);
+        }
+      },
+      NewExpression(node) {
+        if (node.callee.type !== AST_NODE_TYPES.Identifier) {
+          return;
+        }
+
+        if (!pattern.test(node.callee.name)) {
+          return;
+        }
+
+        newExpressions.push(node);
+      },
+      "Program:exit"() {
+        for (const newExpr of newExpressions) {
+          if (newExpr.callee.type !== AST_NODE_TYPES.Identifier) {
+            continue;
+          }
+
+          const className = newExpr.callee.name;
+          const classDecl = classes.get(className);
+
+          if (!classDecl || !isStateless(classDecl)) {
+            continue;
+          }
+
+          if (!findEnclosingRouteHandler(newExpr, elysiaVars)) {
+            continue;
+          }
+
+          context.report({
+            node: newExpr,
+            messageId: "preferStaticService",
+            data: { name: className },
+          });
+        }
+      },
+    };
+  },
+});
+
+function isStateless(node: TSESTree.ClassDeclaration): boolean {
+  return node.body.body.every(memberIsStateless);
+}
+
+function memberIsStateless(member: TSESTree.ClassElement): boolean {
+  if (member.type === AST_NODE_TYPES.PropertyDefinition) {
+    return member.static;
+  }
+
+  if (member.type !== AST_NODE_TYPES.MethodDefinition) {
+    return true;
+  }
+
+  if (member.kind === "constructor" && constructorHasState(member.value)) {
+    return false;
+  }
+
+  return (
+    member.static ||
+    member.value.type === AST_NODE_TYPES.TSEmptyBodyFunctionExpression ||
+    !assignsToThis(member.value)
+  );
+}
+
+function constructorHasState(
+  ctor: TSESTree.FunctionExpression | TSESTree.TSEmptyBodyFunctionExpression
+): boolean {
+  if (
+    ctor.body?.type === AST_NODE_TYPES.BlockStatement &&
+    ctor.body.body.length > 0
+  ) {
+    return true;
+  }
+
+  return ctor.params.some(
+    (param) => param.type === AST_NODE_TYPES.TSParameterProperty
+  );
+}
+
+function assignsToThis(fn: TSESTree.FunctionExpression): boolean {
+  return walkSome(
+    fn.body,
+    (node) =>
+      node.type === AST_NODE_TYPES.AssignmentExpression &&
+      node.left.type === AST_NODE_TYPES.MemberExpression &&
+      node.left.object.type === AST_NODE_TYPES.ThisExpression
+  );
+}
+
+function compilePattern(source: string): RegExp | null {
+  try {
+    return new RegExp(source);
+  } catch {
+    return null;
+  }
+}

package/src/rule-packs/elysia/rules/prefer-throw-status.ts

@@ -0,0 +1,151 @@
+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 {
+  collectElysiaVariables,
+  findEnclosingRouteHandler,
+} from "../utils/elysiaChain";
+
+export const RULE_NAME = "prefer-throw-status";
+
+export interface PreferThrowStatusOptions {
+  readonly maxStatements?: number;
+}
+
+type RuleOptions = [PreferThrowStatusOptions];
+type MessageIds = "preferThrowStatus";
+
+const DEFAULT_MAX_STATEMENTS = 3;
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    maxStatements: { type: "integer", minimum: 1 },
+  },
+};
+
+export const preferThrowStatusRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Inside Elysia route handlers, prefer `throw status(...)` over try/catch blocks that build their own Response — local catches bypass Elysia's typed onError pipeline.",
+    },
+    schema: [optionSchema],
+    messages: {
+      preferThrowStatus:
+        "Avoid wrapping route logic in a try/catch that builds its own response. Use `throw status(code, message)` (or your project's typed exception) so Elysia's onError pipeline can render a typed response.",
+    },
+  },
+  defaultOptions: [{ maxStatements: DEFAULT_MAX_STATEMENTS }],
+  create(context, [options]) {
+    const maxStatements = options.maxStatements ?? DEFAULT_MAX_STATEMENTS;
+    let elysiaVars = new Set<string>();
+
+    return {
+      Program(program) {
+        elysiaVars = collectElysiaVariables(program);
+      },
+      TryStatement(node) {
+        if (!findEnclosingRouteHandler(node, elysiaVars)) {
+          return;
+        }
+
+        const tooLargeTry = node.block.body.length > maxStatements;
+        const catchProducesResponse = node.handler
+          ? catchBuildsResponse(node.handler.body)
+          : false;
+
+        if (!tooLargeTry && !catchProducesResponse) {
+          return;
+        }
+
+        context.report({ node, messageId: "preferThrowStatus" });
+      },
+    };
+  },
+});
+
+function catchBuildsResponse(block: TSESTree.BlockStatement): boolean {
+  for (const stmt of block.body) {
+    if (statementBuildsResponse(stmt)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function statementBuildsResponse(stmt: TSESTree.Statement): boolean {
+  if (stmt.type === AST_NODE_TYPES.ReturnStatement && stmt.argument) {
+    return isResponseLikeExpression(stmt.argument);
+  }
+
+  if (stmt.type === AST_NODE_TYPES.ExpressionStatement) {
+    const expr = stmt.expression;
+
+    if (
+      expr.type === AST_NODE_TYPES.AssignmentExpression &&
+      expr.left.type === AST_NODE_TYPES.MemberExpression &&
+      expr.left.object.type === AST_NODE_TYPES.Identifier &&
+      expr.left.object.name === "set" &&
+      expr.left.property.type === AST_NODE_TYPES.Identifier &&
+      expr.left.property.name === "status"
+    ) {
+      return true;
+    }
+  }
+
+  if (stmt.type === AST_NODE_TYPES.IfStatement) {
+    if (statementBuildsResponse(stmt.consequent)) {
+      return true;
+    }
+
+    if (stmt.alternate && statementBuildsResponse(stmt.alternate)) {
+      return true;
+    }
+  }
+
+  if (stmt.type === AST_NODE_TYPES.BlockStatement) {
+    for (const inner of stmt.body) {
+      if (statementBuildsResponse(inner)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+function isResponseLikeExpression(node: TSESTree.Expression): boolean {
+  if (node.type === AST_NODE_TYPES.NewExpression) {
+    return (
+      node.callee.type === AST_NODE_TYPES.Identifier &&
+      node.callee.name === "Response"
+    );
+  }
+
+  if (
+    node.type === AST_NODE_TYPES.CallExpression &&
+    node.callee.type === AST_NODE_TYPES.MemberExpression &&
+    node.callee.object.type === AST_NODE_TYPES.Identifier &&
+    node.callee.object.name === "Response" &&
+    node.callee.property.type === AST_NODE_TYPES.Identifier &&
+    node.callee.property.name === "json"
+  ) {
+    return true;
+  }
+
+  if (
+    node.type === AST_NODE_TYPES.Literal ||
+    node.type === AST_NODE_TYPES.ObjectExpression ||
+    node.type === AST_NODE_TYPES.ArrayExpression
+  ) {
+    return true;
+  }
+
+  return false;
+}

package/src/rule-packs/elysia/rules/require-hooks-before-routes.ts

@@ -0,0 +1,209 @@
+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 {
+  HOOK_METHODS,
+  ROUTE_METHODS,
+  collectElysiaVariables,
+  getChainRoot,
+  getMemberMethodName,
+  isElysiaRouted,
+  isNewElysiaExpression,
+} from "../utils/elysiaChain";
+
+export const RULE_NAME = "require-hooks-before-routes";
+
+export interface RequireHooksBeforeRoutesOptions {
+  readonly hooks?: readonly string[];
+  readonly routes?: readonly string[];
+}
+
+type RuleOptions = [RequireHooksBeforeRoutesOptions];
+type MessageIds = "hookAfterRoute";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    hooks: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    },
+    routes: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    },
+  },
+};
+
+export const requireHooksBeforeRoutesRule = createRule<RuleOptions, MessageIds>(
+  {
+    name: RULE_NAME,
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "Elysia hooks (onError, onBeforeHandle, etc.) must register before any route methods on the same instance — top-down waterfall semantics mean a hook registered after a route does not apply to it.",
+      },
+      schema: [optionSchema],
+      messages: {
+        hookAfterRoute:
+          "Hook `.{{hook}}(...)` registered after route `.{{route}}(...)` — the hook will NOT apply to that earlier route. Move global hooks before any route on the same instance.",
+      },
+    },
+    defaultOptions: [
+      {
+        hooks: [...HOOK_METHODS],
+        routes: [...ROUTE_METHODS],
+      },
+    ],
+    create(context, [options]) {
+      const hooks = new Set(options.hooks ?? HOOK_METHODS);
+      const routes = new Set(options.routes ?? ROUTE_METHODS);
+
+      let elysiaVars = new Set<string>();
+      const flatBuilderCalls = new Map<string, OrderedCall[]>();
+      const reportedNodes = new WeakSet();
+
+      function reportFlatBuilders(): void {
+        for (const calls of flatBuilderCalls.values()) {
+          const firstRouteIndex = calls.findIndex((c) => routes.has(c.method));
+
+          if (firstRouteIndex === -1) {
+            continue;
+          }
+
+          const firstRoute = calls[firstRouteIndex];
+
+          for (let i = firstRouteIndex + 1; i < calls.length; i++) {
+            const call = calls[i];
+
+            if (!call) {
+              continue;
+            }
+
+            if (
+              hooks.has(call.method) &&
+              firstRoute &&
+              !reportedNodes.has(call.node)
+            ) {
+              reportedNodes.add(call.node);
+              context.report({
+                node: call.node,
+                messageId: "hookAfterRoute",
+                data: { hook: call.method, route: firstRoute.method },
+              });
+            }
+          }
+        }
+      }
+
+      function reportChain(rootCall: TSESTree.CallExpression): void {
+        const ordered = collectChainCalls(rootCall);
+
+        const firstRouteIndex = ordered.findIndex((c) => routes.has(c.method));
+
+        if (firstRouteIndex === -1) {
+          return;
+        }
+
+        const firstRoute = ordered[firstRouteIndex];
+
+        for (let i = firstRouteIndex + 1; i < ordered.length; i++) {
+          const call = ordered[i];
+
+          if (!call) {
+            continue;
+          }
+
+          if (
+            hooks.has(call.method) &&
+            firstRoute &&
+            !reportedNodes.has(call.node)
+          ) {
+            reportedNodes.add(call.node);
+            context.report({
+              node: call.node,
+              messageId: "hookAfterRoute",
+              data: { hook: call.method, route: firstRoute.method },
+            });
+          }
+        }
+      }
+
+      return {
+        Program(program) {
+          elysiaVars = collectElysiaVariables(program);
+        },
+        CallExpression(node) {
+          if (node.callee.type !== AST_NODE_TYPES.MemberExpression) {
+            return;
+          }
+
+          const method = getMemberMethodName(node);
+
+          if (!method) {
+            return;
+          }
+
+          if (!isElysiaRouted(node, elysiaVars)) {
+            return;
+          }
+
+          const root = getChainRoot(node);
+
+          if (isNewElysiaExpression(root)) {
+            if (
+              node.parent?.type === AST_NODE_TYPES.MemberExpression &&
+              node.parent.parent?.type === AST_NODE_TYPES.CallExpression &&
+              isElysiaRouted(node.parent.parent, elysiaVars)
+            ) {
+              return;
+            }
+
+            reportChain(node);
+
+            return;
+          }
+
+          if (
+            root.type === AST_NODE_TYPES.Identifier &&
+            elysiaVars.has(root.name)
+          ) {
+            const list = flatBuilderCalls.get(root.name) ?? [];
+
+            list.push({ method, node });
+            flatBuilderCalls.set(root.name, list);
+          }
+        },
+        "Program:exit"() {
+          reportFlatBuilders();
+        },
+      };
+    },
+  }
+);
+
+interface OrderedCall {
+  readonly method: string;
+  readonly node: TSESTree.CallExpression;
+}
+
+function collectChainCalls(outermost: TSESTree.CallExpression): OrderedCall[] {
+  const calls: OrderedCall[] = [];
+  let current: TSESTree.Expression = outermost;
+
+  while (
+    current.type === AST_NODE_TYPES.CallExpression &&
+    current.callee.type === AST_NODE_TYPES.MemberExpression &&
+    current.callee.property.type === AST_NODE_TYPES.Identifier
+  ) {
+    calls.push({ method: current.callee.property.name, node: current });
+    current = current.callee.object;
+  }
+
+  return calls.reverse();
+}