hk.pkl

// Git hooks for this repository. `pnpm bootstrap` installs them.
// docs/development/quality-gates.md#hook-parity lists the same commands for
// agents and contributors whose hooks did not run.
amends "package://github.com/jdx/hk/releases/download/v2.4.0/hk@2.4.0#/Config.pkl"

// Files that can change the result of rustfmt, Clippy or the Miri cfg check.
local rustInputs = List(
  "**/*.rs",
  "**/Cargo.toml",
  "Cargo.lock",
  "rust-toolchain.toml",
  ".rustfmt.toml",
  ".clippy.toml",
  ".cargo/config.toml"
)

local cargoFmt = new Step {
  check = "cargo fmt --all -- --check"
  fix = "cargo fmt --all"
}

local cargoClippy = new Step {
  check = "cargo clippy --workspace --all-targets -- -D warnings"
}

hooks {
  ["pre-commit"] {
    // Check only. `hk fix` applies the fix commands on request.
    fix = false
    // The git stash stack is shared by every worktree of this repository.
    stash = "none"
    steps {
      ["cargo-fmt"] = (cargoFmt) { glob = rustInputs }
      ["cargo-clippy"] = (cargoClippy) { glob = rustInputs }
      ["typos"] {
        check = "if command -v typos >/dev/null 2>&1; then typos; else sh scripts/hook-tool-hint.sh typos; fi"
      }
      // Block hidden and bidi unicode in staged text files. See
      // scripts/scan-hidden-unicode.py and SECURITY.md.
      ["hidden-unicode"] {
        check = "if command -v python3 >/dev/null 2>&1; then python3 scripts/scan-hidden-unicode.py --mode committed --staged; fi"
      }
      // A committed merge-conflict marker is an unresolved conflict, or test
      // data that trips conflict scanners. See scripts/check-conflict-markers.sh.
      ["conflict-markers"] {
        check = "sh scripts/check-conflict-markers.sh --staged"
      }
      ["comment-quality"] {
        check = "if command -v node >/dev/null 2>&1; then node scripts/check-comment-quality.mjs --staged; else sh scripts/hook-tool-hint.sh node; fi"
      }
      // The Miri CI job is path-filtered and can merge red. The cargo-fallow
      // rule `miri-build-compiles` catches a cfg(test) path to a not(miri)
      // item before it leaves this machine.
      ["miri-cfg"] {
        glob = List("**/*.rs")
        check = "if command -v cargo-fallow >/dev/null 2>&1; then cargo fallow boundaries --fail-on-issues --quiet; else sh scripts/hook-tool-hint.sh cargo-fallow; fi"
      }
      // A Rust file over 2000 lines must not grow. The step measures the
      // staged blob. See docs/development/quality-gates.md#file-size.
      ["file-size"] {
        glob = List("**/*.rs")
        check = "if command -v cargo-fallow >/dev/null 2>&1; then cargo fallow size --staged --fail-on-growth --quiet; else sh scripts/hook-tool-hint.sh cargo-fallow; fi"
      }
      // The same limit for .mjs and .ts files, through `fallow audit` and
      // health.maxFileLines. The audit reads the working tree, not the staged
      // blob. See docs/development/quality-gates.md#file-size.
      ["file-length"] {
        glob = List("**/*.mjs", "**/*.ts", ".fallowrc.json", "scripts/fallow-file-length.json")
        check = "sh scripts/hook-file-length.sh HEAD"
      }
      // Changelog entries go to changelog.d/, never to [Unreleased] in
      // CHANGELOG.md. The step reads the working tree, not the staged blob,
      // because stash is off. CI enforces the committed result. A release
      // `collect` commit skips it with HK_SKIP_STEPS=changelog-fragments.
      ["changelog-fragments"] {
        glob = List("CHANGELOG.md", "changelog.d/**")
        check = "if command -v node >/dev/null 2>&1; then sh scripts/hook-changelog-fragments.sh; else sh scripts/hook-tool-hint.sh node; fi"
      }
      // The `lint:js` script in package.json holds the scope list. The helper
      // reads it from there, so this step holds no copy of the list.
      ["js-lint"] {
        check = "sh scripts/hook-js-lint.sh"
      }
    }
  }
  ["commit-msg"] {
    steps {
      // A fresh worktree has no node_modules. CI still runs commitlint.
      ["commitlint"] {
        check = "if [ -x node_modules/.bin/commitlint ]; then node_modules/.bin/commitlint --edit \"{{commit_msg_file}}\"; else echo 'commit-msg: commitlint is not installed, skipping local check (CI still enforces it). Run: pnpm install' >&2; fi"
      }
      // The Commit messages workflow fails a pull request commit without a
      // Signed-off-by line for its author. Check it before the push.
      ["dco-signoff"] {
        check = "if command -v node >/dev/null 2>&1; then node .github/scripts/check-dco.mjs --message-file \"{{commit_msg_file}}\"; else sh scripts/hook-tool-hint.sh node; fi"
      }
    }
  }
  // Test and Miri run in CI on pull requests, on Linux runners. To run the
  // full suite locally before a pull request:
  //   cargo test --workspace --lib --bins --tests --examples
  //   cargo check --workspace --benches
  //   rustup run nightly cargo miri test -p fallow-types --lib --tests -- --skip proptests
  // The old bash hook unset GIT_DIR and GIT_WORK_TREE for `cargo test`, which
  // spawns fallow in fixture folders. hk passes both variables to each step.
  // A pre-push step that calls git must unset them, as the file-length
  // script does.
  ["pre-push"] {
    steps {
      ["cargo-fmt"] = cargoFmt
      ["cargo-clippy"] = cargoClippy
      // Same command as the required "Documentation" CI job. A broken
      // intra-doc link passes fmt and Clippy.
      ["cargo-doc"] {
        check = "cargo doc --workspace --no-deps --document-private-items"
        env { ["RUSTDOCFLAGS"] = "-D warnings" }
      }
      // Same command as the required "Rust Structure" CI job: unused
      // dependencies and files, visibility, crate boundaries, complexity and
      // duplication. See docs/development/quality-gates.md#rust-structure.
      ["cargo-fallow"] {
        check = "if command -v cargo-fallow >/dev/null 2>&1; then cargo fallow check --baseline cargo-fallow-baseline.json --fail-on-issues --quiet; else sh scripts/hook-tool-hint.sh cargo-fallow; fi"
      }
      // Same rule as the "File length" step of the CI "Fallow Self Analysis"
      // job: a .mjs or .ts file over 2000 lines must not grow on the branch.
      ["file-length"] {
        check = "sh scripts/hook-file-length.sh origin/main upstream/main"
      }
    }
  }
}