Refactor tests and complete architectural hardening

Author: deepakdgupta1

KnowCode.md

@@ -950,22 +950,22 @@ Commands invoked without the required extra should fail fast with: *"Install kno
 > - *"Write a summary of what changed in this module since last release."*
 > - *"Which parts of the documentation are stale and need updating?"*
 
-### **Phase 4.5: Architectural Hardening (NEXT)** *(addresses AD-1 through AD-7)*
+### **Phase 4.5: Architectural Hardening (COMPLETED)** *(addresses AD-1 through AD-7)*
 15. **[x] Dependency Modularisation (AD-1)**: Move heavy dependencies behind optional extras (`server`, `search`, `llm`, `watch`, `all`). Core install stays lightweight.
 16. **[x] Side-Effect-Free Query Paths (AD-2)**: Remove auto-analyze/index from `retrieve_context_for_query()`. Fail fast with actionable errors. Add explicit `ensure_store()` / `ensure_index()` helpers.
 17. **[x] Schema Versioning (AD-3)**: Add `schema_version` to knowledge store JSON, index manifest, chunks metadata, and vector metadata. Include migration/validation shims on load.
 18. **[x] Data Model Fixes (AD-4)**: Change `metadata: dict[str, str]` to `dict[str, Any]` across `Entity`, `Relationship`, and `CodeChunk` with mixed-type roundtrip coverage.
 19. **[x] Configuration Hardening (AD-5)**: Replace `print()` with `logging`; raise on invalid config in server/MCP contexts via strict mode; validate known YAML keys and warn on unknown keys.
 20. **[x] Service Layer Decomposition (AD-6)**: Extracted `RetrievalOrchestrator` from `KnowCodeService`. Added `Protocol` interfaces for `EmbeddingProvider`, `VectorStore`, and `KnowledgeStoreProtocol`.
 21. **[x] Entity Identity Resilience (AD-7)**: Add `content_hash` to entity metadata for rename-resilient correlation.
-22. **[ ] Layer Contract Tests**: Parser → `ParseResult` contract tests; store save/load roundtrip with schema version; retrieval golden-query tests; CLI smoke tests (Click runner); API endpoint contract tests (conditional on `server` extra).
+22. **[x] Layer Contract Tests**: Parser → `ParseResult` contract tests; store save/load roundtrip with schema version; retrieval golden-query tests; CLI smoke tests (Click runner); API endpoint contract tests (conditional on `server` extra).
 
 > *This phase does not unlock new user-facing questions — it makes the existing answers more reliable, portable, and predictable. For example:*
 > - *"I upgraded KnowCode — will my existing analysis still work?"* (schema versioning)
 > - *"I renamed a file — does KnowCode still recognise the same functions?"* (entity identity resilience)
 > - *"Can I install KnowCode without all the heavy AI dependencies?"* (dependency modularisation)
 
-### **Phase 5: Deep Analysis**
+### **Phase 5: Deep Analysis (NEXT)**
 23. **[ ] Static Behavioral Analysis (Layer 4)**: Data flow, state transitions, side-effect classification.
 24. **[ ] Intent Extraction (Layer 6)**: ADR/PR/commit intent linking beyond commit metadata.
 25. **[ ] Confidence Scoring (Layer 3)**: Weighted edges/entities by evidence source.

tests/e2e/test_server_refinement.py

@@ -30,8 +30,13 @@ def _disable_rate_limiter() -> None:
 
 
 @pytest.fixture(scope="module")
-def service() -> KnowCodeService:
-    return KnowCodeService(store_path=".")
+def service(tmp_path_factory: pytest.TempPathFactory) -> KnowCodeService:
+    tmp_dir = tmp_path_factory.mktemp("temp_data")
+    (tmp_dir / "app.py").write_text("class GraphBuilder:\n    pass\n", encoding="utf-8")
+    s = KnowCodeService(store_path=str(tmp_dir))
+    s.ensure_store()
+    s.ensure_index()
+    return s
 
 
 def test_reload_endpoint(service: KnowCodeService) -> None:

tests/integration/test_golden_queries.py

