💻 computer science

Taming the Drift: Context-aware Repair of Dockerfile Drift during Software Evolution

This paper presents Cadre, a context-aware framework that leverages static analysis to construct a Context-aware Dependency Graph (CDG) for generating targeted patches that effectively repair Dockerfile drift, outperforming existing rule-based and LLM-based baselines on the newly introduced $D^3$ benchmark of 1,040 real-world drift instances.

Original authors: Chengjie Wang, Jingzheng Wu, Xiang Ling, Tianyue Luo, Chen Zhao

Published 2026-07-15

📖 6 min read🧠 Deep dive

CC BY 4.0

Original authors: Chengjie Wang, Jingzheng Wu, Xiang Ling, Tianyue Luo, Chen Zhao

Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer

Imagine you're building a robot in your garage. You've written a perfect instruction manual (the Dockerfile) that tells your robot exactly what parts to grab, where to put them, and how to assemble them. But then, you decide to upgrade the robot's brain (the source code) and swap out a few wires. You forget to update the manual to match these new parts.

Now, when you try to build the robot, it sputters and dies. The manual isn't "broken" in a grammatical sense; the words are fine. But the manual is drifting away from reality. It's trying to grab a part that no longer exists or use a tool that's been replaced. In the world of software, this is called Dockerfile drift, and it causes computers to fail silently, leaving developers scratching their heads for days.

The Old Way: Guessing in the Dark

Previous tools tried to fix this by just reading the manual and the error message. It's like trying to fix a car engine by only looking at the "Check Engine" light and the owner's manual, without ever opening the hood to see the actual wires.

Some tools used rigid rules (like a checklist), while others used super-smart AI (Large Language Models) to guess the fix. But here's the problem: these AI tools were drowning in information. They were handed the entire garage—every single screw, every old manual, and every box of junk—along with the error message. The AI got so overwhelmed by the noise that it either gave up or hallucinated a crazy fix that didn't work. In fact, in about 41 to 58 out of every batch of problems, these AI tools simply failed to produce any answer because the "instruction list" was too long for them to read.

The New Hero: Cadre (The Detective)

Enter Cadre, a new framework that acts like a brilliant detective. The authors, Chengjie Wang and his team, realized that the secret to fixing the robot isn't giving the detective more stuff to read, but giving them the right map.

Their big idea is simple: Structure matters more than volume. Knowing which specific wire connects to which specific screw is way more important than reading a thousand pages of unrelated text.

Cadre does this in three magical steps:

The Context Profiler (The Time Traveler): Before trying to fix anything, Cadre simulates the entire building process step-by-step. It watches exactly which files are copied, which variables are set, and which tools are called. It builds a mental model of the "state" of the project at every single moment.
The CDG (The Dependency Map): Using that simulation, Cadre draws a Context-aware Dependency Graph (CDG). Think of this as a subway map for your software. It shows exactly how the "FROM" instruction (the base) connects to the "COPY" instruction (the parts) and finally to the "RUN" instruction (the assembly). If a file changes, the map shows exactly which instructions will trip over it.
The Two-Step Fix (The Smart Filter): Instead of dumping the whole garage on the AI, Cadre asks the AI a smart question first: "Based on this map and the error, which specific files do you actually need to see?"
- Step 1: The AI picks only the relevant files (the "Key Files").
- Step 2: The AI reads only those files and writes the fix.

This keeps the AI's "brain" from overflowing. While other methods failed to generate a patch in 41–58 cases because the prompt was too huge, Cadre produced a patch for every single one of its attempts.

The Results: Does it Work?

The team tested Cadre on 1,040 real-world examples they dug out of GitHub's history (a dataset they called 𝐷3). These weren't fake problems; they were actual failures that happened in real software projects, complete with the exact settings needed to reproduce them.

Here is how Cadre stacked up:

Cadre fixed 35.22% of the problems.
The best previous AI method (without this smart mapping) fixed 28.48%.
The old rule-based checklist method only fixed 9.34%.

