@agjs/tsforge 0.1.18 → 0.2.0

package/src/rule-packs/structured-logging/rules/caught-error-log-requires-cause.ts

@@ -0,0 +1,234 @@
+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 {
+  DEFAULT_LOGGER_METHODS,
+  DEFAULT_LOGGER_NAMES,
+  getStructuredPayload,
+  matchLoggerCall,
+} from "../utils/logger";
+
+export const RULE_NAME = "caught-error-log-requires-cause";
+
+export interface ICaughtErrorLogRequiresCauseOptions {
+  readonly loggerNames?: readonly string[];
+  readonly loggerMethods?: readonly string[];
+  readonly errorIdentifierNames?: readonly string[];
+  readonly causeField?: string;
+}
+
+type RuleOptions = [ICaughtErrorLogRequiresCauseOptions];
+type MessageIds = "missingCause";
+
+const DEFAULT_ERROR_NAMES: readonly string[] = ["error", "err", "e", "cause"];
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    loggerNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    loggerMethods: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    errorIdentifierNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    causeField: { type: "string", minLength: 1 },
+  },
+};
+
+function isErrorIdentifier(
+  node: TSESTree.Node,
+  names: ReadonlySet<string>
+): node is TSESTree.Identifier {
+  return node.type === AST_NODE_TYPES.Identifier && names.has(node.name);
+}
+
+function payloadHasField(
+  payload: TSESTree.ObjectExpression,
+  field: string
+): boolean {
+  for (const prop of payload.properties) {
+    if (prop.type === AST_NODE_TYPES.SpreadElement) {
+      return true;
+    }
+
+    if (prop.type !== AST_NODE_TYPES.Property) {
+      continue;
+    }
+
+    if (
+      prop.key.type === AST_NODE_TYPES.Identifier &&
+      prop.key.name === field
+    ) {
+      return true;
+    }
+
+    if (
+      prop.key.type === AST_NODE_TYPES.Literal &&
+      typeof prop.key.value === "string" &&
+      prop.key.value === field
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function loggerCallReferencesCaughtError(
+  node: TSESTree.CallExpression,
+  catchParam: TSESTree.Identifier | null,
+  errorNames: ReadonlySet<string>
+): boolean {
+  if (catchParam !== null) {
+    for (const arg of node.arguments) {
+      if (arg.type === AST_NODE_TYPES.SpreadElement) {
+        continue;
+      }
+
+      if (isErrorIdentifier(arg, new Set([catchParam.name]))) {
+        return true;
+      }
+    }
+  }
+
+  const payload = getStructuredPayload(node);
+
+  if (payload === null) {
+    return false;
+  }
+
+  for (const prop of payload.properties) {
+    if (prop.type !== AST_NODE_TYPES.Property) {
+      continue;
+    }
+
+    if (isErrorIdentifier(prop.value, errorNames)) {
+      return true;
+    }
+
+    if (
+      prop.key.type === AST_NODE_TYPES.Identifier &&
+      prop.key.name === "err" &&
+      isErrorIdentifier(prop.value, errorNames)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export const caughtErrorLogRequiresCauseRule = createRule<
+  RuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "When logging a caught error, include a `cause` field in the structured payload so downstream tools preserve the error chain.",
+    },
+    schema: [optionSchema],
+    messages: {
+      missingCause:
+        "Logger call for caught error missing `{{field}}:` — include the original error so cause chains survive structured logging.",
+    },
+  },
+  defaultOptions: [
+    {
+      loggerNames: [...DEFAULT_LOGGER_NAMES],
+      loggerMethods: [...DEFAULT_LOGGER_METHODS],
+      errorIdentifierNames: [...DEFAULT_ERROR_NAMES],
+      causeField: "cause",
+    },
+  ],
+  create(context, [options]) {
+    const loggerNames = new Set(options.loggerNames ?? DEFAULT_LOGGER_NAMES);
+    const loggerMethods = new Set(
+      options.loggerMethods ?? DEFAULT_LOGGER_METHODS
+    );
+    const errorNames = new Set(
+      options.errorIdentifierNames ?? DEFAULT_ERROR_NAMES
+    );
+    const causeField = options.causeField ?? "cause";
+
+    return {
+      CatchClause(node) {
+        const catchParam =
+          node.param?.type === AST_NODE_TYPES.Identifier ? node.param : null;
+        const body = node.body;
+
+        const visit = (current: TSESTree.Node): void => {
+          if (current.type === AST_NODE_TYPES.CallExpression) {
+            const method = matchLoggerCall(current, loggerNames, loggerMethods);
+
+            if (
+              method !== null &&
+              loggerCallReferencesCaughtError(current, catchParam, errorNames)
+            ) {
+              const payload = getStructuredPayload(current);
+
+              if (payload === null || !payloadHasField(payload, causeField)) {
+                context.report({
+                  node: current,
+                  messageId: "missingCause",
+                  data: { field: causeField },
+                });
+              }
+            }
+          }
+
+          if (
+            current.type === AST_NODE_TYPES.BlockStatement ||
+            current.type === AST_NODE_TYPES.Program
+          ) {
+            for (const stmt of current.body) {
+              visit(stmt);
+            }
+          }
+
+          if (current.type === AST_NODE_TYPES.ExpressionStatement) {
+            visit(current.expression);
+          }
+
+          if (current.type === AST_NODE_TYPES.IfStatement) {
+            visit(current.consequent);
+
+            if (current.alternate !== null) {
+              visit(current.alternate);
+            }
+          }
+
+          if (current.type === AST_NODE_TYPES.TryStatement) {
+            visit(current.block);
+
+            if (current.handler !== null) {
+              visit(current.handler.body);
+            }
+
+            if (current.finalizer !== null) {
+              visit(current.finalizer);
+            }
+          }
+        };
+
+        visit(body);
+      },
+    };
+  },
+});

package/src/rule-packs/structured-logging/rules/logger-not-console.ts

@@ -0,0 +1,146 @@
+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 { matchesAnyGlobPattern, toPosixRelative } from "../../utils";
+
+export const RULE_NAME = "logger-not-console";
+
+export interface ILoggerNotConsoleOptions {
+  readonly serviceGlobs?: readonly string[];
+  readonly consoleMethods?: readonly string[];
+}
+
+type RuleOptions = [ILoggerNotConsoleOptions];
+type MessageIds = "consoleInService";
+
+const DEFAULT_SERVICE_GLOBS = [
+  "**/services/**",
+  "**/*.service.ts",
+  "**/*.queries.ts",
+] as const;
+
+const DEFAULT_CONSOLE_METHODS = [
+  "log",
+  "info",
+  "warn",
+  "error",
+  "debug",
+  "trace",
+] as const;
+
+const DEFAULT_SERVICE_PATH_PATTERNS = [
+  /(^|\/)services\//,
+  /\.service\.tsx?$/,
+  /\.queries\.ts$/,
+] as const;
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    serviceGlobs: {
+      type: "array",
+      items: { type: "string" },
+    },
+    consoleMethods: {
+      type: "array",
+      items: { type: "string" },
+    },
+  },
+};
+
+function isServiceFile(
+  filename: string,
+  cwd: string,
+  globs: readonly string[]
+): boolean {
+  const rel = toPosixRelative(filename, cwd);
+
+  if (DEFAULT_SERVICE_PATH_PATTERNS.some((pattern) => pattern.test(rel))) {
+    return true;
+  }
+
+  return matchesAnyGlobPattern(rel, globs);
+}
+
+function isConsoleCall(
+  node: TSESTree.CallExpression,
+  methods: ReadonlySet<string>
+): boolean {
+  const callee = node.callee;
+
+  if (callee.type !== AST_NODE_TYPES.MemberExpression || callee.computed) {
+    return false;
+  }
+
+  if (
+    callee.object.type !== AST_NODE_TYPES.Identifier ||
+    callee.object.name !== "console"
+  ) {
+    return false;
+  }
+
+  if (callee.property.type !== AST_NODE_TYPES.Identifier) {
+    return false;
+  }
+
+  return methods.has(callee.property.name);
+}
+
+export const loggerNotConsoleRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Service modules should use the structured logger instead of `console.*` — console output is unstructured and hard to search.",
+    },
+    schema: [optionSchema],
+    messages: {
+      consoleInService:
+        "Use the structured logger instead of `console.{{method}}()` in service modules.",
+    },
+  },
+  defaultOptions: [
+    {
+      serviceGlobs: [...DEFAULT_SERVICE_GLOBS],
+      consoleMethods: [...DEFAULT_CONSOLE_METHODS],
+    },
+  ],
+  create(context, [options]) {
+    const serviceGlobs = options.serviceGlobs ?? DEFAULT_SERVICE_GLOBS;
+    const consoleMethods = new Set(
+      options.consoleMethods ?? DEFAULT_CONSOLE_METHODS
+    );
+    const cwd = context.cwd;
+
+    if (!isServiceFile(context.filename, cwd, serviceGlobs)) {
+      return {};
+    }
+
+    return {
+      CallExpression(node) {
+        if (!isConsoleCall(node, consoleMethods)) {
+          return;
+        }
+
+        const callee = node.callee;
+
+        if (callee.type !== AST_NODE_TYPES.MemberExpression) {
+          return;
+        }
+
+        if (callee.property.type !== AST_NODE_TYPES.Identifier) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "consoleInService",
+          data: { method: callee.property.name },
+        });
+      },
+    };
+  },
+});