@@ -0,0 +1,75 @@
+"""Retrieval Golden-Query Tests."""
+
+import pytest
+from knowcode.indexing.indexer import Indexer
+from knowcode.retrieval.search_engine import SearchEngine
+from knowcode.data_models import EmbeddingConfig
+from knowcode.retrieval.hybrid_index import HybridIndex
+from knowcode.storage.chunk_repository import InMemoryChunkRepository
+from knowcode.storage.vector_store import VectorStore
+from knowcode.storage.knowledge_store import KnowledgeStore
+
+# Mocking the embedding provider so we don't hit external APIs in tests.
+class DeterministicEmbeddingProvider:
+    def __init__(self) -> None:
+        self.config = EmbeddingConfig(dimension=4)
+        
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        # Return deterministic dummy vectors.
+        # BM25 will do the heavy lifting for relevance in this test.
+        return [[0.1, 0.1, 0.1, 0.1] for _ in texts]
+        
+    def embed_single(self, text: str) -> list[float]:
+        return [0.1, 0.1, 0.1, 0.1]
+
+@pytest.fixture
+def search_engine(tmp_path):
+    repo = InMemoryChunkRepository()
+    vs = VectorStore(dimension=4)
+    provider = DeterministicEmbeddingProvider()
+    
+    indexer = Indexer(provider, chunk_repo=repo, vector_store=vs)
+    
+    # Create a small realistic codebase
+    files = {
+        "auth.py": '''
+def login(username, password):
+    """Handle user authentication and login flow."""
+    return True
+''',
+        "database.py": '''
+def connect_to_db(connection_string):
+    """Establish connection to the main postgres database."""
+    pass
+''',
+        "utils.py": '''
+def reverse_string(s):
+    """A helper function to reverse a string."""
+    return s[::-1]
+''',
+    }
+    
+    for filename, content in files.items():
+        p = tmp_path / filename
+        p.write_text(content)
+        indexer.index_file(p)
+        
+    hybrid = HybridIndex(repo, vs)
+    store = KnowledgeStore()
+    engine = SearchEngine(repo, provider, hybrid, store)
+    
+    return engine
+
+@pytest.mark.parametrize("query, expected_filename", [
+    ("user login authentication flow", "auth.py"),
+    ("postgres database connection", "database.py"),
+    ("helper reverse string", "utils.py"),
+])
+def test_golden_queries(search_engine, query, expected_filename):
+    """Golden-query test: ensure specific queries return expected files as top result."""
+    results = search_engine.search(query, limit=3)
+    assert len(results) > 0
+    
+    top_result = results[0]
+    # Check if the expected filename is in the chunk ID (e.g. auth.py::login::chunk_0)
+    assert expected_filename in top_result.id

tests/unit/parsers/test_parser_contract.py

@@ -0,0 +1,76 @@
+import pytest
+from pathlib import Path
+
+from knowcode.data_models import ParseResult, Entity, Relationship
+from knowcode.parsers.python_parser import PythonParser
+from knowcode.parsers.markdown_parser import MarkdownParser
+from knowcode.parsers.yaml_parser import YamlParser
+from knowcode.parsers.javascript_parser import JavaScriptParser
+from knowcode.parsers.java_parser import JavaParser
+from knowcode.parsers.rust_parser import RustParser
+from knowcode.parsers.vue_parser import VueParser
+from knowcode.parsers.typescript_parser import TypeScriptParser
+
+PARSERS = [
+    (PythonParser, "x = 1\n", ".py"),
+    (MarkdownParser, "# Hello\n", ".md"),
+    (YamlParser, "key: value\n", ".yaml"),
+    (JavaScriptParser, "let x = 1;\n", ".js"),
+    (JavaParser, "class Main {}\n", ".java"),
+    (RustParser, "fn main() {}\n", ".rs"),
+    (VueParser, "<template><div></div></template>\n", ".vue"),
+    (TypeScriptParser, "let x: number = 1;\n", ".ts"),
+]
+
+@pytest.mark.parametrize("parser_class, code, ext", PARSERS)
+def test_contract_missing_file(tmp_path, parser_class, code, ext):
+    parser = parser_class()
+    missing_file = tmp_path / f"missing_file{ext}"
+    result = parser.parse_file(missing_file)
+    
+    assert isinstance(result, ParseResult)
+    assert result.file_path == str(missing_file)
+    assert len(result.errors) > 0
+    assert isinstance(result.entities, list)
+    assert isinstance(result.relationships, list)
+
+@pytest.mark.parametrize("parser_class, code, ext", PARSERS)
+def test_contract_empty_file(tmp_path, parser_class, code, ext):
+    parser = parser_class()
+    empty_file = tmp_path / f"empty{ext}"
+    empty_file.write_text("")
+    
+    result = parser.parse_file(empty_file)
+    assert isinstance(result, ParseResult)
+    assert result.file_path == str(empty_file)
+    assert isinstance(result.entities, list)
+    assert isinstance(result.relationships, list)
+    assert isinstance(result.errors, list)
+    
+    for entity in result.entities:
+        assert isinstance(entity, Entity)
+    for rel in result.relationships:
+        assert isinstance(rel, Relationship)
+
+@pytest.mark.parametrize("parser_class, code, ext", PARSERS)
+def test_contract_valid_file(tmp_path, parser_class, code, ext):
+    parser = parser_class()
+    valid_file = tmp_path / f"valid{ext}"
+    valid_file.write_text(code)
+    
+    result = parser.parse_file(valid_file)
+    assert isinstance(result, ParseResult)
+    assert result.file_path == str(valid_file)
+    assert isinstance(result.entities, list)
+    assert isinstance(result.relationships, list)
+    assert isinstance(result.errors, list)
+    
+    for entity in result.entities:
+        assert isinstance(entity, Entity)
+        assert isinstance(entity.id, str)
+        assert entity.id != ""
+        assert isinstance(entity.qualified_name, str)
+    for rel in result.relationships:
+        assert isinstance(rel, Relationship)
+        assert isinstance(rel.source_id, str)
+        assert isinstance(rel.target_id, str)