dataforge-07 0.1.0__py3-none-any.whl

dataforge/transactions/revert.py

@@ -0,0 +1,102 @@
+"""Revert an applied DataForge transaction."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from dataforge.transactions.files import (
+    SourceLockError,
+    atomic_write_bytes,
+    source_path_lock,
+)
+from dataforge.transactions.log import (
+    TransactionAuditVerdict,
+    append_reverted_event,
+    find_transaction_log,
+    load_transaction,
+    sha256_file,
+    verify_transaction_log,
+)
+from dataforge.transactions.txn import RepairTransaction
+
+
+class TransactionRevertError(Exception):
+    """Raised when a transaction cannot be safely reverted."""
+
+
+def revert_transaction(txn_id: str, *, search_root: Path | None = None) -> RepairTransaction:
+    """Revert a previously applied transaction by restoring its source snapshot.
+
+    Args:
+        txn_id: Canonical transaction identifier.
+        search_root: Optional root directory used to locate the transaction log.
+
+    Returns:
+        The replayed transaction state after appending the revert event.
+
+    Raises:
+        TransactionRevertError: If the transaction is not revertible or hash checks fail.
+    """
+    log_path = find_transaction_log(txn_id, search_root=search_root)
+    audit_report = verify_transaction_log(txn_id, log_path=log_path)
+    if audit_report.verdict not in {
+        TransactionAuditVerdict.VERIFIED,
+        TransactionAuditVerdict.LEGACY_UNVERIFIED,
+    }:
+        details = "; ".join(audit_report.errors) or audit_report.verdict.value
+        raise TransactionRevertError(
+            f"Refusing to revert because transaction audit verification failed: {details}"
+        )
+    transaction = load_transaction(log_path)
+
+    if not transaction.applied or transaction.post_sha256 is None:
+        raise TransactionRevertError(
+            f"Transaction '{txn_id}' was recorded but never applied, so there is nothing to revert."
+        )
+    if transaction.reverted_at is not None:
+        raise TransactionRevertError(f"Transaction '{txn_id}' has already been reverted.")
+
+    if transaction.source_kind == "table_store":
+        try:
+            from dataforge.stores.revert import revert_table_store_transaction
+
+            return revert_table_store_transaction(log_path)
+        except Exception as exc:
+            raise TransactionRevertError(str(exc)) from exc
+
+    source_path = Path(transaction.source_path)
+    snapshot_path = Path(transaction.source_snapshot_path)
+
+    if not source_path.exists():
+        raise TransactionRevertError(f"Source file not found: '{source_path}'.")
+    if not snapshot_path.exists():
+        raise TransactionRevertError(
+            f"Source snapshot not found for transaction '{txn_id}': '{snapshot_path}'."
+        )
+
+    try:
+        with source_path_lock(source_path):
+            current_bytes = source_path.read_bytes()
+            current_sha256 = sha256_file(source_path)
+            if current_sha256 != transaction.post_sha256:
+                raise TransactionRevertError(
+                    "Refusing to revert because the current file no longer matches the recorded "
+                    "post-state hash. The file may have been edited after apply."
+                )
+
+            atomic_write_bytes(source_path, snapshot_path.read_bytes())
+            reverted_sha256 = sha256_file(source_path)
+            if reverted_sha256 != transaction.source_sha256:
+                atomic_write_bytes(source_path, current_bytes)
+                raise TransactionRevertError(
+                    f"Revert failed integrity verification for transaction '{txn_id}'."
+                )
+
+            try:
+                append_reverted_event(log_path, txn_id)
+            except Exception:
+                atomic_write_bytes(source_path, current_bytes)
+                raise
+    except SourceLockError as exc:
+        raise TransactionRevertError(str(exc)) from exc
+    return load_transaction(log_path)

dataforge/transactions/txn.py

@@ -0,0 +1,104 @@
+"""Transaction models for reversible DataForge repairs."""
+
+from __future__ import annotations
+
+import secrets
+from datetime import UTC, datetime
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+TxnId = Annotated[str, Field(pattern=r"^txn-\d{4}-\d{2}-\d{2}-[0-9a-f]{6}$")]
+Sha256Hex = Annotated[str, Field(pattern=r"^[0-9a-f]{64}$")]
+
+
+def _require_utc(value: datetime, field_name: str) -> datetime:
+    """Validate that a datetime is timezone-aware UTC."""
+    if value.tzinfo is None or value.utcoffset() is None:
+        raise ValueError(f"{field_name} must be timezone-aware UTC")
+    if value.utcoffset() != UTC.utcoffset(value):
+        raise ValueError(f"{field_name} must be UTC")
+    return value
+
+
+def generate_txn_id(now: datetime | None = None) -> str:
+    """Generate a transaction identifier in the canonical Week 2 format.
+
+    Args:
+        now: Optional timestamp override. If omitted, current UTC time is used.
+
+    Returns:
+        A transaction identifier like ``txn-2026-04-20-a1b2c3``.
+    """
+    current = now or datetime.now(UTC)
+    current_utc = current.astimezone(UTC)
+    return f"txn-{current_utc:%Y-%m-%d}-{secrets.token_hex(3)}"
+
+
+class CellFix(BaseModel):
+    """A single cell mutation proposed or applied by DataForge.
+
+    Args:
+        row: Zero-indexed row number in the CSV body.
+        column: Column name to update.
+        old_value: The value observed before repair.
+        new_value: The value to write during repair.
+        detector_id: The detector / repairer family that produced the fix.
+    """
+
+    row: int = Field(ge=0, description="Zero-indexed row number")
+    column: str = Field(min_length=1, description="Column name")
+    old_value: str = Field(description="Original value before repair")
+    new_value: str = Field(description="Replacement value after repair")
+    detector_id: str = Field(min_length=1, description="Detector / repairer identifier")
+    operation: Literal["update", "delete_row"] = Field(
+        default="update",
+        description="Repair operation kind",
+    )
+
+    model_config = {"frozen": True}
+
+
+class RepairTransaction(BaseModel):
+    """Audit record for a reversible repair transaction.
+
+    Args:
+        txn_id: Canonical transaction identifier.
+        created_at: UTC timestamp when the transaction was recorded.
+        source_path: Absolute path to the repaired source file.
+        source_sha256: SHA-256 of the original source bytes.
+        post_sha256: SHA-256 of the applied file bytes, once written.
+        source_snapshot_path: Absolute path to the immutable source snapshot.
+        fixes: Ordered list of cell fixes recorded for auditability.
+        applied: Whether the journal records that the repair was applied.
+        reverted_at: UTC timestamp when the transaction was reverted, if any.
+    """
+
+    txn_id: TxnId
+    created_at: datetime
+    source_path: str = Field(min_length=1)
+    source_sha256: Sha256Hex
+    post_sha256: Sha256Hex | None = None
+    source_snapshot_path: str = Field(min_length=1)
+    fixes: list[CellFix] = Field(default_factory=list)
+    applied: bool
+    reverted_at: datetime | None = None
+    source_kind: Literal["file", "table_store"] = "file"
+    backend: str | None = None
+    patch_plan: dict[str, Any] | None = None
+
+    @field_validator("created_at")
+    @classmethod
+    def _validate_created_at(cls, value: datetime) -> datetime:
+        """Require ``created_at`` to be UTC."""
+        return _require_utc(value, "created_at")
+
+    @field_validator("reverted_at")
+    @classmethod
+    def _validate_reverted_at(cls, value: datetime | None) -> datetime | None:
+        """Require ``reverted_at`` to be UTC when present."""
+        if value is None:
+            return None
+        return _require_utc(value, "reverted_at")
+
+    model_config = {"frozen": True}

dataforge/ui/__init__.py

@@ -0,0 +1 @@
+"""Terminal UI package scaffolding for DataForge."""

dataforge/ui/profile_view.py

@@ -0,0 +1,136 @@
+"""Rich-based terminal rendering for the ``dataforge profile`` command.
+
+This module contains **rendering only** — no business logic, no data loading,
+no detector invocation.  It receives a list of :class:`Issue` objects and
+renders them as a Rich table with color-coded severity.
+"""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from dataforge.detectors.base import Issue, Severity
+
+# Severity-to-color mapping for the Rich table.
+_SEVERITY_STYLE = {
+    Severity.SAFE: "green",
+    Severity.REVIEW: "yellow",
+    Severity.UNSAFE: "bold red",
+}
+
+# Severity sort key: UNSAFE first, then REVIEW, then SAFE.
+_SEVERITY_ORDER = {Severity.UNSAFE: 0, Severity.REVIEW: 1, Severity.SAFE: 2}
+
+
+def render_profile_table(
+    issues: list[Issue],
+    console: Console | None = None,
+    *,
+    file_path: str = "",
+) -> None:
+    """Render detected issues as a rich-formatted terminal table.
+
+    The table is sorted by severity (UNSAFE first) then confidence
+    (highest first).  Each severity level is color-coded.
+
+    Args:
+        issues: List of Issue objects to display.
+        console: Optional Rich Console instance (for testing / capture).
+            If None, a new Console is created.
+        file_path: Optional file path to display in the header panel.
+
+    Example:
+        >>> from dataforge.detectors.base import Issue, Severity
+        >>> issues = [
+        ...     Issue(row=3, column="price", issue_type="decimal_shift",
+        ...           severity=Severity.REVIEW, confidence=0.92,
+        ...           actual="1020.0", expected="102.0",
+        ...           reason="Value appears 10x too large"),
+        ... ]
+        >>> render_profile_table(issues)  # doctest: +SKIP
+    """
+    if console is None:
+        console = Console()
+
+    # Header panel.
+    header_text = "DataForge Profile Report"
+    if file_path:
+        header_text += f"  |  {file_path}"
+    console.print(
+        Panel(
+            header_text,
+            style="bold cyan",
+            expand=True,
+        )
+    )
+
+    if not issues:
+        console.print(
+            Panel(
+                "[green]No issues detected.[/green]",
+                title="Result",
+                style="green",
+            )
+        )
+        return
+
+    # Sort: UNSAFE first, then REVIEW, then SAFE; highest confidence first.
+    sorted_issues = sorted(
+        issues,
+        key=lambda i: (_SEVERITY_ORDER[i.severity], -i.confidence),
+    )
+
+    # Build the table.
+    table = Table(
+        title="Detected Issues",
+        show_lines=True,
+        header_style="bold magenta",
+        title_style="bold white",
+    )
+    table.add_column("Row", style="dim", justify="right", width=5)
+    table.add_column("Column", style="cyan", min_width=12)
+    table.add_column("Issue Type", style="white", min_width=14)
+    table.add_column("Severity", justify="center", min_width=8)
+    table.add_column("Confidence", justify="right", min_width=10)
+    table.add_column("Reason", min_width=30)
+
+    for issue in sorted_issues:
+        severity_style = _SEVERITY_STYLE[issue.severity]
+        severity_text = Text(issue.severity.value.upper(), style=severity_style)
+
+        confidence_pct = f"{issue.confidence:.0%}"
+
+        table.add_row(
+            str(issue.row),
+            issue.column,
+            issue.issue_type,
+            severity_text,
+            confidence_pct,
+            issue.reason,
+        )
+
+    console.print(table)
+
+    # Summary panel.
+    total = len(sorted_issues)
+    by_severity: dict[Severity, int] = {}
+    for issue in sorted_issues:
+        by_severity[issue.severity] = by_severity.get(issue.severity, 0) + 1
+
+    summary_parts: list[str] = [f"[bold]{total}[/bold] issues found"]
+    for sev in (Severity.UNSAFE, Severity.REVIEW, Severity.SAFE):
+        count = by_severity.get(sev, 0)
+        if count > 0:
+            style = _SEVERITY_STYLE[sev]
+            summary_parts.append(f"[{style}]{sev.value.upper()}: {count}[/{style}]")
+
+    console.print(
+        Panel(
+            "  |  ".join(summary_parts),
+            title="Summary",
+            style="dim",
+        )
+    )

dataforge/ui/repair_diff.py

@@ -0,0 +1,91 @@
+"""Rich rendering for repair proposals and transaction output."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, cast
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+
+@dataclass(frozen=True)
+class _RepairDiffRow:
+    row: int
+    column: str
+    old_value: str
+    new_value: str
+    detector_id: str
+    confidence: float
+    provenance: str
+
+
+def _row_from_fix(fix: object) -> _RepairDiffRow:
+    """Normalize internal ProposedFix and public VerifiedFix objects."""
+    nested = getattr(fix, "fix", None)
+    if nested is None:
+        public = cast(Any, fix)
+        return _RepairDiffRow(
+            row=public.row,
+            column=public.column,
+            old_value=public.old_value,
+            new_value=public.new_value,
+            detector_id=public.detector_id,
+            confidence=public.confidence,
+            provenance=public.provenance,
+        )
+    proposed = cast(Any, fix)
+    return _RepairDiffRow(
+        row=nested.row,
+        column=nested.column,
+        old_value=nested.old_value,
+        new_value=nested.new_value,
+        detector_id=nested.detector_id,
+        confidence=proposed.confidence,
+        provenance=proposed.provenance,
+    )
+
+
+def render_repair_diff(
+    fixes: Sequence[object],
+    console: Console | None = None,
+    *,
+    file_path: str = "",
+) -> None:
+    """Render a rich table describing proposed repairs."""
+    target_console = console or Console()
+    title = "Proposed Repairs"
+    if file_path:
+        title = f"{title}  |  {file_path}"
+    target_console.print(Panel(title, style="bold cyan", expand=True))
+
+    if not fixes:
+        target_console.print(
+            Panel("[yellow]No fixes proposed.[/yellow]", title="Result", style="yellow")
+        )
+        return
+
+    table = Table(title="Repair Diff", show_lines=True, header_style="bold magenta")
+    table.add_column("Row", justify="right", width=5)
+    table.add_column("Column", style="cyan", min_width=12)
+    table.add_column("Old", min_width=12)
+    table.add_column("New", min_width=12)
+    table.add_column("Detector", min_width=14)
+    table.add_column("Confidence", justify="right", min_width=10)
+    table.add_column("Provenance", min_width=13)
+
+    for fix in fixes:
+        row = _row_from_fix(fix)
+        table.add_row(
+            str(row.row),
+            row.column,
+            row.old_value,
+            row.new_value,
+            row.detector_id,
+            f"{row.confidence:.0%}",
+            row.provenance,
+        )
+
+    target_console.print(table)

