@agjs/tsforge 0.1.0

package/src/rule-packs/tanstack-query/rules/prefix-query-key-must-use-set-queries-data.ts

@@ -0,0 +1,321 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { isNodeLike } from "../../utils";
+
+const HOOK_NAMES = new Set([
+  "useQuery",
+  "useInfiniteQuery",
+  "useSuspenseQuery",
+  "useSuspenseInfiniteQuery",
+]);
+
+const PREFIX_UNSAFE_METHODS = new Set([
+  "setQueryData",
+  "getQueryData",
+  "cancelQueries",
+  "removeQueries",
+  "resetQueries",
+  "prefetchQuery",
+]);
+
+const METHODS_ALLOWING_PREFIX_FILTER = new Set([
+  "cancelQueries",
+  "removeQueries",
+  "resetQueries",
+  "prefetchQuery",
+]);
+
+const SKIP_TRAVERSE_KEYS = new Set([
+  "parent",
+  "tokens",
+  "comments",
+  "loc",
+  "range",
+]);
+
+type MessageIds = "useMatcherApi";
+
+function unwrapExpression(node: TSESTree.Expression): TSESTree.Expression {
+  let current: TSESTree.Expression = node;
+
+  for (;;) {
+    if (current.type === AST_NODE_TYPES.TSAsExpression) {
+      current = current.expression;
+      continue;
+    }
+
+    if (current.type === AST_NODE_TYPES.TSNonNullExpression) {
+      current = current.expression;
+      continue;
+    }
+
+    return current;
+  }
+}
+
+function getSpreadPrefixText(
+  node: TSESTree.Expression,
+  getText: (n: TSESTree.Node) => string
+): string | null {
+  const inner = unwrapExpression(node);
+
+  if (inner.type !== AST_NODE_TYPES.ArrayExpression) {
+    return null;
+  }
+
+  const { elements } = inner;
+
+  if (elements.length < 2) {
+    return null;
+  }
+
+  const firstElement = elements[0];
+
+  if (firstElement?.type !== AST_NODE_TYPES.SpreadElement) {
+    return null;
+  }
+
+  const { argument } = firstElement;
+
+  if (
+    argument.type !== AST_NODE_TYPES.Identifier &&
+    argument.type !== AST_NODE_TYPES.MemberExpression
+  ) {
+    return null;
+  }
+
+  return getText(argument);
+}
+
+function findQueryKeyProperty(
+  obj: TSESTree.ObjectExpression
+): TSESTree.Property | undefined {
+  return obj.properties.find(
+    (p): p is TSESTree.Property =>
+      p.type === AST_NODE_TYPES.Property &&
+      !p.computed &&
+      p.key.type === AST_NODE_TYPES.Identifier &&
+      p.key.name === "queryKey"
+  );
+}
+
+function walkAst(
+  node: TSESTree.Node,
+  visitor: (n: TSESTree.Node) => void
+): void {
+  visitor(node);
+
+  for (const key of Object.keys(node)) {
+    if (SKIP_TRAVERSE_KEYS.has(key)) {
+      continue;
+    }
+
+    const child = Object.getOwnPropertyDescriptor(node, key)?.value;
+
+    if (child === null || child === undefined) {
+      continue;
+    }
+
+    if (Array.isArray(child)) {
+      for (const c of child) {
+        if (isNodeLike(c)) {
+          walkAst(c, visitor);
+        }
+      }
+    } else if (isNodeLike(child)) {
+      walkAst(child, visitor);
+    }
+  }
+}
+
+function collectExtendedPrefixes(
+  program: TSESTree.Program,
+  getText: (n: TSESTree.Node) => string
+): ReadonlySet<string> {
+  const out = new Set<string>();
+
+  walkAst(program, (node) => {
+    if (node.type !== AST_NODE_TYPES.CallExpression) {
+      return;
+    }
+
+    const { callee } = node;
+
+    if (
+      callee.type !== AST_NODE_TYPES.Identifier ||
+      !HOOK_NAMES.has(callee.name) ||
+      node.arguments[0]?.type !== AST_NODE_TYPES.ObjectExpression
+    ) {
+      return;
+    }
+
+    const prop = findQueryKeyProperty(node.arguments[0]);
+
+    if (prop === undefined) {
+      return;
+    }
+
+    // prop.value might be a Pattern node; only process Expressions
+    if (
+      prop.value.type === AST_NODE_TYPES.AssignmentPattern ||
+      prop.value.type === AST_NODE_TYPES.ArrayPattern ||
+      prop.value.type === AST_NODE_TYPES.ObjectPattern ||
+      prop.value.type === AST_NODE_TYPES.TSEmptyBodyFunctionExpression
+    ) {
+      return;
+    }
+
+    const prefix = getSpreadPrefixText(prop.value, getText);
+
+    if (prefix !== null) {
+      out.add(prefix);
+    }
+  });
+
+  return out;
+}
+
+function queryFilterAllowsPrefixMatch(
+  arg: TSESTree.CallExpressionArgument | undefined
+): boolean {
+  if (arg?.type !== AST_NODE_TYPES.ObjectExpression) {
+    return false;
+  }
+
+  for (const prop of arg.properties) {
+    if (
+      prop.type !== AST_NODE_TYPES.Property ||
+      prop.computed ||
+      prop.key.type !== AST_NODE_TYPES.Identifier
+    ) {
+      continue;
+    }
+
+    if (prop.key.name === "predicate") {
+      return true;
+    }
+
+    if (
+      prop.key.name === "exact" &&
+      prop.value.type === AST_NODE_TYPES.Literal &&
+      prop.value.value === false
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function getFirstArgQueryKeyText(
+  args: readonly TSESTree.CallExpressionArgument[],
+  getText: (n: TSESTree.Node) => string
+): string | null {
+  const first = args[0];
+
+  if (first === undefined) {
+    return null;
+  }
+
+  if (first.type === AST_NODE_TYPES.ObjectExpression) {
+    const prop = findQueryKeyProperty(first);
+
+    if (prop === undefined) {
+      return null;
+    }
+
+    // prop.value might be a Pattern node; only process Expressions
+    if (
+      prop.value.type === AST_NODE_TYPES.AssignmentPattern ||
+      prop.value.type === AST_NODE_TYPES.ArrayPattern ||
+      prop.value.type === AST_NODE_TYPES.ObjectPattern ||
+      prop.value.type === AST_NODE_TYPES.TSEmptyBodyFunctionExpression
+    ) {
+      return null;
+    }
+
+    return getText(unwrapExpression(prop.value));
+  }
+
+  if (first.type === AST_NODE_TYPES.SpreadElement) {
+    return null;
+  }
+
+  return getText(unwrapExpression(first));
+}
+
+export const prefixQueryKeyMustUseSetQueriesDataRule = createRule<
+  [],
+  MessageIds
+>({
+  name: "prefix-query-key-must-use-set-queries-data",
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "When a hook uses `queryKey: [...prefix, extra]`, do not call `setQueryData(prefix, …)`, `cancelQueries({ queryKey: prefix })`, etc. — those only touch one cache entry. Use `setQueriesData({ queryKey: prefix }, …)` and matcher-style `cancelQueries` / `invalidateQueries` so every variant is covered.",
+    },
+    schema: [],
+    messages: {
+      useMatcherApi:
+        "Query key spreads `{{prefix}}` with extra segments in this file. Use `setQueriesData` / predicate or `{ queryKey: prefix, exact: false }`-style APIs instead of `{{method}}` with the bare prefix (stale cache for other key variants).",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    const sourceCode = context.sourceCode;
+    const getText = (n: TSESTree.Node) => sourceCode.getText(n);
+
+    return {
+      "Program:exit"(program: TSESTree.Program): void {
+        const extendedPrefixes = collectExtendedPrefixes(program, getText);
+
+        if (extendedPrefixes.size === 0) {
+          return;
+        }
+
+        walkAst(program, (node) => {
+          if (node.type !== AST_NODE_TYPES.CallExpression) {
+            return;
+          }
+
+          const { callee } = node;
+
+          if (callee.type !== AST_NODE_TYPES.MemberExpression) {
+            return;
+          }
+
+          if (callee.property.type !== AST_NODE_TYPES.Identifier) {
+            return;
+          }
+
+          const method = callee.property.name;
+
+          if (!PREFIX_UNSAFE_METHODS.has(method)) {
+            return;
+          }
+
+          if (
+            METHODS_ALLOWING_PREFIX_FILTER.has(method) &&
+            queryFilterAllowsPrefixMatch(node.arguments[0])
+          ) {
+            return;
+          }
+
+          const keyText = getFirstArgQueryKeyText(node.arguments, getText);
+
+          if (keyText === null || !extendedPrefixes.has(keyText)) {
+            return;
+          }
+
+          context.report({
+            node: callee.property,
+            messageId: "useMatcherApi",
+            data: { prefix: keyText, method },
+          });
+        });
+      },
+    };
+  },
+});

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

@@ -0,0 +1,23 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { noFocusedTestsRule } from "./rules/no-focused-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[]>> = {
+  "no-focused-tests": noFocusedTestsRule,
+  "test-file-mirrors-source": testFileMirrorsSourceRule,
+};
+
+export const testConventionsPack: IRulePack = {
+  id: "test-conventions",
+  description:
+    "Testing patterns and file structure for vitest, jest, or Bun tests",
+  rules,
+  rulesConfig: {
+    "no-focused-tests": "error",
+    "test-file-mirrors-source": "error",
+  },
+};
+
+export default testConventionsPack;

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

@@ -0,0 +1,2 @@
+export { noFocusedTestsRule } from "./no-focused-tests";
+export { testFileMirrorsSourceRule } from "./test-file-mirrors-source";

package/src/rule-packs/test-conventions/rules/no-focused-tests.ts

@@ -0,0 +1,170 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-focused-tests";
+
+export interface NoFocusedTestsOptions {
+  readonly testGlobals?: readonly string[];
+  readonly focusedAliases?: readonly string[];
+}
+
+type RuleOptions = [NoFocusedTestsOptions];
+type MessageIds = "focusedTest";
+
+const DEFAULT_TEST_GLOBALS: readonly string[] = [
+  "test",
+  "it",
+  "describe",
+  "suite",
+];
+
+const DEFAULT_FOCUSED_ALIASES: readonly string[] = [
+  "fdescribe",
+  "fit",
+  "fcontext",
+];
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    testGlobals: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    focusedAliases: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    },
+  },
+};
+
+function getMemberPropertyName(
+  member: TSESTree.MemberExpression
+): string | null {
+  if (!member.computed && member.property.type === AST_NODE_TYPES.Identifier) {
+    return member.property.name;
+  }
+
+  if (
+    member.computed &&
+    member.property.type === AST_NODE_TYPES.Literal &&
+    typeof member.property.value === "string"
+  ) {
+    return member.property.value;
+  }
+
+  return null;
+}
+
+function getRootIdentifierName(node: TSESTree.Node): string | null {
+  let current: TSESTree.Node = node;
+
+  while (current.type === AST_NODE_TYPES.MemberExpression) {
+    current = current.object;
+  }
+
+  if (current.type === AST_NODE_TYPES.Identifier) {
+    return current.name;
+  }
+
+  return null;
+}
+
+/**
+ * Returns true when any segment in the chain of MemberExpression
+ * properties is `only`. Catches `test.only`, `test.skip.only`,
+ * `describe.each.only`, etc., as well as the computed-key form
+ * `test["only"]`.
+ */
+function chainHasOnly(node: TSESTree.Node): boolean {
+  let current: TSESTree.Node = node;
+
+  while (current.type === AST_NODE_TYPES.MemberExpression) {
+    const name = getMemberPropertyName(current);
+
+    if (name === "only") {
+      return true;
+    }
+
+    current = current.object;
+  }
+
+  return false;
+}
+
+export const noFocusedTestsRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow focused tests (`test.only`, `it.only`, `fdescribe`, ...) — the canonical 'I forgot to remove this before committing' leak.",
+    },
+    schema: [optionSchema],
+    messages: {
+      focusedTest:
+        "Focused test '{{name}}' left in source — this skips every other test in CI. Remove the `.only` / `f`-prefix before committing.",
+    },
+  },
+  defaultOptions: [
+    {
+      testGlobals: [...DEFAULT_TEST_GLOBALS],
+      focusedAliases: [...DEFAULT_FOCUSED_ALIASES],
+    },
+  ],
+  create(context, [options]) {
+    const testGlobals = new Set(options.testGlobals ?? DEFAULT_TEST_GLOBALS);
+    const focusedAliases = new Set(
+      options.focusedAliases ?? DEFAULT_FOCUSED_ALIASES
+    );
+
+    return {
+      CallExpression(node) {
+        const callee = node.callee;
+
+        // Bare `fdescribe(...)` / `fit(...)`.
+        if (
+          callee.type === AST_NODE_TYPES.Identifier &&
+          focusedAliases.has(callee.name)
+        ) {
+          context.report({
+            node: callee,
+            messageId: "focusedTest",
+            data: { name: callee.name },
+          });
+
+          return;
+        }
+
+        // `test.only(...)`, `test.skip.only(...)`, `test["only"](...)`.
+        if (callee.type !== AST_NODE_TYPES.MemberExpression) {
+          return;
+        }
+
+        const root = getRootIdentifierName(callee);
+
+        if (root === null || !testGlobals.has(root)) {
+          return;
+        }
+
+        if (!chainHasOnly(callee)) {
+          return;
+        }
+
+        const sourceText = context.sourceCode.getText(callee);
+
+        context.report({
+          node: callee,
+          messageId: "focusedTest",
+          data: { name: sourceText },
+        });
+      },
+    };
+  },
+});

