gitinspect 0.1.0__py3-none-any.whl

diffenv/__init__.py

@@ -0,0 +1,11 @@
+"""
+diffenv — compare environment-level changes between git refs.
+
+Public SDK surface:
+    from diffenv import compare
+"""
+
+from diffenv.api import compare
+
+__all__ = ["compare"]
+__version__ = "0.1.0"

diffenv/api.py

@@ -0,0 +1,72 @@
+"""
+Public Python SDK for diffenv.
+
+    from diffenv import compare
+    result = compare("main", "feature/new-auth")
+
+    # Or get pre-rendered output directly:
+    text = compare("main", "feature/new-auth", output_format="json")
+"""
+
+from __future__ import annotations
+
+from diffenv.models import DiffResult
+
+
+def compare(
+    ref_old: str,
+    ref_new: str,
+    *,
+    repo_path: str = ".",
+    auto_fetch: bool = True,
+    output_format: str | None = None,
+) -> DiffResult | str:
+    """
+    Compare environment-level changes between two git refs.
+
+    Args:
+        ref_old:        Base ref (branch name, tag, or commit SHA).
+        ref_new:         Target ref to compare against.
+        repo_path:       Path to the git repository root. Defaults to CWD.
+        auto_fetch:      If True (default for SDK use), missing refs are
+                         fetched from the remote automatically. If False,
+                         a missing ref raises RefNotFoundError immediately.
+                         The SDK never blocks on an interactive prompt
+                         (that behavior is CLI-only); auto_fetch is the
+                         only switch controlling this.
+        output_format:   If given ("text", "json", or "color"), returns a
+                         pre-rendered string instead of a DiffResult object.
+                         Leave as None to get the structured DiffResult for
+                         programmatic use.
+
+    Returns:
+        A DiffResult by default, or a rendered str if output_format is set.
+
+    Raises:
+        NotAGitRepoError:  ``repo_path`` is not inside a git repository.
+        RefNotFoundError:  A ref could not be resolved locally or remotely.
+        ParseError:        A tracked file exists but could not be parsed.
+        DiffEnvError:      Any other diffenv-specific failure.
+    """
+    # Imports are deferred so the module loads fast even before deps are ready.
+    from diffenv.git_layer import GitClient
+    from diffenv.parser_layer import parse_snapshot
+    from diffenv.diff_layer import compute_diff
+    from diffenv.formatter_layer import get_formatter
+
+    # The SDK is a non-interactive context: there is no terminal to prompt
+    # against, so a missing ref should fail fast (raise RefNotFoundError)
+    # rather than block on input(). auto_fetch governs the actual decision;
+    # this callback only exists to prevent GitClient from falling back to
+    # its interactive y/N console prompt.
+    client = GitClient(repo_path=repo_path, confirm_callback=lambda ref: False)
+
+    snapshot_old = parse_snapshot(client.fetch_files(ref_old, auto_fetch=auto_fetch), ref=ref_old)
+    snapshot_new = parse_snapshot(client.fetch_files(ref_new, auto_fetch=auto_fetch), ref=ref_new)
+
+    result = compute_diff(snapshot_old, snapshot_new)
+
+    if output_format is None:
+        return result
+
+    return get_formatter(output_format).render(result)

diffenv/cli.py

