commitguardian 0.1.0__py3-none-any.whl

commitguard/detectors/registry.py

@@ -0,0 +1,72 @@
+"""Detector registry.
+
+The registry is an explicit, in-process list. There is intentionally no
+dynamic plugin discovery (entry points, import-by-name from configuration):
+configuration must never cause arbitrary code to be imported or executed.
+"""
+
+from commitguard.detectors.base import Detector
+from commitguard.exceptions.base import UnsafeInputError
+from commitguard.exceptions.detection import DetectorRegistrationError
+from commitguard.rules.matcher import CompiledRules
+from commitguard.security.validation import validate_identifier
+
+
+class DetectorRegistry:
+    """An ordered collection of uniquely named detectors."""
+
+    def __init__(self) -> None:
+        self._detectors: dict[str, Detector] = {}
+
+    def register(self, detector: Detector) -> None:
+        if not isinstance(detector, Detector):
+            raise DetectorRegistrationError(f"{detector!r} is not a Detector")
+        try:
+            validate_identifier(detector.name, kind="detector name")
+            for rule in detector.rules:
+                validate_identifier(rule, kind="rule id")
+        except (AttributeError, UnsafeInputError) as exc:
+            raise DetectorRegistrationError(str(exc)) from exc
+        if not detector.rules:
+            raise DetectorRegistrationError(f"detector {detector.name!r} declares no rules")
+        if detector.name in self._detectors:
+            raise DetectorRegistrationError(f"detector {detector.name!r} is already registered")
+        self._detectors[detector.name] = detector
+
+    def get(self, name: str) -> Detector:
+        try:
+            return self._detectors[name]
+        except KeyError:
+            raise DetectorRegistrationError(f"no detector named {name!r}") from None
+
+    def all(self) -> tuple[Detector, ...]:
+        """All detectors, sorted by name for deterministic execution."""
+        return tuple(self._detectors[name] for name in sorted(self._detectors))
+
+    def rules(self) -> frozenset[str]:
+        """Every rule ID declared by a registered detector."""
+        return frozenset(rule for detector in self._detectors.values() for rule in detector.rules)
+
+    def __len__(self) -> int:
+        return len(self._detectors)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._detectors
+
+
+def builtin_registry(rules: CompiledRules) -> DetectorRegistry:
+    """Return a registry of CommitGuard's built-in detectors using ``rules``."""
+    from commitguard.detectors.bot import BotDetector
+    from commitguard.detectors.coauthor import CoauthorDetector
+    from commitguard.detectors.identity import IdentityDetector
+    from commitguard.detectors.trailer import TrailerDetector
+
+    registry = DetectorRegistry()
+    for detector in (
+        CoauthorDetector(rules),
+        IdentityDetector(rules),
+        TrailerDetector(rules),
+        BotDetector(rules),
+    ):
+        registry.register(detector)
+    return registry

commitguard/detectors/trailer.py

