Skip to content

04-code-intelligence.md

Latest commit

 

History

History
175 lines (125 loc) · 5.73 KB

04-code-intelligence.md

File metadata and controls

175 lines (125 loc) · 5.73 KB

Journey 4 — Code Intelligence

You're exploring or refactoring an unfamiliar codebase. This journey covers the tools that build a graph of your code and answer structural questions: what calls this? what breaks if I change it? what are the most important files?

Source files referenced here:

  • rust/src/cli/dispatch/analytics.rs — graph, smells
  • rust/src/cli/index_cmd.rs — index
  • rust/src/cli/visualize_cmd.rs — visualize
  • rust/src/heatmap.rs — heatmap
  • rust/src/tools/registered/ctx_graph.rs, ctx_impact.rs, ctx_repomap.rs, ctx_callgraph.rs, ctx_architecture.rs, ctx_smells.rs, ctx_refactor.rs

0. The graph underneath everything

All code-intelligence features read from one property graph of your repo: files, symbols (functions/types), and the edges between them (imports, calls, references). It's built with tree-sitter (18 languages) and stored at graphs/<project-hash>/index.json.zst.

You usually don't build it by hand — it builds lazily on first use and updates in the background. To build explicitly:

lean-ctx graph build              # build/refresh the graph
lean-ctx index build-graph        # same, via the index command
lean-ctx graph status             # is it built? how big?

1. "What's connected to this?" — lean-ctx graph / ctx_graph

lean-ctx graph related src/auth.rs        # neighbors in the graph
lean-ctx graph symbol "validate_token"    # find + describe a symbol
lean-ctx graph context "login flow"       # graph-driven context for a query
lean-ctx graph export-html --out graph.html

ctx_graph (MCP) actions: build, related, symbol, impact, context, diagram, status, enrich. It's the unified entry point; the more focused tools below are specializations.

2. "What breaks if I change this?" — ctx_impact / lean-ctx graph impact

Blast-radius analysis. Given a file or symbol, it returns everything transitively affected.

lean-ctx graph impact src/auth/verify.rs

ctx_impact (MCP, in the standard profile) actions: analyze, diff (impact of a working-tree diff), chain (the dependency chain), plus build/update/status. This is the tool to call before a risky refactor.

3. "Who calls this?" — ctx_callgraph

ctx_callgraph action=callers symbol=validate_token
ctx_callgraph action=callees symbol=handle_login
ctx_callgraph action=trace from=main to=db_connect
ctx_callgraph action=risk symbol=validate_token

BFS over call edges. risk scores how dangerous a symbol is to change based on fan-in/fan-out. In the standard profile.

4. "What matters most here?" — ctx_repomap

PageRank over the symbol graph. Returns the most important symbols/files within a token budget — the fastest way for an AI to understand a new repo.

ctx_repomap max_tokens=2000
ctx_repomap focus_files=["src/auth.rs"]

In the standard profile. There is no repomap CLI command — it's an MCP tool only. (CLI users get a similar view via lean-ctx overview.)

5. Architecture & health — ctx_architecture

ctx_architecture action=overview        # layers, clusters at a glance
ctx_architecture action=cycles          # dependency cycles
ctx_architecture action=hotspots        # high-churn / high-coupling spots
ctx_architecture action=health          # an overall score
ctx_architecture action=entrypoints     # where execution starts

Community detection and layering over the property graph. In the standard profile.

6. Code smells — lean-ctx smells / ctx_smells

Eight rules over the graph (god objects, long functions, deep nesting, etc.).

lean-ctx smells summary          # counts by rule
lean-ctx smells scan             # all findings
lean-ctx smells rules            # what the 8 rules are
lean-ctx smells file src/big.rs  # findings for one file

ctx_review (MCP) goes further: an automated review combining impact, callers, test coverage, and smells (review, diff-review, checklist).

7. Refactoring — ctx_refactor

LSP-backed, so it's rename-safe across the project.

ctx_refactor action=rename path=src/auth.rs line=42 new_name=verify_jwt
ctx_refactor action=references path=src/auth.rs line=42
ctx_refactor action=definition path=src/main.rs line=10

In the standard profile. Requires the relevant language server; configure binaries under the [lsp] config map if auto-detection misses one.

8. Seeing it — lean-ctx visualize / heatmap

lean-ctx visualize --open            # interactive D3 HTML report
lean-ctx heatmap --top 20            # hottest files by access
lean-ctx heatmap --by connections    # rank by graph connectivity

visualize renders the graph; heatmap shows which files get touched most (heatmap.json), useful for spotting where attention — and risk — concentrates.

9. Index utilities — lean-ctx index

lean-ctx index status            # what's indexed
lean-ctx index build             # build the search index
lean-ctx index build-full        # full reindex
lean-ctx index build-graph       # (re)build the property graph
lean-ctx index watch             # keep it fresh on file changes

Index scanning can be disabled with LEAN_CTX_NO_INDEX=1 / LEAN_CTX_DISABLE_SEARCH_INDEX=1, and bounded with graph_index_max_files.

UX notes captured during this walkthrough

  • The graph is shared by graph, impact, callgraph, repomap, architecture, and smells — but that's not obvious from the command names. This journey leads with "one graph underneath everything" so the relationship is clear.
  • repomap being MCP-only (no CLI) surprises CLI users; documented here with overview as the CLI alternative.