sheridan-diffract 1.0.1__py3-none-any.whl

sheridan/diffract/__init__.py

@@ -0,0 +1,32 @@
+"""sheridan-diffract: Detect public API changes between git refs and classify commits."""
+
+from __future__ import annotations
+
+__all__ = [
+    "ApiDiff",
+    "ChangeKind",
+    "CommitType",
+    "DiffractConfig",
+    "DiffractError",
+    "DiffractResult",
+    "GitError",
+    "NameChange",
+    "SurfaceError",
+    "__version__",
+    "check",
+    "check_staged",
+    "load_config",
+]
+
+import importlib.metadata
+
+from sheridan.diffract.checker import check, check_staged
+from sheridan.diffract.config import DiffractConfig, load_config
+from sheridan.diffract.enums import ChangeKind, CommitType
+from sheridan.diffract.exceptions import DiffractError, GitError, SurfaceError
+from sheridan.diffract.models import ApiDiff, DiffractResult, NameChange
+
+try:
+    __version__: str = importlib.metadata.version("sheridan-diffract")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

sheridan/diffract/checker.py

@@ -0,0 +1,106 @@
+"""High-level API entry point for sheridan-diffract."""
+
+from __future__ import annotations
+
+__all__ = ["check", "check_staged"]
+
+from pathlib import Path
+
+from sheridan.diffract.classifier import classify
+from sheridan.diffract.differ import diff_surfaces
+from sheridan.diffract.git_utils import (
+    get_api_at_index,
+    get_api_at_ref,
+    get_repo,
+    has_python_changes,
+    has_python_changes_index,
+)
+from sheridan.diffract.models import DiffractResult
+
+
+def check(
+    base_ref: str = "HEAD~1",
+    head_ref: str = "HEAD",
+    repo_path: Path | None = None,
+    src_path: str = "src",
+) -> DiffractResult:
+    """Detect API changes between two git refs and classify the commit type.
+
+    Args:
+        base_ref: The earlier git ref (default: ``HEAD~1``).
+        head_ref: The later git ref (default: ``HEAD``).
+        repo_path: Path to (or inside) the git repository. Defaults to the
+            current working directory.
+        src_path: Subdirectory within the repo to scan for Python packages.
+
+    Returns:
+        A :class:`~sheridan.diffract.models.DiffractResult` describing the
+        commit type, a human-readable summary, and the full API diff.
+
+    Raises:
+        GitError: If the repository cannot be found or either ref is invalid.
+        SurfaceError: If API surface extraction fails for either ref.
+    """
+    resolved_path = repo_path if repo_path is not None else Path.cwd()
+    repo = get_repo(resolved_path)
+
+    base_surface = get_api_at_ref(repo, base_ref, src_path=src_path)
+    head_surface = get_api_at_ref(repo, head_ref, src_path=src_path)
+
+    diff = diff_surfaces(base_surface, head_surface)
+    py_changed = has_python_changes(repo, base_ref, head_ref)
+    commit_type, summary = classify(diff, py_changed)
+
+    return DiffractResult(
+        commit_type=commit_type,
+        summary=summary,
+        diff=diff,
+        base_ref=base_ref,
+        head_ref=head_ref,
+    )
+
+
+def check_staged(
+    repo_path: Path | None = None,
+    src_path: str = "src",
+) -> DiffractResult:
+    """Detect API changes between HEAD and the git staging area and classify the commit type.
+
+    Intended for use in commit-msg hooks, where the working tree is not yet
+    committed. Compares the public API at ``HEAD`` against the public API
+    materialised from the current index (staged files).
+
+    Args:
+        repo_path: Path to (or inside) the git repository. Defaults to the
+            current working directory.
+        src_path: Subdirectory within the repo to scan for Python packages.
+
+    Returns:
+        A :class:`~sheridan.diffract.models.DiffractResult` describing the
+        commit type, a human-readable summary, and the full API diff.
+        The ``base_ref`` field is set to ``"HEAD"`` and ``head_ref`` is set
+        to ``":staged"``.
+
+    Raises:
+        GitError: If the repository cannot be found.
+        SurfaceError: If API surface extraction fails for the index.
+    """
+    resolved_path = repo_path if repo_path is not None else Path.cwd()
+    repo = get_repo(resolved_path)
+
+    # initial commit — no prior surface
+    base_surface = get_api_at_ref(repo, "HEAD", src_path=src_path) if repo.head.is_valid() else {}
+
+    head_surface = get_api_at_index(repo, src_path=src_path)
+
+    diff = diff_surfaces(base_surface, head_surface)
+    py_changed = has_python_changes_index(repo)
+    commit_type, summary = classify(diff, py_changed)
+
+    return DiffractResult(
+        commit_type=commit_type,
+        summary=summary,
+        diff=diff,
+        base_ref="HEAD",
+        head_ref=":staged",  # sentinel — not a real git ref
+    )

sheridan/diffract/classifier.py

