fairlead 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.2.0 (2026-09-26)
+
+### New
+
+- `fairlead plan` lists the tests and checks the changes since a base commit can reach, and why each one is in. It builds an import graph of JavaScript and TypeScript from source, with no install, following tsconfig paths and workspace packages, and caches parsed files by git blob. It adds owner rules, test classes (`unit`, `own`, `demand`, `canary`), checks, and a run-everything fallback for anything it can't read with certainty. The plan is JSON with a published schema. See [Test plan](https://mahkassem.github.io/fairlead/docs/plan.html).
+- `fairlead test --explain` says why a test or check is in the plan, or why it isn't.
+- `fairlead ci plan` plans the checked-out commit and, with `--format github`, sets step outputs. `fairlead ci run --plan` runs the plan's invocations. The GitHub Action installs Fairlead and runs any command. See [Plans in CI](https://mahkassem.github.io/fairlead/docs/ci.html).
+- `fairlead graph stats`, `why` and `importers` inspect the import graph.
+- `fairlead replay fetch` records a repository's pull request and merge queue runs from GitHub. `fairlead replay run` re-plans every recorded failure and reports recall: each failure is a hit, a miss, flaky, unconfirmed, or quarantined. `[[replay.quarantine]]` declares a test flaky in named jobs, with evidence and an expiry, and applies only while the data bears it out. See [Replay](https://mahkassem.github.io/fairlead/docs/replay.html).
+- Opt-in lockfile scoping (`plan.lockfile = "scope"`): a pnpm lockfile change runs only the packages whose resolved dependencies changed.
+- An owner rule can take a run-all path it covers (`overrides_run_all`), such as a fixture project's runner config.
+- Weekly public benchmarks on Effect, pnpm and vitest, published on the [benchmarks page](https://mahkassem.github.io/fairlead/docs/benchmarks.html).
+
+### Changed
+
+- The minimum Rust version for building from source is 1.90.
+- The site has a front page, and the documentation moved to [/docs/](https://mahkassem.github.io/fairlead/docs/). Old page addresses redirect.
+- Fairlead has a brand: the logo and its colors are in `assets/brand`.
+
+### Recall
+
+Replayed from each project's CI history (run 5 of the weekly benchmarks, planned at `8c1b179d44cc`). Adjusted recall leaves out tests quarantined with evidence; raw counts them.
+
+| Repository | Window | Adjusted recall | Raw recall | Misses |
+| --- | --- | --- | --- | --- |
+| Effect-TS/effect | 2026-05-09 to 2026-08-06 | 98.8% (n=853) | 98.0% (n=890) | 10 |
+| pnpm/pnpm | 2026-04-25 to 2026-07-23 | 99.4% (n=312) | 99.4% (n=312) | 2 |
+| vitest-dev/vitest | 2026-06-13 to 2026-09-10 | 95.6% (n=528) | 93.6% (n=627) | 23 |
+
+Selection is recorded, not yet a gate: the median plan still selects most test files (Effect 98.6%, pnpm 100.0%, vitest 98.7%), and 31.7%, 84.8% and 34.9% of plans ran everything, mostly for CI config, lockfile and `package.json` changes. Narrowing that is the next milestone's work.
+
+A full graph build without the parse cache takes 1.19 s on Effect, 1.02 s on pnpm and 0.41 s on vitest on 4 cores, under the 1.5 s budget, which CI checks on every pull request ([Import graph](https://mahkassem.github.io/fairlead/docs/graph.html#speed)). That's with the files already in the operating system's cache; a first read from a cold disk takes longer.
+
+Quarantined, each until 2026-12-31 and applied only while the data bears it out:
+
+- Effect `packages/sql/mysql2/test/Persistence.test.ts` in the first test shard: times out after 30 s waiting on MySQL on changes that touch neither; 21 failures across 19 pull requests.
+- Effect `packages/sql/mysql2/test/KeyValueStore.test.ts` in the second test shard: its setup hook times out waiting on MySQL; 9 failures across 9 pull requests.
+- Effect `packages/sql/d1/test/Resolver.test.ts` in the second Node shard: times out after 5 s against the local D1 engine; 7 failures across 7 pull requests.
+- vitest `test/typescript/test/typechecker.test.ts` in the Windows unit job only: out-of-memory crashes and missing-command cases. It was declared on 60 failures across 36 pull requests, while the same job passed 356 times, and has absorbed 100 failures across 54 pull requests.
+
+Every miss, with its cause:
+
+- Effect, 10: database and service tests failing together on unrelated changes (`sql-libsql` Client 3, `platform-node` NodeRedis 1, SqlRunnerStorage 1, `sql-pg` Client 1 on a LISTEN notification timeout, `sql-libsql` Resolver 1 on a 5 s timeout); `toArbitrary.test.ts` 1, a property test that failed after 8 random cases; `openapi-generator` 2, a native module error (`Failed to recover TsconfigCache type from napi value`) under Deno on a change to `platform-deno`.
+- pnpm, 2: `releasing/commands/test/change/index.test.ts` on Linux and Windows, a missing `CHANGELOG.md` fixture, on a pull request that only edited a test helper in another package.
+- vitest, 23: headless browser specs 14 (`runner.test.ts` 9, fixtures failing inside it: a 249 ms locator click timeout in 5, a CDP events test in 3 (both recurring across unrelated pull requests) and a WebKit clipboard test on Windows in 1; `trace.test.ts`, `bail-out.test.ts`, `locators.test.ts`, `server-url.test.ts` and `to-match-screenshot.test.ts` 1 each, timing and Windows snapshot mismatches); `detect-async-leaks.test.ts` 6, the same leak assertion across unrelated pull requests and bases; `list.test.ts` and `open-telemetry.test.ts` 2, a browser that didn't close within 10 s; `coverage-test/reporters.test.ts` 1, a 15 s timeout on Windows.
+
+The bar we set for this release was 100% recall on failures a change could have caused. By our reading of the logs, none of these misses is one, but that's a judgement, not a measurement: literal 100% recall wasn't reached on any repository, and the misses above are the whole list.
+
+### Fixed
+
+- Replay waits out GitHub's secondary rate limit instead of stopping, and asks once per lookup.
+
 ## 0.1.1 (2026-09-26)
 
 ### New

package/README.md

@@ -1,36 +1,122 @@
-# Fairlead
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mahkassem/fairlead/main/assets/brand/fairlead-reversed-horizontal-dark.svg">
+    <img alt="Fairlead" src="https://raw.githubusercontent.com/mahkassem/fairlead/main/assets/brand/fairlead-primary-horizontal-light.svg" width="360">
+  </picture>
+</p>
 
-Guardrails and a guided path for coding agents.
+<p align="center"><strong>Guardrails and a guided path for coding agents.</strong></p>
+
+<p align="center">
+  <a href="https://github.com/mahkassem/fairlead/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/mahkassem/fairlead/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/mahkassem/fairlead/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/mahkassem/fairlead?color=008F67"></a>
+  <a href="https://mahkassem.github.io/fairlead/docs/"><img alt="Docs" src="https://img.shields.io/badge/docs-book-0B1618"></a>
+</p>
 
 A fairlead is the fitting on a boat that keeps a line running true, so it
 doesn't chafe, tangle or pull off course. Fairlead does that for an agent
-working in your repository:
-
-- **Guards:** your project's rules run as hooks on every edit and command,
-  so a wrong move is stopped with the right command instead of failing CI
-  minutes later.
-- **Guides:** the agent asks what applies to the files in front of it and
-  what its next step is, instead of reading pages of instructions.
-- **Tests smart:** a change runs the tests it can reach, plus a canary set.
-  Main and nightly still run everything.
-- **Remembers, within limits:** small per-module memory with caps and review
-  dates. A lesson becomes a check or it expires.
-- **Measures:** speed, rework, escaped defects, tokens and cost, as counts
-  only. It never phones home.
-
-It is one Rust binary, works in any repository, and supports Claude Code
-first and Codex next.
+working in your repository. It is one Rust binary with no project-specific
+logic: everything about your repository lives in your own `fairlead.toml`.
+
+## Why Fairlead
+
+Join a good team and you don't start from zero. Someone tells you which module
+never to touch without running the migration check first, which test lies on
+Windows, and which "quick fix" broke production last spring. That knowledge is
+why a new engineer is useful in week two instead of month six.
+
+A coding agent gets none of it. It opens your repository cold every time,
+reads the same code again, makes the mistake your team already paid for, and
+finds out in CI that it was an old lesson nobody told it. Fairlead gives every
+repository its own memory, so your agent starts where your team left off instead
+of trying things like a stranger.
+
+- **A memory for every repository.** The hard lessons from past work live with
+  the code, per module, where the agent meets them before it acts. A lesson is
+  kept short, reviewed on a date, and turned into a check when it can be, so
+  the memory stays true instead of growing into noise.
+  *Today:* owner rules record which tests guard which code, and a quarantined
+  test applies only while the evidence holds and until its date.
+- **Set up once, never start cold.** The agent's first job is to learn
+  the repository: its modules, test runners, rules, and the commands that prove
+  a change is right. That goes into one checked config, so every session starts
+  where the last one left off.
+  *Today:* `fairlead config check` validates every layer, and `show --origin`
+  says where each value came from.
+- **The right tool, not the nearest one.** The agent asks what applies to the
+  files in front of it and gets the rule, the command and the next step for
+  exactly those files.
+  *Today:* `fairlead plan` names the tests and checks a change can reach, and
+  `test --explain` says why each one is in or out.
+- **Plans the change, not just the tests.** Before an edit, the agent sees
+  what it's about to touch, everything that depends on it, the rules and
+  lessons recorded there, and what has to pass before it's done. Afterwards,
+  what actually changed is checked against that brief.
+  *Coming in K3* ([#45](https://github.com/mahkassem/fairlead/issues/45)).
+- **The right skills for the code in front of it.** A frontend change
+  shouldn't come with database advice. Fairlead picks the skills that apply to
+  what a change reaches, just as it picks tests, and checks the agent used them.
+  *Coming in K4* ([#43](https://github.com/mahkassem/fairlead/issues/43)).
+- **Measured, not guessed.** Good and bad are numbers: whether the plan would
+  have caught real CI failures, rework, escaped defects, tokens and cost.
+  *Today:* `fairlead replay` re-plans real failures from a repository's CI
+  history, and the [benchmarks](https://mahkassem.github.io/fairlead/docs/benchmarks.html)
+  measure that recall every week.
+- **Fast because it remembers.** No rereading the codebase to rediscover what
+  was learned last week. The graph, the plan and the lessons are already there.
+  *Today:* the import graph is built without installing dependencies and
+  cached between runs.
+- **It learns where it's blind.** When a change reaches no test, Fairlead says
+  so and points at the rule that's missing, so the team's knowledge grows
+  exactly where it was thin.
+  *Today:* `fairlead plan` lists every file no test depends on, and replay
+  suggests the owner rule or check path that would have caught a miss.
+- **Stopped before the mistake, not after.** Your rules run as the agent
+  works, catching a wrong move in seconds instead of minutes later in CI.
+  *Coming in K2.*
+
+## Works with
+
+- **Any test runner.** Vitest, Jest, Playwright, `node --test`, Bun: a runner is
+  one command in your config, so Fairlead never needs a plugin for your stack.
+- **Monorepos, precisely.** pnpm, npm, yarn and bun workspaces. A pnpm lockfile
+  change runs only the packages whose dependencies actually changed.
+- **No install needed to read your code.** The JavaScript and TypeScript import
+  graph comes from source alone, with tsconfig paths resolved and parsed files
+  cached, so a plan takes a fraction of a second.
+- **Your CI, not a new one.** A GitHub Action and `ci plan --format github` for
+  Actions, and a JSON plan with a published schema for any other CI.
+- **Proven on real projects.** Recall is replayed from the CI history of Effect,
+  pnpm and vitest every week, and published.
+- **Private by default.** The CLI sends nothing you didn't ask for: no
+  telemetry, and it never phones home.
+- **One binary, everywhere.** Linux, macOS and Windows, installed with a shell
+  script, PowerShell or npm.
+
+*It reads JavaScript and TypeScript today. More languages, framework packs and
+folders of several repositories are on the way
+([#47](https://github.com/mahkassem/fairlead/issues/47)); Vue, Svelte and Astro
+files fall back to broader test selection until then.*
+
+## What it does today
+
+The test plan (`plan`, `test --explain`), plans in CI (`ci plan`, `ci run` and
+the GitHub Action), `replay`, the import graph (`graph`), and the config
+commands. The [quick start](#quick-start) shows them, and the
+[book](https://mahkassem.github.io/fairlead/docs/) covers each one.
 
 ## Status
 
-Pre-alpha. This release is the bootstrap: `fairlead --version` and
-`fairlead doctor`. The roadmap is milestones K0 to K6 in the
-[issues](https://github.com/mahkassem/fairlead/issues).
+Pre-alpha. The latest release, v0.2.0, ships the test plan, the CI commands
+and action, replay, and the config commands. Its recall on real CI failures,
+with every miss and its cause, is in the [changelog](CHANGELOG.md) and on the
+[benchmarks page](https://mahkassem.github.io/fairlead/docs/benchmarks.html).
+Claude Code comes first, then Codex. The [roadmap](https://mahkassem.github.io/fairlead/docs/roadmap.html)
+has milestones K0 to K6, each an [issue](https://github.com/mahkassem/fairlead/issues)
+with its exit criteria.
 
 ## Install
 
-Once the first release is published:
-
 ```sh
 # macOS and Linux
 curl -fsSL https://github.com/mahkassem/fairlead/releases/latest/download/fairlead-installer.sh | sh
@@ -38,13 +124,30 @@ curl -fsSL https://github.com/mahkassem/fairlead/releases/latest/download/fairle
 # Windows (PowerShell)
 powershell -c "irm https://github.com/mahkassem/fairlead/releases/latest/download/fairlead-installer.ps1 | iex"
 
-# In a JavaScript or TypeScript project
+# In a JavaScript or TypeScript project, as a dev dependency
 bun add -d fairlead   # or: npm i -D fairlead
 ```
 
+Then `fairlead doctor` says which binary, platform and config it would use.
+
+## Quick start
+
+```sh
+fairlead config check                        # validate fairlead.toml
+fairlead plan --base main                    # the tests and checks this branch can affect
+fairlead test --explain src/a.test.ts        # why that test is in the plan, or isn't
+fairlead graph why src/a.test.ts src/util.ts # how one file depends on another
+```
+
 ## Documentation
 
-The book lives in `docs/` and is published to GitHub Pages.
+The site is [mahkassem.github.io/fairlead](https://mahkassem.github.io/fairlead/), and [the book](https://mahkassem.github.io/fairlead/docs/) covers
+install, configuration, the import graph, the test plan, plans in CI, replay
+and the benchmarks. Its source is in `docs/`.
+
+## Brand
+
+The logo, its colors and how to use them are in [`assets/brand`](assets/brand).
 
 ## License
 

package/npm-shrinkwrap.json

@@ -19,7 +19,7 @@
       "hasInstallScript": true,
       "license": "MIT OR Apache-2.0",
       "name": "fairlead",
-      "version": "0.1.1"
+      "version": "0.2.0"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.1.1"
+  "version": "0.2.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/mahkassem/fairlead/releases/download/v0.1.1"
+    "https://github.com/mahkassem/fairlead/releases/download/v0.2.0"
   ],
   "bin": {
     "fairlead": "run-fairlead.js"
@@ -90,7 +90,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.1.1",
+  "version": "0.2.0",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"