@agjs/tsforge 0.1.18 → 0.2.0

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

@@ -1,6 +1,6 @@
 import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
 
-import { walkAll } from "../utils";
+import { pushChildNodes, walkAll } from "../utils";
 
 /**
  * Helper utilities for Drizzle rules.
@@ -113,3 +113,135 @@ export function findCallExpressionsDeep(
 
   return results;
 }
+
+function getParent(node: TSESTree.Node): TSESTree.Node | undefined {
+  return node.parent;
+}
+
+/**
+ * Walk up a fluent call chain (`db.update(t).set(x).where(...)`) looking for a
+ * `.<methodName>(...)` link whose call satisfies `callMatches`.
+ */
+export function chainCallProvides(
+  startCall: TSESTree.CallExpression,
+  methodName: string,
+  callMatches: (call: TSESTree.CallExpression) => boolean
+): boolean {
+  let current: TSESTree.Node = startCall;
+  let parent = getParent(current);
+
+  while (parent !== undefined) {
+    if (
+      parent.type === AST_NODE_TYPES.MemberExpression &&
+      parent.object === current &&
+      parent.property.type === AST_NODE_TYPES.Identifier &&
+      parent.property.name === methodName
+    ) {
+      const call = getParent(parent);
+
+      if (call?.type === AST_NODE_TYPES.CallExpression && callMatches(call)) {
+        return true;
+      }
+    }
+
+    if (
+      parent.type === AST_NODE_TYPES.MemberExpression ||
+      parent.type === AST_NODE_TYPES.CallExpression
+    ) {
+      current = parent;
+      parent = getParent(current);
+
+      continue;
+    }
+
+    break;
+  }
+
+  return false;
+}
+
+export function chainContainsWhere(
+  startCall: TSESTree.CallExpression
+): boolean {
+  return chainCallProvides(startCall, "where", () => true);
+}
+
+export interface IUpdateDeleteQuery {
+  readonly kind: "update" | "delete";
+  readonly table: string;
+}
+
+export function identifyUpdateDeleteQuery(
+  node: TSESTree.CallExpression
+): IUpdateDeleteQuery | null {
+  if (node.callee.type !== AST_NODE_TYPES.MemberExpression) {
+    return null;
+  }
+
+  const property = node.callee.property;
+
+  if (property.type !== AST_NODE_TYPES.Identifier) {
+    return null;
+  }
+
+  if (property.name !== "update" && property.name !== "delete") {
+    return null;
+  }
+
+  const arg = node.arguments[0];
+
+  if (arg?.type !== AST_NODE_TYPES.Identifier) {
+    return null;
+  }
+
+  return { kind: property.name, table: arg.name };
+}
+
+export function subtreeReferencesIdentifier(
+  root: TSESTree.Node,
+  name: string
+): boolean {
+  const stack: TSESTree.Node[] = [root];
+  const visited = new WeakSet<TSESTree.Node>();
+
+  for (let node = stack.pop(); node !== undefined; node = stack.pop()) {
+    if (visited.has(node)) {
+      continue;
+    }
+
+    visited.add(node);
+
+    if (node.type === AST_NODE_TYPES.Identifier && node.name === name) {
+      return true;
+    }
+
+    if (
+      node.type === AST_NODE_TYPES.MemberExpression &&
+      node.property.type === AST_NODE_TYPES.Identifier &&
+      node.property.name === name
+    ) {
+      return true;
+    }
+
+    pushChildNodes(node, stack);
+  }
+
+  return false;
+}
+
+export function chainContainsWhereWithScope(
+  startCall: TSESTree.CallExpression,
+  scopeColumns: readonly string[]
+): boolean {
+  return chainCallProvides(startCall, "where", (call) => {
+    const firstArg = call.arguments[0];
+
+    if (firstArg === undefined) {
+      return false;
+    }
+
+    return scopeColumns.some((col) =>
+      subtreeReferencesIdentifier(firstArg, col)
+    );
+  });
+}

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

