@howells/lint 0.1.8 → 0.2.1

package/CONTEXT.md

@@ -0,0 +1,8 @@
+# Context Glossary
+
+## Terms
+
+### Oxlint/Oxfmt lane
+
+The project setup path that chooses Oxlint for linting and Oxfmt for formatting instead of Biome.
+

package/MIGRATIONS.md

@@ -1,35 +1,51 @@
 # Adoption Notes
 
-Use these notes when replacing an existing ESLint, Prettier, Oxc, or ad hoc Biome setup with `@howells/lint`.
+Use these notes when replacing an existing ESLint, Prettier, Oxlint/Oxfmt, or ad hoc Biome setup with `@howells/lint`.
 
 ## Primary rule
 
-Do not migrate an old local lint philosophy into a new local Biome override.
+Do not migrate an old local lint philosophy into a new local override.
 
 Pick the closest shared preset first. Only add local config after you can explain why the repo is a real exception.
 
-## Preset selection
+## Lane and preset selection
+
+Choose one lane first, then choose the closest preset in that lane.
+
+Biome lane:
 
 - Node or non-React TypeScript: `@howells/lint/biome/core`
 - React package or app without Next.js specifics: `@howells/lint/biome/react`
 - Next.js app: `@howells/lint/biome/next`
 
+Oxlint/Oxfmt lane:
+
+- Node or non-React TypeScript: `@howells/lint/oxlint/core`
+- React package or app without Next.js specifics: `@howells/lint/oxlint/react`
+- Next.js app: `@howells/lint/oxlint/next`
+
 If none of these fit cleanly, the likely answer is a new shared preset here, not a repo-specific fork.
 
 ## Migration steps
 
 1. Add `@howells/lint` as a dev dependency.
 2. Pin Node with `.node-version` set to `22.18.0` and `engines.node` set to `>=22.18.0`.
-3. Replace `eslint`, `next lint`, `prettier`, or direct `biome` scripts with `howells-lint` and `howells-format`.
-4. Replace the project `biome.json` or `biome.jsonc` with a minimal file that only extends one shared preset.
-5. Remove direct `eslint`, `eslint-config-*`, `eslint-plugin-*`, `prettier`, `@biomejs/biome`, `oxlint`, `oxfmt`, `oxlint-tsgolint`, and `ultracite` dependencies once the project is green.
+3. Replace `eslint`, `next lint`, `prettier`, direct `biome`, or direct Oxlint/Oxfmt scripts with the chosen lane's package binaries.
+4. Replace local lint config with a minimal config that only extends one shared preset from the chosen lane.
+5. Remove direct `eslint`, `eslint-config-*`, `eslint-plugin-*`, `prettier`, `@biomejs/biome`, `oxlint`, `oxfmt`, `oxlint-tsgolint`, `ultracite`, `oxlint-plugin-react-doctor`, and `oxc-parser` dependencies once the project is green.
 
 ## Oxlint/Oxfmt opt-in
 
-Biome remains the default migration target. Use Oxlint/Oxfmt only for projects that deliberately choose the Oxc lane.
+Biome remains the default migration target. Use Oxlint/Oxfmt only for projects that deliberately choose the Oxlint/Oxfmt lane. React and Next.js projects with real state, effects, architecture, or framework-boundary concerns are good candidates for that lane.
 
 For an Oxlint/Oxfmt project, add `oxlint.config.ts` and `oxfmt.config.ts` using the exports from `@howells/lint`, then use:
 
