feat: add dry_run preview to apply_refactor_tool (#176)

[azizur100389]

Summary

Adds a dry_run: bool = False parameter to apply_refactor_tool so callers can preview a unified diff of every edited file without writing to disk. When dry_run=True the pending refactor is kept in the cache so the caller can review the diffs and call the tool again with the same refactor_id to actually apply — the two-step commit pattern the maintainer explicitly validated in the issue thread.

Closes #176.

Root cause

apply_refactor_tool wrote changes to disk immediately with no confirmation step. In agentic workflows where multiple MCP tools are chained, this tool could be called as a side effect of a broader task the developer didn't intend to modify files for — and there was no undo path beyond git checkout.

Maintainer validation from the issue thread:

Valid security/UX concern. apply_refactor_tool currently writes changes to disk immediately with no confirmation step. The suggested two-step approach (dry_run first, then confirmed=true to apply) is the right pattern for agentic workflows...

Fix

1. code_review_graph/refactor.py — apply_refactor() gains dry_run: bool = False. When True, compute a unified diff via stdlib difflib.unified_diff between the original file content and the post-edit content, collect per-file entries in a diffs list, and return without writing. The preview is not popped from _pending_refactors in dry-run mode so a follow-up real apply works.
2. code_review_graph/tools/refactor_tools.py — apply_refactor_func() threads dry_run through.
3. code_review_graph/main.py — apply_refactor_tool MCP decorator exposes dry_run to clients with an updated docstring.
4. Path-traversal validation and expiry checks still run in dry-run mode — dry-run is not an escape hatch for security.

Return shape

The non-dry-run path is unchanged (no new keys) so no existing caller breaks. Dry-run adds two keys:

{
    "status": "ok",
    "applied": 0,
    "files_modified": [],
    "edits_applied": 0,
    "dry_run": True,
    "diffs": [{"file": "...", "diff": "--- a/...\n+++ b/...\n@@ ..."}]
}

Tests added (tests/test_refactor.py::TestApplyRefactor)

• test_apply_refactor_dry_run_returns_diff — valid unified diff, file on disk untouched, preview still cached
• test_apply_refactor_dry_run_then_apply — dry-run followed by real apply with the same refactor_id writes the file and consumes the preview
• test_apply_refactor_dry_run_blocks_path_traversal — path-traversal check still fires
• test_apply_refactor_dry_run_rejects_expired — expired previews still rejected

Test results

Stage	Result
Stage 1 — new targeted tests	4/4 passed
Stage 2 — tests/test_refactor.py full	26 passed, 16 pre-existing Windows file-lock teardown errors (verified identical on unchanged main)
Stage 3 — adjacent tests/test_tools.py	62 passed, 15 pre-existing Windows teardown errors
Stage 4 — full suite	699 passed, 6 pre-existing Windows failures in test_incremental/test_notebook (verified identical on main)
Stage 5 — ruff check on all 4 touched files	clean
Stage 6 — MCP tool-wrapper smoke test	dry_run=True returns valid diff without writing; dry_run=False after dry-run writes and consumes

Zero regressions. All pre-existing test issues are Windows-specific file-lock teardown failures that reproduce on unchanged main.

Why this fix is safe

• No new dependency — difflib is stdlib.
• Non-dry-run return shape is unchanged; existing callers and tests work unmodified.
• Dry-run preserves the refactor_id so a real apply can follow without re-running rename_preview.
• Security invariants (path traversal, expiry) are enforced in both modes.

[azizur100389]

Closing this — I just noticed v2.3.0 ships the dry-run preview as part of your super-PR #228. My implementation and the shipped one converge on the same two-step pattern (dry_run=True returns a unified diff via difflib, pending refactor is retained so a follow-up dry_run=False call applies it), so nothing to salvage here.

Thanks for landing it — glad the pattern matched what you had in mind. I've moved on to a smaller follow-up for the .ksh extension you flagged in #230 (tracked in #235, PR #236).