Haskell Haddock And Source Reader

Read documentation and source code for dependencies of a cabal nix-style project, preferring local files over the network. Exhaust local sources before fetching from Hackage.

Which Source To Use

• Package is a dependency of the current project: read locally.
• Package is outside the project's dependency set: fall back to Hackage.
• Prefer the hoogle skill for symbol or type lookup before fetching full documentation pages.

One-Time Setup

If local docs are missing, enable documentation and build once after dependency changes:

cabal configure --enable-documentation
cabal build all

Resolving A Dependency

Run the bundled resolver from the project root:

.codex/skills/haddock/scripts/locate-dep.sh <package>

The resolver regenerates the build plan, reads cabal's store and repo-cache paths, looks up the package's exact UnitId in dist-newstyle/cache/plan.json, and prints JSON:

{
  "store_path": "<cabal-store>/<UnitId>",
  "doc_dir": "<store_path>/share/doc/html",
  "source": "<repo-cache>/.../<pkg>-<ver>.tar.gz"
}

• store_path is the resolved unit directory in the cabal store.
• doc_dir is the Haddock HTML directory, or null if docs were not built.
• source is a Hackage/Stackage source tarball path, source-repository-package metadata, or null.

Do not construct store paths from package names. Cabal abbreviates and hashes store entries, so use the resolved UnitId.

Reading Docs

When doc_dir is non-null, module pages sit directly inside it. A module page is its dotted name with . replaced by - plus .html, for example System.Random.SplitMix becomes System-Random-SplitMix.html. Use index.html or list *.html files if the module name is uncertain.

Reading Source

For a string tarball path, stream a single file without unpacking everything:

tar -tzf <source>
tar -xzOf <source> <pkg>-<ver>/<path/to/File.hs>

For a source-repository-package object, use its { type, location, tag, subdir } metadata. Cabal checks the repo out under dist-newstyle/src/ in a directory named from the repo plus a content hash, not from the tag. Locate the source with a glob such as:

dist-newstyle/src/*/<subdir>/**/*.hs

Drop /<subdir> when absent or ".". If multiple checkouts match, pick the one whose git rev-parse HEAD matches git rev-parse "<tag>^{commit}" inside that checkout.

Resolver Misses

If the resolver prints null or exits non-zero, the package is not in the cabal store. Common cases:

• GHC boot libraries such as base, ghc-prim, containers, and template-haskell ship docs with the compiler. Use ghc-pkg-<ver> field <pkg> haddock-html, deriving <ver> and the matching ghc-pkg path from cabal path --output-format=json.
• Local packages should be read directly from their path in cabal.project.

Hackage Fallback

Use Hackage only when local lookup is not available:

https://hackage.haskell.org/package/<pkg>
https://hackage.haskell.org/package/<pkg>-<ver>/docs/<Module-With-Dashes>.html

If doc_dir is null for a real dependency, documentation: True is probably missing or cabal build all has not run since the dependency was added. Redo setup, then rerun the resolver.