js-style-kit 0.6.1 → 0.8.0

package/src/eslint/testing/README.md

@@ -0,0 +1,436 @@
+# Testing Configuration
+
+Comprehensive testing support with rules for Vitest, Jest, Bun, and Node.js test runners.
+
+[← Back to main README](../../../README.md)
+
+## Overview
+
+Testing support is **disabled by default** and provides:
+
+- Framework-specific test rules (Vitest, Jest, Bun, Node.js)
+- Test file naming conventions
+- Test style consistency (`it` vs `test`)
+- Optional formatting rules for test block padding
+
+## Quick Start
+
+```js
+import { eslintConfig } from "js-style-kit";
+
+export default eslintConfig({
+  testing: true, // Enable with defaults (Vitest)
+});
+```
+
+## Configuration Options
+
+### Basic Enable
+
+```js
+testing: true, // Vitest + ".test" files + "test" style + formatting
+```
+
+### Framework-Specific
+
+```js
+testing: {
+  framework: "vitest",         // "vitest" | "jest" | "bun" | "node"
+  filenamePattern: "test",     // "test" | "spec"
+  itOrTest: "test",            // "test" | "it"
+  formattingRules: true,       // Enable padding rules
+}
+```
+
+### Custom Files
+
+```js
+testing: {
+  framework: "jest",
+  files: ["**/__tests__/**/*.ts", "**/*.test.ts"],
+}
+```
+
+## Framework Options
+
+### Vitest (Default)
+
+```js
+export default eslintConfig({
+  testing: { framework: "vitest" },
+});
+```
+
+**Includes:**
+
+- ✅ Vitest-specific rules and globals
+- ✅ Test assertion best practices
+- ✅ Hook usage validation
+
+### Jest
+
+```js
+export default eslintConfig({
+  testing: { framework: "jest" },
+});
+```
+
+**Includes:**
+
+- ✅ Jest-specific rules and globals
+- ✅ All Jest best practices
+- ✅ Snapshot testing support
+
+### Bun
+
+```js
+export default eslintConfig({
+  testing: { framework: "bun" },
+});
+```
+
+**Includes:**
+
+- ✅ Bun test runner support
+- ✅ Uses `bun:test` global package
+- ✅ Jest-compatible rules
+
+### Node.js
+
+```js
+export default eslintConfig({
+  testing: { framework: "node" },
+});
+```
+
+**Includes:**
+
+- ✅ Node.js native test runner
+- ✅ Uses `node:test` global package
+- ✅ Jest-compatible rules
+
+## Filename Patterns
+
+Control test file naming conventions:
+
+### .test files (Default)
+
+```js
+testing: {
+  filenamePattern: "test", // Enforces .test.ts, .test.tsx, etc.
+}
+```
+
+**Valid:**
+
+- ✅ `user.test.ts`
+- ✅ `components/button.test.tsx`
+- ❌ `user.spec.ts` (warning)
+
+### .spec files
+
+```js
+testing: {
+  filenamePattern: "spec", // Enforces .spec.ts, .spec.tsx, etc.
+}
+```
+
+**Valid:**
+
+- ✅ `user.spec.ts`
+- ✅ `components/button.spec.tsx`
+- ❌ `user.test.ts` (warning)
+
+## Test Style
+
+Choose between `it` and `test` function names:
+
+### "test" Style (Default)
+
+```js
+testing: {
+  itOrTest: "test",
+}
+```
+
+```js
+// ✅ Good
+test("adds two numbers", () => {
+  expect(add(1, 2)).toBe(3);
+});
+
+// ❌ Bad
+it("adds two numbers", () => {
+  expect(add(1, 2)).toBe(3);
+});
+```
+
+### "it" Style
+
+```js
+testing: {
+  itOrTest: "it",
+}
+```
+
+```js
+// ✅ Good
+it("should add two numbers", () => {
+  expect(add(1, 2)).toBe(3);
+});
+
+// ❌ Bad
+test("should add two numbers", () => {
+  expect(add(1, 2)).toBe(3);
+});
+```
+
+## Formatting Rules
+
+Control padding around test blocks for better readability:
+
+### Enabled (Default)
+
+```js
+testing: {
+  formattingRules: true,
+}
+```
+
+```js
+// ✅ Good - proper spacing
+describe("Calculator", () => {
+  let calculator;
+
+  beforeEach(() => {
+    calculator = new Calculator();
+  });
+
+  afterEach(() => {
+    calculator.reset();
+  });
+
+  describe("addition", () => {
+    test("adds positive numbers", () => {
+      expect(calculator.add(2, 3)).toBe(5);
+    });
+
+    test("adds negative numbers", () => {
+      expect(calculator.add(-2, -3)).toBe(-5);
+    });
+  });
+});
+
+// ❌ Bad - no spacing
+describe("Calculator", () => {
+  let calculator;
+  beforeEach(() => {
+    calculator = new Calculator();
+  });
+  afterEach(() => {
+    calculator.reset();
+  });
+  describe("addition", () => {
+    test("adds positive numbers", () => {
+      expect(calculator.add(2, 3)).toBe(5);
+    });
+    test("adds negative numbers", () => {
+      expect(calculator.add(-2, -3)).toBe(-5);
+    });
+  });
+});
+```
+
+### Disabled
+
+```js
+testing: {
+  formattingRules: false, // No padding requirements
+}
+```
+
+## Key Rules
+
+### Test Structure
+
+- **`vitest/consistent-test-filename`** - Enforces consistent file naming
+- **`vitest/consistent-test-it`** / **`jest/consistent-test-it`** - Enforces `it` or `test`
+- **`vitest/no-identical-title`** / **`jest/no-identical-title`** - Prevents duplicate test names
+
+### Assertions
+
+- **`vitest/expect-expect`** / **`jest/expect-expect`** - Ensures tests have assertions
+- **`vitest/no-conditional-expect`** / **`jest/no-conditional-expect`** - No conditional assertions
+- **`vitest/valid-expect`** / **`jest/valid-expect`** - Validates expect usage
+
+### Best Practices
+
+- **`vitest/prefer-to-be`** / **`jest/prefer-to-be`** - Use `toBe()` for primitives
+- **`vitest/prefer-to-be-truthy`** / **`jest/prefer-to-be-truthy`** - Use `toBeTruthy()`/`toBeFalsy()`
+- **`vitest/no-disabled-tests`** / **`jest/no-disabled-tests`** - Warns on `.skip` and `.only`
+
+### TypeScript Integration
+
+When TypeScript is enabled:
+
+- **`@typescript-eslint/unbound-method`** is disabled (conflicts with test mocking)
+
+## Examples
+
+### Vitest + TypeScript
+
+```js
+export default eslintConfig({
+  typescript: true,
+  testing: {
+    framework: "vitest",
+    filenamePattern: "test",
+    itOrTest: "test",
+  },
+});
+```
+
+```ts
+// user.test.ts
+import { describe, test, expect } from "vitest";
+import { createUser } from "./user";
+
+describe("createUser", () => {
+  test("creates a user with valid data", () => {
+    const user = createUser({ name: "Alice", age: 30 });
+    expect(user).toEqual({ name: "Alice", age: 30 });
+  });
+
+  test("throws on invalid age", () => {
+    expect(() => createUser({ name: "Bob", age: -1 })).toThrow();
+  });
+});
+```
+
+### Jest + Spec Files
+
+```js
+export default eslintConfig({
+  testing: {
+    framework: "jest",
+    filenamePattern: "spec",
+    itOrTest: "it",
+  },
+});
+```
+
+```ts
+// user.spec.ts
+describe("User", () => {
+  it("should create a user", () => {
+    const user = new User("Alice");
+    expect(user.name).toBe("Alice");
+  });
+});
+```
+
+### Bun Tests
+
+```js
+export default eslintConfig({
+  testing: {
+    framework: "bun",
+  },
+});
+```
+
+```ts
+// math.test.ts
+import { test, expect } from "bun:test";
+
+test("adds numbers", () => {
+  expect(1 + 2).toBe(3);
+});
+```
+
+### Node.js Tests
+
+```js
+export default eslintConfig({
+  testing: {
+    framework: "node",
+  },
+});
+```
+
+```ts
+// math.test.ts
+import { test } from "node:test";
+import assert from "node:assert";
+
+test("adds numbers", () => {
+  assert.strictEqual(1 + 2, 3);
+});
+```
+
+## Customization
+
+Override specific testing rules:
+
+```js
+export default eslintConfig({
+  testing: { framework: "vitest" },
+  rules: {
+    // Allow .only for debugging
+    "vitest/no-disabled-tests": "off",
+
+    // Stricter test naming
+    "vitest/consistent-test-filename": "error",
+
+    // Disable padding rules
+    "jest/padding-around-test-blocks": "off",
+  },
+});
+```
+
+## Common Patterns
+
+### Monorepo with Multiple Test Runners
+
+```js
+export default eslintConfig({
+  testing: { framework: "vitest" },
+  overrides: [
+    {
+      files: ["packages/legacy/**/*.test.ts"],
+      rules: {
+        // Use Jest rules for legacy package
+      },
+    },
+  ],
+});
+```
+
+### React Component Testing
+
+```js
+export default eslintConfig({
+  typescript: true,
+  react: true,
+  testing: {
+    framework: "vitest",
+    files: ["**/*.test.{ts,tsx}"],
+  },
+});
+```
+
+## Related Configurations
+
+- [TypeScript](../typescript/README.md) - TypeScript configuration
+- [React](../react/README.md) - React component testing
+- [Base](../base/README.md) - Base ESLint rules
+
+## Learn More
+
+- [Vitest](https://vitest.dev/)
+- [Jest](https://jestjs.io/)
+- [Bun Test](https://bun.sh/docs/cli/test)
+- [Node.js Test Runner](https://nodejs.org/api/test.html)
+- [eslint-plugin-vitest](https://github.com/vitest-dev/eslint-plugin-vitest)
+- [eslint-plugin-jest](https://github.com/jest-community/eslint-plugin-jest)
+- [Main README](../../../README.md)

package/src/eslint/testing/config.ts

@@ -0,0 +1,99 @@
+import jest from "eslint-plugin-jest";
+import vitest from "eslint-plugin-vitest";
+
+import type { EslintConfigObject, EslintRuleConfig } from "../types.js";
+
+import { configNames } from "../constants.js";
+import { getImportRestrictions } from "./get-import-restrictions.js";
+import { jestRules } from "./jest-rules.js";
+import { vitestRules } from "./vitest-rules.js";
+
+export interface TestingConfig {
+  filenamePattern?: "spec" | "test";
+  files?: string[];
+  formattingRules?: boolean;
+  framework?: "bun" | "jest" | "node" | "vitest";
+  /**
+   * Whether to enforce imports from the correct testing framework.
+   * Uses the built-in ESLint `no-restricted-imports` rule.
+   *
+   * @default true
+   */
+  importRestrictions?: boolean;
+  itOrTest?: "it" | "test";
+  typescript?: boolean;
+}
+
+/**
+ * Creates an ESLint configuration object for testing.
+ *
+ * @param options - Configuration options
+ * @param options.files - Files to include in the configuration
+ * @param options.filenamePattern - ".test" or ".spec" filename pattern
+ * @param options.itOrTest - "it" or "test"
+ * @param options.framework - "jest" or "vitest" or "bun" or "node"
+ * @param options.formattingRules - Whether to include formatting rules like padding around blocks
+ * @param options.importRestrictions - Whether to enforce imports from the correct testing framework
+ * @param options.typescript - Whether the user is using TypeScript
+ * @param customRules - Optional object containing custom rules to override or add to the testing configuration.
+ * @returns ESLint configuration object
+ */
+export const testingConfig = (
+  {
+    filenamePattern = "test",
+    files,
+    formattingRules = true,
+    framework = "vitest",
+    importRestrictions = true,
+    itOrTest = "test",
+    typescript = true,
+  }: TestingConfig = {},
+  customRules?: Record<string, EslintRuleConfig>,
+): EslintConfigObject => ({
+  files: files ?? ["**/*.{test,spec}.{ts,tsx,js,jsx}"],
+  languageOptions: {
+    globals:
+      framework === "vitest" ?
+        { ...vitest.environments.env.globals }
+      : jest.environments.globals.globals,
+  },
+  name: configNames.testing,
+  plugins: {
+    jest,
+    vitest,
+  },
+  rules: {
+    ...(typescript ? { "@typescript-eslint/unbound-method": "off" } : {}),
+    // jest doesn't have a file name rule, so we'll use this one for both
+    "vitest/consistent-test-filename": [
+      "warn",
+      {
+        allTestPattern: ".*\\.(test|spec)\\.[tj]sx?$",
+        pattern: `.*\\.${filenamePattern}\\.[tj]sx?$`,
+      },
+    ],
+    ...(framework === "vitest" ? vitestRules(itOrTest) : jestRules(itOrTest)),
+    ...(formattingRules ?
+      {
+        "jest/padding-around-after-all-blocks": "warn",
+        "jest/padding-around-after-each-blocks": "warn",
+        "jest/padding-around-before-all-blocks": "warn",
+        "jest/padding-around-before-each-blocks": "warn",
+        "jest/padding-around-describe-blocks": "warn",
+        "jest/padding-around-expect-groups": "warn",
+        "jest/padding-around-test-blocks": "warn",
+      }
+    : {}),
+    ...(importRestrictions ? getImportRestrictions(framework) : {}),
+    ...(customRules ?? {}),
+  },
+  ...(framework !== "jest" && framework !== "vitest" ?
+    {
+      settings: {
+        jest: {
+          globalPackage: framework === "node" ? "node:test" : "bun:test",
+        },
+      },
+    }
+  : {}),
+});

package/src/eslint/testing/get-import-restrictions.ts

@@ -0,0 +1,70 @@
+import type { EslintRuleConfig } from "../types.js";
+
+const commonTestImports = [
+  "describe",
+  "it",
+  "test",
+  "expect",
+  "beforeAll",
+  "beforeEach",
+  "afterAll",
+  "afterEach",
+  "vi",
+  "mock",
+  "spyOn",
+];
+
+const frameworkConfig = {
+  bun: {
+    allowed: "'bun:test'",
+    restricted: ["vitest", "jest", "@jest/globals", "node:test"],
+  },
+  jest: {
+    allowed: "'jest' or '@jest/globals'",
+    restricted: ["vitest", "bun:test", "node:test"],
+  },
+  node: {
+    allowed: "'node:test'",
+    restricted: ["vitest", "jest", "@jest/globals", "bun:test"],
+  },
+  vitest: {
+    allowed: "'vitest'",
+    restricted: ["jest", "@jest/globals", "bun:test", "node:test"],
+  },
+} as const;
+
+/**
+ * Generates the error message for restricted imports.
+ *
+ * @param allowedFramework - The allowed framework(s) for imports
+ * @returns The formatted error message
+ */
+const getRestrictionMessage = (allowedFramework: string): string =>
+  `This project is setup to use ${allowedFramework} for testing. Importing from other testing frameworks is not allowed. Change this setting in eslint.config.js under testing.framework`;
+
+/**
+ * Returns import restriction rules based on the testing framework.
+ * Prevents importing from the wrong testing framework.
+ *
+ * @param framework - The testing framework being used
+ * @returns ESLint rules object with import restrictions
+ */
+export const getImportRestrictions = (
+  framework: "bun" | "jest" | "node" | "vitest",
+): Record<string, EslintRuleConfig> => {
+  const config = frameworkConfig[framework];
+  const message = getRestrictionMessage(config.allowed);
+
+  return {
+    "no-restricted-imports": [
+      "warn",
+      {
+        paths: config.restricted.map((name) => ({
+          importNames: commonTestImports,
+          message,
+          name,
+        })),
+      },
+    ],
+  };
+};

package/src/eslint/testing/jest-rules.ts

@@ -0,0 +1,47 @@
+import type { EslintRuleConfig } from "../types.js";
+
+type JestRules = Record<`jest/${string}`, EslintRuleConfig>;
+
+/**
+ * Creates an object containing the ESLint rules for jest.
+ *
+ * @param itOrTest - "it" or "test"
+ * @returns An object containing the ESLint rules for jest.
+ */
+export const jestRules = (itOrTest: "it" | "test" = "test"): JestRules => ({
+  "jest/consistent-test-it": [
+    "warn",
+    { fn: itOrTest, withinDescribe: itOrTest },
+  ],
+  "jest/expect-expect": "warn",
+  "jest/no-commented-out-tests": "warn",
+  "jest/no-conditional-expect": "warn",
+  "jest/no-conditional-in-test": "warn",
+  "jest/no-disabled-tests": "warn",
+  "jest/no-duplicate-hooks": "warn",
+  "jest/no-focused-tests": "warn",
+  "jest/no-identical-title": "warn",
+  "jest/no-interpolation-in-snapshots": "warn",
+  "jest/no-large-snapshots": ["warn", { inlineMaxSize: 50, maxSize: 100 }],
+  "jest/no-mocks-import": "warn", // Discourage manually importing from __mocks__
+  "jest/no-standalone-expect": "warn",
+  "jest/no-test-prefixes": "warn", // Prefer .only and .skip over f and x
+  "jest/no-test-return-statement": "warn",
+  "jest/prefer-comparison-matcher": "warn",
+  "jest/prefer-equality-matcher": "warn",
+  "jest/prefer-expect-resolves": "warn",
+  "jest/prefer-hooks-in-order": "warn",
+  "jest/prefer-hooks-on-top": "warn",
+  "jest/prefer-lowercase-title": ["warn", { ignoreTopLevelDescribe: true }],
+  "jest/prefer-snapshot-hint": "warn",
+  "jest/prefer-spy-on": "warn",
+  "jest/prefer-strict-equal": "warn",
+  "jest/prefer-to-be": "warn",
+  "jest/prefer-to-contain": "warn",
+  "jest/prefer-to-have-length": "warn",
+  "jest/require-top-level-describe": "warn",
+  "jest/valid-describe-callback": "warn",
+  "jest/valid-expect": "warn",
+  "jest/valid-expect-in-promise": "warn",
+  "jest/valid-title": "warn",
+});

package/src/eslint/testing/vitest-rules.ts

@@ -0,0 +1,42 @@
+import type { EslintRuleConfig } from "../types.js";
+
+type VitestRules = Record<`vitest/${string}`, EslintRuleConfig>;
+
+/**
+ * Creates an object containing the ESLint rules for vitest.
+ *
+ * @param itOrTest - "it" or "test"
+ * @returns An object containing the ESLint rules for vitest.
+ */
+export const vitestRules = (itOrTest: "it" | "test" = "test"): VitestRules => ({
+  "vitest/consistent-test-it": [
+    "warn",
+    { fn: itOrTest, withinDescribe: itOrTest },
+  ],
+  "vitest/expect-expect": "warn",
+  "vitest/no-commented-out-tests": "warn",
+  "vitest/no-conditional-in-test": "warn",
+  "vitest/no-disabled-tests": "warn",
+  "vitest/no-duplicate-hooks": "warn",
+  "vitest/no-focused-tests": "warn",
+  "vitest/no-identical-title": "warn",
+  "vitest/no-import-node-test": "warn",
+  "vitest/no-interpolation-in-snapshots": "warn", // Avoid dynamic snapshots
+  "vitest/no-large-snapshots": ["warn", { inlineMaxSize: 50, maxSize: 100 }], // Keep snapshots manageable
+  "vitest/no-standalone-expect": "warn",
+  "vitest/no-test-return-statement": "warn", // Tests shouldn't return values
+  "vitest/prefer-comparison-matcher": "warn", // Use comparison matchers
+  "vitest/prefer-equality-matcher": "warn", // Use equality matchers
+  "vitest/prefer-hooks-in-order": "warn", // Keep hooks in a predictable order
+  "vitest/prefer-hooks-on-top": "warn", // Keep hooks organized
+  "vitest/prefer-lowercase-title": ["warn", { ignoreTopLevelDescribe: true }], // Consistent casing
+  "vitest/prefer-strict-equal": "warn", // Prefer .toStrictEqual() over .toEqual()
+  "vitest/prefer-to-be": "warn", // Use .toBe() for primitives
+  "vitest/prefer-to-contain": "warn", // Use .toContain() for array/string includes
+  "vitest/prefer-to-have-length": "warn", // Use .toHaveLength() for checking length
+  "vitest/require-local-test-context-for-concurrent-snapshots": "warn",
+  "vitest/require-top-level-describe": "warn", // Group tests in describe blocks
+  "vitest/valid-describe-callback": "warn",
+  "vitest/valid-expect": "warn",
+  "vitest/valid-title": "warn",
+});