@@ -0,0 +1,74 @@
+"""Commit-type classification for sheridan-diffract."""
+
+from __future__ import annotations
+
+__all__ = ["classify"]
+
+from collections import defaultdict
+
+from sheridan.diffract.enums import CommitType
+from sheridan.diffract.models import ApiDiff, NameChange
+
+
+def _group_by_module(changes: tuple[NameChange, ...]) -> dict[str, list[str]]:
+    """Group a sequence of NameChanges by their module name.
+
+    Args:
+        changes: The name changes to group.
+
+    Returns:
+        A dict mapping module name to a sorted list of public names.
+    """
+    grouped: dict[str, list[str]] = defaultdict(list)
+    for change in changes:
+        grouped[change.module].append(change.name)
+    return {mod: sorted(names) for mod, names in sorted(grouped.items())}
+
+
+def _format_grouped(changes: tuple[NameChange, ...]) -> str:
+    """Format grouped name changes as a multi-line string.
+
+    Args:
+        changes: The name changes to format.
+
+    Returns:
+        A human-readable string listing each module and its changed names.
+    """
+    grouped = _group_by_module(changes)
+    lines: list[str] = []
+    for module, names in grouped.items():
+        lines.append(f"{module}: {', '.join(names)}")
+    return "; ".join(lines)
+
+
+def classify(diff: ApiDiff, has_py_changes: bool) -> tuple[CommitType, str]:
+    """Map an ApiDiff to a conventional commit type and human-readable summary.
+
+    Rules applied in priority order:
+
+    1. Any removed names -> ``feat!`` (breaking change).
+       Summary lists removed names grouped by module.
+    2. Any added names -> ``feat``.
+       Summary lists added names grouped by module.
+    3. No name changes but Python files changed -> ``refactor``.
+    4. No changes at all -> ``fix``.
+
+    Args:
+        diff: The API diff produced by :func:`sheridan.diffract.differ.diff_surfaces`.
+        has_py_changes: Whether any ``.py`` files changed between the two refs.
+
+    Returns:
+        A two-tuple of ``(CommitType, summary_string)``.
+    """
+    if diff.is_breaking:
+        summary = f"Breaking: removed public names — {_format_grouped(diff.removed)}"
+        return CommitType.feat_breaking, summary
+
+    if diff.has_additions:
+        summary = f"Added public names — {_format_grouped(diff.added)}"
+        return CommitType.feat, summary
+
+    if has_py_changes:
+        return CommitType.refactor, "Internal Python changes; public API surface unchanged."
+
+    return CommitType.fix, "No public API or Python source changes detected."

sheridan/diffract/cli.py