package/src/rule-packs/test-conventions/index.ts

@@ -1,11 +1,17 @@
 import type { TSESLint } from "@typescript-eslint/utils";
 
+import { fakeTimersMustBeRestoredRule } from "./rules/fake-timers-must-be-restored";
+import { noConditionalExpectRule } from "./rules/no-conditional-expect";
 import { noFocusedTestsRule } from "./rules/no-focused-tests";
+import { noRealNetworkInUnitTestsRule } from "./rules/no-real-network-in-unit-tests";
 import { testFileMirrorsSourceRule } from "./rules/test-file-mirrors-source";
 import type { IRulePack } from "../rule-packs.types";
 
 const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "fake-timers-must-be-restored": fakeTimersMustBeRestoredRule,
+  "no-conditional-expect": noConditionalExpectRule,
   "no-focused-tests": noFocusedTestsRule,
+  "no-real-network-in-unit-tests": noRealNetworkInUnitTestsRule,
   "test-file-mirrors-source": testFileMirrorsSourceRule,
 };
 
@@ -15,7 +21,10 @@ export const testConventionsPack: IRulePack = {
     "Testing patterns and file structure for vitest, jest, or Bun tests",
   rules,
   rulesConfig: {
+    "fake-timers-must-be-restored": "error",
+    "no-conditional-expect": "error",
     "no-focused-tests": "error",
+    "no-real-network-in-unit-tests": "warn",
     "test-file-mirrors-source": "error",
   },
 };

