@agjs/tsforge 0.1.0

package/src/rule-packs/elysia/rules/no-decorate-state-collision.ts

@@ -0,0 +1,276 @@
+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,
+  getChainRoot,
+  getMemberMethodName,
+  isNewElysiaExpression,
+} from "../utils/elysiaChain";
+
+export const RULE_NAME = "no-decorate-state-collision";
+
+export interface NoDecorateStateCollisionOptions {
+  readonly methods?: readonly string[];
+}
+
+type RuleOptions = [NoDecorateStateCollisionOptions];
+type MessageIds = "decorateKeyCollision";
+
+const DEFAULT_METHODS = ["decorate", "state", "derive", "resolve"] as const;
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    methods: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+  },
+};
+
+export const noDecorateStateCollisionRule = createRule<RuleOptions, MessageIds>(
+  {
+    name: RULE_NAME,
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "Disallow duplicate keys across `.decorate()` / `.state()` / `.derive()` / `.resolve()` calls on a single Elysia instance — duplicates silently overwrite and break plugin composition.",
+      },
+      schema: [optionSchema],
+      messages: {
+        decorateKeyCollision:
+          "Key '{{key}}' is registered more than once on this Elysia instance (previously by `.{{previous}}(...)`). Duplicate decorate/state keys silently overwrite each other and break plugin composition.",
+      },
+    },
+    defaultOptions: [{ methods: [...DEFAULT_METHODS] }],
+    create(context, [options]) {
+      const methods = new Set(options.methods ?? DEFAULT_METHODS);
+
+      let elysiaVars = new Set<string>();
+
+      interface Registration {
+        readonly key: string;
+        readonly method: string;
+        readonly node: TSESTree.Node;
+        readonly line: number;
+      }
+      const registrationsByOwner = new Map<string, Registration[]>();
+      const processedChains = new WeakSet();
+
+      function ownerKey(rootCall: TSESTree.CallExpression): string {
+        const root = getChainRoot(rootCall);
+
+        if (isNewElysiaExpression(root)) {
+          return `chain@${root.range[0]}`;
+        }
+
+        if (root.type === AST_NODE_TYPES.Identifier) {
+          return `var:${root.name}`;
+        }
+
+        return `chain@${rootCall.range[0]}`;
+      }
+
+      function checkChain(rootCall: TSESTree.CallExpression): void {
+        if (processedChains.has(rootCall)) {
+          return;
+        }
+
+        processedChains.add(rootCall);
+
+        const ordered = collectChainCalls(rootCall);
+        const owner = ownerKey(rootCall);
+        const existing = registrationsByOwner.get(owner) ?? [];
+
+        for (const call of ordered) {
+          if (!methods.has(call.method)) {
+            continue;
+          }
+
+          for (const reg of extractRegistrations(call.node, call.method)) {
+            const prior = existing.find((e) => e.key === reg.key);
+
+            if (prior) {
+              context.report({
+                node: reg.node,
+                messageId: "decorateKeyCollision",
+                data: {
+                  key: reg.key,
+                  previous: prior.method,
+                },
+              });
+            }
+
+            existing.push(reg);
+          }
+        }
+
+        registrationsByOwner.set(owner, existing);
+      }
+
+      return {
+        Program(program) {
+          elysiaVars = collectElysiaVariables(program);
+        },
+        CallExpression(node) {
+          if (node.callee.type !== AST_NODE_TYPES.MemberExpression) {
+            return;
+          }
+
+          const root = getChainRoot(node);
+
+          const isElysiaChain =
+            isNewElysiaExpression(root) ||
+            (root.type === AST_NODE_TYPES.Identifier &&
+              elysiaVars.has(root.name));
+
+          if (!isElysiaChain) {
+            return;
+          }
+
+          if (
+            node.parent?.type === AST_NODE_TYPES.MemberExpression &&
+            node.parent.parent?.type === AST_NODE_TYPES.CallExpression
+          ) {
+            return;
+          }
+
+          checkChain(node);
+        },
+      };
+    },
+  }
+);
+
+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
+  ) {
+    const method = getMemberMethodName(current);
+
+    if (method) {
+      calls.push({ method, node: current });
+    }
+
+    current = current.callee.object;
+  }
+
+  return calls.reverse();
+}
+
+interface RegistrationCandidate {
+  readonly key: string;
+  readonly method: string;
+  readonly node: TSESTree.Node;
+  readonly line: number;
+}
+
+function extractRegistrations(
+  call: TSESTree.CallExpression,
+  method: string
+): RegistrationCandidate[] {
+  const arg = call.arguments[0];
+
+  if (!arg) {
+    return [];
+  }
+
+  if (arg.type === AST_NODE_TYPES.Literal && typeof arg.value === "string") {
+    return [
+      {
+        key: arg.value,
+        method,
+        node: arg,
+        line: arg.loc.start.line,
+      },
+    ];
+  }
+
+  if (arg.type === AST_NODE_TYPES.ObjectExpression) {
+    return objectExpressionKeys(arg, method);
+  }
+
+  if (
+    arg.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+    arg.type === AST_NODE_TYPES.FunctionExpression
+  ) {
+    const returned = getReturnedObjectExpression(arg);
+
+    if (returned) {
+      return objectExpressionKeys(returned, method);
+    }
+  }
+
+  return [];
+}
+
+function objectExpressionKeys(
+  obj: TSESTree.ObjectExpression,
+  method: string
+): RegistrationCandidate[] {
+  const out: RegistrationCandidate[] = [];
+
+  for (const property of obj.properties) {
+    if (property.type !== AST_NODE_TYPES.Property) {
+      continue;
+    }
+
+    let keyName: string | null = null;
+
+    if (property.key.type === AST_NODE_TYPES.Identifier && !property.computed) {
+      keyName = property.key.name;
+    } else if (
+      property.key.type === AST_NODE_TYPES.Literal &&
+      typeof property.key.value === "string"
+    ) {
+      keyName = property.key.value;
+    }
+
+    if (keyName !== null) {
+      out.push({
+        key: keyName,
+        method,
+        node: property,
+        line: property.loc.start.line,
+      });
+    }
+  }
+
+  return out;
+}
+
+function getReturnedObjectExpression(
+  fn: TSESTree.ArrowFunctionExpression | TSESTree.FunctionExpression
+): TSESTree.ObjectExpression | null {
+  if (fn.body.type === AST_NODE_TYPES.ObjectExpression) {
+    return fn.body;
+  }
+
+  if (fn.body.type === AST_NODE_TYPES.BlockStatement) {
+    for (const stmt of fn.body.body) {
+      if (
+        stmt.type === AST_NODE_TYPES.ReturnStatement &&
+        stmt.argument?.type === AST_NODE_TYPES.ObjectExpression
+      ) {
+        return stmt.argument;
+      }
+    }
+  }
+
+  return null;
+}

