npm - lintlane - Versions diffs - 2.5.0 → 4.0.0 - Mend

lintlane 2.5.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/LICENSE +21 -0
package/README.md +210 -512
package/bin/check-commit.mjs +54 -137
package/bin/checks.mjs +237 -0
package/bin/cli.mjs +299 -220
package/bin/commit-cli.mjs +36 -122
package/bin/doctor.mjs +328 -0
package/bin/hook.mjs +156 -0
package/bin/proc.mjs +132 -0
package/bin/project.mjs +276 -0
package/bin/ui-server.mjs +244 -91
package/package.json +22 -7
package/presets/commitizen.cjs +4 -0
package/presets/commitlint.mjs +47 -0
package/templates/commit-msg +2 -2
package/templates/pre-commit +2 -2
package/templates/pre-push +2 -2
package/templates/prepare-commit-msg +2 -2
package/ui/index.html +210 -44
package/bin/ci.mjs +0 -162
package/bin/commit-config.mjs +0 -24
package/bin/commit-lint.mjs +0 -143
package/bin/commit-msg.mjs +0 -18
package/bin/commit-prompt.mjs +0 -110
package/bin/pre-push-check.mjs +0 -48
package/bin/prepare-commit-msg.mjs +0 -46

package/README.md CHANGED Viewed

@@ -1,321 +1,154 @@
 # lintlane