@@ -0,0 +1,155 @@
+"""
+CLI entry point for diffenv.
+
+    diffenv main feature/new-auth
+    diffenv main feature/new-auth --format json
+    diffenv main feature/new-auth --auto-fetch
+    diffenv main feature/new-auth --repo-path /path/to/repo
+
+Design: this module is intentionally thin. All real logic lives in the
+git/parser/diff/formatter layers; the CLI's only job is argument parsing,
+wiring those layers together, and translating exceptions into clean,
+user-facing messages with appropriate exit codes. No stack traces are ever
+shown to the user — use --verbose to enable debug logging to stderr for
+troubleshooting.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+from rich.console import Console
+
+from diffenv.exceptions import DiffEnvError, GitError, NotAGitRepoError, ParseError, RefNotFoundError
+from diffenv.logging_config import configure as configure_logging
+
+app = typer.Typer(
+    name="diffenv",
+    help="Compare environment-level changes between two git branches or commits.",
+    no_args_is_help=True,
+    pretty_exceptions_show_locals=False,
+    pretty_exceptions_enable=False,
+)
+
+_console_out = Console()
+_console_err = Console(stderr=True)
+
+
+@app.command()
+def main(
+    ref_old: str = typer.Argument(..., help="Base branch, tag, or commit (e.g. 'main')"),
+    ref_new: str = typer.Argument(..., help="Target branch, tag, or commit (e.g. 'feature/new-auth')"),
+    output_format: str = typer.Option(
+        "color",
+        "--format",
+        "-f",
+        help="Output format: color, text, or json.",
+    ),
+    repo_path: str = typer.Option(
+        ".",
+        "--repo-path",
+        "-C",
+        help="Path to the git repository (defaults to current directory).",
+    ),
+    auto_fetch: bool = typer.Option(
+        False,
+        "--auto-fetch",
+        help="Automatically fetch missing refs from the remote without prompting.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show debug logging on stderr for troubleshooting.",
+    ),
+) -> None:
+    """
+    Compare environment-level changes between REF_OLD and REF_NEW.
+
+    Both refs must exist locally, or be fetchable from the 'origin' remote.
+    If a ref is missing locally and --auto-fetch is not set, you'll be
+    prompted interactively to fetch it.
+    """
+    configure_logging(verbose=verbose)
+
+    # Validate format early so a typo doesn't waste time doing git work first.
+    valid_formats = {"color", "text", "json"}
+    if output_format not in valid_formats:
+        _console_err.print(
+            f"[red]Error:[/red] Unknown output format '{output_format}'. "
+            f"Valid options: {', '.join(sorted(valid_formats))}."
+        )
+        raise typer.Exit(code=2)
+
+    from diffenv.git_layer import GitClient
+    from diffenv.parser_layer import parse_snapshot
+    from diffenv.diff_layer import compute_diff
+    from diffenv.formatter_layer import get_formatter
+
+    try:
+        client = GitClient(repo_path=repo_path)
+
+        snapshot_old = parse_snapshot(client.fetch_files(ref_old, auto_fetch=auto_fetch), ref=ref_old)
+        snapshot_new = parse_snapshot(client.fetch_files(ref_new, auto_fetch=auto_fetch), ref=ref_new)
+
+        diff = compute_diff(snapshot_old, snapshot_new)
+        rendered = get_formatter(output_format).render(diff)
+
+        if output_format == "color":
+            _console_out.print(rendered)
+        else:
+            # text and json go to plain stdout — no rich markup, no ANSI
+            # codes — so output is safe to pipe/redirect/parse.
+            typer.echo(rendered)
+
+        # Exit code reflects whether changes were found — useful for CI
+        # gating (e.g. "fail the build if env changed without review").
+        raise typer.Exit(code=0 if diff.is_empty else 1)
+
+    except NotAGitRepoError as exc:
+        _console_err.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=2)
+
+    except RefNotFoundError as exc:
+        _console_err.print(
+            f"[red]Error:[/red] Could not find ref '{exc.ref}'. "
+            "It doesn't exist locally and could not be resolved from the "
+            "remote. Try running 'git fetch' manually, or check the ref name."
+        )
+        raise typer.Exit(code=2)
+
+    except ParseError as exc:
+        _console_err.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=2)
+
+    except GitError as exc:
+        _console_err.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=2)
+
+    except DiffEnvError as exc:
+        _console_err.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=2)
+
+    except typer.Exit:
+        raise
+
+    except Exception as exc:  # noqa: BLE001 — final safety net, never leak raw tracebacks
+        configure_logging.__module__  # no-op to keep import used
+        from diffenv.logging_config import get_logger
+
+        get_logger("cli").debug("Unexpected error", exc_info=True)
+        _console_err.print(
+            "[red]Error:[/red] An unexpected error occurred. "
+            "Run with --verbose for details."
+        )
+        raise typer.Exit(code=1)
+
+
+def app_entry() -> None:
+    """Console-script entry point (referenced by pyproject.toml)."""
+    app()
+
+
+if __name__ == "__main__":
+    app()

diffenv/diff_layer.py

@@ -0,0 +1,102 @@
+"""
+Diff layer — compares two ParsedSnapshot objects and produces a DiffResult.
+
+This layer is pure data transformation: no file I/O, no git, no formatting.
+It takes two already-parsed snapshots and figures out what changed.
+Keeping it pure makes it trivially unit-testable and reusable from both
+the CLI and the SDK.
+"""
+
+from __future__ import annotations
+
+from diffenv.logging_config import get_logger
+from diffenv.models import DepChange, DiffResult, EnvVarChange, ParsedSnapshot
+
+logger = get_logger("diff_layer")
+
+
+def _diff_dependencies(old: ParsedSnapshot, new: ParsedSnapshot) -> list[DepChange]:
+    """
+    Compare dependency lists by name (case-insensitive — PyPI package names
+    are not case-sensitive) and report additions, removals, and version
+    changes. Unchanged dependencies are NOT included in the result.
+
+    Presence and version are tracked separately: a dependency can be
+    "present but unpinned" (version=None, present=True), which is distinct
+    from "absent" (present=False). This avoids conflating "no version
+    pinned" with "package not installed."
+    """
+    old_by_name = {dep.name.lower(): dep for dep in old.dependencies}
+    new_by_name = {dep.name.lower(): dep for dep in new.dependencies}
+
+    all_names = sorted(set(old_by_name) | set(new_by_name))
+    changes: list[DepChange] = []
+
+    for name_key in all_names:
+        old_dep = old_by_name.get(name_key)
+        new_dep = new_by_name.get(name_key)
+
+        old_present = old_dep is not None
+        new_present = new_dep is not None
+        old_version = old_dep.version if old_dep else None
+        new_version = new_dep.version if new_dep else None
+
+        if old_present == new_present and old_version == new_version:
+            continue  # no change
+
+        # Use the original-cased name from whichever side has it (prefer new)
+        display_name = (new_dep or old_dep).name
+        changes.append(
+            DepChange(
+                name=display_name,
+                old_present=old_present,
+                new_present=new_present,
+                old_version=old_version,
+                new_version=new_version,
+            )
+        )
+
+    return changes
+
+
+def _diff_env_vars(old: ParsedSnapshot, new: ParsedSnapshot) -> list[EnvVarChange]:
+    """
+    Compare declared env var keys (case-sensitive — env var names ARE
+    case-sensitive at the OS level). Reports only additions and removals;
+    env vars present in both are unchanged by definition (we don't track
+    values, only key presence).
+    """
+    old_keys = {ev.key for ev in old.env_vars}
+    new_keys = {ev.key for ev in new.env_vars}
+
+    added = sorted(new_keys - old_keys)
+    removed = sorted(old_keys - new_keys)
+
+    changes: list[EnvVarChange] = []
+    changes.extend(EnvVarChange(key=key, is_added=True) for key in added)
+    changes.extend(EnvVarChange(key=key, is_added=False) for key in removed)
+    return changes
+
+
+def compute_diff(old: ParsedSnapshot, new: ParsedSnapshot) -> DiffResult:
+    """
+    Compute the full diff between two parsed snapshots.
+
+    Args:
+        old: snapshot of the base ref (e.g. 'main').
+        new: snapshot of the target ref (e.g. 'feature/new-auth').
+
+    Returns:
+        DiffResult containing only what changed. Use `.is_empty` to check
+        whether there were no environment-level differences at all.
+    """
+    logger.debug("Computing diff: '%s' -> '%s'", old.ref, new.ref)
+
+    return DiffResult(
+        ref_old=old.ref,
+        ref_new=new.ref,
+        dep_changes=_diff_dependencies(old, new),
+        env_changes=_diff_env_vars(old, new),
+        python_old=old.python_version,
+        python_new=new.python_version,
+    )

diffenv/exceptions.py

@@ -0,0 +1,29 @@
+"""Custom exceptions for diffenv. All user-facing errors derive from DiffEnvError."""
+
+
+class DiffEnvError(Exception):
+    """Base class for all diffenv errors."""
+
+
+class GitError(DiffEnvError):
+    """Raised when a git operation fails (bad ref, not a repo, etc.)."""
+
+
+class RefNotFoundError(GitError):
+    """Raised when a ref doesn't exist locally or remotely."""
+
+    def __init__(self, ref: str) -> None:
+        self.ref = ref
+        super().__init__(f"Ref not found: '{ref}'")
+
+
+class NotAGitRepoError(GitError):
+    """Raised when the working directory is not inside a git repo."""
+
+
+class ParseError(DiffEnvError):
+    """Raised when a file cannot be parsed."""
+
+    def __init__(self, filename: str, reason: str) -> None:
+        self.filename = filename
+        super().__init__(f"Could not parse '{filename}': {reason}")

