@howells/lint 0.1.4 → 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,56 +84,83 @@ 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-format` defaults to `biome check . --write`
-- `howells-workspace-check` defaults to `manypkg check`
-- `howells-workspace-fix` defaults to `manypkg fix`
-
-Example scripts:
+Every package or single-package app should use this shape:
 
 ```json
 {
   "scripts": {
-    "lint": "howells-lint",
-    "lint:fix": "howells-format"
+    "lint": "howells-lint .",
+    "lint:fix": "howells-format .",
+    "lint:strict": "howells-lint-strict ."
   }
 }
 ```
 
-Monorepo root scripts should compose package linting with workspace validation:
+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:
 
 ```json
 {
   "scripts": {
-    "lint": "turbo run lint && howells-workspace-check",
-    "lint:fix": "turbo run lint:fix && howells-workspace-fix"
+    "lint": "howells-lint apps/web packages/ui",
+    "lint:fix": "howells-format apps/web packages/ui"
   }
 }
 ```
 
-CI should call `pnpm lint` or `pnpm check` so the workspace check is not bypassed by a direct `turbo lint` command.
+## 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.
 
-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.
@@ -112,6 +168,8 @@ Prefer explicit script targets over config churn when the only difference is sco
 - 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.
+- Keep package `lint` scripts read-only; use `lint:fix` for formatting and safe writes.
+- Prefer `howells-lint .` over raw `biome check` or long target lists unless a package has a real scope constraint.
 
 ## Claude Code Hooks
 

package/bin/howells-lint-strict.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { runPackageBin } from "./run-package-bin.mjs";
+
+const args = process.argv.slice(2);
+const passthroughOptions = new Set(["--help", "-h", "--version", "-V"]);
+const targets =
+	args.length === 0 || args[0].startsWith("-") ? [".", ...args] : args;
+
+const strictRuleOptions = [
+	"--only=security",
+	"--skip=security/noSecrets",
+	"--only=correctness/noConstAssign",
+	"--only=correctness/noUnreachable",
+	"--only=correctness/noInvalidConstructorSuper",
+	"--only=correctness/noSetterReturn",
+	"--only=correctness/noUnsafeFinally",
+	"--only=correctness/noUnsafeOptionalChaining",
+	"--only=correctness/noGlobalObjectCalls",
+	"--only=correctness/noSelfAssign",
+	"--only=correctness/noSwitchDeclarations",
+	"--only=suspicious/noDebugger",
+	"--only=suspicious/noDoubleEquals",
+	"--only=suspicious/noExplicitAny",
+	"--only=suspicious/noCatchAssign",
+	"--only=suspicious/noFunctionAssign",
+	"--only=suspicious/noGlobalAssign",
+	"--only=suspicious/noRedeclare",
+	"--only=suspicious/noSparseArray",
+	"--only=suspicious/noVar",
+	"--only=suspicious/noDuplicateCase",
+	"--only=suspicious/noDuplicateObjectKeys",
+	"--only=suspicious/noDuplicateParameters",
+	"--only=suspicious/noFallthroughSwitchClause",
+	"--only=suspicious/noFocusedTests",
+];
+
+const resolvedArgs = passthroughOptions.has(args[0])
+	? args
+	: ["lint", ...strictRuleOptions, ...targets];
+
+runPackageBin("@biomejs/biome", "biome", resolvedArgs);

package/bin/howells-workspace-check.mjs

@@ -1,6 +1,25 @@
 #!/usr/bin/env node
 
-import { runManypkgCommand } from "./run-manypkg-command.mjs";
+import { handleManypkgMetadataCommand } from "./run-manypkg-command.mjs";
+import { runPackageBin } from "./run-package-bin.mjs";
+import { runWorkspacePreflight } from "./workspace-preflight.mjs";
 
 const args = process.argv.slice(2);
-runManypkgCommand("check", args);
+
+if (handleManypkgMetadataCommand("check", args)) {
+	process.exit(0);
+}
+
+const errors = runWorkspacePreflight();
+
+if (errors.length > 0) {
+	console.error("Workspace hygiene check failed:");
+
+	for (const error of errors) {
+		console.error(`- ${error}`);
+	}
+
+	process.exit(1);
+}
+
+runPackageBin("@manypkg/cli", "manypkg", ["check", ...args]);

package/bin/run-manypkg-command.mjs

@@ -7,24 +7,32 @@ const require = createRequire(import.meta.url);
 const helpOptions = new Set(["--help", "-h"]);
 const versionOptions = new Set(["--version", "-V"]);
 
-function printHelp(command) {
+export function printManypkgCommandHelp(command) {
 	console.log(`Usage: howells-workspace-${command} [options]\n`);
 	console.log(`Runs: manypkg ${command} [options]`);
 }
 
-function printVersion() {
+export function printManypkgCliVersion() {
 	const { version } = require("@manypkg/cli/package.json");
 	console.log(version);
 }
 
-export function runManypkgCommand(command, args) {
+export function handleManypkgMetadataCommand(command, args) {
 	if (helpOptions.has(args[0])) {
-		printHelp(command);
-		process.exit(0);
+		printManypkgCommandHelp(command);
+		return true;
 	}
 
 	if (versionOptions.has(args[0])) {
-		printVersion();
+		printManypkgCliVersion();
+		return true;
+	}
+
+	return false;
+}
+
+export function runManypkgCommand(command, args) {
+	if (handleManypkgMetadataCommand(command, args)) {
 		process.exit(0);
 	}
 

package/bin/workspace-preflight.mjs

@@ -0,0 +1,134 @@
+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");
+
+	if (!existsSync(packageJsonPath)) {
+		return {
+			errors: ["root package.json is missing"],
+			packageJson: undefined,
+		};
+	}
+
+	try {
+		return {
+			errors: [],
+			packageJson: JSON.parse(readFileSync(packageJsonPath, "utf8")),
+		};
+	} catch (error) {
+		return {
+			errors: [`root package.json could not be parsed: ${error.message}`],
+			packageJson: undefined,
+		};
+	}
+}
+
+function hasWorkspaceChildren(directory) {
+	const directoryPath = join(process.cwd(), directory);
+
+	if (!existsSync(directoryPath)) {
+		return false;
+	}
+
+	return readdirSync(directoryPath, { withFileTypes: true }).some((entry) => {
+		return (
+			entry.isDirectory() &&
+			existsSync(join(directoryPath, entry.name, "package.json"))
+		);
+	});
+}
+
+function hasLikelyWorkspaceLayout(packageJson) {
+	return (
+		Boolean(packageJson?.workspaces) || workspaceDirs.some(hasWorkspaceChildren)
+	);
+}
+
+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 (!match?.groups?.major || !match.groups.minor) {
+		return false;
+	}
+
+	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();
+
+	if (!packageJson) {
+		return errors;
+	}
+
+	if (typeof packageJson.packageManager !== "string") {
+		errors.push("root package.json must declare packageManager");
+	} else if (!packageJson.packageManager.startsWith("pnpm@")) {
+		errors.push("root package.json packageManager must use pnpm");
+	}
+
+	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 (
+		hasLikelyWorkspaceLayout(packageJson) &&
+		!existsSync(join(process.cwd(), "pnpm-workspace.yaml"))
+	) {
+		errors.push("pnpm-workspace.yaml is required for workspace projects");
+	}
+
+	return errors;
+}

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.4",
+	"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",
@@ -15,15 +16,16 @@
 	"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.12",
+		"@biomejs/biome": "2.4.14",
 		"@manypkg/cli": "^0.25.1",
-		"ultracite": "7.6.0"
+		"ultracite": "7.6.2"
 	},
 	"exports": {
 		"./package.json": "./package.json",