js-style-kit 0.6.1 → 0.7.0

package/src/eslint/turbo/README.md

@@ -0,0 +1,380 @@
+# Turbo Configuration
+
+ESLint rules for Turborepo monorepos to catch common configuration issues.
+
+[← Back to main README](../../../README.md)
+
+## Overview
+
+Turbo configuration is **disabled by default** and provides:
+
+- Environment variable validation
+- Turborepo configuration best practices
+- Monorepo-specific linting
+
+## Quick Start
+
+```js
+import { eslintConfig } from "js-style-kit";
+
+export default eslintConfig({
+  turbo: true, // Enable Turborepo rules
+});
+```
+
+## Key Features
+
+### Environment Variable Declaration
+
+Ensures all environment variables used in your code are properly declared in Turborepo configuration:
+
+```ts
+// turbo.json
+{
+  "tasks": {
+    "build": {
+      "env": ["NODE_ENV", "API_URL"]
+    }
+  }
+}
+```
+
+```ts
+// ✅ Good - declared in turbo.json
+const apiUrl = process.env.API_URL;
+const nodeEnv = process.env.NODE_ENV;
+
+// ❌ Bad - not declared in turbo.json
+const secretKey = process.env.SECRET_KEY; // Warning!
+```
+
+**Rule:**
+
+- `turbo/no-undeclared-env-vars` - Ensures env vars are declared in `turbo.json`
+
+**Why this matters:**
+
+- Turborepo needs to know about env vars for proper caching
+- Undeclared env vars can cause cache invalidation issues
+- Makes dependencies explicit and trackable
+
+## How It Works
+
+The rule checks your `turbo.json` configuration and validates that any environment variables accessed in your code are listed in the appropriate task's `env` array.
+
+### Project-Level Configuration
+
+```json
+// turbo.json
+{
+  "tasks": {
+    "build": {
+      "env": [
+        "NODE_ENV",
+        "API_URL",
+        "NEXT_PUBLIC_*" // Wildcard pattern
+      ]
+    },
+    "dev": {
+      "cache": false,
+      "env": ["NODE_ENV"]
+    }
+  }
+}
+```
+
+### Global Environment Variables
+
+```json
+// turbo.json
+{
+  "globalEnv": ["CI", "VERCEL"],
+  "tasks": {
+    "build": {
+      "env": ["API_URL"]
+    }
+  }
+}
+```
+
+## Examples
+
+### Valid Usage
+
+```ts
+// turbo.json has: { "tasks": { "build": { "env": ["API_URL", "DB_HOST"] } } }
+
+// ✅ Good - all declared
+export const config = {
+  apiUrl: process.env.API_URL,
+  dbHost: process.env.DB_HOST,
+};
+
+// ✅ Good - using wildcard pattern
+// turbo.json has: { "env": ["NEXT_PUBLIC_*"] }
+const publicKey = process.env.NEXT_PUBLIC_API_KEY;
+```
+
+### Invalid Usage
+
+```ts
+// turbo.json has: { "tasks": { "build": { "env": ["API_URL"] } } }
+
+// ❌ Bad - SECRET_KEY not declared
+const config = {
+  apiUrl: process.env.API_URL,
+  secret: process.env.SECRET_KEY, // Warning!
+};
+```
+
+### Fixing the Issue
+
+Add missing env vars to `turbo.json`:
+
+```json
+{
+  "tasks": {
+    "build": {
+      "env": ["API_URL", "SECRET_KEY"]
+    }
+  }
+}
+```
+
+## Wildcard Patterns
+
+Turborepo supports wildcard patterns for environment variables:
+
+```json
+{
+  "tasks": {
+    "build": {
+      "env": [
+        "NEXT_PUBLIC_*", // Matches NEXT_PUBLIC_API_URL, etc.
+        "VITE_*", // Matches VITE_API_URL, etc.
+        "REACT_APP_*" // Matches REACT_APP_VERSION, etc.
+      ]
+    }
+  }
+}
+```
+
+```ts
+// ✅ All valid with wildcard patterns above
+const apiUrl = process.env.NEXT_PUBLIC_API_URL;
+const appVersion = process.env.REACT_APP_VERSION;
+const viteMode = process.env.VITE_MODE;
+```
+
+## Common Patterns
+
+### Next.js Monorepo
+
+```json
+// turbo.json
+{
+  "globalEnv": ["CI", "NODE_ENV"],
+  "tasks": {
+    "build": {
+      "env": ["NEXT_PUBLIC_*", "DATABASE_URL", "API_SECRET"],
+      "outputs": [".next/**", "!.next/cache/**"]
+    },
+    "dev": {
+      "cache": false
+    }
+  }
+}
+```
+
+### Multi-Framework Monorepo
+
+```json
+// turbo.json
+{
+  "tasks": {
+    "build": {
+      "env": [
+        "NODE_ENV",
+        "NEXT_PUBLIC_*", // Next.js apps
+        "VITE_*", // Vite apps
+        "REACT_APP_*" // CRA apps
+      ]
+    }
+  }
+}
+```
+
+### Backend Services
+
+```json
+// turbo.json
+{
+  "tasks": {
+    "build": {
+      "env": ["DATABASE_URL", "REDIS_URL", "AWS_*", "STRIPE_SECRET_KEY"]
+    },
+    "test": {
+      "env": ["DATABASE_URL", "TEST_DATABASE_URL"]
+    }
+  }
+}
+```
+
+## Customization
+
+### Disable for Specific Files
+
+```js
+export default eslintConfig({
+  turbo: true,
+  overrides: [
+    {
+      files: ["scripts/**/*.ts"],
+      rules: {
+        // Scripts might use env vars not in turbo.json
+        "turbo/no-undeclared-env-vars": "off",
+      },
+    },
+  ],
+});
+```
+
+### Error Instead of Warning
+
+```js
+export default eslintConfig({
+  turbo: true,
+  rules: {
+    // Make undeclared env vars an error
+    "turbo/no-undeclared-env-vars": "error",
+  },
+});
+```
+
+### Disable Completely
+
+```js
+export default eslintConfig({
+  turbo: true,
+  rules: {
+    "turbo/no-undeclared-env-vars": "off",
+  },
+});
+```
+
+## Monorepo Structure
+
+Typical monorepo using Turborepo:
+
+```
+my-monorepo/
+├── turbo.json              # Turbo configuration
+├── package.json
+├── packages/
+│   ├── web/               # Next.js app
+│   │   └── src/
+│   ├── api/               # API service
+│   │   └── src/
+│   └── shared/            # Shared utilities
+│       └── src/
+└── apps/
+    └── mobile/            # React Native app
+        └── src/
+```
+
+Each package can use environment variables, but they must be declared in the root `turbo.json` or task-specific configuration.
+
+## Environment Variables Best Practices
+
+### 1. Declare All Variables
+
+Always declare environment variables in `turbo.json` for proper cache invalidation:
+
+```json
+{
+  "tasks": {
+    "build": {
+      "env": ["ALL", "VARS", "HERE"]
+    }
+  }
+}
+```
+
+### 2. Use Wildcards for Prefixes
+
+For public/framework-specific variables:
+
+```json
+{
+  "tasks": {
+    "build": {
+      "env": ["NEXT_PUBLIC_*", "VITE_*"]
+    }
+  }
+}
+```
+
+### 3. Separate by Task
+
+Different tasks can have different env vars:
+
+```json
+{
+  "tasks": {
+    "build": {
+      "env": ["API_URL", "BUILD_ID"]
+    },
+    "test": {
+      "env": ["TEST_DATABASE_URL"]
+    }
+  }
+}
+```
+
+### 4. Use Global Env for CI
+
+Common variables used everywhere:
+
+```json
+{
+  "globalEnv": ["CI", "NODE_ENV", "VERCEL"],
+  "tasks": {
+    /* ... */
+  }
+}
+```
+
+## Troubleshooting
+
+### Rule not working
+
+- Ensure `turbo.json` exists in your project root
+- Check that the env var is being accessed as `process.env.VAR_NAME`
+- Verify the task name matches your `turbo.json` tasks
+
+### Too many warnings
+
+- Use wildcard patterns for common prefixes
+- Add frequently-used vars to `globalEnv`
+- Consider disabling for certain files (scripts, config)
+
+### False positives
+
+- Dynamic env var access might not be detected correctly:
+
+```ts
+// Might not be caught
+const key = process.env[`DYNAMIC_${name}`];
+```
+
+## Related Configurations
+
+- [Base](../base/README.md) - Base ESLint rules
+- [TypeScript](../typescript/README.md) - TypeScript configuration
+
+## Learn More
+
+- [eslint-plugin-turbo](https://github.com/vercel/turbo/tree/main/packages/eslint-plugin-turbo)
+- [Turborepo Documentation](https://turbo.build/repo/docs)
+- [Turborepo Environment Variables](https://turbo.build/repo/docs/core-concepts/caching#environment-variables)
+- [Main README](../../../README.md)

package/src/eslint/turbo/config.ts

@@ -0,0 +1,26 @@
+import turbo from "eslint-plugin-turbo";
+
+import type { EslintConfigObject, EslintRuleConfig } from "../types.js";
+import type { TurboRules } from "./types.js";
+
+import { configNames } from "../constants.js";
+
+/**
+ * Creates an ESLint configuration for Turbo.
+ *
+ * @param customRules - Optional custom rules to merge with the default Turbo rules.
+ * @returns ESLint configuration object for Turbo.
+ */
+export const turboConfig = (
+  customRules?: Record<string, EslintRuleConfig>,
+): EslintConfigObject => ({
+  name: configNames.turbo,
+  plugins: {
+    turbo,
+  },
+  rules:
+    customRules ??
+    ({
+      "turbo/no-undeclared-env-vars": "warn",
+    } satisfies TurboRules),
+});

package/src/eslint/turbo/types.ts

@@ -0,0 +1,7 @@
+import type { EslintRuleConfig } from "../types.js";
+
+export interface TurboRules {
+  "turbo/no-undeclared-env-vars": EslintRuleConfig<{
+    allowList?: string[];
+  }>;
+}

package/src/eslint/types.ts

@@ -0,0 +1,29 @@
+import type { Linter } from "eslint";
+
+import type { ConfigName } from "./constants.js";
+
+export type EslintSeverity = 0 | 1 | 2 | "error" | "off" | "warn";
+
+export type EslintRuleConfig<
+  TOptions = Record<string, unknown>,
+  TOptions2 = Record<string, unknown>,
+> =
+  | [EslintSeverity, string | TOptions | undefined]
+  | [EslintSeverity, string | undefined, TOptions2 | undefined]
+  | [EslintSeverity, TOptions | undefined, TOptions2 | undefined]
+  | [EslintSeverity]
+  | EslintSeverity;
+
+export interface EslintConfigObject<
+  Rules extends Linter.RulesRecord = Linter.RulesRecord,
+> extends Linter.Config<Rules> {
+  name: ConfigName;
+}
+
+export type FilenameCase =
+  | "camelCase"
+  | "kebabCase"
+  | "pascalCase"
+  | "snakeCase";
+
+export type FunctionStyle = "arrow" | "declaration" | "expression";

package/src/eslint/typescript/README.md

@@ -0,0 +1,229 @@
+# TypeScript Configuration
+
+Comprehensive TypeScript support with type-aware linting rules from `@typescript-eslint`. The configuration strikes a balance between strict type safety and practical development.
+
+[← Back to main README](../../../README.md)
+
+## Overview
+
+TypeScript support is **enabled by default** and provides:
+
+- Type-aware linting rules
+- Consistent TypeScript patterns
+- Import/export type safety
+- Modern TypeScript best practices
+
+## Configuration
+
+```js
+import { eslintConfig } from "js-style-kit";
+
+export default eslintConfig({
+  typescript: true, // Default - automatic project detection
+});
+```
+
+### Options
+
+#### Automatic Detection (Recommended)
+
+```js
+typescript: true; // Automatically finds and uses your tsconfig.json
+```
+
+#### Specify Path
+
+```js
+typescript: "./tsconfig.eslint.json"; // Use specific tsconfig file
+```
+
+#### Disable TypeScript Rules
+
+```js
+typescript: false; // Turn off TypeScript linting
+```
+
+## How It Works
+
+When TypeScript is enabled:
+
+1. **Automatic project detection** - Finds your `tsconfig.json` automatically
+2. **Type-aware linting** - Uses TypeScript's type information for advanced checks
+3. **JavaScript compatibility** - Type-checking disabled for `.js` files
+4. **Base rule overrides** - Replaces ESLint rules with TypeScript equivalents (e.g., `no-unused-vars` → `@typescript-eslint/no-unused-vars`)
+
+## Key Rule Categories
+
+### Type Safety
+
+**Strict Type Checking**
+
+- `no-explicit-any` - Warn when using `any` type
+- `no-unsafe-*` - Prevent unsafe type operations
+- `no-unnecessary-type-assertion` - Remove redundant type assertions
+- `no-unnecessary-condition` - Detect always-true/false conditions
+- `strict-boolean-expressions` - Require boolean types in conditions
+
+**Type Inference**
+
+- `no-inferrable-types` - Remove unnecessary type annotations
+- `prefer-as-const` - Use `as const` for literal types
+- `consistent-type-definitions` - Prefer `interface` or `type` consistently
+
+### Modern TypeScript
+
+**Import/Export**
+
+- `consistent-type-imports` - Use `import type` for types (inline style)
+- `consistent-type-exports` - Use `export type` for types
+- `no-import-type-side-effects` - Prevent import type side effects
+
+```ts
+// ✅ Good - inline type imports
+import { type User, getUser } from "./api";
+
+// ❌ Bad - separate type import
+import type { User } from "./api";
+import { getUser } from "./api";
+```
+
+**Null Safety**
+
+- `prefer-nullish-coalescing` - Use `??` over `||` for null checks
+- `prefer-optional-chain` - Use `?.` for safe property access
+- `no-non-null-assertion` - Warn on `!` non-null assertions (subjective in favor of casting)
+
+**Modern Syntax**
+
+- `prefer-for-of` - Prefer `for...of` over traditional `for` loops
+- `prefer-includes` - Use `.includes()` instead of `.indexOf()`
+- `prefer-string-starts-ends-with` - Use `.startsWith()` and `.endsWith()`
+
+### Code Quality
+
+**Error Prevention**
+
+- `no-floating-promises` - Require handling Promise returns
+- `await-thenable` - Only await Promise-like values
+- `no-misused-promises` - Prevent Promises in wrong contexts
+- `only-throw-error` - Only throw Error objects
+
+**Best Practices**
+
+- `no-unused-vars` - Detect unused variables (with `_` prefix exception)
+- `no-empty-function` - Warn on empty functions
+- `no-useless-constructor` - Remove unnecessary constructors
+- `array-type` - Consistent array type syntax (defaults to `string[]` instead of `Array<string>`)
+
+### Documentation
+
+**Comment Quality**
+
+- `ban-ts-comment` - Require explanations for `@ts-ignore` & `@ts-expect-error` (min 10 chars)
+- `ban-tslint-comment` - Prevent deprecated TSLint comments
+
+```ts
+// ❌ Bad - no explanation
+// @ts-ignore
+const x = dangerous();
+
+// ✅ Good - explains why
+// @ts-expect-error - legacy API doesn't have types
+const x = dangerous();
+```
+
+## TypeScript + React
+
+When both TypeScript and React are enabled, additional rules apply:
+
+```js
+import { eslintConfig } from "js-style-kit";
+
+export default eslintConfig({
+  typescript: "./tsconfig.json",
+  react: true,
+});
+```
+
+React-specific TypeScript rules:
+
+- Type-safe prop definitions
+- React hooks type checking
+- JSX type safety
+
+[→ See React Configuration](../react/README.md)
+
+## Unused Variables
+
+The `no-unused-vars` rule allows `_` prefix for intentionally unused variables:
+
+```ts
+// ✅ Good - underscore prefix indicates intentional
+const [_loading, setLoading] = useState(false);
+const handler = (_event: Event) => {
+  /* ... */
+};
+
+// ❌ Bad - unused without underscore
+const [loading, setLoading] = useState(false);
+```
+
+## Customization
+
+Override specific TypeScript rules:
+
+```js
+import { eslintConfig } from "js-style-kit";
+
+export default eslintConfig({
+  typescript: true,
+  rules: {
+    // Allow any type in certain cases
+    "@typescript-eslint/no-explicit-any": "off",
+
+    // Enforce non-null assertions when you know better than TS
+    "@typescript-eslint/no-non-null-assertion": "off",
+
+    // Stricter unused vars (no underscore escape hatch)
+    "@typescript-eslint/no-unused-vars": [
+      "warn",
+      {
+        argsIgnorePattern: "^_",
+        varsIgnorePattern: "^_",
+        ignoreRestSiblings: true,
+      },
+    ],
+  },
+});
+```
+
+## Troubleshooting
+
+### ESLint can't find tsconfig.json
+
+Use explicit path:
+
+```js
+typescript: "./tsconfig.json";
+```
+
+### Type checking is slow
+
+1. Use `tsconfig.eslint.json` with limited `include` paths
+2. Exclude test files if not needed for linting
+
+```js
+typescript: "./tsconfig.eslint.json";
+```
+
+## Related Configurations
+
+- [Base ESLint](../base/README.md) - Core JavaScript rules
+- [Import Plugin](../import/README.md) - Import/export validation
+- [React](../react/README.md) - React + TypeScript support
+
+## Learn More
+
+- [@typescript-eslint Documentation](https://typescript-eslint.io/)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
+- [Main README](../../../README.md)

package/src/eslint/typescript/config.ts

@@ -0,0 +1,48 @@
+import { defineConfig } from "eslint/config";
+import tseslint, { type Config } from "typescript-eslint";
+
+import type { EslintRuleConfig } from "../types.js";
+
+import { configNames } from "../constants.js";
+import { tseslintRules } from "./rules.js";
+
+/**
+ * Creates a TypeScript ESLint configuration object.
+ *
+ * @param tsconfigPath - Path to the TypeScript configuration file
+ * @param customRules - Optional object containing custom rules to override or add to the TypeScript configuration.
+ * @returns TypeScript ESLint configuration object
+ */
+export const tseslintConfig = (
+  tsconfigPath?: string,
+  customRules?: Record<string, EslintRuleConfig>,
+): Config => {
+  const userCwd = process.cwd();
+
+  return defineConfig(
+    {
+      files: ["**/*.{js,cjs,mjs,ts,jsx,tsx}"],
+      languageOptions: {
+        parser: tseslint.parser,
+        parserOptions: {
+          ...(tsconfigPath ?
+            { project: tsconfigPath, tsconfigRootDir: userCwd }
+          : { projectService: true, tsconfigRootDir: import.meta.dirname }),
+        },
+      },
+      name: configNames.typescript,
+      plugins: {
+        "@typescript-eslint": tseslint.plugin,
+      },
+      rules: {
+        ...tseslintRules,
+        ...(customRules ?? {}),
+      },
+    },
+    {
+      // disable type-aware linting on JS files
+      extends: [tseslint.configs.disableTypeChecked],
+      files: ["**/*.js"],
+    },
+  );
+};