@howells/lint 0.1.5 → 0.1.6

package/MIGRATIONS.md

@@ -19,9 +19,10 @@ If none of these fit cleanly, the likely answer is a new shared preset here, not
 ## Migration steps
 
 1. Add `@howells/lint` as a dev dependency.
-2. Replace `eslint`, `next lint`, `prettier`, or direct `biome` scripts with `howells-lint` and `howells-format`.
-3. Replace the project `biome.json` or `biome.jsonc` with a minimal file that only extends one shared preset.
-4. Remove direct `eslint`, `eslint-config-*`, `eslint-plugin-*`, `prettier`, `@biomejs/biome`, and `ultracite` dependencies once the project is green.
+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.
 
 ## Keep local config thin
 
@@ -35,7 +36,7 @@ The normal local config should look like this:
 
 Acceptable local additions:
 
-- repo-specific file includes or force-ignores that cannot be expressed better in scripts
+- repo-specific file includes or force-ignores for generated files that are unique to one project
 - one-off rule changes tied to a genuine platform constraint
 - temporary compatibility shims during migration
 

package/README.md

@@ -10,36 +10,63 @@ The goal is not to invent a second lint philosophy. The goal is to:
 - give every consumer the same small preset matrix
 - discourage repo-local overrides unless the project has a genuinely unique constraint
 
-## Install
+## Agent Setup Checklist
+
+When configuring a project, do this in order:
+
+1. Require Node 22.18.0+ and pnpm in the root `package.json`, and pin `.node-version` to `22.18.0`.
+2. Install only `@howells/lint` as the direct lint dependency.
+3. Add a `biome.json` that extends the closest presets.
+4. Add read-only `lint`, mutating `lint:fix`, and optional `lint:strict` scripts.
+5. If the project is a monorepo, add root workspace scripts that run `howells-workspace-check`.
+6. Verify with `pnpm lint` and, when configured, `pnpm lint:strict`.
+
+## Requirements
+
+All projects using this package should declare the runtime and package manager explicitly:
+
+```json
+{
+  "packageManager": "pnpm@10.23.0",
+  "engines": {
+    "node": ">=22.18.0"
+  }
+}
+```
+
+Also add a root `.node-version` file:
+
+```text
+22.18.0
+```
+
+Install the shared tooling:
 
 ```bash
 pnpm add -D @howells/lint
 ```
 
-## Presets
+Do not add `@biomejs/biome`, `ultracite`, or `@manypkg/cli` directly unless you are developing this package itself. They are pinned transitively here.
 
-Choose the closest preset instead of starting from a generic base and patching it locally:
+## Biome Presets
 
-- `@howells/lint/biome/core`
-- `@howells/lint/biome/react`
-- `@howells/lint/biome/next`
+Choose the closest preset instead of starting from a generic base and patching it locally:
 
-These presets already:
+- `@howells/lint/biome/core` for Node or non-React TypeScript packages
+- `@howells/lint/biome/react` for React packages
+- `@howells/lint/biome/next` for Next.js apps
 
-- pin Biome and Ultracite transitively
-- enable VCS ignore file support
-- ignore common build output directories
-- keep `ignoreUnknown` on so mixed repos do not need defensive local config
-- enforce 2-space indentation consistently
-- enable Tailwind CSS directives on DOM-oriented presets
+These presets already pin Biome and Ultracite, enable VCS ignore file support, ignore common build output directories, keep `ignoreUnknown` on for mixed repos, enforce 2-space indentation, and enable Tailwind CSS directives on DOM-oriented presets.
 
-## Usage
+The shared presets exclude generated and output folders seen across Howells projects: `node_modules`, `.next`, `.turbo`, `.vercel`, `dist`, `build`, `coverage`, `out`, `storybook-static`, `playwright-report`, `test-results`, `.source`, `.cache`, `.expo`, `.output`, `.wrangler`, `.svelte-kit`, `.nuxt`, `.vite`, `.vinxi`, `dev-dist`, `tmp`, and `temp`. Keep repo-local excludes only for genuinely project-specific generated files or data directories.
 
 Node or non-React TypeScript package:
 
 ```json
 {
-  "extends": ["@howells/lint/biome/core"]
+  "$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+  "extends": ["@howells/lint/biome/core"],
+  "root": true
 }
 ```
 
