@howells/lint 0.1.6 → 0.1.8

package/MIGRATIONS.md

@@ -1,6 +1,6 @@
 # Adoption Notes
 
-Use these notes when replacing an existing ESLint, Prettier, or ad hoc Biome setup with `@howells/lint`.
+Use these notes when replacing an existing ESLint, Prettier, Oxc, or ad hoc Biome setup with `@howells/lint`.
 
 ## Primary rule
 
@@ -22,7 +22,24 @@ If none of these fit cleanly, the likely answer is a new shared preset here, not
 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`, and `ultracite` dependencies once the project is green.
+5. Remove direct `eslint`, `eslint-config-*`, `eslint-plugin-*`, `prettier`, `@biomejs/biome`, `oxlint`, `oxfmt`, `oxlint-tsgolint`, and `ultracite` 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.
+
+For an Oxlint/Oxfmt project, add `oxlint.config.ts` and `oxfmt.config.ts` using the exports from `@howells/lint`, then use:
+
+```json
+{
+  "scripts": {
+    "lint": "howells-ox-check .",
+    "lint:fix": "howells-ox-fix ."
+  }
+}
+```
+
+Do not run Biome and Oxlint/Oxfmt together indefinitely. If both are present during a migration, write down which command is authoritative and remove the other once the migration is green.
 
 ## Keep local config thin
 

package/README.md

@@ -1,15 +1,19 @@
 # `@howells/lint`
 
-Pinned Biome and Ultracite presets for Howells projects.
+Pinned Biome, Oxlint/Oxfmt, and Ultracite presets for Howells projects.
 
 The goal is not to invent a second lint philosophy. The goal is to:
 
 - pin a single `@biomejs/biome` version
+- pin a single `oxlint` version
+- pin a single `oxfmt` version
 - pin a single `ultracite` version
 - 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
 
+Biome is the default toolchain. Oxlint/Oxfmt is offered as an explicit opt-in lane for JavaScript and TypeScript projects that want the Oxc stack's speed and ESLint-style rule coverage.
+
 ## Agent Setup Checklist
 
 When configuring a project, do this in order:
@@ -46,7 +50,7 @@ Install the shared tooling:
 pnpm add -D @howells/lint
 ```
 
-Do not add `@biomejs/biome`, `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`, or `@manypkg/cli` directly unless you are developing this package itself. They are pinned transitively here.
 
 ## Biome Presets
 
@@ -64,7 +68,7 @@ Node or non-React TypeScript package:
 
 ```json
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
   "extends": ["@howells/lint/biome/core"],
   "root": true
 }
@@ -74,7 +78,7 @@ React package:
 
 ```json
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
   "extends": ["@howells/lint/biome/core", "@howells/lint/biome/react"],
   "root": true
 }
@@ -84,7 +88,7 @@ Next.js app:
 
 ```json
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
   "extends": [
     "@howells/lint/biome/core",
     "@howells/lint/biome/react",
@@ -94,6 +98,56 @@ 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.
+
+Create an `oxlint.config.ts`:
+
+```ts
+import { defineConfig } from "oxlint";
+import core from "@howells/lint/oxlint/core";
+
+export default defineConfig({
+  extends: [core],
+});
+```
+
+For React or Next.js projects, add the matching presets:
+
+```ts
+import { defineConfig } from "oxlint";
+import core from "@howells/lint/oxlint/core";
+import react from "@howells/lint/oxlint/react";
+import next from "@howells/lint/oxlint/next";
+
+export default defineConfig({
+  extends: [core, react, next],
+});
+```
+
+Create an `oxfmt.config.ts`:
+
+```ts
+import { defineConfig } from "oxfmt";
+import howells from "@howells/lint/oxfmt";
+
+export default defineConfig({
+  extends: [howells],
+});
+```
+
+Oxlint type-aware rules are available through the pinned `oxlint-tsgolint` dependency. Enable them in the root Oxlint config when the project is ready for TypeScript 7 / `typescript-go` constraints:
+
+```ts
+export default defineConfig({
+  extends: [core],
+  options: {
+    typeAware: true,
+  },
+});
+```
+
 ## Package Scripts
 
 Every package or single-package app should use this shape:
@@ -121,6 +175,19 @@ Prefer `howells-lint .` over raw `biome check` or long target lists. Use explici
 }
 ```
 