@@ -0,0 +1,316 @@
+"""Command-line interface for sheridan-diffract."""
+
+from __future__ import annotations
+
+__all__ = ["main"]
+
+import argparse
+import json
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+from sheridan.diffract import __version__
+from sheridan.diffract.checker import check, check_staged
+from sheridan.diffract.config import load_config
+from sheridan.diffract.enums import CommitType
+from sheridan.diffract.exceptions import DiffractError
+from sheridan.diffract.git_utils import get_repo
+from sheridan.diffract.models import DiffractResult, NameChange
+
+_COMMIT_TYPE_RE: re.Pattern[str] = re.compile(r"^(feat|fix|refactor)(\([^)]*\))?(!)?:")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Construct and return the argument parser for the diffract CLI.
+
+    Returns:
+        A fully-configured :class:`argparse.ArgumentParser` instance.
+    """
+    parser = argparse.ArgumentParser(
+        prog="diffract",
+        description="Detect public API changes between git refs and suggest a commit type.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "base_ref",
+        nargs="?",
+        default=None,
+        metavar="BASE_REF",
+        help=(
+            "The earlier git ref to compare (default: HEAD~1). "
+            "When --validate-msg-file is used without explicit refs, "
+            "diffract automatically compares HEAD vs the staging area."
+        ),
+    )
+    parser.add_argument(
+        "head_ref",
+        nargs="?",
+        default=None,
+        metavar="HEAD_REF",
+        help=(
+            "The later git ref to compare (default: HEAD). "
+            "If only BASE_REF is given, HEAD is used as HEAD_REF. "
+            "When --validate-msg-file is used without explicit refs, "
+            "diffract automatically compares HEAD vs the staging area."
+        ),
+    )
+    parser.add_argument(
+        "--src",
+        default=None,
+        metavar="SRC",
+        dest="src_path",
+        help="Source directory within the repository to scan (default: src).",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="output_json",
+        help="Emit JSON to stdout instead of human-readable text.",
+    )
+    parser.add_argument(
+        "--exit-code",
+        action="store_true",
+        dest="exit_code",
+        help="Exit 1 for breaking changes, 2 for any API change, 0 otherwise.",
+    )
+    parser.add_argument(
+        "--validate-msg-file",
+        dest="validate_msg_file",
+        metavar="MSGFILE",
+        help="Path to commit message file; validates written type against detected API change.",
+    )
+
+    return parser
+
+
+def _group_changes(changes: tuple[NameChange, ...]) -> dict[str, list[str]]:
+    """Group NameChange objects by module for display purposes.
+
+    Args:
+        changes: The name changes to group.
+
+    Returns:
+        A dict mapping module name to sorted list of public names.
+    """
+    grouped: dict[str, list[str]] = defaultdict(list)
+    for change in changes:
+        grouped[change.module].append(change.name)
+    return {mod: sorted(names) for mod, names in sorted(grouped.items())}
+
+
+def _format_human(result: DiffractResult, scope: str | None = None) -> str:
+    """Format a DiffractResult as human-readable text.
+
+    Args:
+        result: The diffract result to format.
+        scope: Optional conventional-commit scope (without parentheses) to
+            include in the suggested commit prefix, e.g. ``"api"`` produces
+            ``"feat(api):"`` instead of ``"feat:"``.
+
+    Returns:
+        A multi-line string suitable for printing to a terminal.
+    """
+    lines: list[str] = []
+    commit_label = str(result.commit_type)
+    is_breaking = result.commit_type == CommitType.feat_breaking
+
+    if is_breaking:
+        lines.append(f"Detected: {commit_label}  (breaking change)")
+    else:
+        lines.append(f"Detected: {commit_label}")
+
+    lines.append("")
+
+    if result.diff.is_empty:
+        lines.append("No public API changes detected.")
+    else:
+        if result.diff.removed:
+            lines.append("Removed public names:")
+            for module, names in _group_changes(result.diff.removed).items():
+                lines.append(f"  {module}:")
+                for name in names:
+                    lines.append(f"    - {name}")
+        if result.diff.added:
+            lines.append("Added public names:")
+            for module, names in _group_changes(result.diff.added).items():
+                lines.append(f"  {module}:")
+                for name in names:
+                    lines.append(f"    + {name}")
+
+    lines.append("")
+    lines.append(f"Suggested commit prefix: {_format_commit_type(result.commit_type, scope)}")
+
+    return "\n".join(lines)
+
+
+def _resolve_exit_code(result: DiffractResult, use_exit_code: bool) -> int:
+    """Determine the process exit code based on the result and flag.
+
+    Args:
+        result: The diffract result.
+        use_exit_code: Whether the ``--exit-code`` flag was passed.
+
+    Returns:
+        ``0`` normally; ``1`` for breaking changes, ``2`` for any API change,
+        when ``use_exit_code`` is ``True``.
+    """
+    if not use_exit_code:
+        return 0
+    if result.diff.is_breaking:
+        return 1
+    if not result.diff.is_empty:
+        return 2
+    return 0
+
+
+def _parse_commit_type(first_line: str) -> CommitType | None:
+    """Parse the conventional commit type from the first line of a commit message.
+
+    Recognises ``feat``, ``feat!``, ``fix``, and ``refactor`` (with or without
+    a scope in parentheses). Any other prefix — including ``docs:``, ``chore:``,
+    ``test:``, etc. — returns ``None`` so that non-conventional commits are
+    never blocked.
+
+    Args:
+        first_line: The first line of the commit message.
+
+    Returns:
+        The matching :class:`~sheridan.diffract.enums.CommitType`, or ``None``
+        if the line does not start with a recognised conventional-commit type.
+    """
+    m = _COMMIT_TYPE_RE.match(first_line)
+    if m is None:
+        return None
+    base, _scope, bang = m.group(1), m.group(2), m.group(3)
+    match (base, bool(bang)):
+        case ("feat", True):
+            return CommitType.feat_breaking
+        case ("feat", False):
+            return CommitType.feat
+        case ("fix", _):
+            return CommitType.fix
+        case ("refactor", _):
+            return CommitType.refactor
+        case _:
+            return None
+
+
+def _extract_scope(first_line: str) -> str | None:
+    """Extract the optional scope from the first line of a commit message.
+
+    Args:
+        first_line: The first line of the commit message.
+
+    Returns:
+        The scope string without parentheses (e.g. ``"parser"`` from
+        ``"feat(parser): …"``), or ``None`` if no scope is present or
+        the line is not a recognised conventional-commit prefix.
+    """
+    m = _COMMIT_TYPE_RE.match(first_line)
+    if m is None:
+        return None
+    raw = m.group(2)  # e.g. "(parser)" or None
+    return raw[1:-1] if raw is not None else None
+
+
+def _format_commit_type(commit_type: CommitType, scope: str | None) -> str:
+    """Render a commit type with an optional scope as a conventional-commit prefix.
+
+    Args:
+        commit_type: The commit type to render.
+        scope: An optional scope string (without parentheses).
+
+    Returns:
+        A string such as ``"feat:"``, ``"feat(api):"`` or ``"feat(api)!:"``.
+    """
+    if scope is None:
+        return f"{commit_type}:"
+    if commit_type == CommitType.feat_breaking:
+        return f"feat({scope})!:"
+    return f"{commit_type}({scope}):"
+
+
+def main() -> None:
+    """CLI entrypoint for diffract.
+
+    Loads configuration from config files (if present), parses command-line arguments,
+    and invokes the check() or check_staged() function to detect API changes. Outputs
+    results as human-readable text or JSON, and optionally validates commit message types.
+
+    When ``--validate-msg-file`` is provided without explicit BASE_REF/HEAD_REF positional
+    arguments, diffract automatically compares ``HEAD`` against the current staging area
+    via :func:`~sheridan.diffract.checker.check_staged`.
+
+    Exits with code:
+      - 0: No changes detected (or --exit-code not set)
+      - 1: Breaking changes detected (with --exit-code), or commit message mismatch
+      - 2: Non-breaking API changes detected (with --exit-code)
+      - 3: Error during processing (git, file I/O, or surface detection)
+    """
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    repo_path = Path.cwd()
+    # Resolve the actual git repo root so load_config finds config files
+    # correctly even when diffract is invoked from a subdirectory.
+    try:
+        repo_root = Path(get_repo(repo_path).working_dir)
+    except DiffractError:
+        repo_root = repo_path  # no repo found; check() will raise the proper error
+    config = load_config(repo_root)
+    # Priority: --src flag > config file > built-in default
+    src_path: str = args.src_path or config.src or "src"
+
+    try:
+        if args.validate_msg_file is not None and not args.base_ref and not args.head_ref:
+            result = check_staged(repo_path=repo_path, src_path=src_path)
+        else:
+            result = check(
+                base_ref=args.base_ref or "HEAD~1",
+                head_ref=args.head_ref or "HEAD",
+                repo_path=repo_path,
+                src_path=src_path,
+            )
+    except DiffractError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(3)
+
+    if args.validate_msg_file is not None:
+        msg_path = Path(args.validate_msg_file)
+        try:
+            raw = msg_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            print(f"diffract: cannot read commit message file: {exc}", file=sys.stderr)
+            sys.exit(3)
+
+        _lines = raw.splitlines()
+        first_line = _lines[0] if _lines else ""
+        written_type = _parse_commit_type(first_line)
+        scope = _extract_scope(first_line)
+
+        if written_type is None:
+            sys.exit(0)
+        if written_type == result.commit_type:
+            sys.exit(0)
+
+        print(_format_human(result, scope=scope), file=sys.stderr)
+        print(
+            f"\ndiffract: commit type mismatch"
+            f"\n  written:  {_format_commit_type(written_type, scope)}"
+            f"\n  detected: {_format_commit_type(result.commit_type, scope)}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if args.output_json:
+        print(json.dumps(result.to_dict(), indent=2))
+    else:
+        print(_format_human(result))
+
+    sys.exit(_resolve_exit_code(result, args.exit_code))

sheridan/diffract/config.py

@@ -0,0 +1,100 @@
+"""TOML config file support for sheridan-diffract."""
+
+from __future__ import annotations
+
+__all__ = ["DiffractConfig", "load_config"]
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from sheridan.diffract.exceptions import DiffractError
+
+
+@dataclass(frozen=True)
+class DiffractConfig:
+    """Configuration loaded from diffract.toml or pyproject.toml.
+
+    Fields are None if not specified in any config file — the caller
+    merges them with CLI flags and built-in defaults.
+
+    Attributes:
+        src: The source directory within the repository to scan, or None
+            if not specified in any config file.
+    """
+
+    src: str | None = None
+
+
+def _parse_src(data: dict[str, Any], config_file: Path) -> str | None:
+    """Extract and validate the ``src`` key from a TOML data dict.
+
+    Args:
+        data: The parsed TOML table to read from.
+        config_file: Path to the config file, used in error messages.
+
+    Returns:
+        The value of ``src`` as a string, or ``None`` if not present.
+
+    Raises:
+        DiffractError: If ``src`` is present but is not a string.
+    """
+    src = data.get("src")
+    if src is None:
+        return None
+    if not isinstance(src, str):
+        raise DiffractError(
+            f"Invalid diffract config in {config_file}: 'src' must be a string, got {type(src).__name__!r}"
+        )
+    return src
+
+
+def _load_toml(path: Path) -> dict[str, Any]:
+    """Read and parse a TOML file, converting parse errors to DiffractError.
+
+    Args:
+        path: The TOML file to read.
+
+    Returns:
+        The parsed TOML document as a dict.
+
+    Raises:
+        DiffractError: If the file contains invalid TOML.
+    """
+    try:
+        with path.open("rb") as f:
+            return tomllib.load(f)
+    except tomllib.TOMLDecodeError as exc:
+        raise DiffractError(f"Failed to parse {path}: {exc}") from exc
+
+
+def load_config(repo_root: Path) -> DiffractConfig:
+    """Load diffract configuration from the repo root.
+
+    Checks for ``diffract.toml`` first, then ``pyproject.toml [tool.diffract]``.
+    Returns a ``DiffractConfig`` with ``None`` for any field not found.
+
+    Args:
+        repo_root: The root directory of the git repository.
+
+    Returns:
+        A ``DiffractConfig`` populated from the first config file found,
+        or an empty ``DiffractConfig`` if neither file exists.
+
+    Raises:
+        DiffractError: If a config file is found but contains invalid TOML
+            or an ``src`` value that is not a string.
+    """
+    diffract_toml = repo_root / "diffract.toml"
+    if diffract_toml.is_file():
+        data = _load_toml(diffract_toml)
+        return DiffractConfig(src=_parse_src(data, diffract_toml))
+
+    pyproject_toml = repo_root / "pyproject.toml"
+    if pyproject_toml.is_file():
+        data = _load_toml(pyproject_toml)
+        tool_diffract: dict[str, Any] = data.get("tool", {}).get("diffract", {})
+        return DiffractConfig(src=_parse_src(tool_diffract, pyproject_toml))
+
+    return DiffractConfig()

sheridan/diffract/differ.py

@@ -0,0 +1,48 @@
+"""API surface diffing for sheridan-diffract."""
+
+from __future__ import annotations
+
+__all__ = ["diff_surfaces"]
+
+from sheridan.diffract.enums import ChangeKind
+from sheridan.diffract.models import ApiDiff, NameChange
+
+
+def diff_surfaces(
+    base: dict[str, list[str]],
+    head: dict[str, list[str]],
+) -> ApiDiff:
+    """Compare two API surfaces and return added/removed NameChanges.
+
+    Iterates over every module present in either surface and computes the
+    symmetric difference of its public names. Results are sorted by
+    ``(module, name)``.
+
+    Args:
+        base: The API surface at the earlier ref, as returned by
+            ``sheridan.iceberg.get_public_api``.
+        head: The API surface at the later ref, as returned by
+            ``sheridan.iceberg.get_public_api``.
+
+    Returns:
+        An :class:`ApiDiff` containing tuples of :class:`NameChange` objects
+        for all names that were added or removed.
+    """
+    all_modules = set(base) | set(head)
+    added: list[NameChange] = []
+    removed: list[NameChange] = []
+
+    for module in all_modules:
+        base_names = set(base.get(module, []))
+        head_names = set(head.get(module, []))
+
+        for name in sorted(head_names - base_names):
+            added.append(NameChange(module=module, name=name, kind=ChangeKind.added))
+
+        for name in sorted(base_names - head_names):
+            removed.append(NameChange(module=module, name=name, kind=ChangeKind.removed))
+
+    added.sort(key=lambda c: (c.module, c.name))
+    removed.sort(key=lambda c: (c.module, c.name))
+
+    return ApiDiff(added=tuple(added), removed=tuple(removed))

sheridan/diffract/enums.py

@@ -0,0 +1,36 @@
+"""Enumerations for sheridan-diffract."""
+
+__all__ = [
+    "ChangeKind",
+    "CommitType",
+]
+
+from enum import StrEnum
+
+
+class CommitType(StrEnum):
+    """Conventional-commit type produced by diffract.
+
+    Attributes:
+        feat: A backwards-compatible addition was detected.
+        feat_breaking: A breaking change (removal) was detected.
+        fix: No API surface changes were detected.
+        refactor: Internal Python changes only; public API surface unchanged.
+    """
+
+    feat = "feat"
+    feat_breaking = "feat!"
+    fix = "fix"
+    refactor = "refactor"
+
+
+class ChangeKind(StrEnum):
+    """Whether a public name was added or removed.
+
+    Attributes:
+        added: The name appeared in head but not in base.
+        removed: The name appeared in base but not in head.
+    """
+
+    added = "added"
+    removed = "removed"

sheridan/diffract/exceptions.py

@@ -0,0 +1,17 @@
+"""Exceptions for sheridan-diffract."""
+
+from __future__ import annotations
+
+__all__ = ["DiffractError", "GitError", "SurfaceError"]
+
+
+class DiffractError(Exception):
+    """Base exception for all sheridan-diffract errors."""
+
+
+class GitError(DiffractError):
+    """Raised when a git operation fails (repo not found, bad ref, etc.)."""
+
+
+class SurfaceError(DiffractError):
+    """Raised when iceberg fails to extract a public API surface."""

sheridan/diffract/git_utils.py

@@ -0,0 +1,172 @@
+"""Git interaction utilities for sheridan-diffract."""
+
+from __future__ import annotations
+
+__all__ = [
+    "get_api_at_index",
+    "get_api_at_ref",
+    "get_repo",
+    "has_python_changes",
+    "has_python_changes_index",
+]
+
+import tarfile
+import tempfile
+from pathlib import Path
+
+from git import BadName, InvalidGitRepositoryError, Repo
+
+from sheridan.diffract.exceptions import GitError, SurfaceError
+from sheridan.iceberg import get_public_api
+
+
+def get_repo(path: Path) -> Repo:
+    """Find and return the git Repo at or above path.
+
+    Args:
+        path: A path inside (or equal to) the git repository root.
+
+    Returns:
+        The ``git.Repo`` instance for the repository.
+
+    Raises:
+        GitError: If no git repository is found at or above ``path``.
+    """
+    try:
+        return Repo(str(path), search_parent_directories=True)
+    except InvalidGitRepositoryError as exc:
+        raise GitError(f"No git repository found at or above: {path}") from exc
+
+
+def get_api_at_ref(repo: Repo, ref: str, src_path: str = "src") -> dict[str, list[str]]:
+    """Extract the public API surface at a given git ref.
+
+    Uses ``git archive`` to extract the repository tree into a temporary
+    directory, then invokes ``sheridan.iceberg.get_public_api()`` on the
+    ``src_path`` subdirectory (or the temp root if that subdirectory does
+    not exist).
+
+    Args:
+        repo: The git repository to archive.
+        ref: The git ref (branch, tag, or commit SHA) to check out.
+        src_path: Relative path within the repo that contains Python packages.
+
+    Returns:
+        A mapping of fully-qualified module name to list of public names,
+        as returned by ``sheridan.iceberg.get_public_api``.
+
+    Raises:
+        GitError: If ``ref`` is not a valid ref in the repository.
+        SurfaceError: If ``get_public_api`` raises any exception.
+    """
+    # Validate the ref early so we can give a clear error message.
+    try:
+        repo.commit(ref)
+    except BadName as exc:
+        raise GitError(f"Unknown ref: {ref}") from exc
+
+    with tempfile.TemporaryDirectory() as tmp:
+        proc = repo.git.archive(ref, format="tar", as_process=True)
+        with tarfile.open(fileobj=proc.stdout, mode="r|") as tar:
+            tar.extractall(tmp, filter="data")
+        proc.wait()
+
+        api_root = Path(tmp) / src_path
+        if not api_root.exists():
+            api_root = Path(tmp)
+
+        try:
+            return get_public_api(api_root)
+        except Exception as exc:
+            raise SurfaceError(f"Failed to extract public API at ref {ref!r}: {exc}") from exc
+
+
+def has_python_changes(repo: Repo, base_ref: str, head_ref: str) -> bool:
+    """Return True if any ``.py`` files differ between base_ref and head_ref.
+
+    Args:
+        repo: The git repository to inspect.
+        base_ref: The earlier git ref.
+        head_ref: The later git ref.
+
+    Returns:
+        ``True`` if at least one ``.py`` file appears in the diff,
+        ``False`` otherwise.
+    """
+    base_commit = repo.commit(base_ref)
+    head_commit = repo.commit(head_ref)
+    diffs = base_commit.diff(head_commit)
+    for d in diffs:
+        a_path: str = d.a_path or ""
+        b_path: str = d.b_path or ""
+        if a_path.endswith(".py") or b_path.endswith(".py"):
+            return True
+    return False
+
+
+def get_api_at_index(repo: Repo, src_path: str = "src") -> dict[str, list[str]]:
+    """Extract the public API surface from the current git staging area (index).
+
+    Materialises the staged tree via ``repo.index.write_tree()``, then uses
+    ``git archive`` on the resulting tree SHA to extract files into a temporary
+    directory before invoking ``sheridan.iceberg.get_public_api()``.
+
+    Args:
+        repo: The git repository whose index (staging area) to inspect.
+        src_path: Relative path within the repo that contains Python packages.
+
+    Returns:
+        A mapping of fully-qualified module name to list of public names,
+        as returned by ``sheridan.iceberg.get_public_api``.
+
+    Raises:
+        GitError: If tree materialisation or archive extraction fails.
+        SurfaceError: If ``get_public_api`` raises any exception.
+
+    Notes:
+        ``write_tree()`` flushes the in-memory index to ``.git/index`` as a
+        side effect before returning the tree object.
+    """
+    tree = repo.index.write_tree()
+    tree_sha: str = tree.hexsha
+
+    with tempfile.TemporaryDirectory() as tmp:
+        proc = repo.git.archive(tree_sha, format="tar", as_process=True)
+        with tarfile.open(fileobj=proc.stdout, mode="r|") as tar:
+            tar.extractall(tmp, filter="data")
+        proc.wait()
+
+        api_root = Path(tmp) / src_path
+        if not api_root.exists():
+            api_root = Path(tmp)
+
+        try:
+            return get_public_api(api_root)
+        except Exception as exc:
+            raise SurfaceError(f"Failed to extract public API from index: {exc}") from exc
+
+
+def has_python_changes_index(repo: Repo) -> bool:
+    """Return True if any ``.py`` files differ between HEAD and the staging area.
+
+    Compares the current HEAD commit against the git index (staging area).
+    If the repository has no HEAD commit (initial commit edge case), returns
+    ``True`` to conservatively assume changes exist.
+
+    Args:
+        repo: The git repository to inspect.
+
+    Returns:
+        ``True`` if at least one ``.py`` file appears in the diff between HEAD
+        and the index, or if no HEAD commit exists. ``False`` otherwise.
+    """
+    try:
+        diffs = repo.index.diff(repo.head.commit)
+    except ValueError:  # repo.head.commit raises ValueError when HEAD is unborn (initial commit)
+        return True
+    for d in diffs:
+        a_path: str = d.a_path or ""
+        b_path: str = d.b_path or ""
+        if a_path.endswith(".py") or b_path.endswith(".py"):
+            return True
+    return False

sheridan/diffract/models.py

@@ -0,0 +1,90 @@
+"""Data models for sheridan-diffract."""
+
+from __future__ import annotations
+
+__all__ = ["ApiDiff", "DiffractResult", "NameChange"]
+
+from dataclasses import dataclass
+
+from sheridan.diffract.enums import ChangeKind, CommitType
+
+
+@dataclass(frozen=True)
+class NameChange:
+    """A single public name that was added or removed from a module.
+
+    Attributes:
+        module: Qualified module name, e.g. ``"sheridan.diffract.enums"``.
+        name: The public identifier, e.g. ``"CommitType"``.
+        kind: Whether the name was added or removed.
+    """
+
+    module: str
+    name: str
+    kind: ChangeKind
+
+
+@dataclass(frozen=True)
+class ApiDiff:
+    """The complete difference between two API surfaces.
+
+    Attributes:
+        added: Public names present in head but not in base.
+        removed: Public names present in base but not in head.
+    """
+
+    added: tuple[NameChange, ...]
+    removed: tuple[NameChange, ...]
+
+    @property
+    def is_breaking(self) -> bool:
+        """Return True if any public names were removed."""
+        return bool(self.removed)
+
+    @property
+    def has_additions(self) -> bool:
+        """Return True if any public names were added."""
+        return bool(self.added)
+
+    @property
+    def is_empty(self) -> bool:
+        """Return True if no public names were added or removed."""
+        return not self.added and not self.removed
+
+
+@dataclass(frozen=True)
+class DiffractResult:
+    """The complete output of a diffract check.
+
+    Attributes:
+        commit_type: The conventional-commit type inferred from the diff.
+        summary: A human-readable description of the changes.
+        diff: The full API diff between base and head.
+        base_ref: The earlier git ref that was compared.
+        head_ref: The later git ref that was compared.
+    """
+
+    commit_type: CommitType
+    summary: str
+    diff: ApiDiff
+    base_ref: str
+    head_ref: str
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a JSON-serialisable representation of this result.
+
+        Returns:
+            A dict with keys ``commit_type``, ``summary``, ``base_ref``,
+            ``head_ref``, and ``diff`` (which contains ``added`` and
+            ``removed`` lists of ``{"module": ..., "name": ...}`` dicts).
+        """
+        return {
+            "commit_type": str(self.commit_type),
+            "summary": self.summary,
+            "base_ref": self.base_ref,
+            "head_ref": self.head_ref,
+            "diff": {
+                "added": [{"module": c.module, "name": c.name} for c in self.diff.added],
+                "removed": [{"module": c.module, "name": c.name} for c in self.diff.removed],
+            },
+        }

