fairlead 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.4.0 (2026-09-27)
+
+### New
+
+- `fairlead guard compare FILE` checks the guard against the linter it replaces: it reads the other linter's `file:line rule` lines and fails on any finding one side has and the other doesn't, with `--map` for rule names and `--rules` to narrow it. `fairlead guard bench --since REV` replays the files each commit changed through the write hook and reports p50, p95 and the slowest time, and what it decided; `--p95-under` makes it a check. CI now fails when the write hook's p95 on a generated history goes over 50 ms. See [Checking the guard against your linter](https://mahkassem.github.io/fairlead/docs/guard.html#checking-the-guard-against-your-linter).
+- The git hook: `fairlead hooks install --git` adds the commit stage to `lefthook.yml` by inserting lines, keeping its comments and layout, and uninstall restores it byte for byte. Plain `install` adds it wherever a lefthook config already exists. `fairlead doctor` reports both hooks, whether lefthook will run the git one, whether `fairlead` is on the PATH, and the event log: write-hook decisions, denies by rule, p50 and p95 time, time-outs, errors and commit-stage runs. See [The git hook](https://mahkassem.github.io/fairlead/docs/guard.html#the-git-hook).
+- The write stage: `fairlead hooks install` adds a Claude Code hook that runs `fairlead guard hook` before every edit, and denies one that adds a finding, with the findings as the reason the agent reads (or, with `guard.on_finding = "warn"`, lets it through with them as a note). It never answers "allow", lets a call through whenever it can't decide, and keeps to `guard.budget_ms` (40 by default). `[[guard.commands]]` deny shell commands. `hooks.claude` chooses `.claude/settings.json` (shared, the default) or `.claude/settings.local.json`; `fairlead hooks uninstall` restores the file byte for byte when nobody changed it since. See [The write hook](https://mahkassem.github.io/fairlead/docs/guard.html#the-write-hook).
+
+- More guard rules: `[guard.test_names]` (file names and test titles), `[guard.citations]` (a pointer in a comment must name a heading in a Markdown file), `[guard.migrations]` (a migration that exists at the base may not change, move or go, and numbers are unique), `[[guard.commands]]` (commands an agent may not run, for the write stage), and `[[guard.external]]` (any tool that prints `file:line message` becomes a rule, at the check stage by default or at commit). `guard check --base REV` checks migrations against a base. See [Guard rules](https://mahkassem.github.io/fairlead/docs/guard.html#test-names).
+- Guard presets: `[guard.comments]` checks comment block length by context, comment density, history (dates, names, phrases, measurements), item references outside a pointer form, comments that address the next editor, and block markers, reading comments after code from the syntax tree. `[guard.size]` adds `function_lines`, counting a function's own lines without the functions nested in it. `[guard.cite]` appends a note to a rule's messages. See [Guard rules](https://mahkassem.github.io/fairlead/docs/guard.html#comments).
+- Environments: `FAIRLEAD_ENV=staging` or `--env staging` layers `fairlead.staging.toml` (shared) over the project file and `fairlead.staging.local.toml` (personal, ignored in CI) over the local one. Naming an environment with no file for it is an error. See [Configuration](https://mahkassem.github.io/fairlead/docs/config.html#environments).
+- `fairlead guard check` checks the project's own rules over every tracked file, with a ratchet: `--write-baseline` records today's counts for ratcheted rules and the check fails only when one rises. `--staged` is the commit stage, failing only on findings the staged change adds, compared by what each finding is about rather than its line. The first rule is `file-length` (`[guard.size]`). `guard.findings = "all"` counts every finding in a touched file instead, and `guard.on_finding = "warn"` shows the findings without stopping the commit. Commit-stage runs are recorded in `.git/fairlead/events.jsonl`, with rule ids and timings and never file contents; `guard.events = "off"` turns that off. See [Guard rules](https://mahkassem.github.io/fairlead/docs/guard.html).
+
+### Changed
+
+- A plan's config digest leaves out `guard` and `hooks`, which never change a plan, so digests are the same as 0.3.0's for the same config.
+- `[[guard.external]]` refuses `stages = ["write"]`: when the write hook runs, the file isn't written yet.
+
+## 0.3.0 (2026-09-26)
+
+### New
+
+- Edges the imports don't show: `[[graph.edges]]` makes each file matching `from` depend on the files its `to` globs match, and the planner follows the edge like an import. It fits a test that reaches its code over HTTP instead of importing it. A `{name}` is read from the side where it's a whole path segment, so `{area}{,-*}.test.ts` still picks up `orders-refunds.test.ts`, and `config check` refuses a rule that would silently match the wrong files. See [Import graph](https://mahkassem.github.io/fairlead/docs/graph.html#edges-the-imports-dont-show).
+- A walk barrier: `graph.barrier` names files the planner reaches but doesn't go past, such as a server module that every area imports and that imports every area. A changed barrier file is left to `tests.unreached` unless `plan.run_all` covers it. `graph why` and `test --explain` say where a barrier stopped the walk, and `graph stats` counts rule edges and barrier files. See [Barriers](https://mahkassem.github.io/fairlead/docs/graph.html#barriers).
+- Replay reads `bun test` output: `extractor = "bun"` attributes each `(fail)` line to the file header above it, including bun's interleaved parallel output and several bun runs in one job, and never takes a failure from bun's closing summary. The dataset keeps those lines. See [Replay](https://mahkassem.github.io/fairlead/docs/replay.html).
+
+### Known gaps
+
+- A bun test file that fails to load prints no `(fail)` line, so replay can't attribute it yet ([#68](https://github.com/mahkassem/fairlead/issues/68)).
+- A captured path segment that looks like glob syntax, such as `[slug]`, is re-read as a glob when filled into another pattern ([#69](https://github.com/mahkassem/fairlead/issues/69)).
+
 ## 0.2.0 (2026-09-26)
 
 ### New

package/README.md

@@ -107,9 +107,10 @@ commands. The [quick start](#quick-start) shows them, and the
 
 ## Status
 
-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
+Pre-alpha. The latest release, v0.4.0, adds guard rules and check, write and
+commit hooks, guard compare and benchmark commands, and layered config
+environments. 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)

package/npm-shrinkwrap.json

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

package/package.json

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