package/src/rule-packs/test-conventions/rules/fake-timers-must-be-restored.ts

@@ -0,0 +1,143 @@
+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 { walkAll } from "../../utils";
+
+export const RULE_NAME = "fake-timers-must-be-restored";
+
+export interface IFakeTimersMustBeRestoredOptions {
+  readonly fakeTimerMethods?: readonly string[];
+  readonly restoreTimerMethods?: readonly string[];
+}
+
+type RuleOptions = [IFakeTimersMustBeRestoredOptions];
+type MessageIds = "timersNotRestored";
+
+const DEFAULT_FAKE_TIMER_METHODS = ["useFakeTimers"] as const;
+const DEFAULT_RESTORE_TIMER_METHODS = ["useRealTimers"] as const;
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    fakeTimerMethods: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    restoreTimerMethods: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+  },
+};
+
+function getMemberPropertyName(
+  member: TSESTree.MemberExpression
+): string | null {
+  if (!member.computed && member.property.type === AST_NODE_TYPES.Identifier) {
+    return member.property.name;
+  }
+
+  return null;
+}
+
+function callUsesMethod(
+  node: TSESTree.CallExpression,
+  methods: ReadonlySet<string>
+): boolean {
+  const callee = node.callee;
+
+  if (callee.type === AST_NODE_TYPES.Identifier) {
+    return methods.has(callee.name);
+  }
+
+  if (callee.type === AST_NODE_TYPES.MemberExpression) {
+    const name = getMemberPropertyName(callee);
+
+    return name !== null && methods.has(name);
+  }
+
+  return false;
+}
+
+export const fakeTimersMustBeRestoredRule = createRule<RuleOptions, MessageIds>(
+  {
+    name: RULE_NAME,
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "When a test file calls `useFakeTimers()`, it must also call `useRealTimers()` so later tests are not affected.",
+      },
+      schema: [optionSchema],
+      messages: {
+        timersNotRestored:
+          "`{{method}}()` was called without a matching restore call — fake timers leak into other tests.",
+      },
+    },
+    defaultOptions: [
+      {
+        fakeTimerMethods: [...DEFAULT_FAKE_TIMER_METHODS],
+        restoreTimerMethods: [...DEFAULT_RESTORE_TIMER_METHODS],
+      },
+    ],
+    create(context, [options]) {
+      const fakeMethods = new Set(
+        options.fakeTimerMethods ?? DEFAULT_FAKE_TIMER_METHODS
+      );
+      const restoreMethods = new Set(
+        options.restoreTimerMethods ?? DEFAULT_RESTORE_TIMER_METHODS
+      );
+
+      return {
+        Program(node) {
+          const fakeCalls: TSESTree.CallExpression[] = [];
+          let hasRestore = false;
+
+          walkAll(node, (child) => {
+            if (child.type !== AST_NODE_TYPES.CallExpression) {
+              return;
+            }
+
+            if (callUsesMethod(child, fakeMethods)) {
+              fakeCalls.push(child);
+            }
+
+            if (callUsesMethod(child, restoreMethods)) {
+              hasRestore = true;
+            }
+          });
+
+          if (fakeCalls.length === 0 || hasRestore) {
+            return;
+          }
+
+          for (const call of fakeCalls) {
+            const callee = call.callee;
+            let method = "useFakeTimers";
+
+            if (
+              callee.type === AST_NODE_TYPES.MemberExpression &&
+              callee.property.type === AST_NODE_TYPES.Identifier
+            ) {
+              method = callee.property.name;
+            } else if (callee.type === AST_NODE_TYPES.Identifier) {
+              method = callee.name;
+            }
+
+            context.report({
+              node: call,
+              messageId: "timersNotRestored",
+              data: { method },
+            });
+          }
+        },
+      };
+    },
+  }
+);