@@ -0,0 +1,211 @@
+"""Trailer detector: configured attribution trailers, malformed trailers and
+exact tool attribution footers.
+
+Nothing here is flagged merely for existing. ``Reviewed-by`` or
+``Signed-off-by`` only produce ``ai_trailer`` when a configured rule says so
+(e.g. the value is an AI identity); ``malformed_trailer`` only applies to keys
+listed in ``malformed_trailer_checks``. ``Co-authored-by`` belongs to the
+co-author detector and is not reported here as AI attribution.
+
+Message markers are exact whole-line matches of tool-inserted footers such as
+``Generated with [Claude Code](https://claude.com/claude-code)``, which tools
+usually prefix with a pictographic symbol (U+1F916 ROBOT FACE). There is no
+free-text inference: "use AI service for recommendations" is not evidence.
+"""
+
+import unicodedata
+from collections.abc import Sequence
+from typing import ClassVar
+
+from commitguard.core.context import CommitContext
+from commitguard.core.result import (
+    Confidence,
+    Evidence,
+    EvidenceSource,
+    Finding,
+    MatchKind,
+    MatchReason,
+    Severity,
+)
+from commitguard.detectors.base import Detector, require_complete_trailers
+from commitguard.provenance.normalization import normalize_text
+from commitguard.provenance.trailers import Trailer, TrailerIssue
+from commitguard.rules.matcher import CompiledRules
+from commitguard.rules.models import PATTERNS_FILE, MalformedTrailerCheck, TrailerRule
+
+RULE_AI_TRAILER = "ai_trailer"
+RULE_MALFORMED_TRAILER = "malformed_trailer"
+
+MAX_MARKER_LINE_CHARS = 300
+
+
+def _marker_key(line: str) -> str:
+    """Normalised line with any leading pictographic symbols removed.
+
+    Tool footers are commonly prefixed with one (U+1F916 ROBOT FACE before
+    ``Generated with ...``); the marker must match with or without it.
+    """
+    text = normalize_text(line)
+    index = 0
+    while index < len(text) and (
+        text[index].isspace() or unicodedata.category(text[index]) in ("So", "Sk", "Sm", "Mn")
+    ):
+        index += 1
+    return text[index:]
+
+
+class TrailerDetector(Detector):
+    name: ClassVar[str] = "trailer"
+    rules: ClassVar[frozenset[str]] = frozenset({RULE_AI_TRAILER, RULE_MALFORMED_TRAILER})
+    description: ClassVar[str] = (
+        "Configured AI attribution trailers/footers and malformed trailers."
+    )
+
+    def __init__(self, rules: CompiledRules) -> None:
+        patterns = rules.rules.patterns
+        self._rules = rules
+        self._attribution: dict[str, TrailerRule] = {
+            key: rule for rule in patterns.attribution_trailers for key in rule.keys
+        }
+        self._malformed: dict[str, MalformedTrailerCheck] = {}
+        for check in patterns.malformed_trailer_checks:
+            for key in check.keys:
+                self._malformed.setdefault(key, check)
+        self._markers: dict[str, tuple[str, str, str]] = {
+            _marker_key(line): (marker.id, marker.agent, line)
+            for marker in patterns.message_markers
+            for line in marker.lines
+        }
+
+    def detect(self, context: CommitContext) -> Sequence[Finding]:
+        commit = context.commit
+        require_complete_trailers(commit)
+        findings: list[Finding] = []
+        for trailer in commit.trailers:
+            key = trailer.normalized_key
+            if (rule := self._attribution.get(key)) is not None:
+                finding = self._attribution_finding(rule, trailer, commit.sha)
+                if finding is not None:
+                    findings.append(finding)
+            if (check := self._malformed.get(key)) is not None:
+                finding = self._malformed_finding(check, trailer, commit.sha)
+                if finding is not None:
+                    findings.append(finding)
+        findings.extend(self._marker_findings(commit.message, commit.sha))
+        return findings
+
+    # ------------------------------------------------------------------ #
+    def _attribution_finding(
+        self, rule: TrailerRule, trailer: Trailer, sha: str | None
+    ) -> Finding | None:
+        key_reason = MatchReason(
+            kind=MatchKind.TRAILER_KEY,
+            value=trailer.normalized_key,
+            rule=f"{PATTERNS_FILE}#{rule.id}",
+        )
+        reasons: tuple[MatchReason, ...]
+        if rule.match == "key_present":
+            if normalize_text(trailer.value) in rule.ignore_values:
+                return None
+            reasons, confidence, subject = (key_reason,), Confidence.HIGH, "AI assistance"
+        else:
+            match = self._rules.ai_matcher.match(trailer.name, trailer.email)
+            if match is None:
+                return None
+            reasons = (key_reason, *match.reasons)
+            confidence, subject = match.confidence, f"the AI agent {match.display_name}"
+        return Finding(
+            detector=self.name,
+            rule_id=RULE_AI_TRAILER,
+            severity=Severity.HIGH,
+            confidence=confidence,
+            title="AI attribution trailer detected",
+            message=f"The {trailer.key!r} trailer attributes the commit to {subject}.",
+            evidence=(
+                Evidence(
+                    source=EvidenceSource.TRAILER,
+                    value=trailer.raw,
+                    line_number=trailer.line_number,
+                    matched=reasons,
+                ),
+            ),
+            commit_sha=sha,
+            remediation="Remove the AI attribution trailer from the commit message before pushing.",
+        )
+
+    def _malformed_finding(
+        self, check: MalformedTrailerCheck, trailer: Trailer, sha: str | None
+    ) -> Finding | None:
+        # Characters before a key (a quoted "> Signed-off-by:" line) are recorded so that
+        # attribution cannot hide behind them, but are not by themselves malformed.
+        notes = [
+            f"trailer: {issue.value}"
+            for issue in trailer.issues
+            if issue is not TrailerIssue.LEADING_CHARACTERS
+        ]
+        if check.require_identity:
+            notes.extend(f"identity: {issue.value}" for issue in trailer.identity.issues)
+        if not notes:
+            return None
+        return Finding(
+            detector=self.name,
+            rule_id=RULE_MALFORMED_TRAILER,
+            severity=Severity.LOW,
+            confidence=Confidence.HIGH,
+            title="Malformed trailer",
+            message=(
+                f"The {trailer.key!r} trailer is malformed. Tools disagree on how to read "
+                "malformed trailers, which can hide or misstate attribution."
+            ),
+            evidence=(
+                Evidence(
+                    source=EvidenceSource.TRAILER,
+                    value=trailer.raw,
+                    line_number=trailer.line_number,
+                    notes=tuple(notes),
+                ),
+            ),
+            commit_sha=sha,
+            remediation="Rewrite the trailer as 'Key: Name <email>' or remove it.",
+        )
+
+    def _marker_findings(self, message: str, sha: str | None) -> list[Finding]:
+        findings = []
+        for line_number, line in enumerate(message.splitlines(), start=1):
+            if len(line) > MAX_MARKER_LINE_CHARS:
+                continue
+            hit = self._markers.get(_marker_key(line))
+            if hit is None:
+                continue
+            marker_id, agent_id, marker_line = hit
+            agent = self._rules.agents[agent_id]
+            findings.append(
+                Finding(
+                    detector=self.name,
+                    rule_id=RULE_AI_TRAILER,
+                    severity=Severity.HIGH,
+                    confidence=Confidence.HIGH,
+                    title="AI attribution footer detected",
+                    message=(
+                        f"The commit message contains an attribution line inserted by "
+                        f"{agent.display_name}."
+                    ),
+                    evidence=(
+                        Evidence(
+                            source=EvidenceSource.MESSAGE,
+                            value=line.strip(),
+                            line_number=line_number,
+                            matched=(
+                                MatchReason(
+                                    kind=MatchKind.MESSAGE_MARKER,
+                                    value=marker_line,
+                                    rule=f"{PATTERNS_FILE}#{marker_id}",
+                                ),
+                            ),
+                        ),
+                    ),
+                    commit_sha=sha,
+                    remediation="Remove the tool attribution line from the commit message.",
+                )
+            )
+        return findings

