cabal-dep-graph

Dependency coupling analysis for Haskell mono-repos.

Point it at any git repository containing .cabal files and it builds a dependency graph entirely through git -- no filesystem traversal, no checkout alteration, works against any revision. Query the graph for blast radius, dependency weight, coupling hotspots, and more.

Current Status

The CLI is implemented and parses all commands and flags correctly. Query execution (graph construction, scoring, output rendering) is in progress. The verified workflows below reflect what the current binary actually does.

---

Getting Started

Prerequisites

• GHC 9.12 + cabal-install, OR Nix with flakes enabled
• Git (the tool reads all data through git commands)

Build and run locally

$ cabal build cabal-dep-graph
$ cabal run -v0 cabal-dep-graph -- --help

Install to PATH

$ cabal install cabal-dep-graph
$ cabal-dep-graph --help

---

Verified Workflows

All outputs below are verified against the current binary.

a) Help text

$ cabal run -v0 cabal-dep-graph -- --help

Exit code: 0

cabal-dep-graph -- Cabal package dependency analysis tool

Usage:
  cabal-dep-graph <command> [<args>] [<flags>]
  cabal-dep-graph --help | -h

Commands:
  blast-radius <pkg>          Packages transitively affected if <pkg> changes.
  why-depends <src> <tgt>     All dependency paths from <src> to <tgt>.
  dep-weight <pkg>            Weighted dependency count for <pkg>.
  depth [<pkg>]               Maximum dependency depth (or for one package).
  hub-score [<pkg>]           Hub centrality score (or for one package).
  ripple-score <pkg>          Change-ripple score for <pkg>.
  ripple-report               Full ripple-score report for all packages.

Global flags:
  --delta[=<rev>|=<r1>..<r2>] Restrict analysis to packages changed in range.
  --evolution=<r1>..<r2>      Compare metrics across a revision range.
  --json                      Output results as JSON.
  --html                      Output results as HTML.
  --no-color                  Disable ANSI colour in terminal output.
  --help, -h                  Show this help text and exit.

b) blast-radius

$ cabal run -v0 cabal-dep-graph -- blast-radius core-types

Exit code: 0

cabal-dep-graph: parsed CmdBlastRadius (PackageName "core-types")

(Query execution not yet implemented; the command was parsed successfully.)

c) ripple-report --json

$ cabal run -v0 cabal-dep-graph -- ripple-report --json

Exit code: 0

cabal-dep-graph: parsed CmdRippleReport

(Query execution not yet implemented; the command was parsed successfully.)

d) ripple-report --json --html (mutually exclusive flags)

$ cabal run -v0 cabal-dep-graph -- ripple-report --json --html

Exit code: 1

cabal-dep-graph: flags are mutually exclusive: --json and --html

e) why-depends with --evolution (unsupported combination)

$ cabal run -v0 cabal-dep-graph -- why-depends app core-types --evolution=v1..v2

Exit code: 1

cabal-dep-graph: evolution not supported: why-depends

f) ripple-report --delta

$ cabal run -v0 cabal-dep-graph -- ripple-report --delta

Exit code: 0

cabal-dep-graph: parsed CmdRippleReport

(Query execution not yet implemented; the command was parsed successfully.)

---

Planned Behavior

The following describes the intended final behavior once query execution and report rendering are complete.

blast-radius List all packages that would be rebuilt if <pkg> changes (transitive reverse dependency closure).

why-depends Show all dependency paths from <src> to <tgt> as a tree, explaining why <src> rebuilds when <tgt> changes.

dep-weight Show the total weight (module count) of everything <pkg> pulls in transitively -- how expensive it is to depend on.

depth [] Report the longest dependency chain (critical path) in the graph, indicating build serialization pressure.

hub-score [] Score packages by fan-in x fan-out to surface coupling bottlenecks -- packages that are both heavily depended-on and have many dependencies themselves.

ripple-score Score <pkg> by the aggregate weight of its blast-radius closure -- the total rebuild cost it imposes on the repo when it changes.

ripple-report Ranked table of all packages by ripple-score. The top-level coupling health dashboard. Supports --json, --html, --delta, and --evolution flags.

Cross-cutting flags

• --delta[=<rev>|=<r1>..<r2>] -- compare graph state between two revisions; defaults to merge-base(main, HEAD)..HEAD (the PR diff).
• --evolution=<r1>..<r2> -- build graphs at every cabal-touching commit in a range and show a time-series table with trend sparklines.
• --json -- machine-readable JSON output for scripting.
• --html -- self-contained single-file HTML report (all CSS/JS inlined), suitable for publishing as CI build artifacts.
• --no-color -- disable ANSI color in terminal output (also auto-detected when stdout is a pipe, or when NO_COLOR env var is set).