dataforge/verifier/__init__.py

@@ -0,0 +1,55 @@
+"""Verifier exports for DataForge."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "AggregateDependency",
+    "AcceptedValues",
+    "ConstraintIR",
+    "DomainBound",
+    "FunctionalDependency",
+    "RegexConstraint",
+    "RelationshipConstraint",
+    "SMTVerifier",
+    "Schema",
+    "SchemaToSMT",
+    "VerificationResult",
+    "VerificationVerdict",
+    "constraint_ir_from_schema",
+    "explain_unsat_core",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily expose verifier symbols without import-time cycles."""
+    if name in {
+        "AcceptedValues",
+        "AggregateDependency",
+        "DomainBound",
+        "FunctionalDependency",
+        "RegexConstraint",
+        "RelationshipConstraint",
+        "Schema",
+    }:
+        from dataforge.verifier import schema as schema_module
+
+        return getattr(schema_module, name)
+    if name in {"ConstraintIR", "constraint_ir_from_schema"}:
+        from dataforge.verifier import constraint_ir as constraint_ir_module
+
+        return getattr(constraint_ir_module, name)
+    if name in {"SchemaToSMT", "VerificationResult", "VerificationVerdict"}:
+        from dataforge.verifier import smt as smt_module
+
+        return getattr(smt_module, name)
+    if name == "SMTVerifier":
+        from dataforge.verifier import gate as gate_module
+
+        return gate_module.SMTVerifier
+    if name == "explain_unsat_core":
+        from dataforge.verifier import explain as explain_module
+
+        return explain_module.explain_unsat_core
+    raise AttributeError(name)

