@agjs/tsforge 0.1.0

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

@@ -0,0 +1,334 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { walkAll } from "../utils";
+
+export { walkAll, walkSome } from "../utils";
+
+/**
+ * Helper utilities for BullMQ rules.
+ */
+
+export interface BullmqImports {
+  hasBullmqImport: boolean;
+  workerLocalNames: Set<string>;
+  queueLocalNames: Set<string>;
+  queueEventsLocalNames: Set<string>;
+}
+
+export interface QueueDefinition {
+  bindingKey: string;
+  defaultJobOptions?: TSESTree.ObjectExpression | null;
+}
+
+export interface WorkerDefinition {
+  bindingKey: string | null;
+  node: TSESTree.NewExpression;
+}
+
+export function analyzeBullmqImports(program: TSESTree.Program): BullmqImports {
+  const result: BullmqImports = {
+    hasBullmqImport: false,
+    workerLocalNames: new Set(),
+    queueLocalNames: new Set(),
+    queueEventsLocalNames: new Set(),
+  };
+
+  for (const stmt of program.body) {
+    if (stmt.type !== AST_NODE_TYPES.ImportDeclaration) {
+      continue;
+    }
+
+    if (stmt.source.value !== "bullmq") {
+      continue;
+    }
+
+    result.hasBullmqImport = true;
+
+    for (const specifier of stmt.specifiers) {
+      recordImportSpecifier(specifier, result);
+    }
+  }
+
+  return result;
+}
+
+function recordImportSpecifier(
+  specifier: TSESTree.ImportClause,
+  result: BullmqImports
+): void {
+  if (specifier.type !== AST_NODE_TYPES.ImportSpecifier) {
+    return;
+  }
+
+  if (specifier.imported.type !== AST_NODE_TYPES.Identifier) {
+    return;
+  }
+
+  const target = {
+    Worker: result.workerLocalNames,
+    Queue: result.queueLocalNames,
+    QueueEvents: result.queueEventsLocalNames,
+  }[specifier.imported.name];
+
+  target?.add(specifier.local.name);
+}
+
+function extractDefaultJobOptions(
+  newExpr: TSESTree.NewExpression
+): TSESTree.ObjectExpression | null {
+  const opts = getOptionsObjectArg(newExpr, 1);
+
+  if (!opts) {
+    return null;
+  }
+
+  const property = findObjectProperty(opts, "defaultJobOptions");
+
+  if (!property) {
+    return null;
+  }
+
+  if (property.value.type === AST_NODE_TYPES.ObjectExpression) {
+    return property.value;
+  }
+
+  return null;
+}
+
+function isNewQueue(
+  node: TSESTree.Node,
+  imports: BullmqImports
+): node is TSESTree.NewExpression {
+  if (node.type !== AST_NODE_TYPES.NewExpression) {
+    return false;
+  }
+
+  if (node.callee.type !== AST_NODE_TYPES.Identifier) {
+    return false;
+  }
+
+  return imports.queueLocalNames.has(node.callee.name);
+}
+
+export function collectQueueDefinitions(
+  program: TSESTree.Program,
+  imports: BullmqImports
+): Map<string, QueueDefinition> {
+  const queues = new Map<string, QueueDefinition>();
+
+  walkAll(program, (node) => {
+    if (
+      node.type === AST_NODE_TYPES.VariableDeclarator &&
+      node.id.type === AST_NODE_TYPES.Identifier &&
+      node.init &&
+      isNewQueue(node.init, imports)
+    ) {
+      const varName = node.id.name;
+      const firstArg = node.init.arguments[0];
+
+      if (firstArg?.type === AST_NODE_TYPES.Literal) {
+        const queueName = firstArg.value;
+
+        if (typeof queueName === "string") {
+          const defaultJobOptions = extractDefaultJobOptions(node.init);
+
+          queues.set(varName, {
+            bindingKey: varName,
+            defaultJobOptions,
+          });
+        }
+      }
+    }
+  });
+
+  walkAll(program, (node) => {
+    if (!isNewQueue(node, imports)) {
+      return;
+    }
+
+    const firstArg = node.arguments[0];
+
+    if (firstArg?.type !== AST_NODE_TYPES.Literal) {
+      return;
+    }
+
+    const queueName = firstArg.value;
+
+    if (typeof queueName !== "string") {
+      return;
+    }
+
+    const defaultJobOptions = extractDefaultJobOptions(node);
+    const { parent } = node;
+
+    if (
+      parent.type !== AST_NODE_TYPES.VariableDeclarator ||
+      parent.id.type !== AST_NODE_TYPES.Identifier
+    ) {
+      queues.set(queueName, {
+        bindingKey: queueName,
+        defaultJobOptions,
+      });
+    }
+  });
+
+  return queues;
+}
+
+export function collectWorkerDefinitions(
+  program: TSESTree.Program,
+  imports: BullmqImports
+): WorkerDefinition[] {
+  const workers: WorkerDefinition[] = [];
+  const varToWorkerMap = new Map<string, TSESTree.NewExpression>();
+
+  walkAll(program, (node) => {
+    if (
+      node.type === AST_NODE_TYPES.VariableDeclarator &&
+      node.id.type === AST_NODE_TYPES.Identifier &&
+      node.init &&
+      isNewWorker(node.init, imports)
+    ) {
+      varToWorkerMap.set(node.id.name, node.init);
+    }
+  });
+
+  walkAll(program, (node) => {
+    if (!isNewWorker(node, imports)) {
+      return;
+    }
+
+    const bindingKey = workerBindingKey(node.parent);
+
+    workers.push({
+      bindingKey,
+      node,
+    });
+  });
+
+  return workers;
+}
+
+function workerBindingKey(parent: TSESTree.Node): string | null {
+  if (
+    parent.type === AST_NODE_TYPES.VariableDeclarator &&
+    parent.id.type === AST_NODE_TYPES.Identifier
+  ) {
+    return parent.id.name;
+  }
+
+  if (parent.type === AST_NODE_TYPES.PropertyDefinition) {
+    if (parent.key.type === AST_NODE_TYPES.Identifier && !parent.computed) {
+      return `this.${parent.key.name}`;
+    }
+
+    if (
+      parent.key.type === AST_NODE_TYPES.Literal &&
+      typeof parent.key.value === "string"
+    ) {
+      return `this.${parent.key.value}`;
+    }
+
+    return null;
+  }
+
+  if (parent.type === AST_NODE_TYPES.AssignmentExpression) {
+    if (parent.left.type === AST_NODE_TYPES.Identifier) {
+      return parent.left.name;
+    }
+
+    if (parent.left.type === AST_NODE_TYPES.MemberExpression) {
+      return getReceiverKey(parent.left);
+    }
+  }
+
+  return null;
+}
+
+export function isNewWorker(
+  node: TSESTree.Node,
+  imports: BullmqImports
+): node is TSESTree.NewExpression {
+  if (node.type !== AST_NODE_TYPES.NewExpression) {
+    return false;
+  }
+
+  if (node.callee.type !== AST_NODE_TYPES.Identifier) {
+    return false;
+  }
+
+  return imports.workerLocalNames.has(node.callee.name);
+}
+
+export function isQueueAddCall(node: TSESTree.CallExpression): boolean {
+  return (
+    node.callee.type === AST_NODE_TYPES.MemberExpression &&
+    node.callee.property.type === AST_NODE_TYPES.Identifier &&
+    node.callee.property.name === "add"
+  );
+}
+
+export function getCallReceiverKey(
+  node: TSESTree.CallExpression
+): string | null {
+  return getReceiverKey(node.callee);
+}
+
+export function getReceiverKey(callee: TSESTree.Node): string | null {
+  if (callee.type === AST_NODE_TYPES.MemberExpression) {
+    if (callee.object.type === AST_NODE_TYPES.Identifier) {
+      return callee.object.name;
+    }
+
+    if (
+      callee.object.type === AST_NODE_TYPES.MemberExpression &&
+      callee.object.property.type === AST_NODE_TYPES.Identifier
+    ) {
+      const base = getReceiverKey(callee.object);
+
+      if (base) {
+        return `${base}.${callee.object.property.name}`;
+      }
+    }
+  }
+
+  return null;
+}
+
+export function isQueueLikeReceiverName(name: string): boolean {
+  return /[Qq]ueue/.test(name);
+}
+
+export function getOptionsObjectArg(
+  node: TSESTree.NewExpression | TSESTree.CallExpression,
+  argIndex: number
+): TSESTree.ObjectExpression | null {
+  const arg = node.arguments[argIndex];
+
+  if (arg?.type === AST_NODE_TYPES.ObjectExpression) {
+    return arg;
+  }
+
+  return null;
+}
+
+export function findObjectProperty(
+  obj: TSESTree.ObjectExpression,
+  name: string
+): TSESTree.Property | null {
+  for (const prop of obj.properties) {
+    if (prop.type !== AST_NODE_TYPES.Property) {
+      continue;
+    }
+
+    if (prop.key.type === AST_NODE_TYPES.Identifier && prop.key.name === name) {
+      return prop;
+    }
+
+    if (prop.key.type === AST_NODE_TYPES.Literal && prop.key.value === name) {
+      return prop;
+    }
+  }
+
+  return null;
+}

