test_git_add.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_git/test_git_add.py
 
"""
Purpose
-------
Integration tests for ``oct git add`` (Phase 4G).
 
Responsibilities
----------------
- Verify whole-file staging stages the requested paths.
- Verify ``--update`` and ``--all`` behave like ``git add -u`` / ``-A``.
- Verify ``--dry-run`` does not modify the index.
- Verify ``--patch`` constructs the correct argv (passthrough is mocked).
- Verify mutual exclusivity rules.
- Verify JSON output schema.
- Verify the post-stage quality gate advisory.
 
Diagnostics
-----------
Domain: GIT-TESTS
Levels:
    L2 -- test lifecycle
    L3 -- assertion details
    L4 -- deep tracing
 
Contracts
---------
- All tests use subprocess invocation against ``oct.cli``.
- All tests use tmp_path fixtures so they are automatically cleaned up.
"""
 
import json
import shutil
import subprocess
import sys
from pathlib import Path
 
import pytest
 
from tests.tests_git.conftest import _git
 
 
def _git_available() -> bool:
    return shutil.which("git") is not None
 
 
def _run_add(root: Path, *extra_args: str) -> subprocess.CompletedProcess:
    """Run ``oct git add`` in a subprocess."""
    return subprocess.run(
        [sys.executable, "-m", "oct.cli", "git", "add", *extra_args],
        cwd=root,
        capture_output=True,
        text=True,
    )
 
 
def _staged_names(repo: Path) -> list[str]:
    """Return file names currently staged (index)."""
    result = subprocess.run(
        ["git", "diff", "--cached", "--name-only"],
        cwd=repo, check=True, capture_output=True, text=True,
    )
    return [
        line.strip() for line in result.stdout.splitlines() if line.strip()
    ]
 
 
# =====================================================================
# Whole-file staging
# =====================================================================
 
 
class TestAddSingleFile:
 
    @pytest.mark.skipif(not _git_available(), reason="git not on PATH")
    def test_stages_one_file(self, temp_git_project: Path) -> None:
        (temp_git_project / "src" / "a.py").write_text(
            "x = 1\n", encoding="utf-8",
        )
        result = _run_add(temp_git_project, "src/a.py")
        assert result.returncode == 0, result.stderr
        assert "src/a.py" in _staged_names(temp_git_project)
 
 
class TestAddMultipleFiles:
 
    @pytest.mark.skipif(not _git_available(), reason="git not on PATH")
    def test_stages_three_files(self, temp_git_project: Path) -> None:
        for name in ("a.py", "b.py", "c.py"):
            (temp_git_project / "src" / name).write_text(
                "x = 1\n", encoding="utf-8",
            )
        result = _run_add(
            temp_git_project, "src/a.py", "src/b.py", "src/c.py",
        )
        assert result.returncode == 0, result.stderr
        names = _staged_names(temp_git_project)
        for name in ("src/a.py", "src/b.py", "src/c.py"):
            assert name in names
 
 
class TestAddUpdate:
 
    @pytest.mark.skipif(not _git_available(), reason="git not on PATH")
    def test_update_only_stages_tracked(
        self, temp_git_project: Path,
    ) -> None:
        # Commit a tracked file first.
        (temp_git_project / "src" / "tracked.py").write_text(
            "x = 1\n", encoding="utf-8",
        )
        _git(temp_git_project, "add", "src/tracked.py")
        _git(temp_git_project, "commit", "-m", "add tracked", "--quiet")
 
        # Modify it.
        (temp_git_project / "src" / "tracked.py").write_text(
            "x = 2\n", encoding="utf-8",
        )
        # Add an untracked file.
        (temp_git_project / "src" / "untracked.py").write_text(
            "x = 3\n", encoding="utf-8",
        )
 
        result = _run_add(temp_git_project, "--update")
        assert result.returncode == 0, result.stderr
        names = _staged_names(temp_git_project)
        assert "src/tracked.py" in names
        assert "src/untracked.py" not in names
 
 
class TestAddAll:
 
    @pytest.mark.skipif(not _git_available(), reason="git not on PATH")
    def test_all_stages_untracked(self, temp_git_project: Path) -> None:
        (temp_git_project / "src" / "new.py").write_text(
            "x = 1\n", encoding="utf-8",
        )
        result = _run_add(temp_git_project, "--all")
        assert result.returncode == 0, result.stderr
        assert "src/new.py" in _staged_names(temp_git_project)
 
 
# =====================================================================
# Dry-run
# =====================================================================
 
 
class TestAddDryRun:
 
    @pytest.mark.skipif(not _git_available(), reason="git not on PATH")
    def test_dry_run_does_not_stage(self, temp_git_project: Path) -> None:
        (temp_git_project / "src" / "a.py").write_text(
            "x = 1\n", encoding="utf-8",
        )
        result = _run_add(temp_git_project, "--dry-run", "src/a.py")
        assert result.returncode == 0, result.stderr
        assert "Would stage" in result.stdout
        # Index should be empty.
        assert _staged_names(temp_git_project) == []
 
 