diffenv/formatter_layer.py

@@ -0,0 +1,198 @@
+"""
+Formatter layer — renders a DiffResult as output text.
+
+Three formatters ship today: plain text, JSON, and colored terminal output.
+All implement the same minimal Formatter protocol, so the CLI/SDK can swap
+between them via dependency injection without any conditional logic at the
+call site — formatters are interchangeable by design.
+
+To add a new output format later (e.g. Markdown for CI comments):
+    1. Write a class with a `.render(diff: DiffResult) -> str` method.
+    2. Register it in `FORMATTERS`.
+That's the entire integration surface.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Protocol
+
+from diffenv.models import DiffResult
+
+
+class Formatter(Protocol):
+    """Minimal interface every formatter must implement."""
+
+    def render(self, diff: DiffResult) -> str:
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Plain text formatter
+# ---------------------------------------------------------------------------
+
+
+class PlainTextFormatter:
+    """Renders output exactly in the style shown in the project spec."""
+
+    def render(self, diff: DiffResult) -> str:
+        if diff.is_empty:
+            return f"No environment-level changes between '{diff.ref_old}' and '{diff.ref_new}'."
+
+        lines: list[str] = []
+
+        if diff.dep_changes:
+            lines.append("Dependencies")
+            for c in diff.dep_changes:
+                if c.is_added:
+                    suffix = f"=={c.new_version}" if c.new_version else ""
+                    lines.append(f"+ {c.name}{suffix}")
+                elif c.is_removed:
+                    lines.append(f"- {c.name}")
+                elif c.is_upgraded:
+                    new_v = c.new_version or "unpinned"
+                    old_v = c.old_version or "unpinned"
+                    lines.append(f"+ {c.name}=={new_v} (was {old_v})")
+                else:
+                    # present both sides, version unchanged-but-flagged edge case
+                    lines.append(f"~ {c.name}")
+            lines.append("")
+
+        if diff.env_changes:
+            lines.append("Environment Variables")
+            for c in diff.env_changes:
+                symbol = "+" if c.is_added else "-"
+                lines.append(f"{symbol} {c.key}")
+            lines.append("")
+
+        if diff.has_python_change:
+            lines.append("Python Runtime")
+            old_v = diff.python_old or "(none)"
+            new_v = diff.python_new or "(none)"
+            lines.append(f"{old_v} \u2192 {new_v}")
+            lines.append("")
+
+        return "\n".join(lines).rstrip("\n")
+
+
+# ---------------------------------------------------------------------------
+# JSON formatter
+# ---------------------------------------------------------------------------
+
+
+class JSONFormatter:
+    """Renders a machine-readable JSON representation, suitable for CI pipelines."""
+
+    def __init__(self, indent: int = 2) -> None:
+        self.indent = indent
+
+    def render(self, diff: DiffResult) -> str:
+        payload = {
+            "ref_old": diff.ref_old,
+            "ref_new": diff.ref_new,
+            "is_empty": diff.is_empty,
+            "dependencies": [
+                {
+                    "name": c.name,
+                    "old_present": c.old_present,
+                    "new_present": c.new_present,
+                    "old_version": c.old_version,
+                    "new_version": c.new_version,
+                    "change_type": (
+                        "added" if c.is_added else "removed" if c.is_removed else "upgraded" if c.is_upgraded else "changed"
+                    ),
+                }
+                for c in diff.dep_changes
+            ],
+            "environment_variables": [
+                {"key": c.key, "change_type": "added" if c.is_added else "removed"}
+                for c in diff.env_changes
+            ],
+            "python_runtime": {
+                "old": diff.python_old,
+                "new": diff.python_new,
+                "changed": diff.has_python_change,
+            },
+        }
+        return json.dumps(payload, indent=self.indent)
+
+
+# ---------------------------------------------------------------------------
+# Colored terminal formatter (uses rich)
+# ---------------------------------------------------------------------------
+
+
+class ColorFormatter:
+    """
+    Renders the same layout as PlainTextFormatter but with rich markup tags
+    for terminal coloring: green for additions, red for removals, yellow
+    for version upgrades and runtime changes.
+
+    Returns a string containing rich markup (e.g. "[green]+ foo[/green]"),
+    intended to be printed via a rich Console, not raw stdout — printing it
+    raw would show the literal markup tags.
+    """
+
+    def render(self, diff: DiffResult) -> str:
+        if diff.is_empty:
+            return f"No environment-level changes between '{diff.ref_old}' and '{diff.ref_new}'."
+
+        lines: list[str] = []
+
+        if diff.dep_changes:
+            lines.append("[bold]Dependencies[/bold]")
+            for c in diff.dep_changes:
+                if c.is_added:
+                    suffix = f"=={c.new_version}" if c.new_version else ""
+                    lines.append(f"[green]+ {c.name}{suffix}[/green]")
+                elif c.is_removed:
+                    lines.append(f"[red]- {c.name}[/red]")
+                elif c.is_upgraded:
+                    new_v = c.new_version or "unpinned"
+                    old_v = c.old_version or "unpinned"
+                    lines.append(f"[yellow]+ {c.name}=={new_v}[/yellow] [dim](was {old_v})[/dim]")
+                else:
+                    lines.append(f"[yellow]~ {c.name}[/yellow]")
+            lines.append("")
+
+        if diff.env_changes:
+            lines.append("[bold]Environment Variables[/bold]")
+            for c in diff.env_changes:
+                if c.is_added:
+                    lines.append(f"[green]+ {c.key}[/green]")
+                else:
+                    lines.append(f"[red]- {c.key}[/red]")
+            lines.append("")
+
+        if diff.has_python_change:
+            lines.append("[bold]Python Runtime[/bold]")
+            old_v = diff.python_old or "(none)"
+            new_v = diff.python_new or "(none)"
+            lines.append(f"[yellow]{old_v} \u2192 {new_v}[/yellow]")
+            lines.append("")
+
+        return "\n".join(lines).rstrip("\n")
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+FORMATTERS: dict[str, type] = {
+    "text": PlainTextFormatter,
+    "json": JSONFormatter,
+    "color": ColorFormatter,
+}
+
+
+def get_formatter(name: str) -> Formatter:
+    """
+    Look up a formatter by name. Raises ValueError with a clean message
+    (not a KeyError) listing valid options, since this is user-facing
+    (e.g. invalid --format flag value).
+    """
+    formatter_cls = FORMATTERS.get(name)
+    if formatter_cls is None:
+        valid = ", ".join(sorted(FORMATTERS))
+        raise ValueError(f"Unknown output format '{name}'. Valid options: {valid}")
+    return formatter_cls()