commitguard/exceptions/__init__.py

@@ -0,0 +1,33 @@
+"""CommitGuard exception hierarchy.
+
+Every error raised deliberately by CommitGuard derives from
+:class:`CommitGuardError`, so callers (in particular the CLI and Git hooks) can
+distinguish expected failures from programming errors and fail closed.
+"""
+
+from commitguard.exceptions.base import CommitGuardError, UnsafeInputError
+from commitguard.exceptions.configuration import ConfigurationError, RulesError
+from commitguard.exceptions.detection import DetectionError, DetectorRegistrationError
+from commitguard.exceptions.git import (
+    GitCommandError,
+    GitError,
+    GitNotFoundError,
+    HookInstallError,
+    MalformedGitOutputError,
+    NotAGitRepositoryError,
+)
+
+__all__ = [
+    "CommitGuardError",
+    "ConfigurationError",
+    "DetectionError",
+    "DetectorRegistrationError",
+    "GitCommandError",
+    "GitError",
+    "GitNotFoundError",
+    "HookInstallError",
+    "MalformedGitOutputError",
+    "NotAGitRepositoryError",
+    "RulesError",
+    "UnsafeInputError",
+]

commitguard/exceptions/base.py

@@ -0,0 +1,9 @@
+"""Root exception types shared by every CommitGuard layer."""
+
+
+class CommitGuardError(Exception):
+    """Base class for all CommitGuard errors."""
+
+
+class UnsafeInputError(CommitGuardError, ValueError):
+    """Raised when untrusted input fails a security validation check."""