@@ -0,0 +1,38 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { errorHandlerMustSetStatusRule } from "./rules/error-handler-must-set-status";
+import { preferReturnOverReplySendRule } from "./rules/prefer-return-over-reply-send";
+import { requireFpForSharedPluginsRule } from "./rules/require-fp-for-shared-plugins";
+import { requirePluginNameRule } from "./rules/require-plugin-name";
+import { requireResponseSchemaRule } from "./rules/require-response-schema";
+import { requireRouteSchemaRule } from "./rules/require-route-schema";
+import { testInjectMustCloseAppRule } from "./rules/test-inject-must-close-app";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "error-handler-must-set-status": errorHandlerMustSetStatusRule,
+  "prefer-return-over-reply-send": preferReturnOverReplySendRule,
+  "require-fp-for-shared-plugins": requireFpForSharedPluginsRule,
+  "require-plugin-name": requirePluginNameRule,
+  "require-response-schema": requireResponseSchemaRule,
+  "require-route-schema": requireRouteSchemaRule,
+  "test-inject-must-close-app": testInjectMustCloseAppRule,
+};
+
+export const fastifyPack: IRulePack = {
+  id: "fastify",
+  description:
+    "Fastify schema-first routing, plugin encapsulation, and test hygiene",
+  rules,
+  rulesConfig: {
+    "error-handler-must-set-status": "error",
+    "prefer-return-over-reply-send": "warn",
+    "require-fp-for-shared-plugins": "error",
+    "require-plugin-name": "error",
+    "require-response-schema": "warn",
+    "require-route-schema": "error",
+    "test-inject-must-close-app": "error",
+  },
+};
+
+export default fastifyPack;

package/src/rule-packs/fastify/rules/error-handler-must-set-status.ts

@@ -0,0 +1,78 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { nodeContainsCallNamed } from "../utils/fastifyChain";
+
+export const RULE_NAME = "error-handler-must-set-status";
+
+type MessageIds = "missingReplyCode";
+
+function isSetErrorHandlerCall(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  return (
+    callee.type === AST_NODE_TYPES.MemberExpression &&
+    !callee.computed &&
+    callee.property.type === AST_NODE_TYPES.Identifier &&
+    callee.property.name === "setErrorHandler"
+  );
+}
+
+function handlerSetsStatus(
+  handler:
+    | TSESTree.ArrowFunctionExpression
+    | TSESTree.FunctionExpression
+    | TSESTree.FunctionDeclaration
+): boolean {
+  const body = handler.body;
+
+  if (body.type === AST_NODE_TYPES.BlockStatement) {
+    for (const stmt of body.body) {
+      if (nodeContainsCallNamed(stmt, "reply", "code")) {
+        return true;
+      }
+
+      if (nodeContainsCallNamed(stmt, "reply", "status")) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+export const errorHandlerMustSetStatusRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Custom Fastify setErrorHandler callbacks must call reply.code() or reply.status() — automatic status mapping is disabled when a custom handler is registered.",
+    },
+    schema: [],
+    messages: {
+      missingReplyCode:
+        "Custom `setErrorHandler` must call `reply.code(...)` (or `reply.status(...)`) before sending — Fastify does not auto-map status codes in custom error handlers.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        if (!isSetErrorHandlerCall(node)) {
+          return;
+        }
+
+        for (const arg of node.arguments) {
+          if (
+            (arg.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+              arg.type === AST_NODE_TYPES.FunctionExpression) &&
+            !handlerSetsStatus(arg)
+          ) {
+            context.report({ node: arg, messageId: "missingReplyCode" });
+          }
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/fastify/rules/prefer-return-over-reply-send.ts

@@ -0,0 +1,104 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import {
+  collectFastifyVariables,
+  getRouteHandler,
+  getRouteMethodName,
+} from "../utils/fastifyChain";
+
+export const RULE_NAME = "prefer-return-over-reply-send";
+
+type MessageIds = "preferReturn";
+
+function isReplySendReturn(node: TSESTree.ReturnStatement): boolean {
+  const arg = node.argument;
+
+  if (arg?.type !== AST_NODE_TYPES.CallExpression) {
+    return false;
+  }
+
+  const callee = arg.callee;
+
+  return (
+    callee.type === AST_NODE_TYPES.MemberExpression &&
+    !callee.computed &&
+    callee.object.type === AST_NODE_TYPES.Identifier &&
+    callee.object.name === "reply" &&
+    callee.property.type === AST_NODE_TYPES.Identifier &&
+    callee.property.name === "send"
+  );
+}
+
+export const preferReturnOverReplySendRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Inside Fastify route handlers, prefer `return data` over `return reply.send(data)` so fast-json-stringify can serialize responses.",
+    },
+    schema: [],
+    messages: {
+      preferReturn:
+        "Return the payload directly instead of `reply.send(...)` — Fastify serializes returned values when a response schema is defined.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    let fastifyVars = new Set<string>();
+
+    return {
+      Program(program: TSESTree.Program) {
+        fastifyVars = collectFastifyVariables(program);
+      },
+      ReturnStatement(node: TSESTree.ReturnStatement) {
+        if (!isReplySendReturn(node)) {
+          return;
+        }
+
+        let parent: TSESTree.Node | undefined = node.parent;
+
+        while (parent) {
+          if (
+            parent.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+            parent.type === AST_NODE_TYPES.FunctionExpression
+          ) {
+            break;
+          }
+
+          parent = parent.parent;
+        }
+
+        if (parent === undefined) {
+          return;
+        }
+
+        let routeCall: TSESTree.CallExpression | null = null;
+        let cursor: TSESTree.Node | undefined = parent.parent;
+
+        while (cursor) {
+          if (cursor.type === AST_NODE_TYPES.CallExpression) {
+            routeCall = cursor;
+            break;
+          }
+
+          cursor = cursor.parent;
+        }
+
+        if (routeCall === null) {
+          return;
+        }
+
+        const method = getRouteMethodName(routeCall, fastifyVars);
+        const handler = getRouteHandler(routeCall);
+
+        if (method === null || handler !== parent) {
+          return;
+        }
+
+        context.report({ node, messageId: "preferReturn" });
+      },
+    };
+  },
+});

