@agjs/tsforge 0.1.0

package/src/rule-packs/bullmq/rules/queue-options-must-set-removeoncomplete.ts

@@ -0,0 +1,130 @@
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+import type { TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import {
+  analyzeBullmqImports,
+  collectQueueDefinitions,
+  findObjectProperty,
+  getCallReceiverKey,
+  getOptionsObjectArg,
+  isQueueAddCall,
+  isQueueLikeReceiverName,
+  type BullmqImports,
+  type QueueDefinition,
+} from "../utils";
+
+export const RULE_NAME = "queue-options-must-set-removeoncomplete";
+
+type RuleOptions = [];
+type MessageIds = "missingRemoveOnComplete";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {},
+};
+
+export const queueOptionsMustSetRemoveOnCompleteRule = createRule<
+  RuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Every `<queue>.add(...)` must configure `removeOnComplete` (per-call or via `defaultJobOptions`) so completed jobs don't accumulate in Redis.",
+    },
+    schema: [optionSchema],
+    messages: {
+      missingRemoveOnComplete:
+        "Job has no `removeOnComplete` configuration — completed jobs accumulate in Redis indefinitely. Set it per-call or via `defaultJobOptions` on the Queue.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    let imports: BullmqImports = {
+      hasBullmqImport: false,
+      workerLocalNames: new Set(),
+      queueLocalNames: new Set(),
+      queueEventsLocalNames: new Set(),
+    };
+    let knownQueues = new Map<string, QueueDefinition>();
+
+    return {
+      Program(program) {
+        imports = analyzeBullmqImports(program);
+        knownQueues = collectQueueDefinitions(program, imports);
+      },
+      CallExpression(node) {
+        if (!isQueueAddCall(node)) {
+          return;
+        }
+
+        if (!receiverIsQueueLike(node, knownQueues)) {
+          return;
+        }
+
+        if (callHasOption(node, "removeOnComplete")) {
+          return;
+        }
+
+        if (queueDefaultsHaveOption(node, knownQueues, "removeOnComplete")) {
+          return;
+        }
+
+        context.report({ node, messageId: "missingRemoveOnComplete" });
+      },
+    };
+  },
+});
+
+function receiverIsQueueLike(
+  call: TSESTree.CallExpression,
+  knownQueues: ReadonlyMap<string, QueueDefinition>
+): boolean {
+  const key = getCallReceiverKey(call);
+
+  if (!key) {
+    return false;
+  }
+
+  if (knownQueues.has(key)) {
+    return true;
+  }
+
+  const last = key.includes(".") ? (key.split(".").pop() ?? key) : key;
+
+  return isQueueLikeReceiverName(last);
+}
+
+function callHasOption(call: TSESTree.CallExpression, name: string): boolean {
+  const opts = getOptionsObjectArg(call, 2);
+
+  if (!opts) {
+    return false;
+  }
+
+  return findObjectProperty(opts, name) !== null;
+}
+
+function queueDefaultsHaveOption(
+  call: TSESTree.CallExpression,
+  knownQueues: ReadonlyMap<string, QueueDefinition>,
+  name: string
+): boolean {
+  const key = getCallReceiverKey(call);
+
+  if (!key) {
+    return false;
+  }
+
+  const def = knownQueues.get(key);
+
+  if (!def?.defaultJobOptions) {
+    return false;
+  }
+
+  return findObjectProperty(def.defaultJobOptions, name) !== null;
+}

package/src/rule-packs/bullmq/rules/queue-options-must-set-removeonfail.ts

