code-graph-builder 0.2.0__py3-none-any.whl

code_graph_builder/tests/test_step1_graph_build.py

@@ -0,0 +1,264 @@
+"""Step 1 integration test: graph-build on tinycc repository.
+
+Builds a knowledge graph from the real tinycc C compiler source code,
+then validates that nodes, relationships, and C-specific properties
+(signatures, visibility, docstrings, macros, structs) are correctly extracted.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+TINYCC_PATH = Path(__file__).resolve().parents[3] / "tinycc"
+
+# Skip entire module if tinycc source is not available
+pytestmark = pytest.mark.skipif(
+    not TINYCC_PATH.exists(),
+    reason=f"tinycc source not found at {TINYCC_PATH}",
+)
+
+
+@pytest.fixture(scope="module")
+def builder(tmp_path_factory):
+    """Build the tinycc graph once for all tests in this module."""
+    from code_graph_builder.mcp.pipeline import build_graph
+
+    db_path = tmp_path_factory.mktemp("graph") / "graph.db"
+    b = build_graph(
+        repo_path=TINYCC_PATH,
+        db_path=db_path,
+        rebuild=True,
+        backend="kuzu",
+    )
+    yield b
+    if hasattr(b, "close"):
+        b.close()
+
+
+# ---------------------------------------------------------------------------
+# Basic graph structure
+# ---------------------------------------------------------------------------
+
+
+class TestGraphStructure:
+    """Verify the graph has expected node and relationship counts."""
+
+    def test_has_modules(self, builder):
+        rows = builder.query("MATCH (m:Module) RETURN count(m) AS cnt")
+        cnt = list(rows[0].values())[0] if rows else 0
+        assert cnt > 0, "Graph should have Module nodes"
+
+    def test_has_functions(self, builder):
+        rows = builder.query("MATCH (f:Function) RETURN count(f) AS cnt")
+        cnt = list(rows[0].values())[0] if rows else 0
+        assert cnt > 50, f"Expected many functions in tinycc, got {cnt}"
+
+    def test_has_calls(self, builder):
+        rows = builder.query("MATCH ()-[r:CALLS]->() RETURN count(r) AS cnt")
+        cnt = list(rows[0].values())[0] if rows else 0
+        assert cnt > 50, f"Expected many CALLS relationships, got {cnt}"
+
+    def test_has_defines(self, builder):
+        rows = builder.query("MATCH ()-[r:DEFINES]->() RETURN count(r) AS cnt")
+        cnt = list(rows[0].values())[0] if rows else 0
+        assert cnt > 0, "Graph should have DEFINES relationships"
+
+    def test_has_classes_or_types(self, builder):
+        """tinycc has structs, enums — should appear as Class or Type nodes."""
+        rows = builder.query(
+            "MATCH (c:Class) RETURN count(c) AS cnt"
+        )
+        cnt = list(rows[0].values())[0] if rows else 0
+        assert cnt > 0, "tinycc should have struct/enum/union Class nodes"
+
+
+# ---------------------------------------------------------------------------
+# C-specific property extraction
+# ---------------------------------------------------------------------------
+
+
+class TestCProperties:
+    """Verify C-specific properties are extracted correctly."""
+
+    def test_function_has_signature(self, builder):
+        """At least some functions should have non-empty signatures."""
+        rows = builder.query(
+            "MATCH (f:Function) WHERE f.signature IS NOT NULL AND f.signature <> '' "
+            "RETURN count(f) AS cnt"
+        )
+        cnt = list(rows[0].values())[0] if rows else 0
+        assert cnt > 10, f"Expected functions with signatures, got {cnt}"
+
+    def test_function_has_return_type(self, builder):
+        rows = builder.query(
+            "MATCH (f:Function) WHERE f.return_type IS NOT NULL AND f.return_type <> '' "
+            "RETURN count(f) AS cnt"
+        )
+        cnt = list(rows[0].values())[0] if rows else 0
+        assert cnt > 10, f"Expected functions with return types, got {cnt}"
+
+    def test_function_has_visibility(self, builder):
+        """Functions should have public/static/extern visibility."""
+        rows = builder.query(
+            "MATCH (f:Function) WHERE f.visibility IN ['public', 'static', 'extern'] "
+            "RETURN f.visibility AS vis, count(f) AS cnt "
+            "ORDER BY cnt DESC"
+        )
+        assert len(rows) > 0, "Expected functions with visibility"
+        vis_types = {r["vis"] for r in rows}
+        assert "static" in vis_types, "tinycc should have static functions"
+
+    def test_static_functions_exist(self, builder):
+        """tinycc has many static helper functions."""
+        rows = builder.query(
+            "MATCH (f:Function) WHERE f.visibility = 'static' RETURN count(f) AS cnt"
+        )
+        cnt = list(rows[0].values())[0] if rows else 0
+        assert cnt > 20, f"Expected many static functions, got {cnt}"
+
+    def test_public_functions_exist(self, builder):
+        """Functions declared in .h files should be public."""
+        rows = builder.query(
+            "MATCH (f:Function) WHERE f.visibility = 'public' RETURN count(f) AS cnt"
+        )
+        cnt = list(rows[0].values())[0] if rows else 0
+        assert cnt > 0, f"Expected public functions from headers, got {cnt}"
+
+
+# ---------------------------------------------------------------------------
+# Comment/docstring extraction (P0 feature)
+# ---------------------------------------------------------------------------
+
+
+class TestDocstringExtraction:
+    """Verify C comments above functions are extracted as docstrings."""
+
+    def test_some_functions_have_docstrings(self, builder):
+        """tinycc has comments above many functions — some should be captured."""
+        rows = builder.query(
+            "MATCH (f:Function) WHERE f.docstring IS NOT NULL AND f.docstring <> '' "
+            "RETURN count(f) AS cnt"
+        )
+        cnt = list(rows[0].values())[0] if rows else 0
+        assert cnt > 0, "Expected some functions with extracted C comments as docstrings"
+
+    def test_docstring_not_decorative(self, builder):
+        """Extracted docstrings should not be purely decorative (e.g., '---')."""
+        rows = builder.query(
+            "MATCH (f:Function) WHERE f.docstring IS NOT NULL AND f.docstring <> '' "
+            "RETURN f.docstring AS doc LIMIT 20"
+        )
+        for r in rows:
+            doc = r["doc"]
+            # Should contain actual words, not just dashes/stars
+            assert any(c.isalpha() for c in doc), f"Decorative docstring leaked: {doc!r}"
+
+
+# ---------------------------------------------------------------------------
+# Macro extraction
+# ---------------------------------------------------------------------------
+
+
+class TestMacroExtraction:
+    """Verify #define macros are extracted as Function nodes with kind='macro'."""
+
+    def test_macros_exist(self, builder):
+        rows = builder.query(
+            "MATCH (f:Function) WHERE f.kind = 'macro' RETURN count(f) AS cnt"
+        )
+        cnt = list(rows[0].values())[0] if rows else 0
+        assert cnt > 0, "tinycc should have macro definitions"
+
+    def test_macro_has_signature(self, builder):
+        """Macro signature should contain the #define text."""
+        rows = builder.query(
+            "MATCH (f:Function) WHERE f.kind = 'macro' AND f.signature IS NOT NULL "
+            "RETURN f.name AS name, f.signature AS sig LIMIT 5"
+        )
+        assert len(rows) > 0
+        for r in rows:
+            assert r["name"], "Macro should have a name"
+
+
+# ---------------------------------------------------------------------------
+# Struct/Enum extraction
+# ---------------------------------------------------------------------------
+
+
+class TestTypeExtraction:
+    """Verify struct/enum/union are extracted as Class nodes."""
+
+    def test_structs_exist(self, builder):
+        rows = builder.query(
+            "MATCH (c:Class) WHERE c.kind = 'struct' RETURN count(c) AS cnt"
+        )
+        cnt = list(rows[0].values())[0] if rows else 0
+        assert cnt > 0, "tinycc should have struct definitions"
+
+    def test_enums_exist(self, builder):
+        rows = builder.query(
+            "MATCH (c:Class) WHERE c.kind = 'enum' RETURN count(c) AS cnt"
+        )
+        cnt = list(rows[0].values())[0] if rows else 0
+        # tinycc may or may not have named enums, so just check >= 0
+        assert cnt >= 0
+
+    def test_class_has_kind(self, builder):
+        """All Class nodes should have a kind property (struct/enum/union)."""
+        rows = builder.query(
+            "MATCH (c:Class) WHERE c.kind IS NOT NULL RETURN DISTINCT c.kind AS kind"
+        )
+        kinds = {r["kind"] for r in rows}
+        assert len(kinds) > 0, "Class nodes should have kind property"
+
+
+# ---------------------------------------------------------------------------
+# Module-Function relationships
+# ---------------------------------------------------------------------------
+
+
+class TestRelationships:
+    """Verify graph relationships are correct."""
+
+    def test_most_functions_have_module(self, builder):
+        """Most functions extracted from source should have a parent module.
+
+        Note: CALLS edges can create Function stubs without DEFINES.
+        We check that the ratio of defined functions is high.
+        """
+        total = builder.query("MATCH (f:Function) RETURN count(f) AS cnt")
+        defined = builder.query(
+            "MATCH (m:Module)-[:DEFINES]->(f:Function) RETURN count(f) AS cnt"
+        )
+        total_cnt = list(total[0].values())[0] if total else 0
+        defined_cnt = list(defined[0].values())[0] if defined else 0
+        assert defined_cnt > 100, f"Expected many defined functions, got {defined_cnt}"
+        ratio = defined_cnt / total_cnt if total_cnt > 0 else 0
+        assert ratio > 0.05, f"Only {ratio:.1%} functions have parent module"
+
+    def test_calls_have_valid_endpoints(self, builder):
+        """CALLS relationships should connect existing functions."""
+        rows = builder.query(
+            "MATCH (a:Function)-[:CALLS]->(b:Function) "
+            "RETURN a.qualified_name AS caller, b.qualified_name AS callee "
+            "LIMIT 5"
+        )
+        assert len(rows) > 0
+        for r in rows:
+            assert r["caller"], "Caller should have qualified_name"
+            assert r["callee"], "Callee should have qualified_name"
+
+    def test_known_function_exists(self, builder):
+        """tinycc's main entry point 'tcc_main' should exist."""
+        rows = builder.query(
+            "MATCH (f:Function) WHERE f.name = 'tcc_main' RETURN f.qualified_name AS qn"
+        )
+        # tcc_main might be named differently, so just check it's queryable
+        # If not found, check for 'main' instead
+        if not rows:
+            rows = builder.query(
+                "MATCH (f:Function) WHERE f.name = 'main' RETURN f.qualified_name AS qn"
+            )
+        assert len(rows) > 0, "Should find tcc_main or main function"