package/src/rule-packs/code-flow/index.ts

@@ -0,0 +1,25 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { noBareDateNowRule } from "./rules/no-bare-date-now";
+import { noTemplateTrimEmptyTernaryRule } from "./rules/no-template-trim-empty-ternary";
+import { preferEarlyReturnRule } from "./rules/prefer-early-return";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "no-bare-date-now": noBareDateNowRule,
+  "no-template-trim-empty-ternary": noTemplateTrimEmptyTernaryRule,
+  "prefer-early-return": preferEarlyReturnRule,
+};
+
+export const codeFlowPack: IRulePack = {
+  id: "code-flow",
+  description: "Control flow clarity and early returns",
+  rules,
+  rulesConfig: {
+    "no-bare-date-now": "error",
+    "no-template-trim-empty-ternary": "error",
+    "prefer-early-return": "error",
+  },
+};
+
+export default codeFlowPack;

package/src/rule-packs/code-flow/rules/index.ts

@@ -0,0 +1,3 @@
+export { noBareDateNowRule } from "./no-bare-date-now";
+export { noTemplateTrimEmptyTernaryRule } from "./no-template-trim-empty-ternary";
+export { preferEarlyReturnRule } from "./prefer-early-return";

package/src/rule-packs/code-flow/rules/no-bare-date-now.ts

