js-style-kit 0.6.1 → 0.7.0

package/src/eslint/index.ts

@@ -0,0 +1,259 @@
+import type { Linter } from "eslint";
+
+import type { EslintRuleConfig, FilenameCase, FunctionStyle } from "./types.js";
+
+import { isObject, isString } from "../utils/is-type.js";
+import { baseEslintConfig } from "./base/config.js";
+import { configNames } from "./constants.js";
+import { convexConfig } from "./convex/config.js";
+import { ignoresConfig } from "./ignores.js";
+import { importConfig } from "./import/config.js";
+import { jsdocConfig } from "./jsdoc/config.js";
+import { nextjsConfig } from "./nextjs/config.js";
+import { perfectionistConfig } from "./perfectionist/config.js";
+import { preferArrowFunctionConfig } from "./prefer-arrow-function/config.js";
+import { processCustomRules } from "./process-custom-rules.js";
+import { queryConfig } from "./query/config.js";
+import { reactRefreshEslintConfig } from "./react-refresh/config.js";
+import { reactEslintConfig } from "./react/config.js";
+import { storybookConfig } from "./storybook/config.js";
+import { testingConfig, type TestingConfig } from "./testing/config.js";
+import { turboConfig } from "./turbo/config.js";
+import { tseslintConfig } from "./typescript/config.js";
+import { unicornConfig } from "./unicorn/config.js";
+
+const defaultTestingConfig: TestingConfig = {
+  filenamePattern: "test",
+  files: ["**/*.{test,spec}.{ts,tsx,js,jsx}"],
+  formattingRules: true,
+  framework: "vitest",
+  itOrTest: "it",
+};
+
+export interface EslintConfigOptions {
+  convex?: boolean;
+  functionStyle?: "off" | FunctionStyle;
+  ignores?: string[];
+  importPlugin?: boolean;
+  jsdoc?:
+    | false
+    | {
+        requireJsdoc?: boolean;
+      };
+  query?: boolean;
+  react?:
+    | boolean
+    | {
+        framework?: "next" | "none" | "react-router" | "remix" | "vite";
+        reactCompiler?: boolean;
+        reactRefresh?: boolean;
+      };
+  rules?: Record<string, EslintRuleConfig>;
+  sorting?: boolean;
+  storybook?: boolean;
+  testing?: false | TestingConfig;
+  turbo?: boolean;
+  typescript?: boolean | string;
+  unicorn?:
+    | boolean
+    | {
+        filenameCase?: FilenameCase;
+      };
+}
+
+/**
+ * Configures ESLint based on provided options.
+ *
+ * @param options - The optional configuration object.
+ * @param options.convex - Whether to include Convex rules.
+ * @param options.functionStyle - The function style to enforce. Defaults to "arrow".
+ * @param options.ignores - Additional paths to ignore. Already excludes `node_modules` and `dist`.
+ * @param options.importPlugin - Whether to include the import plugin. Defaults to true.
+ * @param options.jsdoc - Whether to include JSDoc rules. Set to false to disable, or provide an object to configure.
+ * @param options.query - Whether to include TanStack Query rules.
+ * @param options.react - Whether to include React, React hooks, and React compiler rules.
+ *                        Can specify framework as "next", "none", "react-router", "remix", or "vite" to control related configs:
+ *                        - "next": Includes Next.js config, excludes React Refresh.
+ *                        - "vite" or "none": Includes React Refresh, excludes Next.js.
+ *                        - "remix" or "react-router": Excludes both Next.js and React Refresh (these frameworks handle their own refresh logic).
+ *                        - The reactRefresh property can override this framework-based behavior.
+ * @param options.sorting - Whether to include sorting rules from Perfectionist. Defaults to true.
+ * @param options.storybook - Whether to include Storybook rules. Defaults to false.
+ * @param options.testing - An object with the following properties:
+ *                          - `filenamePattern`: One of "spec" or "test" to determine which filename pattern to use.
+ *                          - `files`: Array of file patterns to include in the configuration.
+ *                          - `framework`: One of "vitest" or "jest" to determine which testing library to use.
+ *                          - `formattingRules`: Whether to include formatting rules like padding around blocks.
+ *                          - `itOrTest`: One of "it" or "test" to determine which test function to use.
+ * @param options.typescript - Whether to include TypeScript rules. Can be a boolean or a string with path to tsconfig.
+ * @param options.turbo - Whether to include Turborepo rules. Defaults to false.
+ * @param options.unicorn - Whether to include Unicorn rules. Defaults to true. Can be an object with filenameCase property.
+ * @param options.rules - This is for rules that you need to alter or turn off.
+ * @param additionalConfigs - Additional ESLint config objects to be merged into the final configuration.
+ * @returns An array of ESLint configuration objects.
+ */
+export const eslintConfig = (
+  {
+    convex = false,
+    functionStyle = "arrow",
+    ignores = [],
+    importPlugin = true,
+    jsdoc = { requireJsdoc: false },
+    query = false,
+    react = false,
+    rules,
+    sorting = true,
+    storybook = false,
+    testing = defaultTestingConfig,
+    turbo = false,
+    typescript = true,
+    unicorn = { filenameCase: "kebabCase" },
+  }: EslintConfigOptions = {},
+  ...additionalConfigs: Linter.Config[]
+): Linter.Config[] => {
+  // Categorize user's custom rules first
+  const categorizedRules = rules === undefined ? {} : processCustomRules(rules);
+
+  const usingNextjs = isObject(react) && react.framework === "next";
+
+  const configs: Linter.Config[] = [
+    ignoresConfig({
+      next: usingNextjs,
+      storybook,
+      userIgnores: ignores,
+    }),
+    baseEslintConfig(
+      functionStyle,
+      Boolean(typescript),
+      categorizedRules[configNames.base],
+    ),
+  ];
+
+  if (jsdoc !== false) {
+    configs.push(
+      jsdocConfig(
+        jsdoc.requireJsdoc ?? false,
+        categorizedRules[configNames.jsdoc],
+      ),
+    );
+  }
+
+  if (typescript) {
+    configs.push(
+      ...(tseslintConfig(
+        isString(typescript) ? typescript : undefined,
+        categorizedRules[configNames.typescript],
+      ) as Linter.Config[]),
+    );
+  }
+
+  if (importPlugin) {
+    configs.push(
+      importConfig(Boolean(typescript), categorizedRules[configNames.import]),
+    );
+  }
+
+  if (react) {
+    const reactOptions = isObject(react) ? react : {};
+
+    // Apply reactRefresh based on framework setting or explicit override
+    const shouldUseReactRefresh =
+      // Explicit setting takes precedence
+      reactOptions.reactRefresh === true ||
+      // Framework-based default (vite/none use reactRefresh by default)
+      ((reactOptions.framework === "vite" ||
+        reactOptions.framework === "none") &&
+        reactOptions.reactRefresh !== false);
+
+    if (shouldUseReactRefresh) {
+      configs.push(
+        reactRefreshEslintConfig(categorizedRules[configNames.reactRefresh]),
+      );
+    }
+
+    configs.push(
+      reactEslintConfig({
+        customRules: categorizedRules[configNames.react],
+        functionStyle,
+        reactCompiler: reactOptions.reactCompiler ?? true,
+        typescript: Boolean(typescript),
+      }),
+    );
+
+    if (usingNextjs) {
+      configs.push(nextjsConfig(categorizedRules[configNames.nextjs]));
+    }
+  }
+
+  if (query) {
+    configs.push(queryConfig(categorizedRules[configNames.query]));
+  }
+
+  if (convex) {
+    configs.push(convexConfig(categorizedRules[configNames.convex]));
+  }
+
+  if (testing !== false) {
+    // Use the provided testing config or the default if testing is true
+    const mergedTestingConfig: TestingConfig =
+      isObject(testing) ?
+        { ...defaultTestingConfig, ...testing }
+      : defaultTestingConfig;
+
+    // Destructure from the merged config
+    const { filenamePattern, files, formattingRules, framework, itOrTest } =
+      mergedTestingConfig;
+
+    configs.push(
+      testingConfig(
+        {
+          filenamePattern,
+          files,
+          formattingRules,
+          framework,
+          itOrTest,
+        },
+        categorizedRules[configNames.testing],
+      ),
+    );
+  }
+
+  if (sorting) {
+    configs.push(
+      perfectionistConfig(categorizedRules[configNames.perfectionist]),
+    );
+  }
+
+  if (unicorn) {
+    const filenameCase = isObject(unicorn) ? unicorn.filenameCase : undefined;
+    configs.push(
+      unicornConfig({
+        customRules: categorizedRules[configNames.unicorn],
+        filenameCase,
+      }),
+    );
+  }
+
+  if (functionStyle === "arrow") {
+    configs.push(
+      preferArrowFunctionConfig(
+        categorizedRules[configNames.preferArrowFunction],
+      ),
+    );
+  }
+
+  if (storybook) {
+    configs.push(...storybookConfig(categorizedRules[configNames.storybook]));
+  }
+
+  if (turbo) {
+    configs.push(turboConfig(categorizedRules[configNames.turbo]));
+  }
+
+  // Add any additional config objects provided by the user
+  if (additionalConfigs.length > 0) {
+    configs.push(...additionalConfigs);
+  }
+
+  return configs;
+};

