Haskell Quality Gates

Haskell Quality Gates

This skill covers the automation that keeps a Haskell project tidy: formatter, linter, performance defaults that prevent common pitfalls, and the pre-commit / CI / done-checklist that hold the line.

Formatter and linter

• ormolu — zero-config, opinionated. No style debates. Always run with --mode inplace before commits, or --mode check in CI.
• hlint — apply its suggestions by default unless they conflict with effectful patterns or clarity.
• cabal-gild — formats .cabal files. Keeps build configs readable and consistently structured. Prefer over cabal-fmt.

The conventions are not negotiable: disagreement is settled by the tool, not by review.

Where these binaries come from. All three must be on PATH before any hook or CI step can call them — the pre-commit hooks below use language: system, which means "already installed". On the native path ormolu is pinned in mise.toml while hlint comes from Homebrew and cabal-gild from cabal install (see haskell-toolchain-mise); the devcontainer image ships ormolu and cabal-gild but not hlint or pre-commit, so install those inside the container on first use. Keep the ormolu CLI in the series HLS bundles, or editor formatting and the CLI will disagree.

Performance defaults

These are the type-and-strictness choices that prevent the most common Haskell performance pitfalls. Apply them by default; deviate only with a reason.

• Text, never String — for anything human-readable. Data.Text strict by default; Data.Text.Lazy only for streaming.
• ByteString for bytes — strict by default, same logic.
• Vector for indexed/numeric data — Data.Vector boxed for arbitrary types, Data.Vector.Unboxed for primitives.
• Map / HashMap instead of association lists — containers for ordered, unordered-containers for hash-based.
• Strict fields by default in data types — data User = User { userId :: !UserId, userEmail :: !Email }. Laziness in fields is a frequent source of space leaks; opt into it explicitly with rare exceptions.
• BangPatterns when a let-bound intermediate result should be forced.
• Profile with -prof -fprof-auto and visualize with ghc-prof-flamegraph. Look at maximum residency with +RTS -s.

Pre-commit hooks

Use pre-commit (the Python framework, language-agnostic) to enforce formatting and linting locally. Commit .pre-commit-config.yaml to the repo:

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: ormolu
        name: ormolu
        entry: ormolu --mode inplace
        language: system
        files: \.hs$

      - id: hlint
        name: hlint
        entry: hlint
        language: system
        files: \.hs$

      - id: cabal-gild
        name: cabal-gild
        entry: cabal-gild
        language: system
        files: \.cabal$

Onboarding step (in README): pip install pre-commit && pre-commit install. After that, every git commit runs the hooks. ormolu --mode inplace reformats files; if anything changes, the commit is blocked and the user re-stages with git add.

CI safety net

Pre-commit hooks can be skipped with git commit --no-verify, and not every contributor will install them. Run the same checks in CI as a final gate:

# .github/workflows/ci.yml fragment
- name: Check formatting
  run: ormolu --mode check $(git ls-files '*.hs')

- name: Check cabal formatting
  run: cabal-gild --mode=check $(git ls-files '*.cabal')

- name: Lint
  run: hlint src test

- name: Build
  run: cabal build --ghc-options=-Werror

- name: Test (hspec + doctest)
  run: cabal test
  env:
    HSPEC_OPTIONS: --color

- name: Documentation gate (coverage + references)
  run: ./scripts/check-haddock.sh

Note -Werror is in CI but not in the .cabal file: locally, warnings should be visible but non-fatal during exploration; CI is where the line is held.

Before declaring work "done"

Always run, in order:

1. cabal build — clean build, no warnings. Warnings are configured in the .cabal file (see haskell-project-setup). Note that Haddock coverage is not enforced here: GHC has no -Wmissing-docs, so it is step 3's job (see haskell-documentation).
2. cabal test — all tests pass, including hspec, properties, and doctests. Output formatting is configured in cabal.project and .hspec (see haskell-testing).
3. ./scripts/check-haddock.sh — Haddock generates cleanly at 100% coverage, with no broken references, malformed markup, or unresolved links. The script exists because neither -Wmissing-docs (GHC) nor -Werror (Haddock 2.31.1) is available on the pinned toolchain (see haskell-documentation).
4. hlint src test — no lint warnings (or all consciously suppressed with reason).

If pre-commit hooks are installed (pre-commit install), step 4 happens automatically on git commit. Ormolu formatting is handled automatically by the PostToolUse hook on each file edit.

When the user is stuck

Common debugging cues, with what to ask for next:

• Type errors: ask for the exact error message and a minimal reproducer. The error is almost always more useful than they realize once decoded. Translate it for them — GHC's vocabulary (expected ... actual ..., "rigid type variable", "ambiguous occurrence") is dense but principled.
• "Could not deduce": usually a missing constraint. Walk through where the constraint comes from — the compiler reports exactly which constraint is needed.
• Show/Eq not in scope: derived instances missing, or wrong import.
• Space leaks: ask about +RTS -s output. Look for non-strict accumulators in folds (use foldl'), missing strict fields, lazy Map.insertWith (use Map.insertWith').
• Library API unfamiliar or version-drifted: tell the user you'll check Hackage rather than guessing — Haskell library APIs drift and guessing wastes their time.

Related

• The warning set enforced in CI is defined in the .cabal file — see haskell-project-setup.
• The Haddock coverage gate (and why -Wmissing-docs/haddock -Werror are unavailable), doctest as a test suite: haskell-documentation.
• cabal test output formatting (test-show-details: direct, .hspec): haskell-testing.