Insight

magus insight <lens> reads version-control history to show where a codebase's attention and risk actually concentrate. Static structure tells you how the code is organized; history tells you how it is used - which files churn, which projects change together, who owns what. The man page lists the flags; this page is the intent.

Design intent

• Behavior over structure. A dependency graph shows what could affect what. History shows what does. A file edited every week is a different risk than one untouched for a year, even at the same complexity.
• Contextual by default. Every lens reflects the working directory's subtree; --workspace widens it to the whole workspace. Run it where you are asking the question.
• Derived, not stored. Insight computes from VCS history on demand. There is no index to maintain and nothing to keep in sync; the active VCS adapter must report per-commit files (git does).

The lenses

The first argument selects a lens:

• hotspots - edit frequency times complexity, the prime refactoring targets. The project view heat-colors the dependency graph by churn (with authors, recency, blast radius, CI duration); --files ranks individual files and renders a churn-versus-complexity quadrant.
• affinity - projects that change together (temporal coupling). A pair that co-changes without either declaring a dependency on the other is a candidate architectural smell: a hidden coupling the graph does not know about.
• ownership - author concentration: the primary author and their share, distinct author count (the bus factor), and abandonment (projects gone quiet).
• trend - the recent half of the window against the earlier half. A positive delta is a rising hotspot; a negative one is cooling.
• report - every lens, plus the knowledge graph's shape from magus graph stats, as one whole-workspace Markdown document. With --mermaid-style=safe the Mermaid subset is restricted to what older or partial renderers (GitHub step summaries, blog renderers) reliably handle; the default standard emits the full Mermaid spec for tools that render it. The magusfile's postflight target prints this to stdout for local use.

Bounding the scan

--commits caps the scan by count; --since bounds it by date (90d, 12w, 6mo, 1y). A wider window is more history and a slower scan, so bound it to the question: recent hotspots want a short window, an ownership audit a long one.

Each lens accepts -o text|json|yaml|name; hotspots and affinity also render -o mermaid for a diagram you can paste into a review.

Where it fits

Insight is a read-only lens, never part of a build. Reach for it when you are deciding what to work on rather than running work: picking a refactor target (hotspots), questioning an architecture (affinity), or planning ownership (ownership). The report lens in CI turns that into a recurring signal on every run.

See also

• targets - the dependency graph insight heat-colors.
• affected - the other VCS-driven command, for building rather than analyzing.