-Pre-push checks for React apps. One command sets up a shared
-[Biome](https://biomejs.dev) lint/format preset, git hooks, a Conventional
-Commits workflow and a CI workflow; a local dashboard lets you run the same
-checks your CI will run — and see exactly what would fail — before you push.
-**What you get**
-- A shared Biome preset (`base`, `strict`, `next`) with auto-detection.
-- A pre-commit hook that formats and lints staged files.
-- Conventional Commits, enforced and guided: a step-by-step prompt, a
-  commit-message check, a pre-push check and a CI check.
-- A GitHub Actions workflow running `biome ci`.
-- `lintlane ui`: a local dashboard with a Lint tab (errors and fixes as a
-  diff) and a CI tab (lint, typecheck, build and tests run locally).
+A code-quality workflow for JavaScript, React and Next.js projects. lintlane
+**orchestrates proven tools instead of reimplementing them**: one command wires
+them together, one config drives the checks everywhere, and a local dashboard
+shows what your CI will say before you push.
+| Job                                  | Tool                                                      |
+| ------------------------------------ | --------------------------------------------------------- |
+| Formatting and linting               | [Biome](https://biomejs.dev)                              |
+| Staged files (partial staging safe)  | [lint-staged](https://github.com/lint-staged/lint-staged) |
+| Git hooks                            | [Husky](https://typicode.github.io/husky)                 |
+| Guided Conventional Commits          | [Commitizen](https://commitizen.github.io/cz-cli/)        |
+| Commit message validation            | [commitlint](https://commitlint.js.org)                   |
+| Setup, checks, CI, doctor, dashboard | **lintlane**                                              |
 ## Contents
 - [Quick start](#quick-start)
-- [Commands at a glance](#commands-at-a-glance)
 - [Requirements](#requirements)
-- [`init`](#init--one-time-project-setup)
-- [`check`, `check:fix`, `ci`](#check-checkfix-ci--run-biome)
-- [Commit workflow](#commit-workflow)
-  - [`commit`](#commit--guided-conventional-commit)
-  - [`check-commit`](#check-commit--validate-commit-messages)
-  - [Hooks: how a bad commit gets caught](#hooks-how-a-bad-commit-gets-caught)
-  - [Settings](#settings)
-  - [Skipping a check](#skipping-a-check)
-- [Dashboard (`ui`)](#dashboard-ui)
+- [Commands](#commands)
+- [`init`](#init--one-time-setup)
+- [Checks: one config for CLI, dashboard and CI](#checks-one-config-for-cli-dashboard-and-ci)
+- [Git hooks](#git-hooks)
+- [Commits](#commits)
+- [`doctor`](#doctor)
+- [Dashboard](#dashboard-ui)
 - [Presets](#presets)
-- [Manual setup (without the CLI)](#manual-setup-without-the-cli)
+- [Migrating from lintlane 3.x](#migrating-from-lintlane-3x)
 - [Troubleshooting](#troubleshooting)
-- [Reference](#reference)
+- [Security](#security)
+- [Limitations](#limitations)
 - [Developing lintlane](#developing-lintlane)
 ## Quick start
 ```sh
-# 1. In your React project (a git repository with a package.json):
-bunx lintlane init
+# In a git repository with a package.json. Preview first, if you like:
+npx lintlane init --dry-run
+npx lintlane init
-# 2. Fix what Biome can fix, see what's left:
-bunx lintlane check:fix
-bunx lintlane check
-# 3. Open the dashboard to review issues and run your CI checks locally:
-bunx lintlane ui
+npx lintlane doctor      # verify the setup
+npx lintlane run         # Biome + typecheck + build + tests, like CI
+npx lintlane ui          # the dashboard
 ```
-From then on, `git commit` is guided and checked, and every push is checked
-before it leaves your machine.
-> The first `bunx lintlane init` downloads the package. After that it's
-> installed in your project, so `bunx lintlane …` (or `npx lintlane …`,
-> `bun run lintlane …`) runs your local copy without touching the network.
-## Commands at a glance
-| Command                                         | What it does                                                    |
-| ----------------------------------------------- | --------------------------------------------------------------- |
-| `lintlane init [flags]`                         | One-time setup: installs, writes config, scripts, hooks and CI. |
-| `lintlane check [paths]`                        | Run `biome check` (lint + format), no changes.                  |
-| `lintlane check:fix [paths]`                    | Run `biome check --write`: apply safe fixes.                    |
-| `lintlane ci [paths]`                           | Run `biome ci --reporter=github` (what CI runs).                |
-| `lintlane commit [flags] [-- <git args>]`       | Guided Conventional Commit (alias `c`).                         |
-| `lintlane check-commit [flags]`                 | Validate commit messages (a message, a file or a git range).    |
-| `lintlane ui [flags]`                           | Open the local dashboard (Lint + CI tabs).                      |
-| `lintlane -h` / `commit -h` / `check-commit -h` | Show help.                                                      |
-Every command except `init` runs from the project root. Examples below use
-`bunx lintlane …`; if you've installed it, `bun run lintlane …`,
-`npx lintlane …` or `node_modules/.bin/lintlane …` work too.
 ## Requirements
-- **Bun 1.2 or newer** to run the CLI (`init`, `check`, `check:fix`, `ci`,
-  `commit`, `check-commit`, `ui`). The CLI is a Bun script.
-- **Your project does not need to use Bun.** `init` detects npm, pnpm, Yarn or
-  Bun and uses that package manager.
-- **Git hooks only need Node** (18 or newer): they're plain Node scripts with no
-  extra dependencies, so teammates don't need Bun to commit or push.
-- **Biome 2.2 up to (not including) 3.** It's a peer dependency; `init` installs it.
-- **Git**, for the commit workflow.
-- **macOS or Linux** for the guided prompt on a plain `git commit` (it reads the
-  terminal through `/dev/tty`). Elsewhere that prompt is skipped; messages are
-  still validated, and `lintlane commit` still works. Not tested on Windows.
+- **Node.js 22 or newer.** Any package manager: npm, pnpm, Yarn or Bun
+  (`npx`, `pnpm dlx`, `yarn dlx`, `bunx`). `init` detects which one you use.
+- **Biome 2.2 up to (not including) 3**, a peer dependency that `init` installs.
+- **Git**.
+- macOS or Linux for the guided prompt on a plain `git commit` (it reads the
+  terminal through `/dev/tty`). Windows is untested; see [Limitations](#limitations).
-## `init` — one-time project setup
+## Commands
-```sh
-bunx lintlane init
-```
+| Command                     | What it does                                                                              |
+| --------------------------- | ----------------------------------------------------------------------------------------- |
+| `init [--dry-run]`          | Install and configure everything. Safe to re-run; never overwrites your config.           |
+| `doctor [--json]`           | Diagnose the setup. Read-only. Exit code 1 only if something is broken.                   |
+| `run [checks…]`             | Run the project's checks in order (`--list`, `--keep-going`).                             |
+| `check`, `check:fix`, `ci`  | Run `biome check`, `biome check --write`, `biome ci`.                                     |
+| `commit` (`c`)              | Guided Conventional Commit, run by Commitizen. Git flags go after `--`.                   |
+| `check-commit`              | Validate messages with commitlint: `--message`, `--commit-msg-file`, `--rev-range`, `-d`. |
+| `ui [--port n] [--no-open]` | The local dashboard.                                                                      |
-`init` installs `@biomejs/biome`, `lintlane` and (unless `--no-hooks`)
-`husky`, then writes:
-| File / change                 | Purpose                                                           |
-| ----------------------------- | ----------------------------------------------------------------- |
-| `biome.json`                  | Extends the preset. If one exists, it only tells you what to add. |
-| `package.json` scripts        | `check`, `check:fix`, and `prepare` (runs husky).                 |
-| `.husky/pre-commit`           | Biome on staged files, auto-fixing what it can.                   |
-| `.husky/commit-msg`           | Rejects messages that aren't Conventional Commits.                |
-| `.husky/prepare-commit-msg`   | Guided prompt when you run a plain `git commit`.                  |
-| `.husky/pre-push`             | Checks every commit about to be pushed.                           |
-| `.github/workflows/biome.yml` | `biome ci`, plus a commit-message check on pull requests.         |
-### Flags
-| Flag               | Effect                                                                  |
-| ------------------ | ----------------------------------------------------------------------- |
-| `--preset <name>`  | `base`, `strict` or `next`; overrides auto-detection.                   |
-| `--no-hooks`       | Skip husky and every git hook (also leaves the commit check out of CI). |
-| `--no-commit-lint` | Keep the pre-commit hook; skip the commit-message hooks and CI check.   |
-| `--no-ci`          | Skip the GitHub Actions workflow.                                       |
-| `--skip-install`   | Print the install command instead of running it.                        |
-| `-h`, `--help`     | Show usage.                                                             |
+## `init` — one-time setup
 ```sh
-bunx lintlane init                                   # everything, preset auto-detected
-bunx lintlane init --preset strict                   # force a preset
-bunx lintlane init --no-commit-lint                  # lint hook only, no commit rules
-bunx lintlane init --no-hooks --no-ci                # just biome.json and scripts
-bunx lintlane init --skip-install                    # you install packages yourself
-bunx lintlane init --preset next --no-ci
+npx lintlane init [--dry-run] [--preset base|strict|next] [--no-hooks] [--no-commit-lint] [--no-ci] [--skip-install]
 ```
-### Preset auto-detection
-Without `--preset`, `init` reads your `package.json` dependencies:
+It installs `@biomejs/biome`, `lintlane` and (with hooks) `husky` as exact dev
+dependencies — only those that are missing, so a Biome or Husky version you
+already pin is never bumped — then adds only what is missing:
-| Found in dependencies                             | Preset used |
-| ------------------------------------------------- | ----------- |
-| `next`                                            | `next`      |
-| `@tanstack/react-start`, `@tanstack/start`        | `base`      |
-| `@react-router/dev` (React Router framework mode) | `base`      |
-| `@remix-run/react`, `@remix-run/node`             | `base`      |
-| `react` (no framework above)                      | `base`      |
-| none of the above                                 | `base`      |
+- `biome.json` extending the detected preset (Next.js → `next`; React, TanStack
+  Start, React Router, Remix → `base`; `strict` only when you ask).
+- `check`, `check:fix` and `prepare` scripts.
+- a `lint-staged` entry in `package.json` that runs Biome on staged files.
+- `commitlint.config.mjs` and `config.commitizen` in `package.json`.
+- `.husky/pre-commit`, `commit-msg`, `prepare-commit-msg`, `pre-push`.
+- `.github/workflows/biome.yml`, generated from your [checks](#checks-one-config-for-cli-dashboard-and-ci).
-Only Next.js has its own Biome lint domain, so it's the only framework that
-changes which preset is used. `init` says what it detected either way.
-`strict` is never auto-selected; pass `--preset strict` when you want it.
+**`--dry-run`** prints every action (including the install command) and changes
+nothing. **Re-running** is safe: whatever exists is reported and left alone. An
+untouched hook from an older lintlane is upgraded; an edited one is never
+rewritten, only reported. Existing lint-staged, commitlint and Commitizen
+configuration is kept as it is.
-### Package manager detection
+The package manager comes from the `packageManager` field, then a lockfile, then
+the tool that launched lintlane, then npm.
-`init` reads the `packageManager` field in `package.json`, otherwise whichever
-lockfile is present (`bun.lock`, `package-lock.json`, `pnpm-lock.yaml`,
-`yarn.lock`), and falls back to Bun. It uses that package manager's install
-command and writes matching CI setup steps.
+## Checks: one config for CLI, dashboard and CI
-### Safe to re-run
+`lintlane run`, the dashboard's CI tab and the generated workflow all read the
+same list, detected from `package.json`:
-`init` never overwrites an existing `biome.json`/`biome.jsonc`, script, hook or
-workflow file; it prints a `!` warning for whatever already exists and writes
-only what's missing. That makes it the way to **upgrade**: update the package,
-then run `init` again to pick up hooks added in newer versions.
+| id          | Runs                                                                                                                |
+| ----------- | ------------------------------------------------------------------------------------------------------------------- |
+| `install`   | Frozen-lockfile install (off by default locally)                                                                    |
+| `biome`     | `biome ci .`                                                                                                        |
+| `typecheck` | script `typecheck`, `type-check`, `check-types` or `tsc`; else `tsc --noEmit` locally when a `tsconfig.json` exists |
+| `build`     | script `build`                                                                                                      |
+| `test`      | script `test` (npm's placeholder is ignored)                                                                        |
-## `check`, `check:fix`, `ci` — run Biome
-These wrap the Biome binary installed in your project, so you never need
-Biome's own flags:
-```sh
-bunx lintlane check            # biome check .                      (read-only)
-bunx lintlane check:fix        # biome check --write .              (applies safe fixes)
-bunx lintlane ci               # biome ci --reporter=github .       (CI-formatted output)
+Tune it in `package.json`:
-bunx lintlane check src/                       # limit to paths
-bunx lintlane check:fix src/components/Button.tsx
-bunx lintlane ci src/ tests/
-```
-The exit code is Biome's, so they work in scripts and CI. If Biome isn't
-installed yet they say so and point you to `init`.
-`init` also adds plain `check` and `check:fix` scripts to `package.json` that
-call `biome` directly, so `npm run check` (or `pnpm`/`yarn`/`bun run check`)
-works without Bun:
-```sh
-npm run check
-npm run check:fix
-```
-## Commit workflow
-`init` sets up [Conventional Commits](https://www.conventionalcommits.org)
-(`type(scope): subject`), which keeps history readable and works with changelog
-and release tooling. The `commit` and `check-commit` commands and flags follow
-[Commitizen](https://commitizen-tools.github.io/commitizen/) where they overlap
-(`check-commit` is Commitizen's `cz check`; it isn't called `check` because
-`lintlane check` runs Biome).
-**The format**
-```text
-type(scope): subject
-optional body
-optional footer, e.g. Closes #123
-BREAKING CHANGE: what breaks and how to migrate
+```json
+{
+  "lintlane": {
+    "checks": { "build": false, "test": "test:unit" }
+  }
+}
 ```
-- **Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`,
-  `build`, `ci`, `chore`, `revert`.
-- The scope is optional. The subject is required, shouldn't end in a period,
-  and the header must stay under 100 characters.
-- A breaking change is marked with `!` (`feat(api)!: …`) plus a
-  `BREAKING CHANGE:` footer.
-- Messages starting with `Merge`, `Revert`, `Pull request`, `fixup!`,
-  `squash!` or `amend!` are left alone.
+`false` turns a check off everywhere, a string names the script to run, `true`
+keeps the detected one. Unknown ids or missing scripts are reported by `doctor`
+and the dashboard instead of failing silently. Only script names come from
+config, never command lines.
-### `commit` — guided Conventional Commit
+The workflow is written once by `init`; after changing checks, `lintlane doctor`
+tells you which CI steps are missing.
-```sh
-git add <files>
-bunx lintlane commit        # alias: bunx lintlane c
-```
+## Git hooks
-Asks seven questions — **type, scope, subject, body, breaking change, footer,
-confirm** — then runs `git commit` with the result, so your pre-commit and
-commit-msg hooks still run. It refuses if nothing is staged. Ctrl+C at any
-step cancels with no commit made. Invalid answers (an empty subject, a trailing
-period, an over-long header) are explained and asked again.
-| Flag                             | Effect                                                               |
-| -------------------------------- | -------------------------------------------------------------------- |
-| `--dry-run`                      | Show the message without committing.                                 |
-| `--write-message-to-file <file>` | Write the message to a file (combine with `--dry-run`).              |
-| `--retry`                        | Reuse your last message after a failed commit, without asking again. |
-| `--no-retry`                     | Always ask, even if `retryAfterFailure` is set.                      |
-| `-l`, `--message-length-limit`   | Maximum header length (`0` = no limit).                              |
-| `-h`, `--help`                   | Show help for this command.                                          |
-| `-- <git args>`                  | Everything after `--` is passed to `git commit`.                     |
+Hooks are Husky scripts that call `lintlane hook <name>`, which runs the real tool:
-```sh
-bunx lintlane commit                    # ask, then commit the staged changes
-bunx lintlane commit -- -a              # stage all tracked changes, then commit
-bunx lintlane commit -- -a -S           # …and sign the commit
-bunx lintlane commit -- -s              # add a Signed-off-by line
-bunx lintlane commit -- -n              # skip git hooks
-bunx lintlane commit --dry-run          # just print the message
-bunx lintlane commit --dry-run --write-message-to-file msg.txt
-bunx lintlane commit -l 72              # stricter header limit for this commit
-```
-**Retrying after a failed commit.** If a hook (for example Biome in pre-commit)
-rejects the commit after you've answered the questions, the message is kept.
-Fix the problem, stage the fix, then run `bunx lintlane commit --retry` — no
-re-typing. The saved message is cleared once a commit succeeds. Set
-`retryAfterFailure` (see [Settings](#settings)) to reuse it automatically.
+| Hook                 | Does                                                                                                                                                                                                     |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pre-commit`         | **lint-staged** runs `biome check --write` on staged files. Partially staged files keep their unstaged edits; nothing you didn't stage is committed. A lint error blocks the commit and changes nothing. |
+| `commit-msg`         | **commitlint** validates the message.                                                                                                                                                                    |
+| `prepare-commit-msg` | A plain `git commit` opens the **Commitizen** prompt (skipped for `-m`, merges, amends, CI, no terminal, `LINTLANE_NO_PROMPT=1`).                                                                        |
+| `pre-push`           | **commitlint** checks every commit being pushed, catching `--no-verify` and GUI clients.                                                                                                                 |
-### `check-commit` — validate commit messages
+Customize staged-file processing in the `lint-staged` key of `package.json` (or
+any lint-staged config file). Bypass once with `git commit --no-verify`.
-Give it exactly one thing to check:
+## Commits
 ```sh
-bunx lintlane check-commit --message "feat: add login"          # a message
-echo "feat: add login" | bunx lintlane check-commit             # …or from stdin
-bunx lintlane check-commit --commit-msg-file .git/COMMIT_EDITMSG
-bunx lintlane check-commit --rev-range origin/main..HEAD        # every commit in a range
-bunx lintlane check-commit -d                                   # shorthand for <default branch>..HEAD
-```
-| Flag                           | Effect                                                |
-| ------------------------------ | ----------------------------------------------------- |
-| `--message <msg>`              | Check this message (or pipe one in on stdin).         |
-| `--commit-msg-file <path>`     | Check the message in a file.                          |
-| `--rev-range <range>`          | Check every commit in a git range, e.g. `main..HEAD`. |
-| `-d`, `--use-default-range`    | Same as `--rev-range <default branch>..HEAD`.         |
-| `--allow-abort`                | Accept an empty message.                              |
-| `--allowed-prefixes <prefix>`  | Skip messages starting with this (repeatable).        |
-| `-l`, `--message-length-limit` | Maximum header length (`0` = no limit).               |
-Exit codes: `0` everything passed, `1` a message was rejected, `2` a usage or
-git error. For a range, the output lists each bad commit with its hash and why.
-### Hooks: how a bad commit gets caught
-Four layers, so a mistake is stopped somewhere:
-| Layer                | Catches                                                                                                             |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `prepare-commit-msg` | A plain `git commit` (no `-m`): walks you through the steps instead of opening an empty editor.                     |
-| `commit-msg`         | `git commit -m "test"`: rejects a message in the wrong format, and says why.                                        |
-| `pre-push`           | Commits that skipped the hooks (`--no-verify`, GUI clients, a fresh clone): checks every commit about to be pushed. |
-| CI (pull requests)   | Anything that still got through: checks the commits in the PR.                                                      |
-```text
-$ git commit -m "test"
-✘ Commit message rejected
-  • The header must look like "type(scope): subject", e.g. "feat(auth): add login form".
-  Format:   type(scope): subject
-  Example:  feat(auth): add login form
-  Types:    feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+npx lintlane commit            # guided prompt
+npx lintlane commit -- -S      # extra args go to git commit
+npx lintlane check-commit --message "feat: add login"
+npx lintlane check-commit --rev-range origin/main..HEAD
 ```
-Notes:
-- On a plain `git commit` the prompt's answer pre-fills your editor, and the
-  message is validated again afterwards. `git commit --amend`, `-m` and `-F`
-  skip the prompt but not the validation.
-- The prompt steps aside in CI, when `LINTLANE_NO_PROMPT` is set, and
-  whenever there's no terminal (editors and GUI clients that commit for you).
-- Hooks run only once git hooks are installed. `init` does this, and teammates
-  get them from `install` through the `prepare` script (`husky`).
-- The pre-push hook checks the commits being pushed (for a new branch: those
-  not already on the remote). Tag pushes and branch deletions are ignored.
-### Settings
-Optional, in your `package.json`:
+Rules come from `commitlint.config.mjs`, which by default is
+`export { default } from "lintlane/commitlint"`: Conventional Commits, plus the
+optional block below. Replace the file with your own config any time.
 ```json
 {
@@ -323,119 +156,52 @@ Optional, in your `package.json`:
     "commit": {
       "types": ["feat", "fix", "chore"],
       "messageLengthLimit": 72,
-      "allowedPrefixes": ["WIP"],
-      "retryAfterFailure": true
+      "allowedPrefixes": ["WIP"]
     }
   }
 }
 ```
-| Key                  | Meaning                                                                                                    |
-| -------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `types`              | Allowed types. A list of names, or `{ "feat": "A new feature" }` to give each a description in the prompt. |
-| `messageLengthLimit` | Maximum header length. `0` turns the check off. Default `100`.                                             |
-| `allowedPrefixes`    | Extra message prefixes to skip (added to the built-in ones).                                               |
-| `retryAfterFailure`  | Reuse your last message automatically after a failed commit. Default `false`.                              |
-The settings apply to the hooks, `commit` and `check-commit`. Command-line flags
-override them for that run.
-### Skipping a check
-| To skip…                  | Do this                                                                 |
-| ------------------------- | ----------------------------------------------------------------------- |
-| The commit hooks, once    | `git commit --no-verify` (the pre-push hook and CI still check it).     |
-| The pre-push check, once  | `git push --no-verify` (CI still checks pull requests).                 |
-| Only the guided prompt    | Set `LINTLANE_NO_PROMPT=1`.                                             |
-| Commit rules for everyone | Re-run `init --no-commit-lint` on a fresh project, or delete the hooks. |
-### Adding the CI step to an existing workflow
-`init` adds the commit-message check only to newly generated workflows. To add
-it to one you already have:
-```yaml
-- uses: actions/checkout@v4
-  with:
-    fetch-depth: 0
-# …after your install step:
-- name: Check commit messages
-  if: github.event_name == 'pull_request'
-  run: node node_modules/lintlane/bin/check-commit.mjs --rev-range origin/${{ github.base_ref }}..HEAD
+The guided prompt is Commitizen's standard `cz-conventional-changelog`
+(`config.commitizen.path = "lintlane/presets/commitizen.cjs"`); configure it like
+any Commitizen adapter.
+## `doctor`
+```sh
+npx lintlane doctor          # human-readable, with a fix for every problem
+npx lintlane doctor --json   # { ok, version, findings: [{ id, status, message, fix? }] }
 ```
+It checks Node, `package.json`, git, the package manager, Biome (and whether it
+is installed in the project, where lint-staged looks for it), lintlane, the
+bundled tools, Husky and `core.hooksPath`, every hook (current, upgradable,
+broken, not executable), lint-staged/commitlint/Commitizen config, your
+`lintlane.checks`, and whether the CI workflow runs your checks. Statuses:
+`pass`, `warn` (missing or out of date), `fail` (broken). It never changes anything.
 ## Dashboard (`ui`)
-`lintlane ui` starts a local dashboard in your browser so you can see what
-would fail before you push:
+`npx lintlane ui` serves a dashboard on `127.0.0.1` and opens it.
-```sh
-bunx lintlane ui              # opens http://127.0.0.1:4321
-bunx lintlane ui --port 5000  # use another port
-bunx lintlane ui --no-open    # print the URL without opening a browser
-```
+- **Lint tab:** Biome diagnostics by file, the proposed fix as a diff, apply
+  fixes per file or all at once. Errors from Biome (can't start, invalid output)
+  are shown with the underlying message; a second check can't start while one runs.
+- **CI tab:** the same checks as `lintlane run` with live output, per-step status
+  and timing, Stop (kills the whole process tree) and stop-on-first-failure.
+  Configuration problems and `doctor` failures appear above the table.
-| Flag         | Effect                                |
-| ------------ | ------------------------------------- |
-| `--port <n>` | Port to listen on (default `4321`).   |
-| `--no-open`  | Don't open the browser automatically. |
-It needs Biome installed in the project (run `init` first). Press Ctrl+C in the
-terminal to stop it. The ☀/☾ button in the header switches between light and
-dark mode; it follows your system setting until you click it, then remembers
-your choice.
-### Lint tab
-Runs `biome check` and shows the result:
-- **Summary cards:** errors, warnings, files with issues, check time.
-- **File table:** each file's worst level, issue count, and whether Biome can fix
-  it. Rows with errors are tinted. Search by file name, message or rule, and
-  filter by All / Errors / Warnings.
-- **Detail panel:** click a file to see each issue (rule, line and column) and
-  the proposed fix as a red/green diff, like `git diff`. Use ↑/↓ (or `j`/`k`) to
-  move between files and `Esc` to close.
-- **Apply fix** writes the fix for one file; **Apply all fixes** applies them to
-  every listed file in one batch. Nothing is written until you click, and the
-  page re-checks afterwards.
-Only Biome's _safe_ fixes are applied (the same ones as `check:fix`). Issues
-with no automatic fix are labelled "Manual". The page lists the first 200 files
-with issues; if there are more, a notice says so and "Apply all fixes" only
-touches the files shown — click it again after the re-check to continue.
-### CI tab
-Runs the checks your CI would run, locally. The steps are detected from your
-project:
-| Step                      | Runs                                                                                                              | On by default |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------- |
-| Install (frozen lockfile) | `bun install --frozen-lockfile`, `npm ci`, or the `pnpm`/`yarn` equivalent                                        | No            |
-| Biome CI (lint + format)  | `biome ci .` — the same check the generated GitHub workflow runs                                                  | Yes           |
-| Typecheck                 | your `typecheck` script (or `type-check`, `check-types`, `tsc`), else `tsc --noEmit` if there's a `tsconfig.json` | Yes           |
-| Build                     | your `build` script                                                                                               | Yes           |
-| Tests                     | your `test` script (skipped if it's npm's "no test specified" placeholder)                                        | Yes           |
-Tick the steps you want, then **Run CI**. Steps run in order with `CI=true`,
-and their output streams into the panel as they run. **Stop on first failure**
-(on by default, like real CI) skips the remaining steps after one fails. At the
-end a banner says either "All N steps passed — safe to push" or "CI would
-fail", naming the first failing step. **Stop** cancels the run and kills the
-running process.
-This is a script-based simulation, not a replica of your workflow: it runs the
-commands above, not the steps in `.github/workflows/*.yml`, and it doesn't
-reproduce CI's environment variables, secrets or Node version. A pass here is a
-strong signal, not a guarantee.
-### Safety
-The server listens on `127.0.0.1` only. Every request needs a random token that
-is part of the URL printed at startup — opening the dashboard without it gives a
-403. The page only sends step ids and file paths; the server decides which
-commands run and refuses paths outside the project.
+### Security
+- Listens on loopback only, on a URL carrying a random per-run token; API calls
+  need the token in a header (compared in constant time).
+- The `Host` header must be `127.0.0.1:<port>` or `localhost:<port>`, which
+  blocks DNS-rebinding attacks from web pages.
+- The page is served with a Content-Security-Policy (per-response script nonce,
+  `default-src 'none'`, `frame-ancestors 'none'`), `nosniff` and `no-referrer`.
+- The browser sends step ids and file paths, never commands. Paths are resolved
+  inside the project and anything outside is refused.
+- Only the checks you configured run, with your project's own scripts.
 ## Presets
@@ -459,156 +225,88 @@ add your own ignores:
 To migrate an existing config into Biome first:
 ```sh
-bunx biome migrate eslint --write
-bunx biome migrate prettier --write
-```
-## Manual setup (without the CLI)
-**Install and configure**
-```sh
-bun add -d -E @biomejs/biome lintlane
-npm install --save-dev --save-exact @biomejs/biome lintlane
-pnpm add --save-dev --save-exact @biomejs/biome lintlane
-yarn add --dev --exact @biomejs/biome lintlane
+npx biome migrate eslint --write
+npx biome migrate prettier --write
 ```
-Create `biome.json`, extending the preset you want:
-```json
-{ "extends": ["lintlane/biome"] }
-```
-(`lintlane/biome/strict` or `lintlane/biome/next` for the others.)
-Add scripts:
-```json
-"check": "biome check .",
-"check:fix": "biome check --write ."
-```
-**Git hooks**
-```sh
-bun add -d husky
-bunx husky init
-```
-Put these in `.husky/`:
-`.husky/pre-commit`
-```sh
-./node_modules/.bin/biome check --write --staged --no-errors-on-unmatched --files-ignore-unknown=true
-git update-index --again
-```
-`.husky/commit-msg`
-```sh
-[ -f node_modules/lintlane/bin/commit-msg.mjs ] || exit 0
-node node_modules/lintlane/bin/commit-msg.mjs "$1"
-```
-`.husky/prepare-commit-msg`
-```sh
-[ -f node_modules/lintlane/bin/prepare-commit-msg.mjs ] || exit 0
-node node_modules/lintlane/bin/prepare-commit-msg.mjs "$1" "$2"
-```
-`.husky/pre-push`
-```sh
-[ -f node_modules/lintlane/bin/pre-push-check.mjs ] || exit 0
-node node_modules/lintlane/bin/pre-push-check.mjs "$1" "$2"
-```
-Commits with errors Biome can't fix are blocked until you resolve them.
+## Migrating from lintlane 3.x
+lintlane 4 replaces its own staged-file and commit code with the tools above.
+1. Upgrade: `npm install -D lintlane@4` (or your package manager's equivalent).
+2. Run `npx lintlane init --dry-run`, then `npx lintlane init`. Untouched 3.x
+   hooks are upgraded; a hook you edited is left alone and reported.
+3. Run `npx lintlane doctor`.
+**Breaking changes**
+- `lintlane` now has runtime dependencies (lint-staged, commitlint, Commitizen).
+- `bin/pre-commit.mjs`, `commit-msg.mjs`, `prepare-commit-msg.mjs`,
+  `pre-push-check.mjs` are gone. Hooks that call them do nothing, which `doctor`
+  reports as a failure. `pre-commit.mjs --restore` is gone too: lint-staged
+  keeps its own backup stash.
+- `lintlane commit` is Commitizen. `--write-message-to-file` and `-l` are gone;
+  `--dry-run`, `--retry`, `-a`, `-S` work as in Commitizen, `-- <git args>` as before.
+- `check-commit`: `--allow-abort`, `--allowed-prefixes` and `-l` are gone; set
+  `lintlane.commit.allowedPrefixes` / `messageLengthLimit` or edit the commitlint config.
+- Commit settings `retryAfterFailure` is gone (use `lintlane commit --retry`).
+  Custom `types` still apply to commitlint but no longer to the prompt; configure
+  the prompt through Commitizen.
+- The CI workflow now runs every detected check (typecheck, tests, build), not
+  only Biome, and the commit check calls `lintlane check-commit`. Existing
+  workflows are not rewritten; turn checks off with `lintlane.checks`.
+- Messages are formatted by commitlint, so wording of rejections changed.
 ## Troubleshooting
-**`bunx lintlane …` downloads the package each time, or says "command not found".**
-Outside a project that has it installed, `bunx` fetches `lintlane` from npm.
-Run `bunx lintlane init` in the project first (or install `lintlane` as a dev
-dependency), after which `bunx lintlane …` uses the local copy.
-**Hooks don't run.** Run your package manager's install (the `prepare` script
-runs husky), or run `node_modules/.bin/husky` once. Check
-`git config core.hooksPath` prints `.husky/_`.
-**The guided prompt doesn't appear on `git commit`.** It's skipped when `CI` or
-`LINTLANE_NO_PROMPT` is set, when you pass `-m`/`-F` or amend, when there's no
-terminal (GUI clients, some editors) and on systems without `/dev/tty`. Run
-`bunx lintlane commit` for the same steps. The message is validated regardless.
-**A commit was rejected and I lost my message.** Use
-`bunx lintlane commit --retry` if you committed through `lintlane commit`.
-**The pre-commit hook blocks my commit.** Biome found an error it can't fix.
-Run `bunx lintlane check` to see it, or open `bunx lintlane ui`. Fix it and
-commit again.
-**Push blocked: "commit message(s) don't follow Conventional Commits".** Reword
-the listed commits with `git rebase -i` (or `git commit --amend` for the latest),
-then push again.
-**`init` says a file already exists.** That's expected; `init` never overwrites.
-Delete the file and re-run `init` if you want lintlane's version.
-**The dashboard shows "Unauthorized" / 403.** Open the exact URL printed when
-`lintlane ui` started; it contains a one-time token.
-**Biome seems slow on a big project.** Add ignores for build output in your
-`biome.json` (for example `dist`, `.next`, `build`, `coverage`) so Biome doesn't
-scan them.
-## Reference
-**Environment variables**
-| Variable             | Effect                                                                            |
-| -------------------- | --------------------------------------------------------------------------------- |
-| `LINTLANE_NO_PROMPT` | Set to any value to skip the guided prompt on `git commit`.                       |
-| `CI`                 | When set, the guided prompt is skipped. The CI tab sets it for the steps it runs. |
-| `NO_COLOR`           | Turns off colors in the prompt.                                                   |
-**Exit codes**
-| Command                    | Codes                                                                                               |
-| -------------------------- | --------------------------------------------------------------------------------------------------- |
-| `check`, `check:fix`, `ci` | Biome's exit code.                                                                                  |
-| `commit`                   | `0` committed (or dry run), `1` cancelled, git's own exit code if the commit failed, `2` bad flags. |
-| `check-commit`             | `0` valid, `1` rejected, `2` usage or git error.                                                    |
-| `ui`                       | Runs until you stop it.                                                                             |
-**Files lintlane may create or use**
-| Path                                                                | What                                           |
-| ------------------------------------------------------------------- | ---------------------------------------------- |
-| `biome.json`                                                        | Biome config extending a preset.               |
-| `.husky/pre-commit`, `commit-msg`, `prepare-commit-msg`, `pre-push` | Git hooks.                                     |
-| `.github/workflows/biome.yml`                                       | CI workflow.                                   |
-| `.git/lintlane-commit-msg`                                          | Your last message, kept after a failed commit. |
+Start with `npx lintlane doctor`; each problem comes with a fix.
+| Symptom                                      | Likely cause / fix                                                                                                       |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Hooks don't run                              | `core.hooksPath` isn't `.husky/_`. Run your package manager's `husky` (via `install`, which runs `prepare`).             |
+| "lintlane: node_modules/lintlane not found"  | Dependencies aren't installed. Run your package manager's install.                                                       |
+| `biome: command not found` in pre-commit     | Biome isn't a dependency of the project. Install `@biomejs/biome`.                                                       |
+| lint-staged: "no configuration found"        | Add a `lint-staged` key (run `init`).                                                                                    |
+| commitlint: "Please add rules"               | Missing `commitlint.config.mjs` (run `init`).                                                                            |
+| `lintlane commit` says no adapter configured | Add `config.commitizen.path` (run `init`).                                                                               |
+| No prompt on `git commit`                    | Expected for `-m`, merges, amends, CI, GUI clients, Windows. Use `lintlane commit`.                                      |
+| Old hook silently does nothing               | It calls a 3.x file that no longer exists. `init` upgrades untouched ones; see [Migrating](#migrating-from-lintlane-3x). |
+| Dashboard says Forbidden                     | Open the exact URL printed by `lintlane ui` (it includes the token).                                                     |
+| CI doesn't run a check                       | The workflow predates the check. Add the step, or disable the check under `lintlane.checks`.                             |
+## Limitations
+- Windows isn't tested. The CLI avoids Unix-only APIs, but the guided prompt on
+  `git commit` is skipped there and CI here runs on Ubuntu and macOS only.
+- The generated workflow targets GitHub Actions.
+- The guided prompt uses the standard Conventional Commits adapter.
+- lint-staged and commitlint behavior, including their config discovery, is theirs;
+  see their docs for advanced setups (monorepos, per-folder configs).
 ## Developing lintlane
-To try a local build in a test app before publishing:
+Requires Node.js 22 or newer.
 ```sh
-# In the lintlane repo:
-npm pack --pack-destination /tmp/lintlane-pack     # builds lintlane-<version>.tgz
-# In a throwaway app (a git repo with a package.json):
-bun add --dev --exact @biomejs/biome husky /tmp/lintlane-pack/lintlane-<version>.tgz
-node_modules/.bin/lintlane init --skip-install      # the package isn't on npm yet
-node_modules/.bin/husky
+npm test                  # unit + integration tests (about 40 seconds, no network)
+npm run test:e2e          # real npm / pnpm / yarn / bun installs (needs network)
+npm run check             # lint and format this repository
+npm run verify:release [npm|pnpm|yarn|bun]   # pack, install in a fresh project, init, doctor, real commits
 ```
-If you rebuild without changing the version, Bun may reuse its cached tarball:
-run `bun pm cache rm`, delete `node_modules/lintlane`, and reinstall (or
-bump the version first). `npm pack --dry-run` lists what would be published.
+| File                             | What it covers                                                                              |
+| -------------------------------- | ------------------------------------------------------------------------------------------- |
+| `test/hooks.test.mjs`            | Real git: pre-commit (partial staging, failures), commit-msg, prepare-commit-msg, pre-push. |
+| `test/setup.test.mjs`            | `init --dry-run`, idempotency, upgrades from 3.x hooks, `doctor`.                           |
+| `test/checks.test.mjs`           | The shared checks list, generated CI, `lintlane run`.                                       |
+| `test/cli.test.mjs`              | Running on Node without Bun, packaging, `init`. Package managers are **mocked** here.       |
+| `test/package-managers.test.mjs` | Package-manager detection and command generation (pure).                                    |
+| `test/ui.test.mjs`               | Dashboard: auth, Host/CSP hardening, every API route, Stop.                                 |
+| `test/e2e.test.mjs`              | **Real** package managers and the packed tarball. Needs `LINTLANE_E2E=1`.                   |
+CI (`.github/workflows/ci.yml`) runs the tests on Ubuntu and macOS with Node 22
+and 24, and `verify:release` for each package manager. To try a local build,
+set `LINTLANE_INSTALL_SPEC` to a tarball from `npm pack` when running `init`.
 ## License