@howells/lint 0.1.0

package/MIGRATIONS.md

@@ -0,0 +1,73 @@
+# Adoption Notes
+
+Use these notes when replacing an existing ESLint, Prettier, or ad hoc Biome setup with `@howells/lint`.
+
+## Primary rule
+
+Do not migrate an old local lint philosophy into a new local Biome override.
+
+Pick the closest shared preset first. Only add local config after you can explain why the repo is a real exception.
+
+## Preset selection
+
+- 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`
+
+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. 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.
+
+## Keep local config thin
+
+The normal local config should look like this:
+
+```json
+{
+  "extends": ["@howells/lint/biome/next"]
+}
+```
+
+Acceptable local additions:
+
+- repo-specific file includes or force-ignores that cannot be expressed better in scripts
+- one-off rule changes tied to a genuine platform constraint
+- temporary compatibility shims during migration
+
+Avoid:
+
+- copying old ESLint rule customizations into Biome
+- broad `linter.rules` sections to preserve team habit
+- local wrapper configs like `base.json` or `library.json`
+- repeating the same override across multiple repos
+
+## Promote shared patterns quickly
+
+If the same override or ignore pattern appears in more than one active project, treat that as pressure on `@howells/lint`.
+
+Either:
+
+- move the shared behavior into an existing preset, or
+- add a new preset with a name that describes the actual environment
+
+Do not normalize repeated local exceptions.
+
+## Prefer scope in scripts
+
+If one repo only needs a narrower target, prefer script-level scope:
+
+```json
+{
+  "scripts": {
+    "lint": "howells-lint apps/web packages/ui",
+    "lint:fix": "howells-format apps/web packages/ui"
+  }
+}
+```
+
+That is usually better than teaching the config about the repo layout.

package/README.md

@@ -0,0 +1,103 @@
+# `@howells/lint`
+
+Pinned Biome 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 `ultracite` version
+- give every consumer the same small preset matrix
+- discourage repo-local overrides unless the project has a genuinely unique constraint
+
+## Install
+
+```bash
+pnpm add -D @howells/lint
+```
+
+## Presets
+
+Choose the closest preset instead of starting from a generic base and patching it locally:
+
+- `@howells/lint/biome/core`
+- `@howells/lint/biome/react`
+- `@howells/lint/biome/next`
+
+These presets already:
+
+- 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
+
+## Usage
+
+Node or non-React TypeScript package:
+
+```json
+{
+  "extends": ["@howells/lint/biome/core"]
+}
+```
+
+React package:
+
+```json
+{
+  "extends": ["@howells/lint/biome/react"]
+}
+```
+
+Next.js app:
+
+```json
+{
+  "extends": ["@howells/lint/biome/next"]
+}
+```
+
+## Binaries
+
+Installers only need `@howells/lint` as a direct dependency. Use the package binaries instead of adding `@biomejs/biome` or `ultracite` 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`
+
+Example scripts:
+
+```json
+{
+  "scripts": {
+    "lint": "howells-lint",
+    "lint:fix": "howells-format"
+  }
+}
+```
+
+Prefer explicit script targets over config churn when the only difference is scope:
+
+```json
+{
+  "scripts": {
+    "lint": "howells-lint apps/web packages/ui",
+    "lint:fix": "howells-format apps/web packages/ui"
+  }
+}
+```
+
+## Rules
+
+- Do not add local overrides just to preserve old ESLint behavior.
+- Do not create local `base`, `shared`, or `custom` Biome wrappers.
+- 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.
+
+## Upstream
+
+This package wraps:
+
+- [Biome configuration docs](https://biomejs.dev/reference/configuration/)
+- [Ultracite configuration docs](https://www.ultracite.ai/configuration)

package/bin/howells-biome.mjs

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

package/bin/howells-format.mjs

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

package/bin/howells-lint.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+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"
+]);
+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];
+
+runPackageBin("@biomejs/biome", "biome", resolvedArgs);

package/bin/howells-ultracite.mjs

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

package/bin/run-package-bin.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+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}'.`);
+}
+
+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 (binField && typeof binField === "object" && binField[binName]) {
+    return join(packageDir, binField[binName]);
+  }
+
+  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
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  process.exit(result.status ?? 1);
+}

package/biome/core.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
+  "extends": ["ultracite/biome/core"],
+  "files": {
+    "ignoreUnknown": true,
+    "includes": [
+      "**",
+      "!!**/dist",
+      "!!**/build",
+      "!!**/.next",
+      "!!**/.turbo",
+      "!!**/coverage",
+      "!!**/storybook-static",
+      "!!**/.vercel/output",
+      "!!**/out"
+    ]
+  },
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  }
+}

package/biome/next.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
+  "extends": ["./react.json", "ultracite/biome/next"]
+}

package/biome/react.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
+  "extends": ["./core.json", "ultracite/biome/react"]
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@howells/lint",
+  "version": "0.1.0",
+  "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.10",
+    "ultracite": "7.4.3"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    "./biome/core": "./biome/core.json",
+    "./biome/react": "./biome/react.json",
+    "./biome/next": "./biome/next.json"
+  }
+}