Comprendia: AI-Augmented Code Comprehension

COMPRENDIA is an Eclipse plugin that integrates structural dependency visualization with LLM-powered code explanation on a shared interactive graph for Java program comprehension. The tool rests on four pillars: (1) a multi-edge-type dependency graph with live search and multiple layouts; (2) LLM explanations grounded in Graph-Aware Callee Pruning (GACP), an auditable strategy that selects relevant callees using the same graph the developer navigates; (3) a clone-detection overlay that highlights duplication and suggests extract-to-parent refactoring opportunities; and (4) a CVE risk overlay powered by OSV.dev. GACP uses graph distance, inheritance collapse, and edge-type weighting to produce prompts that are reproducible across LLM families and traceable to visible graph nodes. We demonstrate COMPRENDIA on a Java project containing known clones and vulnerabilities, showing how the unified graph substrate supports comprehension while keeping the developer in control.

The paper makes three contributions, each grounded in the team's prior published empirical work and unified by a single design principle: the visualization the developer sees is the data structure the tool reasons over.

Contribution 1 is a multi-edge-type structural substrate: COMPRENDIA renders an Eclipse Java project's dependency graph as an interactive visualization with five structural edge types (inheritance, interface, field-type, method-parameter, method-return). Edge-type filters, four layout algorithms, and in-graph search are exposed through a single toolbar. This extends Zibran's management-oriented clone-visualization line from a single-edge overlay to a comprehensive structural graph.

Contribution 2 is Graph-Aware Callee Pruning (GACP): COMPRENDIA introduces GACP, an algorithm that uses the same dependency graph as the relevance signal for prompt construction. GACP (i) admits callees within k graph hops, (ii) collapses near-duplicate siblings sharing an inheritance ancestor into a single delegate, and (iii) allocates the remaining budget under an edge-type-weighted score. Every emitted callee carries an inclusion reason mapping one-to-one onto a visible graph node, making decisions auditable and reproducible.

Contribution 3 is clone-refactoring discovery as a graph overlay: COMPRENDIA integrates the CloMan clone-detection engine with the dependency graph by painting clone-group members as red-highlighted nodes. Clicking a group focuses the graph on its members and reveals extract-to-parent refactoring opportunities. Because the overlay shares the same substrate, clicking a cloned class yields both its graph context and a GACP-enriched explanation via the inheritance-collapse phase.

The paper positions COMPRENDIA against related work. GitHub Copilot Chat and Cursor send the text selection to the model with no additional project context. Sourcegraph Cody and RepoFuse retrieve project-internal code via embedding similarity, but their inclusion decisions are approximate, not reproducible across embedding models, and not auditable. LLMLingua and RECOMP compress prompts using perplexity scores, but their compression decisions are model-internal and not traceable to project-level structure. Structural visualization tools like CodeCity, Lattix, Structure101, and Eclipse Zest do not combine structural visualization with LLM-driven code explanation. COMPRENDIA is, to our knowledge, among the first IDE-native systems to use the project's dependency graph as the relevance signal for prompt construction.

The tool's user-facing workflow: a developer opens an unfamiliar Eclipse Java project and right-clicks Visualize Dependencies. COMPRENDIA parses the workspace incrementally via JDT and renders a dependency graph inside the IDE: nodes are classes, interfaces, and enums; edges encode five structural relationships. The developer toggles edge types, switches among four layout algorithms (spring, tree, radial, grid), and uses in-graph search to locate a class of interest. Double-clicking a node opens the corresponding source file. To understand a method, the developer highlights its body and clicks Explain with AI. COMPRENDIA invokes GACP to select project-internal callees from the graph, assembles a prompt containing the selection and the chosen callee snippets, and routes the request to the configured LLM backend. The explanation appears in the InsightPanel with callee citations the developer can click to navigate to the referenced source. Two overlays enrich the graph: Detect Clones invokes the CloMan clone-detection engine, and parsing the project's pom.xml and querying the OSV.dev vulnerability database paints CVE-severity borders on affected nodes.

GACP is specified as a pure, static function that chooses project-internal callees for the LLM-explanation prompt. Given the enclosing class FQN, AST-extracted callees (filtered to project-internal symbols via JDT), a read-only GraphIndex over the dependency graph, and a token Budget, it returns a ranked list of GacpCallee records. Each record carries the callee's FQN, graph distance, snippet mode (FULL BODY or SIGNATURE ONLY), rendered prompt fragment, and a structured inclusionReason that maps one-to-one onto a visible graph node. The function contains no randomness, no LLM calls, and no UI dependencies.

Phase 1 (Reachability Filter) admits a candidate callee if its declaring class lies within Kmax=2 hops from the enclosing class on the dependency graph; self-calls (distance 0) are admitted directly. The cutoff is a hard structural admission rule, not a soft penalty. Candidates are de-duplicated by declaring class. The snippet mode is distance-dependent: distance-≤1 callees are rendered as FULL BODY, distance-2 as SIGNATURE ONLY.

Phase 2 (Topological Redundancy Elimination): any group of ≥2 surviving candidates whose declaring classes share an immediate inheritance ancestor A is replaced with A itself (rendered as FULL BODY) plus a single concrete delegate. The immediate qualifier guards against false collapses through java.lang.Object. This phase yields the largest savings on clone-touching selections. For example, when the developer requests an explanation inside one of four sibling repository classes sharing BaseRepository, Phase 2 collapses the four near-duplicate method bodies into the BaseRepository contract plus one concrete delegate.

Phase 3 (Edge-Type-Weighted Budget Allocation) ranks survivors by edge-type weight divided by squared graph distance, favoring inheritance and interface edges (weight 1.0) over field-type (0.6) and method-parameter or method-return (0.4) relationships. Candidates are emitted greedily under the token budget, skipping degenerate snippets. Given fixed inputs, GACP returns the same output on every invocation: Phase 1 is O(V+E); Phases 2 and 3 are O(C log C) on the surviving set.