package/src/rule-packs/elysia/rules/no-separate-model-interfaces.ts

@@ -0,0 +1,144 @@
+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 { getCalleeName } from "../utils/elysiaChain";
+
+export const RULE_NAME = "no-separate-model-interfaces";
+
+export interface NoSeparateModelInterfacesOptions {
+  readonly schemaSuffixes?: readonly string[];
+  readonly schemaFactoryNames?: readonly string[];
+}
+
+type RuleOptions = [NoSeparateModelInterfacesOptions];
+type MessageIds = "noSeparateModelInterface";
+
+const DEFAULT_SCHEMA_SUFFIXES = [
+  "Schema",
+  "Model",
+  "Dto",
+  "DTO",
+  "Request",
+  "Response",
+] as const;
+
+const DEFAULT_SCHEMA_FACTORY_NAMES = [
+  "t.Object",
+  "Elysia.t.Object",
+  "Type.Object",
+  "z.object",
+  "v.object",
+] as const;
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    schemaSuffixes: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    },
+    schemaFactoryNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    },
+  },
+};
+
+export const noSeparateModelInterfacesRule = createRule<
+  RuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow TypeScript interfaces that duplicate the shape of a runtime schema with a matching name. Use `typeof Schema.static` (or your project's equivalent) instead.",
+    },
+    schema: [optionSchema],
+    messages: {
+      noSeparateModelInterface:
+        "Interface '{{interface}}' duplicates schema '{{schema}}'. Replace with `type {{interface}} = typeof {{schema}}.static` (or equivalent) to keep the type and the runtime validator from drifting.",
+    },
+  },
+  defaultOptions: [
+    {
+      schemaSuffixes: [...DEFAULT_SCHEMA_SUFFIXES],
+      schemaFactoryNames: [...DEFAULT_SCHEMA_FACTORY_NAMES],
+    },
+  ],
+  create(context, [options]) {
+    const suffixes = options.schemaSuffixes ?? DEFAULT_SCHEMA_SUFFIXES;
+    const factoryNames = new Set(
+      options.schemaFactoryNames ?? DEFAULT_SCHEMA_FACTORY_NAMES
+    );
+
+    const schemaByBase = new Map<string, string>();
+    const interfaces: TSESTree.TSInterfaceDeclaration[] = [];
+
+    return {
+      VariableDeclarator(node) {
+        if (node.id.type !== AST_NODE_TYPES.Identifier) {
+          return;
+        }
+
+        if (node.init?.type !== AST_NODE_TYPES.CallExpression) {
+          return;
+        }
+
+        const calleeName = getCalleeName(node.init);
+
+        if (!calleeName || !factoryNames.has(calleeName)) {
+          return;
+        }
+
+        const base = stripSuffix(node.id.name, suffixes);
+
+        if (base.length > 0) {
+          schemaByBase.set(base, node.id.name);
+        }
+      },
+      TSInterfaceDeclaration(node) {
+        interfaces.push(node);
+      },
+      "Program:exit"() {
+        for (const iface of interfaces) {
+          const base = stripSuffix(iface.id.name, suffixes);
+
+          if (base.length === 0) {
+            continue;
+          }
+
+          const schemaName = schemaByBase.get(base);
+
+          if (!schemaName) {
+            continue;
+          }
+
+          context.report({
+            node: iface.id,
+            messageId: "noSeparateModelInterface",
+            data: {
+              interface: iface.id.name,
+              schema: schemaName,
+            },
+          });
+        }
+      },
+    };
+  },
+});
+
+function stripSuffix(name: string, suffixes: readonly string[]): string {
+  for (const suffix of suffixes) {
+    if (name.endsWith(suffix) && name.length > suffix.length) {
+      return name.slice(0, -suffix.length);
+    }
+  }
+
+  return name;
+}