+- `@howells/lint/oxlint/core` for Node or non-React TypeScript
+- `@howells/lint/oxlint/react` for React (Ultracite React + React Doctor)
+- `@howells/lint/oxlint/next` for Next.js (react preset + Next.js rules)
+
+Each React or Next preset is self-contained. Extend only the closest preset — do not stack `core`, `react`, and `next` together.
+
 ```json
 {
   "scripts": {
@@ -43,7 +59,9 @@ Do not run Biome and Oxlint/Oxfmt together indefinitely. If both are present dur
 
 ## Keep local config thin
 
-The normal local config should look like this:
+The normal local config should only extend the chosen lane's closest preset.
+
+Biome lane:
 
 ```json
 {
@@ -51,6 +69,17 @@ The normal local config should look like this:
 }
 ```
 
+Oxlint/Oxfmt lane:
+
+```ts
+import { defineConfig } from "oxlint";
+import next from "@howells/lint/oxlint/next";
+
+export default defineConfig({
+  extends: [next],
+});
+```
+
 Acceptable local additions:
 
 - repo-specific file includes or force-ignores for generated files that are unique to one project
@@ -59,7 +88,7 @@ Acceptable local additions:
 
 Avoid:
 
-- copying old ESLint rule customizations into Biome
+- copying old ESLint rule customizations into the new lane
 - broad `linter.rules` sections to preserve team habit
 - local wrapper configs like `base.json` or `library.json`
 - repeating the same override across multiple repos
@@ -77,7 +106,9 @@ Do not normalize repeated local exceptions.
 
 ## Prefer scope in scripts
 
-If one repo only needs a narrower target, prefer script-level scope:
+If one repo only needs a narrower target, prefer script-level scope.
+
+Biome lane:
 
 ```json
 {
@@ -88,4 +119,15 @@ If one repo only needs a narrower target, prefer script-level scope:
 }
 ```
 
+Oxlint/Oxfmt lane:
+
+```json
+{
+  "scripts": {
+    "lint": "howells-ox-check apps/web packages/ui",
+    "lint:fix": "howells-ox-fix apps/web packages/ui"
+  }
+}
+```
+
 That is usually better than teaching the config about the repo layout.

package/README.md

@@ -1,6 +1,6 @@
 # `@howells/lint`
 
-Pinned Biome, Oxlint/Oxfmt, and Ultracite presets for Howells projects.
+Pinned Biome, Oxlint/Oxfmt, Ultracite, and React Doctor presets for Howells projects.
 
 The goal is not to invent a second lint philosophy. The goal is to:
 
@@ -8,6 +8,7 @@ The goal is not to invent a second lint philosophy. The goal is to:
 - pin a single `oxlint` version
 - pin a single `oxfmt` version
 - pin a single `ultracite` version
+- pin React Doctor's Oxlint plugin for React and Next.js projects on the Oxlint/Oxfmt lane
 - pin a single `@manypkg/cli` version for monorepo consistency checks
 - give every consumer the same small preset matrix
 - discourage repo-local overrides unless the project has a genuinely unique constraint
@@ -50,7 +51,7 @@ Install the shared tooling:
 pnpm add -D @howells/lint
 ```
 
-Do not add `@biomejs/biome`, `oxlint`, `oxfmt`, `oxlint-tsgolint`, `ultracite`, or `@manypkg/cli` directly unless you are developing this package itself. They are pinned transitively here.
+Do not add `@biomejs/biome`, `oxlint`, `oxfmt`, `oxlint-tsgolint`, `ultracite`, `oxlint-plugin-react-doctor`, `oxc-parser`, or `@manypkg/cli` directly unless you are developing this package itself. They are pinned transitively here.
 
 ## Biome Presets
 
@@ -100,9 +101,16 @@ Next.js app:
 
 ## Oxlint/Oxfmt Presets
 