commitguard/exceptions/configuration.py

@@ -0,0 +1,22 @@
+"""Configuration errors.
+
+Invalid configuration is always an error, never a warning: a typo in a policy
+file must not silently weaken enforcement.
+"""
+
+from pathlib import Path
+
+from commitguard.exceptions.base import CommitGuardError
+
+
+class ConfigurationError(CommitGuardError):
+    """Raised when a configuration file is missing, unreadable, or invalid."""
+
+    def __init__(self, message: str, *, path: Path | None = None) -> None:
+        self.path = path
+        prefix = f"{path}: " if path is not None else ""
+        super().__init__(f"{prefix}{message}")
+
+
+class RulesError(ConfigurationError):
+    """Raised when detection rule files are missing or invalid."""

commitguard/exceptions/detection.py

@@ -0,0 +1,11 @@
+"""Detection errors."""
+
+from commitguard.exceptions.base import CommitGuardError
+
+
+class DetectionError(CommitGuardError):
+    """Raised when a detector misbehaves (e.g. emits an undeclared rule)."""
+
+
+class DetectorRegistrationError(DetectionError):
+    """Raised when a detector cannot be registered (duplicate or invalid name)."""

commitguard/exceptions/git.py

@@ -0,0 +1,41 @@
+"""Git integration errors."""
+
+from collections.abc import Sequence
+
+from commitguard.exceptions.base import CommitGuardError
+
+
+class GitError(CommitGuardError):
+    """Base class for Git-related failures."""
+
+
+class GitNotFoundError(GitError):
+    """Raised when the ``git`` executable cannot be located."""
+
+
+class NotAGitRepositoryError(GitError):
+    """Raised when an operation requires a Git repository and none was found."""
+
+
+class MalformedGitOutputError(GitError):
+    """Raised when Git output does not match the expected, validated shape.
+
+    Commit metadata is untrusted; a crafted object can produce output that a
+    naive parser would mis-assign. We refuse to guess.
+    """
+
+
+class GitCommandError(GitError):
+    """Raised when a Git command exits with a non-zero status."""
+
+    def __init__(self, args: Sequence[str], returncode: int, stderr: str) -> None:
+        self.command = tuple(args)
+        self.returncode = returncode
+        self.stderr = stderr
+        # Only the git sub-command is echoed; arguments may contain user data.
+        subcommand = next((a for a in self.command[1:] if not a.startswith("-")), "?")
+        super().__init__(f"git {subcommand} failed with exit code {returncode}: {stderr}")
+
+
+class HookInstallError(GitError):
+    """Raised when hooks cannot be installed or removed safely."""

commitguard/exceptions/service.py

@@ -0,0 +1,25 @@
+"""Errors raised by long-running services (scan workers, integrations).
+
+The split matters for enforcement: a *policy violation* is a successful scan
+with a BLOCK result, while these errors mean the scan could not be completed.
+Both fail the check, but they are recorded and reported differently.
+"""
+
+from commitguard.exceptions.base import CommitGuardError
+from commitguard.exceptions.configuration import ConfigurationError
+
+
+class PolicyError(ConfigurationError):
+    """A policy (e.g. a mandatory organisation policy) is invalid or cannot be applied."""
+
+
+class ScanError(CommitGuardError):
+    """A scan could not be completed (missing commits, too many commits, stale scan...)."""
+
+
+class StaleScanError(ScanError):
+    """A newer scan owns the result; this scan must not publish anything."""
+
+
+class InfrastructureError(CommitGuardError):
+    """A dependency the service needs (Git, storage, network) failed."""

commitguard/git/__init__.py

@@ -0,0 +1,12 @@
+"""Git integration layer.
+
+* :mod:`commitguard.git.commit` - the normalised :class:`Commit` data model
+  (pure data, no I/O; safe for detectors to import).
+* :mod:`commitguard.git.commands` - the single choke point that executes Git.
+* :mod:`commitguard.git.repository` - repository discovery and read-only queries.
+* :mod:`commitguard.git.diff` - staged change inspection (planned).
+* :mod:`commitguard.git.hooks` - hook installation and removal (planned).
+
+The detection engine and detectors must never import the I/O modules; this is
+enforced by ``tests/unit/test_architecture.py``.
+"""

