Toward Executable Repository-Level Code Generation via Environment Alignment

Abstract: LLMs have achieved strong performance on code generation, but existing methods still struggle with repository-level code generation under executable validation. Under this evaluation setting, success is determined not by the plausibility of isolated code fragments, but by whether a generated multi-file repository can be successfully installed, have its dependencies and internal references resolved, be launched, and be validated in a real execution environment. To address this challenge, we propose EnvGraph, a framework for repository-level code generation that formulates repository executability as an environment alignment problem. EnvGraph jointly models two coupled conditions for successful repository execution, namely external dependency satisfaction and repository-internal reference resolution. It maintains a dual-layer environment representation, uses execution evidence to perform execution-evidence-based attribution, and guides repository generation through a unified targeted revision mechanism within an iterative alignment loop. We evaluate EnvGraph on repository-level code generation with three representative backbone LLMs and compare it against representative environment-aware and repository-level baselines. Experimental results show that EnvGraph consistently achieves the best performance on these repository-level benchmarks. In particular, it outperforms the strongest non-EnvGraph baseline by an absolute margin of 5.72--5.87 percentage points in Functional Correctness and 4.58--8.66 percentage points in Non-Functional Quality.

• The paper presents nv, which reframes repository-level code generation as an iterative environment alignment problem by jointly modeling external dependencies and internal references.
• It employs a dual-layer graph representation and execution-evidence-based attribution to precisely identify and target root causes of generation failures.
• Empirical results show nv outperforms baselines by significantly improving both functional correctness and non-functional quality across multiple benchmarks.

Toward Executable Repository-Level Code Generation via Environment Alignment

Problem Statement and Motivation

Modern LLM-driven code generation research has increasingly shifted focus toward repository-level tasks, where systems are expected to synthesize multi-file, installable repositories from high-level natural language requirements. In this setting, validation is not limited to local plausibility or passing functional tests for single files, but instead demands that the generated repository can be successfully installed, dependencies resolved, all internal references correctly wired, and the project executable within a realistic environment. The principal failure sources in this context extend beyond logic errors to include misalignment with external dependencies and broken repository-internal references—challenges difficult to distinguish solely from execution failure symptoms.

A motivating example (Figure 1) illustrates that identical execution errors (e.g., ModuleNotFoundError) may result from unmet external dependencies or broken internal references, impeding effective iterative revision strategies based solely on observed symptoms.

Figure 1: A motivating example of repository-level code generation under executable validation. The same execution symptom may arise from unmet external dependencies, broken repository-internal references, or both.

Analysis of failed repository generations on NL2Repo-Bench (Figure 2) confirms this duality: environment-related failures arise both from external dependency mismatches and unresolved internal references, sometimes in tandem, demonstrating that executability cannot be assured by dependency handling alone.

Figure 2: Environment-related failure types in failed direct generations on NL2Repo-Bench, highlighting the prevalence of internal reference and dependency issues.

The nv Framework

Formulation as Environment Alignment

nv reformulates repository-level code generation as an iterative environment alignment problem. It explicitly models two coupled prerequisites for repository executability: external dependency satisfaction and repository-internal reference resolution. Generation is steered not by undifferentiated execution failures, but by systematic attribution of the root failure source, enabling targeted, state-dependent revision.

Dual-Layer Environment Representation

nv introduces a dual-layer graph-based representation:

• External Environment Graph: Models satisfaction of declared and inferred external dependencies by constructing a bipartite graph over project, file, and package nodes, encoding package usage and manifest declarations. Mismatch detection pinpoints missing or inconsistent dependency declarations (see Figure 3).

  Figure 3: Example external environment graph for repository Client, revealing unmet dependency requirements.

• Repository Dependency Graph: Encodes internal structural dependencies between files, modules, symbols, and unresolved references, constructed via static code analysis. This representation enables immediate detection of missing files, broken imports, and unresolvable internal module references (see Figure 4).

  Figure 4: Example repository dependency graph for repository Client, exposing unresolved internal module import.

Maintaining both graphs in tandem captures non-redundant root causes of failures, which guides the resolution process after each execution attempt.