@@ -47,7 +74,9 @@ React package:
 
 ```json
 {
-  "extends": ["@howells/lint/biome/react"]
+  "$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+  "extends": ["@howells/lint/biome/core", "@howells/lint/biome/react"],
+  "root": true
 }
 ```
 
@@ -55,23 +84,19 @@ Next.js app:
 
 ```json
 {
-  "extends": ["@howells/lint/biome/next"]
+  "$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+  "extends": [
+    "@howells/lint/biome/core",
+    "@howells/lint/biome/react",
+    "@howells/lint/biome/next"
+  ],
+  "root": true
 }
 ```
 
-## Binaries
+## Package Scripts
 
-Installers only need `@howells/lint` as a direct dependency. Use the package binaries instead of adding `@biomejs/biome`, `ultracite`, or `@manypkg/cli` separately:
-
-- `howells-biome` proxies to the pinned Biome binary
-- `howells-ultracite` proxies to the pinned Ultracite binary
-- `howells-lint` defaults to `biome check .`
-- `howells-lint-strict` runs the high-signal Biome security, correctness, and suspicious lint rules
-- `howells-format` defaults to `biome check . --write`
-- `howells-workspace-check` validates root workspace hygiene, then runs `manypkg check`
-- `howells-workspace-fix` defaults to `manypkg fix`
-
-Example scripts:
+Every package or single-package app should use this shape:
 
 ```json
 {
@@ -85,33 +110,57 @@ Example scripts:
 
 Keep `lint` non-mutating. Put all `--write` behavior in `lint:fix` or `format` so CI and local checks have the same semantics.
 
-Monorepo root scripts should compose package linting with workspace validation:
+Prefer `howells-lint .` over raw `biome check` or long target lists. Use explicit script targets only when the package has a real scope constraint:
 
 ```json
 {
   "scripts": {
-    "lint": "turbo run lint && howells-workspace-check",
-    "lint:fix": "turbo run lint:fix && howells-workspace-fix",
-    "lint:strict": "turbo run lint:strict"
+    "lint": "howells-lint apps/web packages/ui",
+    "lint:fix": "howells-format apps/web packages/ui"
   }
 }
 ```
 
-`howells-workspace-check` expects workspace roots to declare `packageManager: "pnpm@..."`, require Node 20+ in `engines.node`, and keep `pnpm-workspace.yaml` present when using workspace package directories.
+## Monorepo Roots
 
-CI should call `pnpm lint` or `pnpm check` so these root checks are not bypassed by a direct `turbo lint` command.
+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.
 
-Prefer explicit script targets over config churn when the only difference is scope:
+A monorepo root should have:
 
 ```json
 {
+  "packageManager": "pnpm@10.23.0",
+  "engines": {
+    "node": ">=22.18.0"
+  },
   "scripts": {
-    "lint": "howells-lint apps/web packages/ui",
-    "lint:fix": "howells-format apps/web packages/ui"
+    "lint": "turbo run lint && howells-workspace-check",
+    "lint:fix": "turbo run lint:fix && howells-workspace-fix",
+    "lint:strict": "turbo run lint:strict",
+    "check": "pnpm lint && pnpm typecheck && pnpm test"
+  },
+  "devDependencies": {
+    "@howells/lint": "^0.1.6"
   }
 }
 ```
 
+`howells-workspace-check` validates that the root declares `packageManager: "pnpm@..."`, requires Node 22.18.0+ in `engines.node`, pins `.node-version` to `22.18.0`, keeps `pnpm-workspace.yaml` present when workspace package directories exist, and passes `manypkg check`.
+
+CI should call `pnpm lint` or `pnpm check` so root workspace checks are not bypassed by a direct `turbo lint` command.
+
+## Binaries
+
+Installers only need `@howells/lint` as a direct dependency. Use these package binaries:
+
+- `howells-biome` proxies to the pinned Biome binary
+- `howells-ultracite` proxies to the pinned Ultracite binary
+- `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-workspace-check` validates root workspace hygiene, then runs `manypkg check`
+- `howells-workspace-fix` runs `manypkg fix`
+
 ## Rules
 
 - Do not add local overrides just to preserve old ESLint behavior.

package/bin/workspace-preflight.mjs

@@ -2,6 +2,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 const workspaceDirs = ["apps", "packages", "services", "workers", "examples"];
+const requiredNodeVersion = "22.18.0";
 
 function readRootPackageJson() {
 	const packageJsonPath = join(process.cwd(), "package.json");
@@ -47,22 +48,57 @@ function hasLikelyWorkspaceLayout(packageJson) {
 	);
 }
 
-function isNode20Engine(range) {
+function isAtLeastRequiredNodeVersion(major, minor, patch = 0) {
+	if (major > 22) {
+		return true;
+	}
+
+	if (major < 22) {
+		return false;
+	}
+
+	if (minor > 18) {
+		return true;
+	}
+
+	if (minor < 18) {
+		return false;
+	}
+
+	return patch >= 0;
+}
+
+function isNode2218Engine(range) {
 	if (typeof range !== "string") {
 		return false;
 	}
 
 	const normalizedRange = range.replaceAll(/\s+/g, "");
+	const match = normalizedRange.match(
+		/^(?:>=|\^|~)?(?<major>\d+)(?:\.(?<minor>\d+))?(?:\.(?<patch>\d+))?$/,
+	);
 
-	if (/(^|[<>=~^|])1[0-9](\.|[^0-9]|$)/.test(normalizedRange)) {
+	if (!match?.groups?.major || !match.groups.minor) {
 		return false;
 	}
 
-	return />=?20(\.|[^0-9]|$)|\^20(\.|[^0-9]|$)|~20(\.|[^0-9]|$)/.test(
-		normalizedRange,
+	return isAtLeastRequiredNodeVersion(
+		Number(match.groups.major),
+		Number(match.groups.minor),
+		Number(match.groups.patch ?? 0),
 	);
 }
 
+function readNodeVersionFile() {
+	const nodeVersionPath = join(process.cwd(), ".node-version");
+
+	if (!existsSync(nodeVersionPath)) {
+		return undefined;
+	}
+
+	return readFileSync(nodeVersionPath, "utf8").trim();
+}
+
 export function runWorkspacePreflight() {
 	const { errors, packageJson } = readRootPackageJson();
 
@@ -76,8 +112,15 @@ export function runWorkspacePreflight() {
 		errors.push("root package.json packageManager must use pnpm");
 	}
 
-	if (!isNode20Engine(packageJson.engines?.node)) {
-		errors.push("root package.json engines.node must require Node 20+");
+	if (!isNode2218Engine(packageJson.engines?.node)) {
+		errors.push(
+			`root package.json engines.node must require Node ${requiredNodeVersion}+`,
+		);
+	}
+
+	const nodeVersion = readNodeVersionFile();
+	if (nodeVersion !== requiredNodeVersion) {
+		errors.push(`root .node-version must be ${requiredNodeVersion}`);
 	}
 
 	if (

package/biome/core.json

@@ -1,27 +1,42 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.12/schema.json",
-  "extends": ["ultracite/biome/core"],
-  "formatter": {
-    "indentStyle": "space",
-    "indentWidth": 2
-  },
-  "files": {
-    "ignoreUnknown": true,
-    "includes": [
-      "**",
-      "!!**/dist",
-      "!!**/build",
-      "!!**/.next",
-      "!!**/.turbo",
-      "!!**/coverage",
-      "!!**/storybook-static",
-      "!!**/.vercel/output",
-      "!!**/out"
-    ]
-  },
-  "vcs": {
-    "enabled": true,
-    "clientKind": "git",
-    "useIgnoreFile": true
-  }
+	"$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+	"extends": ["ultracite/biome/core"],
+	"formatter": {
+		"indentStyle": "space",
+		"indentWidth": 2
+	},
+	"files": {
+		"ignoreUnknown": true,
+		"includes": [
+			"**",
+			"!**/node_modules/**",
+			"!**/.next/**",
+			"!**/.turbo/**",
+			"!**/.vercel/**",
+			"!**/dist/**",
+			"!**/build/**",
+			"!**/coverage/**",
+			"!**/out/**",
+			"!**/storybook-static/**",
+			"!**/playwright-report/**",
+			"!**/test-results/**",
+			"!**/.source/**",
+			"!**/.cache/**",
+			"!**/.expo/**",
+			"!**/.output/**",
+			"!**/.wrangler/**",
+			"!**/.svelte-kit/**",
+			"!**/.nuxt/**",
+			"!**/.vite/**",
+			"!**/.vinxi/**",
+			"!**/dev-dist/**",
+			"!**/tmp/**",
+			"!**/temp/**"
+		]
+	},
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	}
 }

package/biome/next.json

@@ -1,9 +1,38 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.12/schema.json",
-  "extends": ["./react.json", "ultracite/biome/next"],
-  "css": {
-    "parser": {
-      "tailwindDirectives": true
-    }
-  }
+	"$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+	"extends": ["./react.json", "ultracite/biome/next"],
+	"files": {
+		"ignoreUnknown": true,
+		"includes": [
+			"**",
+			"!**/node_modules/**",
+			"!**/.next/**",
+			"!**/.turbo/**",
+			"!**/.vercel/**",
+			"!**/dist/**",
+			"!**/build/**",
+			"!**/coverage/**",
+			"!**/out/**",
+			"!**/storybook-static/**",
+			"!**/playwright-report/**",
+			"!**/test-results/**",
+			"!**/.source/**",
+			"!**/.cache/**",
+			"!**/.expo/**",
+			"!**/.output/**",
+			"!**/.wrangler/**",
+			"!**/.svelte-kit/**",
+			"!**/.nuxt/**",
+			"!**/.vite/**",
+			"!**/.vinxi/**",
+			"!**/dev-dist/**",
+			"!**/tmp/**",
+			"!**/temp/**"
+		]
+	},
+	"css": {
+		"parser": {
+			"tailwindDirectives": true
+		}
+	}
 }

package/biome/react.json

@@ -1,9 +1,38 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.12/schema.json",
-  "extends": ["./core.json", "ultracite/biome/react"],
-  "css": {
-    "parser": {
-      "tailwindDirectives": true
-    }
-  }
+	"$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+	"extends": ["./core.json", "ultracite/biome/react"],
+	"files": {
+		"ignoreUnknown": true,
+		"includes": [
+			"**",
+			"!**/node_modules/**",
+			"!**/.next/**",
+			"!**/.turbo/**",
+			"!**/.vercel/**",
+			"!**/dist/**",
+			"!**/build/**",
+			"!**/coverage/**",
+			"!**/out/**",
+			"!**/storybook-static/**",
+			"!**/playwright-report/**",
+			"!**/test-results/**",
+			"!**/.source/**",
+			"!**/.cache/**",
+			"!**/.expo/**",
+			"!**/.output/**",
+			"!**/.wrangler/**",
+			"!**/.svelte-kit/**",
+			"!**/.nuxt/**",
+			"!**/.vite/**",
+			"!**/.vinxi/**",
+			"!**/dev-dist/**",
+			"!**/tmp/**",
+			"!**/temp/**"
+		]
+	},
+	"css": {
+		"parser": {
+			"tailwindDirectives": true
+		}
+	}
 }

package/package.json

@@ -1,10 +1,11 @@
 {
 	"name": "@howells/lint",
-	"version": "0.1.5",
+	"version": "0.1.6",
 	"description": "Pinned Biome and Ultracite presets for Howells projects.",
 	"license": "MIT",
+	"packageManager": "pnpm@10.23.0",
 	"engines": {
-		"node": ">=20.19"
+		"node": ">=22.18.0"
 	},
 	"files": [
 		"biome/*.json",
@@ -22,9 +23,9 @@
 		"howells-workspace-fix": "bin/howells-workspace-fix.mjs"
 	},
 	"dependencies": {
-		"@biomejs/biome": "2.4.12",
+		"@biomejs/biome": "2.4.14",
 		"@manypkg/cli": "^0.25.1",
-		"ultracite": "7.6.0"
+		"ultracite": "7.6.2"
 	},
 	"exports": {
 		"./package.json": "./package.json",