oxlint-config-awesomeness 1.2.0 → 2.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 Opinionated Oxlint config for software houses that want all their apps to feel the same.
 
-**493 rules** across **10 plugins**. Built for full-stack TypeScript monorepos with React, Next.js, Hono, Prisma, and more.
+**430 rules** across **10 plugins**. Built for full-stack TypeScript monorepos with React, Next.js, Hono, Prisma, and more.
 
 ## Installation
 
@@ -15,7 +15,17 @@ npm install -D oxlint-config-awesomeness eslint-plugin-no-only-tests eslint-plug
 
 ## Usage
 
-In your `oxlint.config.ts`:
+This package ships an oxlint config object — installing it does **not** generate a config file. You opt in by importing it from your own `oxlint.config.ts`.
+
+The fastest way is the included scaffolder:
+
+```
+npx oxlint-config-awesomeness init
+```
+
+This creates `oxlint.config.ts` in the current directory with the extends boilerplate already wired up. Pass `--force` to overwrite an existing config.
+
+If you'd rather write the file yourself, here's all it needs to be:
 
 ```ts
 import awesomeness from 'oxlint-config-awesomeness';
@@ -28,6 +38,32 @@ export default defineConfig({
 
 Then run `pnpm oxlint` or `npx oxlint`.
 
+## FAQ
+
+### I installed the package but no `.oxlintrc.json` was created. What did I miss?
+
+Nothing — that's by design. This package is an oxlint config you `import` from a JS/TS config file, not a scaffolder that runs on install (postinstall scaffolders are widely considered hostile to consumers). Run `npx oxlint-config-awesomeness init` to create `oxlint.config.ts`, or write the four-line file yourself per the Usage section above. Once that file exists, oxlint will discover it automatically.
+
+### Can I keep using `.oxlintrc.json` and still consume this package?
+
+No. Oxlint's JSON config format only supports file-path `extends`, not package imports — so you can't extend a JS-shipped config from JSON. Migrating to `oxlint.config.ts` is the supported path; the file is small enough to author by hand if you don't want the scaffolder.
+
+### How do I add per-project overrides?
+
+`defineConfig` merges the `awesomeness` config with anything else you pass. Add overrides alongside `extends`:
+
+```ts
+import awesomeness from 'oxlint-config-awesomeness';
+import { defineConfig } from 'oxlint';
+
+export default defineConfig({
+  extends: [awesomeness],
+  overrides: [
+    { files: ['scripts/**/*.ts'], rules: { 'no-console': 'off' } },
+  ],
+});
+```
+
 ## Philosophy
 
 - **Error, Never Warn.** Warnings are noise. Either it's an issue, or it isn't.
@@ -71,7 +107,28 @@ The config includes smart overrides so strict rules don't create noise in files
 
 Instead of enabling the entire `restriction` category (which includes rules like `no-bitwise`, `no-plusplus`, `capitalized-comments` that cause daily friction), this config cherry-picks the most valuable restriction rules:
 
-`curly`, `default-case`, `eqeqeq`, `grouped-accessor-pairs`, `id-length`, `max-classes-per-file`, `max-depth`, `max-lines`, `max-nested-callbacks`, `max-params`, `no-alert`, `no-caller`, `no-console`, `no-eval`, `no-extend-native`, `no-implicit-coercion`, `no-new-func`, `no-new-wrappers`, `no-object-constructor`, `no-param-reassign`, `no-proto`, `no-return-assign`, `no-script-url`, `no-shadow`, `no-throw-literal`, `no-void`, `prefer-promise-reject-errors`, `prefer-template`
+`curly`, `default-case`, `eqeqeq`, `grouped-accessor-pairs`, `max-classes-per-file`, `max-depth`, `max-lines`, `max-nested-callbacks`, `max-params`, `no-alert`, `no-caller`, `no-console`, `no-eval`, `no-extend-native`, `no-implicit-coercion`, `no-new-func`, `no-new-wrappers`, `no-object-constructor`, `no-param-reassign`, `no-proto`, `no-return-assign`, `no-script-url`, `no-shadow`, `no-throw-literal`, `no-void`, `prefer-promise-reject-errors`, `prefer-template`
+
+## Disabled by Intent
+
+The five categories are enabled at `error`, but a small set of category-included rules are explicitly disabled because they fight modern React, Next.js, and ESM conventions:
+
+| Category of fight | Rules off |
+|-------------------|-----------|
+| **React 17+ JSX transform / composition** | `react/react-in-jsx-scope`, `react/jsx-props-no-spreading`, `react/jsx-max-depth`, `react/no-array-index-key`, `react/jsx-no-useless-fragment`, `react/jsx-no-constructed-context-values` |
+| **Modern ESM (named exports, side-effect imports, namespace imports, `node:` protocol)** | `import/no-named-export`, `import/prefer-default-export`, `import/group-exports`, `import/exports-last`, `import/no-anonymous-default-export`, `import/no-nodejs-modules`, `import/no-unassigned-import`, `import/no-namespace`, `import/max-dependencies`, `import/first`, `import/consistent-type-specifier-style` |
+| **Pedantic style preferences** | `no-magic-numbers`, `no-ternary`, `no-inline-comments`, `capitalized-comments`, `arrow-body-style`, `func-style`, `func-names`, `init-declarations`, `no-inferrable-types`, `prefer-destructuring`, `no-negated-condition`, `no-continue`, `parameter-properties`, `max-statements`, `max-lines-per-function`, `id-length` |
+| **Unicorn overreach** | `unicorn/prefer-global-this`, `unicorn/no-useless-undefined`, `unicorn/no-nested-ternary`, `unicorn/explicit-length-check`, `unicorn/custom-error-definition`, `unicorn/no-zero-fractions`, `unicorn/escape-case`, `unicorn/no-array-callback-reference`, `unicorn/no-array-for-each`, `unicorn/no-array-reduce` |
+| **Promise rules with broken assumptions** | `promise/prefer-await-to-callbacks`, `promise/avoid-new`, `promise/param-names` |
+
+A few of these are particularly worth calling out because they form **contradictory pairs** when both fire on the same code:
+
+- `unicorn/explicit-length-check` ↔ `no-magic-numbers` — the first asks you to write `arr.length === 0`, the second then flags the `0`. No way to satisfy both.
+- `import/no-named-export` ↔ `import/prefer-default-export` — exact opposites; one of them is always going to complain.
+- `import/no-namespace` ↔ canonical patterns from Sentry, Prisma, lodash that recommend namespace imports — the rule doesn't know about library conventions.
+- `unicorn/no-zero-fractions` ↔ float-math code that uses `1.0` for type-clarity intent — the rule has no signal about why the `.0` is there.
+
+If you want any of these back on for your project, add them to your `oxlint.config.ts` overrides.
 
 ## Sorting Rules Disabled
 

package/bin/init.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { copyFileSync, existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+const HELP = `Usage: npx oxlint-config-awesomeness init [--force]
+
+Scaffold oxlint.config.ts in the current directory.
+  -f, --force  Overwrite an existing oxlint.config.ts
+  -h, --help   Show this help
+`;
+
+const { positionals, values } = parseArgs({
+  allowPositionals: true,
+  options: {
+    force: { short: "f", type: "boolean" },
+    help: { short: "h", type: "boolean" },
+  },
+});
+
+const command = positionals[0];
+
+if (values.help || !command) {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+if (command !== "init") {
+  process.stderr.write(`Unknown command: ${command}\n\n${HELP}`);
+  process.exit(1);
+}
+
+const target = resolve("oxlint.config.ts");
+
+if (existsSync(target) && !values.force) {
+  process.stderr.write("oxlint.config.ts already exists. Re-run with --force.\n");
+  process.exit(1);
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+copyFileSync(resolve(here, "template.ts"), target);
+process.stdout.write(`Created ${target}\nNext: npx oxlint\n`);

package/bin/template.ts

@@ -0,0 +1,6 @@
+import awesomeness from "oxlint-config-awesomeness";
+import { defineConfig } from "oxlint";
+
+export default defineConfig({
+  extends: [awesomeness],
+});

package/index.js

@@ -134,6 +134,11 @@ export default defineConfig({
     '@typescript-eslint/consistent-type-definitions': ['error', 'type'],
 
     // Core eslint — custom options
+    'eslint/no-duplicate-imports': ['error',
+      {
+      allowSeparateTypeImports: true,
+      }
+    ],
     'no-warning-comments': [
       'error',
       {
@@ -141,12 +146,13 @@ export default defineConfig({
       },
     ],
 
+    
+
     // Restriction — cherry-picked (not bulk-enabled)
     curly: 'error',
     'default-case': 'error',
     eqeqeq: 'error',
     'grouped-accessor-pairs': 'error',
-    'id-length': ['error', { exceptions: ['_', 'a', 'b', 'i', 'j', 'k', 'x', 'y', 'z'] }],
     'max-classes-per-file': ['error', { max: 1 }],
     'max-depth': ['error', { max: 4 }],
     'max-lines': ['error', { max: 400, skipBlankLines: true, skipComments: true }],
@@ -171,6 +177,62 @@ export default defineConfig({
     'prefer-promise-reject-errors': 'error',
     'prefer-template': 'error',
 
+    // Disabled — incompatible with React 17+ JSX transform and common composition patterns
+    'react/jsx-max-depth': 'off',
+    'react/jsx-no-constructed-context-values': 'off',
+    'react/jsx-no-useless-fragment': 'off',
+    'react/jsx-props-no-spreading': 'off',
+    'react/no-array-index-key': 'off',
+    'react/react-in-jsx-scope': 'off',
+
+    // Disabled — modern ESM uses named exports; side-effect imports (CSS, polyfills, node: protocol) are legitimate; namespace imports are canonical for Sentry, Prisma, etc.
+    'import/consistent-type-specifier-style': 'off',
+    'import/exports-last': 'off',
+    'import/first': 'off',
+    'import/group-exports': 'off',
+    'import/max-dependencies': 'off',
+    'import/no-anonymous-default-export': 'off',
+    'import/no-named-export': 'off',
+    'import/no-namespace': 'off',
+    'import/no-nodejs-modules': 'off',
+    'import/no-unassigned-import': 'off',
+    'import/prefer-default-export': 'off',
+
+    // Disabled — pedantic style preferences that fight day-to-day clarity
+    'arrow-body-style': 'off',
+    'capitalized-comments': 'off',
+    'func-names': 'off',
+    'func-style': 'off',
+    'id-length': 'off',
+    'init-declarations': 'off',
+    'max-lines-per-function': 'off',
+    'max-statements': 'off',
+    'no-continue': 'off',
+    'no-inferrable-types': 'off',
+    'no-inline-comments': 'off',
+    'no-magic-numbers': 'off',
+    'no-negated-condition': 'off',
+    'no-ternary': 'off',
+    'parameter-properties': 'off',
+    'prefer-destructuring': 'off',
+
+    // Disabled — unicorn rules that overreach into legitimate patterns
+    'unicorn/custom-error-definition': 'off',
+    'unicorn/escape-case': 'off',
+    'unicorn/explicit-length-check': 'off',
+    'unicorn/no-array-callback-reference': 'off',
+    'unicorn/no-array-for-each': 'off',
+    'unicorn/no-array-reduce': 'off',
+    'unicorn/no-nested-ternary': 'off',
+    'unicorn/no-useless-undefined': 'off',
+    'unicorn/no-zero-fractions': 'off',
+    'unicorn/prefer-global-this': 'off',
+
+    // Disabled — async/await is preferred but raw Promise constructors and callbacks remain idiomatic in many APIs (event emitters, streams, callback adapters)
+    'promise/avoid-new': 'off',
+    'promise/param-names': 'off',
+    'promise/prefer-await-to-callbacks': 'off',
+
     // Style overrides — handled by perfectionist/oxfmt
     'sort-imports': 'off',
     'sort-keys': 'off',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxlint-config-awesomeness",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Oxlint config with sensible defaults.",
   "keywords": [
     "autofix",
@@ -12,10 +12,15 @@
   "license": "MIT",
   "files": [
     "index.js",
-    "index.d.ts"
+    "index.d.ts",
+    "bin/init.js",
+    "bin/template.ts"
   ],
   "type": "module",
   "main": "index.js",
+  "bin": {
+    "oxlint-config-awesomeness": "./bin/init.js"
+  },
   "scripts": {
     "lint": "oxlint ."
   },