Operations

operations

Pydantic models for batch file operations.

Defines the three operation types from the axm-edit spec: - ReplaceOp — modify lines in an existing file - CreateOp — create a new file - DeleteOp — delete an existing file

Operation = Annotated[ReplaceOp | CreateOp | DeleteOp, Field(discriminator='op')] module-attribute

Discriminated union of all operation types.

BatchResult

Bases: BaseModel

Result of a batch edit operation.

Attributes:

Name	Type	Description
success	bool	Whether all operations were applied.
checkpoint	str | None	Git stash SHA for rollback, if available.
applied	int	Total number of individual edits applied.
summary	dict[str, int]	Counts of modified, created, and deleted files.
error	str | None	Human-readable error message on failure.
details	list[ValidationError]	Detailed validation errors on failure.

Source code in packages/axm-edit/src/axm_edit/models/operations.py

class BatchResult(BaseModel):  # type: ignore[explicit-any]  # pydantic synthesizes __init__(**data: Any)
    """Result of a batch edit operation.

    Attributes:
        success: Whether all operations were applied.
        checkpoint: Git stash SHA for rollback, if available.
        applied: Total number of individual edits applied.
        summary: Counts of modified, created, and deleted files.
        error: Human-readable error message on failure.
        details: Detailed validation errors on failure.
    """

    success: bool
    checkpoint: str | None = None
    applied: int = 0
    summary: dict[str, int] = Field(
        default_factory=lambda: {"modified": 0, "created": 0, "deleted": 0},
    )
    error: str | None = None
    details: list[ValidationError] = Field(default_factory=list)
    lint_errors: list[str] = Field(default_factory=list)

    model_config = {"extra": "forbid"}

CreateOp

Bases: BaseModel

Create a new file.

Fails if the file already exists unless overwrite is True.

Source code in packages/axm-edit/src/axm_edit/models/operations.py

class CreateOp(BaseModel):  # type: ignore[explicit-any]  # pydantic synthesizes __init__(**data: Any)
    """Create a new file.

    Fails if the file already exists unless ``overwrite`` is True.
    """

    op: Literal["create"] = "create"
    file: str = Field(..., min_length=1, description="Relative path to the file")
    content: str = Field(..., description="Full file content")
    overwrite: bool = Field(default=False, description="Allow overwriting")

    model_config = {"extra": "forbid"}

DeleteOp

Bases: BaseModel

Delete an existing file.

Fails if the file does not exist.

Source code in packages/axm-edit/src/axm_edit/models/operations.py

class DeleteOp(BaseModel):  # type: ignore[explicit-any]  # pydantic synthesizes __init__(**data: Any)
    """Delete an existing file.

    Fails if the file does not exist.
    """

    op: Literal["delete"] = "delete"
    file: str = Field(..., min_length=1, description="Relative path to the file")

    model_config = {"extra": "forbid"}

Edit

Bases: BaseModel

A single line-level edit within a replace operation.

Attributes:

Name	Type	Description
line	int | None	Optional 1-indexed line hint in the original file. If provided, used as a starting point for searching old. If omitted, old is searched in the entire file.
old	str	Expected content to find and replace (validation anchor). May contain \n for multi-line matches.
new	str	Replacement content.

Source code in packages/axm-edit/src/axm_edit/models/operations.py

class Edit(BaseModel):  # type: ignore[explicit-any]  # pydantic synthesizes __init__(**data: Any)
    """A single line-level edit within a replace operation.

    Attributes:
        line: Optional 1-indexed line hint in the **original** file.
              If provided, used as a starting point for searching ``old``.
              If omitted, ``old`` is searched in the entire file.
        old: Expected content to find and replace (validation anchor).
             May contain ``\\n`` for multi-line matches.
        new: Replacement content.
    """

    line: int | None = Field(
        default=None,
        ge=1,
        description="1-indexed line hint (optional — auto-search if omitted)",
    )
    old: str = Field(..., min_length=1, description="Expected content to find")
    new: str = Field(..., description="Replacement content")

    model_config = {"extra": "forbid"}

ReplaceOp

Bases: BaseModel

Modify lines in an existing file.

All line numbers reference the file as originally read, before any edits are applied. The engine sorts edits bottom-to-top to avoid line-shift problems.

Source code in packages/axm-edit/src/axm_edit/models/operations.py

class ReplaceOp(BaseModel):  # type: ignore[explicit-any]  # pydantic synthesizes __init__(**data: Any)
    """Modify lines in an existing file.

    All line numbers reference the file **as originally read**, before any
    edits are applied.  The engine sorts edits bottom-to-top to avoid
    line-shift problems.
    """

    op: Literal["replace"] = "replace"
    file: str = Field(..., min_length=1, description="Relative path to the file")
    edits: list[Edit] = Field(..., min_length=1, description="List of line edits")

    model_config = {"extra": "forbid"}

ValidationError

Bases: BaseModel

A single validation failure.

Source code in packages/axm-edit/src/axm_edit/models/operations.py

class ValidationError(BaseModel):  # type: ignore[explicit-any]  # pydantic synthesizes __init__(**data: Any)
    """A single validation failure."""

    file: str
    line: int | None = None
    expected: str | None = None
    actual: str | None = None
    error: str | None = None

    model_config = {"extra": "forbid"}