RepoRepair: Leveraging Code Documentation for Repository-Level Automated Program Repair

1. Problem Statement

Automated Program Repair (APR) has traditionally struggled to scale from isolated function-level fixes to repository-level maintenance. Current methods face two primary barriers:

• Context Limitations: Raw repository data is too large for LLM context windows, forcing reliance on shallow retrieval (e.g., directory trees, keyword search) which often misses critical semantic dependencies.
• Semantic Dispersion: Fault-relevant information is often scattered across multiple files and modalities (text and images). Existing tools, particularly those designed for Python (like SWE-bench Lite), often fail on complex, cross-file issues in JavaScript/TypeScript or multimodal contexts (SWE-bench Multimodal) because they lack a structured understanding of the repository's architecture.

2. Methodology: RepoRepair

RepoRepair is an agent-free, documentation-enhanced framework designed to bridge the gap between high-level issue descriptions and low-level code changes. It operates in three distinct stages:

A. Documentation Generation (The Core Innovation)

Instead of feeding raw code to the LLM, RepoRepair first generates a hierarchical code documentation system for the entire repository using a text-based LLM (DeepSeek-V3).

• Function-Level Documentation: Parses source files into ASTs to extract functions/classes. It generates standardized documentation including parameters, logic descriptions, usage notes, and output examples. This handles anonymous functions (common in JS/TS) by assigning standardized names.
• File-Level Documentation: Aggregates function-level docs and project structure trees to generate high-level summaries of each file's architectural role and dependencies.
• Incremental Strategy: Documentation is generated incrementally as issues are processed, reusing existing docs for unchanged files to optimize costs.

B. Hierarchical Fault Localization

The localization stage uses the generated documentation to pinpoint suspicious code, avoiding the token explosion of processing raw source code.

1. File Retrieval: The issue description (converted to text if multimodal) is vectorized and matched against file-level documentation using semantic similarity (FAISS). This filters the repository down to the top 50 relevant files.
2. File Localization: An LLM (Claude-4) analyzes the issue against the file-level documentation of the retrieved files to rank the top 5 most suspicious files using Chain-of-Thought (CoT) reasoning.
3. Function/Class Localization: The LLM further analyzes the function-level documentation of the suspicious files to identify specific classes or functions requiring modification.
   • Verification Mechanism: If no relevant functions are found in a suspicious file, the system discards that file and re-runs file localization, acting as a self-correcting filter.

C. Context-Aware Repair

Once suspicious units are identified, RepoRepair constructs a minimal repair context:

• Dependency-Aware Pruning: It retains the localized code, essential file scaffolding (imports, global vars), and any static dependencies referenced by the localized code. It aggressively removes unrelated code to reduce noise.
• Patch Generation: The LLM generates diff-formatted patches (Search/Replace pairs) rather than full file rewrites, reducing hallucination risks.
• Iterative Validation: Patches are validated against the repository's test suite. The system employs a combinatorial strategy (testing single-file patches, then pairs, etc.) and a temperature-based iteration (increasing temperature from 0.0 to 0.9) to explore diverse solutions until a passing patch is found.

3. Key Contributions

1. Documentation-Enhanced Framework: A novel agent-free approach that leverages LLM-generated hierarchical documentation to create structured semantic abstractions, enabling deep repository understanding without raw code overload.
2. Two-Tiered Localization: A mechanism that uses file-level docs for broad filtering and function-level docs for precise pinpointing, significantly improving localization accuracy over raw code retrieval.
3. Comprehensive Benchmarking: Extensive evaluation on both SWE-bench Lite (Python, text-only) and SWE-bench Multimodal (JS/TS, text+visual), demonstrating robustness across languages and modalities.
4. Open Artifacts: Public release of all generated documentation, source code, and experimental results to ensure reproducibility.

4. Experimental Results

RepoRepair was evaluated against state-of-the-art baselines (e.g., Agentless, SWE-Agent, GUIRepair, OpenHands).

• SWE-bench Lite:

  • Repair Rate: 45.7% (competitive with top tools like ExpeRepair at 60.3% but at a fraction of the cost).
  • Cost: $0.44 per fix (significantly lower than agent-based tools like SWE-Agent at $1.62).
  • Localization: 77.6% file-level accuracy.

• SWE-bench Multimodal (State-of-the-Art):

  • Repair Rate: 37.1%, surpassing the previous best (GUIRepair at 35.98% and Agentless Lite at 25.34%).
  • Cost: $0.56 per fix.
  • Localization: 59.8% file-level accuracy, a nearly 30% absolute improvement over Agentless Lite (30.4%). This highlights the method's superior ability to handle complex, cross-file issues.

• Ablation Studies:

  • Removing File Retrieval caused token costs to explode (15x increase) and performance to drop.
  • Removing Code Documentation caused a massive drop in repair rates (e.g., from 37.1% to ~26% on Multimodal), proving documentation is critical for semantic understanding.
  • Code Pruning was shown to be essential; full contexts introduced noise that reduced repair accuracy.

5. Significance

• Bridging the Semantic Gap: RepoRepair demonstrates that structured documentation acts as an effective intermediary, allowing LLMs to comprehend architectural intent and implicit contracts better than raw code retrieval.
• Cost-Effectiveness: By avoiding iterative agent loops and leveraging efficient documentation-based retrieval, RepoRepair achieves high performance at a very low inference cost, making it viable for large-scale industrial use.
• Multimodal Adaptability: The framework successfully handles multimodal issues (screenshots, UI bugs) by converting visual inputs into text for documentation matching, outperforming specialized multimodal tools in general repository repair.
• Scalability: The hierarchical approach allows the system to scale to large repositories where direct code analysis is infeasible due to context window limits.

In conclusion, RepoRepair establishes a new paradigm for repository-level APR, proving that semantic abstraction via documentation is a more effective strategy than raw code retrieval or complex agent interactions for solving complex, cross-file software defects.