@howells/lint 0.1.3 → 0.1.5

package/README.md

@@ -6,6 +6,7 @@ The goal is not to invent a second lint philosophy. The goal is to:
 
 - pin a single `@biomejs/biome` 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
 
@@ -60,24 +61,46 @@ Next.js app:
 
 ## Binaries
 
-Installers only need `@howells/lint` as a direct dependency. Use the package binaries instead of adding `@biomejs/biome` or `ultracite` separately:
+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:
 
 ```json
 {
   "scripts": {
-    "lint": "howells-lint",
-    "lint:fix": "howells-format"
+    "lint": "howells-lint .",
+    "lint:fix": "howells-format .",
+    "lint:strict": "howells-lint-strict ."
   }
 }
 ```
 
+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:
+
+```json
+{
+  "scripts": {
+    "lint": "turbo run lint && howells-workspace-check",
+    "lint:fix": "turbo run lint:fix && howells-workspace-fix",
+    "lint:strict": "turbo run lint:strict"
+  }
+}
+```
+
+`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.
+
+CI should call `pnpm lint` or `pnpm check` so these root checks are not bypassed by a direct `turbo lint` command.
+
 Prefer explicit script targets over config churn when the only difference is scope:
 
 ```json
@@ -96,6 +119,40 @@ 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
+
+Add this to `.claude/settings.json` so files are formatted on edit and linted on session end:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.file_path' | { read file_path; case \"$file_path\" in *.js|*.ts|*.jsx|*.tsx|*.json|*.jsonc|*.css|*.graphql) howells-format \"$file_path\" 2>/dev/null || true ;; esac; }"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "git diff --name-only --diff-filter=d HEAD | grep -E '\\.(js|ts|jsx|tsx|json|jsonc|css|graphql)$' | xargs howells-format 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
 
 ## Upstream
 

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

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+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);
+
+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/howells-workspace-fix.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { runManypkgCommand } from "./run-manypkg-command.mjs";
+
+const args = process.argv.slice(2);
+runManypkgCommand("fix", args);

package/bin/run-manypkg-command.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import { createRequire } from "node:module";
+import { runPackageBin } from "./run-package-bin.mjs";
+
+const require = createRequire(import.meta.url);
+const helpOptions = new Set(["--help", "-h"]);
+const versionOptions = new Set(["--version", "-V"]);
+
+export function printManypkgCommandHelp(command) {
+	console.log(`Usage: howells-workspace-${command} [options]\n`);
+	console.log(`Runs: manypkg ${command} [options]`);
+}
+
+export function printManypkgCliVersion() {
+	const { version } = require("@manypkg/cli/package.json");
+	console.log(version);
+}
+
+export function handleManypkgMetadataCommand(command, args) {
+	if (helpOptions.has(args[0])) {
+		printManypkgCommandHelp(command);
+		return true;
+	}
+
+	if (versionOptions.has(args[0])) {
+		printManypkgCliVersion();
+		return true;
+	}
+
+	return false;
+}
+
+export function runManypkgCommand(command, args) {
+	if (handleManypkgMetadataCommand(command, args)) {
+		process.exit(0);
+	}
+
+	runPackageBin("@manypkg/cli", "manypkg", [command, ...args]);
+}

package/bin/workspace-preflight.mjs

@@ -0,0 +1,91 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const workspaceDirs = ["apps", "packages", "services", "workers", "examples"];
+
+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 isNode20Engine(range) {
+	if (typeof range !== "string") {
+		return false;
+	}
+
+	const normalizedRange = range.replaceAll(/\s+/g, "");
+
+	if (/(^|[<>=~^|])1[0-9](\.|[^0-9]|$)/.test(normalizedRange)) {
+		return false;
+	}
+
+	return />=?20(\.|[^0-9]|$)|\^20(\.|[^0-9]|$)|~20(\.|[^0-9]|$)/.test(
+		normalizedRange,
+	);
+}
+
+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 (!isNode20Engine(packageJson.engines?.node)) {
+		errors.push("root package.json engines.node must require Node 20+");
+	}
+
+	if (
+		hasLikelyWorkspaceLayout(packageJson) &&
+		!existsSync(join(process.cwd(), "pnpm-workspace.yaml"))
+	) {
+		errors.push("pnpm-workspace.yaml is required for workspace projects");
+	}
+
+	return errors;
+}

package/package.json

@@ -1,28 +1,35 @@
 {
-  "name": "@howells/lint",
-  "version": "0.1.3",
-  "description": "Pinned Biome and Ultracite presets for Howells projects.",
-  "license": "MIT",
-  "files": [
-    "biome/*.json",
-    "bin/*.mjs",
-    "README.md",
-    "MIGRATIONS.md"
-  ],
-  "bin": {
-    "howells-biome": "bin/howells-biome.mjs",
-    "howells-lint": "bin/howells-lint.mjs",
-    "howells-format": "bin/howells-format.mjs",
-    "howells-ultracite": "bin/howells-ultracite.mjs"
-  },
-  "dependencies": {
-    "@biomejs/biome": "2.4.12",
-    "ultracite": "7.6.0"
-  },
-  "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.5",
+	"description": "Pinned Biome and Ultracite presets for Howells projects.",
+	"license": "MIT",
+	"engines": {
+		"node": ">=20.19"
+	},
+	"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.12",
+		"@manypkg/cli": "^0.25.1",
+		"ultracite": "7.6.0"
+	},
+	"exports": {
+		"./package.json": "./package.json",
+		"./biome/core": "./biome/core.json",
+		"./biome/react": "./biome/react.json",
+		"./biome/next": "./biome/next.json"
+	}
 }