That means Cadre is 1.24 times better than the best AI competitor and nearly 3 times better than the old rule-based tools.

But the real magic happens when the problem gets "stale." Imagine a broken build that nobody fixed for five or six updates. The recent code changes look totally unrelated to the original error. Most tools get confused and give up. But because Cadre uses the CDG map, it can trace the broken wire back to its origin, even if it's buried deep in history. At five or more updates away, Cadre fixed 25.9% of the problems, while the next best tool only managed 19.7%. The gap actually grew wider as the problems got older, proving that the map is a durable signal.

What It's NOT

It's important to know what Cadre doesn't do. It's not a magic wand that fixes everything.

It can't fix problems caused by the internet being down or a server running out of disk space.
It can't fix bugs inside the actual code logic (like a math error in the program itself); it only fixes the build instructions.
In about 65% of the cases where it failed, the issue was a complex build-tool constraint that simply couldn't be solved by changing the manual (like a missing package in a private registry).

The Takeaway

The authors suggest that for the future of software maintenance, we need to stop just throwing more data at AI and start teaching it how to understand the structure of dependencies. By building a map of how files and instructions connect, Cadre proved that a little bit of smart context goes a long way. It's not about reading the whole library; it's about knowing exactly which page to turn to.

All the code and the dataset of 1,040 real-world drifts are open for anyone to check, ensuring that this isn't just a theory, but a tool built on real, reproducible evidence.

Technical Summary: Taming the Drift: Context-aware Repair of Dockerfile Drift during Software Evolution

1. Problem Definition: Dockerfile Drift

Modern software development relies heavily on Continuous Integration and Continuous Deployment (CI/CD) pipelines, where Docker serves as the de facto standard for ensuring reproducible build environments. However, a critical issue known as Dockerfile drift undermines this reliability. Drift occurs when a Dockerfile fails to absorb changes made to the application's source code, leading to a mismatch between the build script and the evolving repository state. Unlike syntax errors, drift is an internal co-evolution problem where the fix information resides within the same repository that produced the failure.

Drift manifests as incorrect file paths, mismatched environment variables, outdated dependency specifications, or platform changes. These failures are particularly difficult to repair automatically due to three core challenges:

C1 (Context Extraction): The build state (working directory, environment variables, file sets) is determined by the cumulative execution of prior instructions, not just the text of the Dockerfile. Existing rule-based and LLM-based methods often treat the Dockerfile in isolation, failing to model these dynamic interactions.
C2 (Cross-Instruction Dependencies): Instructions often depend on artifacts produced by earlier steps in non-obvious ways (e.g., a RUN command operating on files introduced by a prior COPY or variables set by an ARG). These dependencies are not syntactically visible in isolation.
C3 (Locating Root Causes): Error logs often point to the failing instruction but rarely identify the root cause, which may stem from a code change introduced in a previous commit.

2. Methodology: The Cadre Framework

The authors propose Cadre, a context-aware framework designed to repair Dockerfile drift by explicitly modeling the build context. The central design insight is that context structure determines repair quality more than context volume. Cadre addresses the three challenges through four integrated phases:

2.1 Dockerfile Drift Extractor (DodeX)

To address the lack of realistic benchmarks, the authors developed DodeX, a pipeline that mines real-world drift instances from GitHub Actions CI logs. Unlike static snapshot datasets, DodeX captures the complete build configuration, including dynamic build arguments, target platforms, and the exact code-change diffs that triggered the failure. This ensures every extracted instance is locally reproducible.

2.2 Instruction-level Context Profiler

To solve C1, Cadre performs a stateful simulation of the Docker build process. It traverses the Dockerfile instruction by instruction, maintaining a Context State ( $\sigma$ ) that tracks:

The current working directory ( $\delta$ ).
Resolved environment variables ( $\varepsilon$ ).
The set of files present in the container ( $\Phi$ ).

