test_skeleton_exporter.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/tests/tests_tools/test_skeleton_exporter.py
 
"""
Purpose
-------
Tests for the skeleton exporter: core extraction, docstring stripping,
non-Python placeholders, and integration.
 
Responsibilities
----------------
- Verify extract_skeleton produces correct output for various Python patterns.
- Verify _strip_docstring_section removes targeted sections.
- Verify non-Python files produce one-line placeholders.
- Verify write_skeleton_file_for_dir and clean_skeleton_dirs work end-to-end.
 
Diagnostics
-----------
Domain: OCT-TEST
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- All tests are self-contained with no external dependencies beyond pytest.
"""
 
import textwrap
from pathlib import Path
 
import pytest
 
from oct.tools.skeleton_exporter import (
    extract_skeleton,
    _strip_docstring_section,
    _skeleton_for_non_python,
    write_skeleton_file_for_dir,
    clean_skeleton_dirs,
)
 
 
# ============================================================
# Test fixtures
# ============================================================
 
SIMPLE_MODULE = textwrap.dedent('''\
    #!/usr/bin/env python3
    # -*- coding: utf-8 -*-
    # myproject/simple.py
 
    """
    Purpose
    -------
    A simple module.
 
    Responsibilities
    ----------------
    - Do things.
 
    Diagnostics
    -----------
    Domain: TEST
    Levels:
        L2 — lifecycle
        L3 — details
        L4 — trace
 
    Contracts
    ---------
    Inputs: none
    Outputs: none
    """
 
    MAX_RETRIES = 3
 
    def hello(name: str) -> str:
        """Greet someone."""
        return f"Hello, {name}!"
 
    def _private(x):
        # internal helper
        for i in range(x):
            print(i)
        return x * 2
''')
 
CLASS_MODULE = textwrap.dedent('''\
    #!/usr/bin/env python3
    # -*- coding: utf-8 -*-
    # myproject/models.py
 
    """
    Purpose
    -------
    Models module.
 
    Responsibilities
    ----------------
    - Define models.
    """
 
    class Base:
        """Base class."""
 
        _REGISTRY = {}
 
        def save(self) -> None:
            """Persist to storage."""
            self._write_to_db()
            self._update_cache()
 
    class User(Base, metaclass=type):
        """User model."""
 
        @property
        def name(self) -> str:
            """The user name."""
            return self._name
 
        @staticmethod
        def create(data: dict) -> "User":
            """Factory method."""
            u = User()
            u._name = data["name"]
            return u
 
        class Meta:
            """Inner meta class."""
            table_name = "users"
''')
 
ASYNC_MODULE = textwrap.dedent('''\
    #!/usr/bin/env python3
    # -*- coding: utf-8 -*-
    # myproject/async_mod.py
 
    async def fetch(url: str, *, timeout: int = 30) -> bytes:
        """Fetch data from URL."""
        async with session.get(url, timeout=timeout) as resp:
            return await resp.read()
''')
 
DECORATOR_MODULE = textwrap.dedent('''\
    #!/usr/bin/env python3
    # -*- coding: utf-8 -*-
    # myproject/routes.py
 
    @app.route("/api/v1", methods=["GET", "POST"])
    def api_handler(request):
        """Handle API requests."""
        return process(request)
''')
 
 
# ============================================================
# TestExtractSkeleton
# ============================================================
 