sheridan_diffract-1.0.1.dist-info/METADATA

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: sheridan-diffract
+Version: 1.0.1
+Summary: A short description of your project
+Project-URL: Repository, https://github.com/andrewasheridan/diffract
+Project-URL: Issues, https://github.com/andrewasheridan/diffract/issues
+Project-URL: Changelog, https://github.com/andrewasheridan/diffract/blob/main/CHANGELOG.md
+Author-email: sheridan <andrewasheridan@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: gitpython
+Requires-Dist: sheridan-iceberg>=2.0.0
+Provides-Extra: dev
+Requires-Dist: bandit[toml]>=1.9.4; extra == 'dev'
+Requires-Dist: commitizen>=4.13.9; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=1.0.3; extra == 'dev'
+Requires-Dist: mypy>=1.19.1; extra == 'dev'
+Requires-Dist: pre-commit>=4.5.1; extra == 'dev'
+Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: ruff>=0.15.7; extra == 'dev'
+Requires-Dist: zensical; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sheridan-diffract
+
+**Detects how a Python package's public API changed between two git commits and classifies that change as a conventional commit type.**
+
+Most semver tools trust the developer to classify their own changes correctly. `diffract` verifies that classification against the actual diff — catching the common case where someone writes `fix:` but actually removed a public function.
+
+## How it works
+
+1. Uses [sheridan-iceberg](https://github.com/andrewasheridan/iceberg) to extract the public API surface at two points in git history
+2. Diffs those two surfaces to find what was added or removed
+3. Maps the diff to a conventional commit classification:
+
+| Change | Commit type |
+|---|---|
+| Public name removed | `feat!` (breaking) |
+| Public name added | `feat` |
+| Only internal/private changes | `refactor` |
+| No changes detected | `fix` |
+
+## Installation
+
+```bash
+pip install sheridan-diffract
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Compare the last two commits (default)
+diffract
+
+# Compare specific refs
+diffract HEAD~3 HEAD
+
+# Custom source directory (default: src/)
+diffract --src lib/
+
+# Emit JSON for CI consumption
+diffract --json
+
+# Exit non-zero if a breaking change is detected (for CI gates)
+diffract --exit-code
+```
+
+**Exit codes with `--exit-code`:**
+- `0` — no API surface changes
+- `1` — breaking change (public name removed)
+- `2` — non-breaking API change (public name added)
+- `3` — error (git or surface extraction failure)
+
+**Example output:**
+
+```
+Detected: feat!  (breaking change)
+
+Removed public names:
+  sheridan.diffract.enums:
+    - OldHelper
+
+Suggested commit prefix: feat!:
+```
+
+```
+Detected: fix
+
+No public API changes detected.
+
+Suggested commit prefix: fix:
+```
+
+Scopes are passed through to the suggestion — if your commit message includes `(parser)`, the suggested prefix will too:
+
+```
+Suggested commit prefix: feat(parser):
+```
+
+### Python API
+
+```python
+from sheridan.diffract import check
+
+result = check(base_ref="v1.2.0", head_ref="HEAD")
+print(result.commit_type)   # e.g. "feat!"
+print(result.summary)       # human-readable description
+print(result.diff.removed)  # tuple of NameChange objects
+print(result.diff.added)
+
+# JSON-serialisable dict for CI output
+import json
+print(json.dumps(result.to_dict(), indent=2))
+```
+
+To compare `HEAD` against the **staging area** (what the next commit will contain) — the same comparison the pre-commit hook uses:
+
+```python
+from sheridan.diffract import check_staged
+
+result = check_staged()
+print(result.commit_type)  # reflects what is staged, not the last commit
+```
+
+### Validate commit messages with pre-commit
+
+`diffract` ships a `commit-msg` hook that rejects commits whose conventional commit type doesn't match the detected API change — catching `fix:` when you actually removed a public name.
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/sheridan/diffract
+    rev: v<VERSION>
+    hooks:
+      - id: diffract-validate
+```
+- make sure to `pre-commit install --hook-type commit-msg` first
+
+The hook compares `HEAD` against the **git staging area** (not `HEAD~1 → HEAD`), so it correctly detects what is about to be committed rather than what was committed last. Explicit `BASE`/`HEAD` refs can be added to override this (see the GitHub Actions example below).
+
+Scopes are preserved in all output — if you write `fix(parser): …`, the mismatch message will show `fix(parser):` as written and `feat(parser):` as the suggested replacement:
+
+```
+diffract: commit type mismatch
+  written:  fix(parser):
+  detected: feat(parser):
+```
+
+Non-conventional commit types (`docs:`, `chore:`, `test:`, etc.) are never blocked.
+
+### Configuration
+
+If your source code isn't in `src/`, tell diffract once in a config file rather than repeating it on every command:
+
+**`diffract.toml`** (takes precedence):
+```toml
+src = "python/src"
+```
+
+**`pyproject.toml`**:
+```toml
+[tool.diffract]
+src = "python/src"
+```
+
+Priority: explicit `--src` flag → `diffract.toml` → `pyproject.toml` → default (`src/`).
+
+### As a GitHub Actions check
+
+Validate the **PR title** against detected API changes — the CI equivalent of the pre-commit hook.
+The refs to diff are the PR branch HEAD versus the target branch HEAD:
+
+```yaml
+# .github/workflows/diffract.yml
+name: diffract
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]  # 'edited' catches title-only changes
+
+jobs:
+  api-change-check:
+    name: Validate PR title against API changes
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # required to access both commit SHAs
+
+      - name: Install diffract
+        run: pip install sheridan-diffract
+
+      - name: Validate PR title type matches API change
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          printf '%s' "$PR_TITLE" > /tmp/pr-title.txt
+          diffract \
+            ${{ github.event.pull_request.base.sha }} \
+            ${{ github.event.pull_request.head.sha }} \
+            --validate-msg-file /tmp/pr-title.txt
+```
+
+- `base.sha` — HEAD of the target branch (e.g. `main`) at the time of the PR event
+- `head.sha` — HEAD of the PR branch
+- Non-conventional title prefixes (`docs:`, `chore:`, `test:`, etc.) are never blocked
+- Scopes are passed through: a title of `feat(parser): …` will suggest `feat(parser):` on mismatch
+
+## What it does not do
+
+- `diffract` has **no AST logic of its own**. It delegates all API surface extraction to `sheridan-iceberg`.
+- It compares public names only (additions and removals). **Signature changes** (argument renames, return type changes) are not currently detected — iceberg returns name lists, not signatures.
+- It does not modify commits or rewrite history. It only reports.
+
+## Development
+
+```bash
+task install        # install all dependencies
+task check          # lint + format + typecheck + tests (must all pass)
+task test           # pytest with coverage (≥90% required)
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.