package/src/rule-packs/test-conventions/rules/no-conditional-expect.ts

@@ -0,0 +1,77 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-conditional-expect";
+
+type MessageIds = "conditionalExpect";
+
+const CONDITIONAL_PARENTS = new Set([
+  AST_NODE_TYPES.IfStatement,
+  AST_NODE_TYPES.ForStatement,
+  AST_NODE_TYPES.ForInStatement,
+  AST_NODE_TYPES.ForOfStatement,
+  AST_NODE_TYPES.WhileStatement,
+  AST_NODE_TYPES.DoWhileStatement,
+  AST_NODE_TYPES.SwitchCase,
+  AST_NODE_TYPES.ConditionalExpression,
+]);
+
+function isExpectCall(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  if (callee.type === AST_NODE_TYPES.Identifier) {
+    return callee.name === "expect";
+  }
+
+  if (
+    callee.type === AST_NODE_TYPES.MemberExpression &&
+    !callee.computed &&
+    callee.property.type === AST_NODE_TYPES.Identifier &&
+    callee.property.name === "expect"
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+function isInsideConditional(node: TSESTree.Node): boolean {
+  let current = node.parent;
+
+  while (current !== undefined && current !== null) {
+    if (CONDITIONAL_PARENTS.has(current.type)) {
+      return true;
+    }
+
+    current = current.parent;
+  }
+
+  return false;
+}
+
+export const noConditionalExpectRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow `expect()` inside conditionals — tests must fail when assertions are skipped.",
+    },
+    schema: [],
+    messages: {
+      conditionalExpect:
+        "Do not call `expect()` inside a conditional — skipped assertions hide regressions.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (isExpectCall(node) && isInsideConditional(node)) {
+          context.report({ node, messageId: "conditionalExpect" });
+        }
+      },
+    };
+  },
+});