uni-diff-patch 0.0.1__py3-none-any.whl

uni_diff_patch/core/search_replace.py

@@ -0,0 +1,140 @@
+"""Search-replace engine with line_hint disambiguation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Replacement:
+    """A single search-replace operation.
+
+    Args:
+        search: Text to find in the file (must be non-empty).
+        replace: Text to substitute in place of the search text.
+        line_hint: Approximate 1-based line number to disambiguate
+            when *search* matches more than once. The match closest
+            to this line is chosen.
+    """
+
+    search: str
+    replace: str
+    line_hint: int | None = None
+
+
+class SearchReplaceError(Exception):
+    """Raised when a search-replace operation cannot be completed."""
+
+
+class NoMatchError(SearchReplaceError):
+    """Search text was not found in the file content."""
+
+    def __init__(self, search: str, file_path: str) -> None:
+        preview = search[:80] + ("..." if len(search) > 80 else "")
+        super().__init__(
+            f"Search text not found in {file_path}: {preview!r}"
+        )
+        self.search = search
+        self.file_path = file_path
+
+
+class AmbiguousMatchError(SearchReplaceError):
+    """Search text matched multiple locations without a disambiguator."""
+
+    def __init__(
+        self, search: str, file_path: str, positions: list[int]
+    ) -> None:
+        preview = search[:80] + ("..." if len(search) > 80 else "")
+        lines = ", ".join(str(p) for p in positions[:5])
+        super().__init__(
+            f"Search text matches {len(positions)} locations in {file_path} "
+            f"(lines: {lines}): {preview!r}. "
+            f"Provide line_hint to disambiguate."
+        )
+        self.search = search
+        self.file_path = file_path
+        self.positions = positions
+
+
+def _find_line_number(content: str, char_offset: int) -> int:
+    """Convert a character offset to a 1-based line number."""
+    return content[:char_offset].count("\n") + 1
+
+
+def _find_all_occurrences(content: str, search: str) -> list[int]:
+    """Find all character offsets where *search* appears in *content*."""
+    offsets: list[int] = []
+    start = 0
+    while True:
+        idx = content.find(search, start)
+        if idx == -1:
+            break
+        offsets.append(idx)
+        start = idx + 1
+    return offsets
+
+
+def apply_replacements(
+    content: str,
+    replacements: list[Replacement],
+    file_path: str = "<unknown>",
+) -> str:
+    """Apply a sequence of search-replace operations to *content*.
+
+    Replacements are applied sequentially in order. Each replacement
+    operates on the result of the previous one.
+
+    Args:
+        content: Original file content.
+        replacements: Ordered list of replacements to apply.
+        file_path: File path for error messages.
+
+    Returns:
+        Modified content after all replacements.
+
+    Raises:
+        NoMatchError: If a search text is not found.
+        AmbiguousMatchError: If a search text matches multiple locations
+            and no line_hint is provided.
+    """
+    result = content
+
+    for rep in replacements:
+        if not rep.search:
+            raise SearchReplaceError("Search text must not be empty")
+
+        offsets = _find_all_occurrences(result, rep.search)
+
+        if not offsets:
+            raise NoMatchError(rep.search, file_path)
+
+        if len(offsets) == 1:
+            # 唯一匹配，直接替换
+            offset = offsets[0]
+        elif rep.line_hint is not None:
+            # 验证 line_hint 合法性
+            if rep.line_hint < 1:
+                raise SearchReplaceError(
+                    f"line_hint must be a positive integer, got {rep.line_hint}"
+                )
+            # 多个匹配，用 line_hint 选最近的
+            hint = rep.line_hint
+            lines = [_find_line_number(result, o) for o in offsets]
+            distances = [abs(line - hint) for line in lines]
+            min_dist = min(distances)
+            # 等距时不猜测，要求调用方提供更精确的 hint
+            closest = [i for i, d in enumerate(distances) if d == min_dist]
+            if len(closest) > 1:
+                positions = [lines[i] for i in closest]
+                raise AmbiguousMatchError(rep.search, file_path, positions)
+            offset = offsets[closest[0]]
+        else:
+            # 多个匹配且无消歧信息
+            positions = [_find_line_number(result, o) for o in offsets]
+            raise AmbiguousMatchError(rep.search, file_path, positions)
+
+        result = (
+            result[:offset] + rep.replace + result[offset + len(rep.search) :]
+        )
+
+    return result

uni_diff_patch/core/validator.py

@@ -0,0 +1,214 @@
+"""Patch validation via mpatch parsing and optional git apply --check."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import mpatch
+
+
+@dataclass
+class FileInfo:
+    """Per-file statistics extracted from a parsed patch."""
+
+    file_path: str
+    hunk_count: int
+    is_creation: bool
+
+
+@dataclass
+class ValidationResult:
+    """Result of patch validation.
+
+    Args:
+        valid: Whether the patch is structurally valid.
+        files: Per-file statistics.
+        total_hunks: Total number of hunks across all files.
+        parse_error: Error message if parsing failed.
+        git_apply_ok: Result of git apply --check (None if not run).
+        git_apply_error: Error output from git apply --check.
+    """
+
+    valid: bool
+    files: list[FileInfo] = field(default_factory=list)
+    total_hunks: int = 0
+    parse_error: str | None = None
+    git_apply_ok: bool | None = None
+    git_apply_error: str | None = None
+
+
+def _parse_header_only_diffs(content: str) -> list[FileInfo]:
+    """Parse git extended header-only diffs (rename, chmod without content changes).
+
+    mpatch.parse_auto cannot parse these since they have no hunk body.
+    We detect them by looking for 'diff --git' lines followed by
+    rename/mode headers without any @@ hunk markers.
+
+    Returns:
+        List of FileInfo for recognized header-only diffs, empty if none found.
+    """
+    files: list[FileInfo] = []
+    # 匹配 "diff --git a/X b/Y" 块
+    diff_blocks = re.split(r"(?=^diff --git )", content, flags=re.MULTILINE)
+    for block in diff_blocks:
+        block = block.strip()
+        if not block.startswith("diff --git "):
+            continue
+        # 如果有 @@ hunk，mpatch 应该已经处理了，这里只处理无 hunk 的
+        if "@@" in block:
+            continue
+
+        # 提取文件路径
+        first_line = block.split("\n")[0]
+        m = re.match(r"diff --git a/(.+?) b/(.+)", first_line)
+        if not m:
+            continue
+
+        file_path = m.group(2)
+        is_rename = "rename from" in block
+        is_chmod = "old mode" in block or "new mode" in block
+
+        if is_rename or is_chmod:
+            files.append(FileInfo(
+                file_path=file_path,
+                hunk_count=0,
+                is_creation=False,
+            ))
+
+    return files
+
+
+def validate_patch(
+    patch_content: str | None = None,
+    patch_path: str | None = None,
+    git_check: bool = False,
+    work_dir: str | None = None,
+) -> ValidationResult:
+    """Validate a unified diff patch.
+
+    Parses the patch with mpatch and optionally runs git apply --check.
+
+    Args:
+        patch_content: The patch text to validate (mutually exclusive with patch_path).
+        patch_path: Path to a patch file (mutually exclusive with patch_content).
+        git_check: If True, run git apply --check against work_dir.
+        work_dir: Working directory for git apply --check.
+
+    Returns:
+        ValidationResult with parse status and optional git check result.
+
+    Raises:
+        ValueError: If neither or both of patch_content/patch_path are provided.
+    """
+    if (patch_content is None) == (patch_path is None):
+        raise ValueError(
+            "Provide exactly one of patch_content or patch_path"
+        )
+
+    if patch_path is not None:
+        path = Path(patch_path)
+        if not path.is_file():
+            return ValidationResult(
+                valid=False,
+                parse_error=f"Patch file not found: {patch_path}",
+            )
+        try:
+            patch_content = path.read_text(encoding="utf-8")
+        except OSError as e:
+            return ValidationResult(
+                valid=False,
+                parse_error=f"Cannot read patch file {patch_path}: {e}",
+            )
+        except UnicodeDecodeError as e:
+            return ValidationResult(
+                valid=False,
+                parse_error=f"Patch file encoding error {patch_path}: {e}",
+            )
+
+    assert patch_content is not None
+
+    if not patch_content.strip():
+        return ValidationResult(
+            valid=False, parse_error="Patch content is empty"
+        )
+
+    # 用 mpatch 解析
+    try:
+        patches = mpatch.parse_auto(patch_content)
+    except Exception as e:
+        return ValidationResult(valid=False, parse_error=str(e))
+
+    # mpatch.parse_auto 无法解析 header-only diff（纯 rename/chmod）
+    # 如果 parse 结果为空，检查是否包含 git 扩展 header
+    if not patches:
+        header_files = _parse_header_only_diffs(patch_content)
+        if header_files:
+            return ValidationResult(
+                valid=True, files=header_files, total_hunks=0,
+            )
+        return ValidationResult(
+            valid=False, parse_error="No patches found in content"
+        )
+
+    files: list[FileInfo] = []
+    total_hunks = 0
+    for p in patches:
+        hunk_count = len(p)
+        total_hunks += hunk_count
+        files.append(
+            FileInfo(
+                file_path=str(p.file_path),
+                hunk_count=hunk_count,
+                is_creation=p.is_creation,
+            )
+        )
+
+    result = ValidationResult(
+        valid=True,
+        files=files,
+        total_hunks=total_hunks,
+    )
+
+    # 可选 git apply --check
+    if git_check:
+        result.git_apply_ok, result.git_apply_error = _run_git_apply_check(
+            patch_content, work_dir
+        )
+        if not result.git_apply_ok:
+            result.valid = False
+
+    return result
+
+
+def _run_git_apply_check(
+    patch_content: str, work_dir: str | None
+) -> tuple[bool, str | None]:
+    """Run git apply --check and return (success, error_message)."""
+    # 先验证 work_dir 存在
+    if work_dir and not Path(work_dir).is_dir():
+        return False, f"work_dir does not exist or is not a directory: {work_dir}"
+
+    cmd = ["git", "apply", "--check"]
+    try:
+        proc = subprocess.run(
+            cmd,
+            input=patch_content,
+            capture_output=True,
+            text=True,
+            cwd=work_dir,
+            timeout=30,
+        )
+        if proc.returncode == 0:
+            return True, None
+        return False, (proc.stderr or proc.stdout).strip()
+    except FileNotFoundError:
+        return False, "git executable not found in PATH"
+    except NotADirectoryError:
+        return False, f"work_dir is not a valid directory: {work_dir}"
+    except PermissionError:
+        return False, f"Permission denied accessing work_dir: {work_dir}"
+    except subprocess.TimeoutExpired:
+        return False, "git apply --check timed out"