code_graph_builder/tests/test_step2_api_docs.py

@@ -0,0 +1,323 @@
+"""Step 2 integration test: API docs generation from tinycc graph.
+
+Reuses the graph built in Step 1, generates L1/L2/L3 API documentation,
+and validates file structure, content format, and C-specific features.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+TINYCC_PATH = Path(__file__).resolve().parents[3] / "tinycc"
+
+pytestmark = pytest.mark.skipif(
+    not TINYCC_PATH.exists(),
+    reason=f"tinycc source not found at {TINYCC_PATH}",
+)
+
+
+@pytest.fixture(scope="module")
+def builder(tmp_path_factory):
+    """Build the tinycc graph once for all tests."""
+    from code_graph_builder.mcp.pipeline import build_graph
+
+    db_path = tmp_path_factory.mktemp("graph") / "graph.db"
+    b = build_graph(
+        repo_path=TINYCC_PATH,
+        db_path=db_path,
+        rebuild=True,
+        backend="kuzu",
+    )
+    yield b
+    if hasattr(b, "close"):
+        b.close()
+
+
+@pytest.fixture(scope="module")
+def api_docs_dir(builder, tmp_path_factory):
+    """Generate API docs and return the output directory."""
+    from code_graph_builder.mcp.pipeline import generate_api_docs_step
+
+    artifact_dir = tmp_path_factory.mktemp("artifacts")
+    result = generate_api_docs_step(
+        builder=builder,
+        artifact_dir=artifact_dir,
+        rebuild=True,
+    )
+    assert result["status"] == "success", f"API doc generation failed: {result}"
+    return artifact_dir / "api_docs", result
+
+
+# ---------------------------------------------------------------------------
+# File structure
+# ---------------------------------------------------------------------------
+
+
+class TestFileStructure:
+    """Verify the three-level doc hierarchy is generated."""
+
+    def test_index_exists(self, api_docs_dir):
+        docs_dir, _ = api_docs_dir
+        assert (docs_dir / "index.md").exists()
+
+    def test_modules_dir_exists(self, api_docs_dir):
+        docs_dir, _ = api_docs_dir
+        assert (docs_dir / "modules").is_dir()
+
+    def test_funcs_dir_exists(self, api_docs_dir):
+        docs_dir, _ = api_docs_dir
+        assert (docs_dir / "funcs").is_dir()
+
+    def test_module_files_generated(self, api_docs_dir):
+        docs_dir, _ = api_docs_dir
+        module_files = list((docs_dir / "modules").glob("*.md"))
+        assert len(module_files) > 0, "Should generate module pages"
+
+    def test_func_files_generated(self, api_docs_dir):
+        docs_dir, _ = api_docs_dir
+        func_files = list((docs_dir / "funcs").glob("*.md"))
+        assert len(func_files) > 50, f"Expected many func pages, got {len(func_files)}"
+
+    def test_result_counts(self, api_docs_dir):
+        _, result = api_docs_dir
+        assert result["module_count"] > 0
+        assert result["func_count"] > 50
+        assert result["type_count"] >= 0
+
+
+# ---------------------------------------------------------------------------
+# L1 index content
+# ---------------------------------------------------------------------------
+
+
+class TestL1Index:
+    """Verify the global index page content."""
+
+    def test_has_title(self, api_docs_dir):
+        docs_dir, _ = api_docs_dir
+        content = (docs_dir / "index.md").read_text(encoding="utf-8")
+        assert "# API Documentation Index" in content
+
+    def test_has_module_table(self, api_docs_dir):
+        docs_dir, _ = api_docs_dir
+        content = (docs_dir / "index.md").read_text(encoding="utf-8")
+        assert "| 模块" in content or "| Module" in content
+
+    def test_has_total_counts(self, api_docs_dir):
+        docs_dir, _ = api_docs_dir
+        content = (docs_dir / "index.md").read_text(encoding="utf-8")
+        assert "modules" in content.lower() or "模块" in content
+
+    def test_module_links(self, api_docs_dir):
+        docs_dir, _ = api_docs_dir
+        content = (docs_dir / "index.md").read_text(encoding="utf-8")
+        assert "modules/" in content, "Index should link to module pages"
+
+
+# ---------------------------------------------------------------------------
+# L2 module page content
+# ---------------------------------------------------------------------------
+
+
+class TestL2ModulePage:
+    """Verify module-level documentation pages."""
+
+    def _get_any_module_page(self, api_docs_dir):
+        docs_dir, _ = api_docs_dir
+        pages = list((docs_dir / "modules").glob("*.md"))
+        assert len(pages) > 0
+        return pages[0].read_text(encoding="utf-8"), pages[0].name
+
+    def test_has_title(self, api_docs_dir):
+        content, _ = self._get_any_module_page(api_docs_dir)
+        assert content.startswith("# ")
+
+    def test_has_file_info(self, api_docs_dir):
+        content, _ = self._get_any_module_page(api_docs_dir)
+        # Should mention header or implementation files
+        assert "文件" in content or "头文件" in content or "Files" in content or ".c" in content
+
+    def test_has_function_table(self, api_docs_dir):
+        content, _ = self._get_any_module_page(api_docs_dir)
+        # Should have a table with function signatures
+        assert "|" in content, "Module page should have tables"
+
+    def test_links_to_func_pages(self, api_docs_dir):
+        """At least some module pages should link to function detail pages."""
+        docs_dir, _ = api_docs_dir
+        for page in (docs_dir / "modules").glob("*.md"):
+            content = page.read_text(encoding="utf-8")
+            if "../funcs/" in content:
+                return
+        pytest.fail("No module page links to function detail pages")
+
+    def test_visibility_sections(self, api_docs_dir):
+        """At least some module pages should have visibility-related content."""
+        docs_dir, _ = api_docs_dir
+        found = False
+        for page in (docs_dir / "modules").glob("*.md"):
+            content = page.read_text(encoding="utf-8")
+            if any(kw in content for kw in [
+                "公开接口", "内部函数", "外部声明", "其他",
+                "Public", "Static", "Extern",
+                "## 宏",  # macro section is also a visibility grouping
+            ]):
+                found = True
+                break
+        assert found, "At least one module page should have visibility/type sections"
+
+
+# ---------------------------------------------------------------------------
+# L3 function detail page content
+# ---------------------------------------------------------------------------
+
+
+class TestL3FuncDetail:
+    """Verify function detail documentation pages."""
+
+    def _get_func_page_with_content(self, api_docs_dir):
+        """Find a function page that has substantial content."""
+        docs_dir, _ = api_docs_dir
+        for page in sorted((docs_dir / "funcs").glob("*.md")):
+            content = page.read_text(encoding="utf-8")
+            if len(content) > 200:  # Skip near-empty pages
+                return content, page.name
+        pytest.fail("No substantial function pages found")
+
+    def test_has_title(self, api_docs_dir):
+        content, _ = self._get_func_page_with_content(api_docs_dir)
+        assert content.startswith("# ")
+
+    def test_has_signature(self, api_docs_dir):
+        content, _ = self._get_func_page_with_content(api_docs_dir)
+        assert "签名" in content or "定义" in content or "Signature" in content
+
+    def test_has_visibility(self, api_docs_dir):
+        content, _ = self._get_func_page_with_content(api_docs_dir)
+        assert "可见性" in content or "Visibility" in content
+
+    def test_has_location(self, api_docs_dir):
+        content, _ = self._get_func_page_with_content(api_docs_dir)
+        assert "位置" in content or "Location" in content
+
+    def test_has_module_reference(self, api_docs_dir):
+        content, _ = self._get_func_page_with_content(api_docs_dir)
+        assert "模块" in content or "Module" in content
+
+    def test_has_called_by_section(self, api_docs_dir):
+        content, _ = self._get_func_page_with_content(api_docs_dir)
+        assert "被调用" in content or "Called by" in content
+
+    def test_has_description_or_todo(self, api_docs_dir):
+        """Function should have either a docstring description or TODO placeholder."""
+        content, _ = self._get_func_page_with_content(api_docs_dir)
+        has_desc = ">" in content  # blockquote description line
+        assert has_desc, "Function page should have > description line"
+
+
+# ---------------------------------------------------------------------------
+# C-specific doc features
+# ---------------------------------------------------------------------------
+
+
+class TestCSpecificDocs:
+    """Verify C/C++ specific documentation features."""
+
+    def test_macro_docs_generated(self, api_docs_dir):
+        """Macros should have their own function doc pages."""
+        docs_dir, _ = api_docs_dir
+        all_pages = list((docs_dir / "funcs").glob("*.md"))
+        macro_pages = []
+        for page in all_pages:
+            content = page.read_text(encoding="utf-8")
+            if "宏定义" in content or "macro" in content.lower():
+                macro_pages.append(page.name)
+        assert len(macro_pages) > 0, "Should have macro documentation pages"
+
+    def test_struct_docs_in_module_page(self, api_docs_dir):
+        """Module pages should document structs."""
+        docs_dir, _ = api_docs_dir
+        for page in (docs_dir / "modules").glob("*.md"):
+            content = page.read_text(encoding="utf-8")
+            if "struct" in content.lower() or "结构体" in content:
+                return  # Found struct documentation
+        # Not all modules have structs, but at least some should
+        # Check if any types were generated at all
+        _, result = api_docs_dir
+        if result["type_count"] > 0:
+            pytest.fail("Types exist but no struct documentation found in module pages")
+
+    def test_signature_has_c_syntax(self, api_docs_dir):
+        """Some function pages should contain C-style signatures."""
+        docs_dir, _ = api_docs_dir
+        # Search for pages whose filename suggests a real C function (contains a dot separator)
+        # e.g., tinycc.tcc.tcc_compile.md — not just macro names
+        c_keywords = ["int ", "void ", "char ", "unsigned ", "long ", "struct ", "static "]
+        for page in (docs_dir / "funcs").glob("*.md"):
+            content = page.read_text(encoding="utf-8")
+            if "(" in content and any(kw in content for kw in c_keywords):
+                return  # Found at least one
+        pytest.fail("Should find at least one C-style function signature in func docs")
+
+    def test_visibility_field_present(self, api_docs_dir):
+        """Function pages should have a visibility field."""
+        docs_dir, _ = api_docs_dir
+        checked = 0
+        has_visibility = 0
+        for page in list((docs_dir / "funcs").glob("*.md"))[:100]:
+            content = page.read_text(encoding="utf-8")
+            checked += 1
+            if "可见性:" in content or "Visibility:" in content:
+                has_visibility += 1
+        assert has_visibility > 0, "Function pages should have visibility field"
+
+    def test_docstring_in_description(self, api_docs_dir):
+        """Functions with extracted C comments should show them in description."""
+        docs_dir, _ = api_docs_dir
+        with_desc = 0
+        for page in (docs_dir / "funcs").glob("*.md"):
+            content = page.read_text(encoding="utf-8")
+            # Has a blockquote description that is NOT a TODO placeholder
+            for line in content.splitlines():
+                if line.startswith("> ") and "<!-- TODO" not in line:
+                    with_desc += 1
+                    break
+        assert with_desc > 0, "Some functions should have real descriptions from C comments"
+
+
+# ---------------------------------------------------------------------------
+# Consistency checks
+# ---------------------------------------------------------------------------
+
+
+class TestConsistency:
+    """Verify consistency between L1/L2/L3 levels."""
+
+    def test_module_count_matches_files(self, api_docs_dir):
+        docs_dir, result = api_docs_dir
+        module_files = list((docs_dir / "modules").glob("*.md"))
+        assert len(module_files) == result["module_count"], (
+            f"Module file count ({len(module_files)}) != result count ({result['module_count']})"
+        )
+
+    def test_func_count_matches_files(self, api_docs_dir):
+        """File count should closely match result count (small diff from filename collisions)."""
+        docs_dir, result = api_docs_dir
+        func_files = list((docs_dir / "funcs").glob("*.md"))
+        diff = abs(len(func_files) - result["func_count"])
+        assert diff <= 10, (
+            f"Func file count ({len(func_files)}) differs too much "
+            f"from result count ({result['func_count']}), diff={diff}"
+        )
+
+    def test_index_lists_all_modules(self, api_docs_dir):
+        """Index page should reference every module page."""
+        docs_dir, _ = api_docs_dir
+        index_content = (docs_dir / "index.md").read_text(encoding="utf-8")
+        module_files = list((docs_dir / "modules").glob("*.md"))
+        # At least 80% of module files should be referenced in index
+        referenced = sum(1 for f in module_files if f.stem in index_content)
+        ratio = referenced / len(module_files) if module_files else 1
+        assert ratio > 0.8, f"Only {ratio:.0%} modules referenced in index"