Crucially, the profiler employs build-system-aware parsers for 11 major ecosystems (e.g., Go, Python, npm, Maven). Instead of treating RUN commands as opaque strings, these parsers infer implicit file dependencies (e.g., inferring that go build depends on go.mod and all *.go files in the directory). This produces an Instruction Context Map (ICM) linking every instruction to its precise build-time state.

2.3 Context-aware Dependency Graph (CDG)

To solve C2, the ICM is converted into a Context-aware Dependency Graph (CDG), a directed acyclic graph ( $G = (V, E)$ ) that makes inter-instruction dependencies explicit:

Vertices: Include instruction nodes ( $V_I$ ) and file nodes ( $V_F$ ).
Edges: Include sequential edges ( $E_S$ ) representing control flow and dataflow edges ( $E_D$ ) representing "read-from" dependencies between files and instructions.
This graph allows the system to trace failure propagation paths across instruction boundaries, identifying how a change in a source file (e.g., go.mod) invalidates a specific RUN instruction via intermediate COPY or ARG steps.

2.4 Context-refined Repair Workflow

To solve C3 and manage token limits, Cadre employs a two-step agentic workflow rather than a single-shot prompt:

Context Inquiry: The LLM is presented with the error log, the code diff, and a pruned version of the CDG. It is asked to select the minimal set of relevant files and grep keywords required for repair. This step filters out irrelevant context before file contents are loaded.
Repair Generation: The system retrieves only the selected files and generates a targeted patch.
This approach prevents prompt overflow (a common failure mode in competing LLM methods) and ensures the model focuses on causally relevant evidence.

3. Key Contributions

Cadre Framework: A novel repair framework grounded in the insight that context structure is more valuable than volume. It integrates a stateful context profiler, a dependency graph, and a two-step LLM workflow.
DodeX and $D^3$ Benchmark: The creation of DodeX, a pipeline for extracting drift instances with full build configurations, and $D^3$ , the first Dockerfile drift benchmark where all 1,040 instances are locally reproducible using exact parameters from original CI runs.
Empirical Evaluation: A comprehensive evaluation comparing Cadre against rule-based baselines (Parfum), retrieval-based baselines (FlakiDock), and vanilla LLMs.

4. Experimental Results

The framework was evaluated on the $D^3$ benchmark (653 executable instances after filtering for network timeouts).

Repair Effectiveness: Cadre achieved a 35.22% repair rate, outperforming the rule-based baseline (Parfum, 9.34%) by 2.78 $\times$ and the best LLM-based baseline (Vanilla-LLM, 28.48%) by 1.24 $\times$ .
Token Efficiency & Robustness: Cadre eliminated prompt-overflow failures entirely ( $|F_r| = 0$ ), keeping 95.25% of prompts under 30k tokens. In contrast, competing LLM methods failed to generate patches in 41–58 cases due to exceeding context limits.
Stale Drift Robustness: As drift instances became "stale" (persisting across multiple commits), the performance of diff-only approaches degraded significantly. At 5+ commits of distance, Cadre maintained a 25.9% success rate compared to 19.7% for the best baseline, demonstrating that the CDG provides a structural signal robust to commit distance.
Ablation Studies: Removing the CDG reduced the repair rate by 4.29 percentage points, while removing the two-step workflow reduced it by 3.67 points and reintroduced prompt-overflow failures. The components were found to be mutually reinforcing.

5. Significance and Claims

The paper claims that explicit dependency modeling is a durable repair signal. The authors argue that the advantage of context-aware approaches over diff-only or retrieval-based methods widens as drift ages across commits. The study suggests that context-aware Infrastructure as Code (IaC) maintenance is a productive direction for future tool development.

The authors modestly note limitations: the CDG is based on static analysis and cannot fully capture runtime factors like package registry states or network conditions, which account for some unresolved failures. Additionally, the benchmark is limited to public GitHub repositories. However, the work establishes that modeling the build context explicitly—specifically the flow of data and control across instructions—is critical for automating the repair of evolving software configurations.