package/src/rule-packs/test-conventions/rules/test-file-mirrors-source.ts

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import { toPosixRelative } from "../../utils";
+
+export const RULE_NAME = "test-file-mirrors-source";
+
+export interface TestFileMirrorsSourceOptions {
+  readonly testRoot?: string;
+  readonly sourceRoot?: string;
+  readonly testSuffix?: string;
+  readonly additionalSourceRoots?: readonly string[];
+}
+
+type RuleOptions = [TestFileMirrorsSourceOptions];
+type MessageIds = "orphanedTest";
+
+const DEFAULT_TEST_ROOT = "tests";
+const DEFAULT_SOURCE_ROOT = "src";
+const DEFAULT_TEST_SUFFIX = ".test.ts";
+const DEFAULT_ADDITIONAL_SOURCE_ROOTS: readonly string[] = [];
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    testRoot: { type: "string", minLength: 1 },
+    sourceRoot: { type: "string", minLength: 1 },
+    testSuffix: { type: "string", minLength: 1 },
+    additionalSourceRoots: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    },
+  },
+};
+
+/**
+ * Indirection so test suites can stub fs lookups without spinning up a
+ * real filesystem. Defaults to the real `fs.existsSync`.
+ */
+export type FileExistsFn = (absolutePath: string) => boolean;
+
+let fileExists: FileExistsFn = (p) => fs.existsSync(p);
+
+export function setFileExistsForTesting(fn: FileExistsFn | null): void {
+  fileExists = fn ?? ((p) => fs.existsSync(p));
+}
+
+export const testFileMirrorsSourceRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Every test file under `tests/` must mirror a source file under `src/`. Catches orphaned tests left behind after refactors and renames.",
+    },
+    schema: [optionSchema],
+    messages: {
+      orphanedTest:
+        "Test file '{{file}}' has no matching source — expected '{{expected}}'. Either rename the test or delete it.",
+    },
+  },
+  defaultOptions: [
+    {
+      testRoot: DEFAULT_TEST_ROOT,
+      sourceRoot: DEFAULT_SOURCE_ROOT,
+      testSuffix: DEFAULT_TEST_SUFFIX,
+      additionalSourceRoots: [...DEFAULT_ADDITIONAL_SOURCE_ROOTS],
+    },
+  ],
+  create(context, [options]) {
+    const testRoot = options.testRoot ?? DEFAULT_TEST_ROOT;
+    const sourceRoot = options.sourceRoot ?? DEFAULT_SOURCE_ROOT;
+    const testSuffix = options.testSuffix ?? DEFAULT_TEST_SUFFIX;
+    const additionalSourceRoots =
+      options.additionalSourceRoots ?? DEFAULT_ADDITIONAL_SOURCE_ROOTS;
+
+    return {
+      Program(program) {
+        const filename = context.filename;
+        const cwd = context.cwd;
+        const relative = toPosixRelative(filename, cwd);
+
+        const testRootPrefix = `${testRoot.replace(/\/$/, "")}/`;
+
+        if (!relative.startsWith(testRootPrefix)) {
+          return;
+        }
+
+        if (!relative.endsWith(testSuffix)) {
+          return;
+        }
+
+        const innerPath = relative.slice(
+          testRootPrefix.length,
+          relative.length - testSuffix.length
+        );
+
+        const candidateRoots = [sourceRoot, ...additionalSourceRoots];
+        const candidates = candidateRoots.map((root) =>
+          path.resolve(cwd, `${root.replace(/\/$/, "")}/${innerPath}.ts`)
+        );
+
+        for (const candidate of candidates) {
+          if (fileExists(candidate)) {
+            return;
+          }
+        }
+
+        const expectedRelative = `${sourceRoot.replace(/\/$/, "")}/${innerPath}.ts`;
+
+        context.report({
+          node: program,
+          messageId: "orphanedTest",
+          data: {
+            file: relative,
+            expected: expectedRelative,
+          },
+        });
+      },
+    };
+  },
+});