@@ -0,0 +1,130 @@
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+import type { TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import {
+  analyzeBullmqImports,
+  collectQueueDefinitions,
+  findObjectProperty,
+  getCallReceiverKey,
+  getOptionsObjectArg,
+  isQueueAddCall,
+  isQueueLikeReceiverName,
+  type BullmqImports,
+  type QueueDefinition,
+} from "../utils";
+
+export const RULE_NAME = "queue-options-must-set-removeonfail";
+
+type RuleOptions = [];
+type MessageIds = "missingRemoveOnFail";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {},
+};
+
+export const queueOptionsMustSetRemoveOnFailRule = createRule<
+  RuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Every `<queue>.add(...)` must configure `removeOnFail` (per-call or via `defaultJobOptions`) so failed jobs don't accumulate in Redis.",
+    },
+    schema: [optionSchema],
+    messages: {
+      missingRemoveOnFail:
+        "Job has no `removeOnFail` configuration — failed jobs accumulate in Redis indefinitely. Set it per-call or via `defaultJobOptions` on the Queue.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    let imports: BullmqImports = {
+      hasBullmqImport: false,
+      workerLocalNames: new Set(),
+      queueLocalNames: new Set(),
+      queueEventsLocalNames: new Set(),
+    };
+    let knownQueues = new Map<string, QueueDefinition>();
+
+    return {
+      Program(program) {
+        imports = analyzeBullmqImports(program);
+        knownQueues = collectQueueDefinitions(program, imports);
+      },
+      CallExpression(node) {
+        if (!isQueueAddCall(node)) {
+          return;
+        }
+
+        if (!receiverIsQueueLike(node, knownQueues)) {
+          return;
+        }
+
+        if (callHasOption(node, "removeOnFail")) {
+          return;
+        }
+
+        if (queueDefaultsHaveOption(node, knownQueues, "removeOnFail")) {
+          return;
+        }
+
+        context.report({ node, messageId: "missingRemoveOnFail" });
+      },
+    };
+  },
+});
+
+function receiverIsQueueLike(
+  call: TSESTree.CallExpression,
+  knownQueues: ReadonlyMap<string, QueueDefinition>
+): boolean {
+  const key = getCallReceiverKey(call);
+
+  if (!key) {
+    return false;
+  }
+
+  if (knownQueues.has(key)) {
+    return true;
+  }
+
+  const last = key.includes(".") ? (key.split(".").pop() ?? key) : key;
+
+  return isQueueLikeReceiverName(last);
+}
+
+function callHasOption(call: TSESTree.CallExpression, name: string): boolean {
+  const opts = getOptionsObjectArg(call, 2);
+
+  if (!opts) {
+    return false;
+  }
+
+  return findObjectProperty(opts, name) !== null;
+}
+
+function queueDefaultsHaveOption(
+  call: TSESTree.CallExpression,
+  knownQueues: ReadonlyMap<string, QueueDefinition>,
+  name: string
+): boolean {
+  const key = getCallReceiverKey(call);
+
+  if (!key) {
+    return false;
+  }
+
+  const def = knownQueues.get(key);
+
+  if (!def?.defaultJobOptions) {
+    return false;
+  }
+
+  return findObjectProperty(def.defaultJobOptions, name) !== null;
+}

package/src/rule-packs/bullmq/rules/worker-must-implement-close.ts

