js-style-kit 0.6.1 → 0.7.0

package/src/eslint/typescript/rules.ts

@@ -0,0 +1,137 @@
+import type { TypescriptRules } from "./types.js";
+
+export const tseslintRules: TypescriptRules = {
+  "@typescript-eslint/adjacent-overload-signatures": "warn",
+  "@typescript-eslint/array-type": "warn",
+  "@typescript-eslint/await-thenable": "warn",
+  "@typescript-eslint/ban-ts-comment": [
+    "warn",
+    { minimumDescriptionLength: 10 },
+  ],
+  "@typescript-eslint/ban-tslint-comment": "warn",
+  "@typescript-eslint/class-literal-property-style": "warn",
+  "@typescript-eslint/consistent-generic-constructors": "warn",
+  "@typescript-eslint/consistent-indexed-object-style": "warn",
+  "@typescript-eslint/consistent-type-assertions": "warn",
+  "@typescript-eslint/consistent-type-definitions": "warn",
+  "@typescript-eslint/consistent-type-exports": [
+    "warn",
+    { fixMixedExportsWithInlineTypeSpecifier: true },
+  ],
+  "@typescript-eslint/consistent-type-imports": [
+    "warn",
+    {
+      fixStyle: "inline-type-imports",
+      prefer: "type-imports",
+    },
+  ],
+  "@typescript-eslint/dot-notation": "warn",
+  "@typescript-eslint/no-array-constructor": "warn",
+  "@typescript-eslint/no-array-delete": "warn",
+  "@typescript-eslint/no-base-to-string": "warn",
+  "@typescript-eslint/no-confusing-non-null-assertion": "warn",
+  "@typescript-eslint/no-confusing-void-expression": "warn",
+  "@typescript-eslint/no-deprecated": "warn",
+  "@typescript-eslint/no-duplicate-enum-values": "warn",
+  "@typescript-eslint/no-duplicate-type-constituents": "warn",
+  "@typescript-eslint/no-dynamic-delete": "warn",
+  "@typescript-eslint/no-empty-function": "warn",
+  "@typescript-eslint/no-empty-object-type": "warn",
+  "@typescript-eslint/no-explicit-any": "warn",
+  "@typescript-eslint/no-extra-non-null-assertion": "warn",
+  "@typescript-eslint/no-extraneous-class": "warn",
+  "@typescript-eslint/no-floating-promises": "warn",
+  "@typescript-eslint/no-for-in-array": "warn",
+  "@typescript-eslint/no-implied-eval": "warn",
+  "@typescript-eslint/no-import-type-side-effects": "warn",
+  "@typescript-eslint/no-inferrable-types": "warn",
+  "@typescript-eslint/no-invalid-void-type": "warn",
+  "@typescript-eslint/no-meaningless-void-operator": "warn",
+  "@typescript-eslint/no-misused-new": "warn",
+  "@typescript-eslint/no-misused-promises": "warn",
+  "@typescript-eslint/no-mixed-enums": "warn",
+  "@typescript-eslint/no-namespace": "warn",
+  "@typescript-eslint/no-non-null-asserted-nullish-coalescing": "warn",
+  "@typescript-eslint/no-non-null-asserted-optional-chain": "warn",
+  "@typescript-eslint/no-non-null-assertion": "warn",
+  "@typescript-eslint/no-redundant-type-constituents": "warn",
+  "@typescript-eslint/no-require-imports": "warn",
+  "@typescript-eslint/no-this-alias": "warn",
+  "@typescript-eslint/no-unnecessary-boolean-literal-compare": "warn",
+  "@typescript-eslint/no-unnecessary-condition": "warn",
+  "@typescript-eslint/no-unnecessary-template-expression": "warn",
+  "@typescript-eslint/no-unnecessary-type-arguments": "warn",
+  "@typescript-eslint/no-unnecessary-type-assertion": "warn",
+  "@typescript-eslint/no-unnecessary-type-constraint": "warn",
+  "@typescript-eslint/no-unnecessary-type-parameters": "warn",
+  "@typescript-eslint/no-unsafe-declaration-merging": "warn",
+  "@typescript-eslint/no-unsafe-enum-comparison": "warn",
+  "@typescript-eslint/no-unsafe-function-type": "warn",
+  "@typescript-eslint/no-unsafe-unary-minus": "warn",
+  "@typescript-eslint/no-unused-expressions": "warn",
+  "@typescript-eslint/no-unused-vars": [
+    "warn",
+    {
+      args: "after-used",
+      argsIgnorePattern: "^_",
+      ignoreRestSiblings: false,
+      vars: "all",
+      varsIgnorePattern: "^_",
+    },
+  ],
+  "@typescript-eslint/no-useless-constructor": "warn",
+  "@typescript-eslint/no-wrapper-object-types": "warn",
+  // TODO: Investiate non-null vs type-cast rules
+  "@typescript-eslint/non-nullable-type-assertion-style": "off",
+  "@typescript-eslint/only-throw-error": "warn",
+  "@typescript-eslint/prefer-as-const": "warn",
+  "@typescript-eslint/prefer-find": "warn",
+  "@typescript-eslint/prefer-for-of": "warn",
+  "@typescript-eslint/prefer-function-type": "warn",
+  "@typescript-eslint/prefer-includes": "warn",
+  "@typescript-eslint/prefer-literal-enum-member": "warn",
+  "@typescript-eslint/prefer-namespace-keyword": "warn",
+  "@typescript-eslint/prefer-nullish-coalescing": [
+    "warn",
+    {
+      ignorePrimitives: { string: true },
+    },
+  ],
+  "@typescript-eslint/prefer-optional-chain": "warn",
+  "@typescript-eslint/prefer-promise-reject-errors": "warn",
+  "@typescript-eslint/prefer-reduce-type-parameter": "warn",
+  "@typescript-eslint/prefer-regexp-exec": "warn",
+  "@typescript-eslint/prefer-return-this-type": "warn",
+  "@typescript-eslint/prefer-string-starts-ends-with": "warn",
+  "@typescript-eslint/related-getter-setter-pairs": "warn",
+  "@typescript-eslint/require-await": "warn",
+  "@typescript-eslint/restrict-plus-operands": [
+    "warn",
+    {
+      allowAny: false,
+      allowBoolean: false,
+      allowNullish: false,
+      allowNumberAndString: false,
+      allowRegExp: false,
+    },
+  ],
+  "@typescript-eslint/restrict-template-expressions": [
+    "warn",
+    {
+      allow: [{ from: "lib", name: ["Error", "URL", "URLSearchParams"] }],
+      allowAny: true,
+      allowBoolean: true,
+      allowNullish: true,
+      allowNumber: true,
+      allowRegExp: true,
+    },
+  ],
+  "@typescript-eslint/return-await": [
+    "warn",
+    "error-handling-correctness-only",
+  ],
+  "@typescript-eslint/triple-slash-reference": "warn",
+  "@typescript-eslint/unbound-method": "warn",
+  "@typescript-eslint/unified-signatures": "warn",
+  "@typescript-eslint/use-unknown-in-catch-callback-variable": "warn",
+};

