From 1fe3dbe28bf4c9e2ce5c06711bf94be5ec874b6d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Thomas=20M=C3=BCller?= <thomas.mi.iller.gitea.tmu@gmail.com>
Date: Fri, 4 Sep 2026 23:58:18 +0200
Subject: [PATCH] :sparkles: Add npm run fix aggregator for the fix:* scripts

Override the prior design choice: there is now an npm run fix
script that runs fix:oxlint && fix:oxfmt. Rationale: the friction
of having to remember and run two separate fix commands after
npm run check outweighs the 'intentional fixes' argument once
check has already told you which fixers are needed. The diff
after running fix remains the review surface.

- package.json: new 'fix' script (npm run fix:oxlint && npm run fix:oxfmt)
- project-specs.md: updated the FIX section to document the new
  aggregator, removed the 'no fix aggregator by design' text in
  two places (FIX section and PREFIX CONVENTION section)
- README.md: same updates, plus the Development section header
  changed from 'Format/Fix' to 'Individual fixes' to reflect
  the new hierarchy
---
 README.md        |  4 ++--
 package.json     |  1 +
 project-specs.md | 12 +++++++-----
 3 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 4a4ea58..cd28922 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ Pattern matching for TypeScript/ESM environments (F#-style, not regex).
 - **Build:** `npm run build`
 - **Test:** `npm run test`, `npm run test:ci`
 - **Checks:** `npm run check`, `npm run fix`
-- **Format/Fix:** `npm run fix:oxfmt`, `npm run fix:oxlint`
+- **Individual fixes:** `npm run fix:oxfmt`, `npm run fix:oxlint`
 
 ### Tooling
 
@@ -43,7 +43,7 @@ Pattern matching for TypeScript/ESM environments (F#-style, not regex).
 Script names follow a prefix convention that signals _when_ they run:
 
 - `check:*` — read-only verification. Aggregated by `npm run check`. Used in pre-commit hooks and CI's build job.
-- `fix:*` — mutating counterpart of `check:*`. Run individually (no `npm run fix` aggregator by design — fixes should be intentional, not batched).
+- `fix:*` — mutating counterpart of `check:*`. Aggregated by `npm run fix`. Use after `npm run check` to auto-resolve issues.
 - `test:*` — test scripts. `npm run test` runs the full suite; `test:unit` / `test:ci` are scope-specific variants.
 - `publish:*` — runs only at publish time, in the CI `publish` job (immediately before `npm publish`). There is no local `npm run publish` script — publishing is CI-only by policy.
 
diff --git a/package.json b/package.json
index 8e6b3e1..2f9fe89 100644
--- a/package.json
+++ b/package.json
@@ -43,6 +43,7 @@
         "check:oxlint": "oxlint ${LEFTHOOK_FILES:-src}",
         "check:tsc": "tsc",
         "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
+        "fix": "npm run fix:oxlint && npm run fix:oxfmt",
         "fix:oxfmt": "oxfmt ${LEFTHOOK_FILES:-.}",
         "fix:oxlint": "oxlint --fix src",
         "test": "npm run check:tsc && node --test --strip-types \"src/**/*.test.ts\"",
diff --git a/project-specs.md b/project-specs.md
index dd6f128..43069b2 100644
--- a/project-specs.md
+++ b/project-specs.md
@@ -176,9 +176,9 @@ script's intended lifecycle:
   (which runs all `check:*` scripts in order). Called from the
   lefthook pre-commit hook on staged files, and from the CI build
   job on the full project. Read-only; never modifies files.
-- `fix:*` — mutating counterpart of a `check:*` script. There is
-  **no** `npm run fix` aggregator by design: fixes should be
-  intentional, not batched. Run individually.
+- `fix:*` — mutating counterpart of a `check:*` script. Aggregated
+  by `npm run fix`. Use after `npm run check` to auto-resolve
+  issues; the diff is the review surface.
 - `test:*` — test scripts. `npm run test` is the canonical entry
   point (`check:tsc` + unit tests); `test:unit` skips the typecheck
   for fast local iteration; `test:ci` adds c8 coverage and is the
@@ -268,12 +268,14 @@ script does not belong in the standard pipeline.
 
 ### FIX
 
+- `fix`: Run all fixes in order — `fix:oxlint`, then `fix:oxfmt`.
+  Use this when `npm run check` reports issues you want to
+  auto-resolve. The fix scripts write changes in place; review
+  the diff before committing.
 - `fix:oxlint`: `oxlint --fix src`.
 - `fix:oxfmt`: `oxfmt ${LEFTHOOK_FILES:-.}` — same scoping as
   `check:oxfmt` (whole project by default, staged files from
   lefthook). Writes changes in place.
-  (There is no `fix` aggregator in the scripts; run the `fix:*` scripts
-  individually.)
 
 ### PUBLISH