sheridan_diffract-1.0.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+sheridan/diffract/__init__.py,sha256=W3_ros8is0HZCC923q0IYzBXLNznNbvRhHvUvJJM38A,903
+sheridan/diffract/checker.py,sha256=eIfAke2J3JCS8tgPKeNWQPXO1s_65sxpSOM8AnDhFI0,3595
+sheridan/diffract/classifier.py,sha256=dL32A1-vtLxF23fxXP1Y0d-nLuj99DqOg4WRYvbCwNE,2473
+sheridan/diffract/cli.py,sha256=ntp5gOhsBA0bVHxYxVQ1EPdjmNndSGt9qd0XP5izf90,10762
+sheridan/diffract/config.py,sha256=SVpXC5C_h2U1yXWOdQsGkA2dHlUxWXyXgnvagbplzCg,3046
+sheridan/diffract/differ.py,sha256=LhoHUVuwJ1Hw4Ve7q1h_MJYU6XwR514m7ELgNoeQibU,1624
+sheridan/diffract/enums.py,sha256=p8UZ0g8StcXPKCxPgByhXI4OGHP-fph9hVtcCuVjF0c,838
+sheridan/diffract/exceptions.py,sha256=oFjWLIJNcCyChpIjE8rseEe5lS18b4X7qVOsFc_IX0w,442
+sheridan/diffract/git_utils.py,sha256=UXED4NbH9HXYiFkzN_vHeLlUq4ek4k_xAzP3MDaX3yM,5867
+sheridan/diffract/models.py,sha256=DHhP5ddl8LQCHZ4AYH8cFwkx0SXk8Bfy_8hdf6aJt2o,2672
+sheridan/diffract/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sheridan_diffract-1.0.1.dist-info/METADATA,sha256=W3wzr4YL4ni1w-RxX20CFKOIBi4v4CyUoeVF9e8Uu28,7132
+sheridan_diffract-1.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sheridan_diffract-1.0.1.dist-info/entry_points.txt,sha256=8h6QCl44rTMcNA0XvYf4lAWyg9ZJR2QG6vxvrFMURhY,56
+sheridan_diffract-1.0.1.dist-info/licenses/LICENSE,sha256=1PPxoxjYTZ-Folpvd8k2L7IRTHqgjLGNxjpUEElePOo,1065
+sheridan_diffract-1.0.1.dist-info/RECORD,,

sheridan_diffract-1.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sheridan_diffract-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+diffract = sheridan.diffract.cli:main

sheridan_diffract-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sheridan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.