Execution-Evidence-Based Attribution

Upon execution, nv aggregates installation logs, stack traces, and test results, then employs an LLM only for evidence normalization. A deterministic attribution policy then identifies the dominant misalignment: (1) unmet external dependencies, (2) broken internal references, or (3) residual logic faults. Failure source precedence follows the causal structure of executability constraints (dependencies > internal structure > logic).

Targeted and Unified Repository Revision

When the dominant failure cause is identified, nv performs a unified but state-conditioned repository revision, prioritizing dependency artifacts or internal structural corrections as appropriate. Graph-guided refinement ensures that revisions directly address the current primary source of misalignment without regressing previously established executability properties.

Iterative Alignment Loop

This process is iterated: after each execution, environment graphs and evidence are updated, attribution repeated, and targeted revision applied. The loop halts on executable success or when a revision budget is exhausted. Figure 5 visually summarizes the nv workflow.

Figure 5: Overview of nv workflow; dual-layer representation, execution-evidence-based attribution, and targeted revision in an iterative loop.

Empirical Evaluation

nv is evaluated using RAL-Bench and NL2Repo-Bench, which stress both functional correctness and non-functional (engineering) quality at repository scale using multiple LLM backbones. Compared methods include state-of-the-art environment-aware baselines (VersiCode (Wu et al., 2024), APIMig [kuang2025apimig]) and repository-level planning and graph methods (Repo2Run, CodePlan, RepoGraph).

Core Results

nv achieves the highest Functional Correctness and Non-Functional Quality on both benchmarks under all backbones, with absolute improvements over the strongest baselines of 5.72–5.87 points (functional) and 4.58–8.66 points (non-functional). This superiority holds across various LLMs (GPT-5, DeepSeek-V3, Gemini-3) and task granularities, including hard and large repositories. Notably, single-aspect baselines improve on their specific dimensions but do not achieve the holistic executability required for repository-level synthesis.

Ablation Analysis

Component ablation (Table 1) shows that both environment graphs are individually necessary; removal of either consistently degrades functional correctness (up to 7 points for the internal dependency graph). The largest accuracy drops result from ablating execution-evidence-based attribution (up to 11 points) and disabling iterative alignment, emphasizing that informed, evidence-guided iteration is critical to effectiveness.

Failure Analysis and Limitations

Analysis of remaining failures (Figure 6) reveals that, once environment misalignment is mitigated, residual logic faults dominate (~40–46%), though shortcomings in packaging, interface coordination, and implementation completeness persist, especially for weaker backbone models.

Figure 6: Failure-type distribution for nv by model, with residual logic faults the dominant remaining challenge.

Implications and Prospects

This work demonstrates that achieving repository executability at generation time fundamentally requires joint modeling of external and internal environment alignment. Methods targeting only dependencies or structural planning can improve generation outcomes in their respective domains but frequently stall when confronted by multi-source or ambiguous execution failures. The attribution-plus-targeted-iteration paradigm of nv sets a new standard for future repository-level generation frameworks.

From a practical perspective, enforcement of dual-layer alignment can reduce human intervention during LLM-based codebase bootstrapping or migration tasks. Theoretically, the architecture operationalizes the insight that LLMs must be equipped with real environment feedback not just as revision cues but as inputs for high-fidelity failure attribution, guiding repository adaptation along causally sound axes.

Future research directions include: (1) extending graph representations to richer semantics (e.g., dynamic resource requirements, external service interactions), (2) enhancing attribution granularity to finer-grained fault localization, and (3) integrating post-alignment logic-level program repair or synthesis modules to address residual logic faults that now constitute the primary bottleneck.

Conclusion

nv establishes a state-of-the-art baseline for executable repository-level code generation by framing the task as environment alignment, leveraging dual-layer graphs, and using evidence-guided, targeted revision. This architecture produces repositories with increased executability and engineering quality across multiple LLMs and settings, and clarifies the remaining challenges at the intersection of environment and logic for the research community. The environment alignment mechanism suggests a paradigm shift for future repository-scale synthesis and refinement systems.