potok

potok — Slavic stream / flow / current — mines a git repository's history and renders a heatmap of where things are changing, specialized for Terraform. Unlike file-level churn tools, potok is HCL-aware: it attributes change to Terraform entities — modules, input variables, resources, data sources, outputs — and contrasts the static HCL reference graph against the temporal co-change graph to surface hidden coupling.

Status

🚧 Under active development (see PROGRES.md for milestone tracking). All milestones M1–M8 complete + all 10 packages tested green: model, config, vcs backends, hclx HCL analysis, attribute hunk↔block join, metric heat/coupling/ownership/divergence, render Canvas/colormap/ treemap/ANSI(colorprofile)/SVG/PNG/JSON/DOT (with embedded TTF + 5 golden formats), full Build pipeline with hunk attribution, wired CLI commands (all notable per-command flags), CI gates, age (RenderAgeReport), config-file overlay, goreleaser, unit tests + testscript E2E + golden files + attribute edge cases + go-git chunk walker parity + cross-backend parity — all green. See SPEC.md for the full blueprint.

Build

go build -o potok ./cmd/potok     # or: just build
just check                         # vet + test + build

Quick start

potok modules                       # per-module churn
potok heatmap --color never          # entity heat table
potok heatmap --layout stacked --format svg   # stacked-bar heatmap
potok heatmap --layout flame --format png     # flamegraph heatmap
potok heatmap --scale sqrt            # spread low-churn tails (Terraform-friendly)
potok graph                          # static HCL reference graph (DOT)
potok coupling                      # temporal co-change pairs
potok divergence                    # flagship: hidden coupling / phantom structure
potok divergence --fail-on-hidden-coupling 0   # CI gate (exit 3 on breach)
potok report --out-dir report/      # bundle: heatmap.svg + corpus.json

What it does

A single static Go binary that, pointed at a git working tree, walks commit history, statically parses the Terraform (HCL) at the analyzed revision, and produces a change heatmap plus relationship analyses. It answers:

• Which resource / module input variable changes most often? — the volatile public surface.
• Which modules always change together but share no module/var reference? — hidden coupling.
• Where is high churn colliding with a low bus factor? — the riskiest cells on the map.

It runs without terraform init, reads no state, and makes no network calls.

Build

just build     # or: go build -o potok ./cmd/potok
just check     # gofumpt + golangci-lint + vet + test + build
just test

Usage

potok heatmap --by resource       # treemap/table of entity heat
potok heatmap --layout stacked   # stacked-bar: one band per module, every entity visible
potok heatmap --layout flame     # flamegraph: root → module → entity hierarchy
potok heatmap --scale sqrt       # sqrt normalization (spreads low-churn Terraform tails)
potok heatmap --scale gamma0.4   # gamma curve, custom exponent
potok heatmap --width 1200 --height 400 --format svg   # custom canvas dimensions
potok hotspots                    # freq × complexity (Tornhill)
potok coupling --formula degree   # temporal co-change pairs + matrix
potok divergence                  # flagship: hidden coupling / phantom structure
potok modules                     # per-module inventory + churn
potok graph                       # static HCL reference graph (DOT/JSON/SVG)
potok age                         # line-age heat (blame-based)
potok report --out-dir report/    # bundle of SVGs + corpus.json

Architecture

A pipeline, not a service. One pass, four stages, three renderers:

git working tree → vcs (history) + hclx (static HCL) + config
                 → attribute (hunk↔Block.Range intersection)
                 → metric (heat, coupling, ownership, divergence)
                 → render (ANSI | SVG | PNG | JSON | DOT)

Packages (internal/*): model, vcs, hclx, attribute, metric, render, config; cmd/potok is cobra wiring.