package/src/rule-packs/elysia/rules/prefer-destructured-context.ts

@@ -0,0 +1,155 @@
+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 { pushChildNodes } from "../../utils";
+import {
+  collectElysiaVariables,
+  getRouteHandlerFunction,
+  isElysiaRouteCall,
+} from "../utils/elysiaChain";
+
+export const RULE_NAME = "prefer-destructured-context";
+
+export interface PreferDestructuredContextOptions {
+  readonly allowNames?: readonly string[];
+}
+
+type RuleOptions = [PreferDestructuredContextOptions];
+type MessageIds = "preferDestructuredContext";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    allowNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    },
+  },
+};
+
+export const preferDestructuredContextRule = createRule<
+  RuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Prefer destructured context (`{ body, set, ... }`) over passing the entire dynamic Elysia context object into controllers/services.",
+    },
+    schema: [optionSchema],
+    messages: {
+      preferDestructuredContext:
+        "Do not pass the full Elysia context (`{{name}}`) into another function. Destructure only the properties you need at the route boundary.",
+    },
+  },
+  defaultOptions: [{ allowNames: [] }],
+  create(context, [options]) {
+    const allowNames = new Set(options.allowNames ?? []);
+    let elysiaVars = new Set<string>();
+
+    return {
+      Program(program) {
+        elysiaVars = collectElysiaVariables(program);
+      },
+      CallExpression(node) {
+        if (!isElysiaRouteCall(node, elysiaVars)) {
+          return;
+        }
+
+        const handler = getRouteHandlerFunction(node);
+
+        if (handler?.params.length !== 1) {
+          return;
+        }
+
+        const param = handler.params[0];
+
+        if (param?.type !== AST_NODE_TYPES.Identifier) {
+          return;
+        }
+
+        if (allowNames.has(param.name)) {
+          return;
+        }
+
+        const ctxName = param.name;
+
+        for (const violation of collectContextPassThrough(
+          handler.body,
+          ctxName
+        )) {
+          context.report({
+            node: violation,
+            messageId: "preferDestructuredContext",
+            data: { name: ctxName },
+          });
+        }
+      },
+    };
+  },
+});
+
+function isFunctionNode(node: TSESTree.Node): boolean {
+  return (
+    node.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+    node.type === AST_NODE_TYPES.FunctionExpression ||
+    node.type === AST_NODE_TYPES.FunctionDeclaration
+  );
+}
+
+/** True when a call/new expression forwards `ctxName` (directly or spread). */
+function callPassesContext(
+  call: TSESTree.CallExpression | TSESTree.NewExpression,
+  ctxName: string
+): boolean {
+  return call.arguments.some((arg) => {
+    if (arg.type === AST_NODE_TYPES.Identifier) {
+      return arg.name === ctxName;
+    }
+
+    return (
+      arg.type === AST_NODE_TYPES.SpreadElement &&
+      arg.argument.type === AST_NODE_TYPES.Identifier &&
+      arg.argument.name === ctxName
+    );
+  });
+}
+
+/** Calls inside the handler body (excluding nested functions) that forward the context. */
+function collectContextPassThrough(
+  root: TSESTree.Node,
+  ctxName: string
+): TSESTree.Node[] {
+  const violations: TSESTree.Node[] = [];
+  const stack: TSESTree.Node[] = [root];
+  const visited = new WeakSet();
+
+  for (let node = stack.pop(); node !== undefined; node = stack.pop()) {
+    if (visited.has(node)) {
+      continue;
+    }
+
+    visited.add(node);
+
+    if (isFunctionNode(node) && node !== root) {
+      continue;
+    }
+
+    if (
+      (node.type === AST_NODE_TYPES.CallExpression ||
+        node.type === AST_NODE_TYPES.NewExpression) &&
+      callPassesContext(node, ctxName)
+    ) {
+      violations.push(node);
+    }
+
+    pushChildNodes(node, stack);
+  }
+
+  return violations;
+}