package/src/rule-packs/fastify/rules/require-fp-for-shared-plugins.ts

@@ -0,0 +1,106 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { walkSome } from "../../utils";
+
+export const RULE_NAME = "require-fp-for-shared-plugins";
+
+type MessageIds = "needsFpWrapper";
+
+function pluginFunctionMutatesFastify(node: TSESTree.Node): boolean {
+  return walkSome(node, (current) => {
+    if (current.type !== AST_NODE_TYPES.CallExpression) {
+      return false;
+    }
+
+    const callee = current.callee;
+
+    return (
+      callee.type === AST_NODE_TYPES.MemberExpression &&
+      !callee.computed &&
+      callee.object.type === AST_NODE_TYPES.Identifier &&
+      callee.object.name === "fastify" &&
+      callee.property.type === AST_NODE_TYPES.Identifier &&
+      (callee.property.name === "decorate" ||
+        callee.property.name === "addHook" ||
+        callee.property.name === "register")
+    );
+  });
+}
+
+function isWrappedInFp(node: TSESTree.Node): boolean {
+  let parent = node.parent;
+
+  while (parent) {
+    if (
+      parent.type === AST_NODE_TYPES.CallExpression &&
+      parent.callee.type === AST_NODE_TYPES.Identifier &&
+      parent.callee.name === "fp"
+    ) {
+      return true;
+    }
+
+    parent = parent.parent;
+  }
+
+  return false;
+}
+
+export const requireFpForSharedPluginsRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Fastify plugins that call fastify.decorate, fastify.addHook, or fastify.register must be wrapped in fastify-plugin (fp) to break encapsulation and share state.",
+    },
+    schema: [],
+    messages: {
+      needsFpWrapper:
+        "Plugin function mutates the Fastify instance — export it wrapped in `fastify-plugin` (`fp(...)`) so decorators and hooks are visible outside the plugin context.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    function checkPluginFunction(
+      node:
+        | TSESTree.FunctionDeclaration
+        | TSESTree.FunctionExpression
+        | TSESTree.ArrowFunctionExpression
+    ): void {
+      if (!pluginFunctionMutatesFastify(node) || isWrappedInFp(node)) {
+        return;
+      }
+
+      context.report({ node, messageId: "needsFpWrapper" });
+    }
+
+    return {
+      ExportDefaultDeclaration(node: TSESTree.ExportDefaultDeclaration) {
+        const decl = node.declaration;
+
+        if (
+          decl.type === AST_NODE_TYPES.FunctionDeclaration ||
+          decl.type === AST_NODE_TYPES.FunctionExpression ||
+          decl.type === AST_NODE_TYPES.ArrowFunctionExpression
+        ) {
+          checkPluginFunction(decl);
+        }
+      },
+      AssignmentExpression(node: TSESTree.AssignmentExpression) {
+        if (
+          node.left.type === AST_NODE_TYPES.MemberExpression &&
+          !node.left.computed &&
+          node.left.object.type === AST_NODE_TYPES.Identifier &&
+          node.left.object.name === "module" &&
+          node.left.property.type === AST_NODE_TYPES.Identifier &&
+          node.left.property.name === "exports" &&
+          (node.right.type === AST_NODE_TYPES.FunctionExpression ||
+            node.right.type === AST_NODE_TYPES.ArrowFunctionExpression)
+        ) {
+          checkPluginFunction(node.right);
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/fastify/rules/require-plugin-name.ts

@@ -0,0 +1,54 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { findObjectProperty } from "../utils/fastifyChain";
+
+export const RULE_NAME = "require-plugin-name";
+
+type MessageIds = "missingPluginName";
+
+function isFpCall(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  return callee.type === AST_NODE_TYPES.Identifier && callee.name === "fp";
+}
+
+export const requirePluginNameRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "fastify-plugin (fp) wrappers must include a `name` option so Fastify can deduplicate plugin registration.",
+    },
+    schema: [],
+    messages: {
+      missingPluginName:
+        "`fp(..., { name: '...' })` must include a `name` property in the options object.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        if (!isFpCall(node)) {
+          return;
+        }
+
+        const optionsArg = node.arguments[1];
+
+        if (optionsArg?.type !== AST_NODE_TYPES.ObjectExpression) {
+          context.report({ node, messageId: "missingPluginName" });
+
+          return;
+        }
+
+        const nameProp = findObjectProperty(optionsArg, "name");
+
+        if (nameProp === null) {
+          context.report({ node, messageId: "missingPluginName" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/fastify/rules/require-response-schema.ts

@@ -0,0 +1,62 @@
+import type { TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import {
+  collectFastifyVariables,
+  findNestedProperty,
+  findRouteOptionsArg,
+  getRouteMethodName,
+} from "../utils/fastifyChain";
+
+export const RULE_NAME = "require-response-schema";
+
+type MessageIds = "missingResponseSchema";
+
+export const requireResponseSchemaRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Fastify routes should declare schema.response for compiled fast-json-stringify serialization.",
+    },
+    schema: [],
+    messages: {
+      missingResponseSchema:
+        "Route `.{{method}}(...)` should declare `schema.response` so Fastify can compile serializers at startup.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    let fastifyVars = new Set<string>();
+
+    return {
+      Program(program: TSESTree.Program) {
+        fastifyVars = collectFastifyVariables(program);
+      },
+      CallExpression(node: TSESTree.CallExpression) {
+        const method = getRouteMethodName(node, fastifyVars);
+
+        if (method === null) {
+          return;
+        }
+
+        const options = findRouteOptionsArg(node);
+
+        if (options === null) {
+          return;
+        }
+
+        const responseProp = findNestedProperty(options, "schema", "response");
+
+        if (responseProp === null) {
+          context.report({
+            node,
+            messageId: "missingResponseSchema",
+            data: { method },
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/fastify/rules/require-route-schema.ts

@@ -0,0 +1,104 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import {
+  MUTATING_METHODS,
+  collectFastifyVariables,
+  findNestedProperty,
+  findRouteOptionsArg,
+  getRouteMethodName,
+} from "../utils/fastifyChain";
+
+export const RULE_NAME = "require-route-schema";
+
+type MessageIds = "missingSchema" | "missingBodySchema";
+
+export const requireRouteSchemaRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Fastify POST/PUT/PATCH routes must declare schema.body; GET/DELETE routes must declare schema.querystring or schema.params.",
+    },
+    schema: [],
+    messages: {
+      missingSchema:
+        "Route `.{{method}}(...)` must declare a `schema` object with validation for inputs.",
+      missingBodySchema:
+        "Mutating route `.{{method}}(...)` must declare `schema.body` for request validation.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    let fastifyVars = new Set<string>();
+
+    return {
+      Program(program: TSESTree.Program) {
+        fastifyVars = collectFastifyVariables(program);
+      },
+      CallExpression(node: TSESTree.CallExpression) {
+        const method = getRouteMethodName(node, fastifyVars);
+
+        if (method === null) {
+          return;
+        }
+
+        const options = findRouteOptionsArg(node);
+
+        if (options === null) {
+          context.report({
+            node,
+            messageId: "missingSchema",
+            data: { method },
+          });
+
+          return;
+        }
+
+        const schemaProp = findNestedProperty(options, "schema");
+        const schemaObject =
+          schemaProp?.value.type === AST_NODE_TYPES.ObjectExpression
+            ? schemaProp.value
+            : null;
+
+        if (schemaObject === null) {
+          context.report({
+            node,
+            messageId: "missingSchema",
+            data: { method },
+          });
+
+          return;
+        }
+
+        if (MUTATING_METHODS.has(method)) {
+          const bodyProp = findNestedProperty(options, "schema", "body");
+
+          if (bodyProp === null) {
+            context.report({
+              node,
+              messageId: "missingBodySchema",
+              data: { method },
+            });
+          }
+        } else {
+          const queryProp = findNestedProperty(
+            options,
+            "schema",
+            "querystring"
+          );
+          const paramsProp = findNestedProperty(options, "schema", "params");
+
+          if (queryProp === null && paramsProp === null) {
+            context.report({
+              node,
+              messageId: "missingSchema",
+              data: { method },
+            });
+          }
+        }
+      },
+    };
+  },
+});