package/src/eslint/typescript/types.ts

@@ -0,0 +1,35 @@
+import type { EslintRuleConfig } from "../types.js";
+
+export type TypescriptRules = Record<
+  `@typescript-eslint/${string}`,
+  EslintRuleConfig
+> & {
+  "@typescript-eslint/prefer-nullish-coalescing": EslintRuleConfig<{
+    /** Unless this is set to `true`, the rule will error on every file whose `tsconfig.json` does _not_ have the `strictNullChecks` compiler option (or `strict`) set to `true`. */
+    allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing?: boolean;
+    /** Whether to ignore arguments to the `Boolean` constructor */
+    ignoreBooleanCoercion?: boolean;
+    /** Whether to ignore cases that are located within a conditional test. */
+    ignoreConditionalTests?: boolean;
+    /** Whether to ignore any if statements that could be simplified by using the nullish coalescing operator. */
+    ignoreIfStatements?: boolean;
+    /** Whether to ignore any logical or expressions that are part of a mixed logical expression (with `&&`). */
+    ignoreMixedLogicalExpressions?: boolean;
+    /** Whether to ignore all (`true`) or some (an object with properties) primitive types. */
+    ignorePrimitives?:
+      | true
+      | {
+          [k: string]: unknown;
+          /** Ignore bigint primitive types. */
+          bigint?: boolean;
+          /** Ignore boolean primitive types. */
+          boolean?: boolean;
+          /** Ignore number primitive types. */
+          number?: boolean;
+          /** Ignore string primitive types. */
+          string?: boolean;
+        };
+    /** Whether to ignore any ternary expressions that could be simplified by using the nullish coalescing operator. */
+    ignoreTernaryTests?: boolean;
+  }>;
+};