commitguard/git/commands.py

@@ -0,0 +1,101 @@
+"""The single choke point through which CommitGuard executes Git.
+
+Hardening applied to every invocation:
+
+* ``git`` is resolved once via ``PATH`` and invoked with an argument vector;
+* ``--no-pager`` and ``GIT_TERMINAL_PROMPT=0``: never block on a pager/prompt;
+* ``GIT_NO_REPLACE_OBJECTS=1``: ``git replace`` refs cannot substitute the
+  commit we inspect with a different, innocent-looking one;
+* ``GIT_OPTIONAL_LOCKS=0``: read-only queries do not refresh the index;
+* ``LC_ALL=C``: stable, parseable error messages.
+
+Callers that pass revisions must place them after ``--end-of-options``.
+"""
+
+import re
+import shutil
+import subprocess
+from collections.abc import Mapping, Sequence
+from functools import cache
+from pathlib import Path
+
+from commitguard.exceptions.git import GitCommandError, GitError, GitNotFoundError
+from commitguard.security.sanitization import sanitize_for_terminal
+from commitguard.utils.subprocess import DEFAULT_TIMEOUT_SECONDS, CommandResult, run_command
+
+# ``rev-parse --end-of-options`` and ``--path-format=absolute`` need Git 2.31.
+MINIMUM_GIT_VERSION = (2, 31)
+
+GIT_ENV_OVERRIDES: dict[str, str] = {
+    "GIT_TERMINAL_PROMPT": "0",
+    "GIT_NO_REPLACE_OBJECTS": "1",
+    "GIT_OPTIONAL_LOCKS": "0",
+    "LC_ALL": "C",
+}
+
+_VERSION_RE = re.compile(rb"git version (\d+)\.(\d+)(?:\.(\d+))?")
+
+
+@cache
+def git_executable() -> str:
+    """Return the absolute path of the ``git`` executable."""
+    path = shutil.which("git")
+    if path is None:
+        raise GitNotFoundError("git executable not found on PATH")
+    return path
+
+
+def run_git(
+    args: Sequence[str],
+    *,
+    cwd: Path | None = None,
+    check: bool = True,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    input_bytes: bytes | None = None,
+    extra_env: Mapping[str, str] | None = None,
+) -> CommandResult:
+    """Run ``git <args>`` with CommitGuard's hardening applied.
+
+    With ``check=True`` a non-zero exit raises :class:`GitCommandError` whose
+    message contains sanitised stderr only. ``extra_env`` may add variables but
+    never replace the hardening in :data:`GIT_ENV_OVERRIDES`.
+    """
+    argv = [git_executable(), "--no-pager", *args]
+    env = dict(GIT_ENV_OVERRIDES)
+    if extra_env:
+        clash = sorted(set(extra_env) & set(GIT_ENV_OVERRIDES))
+        if clash:
+            raise ValueError(f"extra_env must not override git hardening: {', '.join(clash)}")
+        env.update(extra_env)
+    try:
+        result = run_command(
+            argv,
+            cwd=cwd,
+            env_overrides=env,
+            timeout=timeout,
+            input_bytes=input_bytes,
+        )
+    except FileNotFoundError as exc:
+        raise GitNotFoundError("git executable could not be started") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise GitError(f"git command timed out after {timeout:g}s") from exc
+
+    if check and not result.ok:
+        stderr = sanitize_for_terminal(result.stderr.decode("utf-8", errors="replace").strip())
+        raise GitCommandError(argv, result.returncode, stderr)
+    return result
+
+
+def git_version() -> tuple[int, int, int]:
+    """Return the installed Git version as ``(major, minor, patch)``."""
+    result = run_git(["--version"])
+    match = _VERSION_RE.search(result.stdout)
+    if match is None:
+        raise GitError("could not determine git version")
+    major, minor, patch = match.groups()
+    return int(major), int(minor), int(patch or 0)
+
+
+def git_version_supported() -> bool:
+    """Return True if the installed Git meets :data:`MINIMUM_GIT_VERSION`."""
+    return git_version()[:2] >= MINIMUM_GIT_VERSION