dataforge/verifier/constraint_ir.py

@@ -0,0 +1,155 @@
+"""ConstraintIR models bridging schemas, dbt tests, SMT, and SQL proof queries."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from dataforge.verifier.schema import Schema
+
+ConstraintIRKind = Literal[
+    "column_type",
+    "not_null",
+    "domain_bound",
+    "regex",
+    "unique",
+    "accepted_values",
+    "functional_dependency",
+    "referential",
+    "dbt_generic_test",
+]
+
+
+class ConstraintIR(BaseModel):
+    """Backend-neutral constraint representation used by patch plans."""
+
+    constraint_id: str = Field(min_length=1)
+    kind: ConstraintIRKind
+    columns: tuple[str, ...] = Field(default_factory=tuple)
+    expression: str | None = None
+    verifier: Literal["smt", "sql", "dbt"] = "smt"
+    repair_supported: bool = False
+
+    model_config = ConfigDict(strict=True, extra="forbid", frozen=True)
+
+
+def constraint_ir_from_schema(schema: Schema | None) -> tuple[ConstraintIR, ...]:
+    """Map DataForge's current schema model into the v1 ConstraintIR."""
+    if schema is None:
+        return ()
+    constraints: list[ConstraintIR] = []
+    for column, column_type in sorted(schema.columns.items()):
+        constraints.append(
+            ConstraintIR(
+                constraint_id=f"column_type::{column}",
+                kind="column_type",
+                columns=(column,),
+                expression=column_type,
+                verifier="smt",
+                repair_supported=True,
+            )
+        )
+    for bound in schema.domain_bounds:
+        parts: list[str] = []
+        if bound.min_value is not None:
+            operator = ">=" if bound.inclusive_min else ">"
+            parts.append(f"{bound.column} {operator} {bound.min_value}")
+        if bound.max_value is not None:
+            operator = "<=" if bound.inclusive_max else "<"
+            parts.append(f"{bound.column} {operator} {bound.max_value}")
+        constraints.append(
+            ConstraintIR(
+                constraint_id=f"domain_bound::{bound.column}",
+                kind="domain_bound",
+                columns=(bound.column,),
+                expression=" AND ".join(parts) if parts else None,
+                verifier="smt",
+                repair_supported=True,
+            )
+        )
+    for column in sorted(schema.not_null_columns):
+        constraints.append(
+            ConstraintIR(
+                constraint_id=f"not_null::{column}",
+                kind="not_null",
+                columns=(column,),
+                expression=f"{column} IS NOT NULL",
+                verifier="smt",
+                repair_supported=True,
+            )
+        )
+    for column in sorted(schema.unique_columns):
+        constraints.append(
+            ConstraintIR(
+                constraint_id=f"unique::{column}",
+                kind="unique",
+                columns=(column,),
+                expression=f"{column} must be unique",
+                verifier="smt",
+                repair_supported=True,
+            )
+        )
+    for column in sorted(schema.primary_key_columns):
+        constraints.append(
+            ConstraintIR(
+                constraint_id=f"primary_key::{column}",
+                kind="unique",
+                columns=(column,),
+                expression=f"{column} must be not null and unique",
+                verifier="smt",
+                repair_supported=False,
+            )
+        )
+    for accepted_rule in schema.accepted_values:
+        constraints.append(
+            ConstraintIR(
+                constraint_id=f"accepted_values::{accepted_rule.column}",
+                kind="accepted_values",
+                columns=(accepted_rule.column,),
+                expression=", ".join(accepted_rule.values),
+                verifier="smt",
+                repair_supported=True,
+            )
+        )
+    for regex_rule in schema.regex_constraints:
+        constraints.append(
+            ConstraintIR(
+                constraint_id=f"regex::{regex_rule.column}",
+                kind="regex",
+                columns=(regex_rule.column,),
+                expression=regex_rule.pattern,
+                verifier="smt",
+                repair_supported=True,
+            )
+        )
+    for relationship_rule in schema.relationships:
+        constraints.append(
+            ConstraintIR(
+                constraint_id=(
+                    f"relationship::{relationship_rule.column}->"
+                    f"{relationship_rule.reference}.{relationship_rule.reference_column}"
+                ),
+                kind="referential",
+                columns=(relationship_rule.column,),
+                expression=(
+                    f"{relationship_rule.column} references "
+                    f"{relationship_rule.reference}({relationship_rule.reference_column})"
+                ),
+                verifier="sql",
+                repair_supported=False,
+            )
+        )
+    for fd in schema.functional_dependencies:
+        determinant = "+".join(fd.determinant)
+        constraints.append(
+            ConstraintIR(
+                constraint_id=f"fd::{determinant}->{fd.dependent}",
+                kind="functional_dependency",
+                columns=(*fd.determinant, fd.dependent),
+                expression=f"{determinant} -> {fd.dependent}",
+                verifier="smt",
+                repair_supported=True,
+            )
+        )
+    return tuple(constraints)