@@ -0,0 +1,138 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-bare-date-now";
+
+type MessageIds =
+  | "bareDateNow"
+  | "bareNewDate"
+  | "bareMathRandom"
+  | "bareDateConstructor";
+
+export interface INoBareDateNowOptions {
+  readonly allowedPaths?: readonly string[];
+}
+
+const DEFAULTS: Required<INoBareDateNowOptions> = {
+  allowedPaths: [],
+};
+
+function fileMatchesAllowlist(
+  filename: string,
+  allowed: readonly string[]
+): boolean {
+  if (allowed.length === 0) {
+    return false;
+  }
+
+  const normalized = filename.replace(/\\/g, "/");
+
+  return allowed.some((segment) => normalized.includes(segment));
+}
+
+function isDateNow(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  return (
+    callee.type === AST_NODE_TYPES.MemberExpression &&
+    callee.object.type === AST_NODE_TYPES.Identifier &&
+    callee.object.name === "Date" &&
+    callee.property.type === AST_NODE_TYPES.Identifier &&
+    callee.property.name === "now" &&
+    !callee.computed
+  );
+}
+
+function isMathRandom(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  return (
+    callee.type === AST_NODE_TYPES.MemberExpression &&
+    callee.object.type === AST_NODE_TYPES.Identifier &&
+    callee.object.name === "Math" &&
+    callee.property.type === AST_NODE_TYPES.Identifier &&
+    callee.property.name === "random" &&
+    !callee.computed
+  );
+}
+
+function isBareDate(
+  node: TSESTree.NewExpression | TSESTree.CallExpression
+): boolean {
+  return (
+    node.callee.type === AST_NODE_TYPES.Identifier &&
+    node.callee.name === "Date" &&
+    node.arguments.length === 0
+  );
+}
+
+export const noBareDateNowRule = createRule<
+  [INoBareDateNowOptions],
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow direct calls to non-deterministic time/random sources (`Date.now()`, `new Date()`, `Date()`, `Math.random()`) outside an allowlisted set of utility paths. Determinism is required for snapshot tests, workflow replays, and time-travel debugging — every consumer should route through a typed util that can be faked in tests.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          allowedPaths: {
+            type: "array",
+            items: { type: "string" },
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      bareDateNow:
+        "Direct `Date.now()` is non-deterministic. Import the project's `now()` util instead (or add the file to this rule's `allowedPaths` if it IS the util).",
+      bareNewDate:
+        "Direct `new Date()` (no args) is non-deterministic. Import the project's `now()` util and pass the millisecond timestamp explicitly, or add the file to `allowedPaths`.",
+      bareDateConstructor:
+        "Direct `Date()` (no args) is non-deterministic. Import the project's `now()` util and pass the millisecond timestamp explicitly, or add the file to `allowedPaths`.",
+      bareMathRandom:
+        "Direct `Math.random()` is non-deterministic. Import the project's random util (which can be seeded in tests) instead, or add the file to `allowedPaths`.",
+    },
+  },
+  defaultOptions: [DEFAULTS],
+  create(context, optionsArg) {
+    const options = optionsArg[0] ?? DEFAULTS;
+    const allowed = options.allowedPaths ?? DEFAULTS.allowedPaths;
+
+    if (fileMatchesAllowlist(context.filename, allowed)) {
+      return {};
+    }
+
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        if (isDateNow(node)) {
+          context.report({ node, messageId: "bareDateNow" });
+
+          return;
+        }
+
+        if (isMathRandom(node)) {
+          context.report({ node, messageId: "bareMathRandom" });
+
+          return;
+        }
+
+        if (isBareDate(node)) {
+          context.report({ node, messageId: "bareDateConstructor" });
+        }
+      },
+      NewExpression(node: TSESTree.NewExpression) {
+        if (isBareDate(node)) {
+          context.report({ node, messageId: "bareNewDate" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/code-flow/rules/no-template-trim-empty-ternary.ts

@@ -0,0 +1,87 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-template-trim-empty-ternary";
+
+type MessageIds = "extractToUtil";
+
+/**
+ * Bans the "build a string from a template literal, trim it, ternary
+ * against empty" pattern:
+ *
+ *   `${first} ${last}`.trim() === "" ? email : `${first} ${last}`.trim()
+ *
+ * Patterns like this are testability traps: the same expression is
+ * built twice in the call site, no name documents the intent, and tests
+ * have to duplicate the construction to verify behaviour. Extract to a
+ * named util (e.g. `buildDisplayName({ first, last, fallback }))`) and
+ * test it in one place.
+ */
+export const noTemplateTrimEmptyTernaryRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow inline `<template>.trim() === '' ? fallback : <template>.trim()` patterns. Extract to a named utility.",
+    },
+    schema: [],
+    messages: {
+      extractToUtil:
+        "Extract this `<template>.trim() === ''` fallback pattern to a named util (e.g. `buildDisplayName(...)`). Inline ternaries duplicate the expression and aren't unit-testable in one place.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      ConditionalExpression(node) {
+        if (matchesTemplateTrimEmptyTest(node.test)) {
+          context.report({ node, messageId: "extractToUtil" });
+        }
+      },
+    };
+  },
+});
+
+function matchesTemplateTrimEmptyTest(test: TSESTree.Expression): boolean {
+  if (test.type !== AST_NODE_TYPES.BinaryExpression) {
+    return false;
+  }
+
+  if (test.operator !== "===" && test.operator !== "!==") {
+    return false;
+  }
+
+  return (
+    (isTrimCallOnTemplate(test.left) && isEmptyStringLiteral(test.right)) ||
+    (isEmptyStringLiteral(test.left) && isTrimCallOnTemplate(test.right))
+  );
+}
+
+function isTrimCallOnTemplate(node: TSESTree.Node): boolean {
+  if (node.type !== AST_NODE_TYPES.CallExpression) {
+    return false;
+  }
+
+  if (node.callee.type !== AST_NODE_TYPES.MemberExpression) {
+    return false;
+  }
+
+  if (
+    node.callee.property.type !== AST_NODE_TYPES.Identifier ||
+    node.callee.property.name !== "trim"
+  ) {
+    return false;
+  }
+
+  return node.callee.object.type === AST_NODE_TYPES.TemplateLiteral;
+}
+
+function isEmptyStringLiteral(node: TSESTree.Node): boolean {
+  return (
+    node.type === AST_NODE_TYPES.Literal &&
+    typeof node.value === "string" &&
+    node.value === ""
+  );
+}