uni_diff_patch/models.py

@@ -0,0 +1,166 @@
+"""Pydantic models for MCP/CLI input validation and schema generation.
+
+These models are the single source of truth for the generate_patch API.
+FastMCP auto-generates JSON Schema from these for LLM tool discovery.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal, Union
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class ReplacementModel(BaseModel):
+    """A single search-replace operation.
+
+    Attributes:
+        search: Text to find in the file (must be non-empty).
+        replace: Text to substitute in place of the search text.
+        line_hint: Approximate 1-based line number to disambiguate
+            when search matches more than once. Closest match wins.
+    """
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    search: str = Field(..., min_length=1, description="Text to find in the file")
+    replace: str = Field(..., description="Replacement text")
+    line_hint: int | None = Field(
+        default=None, ge=1, description="Approximate line number to disambiguate multiple matches"
+    )
+
+
+class _ChangeBase(BaseModel):
+    """Common fields for all change types."""
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    file_path: str = Field(..., min_length=1, description="Target file path (absolute or relative)")
+
+    @field_validator("file_path")
+    @classmethod
+    def _no_control_chars(cls, v: str) -> str:
+        if any(c in v for c in ("\n", "\r", "\x00")):
+            raise ValueError("file_path contains invalid control characters")
+        return v
+
+
+class FileContentChange(_ChangeBase):
+    """Provide the full new file content. Tool reads original from disk and diffs.
+
+    Best for: complete rewrites or when you already have the full new content.
+    """
+
+    mode: Literal["file_content"] = "file_content"
+    new_content: str = Field(..., description="Complete new file content")
+    encoding: str = Field(default="utf-8", description="File encoding for reading the original")
+    context_lines: int = Field(default=3, ge=0, description="Number of context lines in the diff")
+
+
+class SearchReplaceChange(_ChangeBase):
+    """Provide search/replace pairs. Tool reads file, applies replacements, and diffs.
+
+    Best for: small targeted changes in large files (most token-efficient).
+    """
+
+    mode: Literal["search_replace"] = "search_replace"
+    replacements: list[ReplacementModel] = Field(
+        ..., min_length=1, description="Ordered list of search-replace operations"
+    )
+    encoding: str = Field(default="utf-8", description="File encoding for reading the original")
+    context_lines: int = Field(default=3, ge=0, description="Number of context lines in the diff")
+
+
+class CreateFileChange(_ChangeBase):
+    """Create a new file. Fails if the file already exists.
+
+    Best for: adding new files to the project.
+    """
+
+    mode: Literal["create_file"] = "create_file"
+    new_content: str = Field(..., description="Content for the new file")
+
+
+class DeleteFileChange(_ChangeBase):
+    """Delete an existing file. Tool reads current content and generates deletion diff.
+
+    Best for: removing files from the project.
+    """
+
+    mode: Literal["delete_file"] = "delete_file"
+    encoding: str = Field(default="utf-8", description="File encoding for reading the file")
+
+
+class TextPairChange(_ChangeBase):
+    """Provide both old and new text directly. No disk read needed.
+
+    Best for: virtual files, or when you already have both versions in memory.
+    """
+
+    mode: Literal["text_pair"] = "text_pair"
+    old_text: str = Field(..., description="Original text content")
+    new_text: str = Field(..., description="New text content")
+    context_lines: int = Field(default=3, ge=0, description="Number of context lines in the diff")
+
+
+class RenameFileChange(_ChangeBase):
+    """Rename/move a file, optionally with content changes.
+
+    Generates git-compatible rename diff with extended headers.
+    file_path is the old (source) path, new_path is the destination.
+    """
+
+    mode: Literal["rename_file"] = "rename_file"
+    new_path: str = Field(..., min_length=1, description="New file path after rename")
+    new_content: str | None = Field(
+        default=None, description="Optional new content (if also modifying the file)"
+    )
+    encoding: str = Field(default="utf-8", description="File encoding for reading the original")
+    context_lines: int = Field(default=3, ge=0, description="Number of context lines in the diff")
+
+    @field_validator("new_path")
+    @classmethod
+    def _no_control_chars_new(cls, v: str) -> str:
+        if any(c in v for c in ("\n", "\r", "\x00")):
+            raise ValueError("new_path contains invalid control characters")
+        return v
+
+
+class ChmodChange(_ChangeBase):
+    """Change file permissions, optionally with content changes.
+
+    Generates git-compatible mode change diff with extended headers.
+    Mode values use git's octal format (e.g. "100644", "100755").
+    """
+
+    mode: Literal["chmod"] = "chmod"
+    old_mode: str = Field(..., pattern=r"^1[0-7]{5}$", description='Old file mode (e.g. "100644")')
+    new_mode: str = Field(..., pattern=r"^1[0-7]{5}$", description='New file mode (e.g. "100755")')
+    new_content: str | None = Field(
+        default=None, description="Optional new content (if also modifying the file)"
+    )
+    encoding: str = Field(default="utf-8", description="File encoding for reading the original")
+    context_lines: int = Field(default=3, ge=0, description="Number of context lines in the diff")
+
+    @field_validator("new_mode")
+    @classmethod
+    def _modes_must_differ(cls, v: str, info) -> str:
+        if info.data.get("old_mode") == v:
+            raise ValueError("old_mode and new_mode must be different")
+        return v
+
+
+# Discriminated union — FastMCP uses this to generate a precise JSON Schema
+# with oneOf and "mode" as discriminator
+FileChange = Annotated[
+    Union[
+        FileContentChange,
+        SearchReplaceChange,
+        CreateFileChange,
+        DeleteFileChange,
+        TextPairChange,
+        RenameFileChange,
+        ChmodChange,
+    ],
+    Field(discriminator="mode"),
+]

uni_diff_patch/server.py

@@ -0,0 +1,147 @@
+"""MCP server exposing generate_patch and validate_patch tools."""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import ValidationError
+
+from uni_diff_patch.core.diff_engine import (
+    DiffGenerationError,
+    GenerateResult,
+    generate_patch,
+)
+from uni_diff_patch.core.search_replace import SearchReplaceError
+from uni_diff_patch.core.validator import ValidationResult
+from uni_diff_patch.core.validator import validate_patch as _validate_patch
+from uni_diff_patch.models import FileChange
+
+mcp = FastMCP(
+    "uni-diff-patch",
+    instructions=(
+        "Generate valid unified diff patches deterministically. "
+        "LLMs provide file content or search/replace pairs, "
+        "the tool computes correct diffs that git apply accepts."
+    ),
+)
+
+
+def _parse_changes(raw_changes: list) -> list[FileChange]:
+    """Parse and validate a list of raw change dicts into Pydantic models.
+
+    Args:
+        raw_changes: List of dicts from MCP/CLI input.
+
+    Returns:
+        List of validated FileChange models (discriminated union).
+
+    Raises:
+        ValueError: On validation failure with clear error message.
+    """
+    results: list[FileChange] = []
+    from pydantic import TypeAdapter
+    adapter = TypeAdapter(FileChange)
+
+    for i, raw in enumerate(raw_changes):
+        if not isinstance(raw, dict):
+            raise ValueError(f"changes[{i}] must be an object, got {type(raw).__name__}")
+        try:
+            results.append(adapter.validate_python(raw))
+        except ValidationError as e:
+            # 提取 Pydantic 的错误信息，格式化为人类可读
+            errors = "; ".join(
+                f"{'.'.join(str(loc) for loc in err['loc'])}: {err['msg']}"
+                for err in e.errors()
+            )
+            raise ValueError(f"changes[{i}] validation failed: {errors}")
+    return results
+
+
+@mcp.tool()
+def generate_patch_tool(
+    changes: list[FileChange],
+    output_path: str | None = None,
+    work_dir: str | None = None,
+    overwrite: bool = False,
+) -> dict:
+    """Generate a valid unified diff patch from structured file changes.
+
+    Each change object must have a "mode" field to select the change type,
+    plus mode-specific fields. The mode determines which fields are required.
+
+    Args:
+        changes: Array of change objects (discriminated by "mode" field).
+        output_path: Optional file path to write the patch to.
+        work_dir: Base directory for relativizing absolute paths in diff headers.
+        overwrite: If true, overwrite existing output file. Default false.
+
+    Returns:
+        Dict with patch, files_changed, self_valid, skipped_files, or error.
+    """
+    try:
+        result: GenerateResult = generate_patch(
+            list(changes),
+            output_path=output_path,
+            work_dir=work_dir,
+            overwrite=overwrite,
+        )
+        return {
+            "patch": result.patch,
+            "files_changed": result.files_changed,
+            "self_valid": result.self_valid,
+            "skipped_files": result.skipped_files,
+        }
+    except (DiffGenerationError, SearchReplaceError, ValueError) as e:
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def validate_patch_tool(
+    patch_content: str | None = None,
+    patch_path: str | None = None,
+    git_check: bool = False,
+    work_dir: str | None = None,
+) -> dict:
+    """Validate a unified diff patch.
+
+    Provide either patch_content (the diff string) or patch_path
+    (path to a .diff file). Parses the patch structure and reports
+    file count, hunk count, and validity.
+
+    Args:
+        patch_content: The patch text to validate.
+        patch_path: Path to a patch file to validate.
+        git_check: If true, also run git apply --check.
+        work_dir: Working directory for git apply --check.
+
+    Returns:
+        Dict with valid, files, total_hunks, and optional error details.
+    """
+    try:
+        result: ValidationResult = _validate_patch(
+            patch_content=patch_content,
+            patch_path=patch_path,
+            git_check=git_check,
+            work_dir=work_dir,
+        )
+        return {
+            "valid": result.valid,
+            "files": [
+                {
+                    "file_path": f.file_path,
+                    "hunk_count": f.hunk_count,
+                    "is_creation": f.is_creation,
+                }
+                for f in result.files
+            ],
+            "total_hunks": result.total_hunks,
+            "parse_error": result.parse_error,
+            "git_apply_ok": result.git_apply_ok,
+            "git_apply_error": result.git_apply_error,
+        }
+    except ValueError as e:
+        return {"valid": False, "error": str(e)}
+
+
+def run_server() -> None:
+    """Start the MCP server with stdio transport."""
+    mcp.run(transport="stdio")