fairlead 0.3.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.4.2 (2026-09-28)
+
+### Fixed
+
+- Generated npm packages no longer include `npm-shrinkwrap.json`.
+
+## 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

package/README.md

@@ -107,10 +107,11 @@ commands. The [quick start](#quick-start) shows them, and the
 
 ## Status
 
-Pre-alpha. The latest release, v0.3.0, adds edges the imports don't show, a
-walk barrier, and replay of bun test output to v0.2.0's test plan, CI commands
-and action, replay, and config commands. 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.2, removes `npm-shrinkwrap.json` from the
+generated npm package. v0.4.0 added 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/package.json

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

package/npm-shrinkwrap.json

@@ -1,52 +0,0 @@
-{
-  "lockfileVersion": 3,
-  "name": "fairlead",
-  "packages": {
-    "": {
-      "bin": {
-        "fairlead": "run-fairlead.js"
-      },
-      "dependencies": {
-        "detect-libc": "^2.1.2"
-      },
-      "devDependencies": {
-        "prettier": "^3.8.3"
-      },
-      "engines": {
-        "node": ">=14.14",
-        "npm": ">=6"
-      },
-      "hasInstallScript": true,
-      "license": "MIT OR Apache-2.0",
-      "name": "fairlead",
-      "version": "0.3.0"
-    },
-    "node_modules/detect-libc": {
-      "engines": {
-        "node": ">=8"
-      },
-      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
-      "license": "Apache-2.0",
-      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
-      "version": "2.1.2"
-    },
-    "node_modules/prettier": {
-      "bin": {
-        "prettier": "bin/prettier.cjs"
-      },
-      "dev": true,
-      "engines": {
-        "node": ">=14"
-      },
-      "funding": {
-        "url": "https://github.com/prettier/prettier?sponsor=1"
-      },
-      "integrity": "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw==",
-      "license": "MIT",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.3.tgz",
-      "version": "3.8.3"
-    }
-  },
-  "requires": true,
-  "version": "0.3.0"
-}