commitguard/git/commit.py

@@ -0,0 +1,97 @@
+"""Normalised commit model.
+
+This module is pure data: it has no Git or filesystem access, so detectors can
+depend on it without depending on Git itself.
+
+A :class:`Commit` may describe a commit that does not exist yet. During a
+``commit-msg`` check there is a message and an identity but no object ID, so
+``sha`` and ``parents`` are optional.
+
+Trailers are always *derived* from ``message`` by
+:func:`~commitguard.provenance.trailers.parse_trailers`; they cannot be passed
+in separately, so they can never disagree with the message they came from.
+"""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from commitguard.provenance.author import Identity
+from commitguard.provenance.signatures import SignatureInfo
+from commitguard.provenance.trailers import Trailer, parse_trailers
+from commitguard.security.validation import validate_git_sha
+
+SHORT_SHA_LENGTH = 7
+
+
+class Commit(BaseModel):
+    """A normalised, immutable view of a Git commit.
+
+    All string fields hold *untrusted* data exactly as recorded in the commit.
+    Sanitise before displaying (see :mod:`commitguard.security.sanitization`).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    sha: str | None = Field(default=None, description="Object ID; None for a pending commit")
+    parents: tuple[str, ...] = ()
+    author: Identity
+    committer: Identity
+    authored_at: datetime | None = None
+    committed_at: datetime | None = None
+    message: str
+    trailers: tuple[Trailer, ...] = Field(default=(), description="Derived from message")
+    trailers_truncated: bool = Field(
+        default=False, description="True if the message had more trailers than can be analysed"
+    )
+    signature: SignatureInfo | None = Field(
+        default=None,
+        description="Not collected yet (security intelligence phase); None means unknown",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _derive_trailers(cls, data: Any) -> Any:
+        if isinstance(data, dict) and isinstance(data.get("message"), str):
+            parsed = parse_trailers(data["message"])
+            data = {**data, "trailers": parsed.trailers, "trailers_truncated": parsed.truncated}
+        return data
+
+    @field_validator("sha")
+    @classmethod
+    def _validate_sha(cls, value: str | None) -> str | None:
+        return None if value is None else validate_git_sha(value)
+
+    @field_validator("parents")
+    @classmethod
+    def _validate_parents(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        for parent in value:
+            validate_git_sha(parent)
+        return value
+
+    @property
+    def is_pending(self) -> bool:
+        """True if this commit has not been written to the object database."""
+        return self.sha is None
+
+    @property
+    def is_merge(self) -> bool:
+        return len(self.parents) > 1
+
+    @property
+    def short_sha(self) -> str:
+        return self.sha[:SHORT_SHA_LENGTH] if self.sha else "pending"
+
+    @property
+    def timestamp(self) -> datetime | None:
+        """Commit time (committer date), falling back to the author date."""
+        return self.committed_at or self.authored_at
+
+    @property
+    def subject(self) -> str:
+        """First line of the message (untrusted; sanitise before display)."""
+        return self.message.split("\n", 1)[0]
+
+    def trailers_with_key(self, normalized_key: str) -> tuple[Trailer, ...]:
+        return tuple(t for t in self.trailers if t.normalized_key == normalized_key)

commitguard/git/diff.py

@@ -0,0 +1,36 @@
+"""Staged and committed change inspection.
+
+TODO(phase-3): implement read-only diff inspection for the ``pre-commit`` and
+``pre-push`` hooks, e.g. ``git diff --cached --name-status -z`` for staged
+paths and ``git diff-tree`` for pushed commits. Requirements:
+
+* NUL-delimited output only (paths may contain newlines or escape codes);
+* binary-safe, size-bounded reads of blob content (for future secret detection);
+* no content ever leaves the machine unless a policy explicitly opts in.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ChangeType(StrEnum):
+    """Git name-status change codes."""
+
+    ADDED = "A"
+    COPIED = "C"
+    DELETED = "D"
+    MODIFIED = "M"
+    RENAMED = "R"
+    TYPE_CHANGED = "T"
+    UNMERGED = "U"
+
+
+class FileChange(BaseModel):
+    """A single changed path. Not populated yet (Phase 3)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    path: str
+    change: ChangeType
+    old_path: str | None = None