conftest.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_git/conftest.py
 
"""
Purpose
-------
Shared fixtures for the ``oct git`` integration tests (Phase 4B).
Provides pre-seeded git repositories with Option C project structure
so that ``oct git status`` and ``oct git check`` can be tested against
realistic scenarios.
 
Responsibilities
----------------
- ``temp_git_project``: a real git repo with minimal Option C structure.
- ``make_compliant_py``: factory writing a fully-compliant Python file.
- ``make_noncompliant_py``: factory writing a file with a chosen violation.
- ``commit_file``: helper to stage + commit a file.
 
Diagnostics
-----------
Domain: GIT-TESTS
Levels:
    L2 — fixture lifecycle
    L3 — fixture setup details
    L4 — deep tracing
 
Contracts
---------
- ``temp_git_project`` always returns a directory that is a real git
  working tree with ``user.name`` / ``user.email`` pre-configured and
  at least one commit (HEAD exists).
- All fixtures create files under ``tmp_path`` so they are automatically
  cleaned up by pytest.
"""
 
import json
import os
import shutil
import subprocess
import textwrap
from pathlib import Path
 
import pytest
 
 
# =====================================================================
# Low-level helpers
# =====================================================================
 
 
def _git_available() -> bool:
    return shutil.which("git") is not None
 
 
def _git(repo: Path, *args: str, check: bool = True) -> subprocess.CompletedProcess:
    """Run a git command inside *repo*."""
    return subprocess.run(
        ["git", *args],
        cwd=repo,
        check=check,
        capture_output=True,
        text=True,
    )
 
 
def commit_file(
    repo: Path, name: str, content: str, message: str = "add file",
) -> None:
    """Write a file, stage it, and commit it."""
    path = repo / name
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(content, encoding="utf-8")
    _git(repo, "add", name)
    _git(repo, "commit", "-m", message, "--quiet")
 
 
# =====================================================================
# Compliant / noncompliant file templates
# =====================================================================
 
 
_COMPLIANT_TEMPLATE = textwrap.dedent("""\
    #!/usr/bin/env python3
    # -*- coding: utf-8 -*-
    # {rel_path}
 
    \"\"\"
    Purpose
    -------
    Test module for quality gate validation.
 
    Responsibilities
    ----------------
    - Placeholder for Phase 4B integration tests.
 
    Diagnostics
    -----------
    Domain: TEST
    Levels:
        L1 — errors
        L2 — lifecycle
        L3 — details
        L4 — deep trace
 
    Contracts
    ---------
    - None.
    \"\"\"
 
    from oc_diagnostics import _dbg
 
    func = "placeholder"
    _dbg("TEST", func, "loaded", 2)
""")
 
 
_NONCOMPLIANT_MISSING_HEADER = textwrap.dedent("""\
    \"\"\"A module with no Option C header.\"\"\"
 
    x = 1
""")
 
 
_NONCOMPLIANT_MISSING_DOCSTRING = textwrap.dedent("""\
    #!/usr/bin/env python3
    # -*- coding: utf-8 -*-
    # test_project/src/bad_doc.py
 
    x = 1
""")
 
 
_NONCOMPLIANT_HARDCODED_SECRET = textwrap.dedent("""\
    #!/usr/bin/env python3
    # -*- coding: utf-8 -*-
    # test_project/src/has_secret.py
 
    \"\"\"
    Purpose
    -------
    Module that contains a hardcoded secret for testing.
 
    Responsibilities
    ----------------
    - None.
 
    Diagnostics
    -----------
    Domain: TEST
    Levels:
        L1 — errors
 
    Contracts
    ---------
    - None.
    \"\"\"
 
    password = "hunter2"
""")
 
 
_NONCOMPLIANT_FORMAT_ERROR = textwrap.dedent("""\
    #!/usr/bin/env python3
    # -*- coding: utf-8 -*-
    # WRONG_PROJECT/WRONG_PATH.py
 
    \"\"\"
    Purpose
    -------
    Module with wrong header path (format violation).
 
    Responsibilities
    ----------------
    - None.
 
    Diagnostics
    -----------
    Domain: TEST
    Levels:
        L1 — errors
 
    Contracts
    ---------
    - None.
    \"\"\"
 
    x = 1
""")
 
 
# =====================================================================
# Fixtures
# =====================================================================
 
 
@pytest.fixture
def temp_git_project(tmp_path: Path) -> Path:
    """Create a minimal Option C project inside a real git repo.
 
    Directory structure::
 
        <root>/
        ├── .octrc.json
        ├── debug_config.json
        ├── docs/
        │   └── ARCHITECTURE.md
        ├── logs/
        ├── oc_diagnostics/
        ├── src/
        └── tests/
 
    The repo has one initial commit so HEAD exists, and
    ``user.name``/``user.email`` are configured.
    """
    if not _git_available():
        pytest.skip("git binary not available on PATH")
 
    root = tmp_path / "project"
    root.mkdir()
 
    # Init git repo.
    _git(root, "init", "--quiet", "-b", "main")
    _git(root, "config", "user.email", "test@example.com")
    _git(root, "config", "user.name", "Test")
    _git(root, "config", "commit.gpgsign", "false")
 
    # Create project structure.
    (root / "src").mkdir()
    (root / "tests").mkdir()
    (root / "docs").mkdir()
    (root / "logs").mkdir()
    (root / "oc_diagnostics").mkdir()
 
    # .octrc.json with compact default.
    octrc = {
        "linter": {"profile": "compact"},
        "git": {"protected_branches": ["main", "master"]},
    }
    (root / ".octrc.json").write_text(
        json.dumps(octrc, indent=2), encoding="utf-8",
    )
 
    # debug_config.json stub.
    debug_cfg = {
        "domains": {
            "GIT": {"level": 1, "color": "cyan"},
            "TEST": {"level": 1, "color": "white"},
        },
    }
    (root / "debug_config.json").write_text(
        json.dumps(debug_cfg, indent=2), encoding="utf-8",
    )
 
    # docs/ARCHITECTURE.md stub.
    (root / "docs" / "ARCHITECTURE.md").write_text(
        "# Architecture\n\nStub for testing.\n", encoding="utf-8",
    )
 
    # pyproject.toml marker (needed for get_project_root).
    (root / "pyproject.toml").write_text(
        '[project]\nname = "test_project"\n', encoding="utf-8",
    )
 
    # Initial commit.
    _git(root, "add", "-A")
    _git(root, "commit", "-m", "initial: project structure", "--quiet")
 
    return root.resolve()
 
 