class TestExtractSkeleton:
    """Unit tests for extract_skeleton()."""
 
    def test_header_always_present(self):
        skeleton = extract_skeleton(SIMPLE_MODULE, "myproject/simple.py")
        assert "#!/usr/bin/env python3" in skeleton
        assert "# -*- coding: utf-8 -*-" in skeleton
        assert "# myproject/simple.py" in skeleton
 
    def test_module_docstring_included(self):
        skeleton = extract_skeleton(SIMPLE_MODULE, "myproject/simple.py")
        assert "Purpose" in skeleton
        assert "A simple module." in skeleton
 
    def test_no_diagnostics_strips_section(self):
        skeleton = extract_skeleton(SIMPLE_MODULE, "myproject/simple.py",
                                    no_diagnostics=True)
        assert "Purpose" in skeleton
        assert "Responsibilities" in skeleton
        assert "Domain: TEST" not in skeleton
        assert "L2" not in skeleton
 
    def test_no_diagnostics_keeps_other_sections(self):
        skeleton = extract_skeleton(SIMPLE_MODULE, "myproject/simple.py",
                                    no_diagnostics=True)
        assert "Contracts" in skeleton
        assert "Inputs: none" in skeleton
 
    def test_function_signatures_preserved(self):
        skeleton = extract_skeleton(SIMPLE_MODULE, "myproject/simple.py")
        assert "def hello(name: str) -> str:" in skeleton
        assert "def _private(x):" in skeleton
 
    def test_function_docstrings_preserved(self):
        skeleton = extract_skeleton(SIMPLE_MODULE, "myproject/simple.py")
        assert "Greet someone." in skeleton
 
    def test_no_implementation_bodies(self):
        skeleton = extract_skeleton(SIMPLE_MODULE, "myproject/simple.py")
        assert 'f"Hello, {name}!"' not in skeleton
        assert "range(x)" not in skeleton
        assert "print(i)" not in skeleton
        assert "return x * 2" not in skeleton
 
    def test_constants_included(self):
        skeleton = extract_skeleton(SIMPLE_MODULE, "myproject/simple.py")
        assert "MAX_RETRIES = ..." in skeleton
 
    def test_class_with_methods(self):
        skeleton = extract_skeleton(CLASS_MODULE, "myproject/models.py")
        assert "class Base:" in skeleton
        assert "class User(Base, metaclass=type):" in skeleton
        assert "def save(self) -> None:" in skeleton
        assert "User model." in skeleton
 
    def test_decorators_preserved(self):
        skeleton = extract_skeleton(CLASS_MODULE, "myproject/models.py")
        assert "@property" in skeleton
        assert "@staticmethod" in skeleton
 
    def test_complex_decorator(self):
        skeleton = extract_skeleton(DECORATOR_MODULE, "myproject/routes.py")
        # ast.unparse may use single quotes; check structural content
        assert "@app.route(" in skeleton
        assert "methods=" in skeleton
 
    def test_async_function(self):
        skeleton = extract_skeleton(ASYNC_MODULE, "myproject/async_mod.py")
        # ast.unparse may collapse spaces around = in defaults
        assert "async def fetch(" in skeleton
        assert "url: str" in skeleton
        assert "timeout: int" in skeleton
        assert "-> bytes:" in skeleton
 
    def test_nested_class(self):
        skeleton = extract_skeleton(CLASS_MODULE, "myproject/models.py")
        assert "class Meta:" in skeleton
        assert "Inner meta class." in skeleton
 
    def test_class_body_not_leaked(self):
        skeleton = extract_skeleton(CLASS_MODULE, "myproject/models.py")
        assert "_write_to_db" not in skeleton
        assert "_update_cache" not in skeleton
 
    def test_syntax_error_file(self):
        bad_code = "#!/usr/bin/env python3\n# -*- coding: utf-8 -*-\n# bad.py\ndef ("
        skeleton = extract_skeleton(bad_code, "bad.py")
        assert "#!/usr/bin/env python3" in skeleton
        assert "syntax error" in skeleton.lower()
 
    def test_empty_file(self):
        skeleton = extract_skeleton("", "empty.py")
        assert skeleton.strip() == ""
 
    def test_ellipsis_body_placeholder(self):
        skeleton = extract_skeleton(SIMPLE_MODULE, "myproject/simple.py")
        assert "    ..." in skeleton
 
 
# ============================================================
# TestStripDocstringSection
# ============================================================
 
class TestStripDocstringSection:
    """Unit tests for _strip_docstring_section."""
 
    DOCSTRING = textwrap.dedent("""\
        Purpose
        -------
        Do stuff.
 
        Responsibilities
        ----------------
        - Thing one.
 
        Diagnostics
        -----------
        Domain: TEST
        L2: summary
 
        Contracts
        ---------
        Inputs: none
    """)
 
    def test_strip_diagnostics(self):
        result = _strip_docstring_section(self.DOCSTRING, "Diagnostics")
        assert "Purpose" in result
        assert "Responsibilities" in result
        assert "Domain: TEST" not in result
        assert "Contracts" in result
 
    def test_strip_contracts(self):
        result = _strip_docstring_section(self.DOCSTRING, "Contracts")
        assert "Diagnostics" in result
        assert "Inputs: none" not in result
 
    def test_no_match_returns_unchanged(self):
        result = _strip_docstring_section(self.DOCSTRING, "NonExistent")
        assert "Purpose" in result
        assert "Diagnostics" in result
        assert "Contracts" in result
 
    def test_strip_middle_section(self):
        result = _strip_docstring_section(self.DOCSTRING, "Responsibilities")
        assert "Purpose" in result
        assert "Thing one." not in result
        assert "Diagnostics" in result
 
    def test_strip_section_with_numeric_header(self):
        """OI-415: section headers starting with digits must be handled."""
        docstring = textwrap.dedent("""\
            Purpose
            -------
            Stuff.
 
            Layer 3
            -------
            Low-level notes.
 
            Contracts
            ---------
            Inputs: none
        """)
        # Ensure the 'Layer 3' section terminates correctly (\S matching)
        result = _strip_docstring_section(docstring, "Purpose")
        assert "Stuff." not in result
        assert "Layer 3" in result
        assert "Contracts" in result
 
    def test_strip_section_terminated_by_unicode_header(self):
        """OI-415: non-ASCII section headers must still terminate matching."""
        docstring = textwrap.dedent("""\
            Purpose
            -------
            Do stuff.
 
            Résumé
            ------
            Summary line.
 
            Contracts
            ---------
            Inputs: none
        """)
        result = _strip_docstring_section(docstring, "Purpose")
        assert "Do stuff." not in result
        assert "Résumé" in result
        assert "Summary line." in result
 
    def test_strip_section_with_trailing_whitespace_on_header(self):
        """OI-415: headers with trailing whitespace should still be matched."""
        docstring = (
            "Purpose\n"
            "-------\n"
            "Do stuff.\n"
            "\n"
            "Diagnostics   \n"
            "-----------\n"
            "Domain: TEST\n"
            "\n"
            "Contracts\n"
            "---------\n"
            "Inputs: none\n"
        )
        result = _strip_docstring_section(docstring, "Diagnostics")
        assert "Domain: TEST" not in result
        assert "Purpose" in result
        assert "Contracts" in result
 
 