package/src/rule-packs/code-flow/rules/prefer-early-return.ts

@@ -0,0 +1,80 @@
+import type { TSESTree } from "@typescript-eslint/utils";
+import type { RuleFixer } from "@typescript-eslint/utils/ts-eslint";
+
+import { createRule } from "../../create-rule";
+import {
+  buildGuardClauseReplacement,
+  findWrappedHappyPathIf,
+  getFunctionBlockBody,
+} from "../utils/prefer-early-return";
+
+export const RULE_NAME = "prefer-early-return";
+
+type MessageIds = "preferEarlyReturn";
+
+export const preferEarlyReturnRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Prefer guard clauses (early return) over wrapping the function body in a multi-statement `if` without an `else`.",
+    },
+    schema: [],
+    messages: {
+      preferEarlyReturn:
+        "Use a guard clause (early return) instead of wrapping the function body in an `if`. Invert the condition and return early so the happy path stays at the top level.",
+    },
+    hasSuggestions: true,
+  },
+  defaultOptions: [],
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    function reportWrappedHappyPath(ifStatement: TSESTree.IfStatement): void {
+      const replacement = buildGuardClauseReplacement(sourceCode, ifStatement);
+      const suggest =
+        replacement === null
+          ? []
+          : [
+              {
+                messageId: "preferEarlyReturn" as const,
+                fix(fixer: RuleFixer) {
+                  return fixer.replaceText(ifStatement, replacement);
+                },
+              },
+            ];
+
+      context.report({
+        node: ifStatement,
+        messageId: "preferEarlyReturn",
+        suggest,
+      });
+    }
+
+    function checkFunctionBody(
+      node:
+        | TSESTree.FunctionDeclaration
+        | TSESTree.FunctionExpression
+        | TSESTree.ArrowFunctionExpression
+    ): void {
+      const body = getFunctionBlockBody(node);
+
+      if (body === null) {
+        return;
+      }
+
+      const wrappedIf = findWrappedHappyPathIf(body);
+
+      if (wrappedIf !== null) {
+        reportWrappedHappyPath(wrappedIf);
+      }
+    }
+
+    return {
+      FunctionDeclaration: checkFunctionBody,
+      FunctionExpression: checkFunctionBody,
+      ArrowFunctionExpression: checkFunctionBody,
+    };
+  },
+});