-Use this lane only when a project deliberately wants Oxlint and Oxfmt instead of Biome for day-to-day linting and formatting. The default `howells-lint` and `howells-format` commands stay on Biome.
+Use this lane when a project wants Oxlint and Oxfmt instead of Biome. React and Next presets stack the relevant Ultracite Ox rules with [React Doctor](https://react.doctor) rules in one config.
 
-Create an `oxlint.config.ts`:
+Choose the closest preset:
+
+- `@howells/lint/oxlint/core` for Node or non-React TypeScript
+- `@howells/lint/oxlint/react` for React (Ultracite React + React Doctor recommended rules)
+- `@howells/lint/oxlint/next` for Next.js (react preset + Next.js rules)
+- `@howells/lint/oxlint/react-doctor-rules` for composing or disabling React Doctor rules in mixed workspaces
+
+Node or non-React TypeScript:
 
 ```ts
 import { defineConfig } from "oxlint";
@@ -113,16 +121,43 @@ export default defineConfig({
 });
 ```
 
-For React or Next.js projects, add the matching presets:
+React package:
 
 ```ts
 import { defineConfig } from "oxlint";
-import core from "@howells/lint/oxlint/core";
 import react from "@howells/lint/oxlint/react";
+
+export default defineConfig({
+  extends: [react],
+});
+```
+
+Next.js app:
+
+```ts
+import { defineConfig } from "oxlint";
 import next from "@howells/lint/oxlint/next";
 
 export default defineConfig({
-  extends: [core, react, next],
+  extends: [next],
+});
+```
+
+Mixed monorepo with a Next.js app and Node-only packages:
+
+```ts
+import { defineConfig } from "oxlint";
+import next from "@howells/lint/oxlint/next";
+import { disabledReactDoctorRules } from "@howells/lint/oxlint/react-doctor-rules";
+
+export default defineConfig({
+  extends: [next],
+  overrides: [
+    {
+      files: ["packages/**/*.ts"],
+      rules: disabledReactDoctorRules,
+    },
+  ],
 });
 ```
 
@@ -150,7 +185,9 @@ export default defineConfig({
 
 ## Package Scripts
 
-Every package or single-package app should use this shape:
+Use scripts that match the lane the project has chosen.
+
+Biome lane:
 
 ```json
 {
@@ -162,26 +199,28 @@ Every package or single-package app should use this shape:
 }
 ```
 
-Keep `lint` non-mutating. Put all `--write` behavior in `lint:fix` or `format` so CI and local checks have the same semantics.
-
-Prefer `howells-lint .` over raw `biome check` or long target lists. Use explicit script targets only when the package has a real scope constraint:
+Oxlint/Oxfmt lane:
 
 ```json
 {
   "scripts": {
-    "lint": "howells-lint apps/web packages/ui",
-    "lint:fix": "howells-format apps/web packages/ui"
+    "lint": "howells-ox-check .",
+    "lint:fix": "howells-ox-fix ."
   }
 }
 ```
 
-For an Oxlint/Oxfmt project, keep the command names explicit:
+The Oxlint/Oxfmt lane does not currently define a separate `lint:strict`; React Doctor's recommended rules are part of the normal Ox check.
+
+Keep `lint` non-mutating. Put all write behavior in `lint:fix` or `format` so CI and local checks have the same semantics.
+
+Prefer the package binaries over raw tool commands or long target lists. Use explicit script targets only when the package has a real scope constraint:
 
 ```json
 {
   "scripts": {
-    "lint": "howells-ox-check .",
-    "lint:fix": "howells-ox-fix ."
+    "lint": "howells-lint apps/web packages/ui",
+    "lint:fix": "howells-format apps/web packages/ui"
   }
 }
 ```
@@ -207,7 +246,7 @@ A monorepo root should have:
     "check": "pnpm lint && pnpm typecheck && pnpm test"
   },
   "devDependencies": {
-    "@howells/lint": "^0.1.7"
+    "@howells/lint": "^0.2.0"
   }
 }
 ```
@@ -283,3 +322,4 @@ This package wraps:
 - [Oxlint configuration docs](https://oxc.rs/docs/guide/usage/linter/config-file-reference.html)
 - [Oxfmt configuration docs](https://oxc.rs/docs/guide/usage/formatter/config-file-reference)
 - [Ultracite configuration docs](https://www.ultracite.ai/configuration)
+- [React Doctor docs](https://react.doctor/docs)

package/docs/adr/0001-stack-ultracite-and-react-doctor-on-oxlint-lane.md

@@ -0,0 +1,34 @@
+# 0001. Stack Ultracite and React Doctor on the Oxlint/Oxfmt Lane
+
+## Status
+
+Accepted
+
+## Context
+
+`@howells/lint` offers separate linting lanes. Projects choose the Biome lane or the Oxlint/Oxfmt lane; they do not run both indefinitely.
+
+For React and Next.js projects on the Oxlint/Oxfmt lane, there are two useful rule sources:
+
+- Ultracite's Oxlint presets, which provide broad JavaScript, TypeScript, React, accessibility, and framework rules.
+- React Doctor's Oxlint plugin, which adds deeper React-specific rules for state, effects, architecture, performance, server boundaries, and framework behavior.
+
+Some React Doctor rules overlap with Ultracite's React and accessibility rules. Filtering duplicates would reduce repeated diagnostics, but it would also require `@howells/lint` to maintain a reconciliation layer that could drift as either upstream package changes.
+
+## Decision
+
+For React and Next.js projects on the Oxlint/Oxfmt lane, stack the relevant Ultracite Oxlint presets with React Doctor rules in one preset:
+
+- `@howells/lint/oxlint/react` extends `ultracite/oxlint/core` and `ultracite/oxlint/react`, then adds React Doctor's recommended rules through `oxlint-plugin-react-doctor`.
+- `@howells/lint/oxlint/next` extends the React preset and `ultracite/oxlint/next`, then adds React Doctor's Next.js rules.
+
+Do not filter overlapping rules by default.
+
+## Consequences
+
+Consumers get one Oxlint/Oxfmt lane preset for React and Next.js projects, with both Ultracite coverage and React Doctor coverage.
+
+Some findings may be duplicate or near-duplicate when upstream rule sets overlap. This is acceptable because coverage is preferred over maintaining a local rule reconciliation matrix.
+
+`@howells/lint` owns the pinned React Doctor Oxlint plugin and its parser compatibility dependency so consumer projects do not install them directly.
+

package/oxlint/next.mjs

@@ -1 +1,9 @@
-export { default } from "ultracite/oxlint/next";
+import { defineConfig } from "oxlint";
+import { NEXTJS_RULES } from "oxlint-plugin-react-doctor";
+import ultraciteNext from "ultracite/oxlint/next";
+import react from "./react.mjs";
+
+export default defineConfig({
+	extends: [react, ultraciteNext],
+	rules: NEXTJS_RULES,
+});

package/oxlint/react-doctor-rules.d.mts

@@ -0,0 +1,8 @@
+import type { OxlintConfig } from "oxlint";
+
+type OxlintRules = NonNullable<OxlintConfig["rules"]>;
+
+export const reactDoctorRecommendedRules: OxlintRules;
+export const reactDoctorNextRules: OxlintRules;
+export const reactDoctorRules: OxlintRules;
+export const disabledReactDoctorRules: OxlintRules;

package/oxlint/react-doctor-rules.mjs

@@ -0,0 +1,14 @@
+import {
+	NEXTJS_RULES,
+	RECOMMENDED_RULES,
+} from "oxlint-plugin-react-doctor";
+
+export const reactDoctorRecommendedRules = RECOMMENDED_RULES;
+export const reactDoctorNextRules = NEXTJS_RULES;
+export const reactDoctorRules = {
+	...RECOMMENDED_RULES,
+	...NEXTJS_RULES,
+};
+export const disabledReactDoctorRules = Object.fromEntries(
+	Object.keys(reactDoctorRules).map((ruleName) => [ruleName, "allow"])
+);

package/oxlint/react.mjs

@@ -1 +1,12 @@
-export { default } from "ultracite/oxlint/react";
+import { defineConfig } from "oxlint";
+import { RECOMMENDED_RULES } from "oxlint-plugin-react-doctor";
+import core from "ultracite/oxlint/core";
+import ultraciteReact from "ultracite/oxlint/react";
+
+export default defineConfig({
+	extends: [core, ultraciteReact],
+	jsPlugins: [
+		{ name: "react-doctor", specifier: "oxlint-plugin-react-doctor" },
+	],
+	rules: RECOMMENDED_RULES,
+});

package/package.json

@@ -1,62 +1,86 @@
 {
-  "name": "@howells/lint",
-  "version": "0.1.8",
-  "description": "Pinned Biome, Oxlint/Oxfmt, and Ultracite presets for Howells projects.",
-  "license": "MIT",
-  "engines": {
-    "node": ">=22.18.0"
-  },
-  "files": [
-    "biome/*.json",
-    "oxfmt/*.d.mts",
-    "oxfmt/*.mjs",
-    "oxlint/*.d.mts",
-    "oxlint/*.mjs",
-    "bin/*.mjs",
-    "README.md",
-    "MIGRATIONS.md"
-  ],
-  "bin": {
-    "howells-biome": "bin/howells-biome.mjs",
-    "howells-lint": "bin/howells-lint.mjs",
-    "howells-lint-strict": "bin/howells-lint-strict.mjs",
-    "howells-format": "bin/howells-format.mjs",
-    "howells-ox-check": "bin/howells-ox-check.mjs",
-    "howells-ox-fix": "bin/howells-ox-fix.mjs",
-    "howells-oxfmt": "bin/howells-oxfmt.mjs",
-    "howells-oxlint": "bin/howells-oxlint.mjs",
-    "howells-ultracite": "bin/howells-ultracite.mjs",
-    "howells-workspace-check": "bin/howells-workspace-check.mjs",
-    "howells-workspace-fix": "bin/howells-workspace-fix.mjs"
-  },
-  "dependencies": {
-    "@biomejs/biome": "2.4.15",
-    "@manypkg/cli": "^0.25.1",
-    "oxfmt": "0.51.0",
-    "oxlint": "1.66.0",
-    "oxlint-tsgolint": "0.23.0",
-    "ultracite": "7.7.0"
-  },
-  "exports": {
-    "./package.json": "./package.json",
-    "./biome/core": "./biome/core.json",
-    "./biome/react": "./biome/react.json",
-    "./biome/next": "./biome/next.json",
-    "./oxfmt": {
-      "types": "./oxfmt/index.d.mts",
-      "default": "./oxfmt/index.mjs"
-    },
-    "./oxlint/core": {
-      "types": "./oxlint/core.d.mts",
-      "default": "./oxlint/core.mjs"
-    },
-    "./oxlint/react": {
-      "types": "./oxlint/react.d.mts",
-      "default": "./oxlint/react.mjs"
-    },
-    "./oxlint/next": {
-      "types": "./oxlint/next.d.mts",
-      "default": "./oxlint/next.mjs"
-    }
-  }
-}
+	"name": "@howells/lint",
+	"version": "0.2.1",
+	"description": "Pinned Biome, Oxlint/Oxfmt, Ultracite, and React Doctor presets for Howells projects.",
+	"license": "MIT",
+	"packageManager": "pnpm@10.23.0",
+	"engines": {
+		"node": ">=22.18.0"
+	},
+	"files": [
+		"biome/*.json",
+		"oxfmt/*.d.mts",
+		"oxfmt/*.mjs",
+		"oxlint/*.d.mts",
+		"oxlint/*.mjs",
+		"bin/*.mjs",
+		"docs/**/*.md",
+		"CONTEXT.md",
+		"README.md",
+		"MIGRATIONS.md"
+	],
+	"bin": {
+		"howells-biome": "bin/howells-biome.mjs",
+		"howells-lint": "bin/howells-lint.mjs",
+		"howells-lint-strict": "bin/howells-lint-strict.mjs",
+		"howells-format": "bin/howells-format.mjs",
+		"howells-ox-check": "bin/howells-ox-check.mjs",
+		"howells-ox-fix": "bin/howells-ox-fix.mjs",
+		"howells-oxfmt": "bin/howells-oxfmt.mjs",
+		"howells-oxlint": "bin/howells-oxlint.mjs",
+		"howells-ultracite": "bin/howells-ultracite.mjs",
+		"howells-workspace-check": "bin/howells-workspace-check.mjs",
+		"howells-workspace-fix": "bin/howells-workspace-fix.mjs"
+	},
+	"dependencies": {
+		"@biomejs/biome": "2.4.15",
+		"@manypkg/cli": "^0.25.1",
+		"oxc-parser": "0.133.0",
+		"oxfmt": "0.51.0",
+		"oxlint": "1.66.0",
+		"oxlint-plugin-react-doctor": "0.2.14",
+		"oxlint-tsgolint": "0.23.0",
+		"ultracite": "7.7.0"
+	},
+	"exports": {
+		"./package.json": "./package.json",
+		"./biome/core": "./biome/core.json",
+		"./biome/react": "./biome/react.json",
+		"./biome/next": "./biome/next.json",
+		"./oxfmt": {
+			"types": "./oxfmt/index.d.mts",
+			"default": "./oxfmt/index.mjs"
+		},
+		"./oxlint/core": {
+			"types": "./oxlint/core.d.mts",
+			"default": "./oxlint/core.mjs"
+		},
+		"./oxlint/react": {
+			"types": "./oxlint/react.d.mts",
+			"default": "./oxlint/react.mjs"
+		},
+		"./oxlint/next": {
+			"types": "./oxlint/next.d.mts",
+			"default": "./oxlint/next.mjs"
+		},
+		"./oxlint/react-doctor-rules": {
+			"types": "./oxlint/react-doctor-rules.d.mts",
+			"default": "./oxlint/react-doctor-rules.mjs"
+		}
+	},
+	"main": "index.js",
+	"scripts": {
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/howells/lint.git"
+	},
+	"keywords": [],
+	"author": "",
+	"type": "commonjs",
+	"bugs": {
+		"url": "https://github.com/howells/lint/issues"
+	},
+	"homepage": "https://github.com/howells/lint#readme"
+}