From 45b6c141e80f7dc422e647194ca6c29148f234a3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Thomas=20M=C3=BCller?= <thomas.mi.iller.gitea.tmu@gmail.com>
Date: Thu, 3 Sep 2026 18:12:01 +0000
Subject: [PATCH] :wrench: Migrate lefthook config to v2 schema
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous config was a hybrid of v1 (jobs: array) and v1
(top-level commands: block) that no longer validates under
lefthook 2.x. lefthook 2.0.0's schema has top-level 'commands:'
set to 'false'; the v1 jobs: array form still works, but the
orphan named-commands block at the top was silently invalid
(caught by 'lefthook validate').

Migrate to the v2-native 'commands:' (named) form under the hook:

  pre-commit:
    parallel: true
    commands:
      oxlint:
        glob: ...
        run: npx oxlint {staged_files}
      ...

Changes:
- Add 'min_version: 2.0.0' to declare the v2 schema explicitly
- Replace pre-commit.jobs: array with pre-commit.commands: (named)
- Inline the glob on each command (was a top-level property on each
  job in v1)
- Remove the orphan top-level 'commands:' block — it was never
  referenced by any hook, and v2 forbids it
- Update project-specs.md: drop the dangling reference to the
  lefthook 'commands:' block (it was the dead top-level one);
  describe the v2 commands: form

Verified:
- 'lefthook validate' reports 'All good'
- 'lefthook run pre-commit' executes all 5 hooks (oxlint, oxfmt,
  sort-package-json, typecheck, cspell); globs correctly skip hooks
  on non-matching files (e.g. lefthook.yml alone) and run them on
  TS/JS changes
- 'npm run check' exits 0
- 'lefthook dump' shows the normalized v2 config
---
 lefthook.yml     | 42 +++++++++++++++---------------------------
 project-specs.md | 17 ++++++++++-------
 2 files changed, 25 insertions(+), 34 deletions(-)

diff --git a/lefthook.yml b/lefthook.yml
index 9b642b7..66f0edf 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -1,29 +1,17 @@
+min_version: 2.0.0
+
 pre-commit:
     parallel: true
-    jobs:
-        - name: oxlint
-          glob: "*.{ts,tsx,js,jsx,mjs,cjs}"
-          run: npx oxlint {staged_files}
-        - name: oxfmt
-          glob: "*.{ts,tsx,js,jsx,mjs,cjs}"
-          run: npx oxfmt --check {staged_files}
-        - name: cspell
-          run: npx cspell {staged_files}
-        - name: sort-package-json
-          run: npx sort-package-json --check
-        - name: typecheck
-          run: npx tsc --noEmit
-
-commands:
-    typecheck:
-        run: npm run check:tsc
-    spell:
-        run: npm run check:cspell
-    sort:
-        run: npm run check:package
-    lint:
-        run: npm run check:oxlint
-    format:
-        run: npm run check:oxfmt
-    outdated:
-        run: npm run check:outdated
\ No newline at end of file
+    commands:
+        oxlint:
+            glob: "*.{ts,tsx,js,jsx,mjs,cjs}"
+            run: npx oxlint {staged_files}
+        oxfmt:
+            glob: "*.{ts,tsx,js,jsx,mjs,cjs}"
+            run: npx oxfmt --check {staged_files}
+        cspell:
+            run: npx cspell {staged_files}
+        sort-package-json:
+            run: npx sort-package-json --check
+        typecheck:
+            run: npx tsc --noEmit
\ No newline at end of file
diff --git a/project-specs.md b/project-specs.md
index 86526ba..7142c24 100644
--- a/project-specs.md
+++ b/project-specs.md
@@ -38,12 +38,15 @@ typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starte
   `oxfmtrc`, `oxlintrc`, `sortpackagerc`, `EDITMSG`, `typescriptteam`,
   `gitmoji`, `dbaeumer`, `msvc`) and a few library names (`tslib`,
   `typefest`, `lefthook`).
-- **Lefthook**: Pre-commit checks for (run in parallel):
-    - oxlint on staged JS/TS files
-    - oxfmt --check on staged JS/TS files
-    - cspell on staged files
-    - sort-package-json --check
-    - tsc --noEmit
+- **Lefthook**: Pre-commit checks (run in parallel, lefthook v2 schema):
+    - `min_version: 2.0.0`
+    - `pre-commit.commands.oxlint` — `npx oxlint {staged_files}` on
+      staged `*.{ts,tsx,js,jsx,mjs,cjs}` files
+    - `pre-commit.commands.oxfmt` — `npx oxfmt --check {staged_files}`
+      on staged `*.{ts,tsx,js,jsx,mjs,cjs}` files
+    - `pre-commit.commands.cspell` — `npx cspell {staged_files}`
+    - `pre-commit.commands.sort-package-json` — `npx sort-package-json --check`
+    - `pre-commit.commands.typecheck` — `npx tsc --noEmit`
   `outdated` is intentionally NOT a pre-commit check (it can flag
   upstream patch releases that aren't actionable locally); it runs in
   CI and via the explicit `lefthook run outdated` command.
@@ -173,7 +176,7 @@ typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starte
 - `fix:oxfmt`: `oxfmt src`.
 - `fix:package`: `sort-package-json --write`.
   (There is no `fix` aggregator in the scripts; run the `fix:*` scripts
-  individually or via the lefthook `commands:` block.)
+  individually.)
 
 ### HOOKS