gitinspect 0.1.0__py3-none-any.whl

diffenv/git_layer.py

@@ -0,0 +1,278 @@
+"""
+Git layer — resolves refs and fetches file content at a given ref, without
+ever checking out the working tree. Uses `git show <ref>:<path>` so the
+user's working directory and index are never touched.
+
+Responsibilities:
+    - Validate we're inside a git repository.
+    - Resolve a ref (branch / tag / commit) to a real commit, fetching from
+      the remote if it's missing locally (interactively, unless auto_fetch).
+    - Fetch the content of specific tracked files at that ref.
+    - Never leak raw git/subprocess errors to the caller — everything is
+      translated into diffenv's own exception types with clear messages.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from diffenv.exceptions import GitError, NotAGitRepoError, RefNotFoundError
+from diffenv.logging_config import get_logger
+
+logger = get_logger("git_layer")
+
+# Files diffenv cares about. Parser layer (Phase 3) consumes these by name.
+TRACKED_FILES: tuple[str, ...] = (
+    "requirements.txt",
+    "pyproject.toml",
+    ".env.example",
+    ".python-version",
+)
+
+
+class _GitResult:
+    """
+    Minimal result object returned by _run_git.
+    stdout is kept as raw bytes so callers can decode with BOM detection.
+    stderr is pre-decoded as UTF-8 (git's own messages are always UTF-8).
+    """
+
+    __slots__ = ("returncode", "stdout_bytes", "stderr")
+
+    def __init__(self, returncode: int, stdout_bytes: bytes, stderr: str) -> None:
+        self.returncode = returncode
+        self.stdout_bytes = stdout_bytes
+        self.stderr = stderr
+
+
+def _decode_file_bytes(raw: bytes) -> str:
+    """
+    Decode raw file bytes from git show, handling:
+      - UTF-16 LE with BOM (\\xff\\xfe) — PowerShell echo, old Notepad
+      - UTF-16 BE with BOM (\\xfe\\xff) — rare but possible
+      - UTF-8 with BOM (\\xef\\xbb\\xbf) — some Windows editors
+      - Plain UTF-8 (no BOM) — standard on Linux/Mac, Git for Windows default
+    """
+    if raw[:2] == b"\xff\xfe":
+        return raw.decode("utf-16-le", errors="replace").lstrip("\ufeff")
+    if raw[:2] == b"\xfe\xff":
+        return raw.decode("utf-16-be", errors="replace").lstrip("\ufeff")
+    if raw[:3] == b"\xef\xbb\xbf":
+        return raw[3:].decode("utf-8", errors="replace")
+    return raw.decode("utf-8", errors="replace")
+
+
+def _run_git(args: list[str], cwd: str) -> subprocess.CompletedProcess:
+    """
+    Run a git subcommand and return the CompletedProcess.
+    Never raises on non-zero exit — caller inspects returncode.
+    Raises GitError only if git itself cannot be invoked (not installed).
+    """
+    try:
+        # Use text=False (binary mode) so we get raw bytes back regardless
+        # of the platform's default encoding. We decode stdout ourselves in
+        # get_file_content() to handle UTF-16 files created by Windows tools.
+        # stderr is always plain ASCII/UTF-8 from git itself, safe to decode.
+        result = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            capture_output=True,
+            text=False,
+            timeout=30,
+        )
+        # Decode stderr as UTF-8 (git's own messages are always UTF-8).
+        result_text_stderr = result.stderr.decode("utf-8", errors="replace")
+        # Return a namespace-like object that callers can treat the same way.
+        # stdout is kept as bytes; get_file_content decodes it with BOM detection.
+        return _GitResult(
+            returncode=result.returncode,
+            stdout_bytes=result.stdout,
+            stderr=result_text_stderr,
+        )
+    except FileNotFoundError as exc:
+        raise GitError(
+            "Git is not installed or not available on PATH. "
+            "Please install git to use diffenv."
+        ) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise GitError(
+            "Git command timed out. This can happen with a slow or "
+            "unreachable remote — check your network connection."
+        ) from exc
+
+
+class GitClient:
+    """
+    Thin, safe wrapper around git for diffenv's needs.
+
+    Args:
+        repo_path:        Path to the repository root (defaults to CWD).
+        confirm_callback:  Called with the missing ref name when a ref isn't
+                            found locally and a remote fetch could resolve
+                            it. Should return True to proceed with fetching,
+                            False to decline. Defaults to an interactive
+                            y/n console prompt. SDK callers can pass a
+                            no-op (lambda r: False) or set auto_fetch=True
+                            on individual calls to skip prompting entirely.
+    """
+
+    def __init__(
+        self,
+        repo_path: str = ".",
+        confirm_callback=None,
+    ) -> None:
+        self.repo_path = str(Path(repo_path).resolve())
+        self._confirm_callback = confirm_callback or self._default_confirm
+        self._verify_repo()
+
+    # ------------------------------------------------------------------
+    # Setup / validation
+    # ------------------------------------------------------------------
+
+    def _verify_repo(self) -> None:
+        result = _run_git(["rev-parse", "--is-inside-work-tree"], cwd=self.repo_path)
+        if result.returncode != 0:
+            logger.debug("rev-parse failed: %s", result.stderr.strip())
+            raise NotAGitRepoError(
+                f"'{self.repo_path}' is not a git repository "
+                "(or none of the parent directories are)."
+            )
+
+    @staticmethod
+    def _default_confirm(ref: str) -> bool:
+        """Interactive y/n prompt used by the CLI. SDK users should override this."""
+        try:
+            answer = input(
+                f"Branch/ref '{ref}' was not found locally. "
+                f"Attempt to fetch it from the remote? [y/N]: "
+            ).strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            return False
+        return answer in ("y", "yes")
+
+    # ------------------------------------------------------------------
+    # Ref resolution
+    # ------------------------------------------------------------------
+
+    def _ref_exists_locally(self, ref: str) -> bool:
+        result = _run_git(["rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}"], cwd=self.repo_path)
+        return result.returncode == 0
+
+    def _remote_ref_exists(self, ref: str) -> bool:
+        """Check (without fetching) whether `ref` exists on any configured remote."""
+        result = _run_git(["ls-remote", "--exit-code", "--heads", "--tags", "origin", ref], cwd=self.repo_path)
+        return result.returncode == 0 and bool(result.stdout_bytes.strip())
+
+    def _fetch_ref(self, ref: str) -> bool:
+        """
+        Fetch `ref` from origin into FETCH_HEAD. A plain `git fetch origin <ref>`
+        does NOT create or update a local branch — it only populates FETCH_HEAD —
+        so resolution after fetching must use `origin/<ref>` or FETCH_HEAD,
+        never the bare branch name.
+        """
+        logger.debug("Fetching ref '%s' from origin", ref)
+        result = _run_git(["fetch", "origin", ref], cwd=self.repo_path)
+        if result.returncode != 0:
+            logger.debug("git fetch failed: %s", result.stderr.strip())
+            return False
+        return True
+
+    def resolve_ref(self, ref: str, auto_fetch: bool = False) -> str:
+        """
+        Ensure `ref` is resolvable, fetching from the remote if needed.
+
+        Args:
+            ref:        Branch name, tag, or commit SHA.
+            auto_fetch: If True, fetch automatically without prompting
+                         (used by the SDK / non-interactive callers).
+
+        Returns:
+            A ref string guaranteed resolvable via `git show`. This may
+            differ from the input `ref` (e.g. resolved to `origin/<ref>`
+            after a remote fetch) — callers must use the RETURNED value,
+            not the original argument, for all subsequent git operations.
+
+        Raises:
+            RefNotFoundError: ref does not exist locally or on the remote,
+                               or the user declined to fetch it.
+        """
+        if self._ref_exists_locally(ref):
+            return ref
+
+        logger.debug("Ref '%s' not found locally", ref)
+
+        if not auto_fetch:
+            should_fetch = self._confirm_callback(ref)
+            if not should_fetch:
+                raise RefNotFoundError(ref)
+        else:
+            logger.debug("auto_fetch enabled, skipping prompt for '%s'", ref)
+
+        if not self._remote_ref_exists(ref):
+            raise RefNotFoundError(ref)
+
+        if not self._fetch_ref(ref):
+            raise RefNotFoundError(ref)
+
+        # After `git fetch origin <ref>`, the content is reachable via
+        # FETCH_HEAD. We resolve through `origin/<ref>` when the remote
+        # tracking branch was updated, falling back to FETCH_HEAD directly.
+        remote_tracking_ref = f"origin/{ref}"
+        if self._ref_exists_locally(remote_tracking_ref):
+            return remote_tracking_ref
+
+        if self._ref_exists_locally("FETCH_HEAD"):
+            return "FETCH_HEAD"
+
+        raise RefNotFoundError(ref)
+
+    # ------------------------------------------------------------------
+    # File content fetching
+    # ------------------------------------------------------------------
+
+    def file_exists_at_ref(self, ref: str, filename: str) -> bool:
+        result = _run_git(["cat-file", "-e", f"{ref}:{filename}"], cwd=self.repo_path)
+        return result.returncode == 0
+
+    def get_file_content(self, ref: str, filename: str) -> str | None:
+        """
+        Return the content of `filename` as it existed at `ref`.
+
+        Returns None if the file did not exist at that ref (this is normal,
+        not an error — e.g. a dependency file added/removed between branches).
+
+        Raises:
+            GitError: an unexpected git failure unrelated to file absence.
+        """
+        result = _run_git(["show", f"{ref}:{filename}"], cwd=self.repo_path)
+
+        if result.returncode == 0:
+            return _decode_file_bytes(result.stdout_bytes)
+
+        stderr = result.stderr.strip().lower()
+        if "exists on disk, but not in" in stderr or "does not exist" in stderr or "fatal: path" in stderr:
+            logger.debug("'%s' not present at ref '%s'", filename, ref)
+            return None
+
+        # Any other failure is unexpected — surface as a clean GitError.
+        logger.debug("Unexpected git show failure for %s:%s — %s", ref, filename, result.stderr.strip())
+        raise GitError(f"Could not read '{filename}' at '{ref}'. The repository may be in an unexpected state.")
+
+    def fetch_files(
+        self,
+        ref: str,
+        filenames: tuple[str, ...] = TRACKED_FILES,
+        auto_fetch: bool = False,
+    ) -> dict[str, str | None]:
+        """
+        Resolve `ref` and return a mapping of filename -> content (or None
+        if absent at that ref) for every file diffenv tracks.
+
+        This is the single method the parser layer (Phase 3) depends on.
+        """
+        resolved_ref = self.resolve_ref(ref, auto_fetch=auto_fetch)
+        return {
+            filename: self.get_file_content(resolved_ref, filename)
+            for filename in filenames
+        }

diffenv/logging_config.py

@@ -0,0 +1,23 @@
+"""Logging setup for diffenv. Debug output goes to stderr; never pollutes stdout."""
+
+import logging
+import sys
+
+_LOG_FORMAT = "%(levelname)s [diffenv.%(module)s] %(message)s"
+
+
+def configure(verbose: bool = False) -> None:
+    """Call once at CLI entry-point to configure root logger."""
+    level = logging.DEBUG if verbose else logging.WARNING
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter(_LOG_FORMAT))
+    root = logging.getLogger("diffenv")
+    root.setLevel(level)
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.propagate = False
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a child logger namespaced under 'diffenv'."""
+    return logging.getLogger(f"diffenv.{name}")

diffenv/models.py

@@ -0,0 +1,107 @@
+"""
+Shared data models used across all layers (git, parser, diff, formatter).
+Using dataclasses for lightweight, type-checked value objects.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+# ---------------------------------------------------------------------------
+# Parsed data models
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Dependency:
+    """A single dependency entry (name + optional pinned version)."""
+
+    name: str
+    version: str | None = None  # None means unpinned / not present
+
+    def __str__(self) -> str:
+        if self.version:
+            return f"{self.name}=={self.version}"
+        return self.name
+
+
+@dataclass(frozen=True)
+class EnvVar:
+    """An environment variable key declared in .env.example."""
+
+    key: str
+
+
+@dataclass
+class ParsedSnapshot:
+    """Everything parsed from a single git ref."""
+
+    ref: str
+    dependencies: list[Dependency] = field(default_factory=list)
+    env_vars: list[EnvVar] = field(default_factory=list)
+    python_version: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Diff result models
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class DepChange:
+    """A single dependency change between two refs."""
+
+    name: str
+    old_present: bool        # was this dependency present at all in the old ref
+    new_present: bool        # is this dependency present at all in the new ref
+    old_version: str | None  # pinned version in old ref, or None if absent/unpinned
+    new_version: str | None  # pinned version in new ref, or None if absent/unpinned
+
+    @property
+    def is_added(self) -> bool:
+        return not self.old_present and self.new_present
+
+    @property
+    def is_removed(self) -> bool:
+        return self.old_present and not self.new_present
+
+    @property
+    def is_upgraded(self) -> bool:
+        return (
+            self.old_present
+            and self.new_present
+            and self.old_version != self.new_version
+        )
+
+
+@dataclass(frozen=True)
+class EnvVarChange:
+    """A single env-var change between two refs."""
+
+    key: str
+    is_added: bool  # True = appeared in new ref, False = removed from new ref
+
+
+@dataclass
+class DiffResult:
+    """Complete diff between two refs, ready for formatting."""
+
+    ref_old: str
+    ref_new: str
+    dep_changes: list[DepChange] = field(default_factory=list)
+    env_changes: list[EnvVarChange] = field(default_factory=list)
+    python_old: str | None = None
+    python_new: str | None = None
+
+    @property
+    def has_python_change(self) -> bool:
+        return self.python_old != self.python_new
+
+    @property
+    def is_empty(self) -> bool:
+        return (
+            not self.dep_changes
+            and not self.env_changes
+            and not self.has_python_change
+        )

diffenv/parser_layer.py

@@ -0,0 +1,257 @@
+"""
+Parser layer — turns raw file content (as strings) into the shared data
+models from `models.py`. Each file type has its own parser function; all
+parsers share the same signature so new file types can be added without
+touching existing code.
+
+Design: a registry (dict) maps filename -> parser function. `parse_snapshot`
+is the only function the rest of the app calls; it doesn't know or care how
+many parsers exist or what file types they handle.
+
+To add a new file type later:
+    1. Write a function: def parse_xxx(content: str) -> ...
+    2. Register it in _DEP_PARSERS, _ENV_PARSERS, or _PYTHON_VERSION_PARSERS
+       depending on what kind of data it contributes.
+That's the entire integration surface.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Callable
+
+from diffenv.exceptions import ParseError
+from diffenv.logging_config import get_logger
+from diffenv.models import Dependency, EnvVar, ParsedSnapshot
+
+logger = get_logger("parser_layer")
+
+# ---------------------------------------------------------------------------
+# requirements.txt
+# ---------------------------------------------------------------------------
+
+# Matches: name, optional extras [foo,bar], optional version spec (==, >=, etc.)
+_REQ_LINE_RE = re.compile(
+    r"^\s*([A-Za-z0-9][A-Za-z0-9._-]*)"   # package name
+    r"(?:\[[^\]]*\])?"                     # optional extras, ignored
+    r"\s*(==\s*([^\s;#]+))?"               # optional ==version (captured)
+    r"(?:[<>=!~].*)?"                      # any other version specifier, ignored for version capture
+)
+
+
+def parse_requirements_txt(content: str) -> list[Dependency]:
+    """
+    Parse a requirements.txt file into a list of Dependency objects.
+
+    Only `==` pins are treated as a known version; ranges like `>=1.0` or
+    unpinned entries are recorded with version=None, since diffenv reports
+    exact version changes, not range changes.
+
+    Lines that are comments, blank, -e/-r includes, or otherwise not a
+    simple requirement are skipped (logged at debug level, not an error —
+    requirements.txt has no strict spec, so being permissive here matters).
+    """
+    dependencies: list[Dependency] = []
+
+    for lineno, raw_line in enumerate(content.splitlines(), start=1):
+        line = raw_line.strip()
+
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith(("-e ", "-r ", "--", "-c ", "-f ", "-i ")):
+            logger.debug("requirements.txt line %d: skipping directive: %s", lineno, line)
+            continue
+
+        # Strip inline comments
+        line = line.split(" #", 1)[0].strip()
+        if not line:
+            continue
+
+        match = _REQ_LINE_RE.match(line)
+        if not match:
+            logger.debug("requirements.txt line %d: could not parse, skipping: %s", lineno, line)
+            continue
+
+        name = match.group(1)
+        version = match.group(3)  # None if not an == pin
+        dependencies.append(Dependency(name=name, version=version))
+
+    return dependencies
+
+
+# ---------------------------------------------------------------------------
+# pyproject.toml
+# ---------------------------------------------------------------------------
+
+
+def _load_toml(content: str, filename: str) -> dict:
+    try:
+        import tomllib  # Python 3.11+
+    except ModuleNotFoundError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+    try:
+        return tomllib.loads(content)
+    except Exception as exc:
+        raise ParseError(filename, f"invalid TOML syntax ({exc})") from exc
+
+
+# Matches a PEP 508 dependency string: name[extras]specifier
+_PEP508_RE = re.compile(
+    r"^\s*([A-Za-z0-9][A-Za-z0-9._-]*)"
+    r"(?:\[[^\]]*\])?"
+    r"\s*(==\s*([^\s;,]+))?"
+)
+
+
+def _parse_pep508_list(entries: list) -> list[Dependency]:
+    dependencies: list[Dependency] = []
+    for entry in entries:
+        if not isinstance(entry, str):
+            continue
+        match = _PEP508_RE.match(entry)
+        if not match:
+            logger.debug("pyproject.toml: could not parse dependency entry: %s", entry)
+            continue
+        dependencies.append(Dependency(name=match.group(1), version=match.group(3)))
+    return dependencies
+
+
+def parse_pyproject_toml(content: str) -> tuple[list[Dependency], str | None]:
+    """
+    Parse pyproject.toml for:
+        - [project.dependencies] (PEP 621 standard)
+        - [project.requires-python] -> used as a fallback Python version hint
+
+    Returns:
+        (dependencies, required_python_spec)
+
+    Notes:
+        - Poetry-style [tool.poetry.dependencies] is intentionally NOT parsed
+          in this phase to keep scope tight; requirements.txt and PEP 621
+          cover the common case. This is a natural extension point later.
+        - requires-python is a specifier (e.g. ">=3.10"), not an exact
+          version, so it's kept separate from .python-version's exact pin
+          and surfaced only when .python-version is absent.
+    """
+    data = _load_toml(content, "pyproject.toml")
+
+    project = data.get("project", {})
+    if not isinstance(project, dict):
+        raise ParseError("pyproject.toml", "'[project]' section is malformed")
+
+    raw_deps = project.get("dependencies", [])
+    if not isinstance(raw_deps, list):
+        raise ParseError("pyproject.toml", "'project.dependencies' must be a list")
+
+    dependencies = _parse_pep508_list(raw_deps)
+
+    requires_python = project.get("requires-python")
+    if requires_python is not None and not isinstance(requires_python, str):
+        requires_python = None
+
+    return dependencies, requires_python
+
+
+# ---------------------------------------------------------------------------
+# .env.example
+# ---------------------------------------------------------------------------
+
+_ENV_LINE_RE = re.compile(r"^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=")
+
+
+def parse_env_example(content: str) -> list[EnvVar]:
+    """
+    Parse a .env.example file into a list of declared env var keys.
+    Values are intentionally ignored — diffenv only cares whether a key
+    is declared, not what placeholder value it holds.
+    """
+    env_vars: list[EnvVar] = []
+    seen: set[str] = set()
+
+    for lineno, raw_line in enumerate(content.splitlines(), start=1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+
+        match = _ENV_LINE_RE.match(line)
+        if not match:
+            logger.debug(".env.example line %d: not a KEY=value line, skipping: %s", lineno, line)
+            continue
+
+        key = match.group(1)
+        if key in seen:
+            continue
+        seen.add(key)
+        env_vars.append(EnvVar(key=key))
+
+    return env_vars
+
+
+# ---------------------------------------------------------------------------
+# .python-version
+# ---------------------------------------------------------------------------
+
+
+def parse_python_version(content: str) -> str | None:
+    """
+    Parse a .python-version file (pyenv-style — a single version string,
+    optionally with trailing whitespace/newline, sometimes multiple lines
+    where only the first is the active version).
+    """
+    first_line = content.strip().splitlines()[0].strip() if content.strip() else ""
+    return first_line or None
+
+
+# ---------------------------------------------------------------------------
+# Snapshot assembly
+# ---------------------------------------------------------------------------
+
+
+def parse_snapshot(files: dict[str, str | None], ref: str) -> ParsedSnapshot:
+    """
+    Parse all tracked files fetched from a single git ref into one
+    ParsedSnapshot. Missing files (content=None) simply contribute nothing
+    — that's normal, not an error.
+
+    Args:
+        files: mapping of filename -> content (or None if absent at ref),
+               as produced by GitClient.fetch_files().
+        ref:   the ref these files were fetched from (for traceability).
+
+    Raises:
+        ParseError: a file was present but malformed (e.g. broken TOML).
+                    Parse failures are NOT silently swallowed — a broken
+                    pyproject.toml is real, actionable information for
+                    the user, distinct from a merely-absent file.
+    """
+    snapshot = ParsedSnapshot(ref=ref)
+
+    requirements_content = files.get("requirements.txt")
+    if requirements_content is not None:
+        snapshot.dependencies.extend(parse_requirements_txt(requirements_content))
+
+    pyproject_content = files.get("pyproject.toml")
+    pyproject_requires_python: str | None = None
+    if pyproject_content is not None:
+        pyproject_deps, pyproject_requires_python = parse_pyproject_toml(pyproject_content)
+        # Merge without duplicating a dependency already declared in requirements.txt
+        existing_names = {dep.name.lower() for dep in snapshot.dependencies}
+        for dep in pyproject_deps:
+            if dep.name.lower() not in existing_names:
+                snapshot.dependencies.append(dep)
+                existing_names.add(dep.name.lower())
+
+    env_content = files.get(".env.example")
+    if env_content is not None:
+        snapshot.env_vars.extend(parse_env_example(env_content))
+
+    python_version_content = files.get(".python-version")
+    if python_version_content is not None:
+        snapshot.python_version = parse_python_version(python_version_content)
+    elif pyproject_requires_python is not None:
+        # Fallback: no .python-version pin, but pyproject.toml declares a
+        # supported range — surface it so Python runtime info isn't silently lost.
+        snapshot.python_version = pyproject_requires_python
+
+    return snapshot