test_run_scaffold.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_scaffold/test_run_scaffold.py
 
"""
Purpose
-------
OI-512 / FS-518 regression coverage — :func:`oct.scaffold.run_scaffold`
must materialise the full Option C project skeleton (directories, bundled
files, ``.gitignore`` / ``.octignore`` entries including ``.venv/``) and
behave idempotently (already-present paths land in ``skipped`` rather
than being overwritten). ``dry_run=True`` must be strictly side-effect
free.
 
The ``include_venv`` flag and its health-warning companion are covered
in :mod:`test_scaffold_venv`.
 
Responsibilities
----------------
- Verify full skeleton materialisation (directories and bundled files).
- Verify idempotent re-runs land existing paths in ``skipped``.
- Verify ``dry_run=True`` produces no filesystem side-effects.
 
Diagnostics
-----------
Domain: SCAFFOLD-TESTS
Levels:
    L2 — test lifecycle
    L3 — assertion details
    L4 — deep tracing
 
Contracts
---------
- ``dry_run=True`` → no filesystem changes; messages populated.
- All documented files appear in ``result.created`` on first run.
- A second ``run_scaffold`` call on the same directory creates nothing
  new and produces no duplicate-file errors.
"""
 
from __future__ import annotations
 
from pathlib import Path
 
import pytest
 
from oct.scaffold import ScaffoldResult, run_scaffold
 
 
def test_dry_run_creates_nothing(tmp_path: Path):
    """OI-512: dry_run emits plan messages and never touches the disk."""
    result = run_scaffold("demo", tmp_path, dry_run=True, include_venv=False)
    assert isinstance(result, ScaffoldResult)
    assert result.created == []
    assert not (tmp_path / "demo").exists()
    assert any("DRY RUN" in m for m in result.messages)
 
 
def test_scaffold_creates_core_directories(tmp_path: Path):
    """FS-539: docs/, tests/, .option_c/, .option_c/logs/ all appear."""
    result = run_scaffold("demo", tmp_path, include_venv=False)
    project = tmp_path / "demo"
    for sub in (
        "docs",
        "tests",
        ".option_c",
        ".option_c/logs",
        ".option_c/cache",
        "docs/_build",
    ):
        assert (project / sub).is_dir(), sub
    assert project in result.created or (project / "docs") in result.created
 
 
def test_scaffold_writes_debug_config_and_octrc(tmp_path: Path):
    """FS-539: debug_config + octrc land under .option_c/ with expected shape."""
    run_scaffold("demo", tmp_path, include_venv=False)
    project = tmp_path / "demo"
    debug_cfg = project / ".option_c" / "debug_config.json"
    octrc = project / ".option_c" / "octrc.json"
    assert debug_cfg.is_file()
    assert octrc.is_file()
    # Debug config must be the v2 schema.
    assert '"_schema_version": "2.0"' in debug_cfg.read_text(encoding="utf-8")
    assert '"sphinx_output"' in octrc.read_text(encoding="utf-8")
 
 
def test_scaffold_writes_gitignore_with_venv(tmp_path: Path):
    """FS-503 / FS-504: .gitignore and .octignore both include .venv/."""
    run_scaffold("demo", tmp_path, include_venv=False)
    project = tmp_path / "demo"
    gitignore = (project / ".gitignore").read_text(encoding="utf-8")
    octignore = (project / ".octignore").read_text(encoding="utf-8")
    assert ".venv/" in gitignore
    assert ".venv/" in octignore
    # Also covers the documented secret-filename entries.
    assert ".env" in gitignore
    assert "*.pem" in gitignore
 
 
def test_scaffold_is_idempotent(tmp_path: Path):
    """OI-512: a second run must skip everything, not overwrite."""
    first = run_scaffold("demo", tmp_path, include_venv=False)
    assert first.created  # first run creates many entries.
    second = run_scaffold("demo", tmp_path, include_venv=False)
    # Every core file from the first run is in ``skipped`` on the second.
    project = tmp_path / "demo"
    assert (project / ".option_c" / "octrc.json") in second.skipped
    assert (project / ".option_c" / "debug_config.json") in second.skipped
    assert (project / ".option_c" / "oc_status.json") in second.skipped
 
 
def test_scaffold_result_is_dataclass(tmp_path: Path):
    """OI-512: the return type must be a ScaffoldResult with the documented fields."""
    result = run_scaffold("demo", tmp_path, include_venv=False)
    assert hasattr(result, "created")
    assert hasattr(result, "skipped")
    assert hasattr(result, "messages")
    assert hasattr(result, "venv_path")
    # include_venv=False → venv_path stays None.
    assert result.venv_path is None