package/src/eslint/unicorn/README.md

@@ -0,0 +1,497 @@
+# Unicorn Configuration
+
+Modern JavaScript/TypeScript best practices and code quality rules powered by `eslint-plugin-unicorn`.
+
+[← Back to main README](../../../README.md)
+
+## Overview
+
+Unicorn configuration is **enabled by default** and provides:
+
+- File naming conventions (kebab-case)
+- Modern JavaScript best practices
+- Error handling improvements
+- Node.js protocol enforcement
+- String and regex optimizations
+
+## Quick Start
+
+The unicorn configuration is automatically enabled when you use `eslintConfig()`:
+
+```js
+import { eslintConfig } from "js-style-kit";
+
+export default eslintConfig(); // Unicorn rules enabled by default with kebab-case filenames
+```
+
+### Configure Filename Case
+
+You can customize the filename case convention:
+
+```js
+import { eslintConfig } from "js-style-kit";
+
+export default eslintConfig({
+  unicorn: {
+    filenameCase: "camelCase", // "camelCase" | "kebabCase" | "pascalCase" | "snakeCase"
+  },
+});
+```
+
+## Key Features
+
+### File Naming
+
+Enforces consistent filename case conventions. By default, kebab-case is used, which promotes consistency and avoids case-sensitivity issues across different operating systems.
+
+**Available Options:**
+
+- `kebabCase` (default) - `user-service.ts`, `api-client.js`
+- `camelCase` - `userService.ts`, `apiClient.js`
+- `pascalCase` - `UserService.ts`, `ApiClient.js`
+- `snakeCase` - `user_service.ts`, `api_client.js`
+
+```
+✅ Good filenames:
+- user-service.ts
+- api-client.js
+- button-component.tsx
+- use-auth-hook.ts
+- format-date.util.ts
+
+❌ Bad filenames:
+- UserService.ts (PascalCase)
+- apiClient.js (camelCase)
+- Button_Component.tsx (snake_case)
+- useAuthHook.ts (camelCase)
+```
+
+**Rule:**
+
+- `unicorn/filename-case` - Enforces consistent filename case
+
+**Configuration:**
+
+```js
+// Use camelCase for all files
+export default eslintConfig({
+  unicorn: {
+    filenameCase: "camelCase",
+  },
+});
+
+// Use PascalCase for all files
+export default eslintConfig({
+  unicorn: {
+    filenameCase: "pascalCase",
+  },
+});
+```
+
+For more advanced customization (like ignoring specific patterns), you can override the rule directly:
+
+```js
+export default eslintConfig({
+  unicorn: {
+    filenameCase: "kebabCase",
+  },
+  rules: {
+    // Allow PascalCase for React components
+    "unicorn/filename-case": [
+      "warn",
+      {
+        case: "kebabCase",
+        ignore: [
+          "^[A-Z].*\\.tsx$", // Allow PascalCase for .tsx files
+        ],
+      },
+    ],
+  },
+});
+```
+
+### Node.js Protocol
+
+Requires using the `node:` protocol when importing Node.js built-in modules:
+
+```js
+// ✅ Good - node: protocol
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { EventEmitter } from "node:events";
+
+// ❌ Bad - missing node: protocol
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { EventEmitter } from "events";
+```
+
+**Rule:**
+
+- `unicorn/prefer-node-protocol` - Enforces `node:` prefix (auto-fixable)
+
+**Benefits:**
+
+- Makes it clear which modules are built-in
+- Prevents conflicts with npm packages
+- Improves module resolution performance
+
+### Error Handling
+
+Ensures errors have meaningful messages:
+
+```js
+// ✅ Good - descriptive error messages
+throw new Error("Failed to fetch user data");
+throw new TypeError("Expected string, got number");
+
+// ❌ Bad - empty error
+throw new Error();
+throw new TypeError();
+```
+
+**Rules:**
+
+- `unicorn/error-message` - Requires error messages
+- `unicorn/prefer-type-error` - Use `TypeError` for type checking (auto-fixable)
+
+### Better Regex
+
+Optimizes regular expressions:
+
+```js
+// ✅ Good - optimized regex
+const regex = /\d+/;
+const pattern = /[a-z]+/i;
+
+// ❌ Bad - can be optimized
+const regex = /[0-9]+/; // Use \d instead
+const pattern = /[a-zA-Z]+/; // Use /[a-z]+/i instead
+```
+
+**Rule:**
+
+- `unicorn/better-regex` - Suggests regex improvements (auto-fixable)
+
+### Modern JavaScript
+
+Promotes modern language features:
+
+#### String Methods
+
+```js
+// ✅ Good - replaceAll for global replacement
+const text = "hello hello".replaceAll("hello", "hi");
+
+// ❌ Bad - global regex for simple replacement
+const text = "hello hello".replace(/hello/g, "hi");
+```
+
+**Rule:**
+
+- `unicorn/prefer-string-replace-all` - Use `replaceAll()` over global regex (auto-fixable)
+
+#### Loop Improvements
+
+```js
+// ✅ Good - for...of loop
+for (const item of items) {
+  process(item);
+}
+
+// ❌ Bad - traditional for loop for simple iteration
+for (let i = 0; i < items.length; i++) {
+  process(items[i]);
+}
+```
+
+**Rule:**
+
+- `unicorn/no-for-loop` - Prefer for...of over C-style for loops (auto-fixable)
+
+#### Built-in Constructors
+
+```js
+// ✅ Good - using new with constructors
+const map = new Map();
+const set = new Set();
+const date = new Date();
+
+// ❌ Bad - missing new
+const map = Map();
+const set = Set();
+```
+
+**Rule:**
+
+- `unicorn/new-for-builtins` - Enforces `new` for built-ins (auto-fixable)
+
+### Event Listeners
+
+Promotes modern event handling:
+
+```js
+// ✅ Good - addEventListener
+element.addEventListener("click", handler);
+
+// ❌ Bad - on-handler
+element.onclick = handler;
+```
+
+**Rule:**
+
+- `unicorn/prefer-add-event-listener` - Use `addEventListener()` (auto-fixable)
+
+### Switch Case Braces
+
+Enforces consistent brace usage in switch cases:
+
+```js
+// ✅ Good - braces around case
+switch (value) {
+  case "a": {
+    const result = doSomething();
+    return result;
+  }
+  case "b": {
+    return doOther();
+  }
+  default: {
+    return defaultValue;
+  }
+}
+
+// ❌ Bad - missing braces
+switch (value) {
+  case "a":
+    const result = doSomething(); // Variable could leak to other cases
+    return result;
+}
+```
+
+**Rule:**
+
+- `unicorn/switch-case-braces` - Always use braces in case clauses (auto-fixable)
+
+### Text Encoding
+
+Enforces consistent encoding identifier case:
+
+```js
+// ✅ Good - lowercase encoding
+const text = new TextDecoder("utf-8").decode(buffer);
+const encoded = new TextEncoder().encode("text");
+
+// ❌ Bad - inconsistent case
+const text = new TextDecoder("UTF-8").decode(buffer);
+```
+
+**Rule:**
+
+- `unicorn/text-encoding-identifier-case` - Lowercase encoding identifiers (auto-fixable)
+
+### Console Improvements
+
+Prevents extra spaces in console output:
+
+```js
+// ✅ Good
+console.log("User:", user);
+console.error("Error:", error);
+
+// ❌ Bad - extra spaces
+console.log("User: ", user);
+console.error("Error: ", error);
+```
+
+**Rule:**
+
+- `unicorn/no-console-spaces` - No spaces before arguments (auto-fixable)
+
+## Complete Example
+
+```ts
+// ✅ user-service.ts - follows all Unicorn rules
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export class UserService {
+  async loadUser(userId: string): Promise<User> {
+    if (typeof userId !== "string") {
+      throw new TypeError("userId must be a string");
+    }
+
+    const filePath = join("data", "users", `${userId}.json`);
+
+    try {
+      const content = await readFile(filePath, "utf-8");
+      return JSON.parse(content);
+    } catch (error) {
+      throw new Error(`Failed to load user ${userId}`);
+    }
+  }
+
+  processUsers(users: User[]): void {
+    for (const user of users) {
+      console.log("Processing:", user.name);
+
+      switch (user.status) {
+        case "active": {
+          this.activateUser(user);
+          break;
+        }
+        case "inactive": {
+          this.deactivateUser(user);
+          break;
+        }
+        default: {
+          throw new Error(`Unknown status: ${user.status}`);
+        }
+      }
+    }
+  }
+}
+```
+
+## Customization
+
+### Change Filename Convention
+
+```js
+// Use camelCase instead of kebab-case
+export default eslintConfig({
+  unicorn: {
+    filenameCase: "camelCase",
+  },
+});
+
+// Use PascalCase for component files
+export default eslintConfig({
+  unicorn: {
+    filenameCase: "pascalCase",
+  },
+});
+```
+
+### Override Filename Convention with Patterns
+
+```js
+export default eslintConfig({
+  unicorn: {
+    filenameCase: "kebabCase",
+  },
+  rules: {
+    // Allow PascalCase for React components
+    "unicorn/filename-case": [
+      "warn",
+      {
+        case: "kebabCase",
+        ignore: [
+          "^[A-Z].*\\.tsx$", // Allow PascalCase for .tsx files
+        ],
+      },
+    ],
+  },
+});
+```
+
+### Disable Specific Rules
+
+```js
+export default eslintConfig({
+  rules: {
+    // Allow traditional for loops
+    "unicorn/no-for-loop": "off",
+
+    // Allow onclick handlers
+    "unicorn/prefer-add-event-listener": "off",
+  },
+});
+```
+
+### File-Specific Overrides
+
+```js
+export default eslintConfig({
+  overrides: [
+    {
+      files: ["scripts/**/*.js"],
+      rules: {
+        // Allow any filename case in scripts
+        "unicorn/filename-case": "off",
+      },
+    },
+  ],
+});
+```
+
+## Common Patterns
+
+### Node.js Project
+
+```ts
+// server.ts
+import { createServer } from "node:http";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const server = createServer(async (req, res) => {
+  try {
+    const file = await readFile(join("public", "index.html"));
+    res.writeHead(200, { "Content-Type": "text/html" });
+    res.end(file);
+  } catch (error) {
+    throw new Error("Failed to read file");
+  }
+});
+```
+
+### Frontend Project
+
+```ts
+// api-client.ts
+export class ApiClient {
+  async fetchUsers(): Promise<User[]> {
+    const response = await fetch("/api/users");
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch users: ${response.status}`);
+    }
+
+    return response.json();
+  }
+}
+```
+
+## Benefits
+
+### Code Quality
+
+- Catches common mistakes
+- Promotes modern JavaScript
+- Consistent patterns
+
+### Maintainability
+
+- Standard file naming
+- Clear error messages
+- Readable code patterns
+
+### Performance
+
+- Optimized regex
+- Better module resolution
+- Efficient iterations
+
+## Related Configurations
+
+- [Base](../base/README.md) - Base ESLint rules
+- [TypeScript](../typescript/README.md) - TypeScript configuration
+- [Import](../import/README.md) - Import validation
+
+## Learn More
+
+- [eslint-plugin-unicorn](https://github.com/sindresorhus/eslint-plugin-unicorn)
+- [Node.js Module System](https://nodejs.org/api/esm.html)
+- [Modern JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
+- [Main README](../../../README.md)

package/src/eslint/unicorn/config.ts

@@ -0,0 +1,36 @@
+import unicorn from "eslint-plugin-unicorn";
+
+import type {
+  EslintConfigObject,
+  EslintRuleConfig,
+  FilenameCase,
+} from "../types.js";
+
+import { configNames } from "../constants.js";
+import { rules } from "./rules.js";
+
+/**
+ * ESLint configuration for unicorn plugin.
+ * This plugin provides a set of rules to enforce consistent code style and catch common errors.
+ *
+ * @param options - Configuration options for Unicorn.
+ * @param options.customRules - Optional custom rules to merge with the default Unicorn rules.
+ * @param options.filenameCase - Optional filename case to enforce. Defaults to "kebabCase".
+ * @returns ESLint configuration object for Unicorn.
+ */
+export const unicornConfig = ({
+  customRules,
+  filenameCase = "kebabCase",
+}: {
+  customRules?: Record<string, EslintRuleConfig>;
+  filenameCase?: FilenameCase;
+}): EslintConfigObject => ({
+  name: configNames.unicorn,
+  plugins: {
+    unicorn,
+  },
+  rules: {
+    ...rules(filenameCase),
+    ...(customRules ?? {}),
+  },
+});