App: Diff Reviewer — Compare Versions

A5.0 What This Teaches

• Generating a unified diff with Python's standard library difflib
• Embedding the diff in a prompt for risk assessment
• Short-circuiting the API call when the files are identical
• Combining stdlib tools with LLMs to get insights that neither provides alone

A5.1 What a Diff Shows

• Lines starting with - were in the old file and removed
• Lines starting with + are in the new file and added
• Lines with no prefix are context - unchanged lines that appear on both sides

--- old.py
+++ new.py
@@ -4,7 +4,10 @@
 def load_data(filename):
-    with open(filename) as f:
-        return f.read()
+    try:
+        with open(filename, encoding="utf-8") as f:
+            return f.read()
+    except FileNotFoundError:
+        return None

A5.2 Generating the Diff with difflib

# gen_diff.py - compute a unified diff between two files.
import difflib
from pathlib import Path

def compute_diff(old_path: str, new_path: str) -> str:
    old_lines = Path(old_path).read_text(encoding="utf-8").splitlines(keepends=True)
    new_lines = Path(new_path).read_text(encoding="utf-8").splitlines(keepends=True)

    diff = difflib.unified_diff(
        old_lines,
        new_lines,
        fromfile=old_path,
        tofile=new_path,
        lineterm="",
    )
    return "".join(diff)

A5.3 The Review Prompt

# diff_prompt.py - build the review prompt.
def build_review_prompt(diff_text: str) -> str:
    return (
        "Review this unified diff. Explain:\n"
        "(1) What changed and why it likely changed.\n"
        "(2) Any risks introduced (bugs, security issues, breaking changes).\n"
        "(3) Whether the change looks complete or if anything is missing.\n\n"
        f"```diff\n{diff_text}\n```"
    )

A5.4 Complete Implementation

# diff_review.py - compare two files and review the changes with Claude.
# Usage: python diff_review.py old.py new.py

import sys
import difflib
from pathlib import Path
import anthropic

def read_file(path: str) -> list[str]:
    try:
        return Path(path).read_text(encoding="utf-8").splitlines(keepends=True)
    except FileNotFoundError:
        print(f"Error: file not found: {path}")
        sys.exit(1)

def compute_diff(old_path: str, new_path: str) -> str:
    old_lines = read_file(old_path)
    new_lines = read_file(new_path)
    return "".join(difflib.unified_diff(
        old_lines, new_lines,
        fromfile=old_path, tofile=new_path, lineterm="",
    ))

def main():
    if len(sys.argv) < 3:
        print("Usage: python diff_review.py old.py new.py")
        sys.exit(1)

    old_path, new_path = sys.argv[1], sys.argv[2]
    diff = compute_diff(old_path, new_path)

    if not diff:
        print("Files are identical.")
        sys.exit(0)

    prompt = (
        "Review this unified diff. Explain:\n"
        "(1) What changed and why it likely changed.\n"
        "(2) Any risks introduced (bugs, security issues, breaking changes).\n"
        "(3) Whether the change looks complete or if anything is missing.\n\n"
        f"```diff\n{diff}\n```"
    )

    client = anthropic.Anthropic()
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}],
    )

    print(response.content[0].text)

if __name__ == "__main__":
    main()

A5.5 Sample Output

$ python diff_review.py old.py new.py

(1) What changed and why it likely changed.
The load_data function gained an explicit encoding argument ("utf-8") and a
try/except block that returns None when the file is not found. This is a
defensive improvement - the original would raise an unhandled FileNotFoundError
on a missing file.

(2) Risks introduced.
Returning None on error means callers must now check the return value before
using it. Any code that does `data.split(...)` on the result will raise
AttributeError if the file is missing. The change shifts responsibility for
error handling to the caller without documenting that contract.

(3) Completeness.
The change looks complete for the stated goal of avoiding a crash. A type hint
on the return value (str | None) would make the None case explicit and would
help tools like mypy catch callers that forget to check.

A5.6 Handling Empty Diffs

# empty_diff_guard.py - avoid an unnecessary API call.
diff = compute_diff(old_path, new_path)

if not diff:
    print("Files are identical.")
    sys.exit(0)

# only reaches here if there are actual changes
response = client.messages.create(...)

A5.7 Exercise

risk_instruction = (
    "Rate the overall risk of this change on a scale of 1-5 "
    "where 1 is trivial and 5 is high-risk. "
    "Give one sentence justification."
)

python diff_review.py old.py new.py --risk

A5.8 Common Mistakes

Key Terms