package/src/eslint/jsdoc/README.md

@@ -0,0 +1,399 @@
+# JSDoc Configuration
+
+JSDoc comment validation and formatting for better code documentation.
+
+[← Back to main README](../../../README.md)
+
+## Overview
+
+JSDoc configuration is **disabled by default** and provides:
+
+- JSDoc comment validation
+- Type and tag checking
+- Parameter and return value documentation
+- Formatting and style consistency
+- TypeScript-aware (disables redundant type rules)
+
+This plugin can be handy for libraries, but it can get annoying, so it's not for everyone. [See my configuration](./rules.ts), and feel free to customize via the `rules` option.
+
+## Quick Start
+
+```js
+import { eslintConfig } from "js-style-kit";
+
+export default eslintConfig({
+  jsdoc: true, // Enable JSDoc validation
+});
+```
+
+## Configuration Options
+
+### Basic Enable
+
+```js
+jsdoc: true, // Validation without requiring JSDoc on all functions
+```
+
+### Require JSDoc
+
+```js
+jsdoc: {
+  requireJsdoc: true, // Enforce JSDoc on functions and classes
+}
+```
+
+## File Scope
+
+JSDoc rules apply to:
+
+- ✅ All `.js`, `.jsx`, `.ts`, `.tsx`, `.cjs`, `.mjs` files
+- ❌ Excluded from `.test` and `.spec` files
+
+## Validation Without Enforcement
+
+By default (`requireJsdoc: false`), JSDoc comments are **validated but not required**:
+
+```ts
+// ✅ Good - no JSDoc required, but valid if present
+export const add = (a: number, b: number) => a + b;
+
+// ✅ Good - JSDoc is validated when present
+/**
+ * Adds two numbers together.
+ *
+ * @param a - First number
+ * @param b - Second number
+ * @returns Sum of the two numbers
+ */
+export const add = (a: number, b: number) => a + b;
+
+// ❌ Bad - invalid JSDoc syntax
+/**
+ * @param c - Wrong parameter name
+ */
+export const add = (a: number, b: number) => a + b;
+```
+
+**Active rules:**
+
+- ✅ Validates JSDoc syntax and formatting
+- ✅ Checks parameter names match function signature
+- ✅ Verifies tag names are valid
+- ❌ Does NOT require JSDoc on all functions
+
+## Require JSDoc Mode
+
+When `requireJsdoc: true`, documentation becomes mandatory:
+
+```ts
+// ❌ Bad - missing JSDoc
+export const add = (a: number, b: number) => a + b;
+
+// ✅ Good - complete JSDoc
+/**
+ * Adds two numbers together.
+ *
+ * @param a - First number
+ * @param b - Second number
+ * @returns Sum of the two numbers
+ */
+export const add = (a: number, b: number) => a + b;
+```
+
+**Requires JSDoc on:**
+
+- Function declarations
+- Function expressions
+- Arrow functions
+- Class declarations
+- Class expressions
+- Method definitions
+
+## TypeScript Integration
+
+When using TypeScript, JSDoc rules automatically adjust:
+
+```ts
+// ✅ Good - TypeScript handles types
+/**
+ * Calculates the total price with tax.
+ *
+ * @param price - Base price
+ * @param taxRate - Tax rate as decimal
+ * @returns Total price including tax
+ */
+export const calculateTotal = (price: number, taxRate: number): number => {
+  return price * (1 + taxRate);
+};
+
+// ❌ Bad - redundant type in JSDoc (TypeScript projects)
+/**
+ * @param {number} price - Base price
+ * @param {number} taxRate - Tax rate
+ * @returns {number} Total
+ */
+export const calculateTotal = (price: number, taxRate: number): number => {
+  return price * (1 + taxRate);
+};
+```
+
+**TypeScript-specific behavior:**
+
+- `jsdoc/no-types` is enabled (prevents redundant `{type}` annotations)
+- `jsdoc/no-undefined-types` is disabled (TypeScript validates types)
+- Type information comes from TypeScript, not JSDoc
+
+## Key Rules
+
+### Syntax Validation
+
+- **`jsdoc/check-alignment`** - Enforces proper JSDoc alignment
+- **`jsdoc/check-tag-names`** - Validates tag names are recognized
+- **`jsdoc/check-types`** - Validates JSDoc types (non-TypeScript)
+- **`jsdoc/valid-types`** - Ensures type syntax is valid
+- **`jsdoc/empty-tags`** - Validates tags that shouldn't have content
+
+### Parameter Documentation
+
+- **`jsdoc/check-param-names`** - Parameter names match function signature
+- **`jsdoc/require-param`** - Requires `@param` tags (when `requireJsdoc: true`)
+- **`jsdoc/require-param-name`** - Ensures `@param` has parameter name
+- **`jsdoc/require-param-description`** - Requires parameter descriptions
+
+### Return Documentation
+
+- **`jsdoc/require-returns`** - Requires `@returns` tag (when `requireJsdoc: true`)
+- **`jsdoc/require-returns-check`** - Validates `@returns` matches return statement
+- **`jsdoc/require-returns-description`** - Requires return value description
+
+### Formatting
+
+- **`jsdoc/multiline-blocks`** - Enforces multiline JSDoc format
+- **`jsdoc/no-multi-asterisks`** - Prevents extra asterisks
+- **`jsdoc/require-asterisk-prefix`** - Requires asterisk on each line
+- **`jsdoc/tag-lines`** - Controls spacing between tags
+
+### Other Rules
+
+- **`jsdoc/check-access`** - Validates `@private`, `@public`, etc.
+- **`jsdoc/check-property-names`** - Validates `@property` tag names
+- **`jsdoc/implements-on-classes`** - Ensures `@implements` on classes only
+- **`jsdoc/no-defaults`** - Prevents documenting default values
+
+## Examples
+
+### Function Documentation
+
+```ts
+/**
+ * Fetches user data from the API.
+ *
+ * @param userId - The unique identifier for the user
+ * @returns Promise resolving to user data
+ * @throws {Error} When the user is not found
+ */
+export const fetchUser = async (userId: string): Promise<User> => {
+  const response = await fetch(`/api/users/${userId}`);
+  if (!response.ok) throw new Error("User not found");
+  return response.json();
+};
+```
+
+### Class Documentation
+
+```ts
+/**
+ * Manages user authentication and sessions.
+ */
+export class AuthService {
+  /**
+   * Authenticates a user with credentials.
+   *
+   * @param username - User's username
+   * @param password - User's password
+   * @returns Authentication token
+   */
+  login(username: string, password: string): string {
+    // Implementation
+  }
+
+  /**
+   * Logs out the current user.
+   */
+  logout(): void {
+    // Implementation
+  }
+}
+```
+
+### Interface Documentation
+
+```ts
+/**
+ * Represents a user in the system.
+ */
+interface User {
+  /** Unique user identifier */
+  id: string;
+
+  /** User's display name */
+  name: string;
+
+  /** User's email address */
+  email: string;
+}
+```
+
+### Destructured Parameters
+
+```ts
+/**
+ * Creates a new user account.
+ *
+ * @param options - User creation options
+ * @param options.name - User's name
+ * @param options.email - User's email
+ * @param options.role - User's role in the system
+ * @returns Created user object
+ */
+export const createUser = ({
+  name,
+  email,
+  role,
+}: {
+  name: string;
+  email: string;
+  role: string;
+}): User => {
+  // Implementation
+};
+```
+
+### Async Functions
+
+```ts
+/**
+ * Processes payment for an order.
+ *
+ * @param orderId - Order identifier
+ * @param amount - Payment amount
+ * @returns Promise resolving to payment confirmation
+ * @throws {PaymentError} When payment processing fails
+ */
+export const processPayment = async (
+  orderId: string,
+  amount: number,
+): Promise<PaymentConfirmation> => {
+  // Implementation
+};
+```
+
+## Tag Formatting
+
+JSDoc enforces consistent tag spacing:
+
+```ts
+// ✅ Good - proper tag formatting
+/**
+ * Description here.
+ *
+ * @param name - Parameter description
+ * @param age - Parameter description
+ * @returns Return description
+ */
+
+// ❌ Bad - extra lines between tags
+/**
+ * Description here.
+ *
+ * @param name - Parameter description
+ *
+ * @param age - Parameter description
+ *
+ * @returns Return description
+ */
+```
+
+**Rules:**
+
+- One blank line between description and first tag
+- No blank lines between `@param` tags
+- Consistent formatting throughout
+
+## Customization
+
+### Require JSDoc on Exports Only
+
+```js
+export default eslintConfig({
+  jsdoc: { requireJsdoc: true },
+  rules: {
+    "jsdoc/require-jsdoc": [
+      "warn",
+      {
+        require: {
+          FunctionDeclaration: true,
+          // Only require JSDoc on exported functions
+          publicOnly: true,
+        },
+      },
+    ],
+  },
+});
+```
+
+### Allow JSDoc Types in TypeScript
+
+```js
+export default eslintConfig({
+  jsdoc: true,
+  rules: {
+    // Allow {type} annotations even in TypeScript
+    "jsdoc/no-types": "off",
+  },
+});
+```
+
+### Disable Description Requirements
+
+```js
+export default eslintConfig({
+  jsdoc: true,
+  rules: {
+    "jsdoc/require-param-description": "off",
+    "jsdoc/require-returns-description": "off",
+  },
+});
+```
+
+## Common Patterns
+
+### Library Development
+
+```js
+export default eslintConfig({
+  typescript: true,
+  jsdoc: { requireJsdoc: true }, // Require docs for public API
+});
+```
+
+### Application Development
+
+```js
+export default eslintConfig({
+  typescript: true,
+  jsdoc: true, // Validate JSDoc but don't require it
+});
+```
+
+## Related Configurations
+
+- [TypeScript](../typescript/README.md) - TypeScript type checking
+- [Base](../base/README.md) - Base ESLint rules
+
+## Learn More
+
+- [eslint-plugin-jsdoc](https://github.com/gajus/eslint-plugin-jsdoc)
+- [JSDoc Official](https://jsdoc.app/)
+- [TypeScript JSDoc Reference](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html)
+- [Main README](../../../README.md)

package/src/eslint/jsdoc/config.ts

@@ -0,0 +1,29 @@
+import jsdoc from "eslint-plugin-jsdoc";
+
+import type { EslintConfigObject, EslintRuleConfig } from "../types.js";
+
+import { configNames } from "../constants.js";
+import { jsdocRules } from "./rules.js";
+
+/**
+ * Generates ESLint configuration for JSDoc comments.
+ *
+ * @param requireJsdoc - Whether to enforce JSDoc comments on functions and classes. Defaults to false.
+ * @param customRules - Optional object containing custom rules to override or add to the JSDoc configuration.
+ * @returns An ESLint configuration object for JSDoc comments.
+ */
+export const jsdocConfig = (
+  requireJsdoc = false,
+  customRules?: Record<string, EslintRuleConfig>,
+): EslintConfigObject => ({
+  files: ["**/*.{js,jsx,ts,tsx,cjs,mjs}"],
+  ignores: ["**/*.{test,spec}.{js,jsx,ts,tsx,cjs,mjs}"],
+  name: configNames.jsdoc,
+  plugins: {
+    jsdoc,
+  },
+  rules: {
+    ...jsdocRules(requireJsdoc),
+    ...(customRules ?? {}),
+  },
+});