dataforge/verifier/explain.py

@@ -0,0 +1,47 @@
+"""Unsat-core explanation helpers for the Week 3 verifier."""
+
+from __future__ import annotations
+
+from dataforge.verifier.schema import Schema
+
+
+def explain_unsat_core(unsat_core: tuple[str, ...], schema: Schema) -> str:
+    """Convert tracked unsat-core labels into user-facing text."""
+    if not unsat_core:
+        return "The verifier rejected the fix, but did not expose a tracked explanation."
+
+    parts: list[str] = []
+    for label in unsat_core:
+        tokens = label.split("::")
+        if len(tokens) >= 5 and tokens[0] == "domain":
+            _, column, bound_kind, _, row = tokens[:5]
+            adjective = "minimum" if bound_kind == "min" else "maximum"
+            parts.append(f"Row {row} would violate the {adjective} bound for column '{column}'.")
+            continue
+        if len(tokens) >= 5 and tokens[0] == "fd":
+            _, determinant, dependent, _, row = tokens[:5]
+            determinant_text = determinant.replace("+", ", ")
+            parts.append(
+                f"Row {row} would violate FD (functional dependency) "
+                f"{determinant_text} -> {dependent}."
+            )
+            continue
+        if len(tokens) >= 4 and tokens[0] in {"not_null", "primary_key_not_null"}:
+            _, column, _, row = tokens[:4]
+            parts.append(f"Row {row} would violate the not-null constraint for '{column}'.")
+            continue
+        if len(tokens) >= 4 and tokens[0] in {"unique", "primary_key_unique"}:
+            _, column, _, row = tokens[:4]
+            parts.append(f"Row {row} would violate the unique constraint for '{column}'.")
+            continue
+        if len(tokens) >= 4 and tokens[0] == "accepted_values":
+            _, column, _, row = tokens[:4]
+            parts.append(f"Row {row} would violate the accepted values constraint for '{column}'.")
+            continue
+        if len(tokens) >= 4 and tokens[0] == "regex":
+            _, column, _, row = tokens[:4]
+            parts.append(f"Row {row} would violate the regex constraint for '{column}'.")
+            continue
+        parts.append(f"Tracked verifier rule '{label}' rejected the fix.")
+
+    return " ".join(parts)