@pytest.fixture
def make_compliant_py(temp_git_project: Path):
    """Factory: write a compliant Python file and return its Path.
 
    Usage::
 
        path = make_compliant_py("src/good.py")
    """
    def _factory(rel_path: str) -> Path:
        content = _COMPLIANT_TEMPLATE.format(
            rel_path=rel_path,
        )
        full = temp_git_project / rel_path
        full.parent.mkdir(parents=True, exist_ok=True)
        full.write_text(content, encoding="utf-8")
 
        # Create companion test file so `tests_exist` check passes.
        # The linter looks for tests/test_<module>.py.
        module_name = full.stem  # e.g. "good" from "src/good.py"
        test_file = temp_git_project / "tests" / f"test_{module_name}.py"
        if not test_file.exists():
            test_file.write_text(
                f'"""Stub test for {module_name}."""\n\n'
                f'def test_{module_name}():\n    pass\n',
                encoding="utf-8",
            )
        return full
 
    return _factory
 
 
@pytest.fixture
def make_noncompliant_py(temp_git_project: Path):
    """Factory: write a noncompliant Python file with a chosen violation.
 
    Usage::
 
        path = make_noncompliant_py("src/bad.py", "missing_header")
 
    Supported violations:
    - ``"missing_header"``
    - ``"missing_docstring"``
    - ``"hardcoded_secret"``
    - ``"format_error"``
    """
    templates = {
        "missing_header": _NONCOMPLIANT_MISSING_HEADER,
        "missing_docstring": _NONCOMPLIANT_MISSING_DOCSTRING,
        "hardcoded_secret": _NONCOMPLIANT_HARDCODED_SECRET,
        "format_error": _NONCOMPLIANT_FORMAT_ERROR,
    }
 
    def _factory(rel_path: str, violation: str) -> Path:
        if violation not in templates:
            raise ValueError(
                f"Unknown violation {violation!r}; "
                f"choose from: {', '.join(templates)}"
            )
        content = templates[violation]
        full = temp_git_project / rel_path
        full.parent.mkdir(parents=True, exist_ok=True)
        full.write_text(content, encoding="utf-8")
        return full
 
    return _factory