# =====================================================================
# Path scope
# =====================================================================
 
 
class TestAddOutsideProjectScope:
 
    @pytest.mark.skipif(not _git_available(), reason="git not on PATH")
    def test_outside_path_skipped_with_warning(
        self, temp_git_project: Path, tmp_path: Path,
    ) -> None:
        # Create a file *outside* the project root.
        outside = tmp_path / "outside.py"
        outside.write_text("x = 1\n", encoding="utf-8")
        result = _run_add(temp_git_project, str(outside))
        # All paths are skipped; nothing left to stage and no flags -> exit 1.
        assert result.returncode == 1
        assert "outside project scope" in result.stderr.lower()
 
 
# =====================================================================
# JSON
# =====================================================================
 
 
class TestAddJson:
 
    @pytest.mark.skipif(not _git_available(), reason="git not on PATH")
    def test_json_schema(self, temp_git_project: Path) -> None:
        (temp_git_project / "src" / "a.py").write_text(
            "x = 1\n", encoding="utf-8",
        )
        result = _run_add(temp_git_project, "--json", "src/a.py")
        assert result.returncode == 0, result.stderr
        data = json.loads(result.stdout)
        for key in ("operation", "paths_staged", "paths_skipped",
                    "post_check", "exit_code", "errors"):
            assert key in data, f"missing key: {key}"
        assert data["operation"] == "add"
        assert data["exit_code"] == 0
 
 
# =====================================================================
# Mutual exclusivity
# =====================================================================
 
 
class TestAddMutualExclusivity:
 
    @pytest.mark.skipif(not _git_available(), reason="git not on PATH")
    def test_patch_with_all_rejected(
        self, temp_git_project: Path,
    ) -> None:
        result = _run_add(temp_git_project, "--patch", "--all")
        assert result.returncode == 1
        assert "cannot be combined" in result.stderr.lower()
 
    @pytest.mark.skipif(not _git_available(), reason="git not on PATH")
    def test_update_with_all_rejected(
        self, temp_git_project: Path,
    ) -> None:
        result = _run_add(temp_git_project, "--update", "--all")
        assert result.returncode == 1
        assert "mutually exclusive" in result.stderr.lower()
 
 
# =====================================================================
# No-op safety
# =====================================================================
 
 
class TestAddNoOp:
 
    @pytest.mark.skipif(not _git_available(), reason="git not on PATH")
    def test_no_paths_no_flags_errors(
        self, temp_git_project: Path,
    ) -> None:
        result = _run_add(temp_git_project)
        assert result.returncode == 1
        assert "no paths to stage" in result.stderr.lower()
 
 
# =====================================================================
# L2: harmless git warnings should still exit 0
# =====================================================================
 
 
class TestAddIgnoredDirWarning:
 
    @pytest.mark.skipif(not _git_available(), reason="git not on PATH")
    def test_tracked_file_in_ignored_dir_exits_zero(
        self, temp_git_project: Path,
    ) -> None:
        # Track a file, then add the parent directory to .gitignore.
        # When we re-stage the tracked file, git emits the "ignored
        # path" warning and exits 1 — but the file IS staged.
        ignored_dir = temp_git_project / "src" / "build_artefacts"
        ignored_dir.mkdir(parents=True, exist_ok=True)
        f = ignored_dir / "tracked.txt"
        f.write_text("x\n", encoding="utf-8")
        _git(temp_git_project, "add", "src/build_artefacts/tracked.txt")
        _git(
            temp_git_project, "commit", "-m", "track artefact", "--quiet",
        )
 
        # Now mark the dir as ignored AND modify the tracked file.
        gitignore = temp_git_project / ".gitignore"
        existing = (
            gitignore.read_text(encoding="utf-8")
            if gitignore.is_file() else ""
        )
        gitignore.write_text(
            existing + "\nsrc/build_artefacts/\n",
            encoding="utf-8",
        )
        f.write_text("modified\n", encoding="utf-8")
 
        result = _run_add(
            temp_git_project, "src/build_artefacts/tracked.txt",
        )
        # L2: even though git warns, the file was staged -> exit 0.
        assert result.returncode == 0, (
            f"L2: expected exit 0 on staged-with-warning; "
            f"got {result.returncode}\nstderr: {result.stderr}"
        )
        # File should be staged (path, not basename).
        assert "src/build_artefacts/tracked.txt" in _staged_names(
            temp_git_project,
        )
 
 
# =====================================================================
# Audit trail
# =====================================================================
 
 
class TestAddAudit:
 
    @pytest.mark.skipif(not _git_available(), reason="git not on PATH")
    def test_audit_record_written(self, temp_git_project: Path) -> None:
        (temp_git_project / "src" / "a.py").write_text(
            "x = 1\n", encoding="utf-8",
        )
        result = _run_add(temp_git_project, "src/a.py")
        assert result.returncode == 0, result.stderr
 
        # Audit log should exist with at least one "oct git add" entry.
        audit_dir = temp_git_project / "logs"
        assert audit_dir.is_dir()
        audit_files = list(audit_dir.glob("git-audit-*.jsonl"))
        assert audit_files, "no audit file written"
 
        found = False
        for af in audit_files:
            for line in af.read_text(encoding="utf-8").splitlines():
                try:
                    rec = json.loads(line)
                except json.JSONDecodeError:
                    continue
                if rec.get("command") == "oct git add":
                    found = True
                    break
            if found:
                break
        assert found, "no 'oct git add' audit record found"