The demonstration uses six method-body selections from the QUICKBITE open-source Java benchmark (33 classes, 6 packages), replayed against three LLM families (Claude Sonnet 4.6, GPT-4o-mini, Llama 3 via Ollama). The harness compares four modes per fixture: SELECTION-ONLY (no callee context), LEGACY (dedup-and-cap at 5 callees), GACP-SIG (GACP with signature-only rendering), and GACP-BODY (GACP with full bodies for distance-1 callees, the shipping default). Three fixtures exercise Phase 1's reachability filter without engaging collapse; three engage Phase 2 with group sizes k = 2, 3, 4.

Token cost results: GACP-SIG trades a modest token premium (+7.5% overall) for graph-grounded inclusion decisions. On collapse fixtures the cost is near-parity (+1.5%), because Phase 2 replaces k sibling bodies with one parent contract plus one delegate. On the k=4 case, GACP-SIG actually saves 2.7% (186→181 tokens). On no-collapse fixtures, GACP-SIG admits more callees than LEGACY's cap: placeOrder emits 7 vs. 5, including two structurally proximate helpers that the cap drops (+19.3%). GACP-BODY roughly doubles the prompt on no-collapse fixtures (+109.3%) by including full method bodies. On collapse fixtures, Phase 2 limits the increase to +13.7%. Prompt-token counts are identical across all three LLM families for every fixture×mode combination, confirming that GACP's output is a pure function of the graph and the selection.

The paper acknowledges limitations: a single benchmark project (QUICKBITE), a coarse accuracy rubric (keyword-match accuracy saturates to 2/2 across all modes and LLM families), a token estimator based on character-count/4, no human-comprehension claim (the paper measures the algorithm's effect on the prompt, not whether developers comprehend code faster), no personalization or method-level graph granularity, and no comparison against embedding-retrieval systems or parameter sweeps.

The conclusion states that COMPRENDIA integrates dependency-graph visualization, LLM-assisted code explanation, and clone-refactoring discovery onto a single graph substrate. The unifying design principle is that the visualization the developer sees is the data structure the tool reasons over: GACP queries the graph for callee distances, the clone overlay paints onto the graph, and the developer reads the graph to verify both. GACP's callee-inclusion decisions are auditable against visible graph nodes and reproducible across LLM families, distinguishing COMPRENDIA from embedding-retrieval and perplexity-based approaches whose relevance signals are model-internal. On the QUICKBITE benchmark, GACP's inheritance-collapse phase reshapes prompts on clone-touching selections from k sibling duplicates to a parent-contract-plus-delegate form, and the graph-distance cutoff admits structurally proximate helpers that a fixed cap drops.

Improvements to AI systems based on this paper:

1. Graph-grounded prompt construction: Replace opaque, embedding-based retrieval with a deterministic, graph-distance-based callee selection algorithm (GACP). The AI system can now justify every included code snippet by referencing a visible dependency-graph node, making its context choices auditable and reproducible across different LLM backends.

2. Inheritance-collapse for clone-heavy code: Implement Phase 2 of GACP to detect near-duplicate sibling classes sharing an immediate ancestor and collapse them into a parent contract plus one concrete delegate. The improved system can generate concise, non-redundant explanations for methods in cloned code, reducing token usage by up to 2.7% while preserving semantic coverage.

3. Edge-type-weighted relevance scoring: Use the five structural edge types (inheritance, interface, field-type, method-parameter, method-return) with weights (1.0, 1.0, 0.6, 0.4, 0.4) divided by squared graph distance to rank callees. The AI system can prioritize structurally significant dependencies over incidental ones, improving explanation quality for complex method calls.

4. Distance-aware snippet rendering: Automatically render callees within 1 hop as full method bodies and those at distance 2 as signatures only. The improved system balances token cost against contextual depth, avoiding both under- and over-explanation.

5. Unified visualization-reasoning substrate: Bind the AI's reasoning data structure to the exact graph the developer sees. The improved system can highlight which graph nodes contributed to an explanation, letting users verify AI decisions by eye and click through to source code—reducing blind trust in black-box outputs.

6. Clone-refactoring suggestion with AI explanation: When clone groups are detected (via CloMan), the system can automatically generate extract-to-parent refactoring suggestions by applying GACP's inheritance-collapse logic. The improved system can explain why a refactoring is beneficial, citing the graph distance and edge-type weights that justify merging sibling classes.

7. CVE-aware context pruning: Integrate OSV.dev vulnerability data into the graph, so the AI system can prioritize callees in vulnerable nodes when explaining security-sensitive code. The improved system can proactively warn about risky dependencies during explanation generation.

8. Deterministic, testable AI context selection: Because GACP is a pure function (no randomness, no LLM calls, no UI dependencies), the improved system can be unit-tested for prompt construction, enabling regression testing and cross-LLM reproducibility guarantees.

What the improved AI system can do:

• Explain any Java method with a context that is provably grounded in the project's actual dependency structure, not approximate similarity.

• Automatically collapse redundant sibling explanations into a parent-contract-plus-delegate form, saving tokens and reducing cognitive load.

• Show the developer exactly which graph edges and nodes justified each included code snippet, enabling verification and trust.

• Adapt its explanation depth (full body vs. signature) based on structural proximity, not arbitrary caps.

• Detect clone-induced redundancy and suggest refactorings with a clear, graph-based rationale.

• Flag security-relevant callees during explanation, integrating vulnerability awareness into everyday comprehension.

• Produce identical prompts across Claude, GPT, and Llama families, ensuring consistent behavior regardless of backend.