+For an Oxlint/Oxfmt project, keep the command names explicit:
+
+```json
+{
+  "scripts": {
+    "lint": "howells-ox-check .",
+    "lint:fix": "howells-ox-fix ."
+  }
+}
+```
+
+Use `howells-ox-fix --unsafe .` only when you deliberately want Oxlint's dangerous fixes.
+
 ## Monorepo Roots
 
 Use workspace checks only at the monorepo root. Do not add `howells-workspace-check` to individual packages, and do not add it to single-package apps.
@@ -140,7 +207,7 @@ A monorepo root should have:
     "check": "pnpm lint && pnpm typecheck && pnpm test"
   },
   "devDependencies": {
-    "@howells/lint": "^0.1.6"
+    "@howells/lint": "^0.1.7"
   }
 }
 ```
@@ -158,6 +225,10 @@ Installers only need `@howells/lint` as a direct dependency. Use these package b
 - `howells-lint` defaults to `biome check .`
 - `howells-lint-strict` runs high-signal Biome security, correctness, and suspicious lint rules
 - `howells-format` defaults to `biome check . --write`
+- `howells-oxlint` proxies to the pinned Oxlint binary
+- `howells-oxfmt` proxies to the pinned Oxfmt binary
+- `howells-ox-check` runs `oxfmt --check`, then `oxlint`
+- `howells-ox-fix` runs `oxfmt --write`, then `oxlint --fix`
 - `howells-workspace-check` validates root workspace hygiene, then runs `manypkg check`
 - `howells-workspace-fix` runs `manypkg fix`
 
@@ -165,6 +236,7 @@ Installers only need `@howells/lint` as a direct dependency. Use these package b
 
 - Do not add local overrides just to preserve old ESLint behavior.
 - Do not create local `base`, `shared`, or `custom` Biome wrappers.
+- Do not mix Biome and Oxlint/Oxfmt scripts in the same package unless the project has a deliberate migration plan.
 - If multiple repos need the same exception, add or adjust a preset here.
 - If a repo needs framework-specific linting, choose the matching preset instead of layering rules manually.
 - Prefer inline `biome-ignore` comments for truly isolated exceptions over broad config overrides.
@@ -208,4 +280,6 @@ Add this to `.claude/settings.json` so files are formatted on edit and linted on
 This package wraps:
 
 - [Biome configuration docs](https://biomejs.dev/reference/configuration/)
+- [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)

package/bin/howells-format.mjs

@@ -4,8 +4,8 @@ import { runPackageBin } from "./run-package-bin.mjs";
 
 const targets = process.argv.slice(2);
 const args =
-  targets.length > 0
-    ? ["check", "--write", ...targets]
-    : ["check", "--write", "."];
+	targets.length > 0
+		? ["check", "--write", ...targets]
+		: ["check", "--write", "."];
 
 runPackageBin("@biomejs/biome", "biome", args);

package/bin/howells-lint.mjs

@@ -4,33 +4,33 @@ import { runPackageBin } from "./run-package-bin.mjs";
 
 const args = process.argv.slice(2);
 const biomeCommands = new Set([
-  "version",
-  "rage",
-  "start",
-  "stop",
-  "check",
-  "lint",
-  "format",
-  "ci",
-  "init",
-  "migrate",
-  "search",
-  "explain",
-  "clean",
-  "daemon",
-  "lsp-proxy"
+	"version",
+	"rage",
+	"start",
+	"stop",
+	"check",
+	"lint",
+	"format",
+	"ci",
+	"init",
+	"migrate",
+	"search",
+	"explain",
+	"clean",
+	"daemon",
+	"lsp-proxy",
 ]);
 const passthroughOptions = new Set(["--help", "-h", "--version", "-V"]);
 
 const resolvedArgs =
-  args.length === 0
-    ? ["check", "."]
-    : biomeCommands.has(args[0])
-      ? args
-      : passthroughOptions.has(args[0])
-        ? args
-      : args[0].startsWith("-")
-        ? ["check", ".", ...args]
-      : ["check", ...args];
+	args.length === 0
+		? ["check", "."]
+		: biomeCommands.has(args[0])
+			? args
+			: passthroughOptions.has(args[0])
+				? args
+				: args[0].startsWith("-")
+					? ["check", ".", ...args]
+					: ["check", ...args];
 
 runPackageBin("@biomejs/biome", "biome", resolvedArgs);

package/bin/howells-ox-check.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { resolvePackageBin } from "./run-package-bin.mjs";
+
+const args = process.argv.slice(2);
+const targets = args.filter((arg) => !arg.startsWith("-"));
+const oxlintOptions = args.filter((arg) => arg.startsWith("-"));
+const resolvedTargets = targets.length > 0 ? targets : ["."];
+
+function run(packageName, binName, commandArgs) {
+	const binPath = resolvePackageBin(packageName, binName);
+	const result = spawnSync(binPath, commandArgs, {
+		stdio: "inherit",
+		env: process.env,
+	});
+
+	if (result.error) {
+		throw result.error;
+	}
+
+	if ((result.status ?? 1) !== 0) {
+		process.exit(result.status ?? 1);
+	}
+}
+
+run("oxfmt", "oxfmt", ["--check", ...resolvedTargets]);
+run("oxlint", "oxlint", [...oxlintOptions, ...resolvedTargets]);

package/bin/howells-ox-fix.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { resolvePackageBin } from "./run-package-bin.mjs";
+
+const args = process.argv.slice(2);
+const useDangerousFixes = args.includes("--unsafe");
+const filteredArgs = args.filter((arg) => arg !== "--unsafe");
+const targets = filteredArgs.filter((arg) => !arg.startsWith("-"));
+const oxlintOptions = filteredArgs.filter((arg) => arg.startsWith("-"));
+const resolvedTargets = targets.length > 0 ? targets : ["."];
+
+function run(packageName, binName, commandArgs) {
+	const binPath = resolvePackageBin(packageName, binName);
+	const result = spawnSync(binPath, commandArgs, {
+		stdio: "inherit",
+		env: process.env,
+	});
+
+	if (result.error) {
+		throw result.error;
+	}
+
+	if ((result.status ?? 1) !== 0) {
+		process.exit(result.status ?? 1);
+	}
+}
+
+run("oxfmt", "oxfmt", ["--write", ...resolvedTargets]);
+run("oxlint", "oxlint", [
+	useDangerousFixes ? "--fix-dangerously" : "--fix",
+	...oxlintOptions,
+	...resolvedTargets,
+]);

package/bin/howells-oxfmt.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runPackageBin } from "./run-package-bin.mjs";
+
+runPackageBin("oxfmt", "oxfmt", process.argv.slice(2));

package/bin/howells-oxlint.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runPackageBin } from "./run-package-bin.mjs";
+
+runPackageBin("oxlint", "oxlint", process.argv.slice(2));

package/bin/run-package-bin.mjs

@@ -2,67 +2,77 @@
 
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
 import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const require = createRequire(import.meta.url);
 const currentDir = dirname(fileURLToPath(import.meta.url));
 
 function resolvePackageJsonPath(packageName) {
-  try {
-    return require.resolve(`${packageName}/package.json`);
-  } catch {
-    const packageSegments = packageName.split("/");
-    let searchDir = currentDir;
-
-    while (true) {
-      const candidate = join(searchDir, "..", "node_modules", ...packageSegments, "package.json");
-
-      if (existsSync(candidate)) {
-        return candidate;
-      }
-
-      const parentDir = dirname(searchDir);
-
-      if (parentDir === searchDir) {
-        break;
-      }
-
-      searchDir = parentDir;
-    }
-  }
-
-  throw new Error(`Could not resolve package.json for package '${packageName}'.`);
+	try {
+		return require.resolve(`${packageName}/package.json`);
+	} catch {
+		const packageSegments = packageName.split("/");
+		let searchDir = currentDir;
+
+		while (true) {
+			const candidate = join(
+				searchDir,
+				"..",
+				"node_modules",
+				...packageSegments,
+				"package.json",
+			);
+
+			if (existsSync(candidate)) {
+				return candidate;
+			}
+
+			const parentDir = dirname(searchDir);
+
+			if (parentDir === searchDir) {
+				break;
+			}
+
+			searchDir = parentDir;
+		}
+	}
+
+	throw new Error(
+		`Could not resolve package.json for package '${packageName}'.`,
+	);
 }
 
-function resolvePackageBin(packageName, binName) {
-  const packageJsonPath = resolvePackageJsonPath(packageName);
-  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
-  const packageDir = dirname(packageJsonPath);
-  const binField = packageJson.bin;
+export function resolvePackageBin(packageName, binName) {
+	const packageJsonPath = resolvePackageJsonPath(packageName);
+	const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+	const packageDir = dirname(packageJsonPath);
+	const binField = packageJson.bin;
 
-  if (typeof binField === "string") {
-    return join(packageDir, binField);
-  }
+	if (typeof binField === "string") {
+		return join(packageDir, binField);
+	}
 
-  if (binField && typeof binField === "object" && binField[binName]) {
-    return join(packageDir, binField[binName]);
-  }
+	if (binField && typeof binField === "object" && binField[binName]) {
+		return join(packageDir, binField[binName]);
+	}
 
-  throw new Error(`Could not resolve bin '${binName}' for package '${packageName}'.`);
+	throw new Error(
+		`Could not resolve bin '${binName}' for package '${packageName}'.`,
+	);
 }
 
 export function runPackageBin(packageName, binName, args) {
-  const binPath = resolvePackageBin(packageName, binName);
-  const result = spawnSync(binPath, args, {
-    stdio: "inherit",
-    env: process.env
-  });
+	const binPath = resolvePackageBin(packageName, binName);
+	const result = spawnSync(binPath, args, {
+		stdio: "inherit",
+		env: process.env,
+	});
 
-  if (result.error) {
-    throw result.error;
-  }
+	if (result.error) {
+		throw result.error;
+	}
 
-  process.exit(result.status ?? 1);
+	process.exit(result.status ?? 1);
 }

package/biome/core.json

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+	"$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
 	"extends": ["ultracite/biome/core"],
 	"formatter": {
 		"indentStyle": "space",

package/biome/next.json

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+	"$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
 	"extends": ["./react.json", "ultracite/biome/next"],
 	"files": {
 		"ignoreUnknown": true,

package/biome/react.json

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+	"$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
 	"extends": ["./core.json", "ultracite/biome/react"],
 	"files": {
 		"ignoreUnknown": true,

package/oxfmt/index.d.mts

@@ -0,0 +1,4 @@
+import type { OxfmtConfig } from "oxfmt";
+
+declare const config: OxfmtConfig;
+export default config;

package/oxfmt/index.mjs

@@ -0,0 +1 @@
+export { default } from "ultracite/oxfmt";

package/oxlint/core.d.mts

@@ -0,0 +1,4 @@
+import type { OxlintConfig } from "oxlint";
+
+declare const config: OxlintConfig;
+export default config;

package/oxlint/core.mjs

@@ -0,0 +1 @@
+export { default } from "ultracite/oxlint/core";

package/oxlint/next.d.mts

@@ -0,0 +1,4 @@
+import type { OxlintConfig } from "oxlint";
+
+declare const config: OxlintConfig;
+export default config;

package/oxlint/next.mjs

@@ -0,0 +1 @@
+export { default } from "ultracite/oxlint/next";

package/oxlint/react.d.mts

@@ -0,0 +1,4 @@
+import type { OxlintConfig } from "oxlint";
+
+declare const config: OxlintConfig;
+export default config;

package/oxlint/react.mjs

@@ -0,0 +1 @@
+export { default } from "ultracite/oxlint/react";

package/package.json

@@ -1,36 +1,62 @@
 {
-	"name": "@howells/lint",
-	"version": "0.1.6",
-	"description": "Pinned Biome and Ultracite presets for Howells projects.",
-	"license": "MIT",
-	"packageManager": "pnpm@10.23.0",
-	"engines": {
-		"node": ">=22.18.0"
-	},
-	"files": [
-		"biome/*.json",
-		"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-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.14",
-		"@manypkg/cli": "^0.25.1",
-		"ultracite": "7.6.2"
-	},
-	"exports": {
-		"./package.json": "./package.json",
-		"./biome/core": "./biome/core.json",
-		"./biome/react": "./biome/react.json",
-		"./biome/next": "./biome/next.json"
-	}
-}
+  "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"
+    }
+  }
+}