# ============================================================
# TestNonPythonSkeleton
# ============================================================
 
class TestNonPythonSkeleton:
    """Tests for non-Python file placeholder output."""
 
    def test_json_placeholder(self, tmp_path):
        f = tmp_path / "config.json"
        f.write_text('{"key": "value"}\n', encoding="utf-8")
        result = _skeleton_for_non_python(f)
        assert "config.json" in result
        assert "line" in result
        assert "KB" in result
 
    def test_markdown_placeholder(self, tmp_path):
        f = tmp_path / "README.md"
        f.write_text("# Title\n\nSome content.\n", encoding="utf-8")
        result = _skeleton_for_non_python(f)
        assert "README.md" in result
        assert "KB" in result
 
 
# ============================================================
# TestSkeletonIntegration
# ============================================================
 
class TestSkeletonIntegration:
    """Integration tests using write_skeleton_file_for_dir and clean."""
 
    @pytest.fixture
    def project(self, tmp_path):
        """Create a minimal project structure."""
        src = tmp_path / "myproject"
        src.mkdir()
        (src / "docs").mkdir()
        (src / "tests").mkdir()
        (src / "oc_diagnostics").mkdir()
 
        py_file = src / "main.py"
        py_file.write_text(textwrap.dedent('''\
            #!/usr/bin/env python3
            # -*- coding: utf-8 -*-
            # myproject/main.py
 
            def run():
                """Start the app."""
                print("running")
        '''), encoding="utf-8")
 
        json_file = src / "config.json"
        json_file.write_text('{"debug": true}\n', encoding="utf-8")
 
        return src
 
    def test_writes_output_file(self, project, tmp_path):
        cfg = {
            "include_extensions": [".py", ".json"],
            "exclude_dirs": set(),
            "wildcard_exclude_dirs": [],
            "header_text": "SKELETON\n",
            "separator_file": "--- {num}: {path}\n",
            "separator_subdir": "=== {num}: {dirname}\n",
            "root_header": "ROOT\n",
            "max_safe_path_len": 240,
        }
        out = tmp_path / "output.txt"
        count, *_ = write_skeleton_file_for_dir(project, out, project, cfg)
        assert count > 0
        content = out.read_text(encoding="utf-8")
        assert "def run():" in content
        assert "config.json" in content
        # No implementation body
        assert 'print("running")' not in content
 
    def test_clean_removes_skeleton_dirs(self, project):
        skel_dir = project / "_skeleton_code-20260408-1500"
        skel_dir.mkdir()
        (skel_dir / "test.txt").write_text("test", encoding="utf-8")
 
        clean_skeleton_dirs(project)
 
        assert not skel_dir.exists()
 
    def test_exclusions_respected(self, project, tmp_path):
        # Create an excluded dir and a secret file
        venv = project / ".git"
        venv.mkdir()
        (venv / "config").write_text("secret", encoding="utf-8")
 
        env_file = project / ".env"
        env_file.write_text("SECRET=abc", encoding="utf-8")
 
        cfg = {
            "include_extensions": [".py", ".json", ".env"],
            "exclude_dirs": {".git"},
            "wildcard_exclude_dirs": [],
            "header_text": "SKELETON\n",
            "separator_file": "--- {num}: {path}\n",
            "separator_subdir": "=== {num}: {dirname}\n",
            "root_header": "ROOT\n",
            "max_safe_path_len": 240,
        }
        out = tmp_path / "output.txt"
        write_skeleton_file_for_dir(project, out, project, cfg)
        content = out.read_text(encoding="utf-8")
        assert ".git" not in content
        assert ".env" not in content
        assert "SECRET=abc" not in content