@@ -0,0 +1,182 @@
+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 {
+  analyzeBullmqImports,
+  isNewWorker,
+  walkSome,
+  type BullmqImports,
+} from "../utils";
+
+export const RULE_NAME = "worker-must-implement-close";
+
+export interface WorkerMustImplementCloseOptions {
+  readonly closeMethodNames?: readonly string[];
+}
+
+type RuleOptions = [WorkerMustImplementCloseOptions];
+type MessageIds = "missingClose";
+
+const DEFAULT_CLOSE_METHODS: readonly string[] = [
+  "close",
+  "shutdown",
+  "dispose",
+  "onModuleDestroy",
+];
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    closeMethodNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+  },
+};
+
+export const workerMustImplementCloseRule = createRule<RuleOptions, MessageIds>(
+  {
+    name: RULE_NAME,
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "Classes that own a `new Worker(...)` instance must declare a close-equivalent method for graceful shutdown.",
+      },
+      schema: [optionSchema],
+      messages: {
+        missingClose:
+          "Class '{{name}}' owns a `new Worker(...)` instance but does not declare a close method ({{methods}}). BullMQ workers must be explicitly closed during graceful shutdown — otherwise jobs in flight are abandoned and Redis connections leak.",
+      },
+    },
+    defaultOptions: [{ closeMethodNames: [...DEFAULT_CLOSE_METHODS] }],
+    create(context, [options]) {
+      const closeMethods = new Set(
+        options.closeMethodNames ?? DEFAULT_CLOSE_METHODS
+      );
+
+      let imports: BullmqImports = {
+        hasBullmqImport: false,
+        workerLocalNames: new Set(),
+        queueLocalNames: new Set(),
+        queueEventsLocalNames: new Set(),
+      };
+
+      return {
+        Program(program) {
+          imports = analyzeBullmqImports(program);
+        },
+        ClassDeclaration(node) {
+          if (!imports.hasBullmqImport) {
+            return;
+          }
+
+          if (!classOwnsWorker(node, imports)) {
+            return;
+          }
+
+          if (classDeclaresAnyMethod(node, closeMethods)) {
+            return;
+          }
+
+          const className = node.id?.name ?? "<anonymous>";
+          const methodList = [...closeMethods]
+            .map((m) => `\`${m}\``)
+            .join(", ");
+
+          context.report({
+            node: node.id ?? node,
+            messageId: "missingClose",
+            data: { name: className, methods: methodList },
+          });
+        },
+      };
+    },
+  }
+);
+
+function classOwnsWorker(
+  cls: TSESTree.ClassDeclaration,
+  imports: BullmqImports
+): boolean {
+  for (const member of cls.body.body) {
+    if (
+      member.type === AST_NODE_TYPES.PropertyDefinition &&
+      member.value &&
+      isNewWorker(member.value, imports)
+    ) {
+      return true;
+    }
+
+    if (member.type === AST_NODE_TYPES.MethodDefinition) {
+      const fnBody = member.value.body;
+
+      if (!fnBody) {
+        continue;
+      }
+
+      const found = walkSome(fnBody, (n) => {
+        if (n.type !== AST_NODE_TYPES.AssignmentExpression) {
+          return false;
+        }
+
+        if (
+          n.left.type !== AST_NODE_TYPES.MemberExpression ||
+          n.left.object.type !== AST_NODE_TYPES.ThisExpression
+        ) {
+          return false;
+        }
+
+        return isNewWorker(n.right, imports);
+      });
+
+      if (found) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+function classDeclaresAnyMethod(
+  cls: TSESTree.ClassDeclaration,
+  methodNames: ReadonlySet<string>
+): boolean {
+  for (const member of cls.body.body) {
+    if (member.type !== AST_NODE_TYPES.MethodDefinition) {
+      continue;
+    }
+
+    if (member.kind === "constructor") {
+      continue;
+    }
+
+    const name = getMethodName(member);
+
+    if (name && methodNames.has(name)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function getMethodName(method: TSESTree.MethodDefinition): string | null {
+  if (method.key.type === AST_NODE_TYPES.Identifier) {
+    return method.key.name;
+  }
+
+  if (
+    method.key.type === AST_NODE_TYPES.Literal &&
+    typeof method.key.value === "string"
+  ) {
+    return method.key.value;
+  }
+
+  return null;
+}

package/src/rule-packs/bullmq/rules/worker-must-listen-failed.ts

@@ -0,0 +1,140 @@
+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 {
+  analyzeBullmqImports,
+  collectWorkerDefinitions,
+  getReceiverKey,
+  walkAll,
+  type BullmqImports,
+  type WorkerDefinition,
+} from "../utils";
+
+export const RULE_NAME = "worker-must-listen-failed";
+
+export interface WorkerMustListenFailedOptions {
+  readonly requiredEvents?: readonly string[];
+}
+
+type RuleOptions = [WorkerMustListenFailedOptions];
+type MessageIds = "missingListener";
+
+const DEFAULT_REQUIRED_EVENTS: readonly string[] = ["failed"];
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    requiredEvents: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+  },
+};
+
+export const workerMustListenFailedRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Every `new Worker(...)` must register listeners for required events (default `failed`) — BullMQ failures are silent unless explicitly subscribed.",
+    },
+    schema: [optionSchema],
+    messages: {
+      missingListener:
+        "Worker assigned to `{{name}}` has no `.on('{{event}}', ...)` listener — BullMQ failures are silent unless explicitly subscribed.",
+    },
+  },
+  defaultOptions: [{ requiredEvents: [...DEFAULT_REQUIRED_EVENTS] }],
+  create(context, [options]) {
+    const requiredEvents = options.requiredEvents ?? DEFAULT_REQUIRED_EVENTS;
+
+    let imports: BullmqImports = {
+      hasBullmqImport: false,
+      workerLocalNames: new Set(),
+      queueLocalNames: new Set(),
+      queueEventsLocalNames: new Set(),
+    };
+    let workers: WorkerDefinition[] = [];
+    let listenerKeyEventPairs = new Set<string>();
+
+    return {
+      Program(program) {
+        imports = analyzeBullmqImports(program);
+
+        if (!imports.hasBullmqImport) {
+          return;
+        }
+
+        workers = collectWorkerDefinitions(program, imports);
+        listenerKeyEventPairs = collectOnListeners(program);
+      },
+      "Program:exit"() {
+        if (!imports.hasBullmqImport) {
+          return;
+        }
+
+        for (const worker of workers) {
+          const bindingKey = worker.bindingKey;
+
+          if (!bindingKey) {
+            continue;
+          }
+
+          for (const event of requiredEvents) {
+            const key = `${bindingKey}::${event}`;
+
+            if (!listenerKeyEventPairs.has(key)) {
+              context.report({
+                node: worker.node,
+                messageId: "missingListener",
+                data: { name: bindingKey, event },
+              });
+            }
+          }
+        }
+      },
+    };
+  },
+});
+
+function collectOnListeners(program: TSESTree.Program): Set<string> {
+  const pairs = new Set<string>();
+
+  walkAll(program, (node) => {
+    if (node.type !== AST_NODE_TYPES.CallExpression) {
+      return;
+    }
+
+    if (
+      node.callee.type !== AST_NODE_TYPES.MemberExpression ||
+      node.callee.property.type !== AST_NODE_TYPES.Identifier ||
+      node.callee.property.name !== "on"
+    ) {
+      return;
+    }
+
+    const receiverKey = getReceiverKey(node.callee.object);
+
+    if (!receiverKey) {
+      return;
+    }
+
+    const eventArg = node.arguments[0];
+
+    if (
+      eventArg?.type !== AST_NODE_TYPES.Literal ||
+      typeof eventArg.value !== "string"
+    ) {
+      return;
+    }
+
+    pairs.add(`${receiverKey}::${eventArg.value}`);
+  });
+
+  return pairs;
+}