From ea145d234da523f66b8370b35f53f3850d17376e Mon Sep 17 00:00:00 2001 From: Luis Ojeda <119911593+Alejo2304@users.noreply.github.com> Date: Sat, 14 Nov 2026 20:51:42 -0500 Subject: [PATCH 1/7] fix: handle unrecorded language and layout metadata on --update (#161) --- codewiki/cli/adapters/doc_generator.py | 12 ++ codewiki/cli/commands/generate.py | 35 +++-- codewiki/src/be/doc_layout.py | 9 +- codewiki/src/be/documentation_generator.py | 8 ++ codewiki/src/language.py | 10 +- tests/test_doc_layout.py | 7 + tests/test_language.py | 149 ++++++++++++++++++++- 7 files changed, 217 insertions(+), 13 deletions(-) diff --git a/codewiki/cli/adapters/doc_generator.py b/codewiki/cli/adapters/doc_generator.py index 2a012d3a..6acc2c6f 100644 --- a/codewiki/cli/adapters/doc_generator.py +++ b/codewiki/cli/adapters/doc_generator.py @@ -664,6 +664,18 @@ def _finish_usage(self, incomplete: bool = False): metadata = {} if not isinstance(metadata, dict): metadata = {} + if "generation_info" not in metadata and ( + (self.output_dir / "module_tree.json").exists() + or list_doc_files(str(self.output_dir)) + ): + from codewiki.src.be.doc_layout import normalize_layout + from codewiki.src.language import normalize_language + + instructions = self.config.get("agent_instructions") or {} + metadata["generation_info"] = { + "language": normalize_language(instructions.get("language")), + "layout": normalize_layout(self.config.get("layout")), + } metadata["usage"] = report record = getattr(self, "_last_update_record", None) if record is not None: diff --git a/codewiki/cli/commands/generate.py b/codewiki/cli/commands/generate.py index 1dfd07f0..c6b8e284 100644 --- a/codewiki/cli/commands/generate.py +++ b/codewiki/cli/commands/generate.py @@ -43,15 +43,30 @@ def parse_patterns(patterns_str: str) -> list[str]: return [p.strip() for p in patterns_str.split(",") if p.strip()] -def _read_stored_language(output_dir: Path) -> str | None: - """Language recorded in metadata.json by the previous generation (None = English).""" +def _read_stored_language_state(output_dir: Path) -> tuple[bool, str | None]: + """Return ``(known, language)`` recorded in ``metadata.json``. + + ``known`` is False when ``metadata.json`` has no ``generation_info`` or no + ``language`` key (e.g., legacy docs or an incomplete run that only + persisted usage stats), so ``--update`` does not misread an unknown + language as English. + """ import json try: metadata = json.loads((output_dir / "metadata.json").read_text(encoding="utf-8")) - return (metadata.get("generation_info") or {}).get("language") + info = metadata.get("generation_info") + if not isinstance(info, dict) or "language" not in info: + return False, None + return True, info.get("language") except (OSError, json.JSONDecodeError, AttributeError): - return None + return False, None + + +def _read_stored_language(output_dir: Path) -> str | None: + """Language recorded in metadata.json by the previous generation (None = English).""" + _, stored = _read_stored_language_state(output_dir) + return stored def _detect_changed_files( @@ -644,12 +659,14 @@ def generate_command( # Incremental update: detect changed files and selectively regenerate changed_files = None update_language = None + stored_language_known = False updating_existing_docs = update and (output_dir / "metadata.json").exists() if updating_existing_docs: # Keep updated pages in the language of the existing docs + stored_language_known, stored_language = _read_stored_language_state(output_dir) try: update_language = resolve_update_language( - _read_stored_language(output_dir), language + stored_language, language, known=stored_language_known ) except ValueError as e: raise ConfigurationError(str(e)) from None @@ -802,15 +819,17 @@ def generate_command( elif config.agent_instructions and not config.agent_instructions.is_empty(): agent_instructions_dict = config.agent_instructions.to_dict() - if updating_existing_docs: - # The stored language overrides the saved `config agent --language` default + if updating_existing_docs and (stored_language_known or update_language is not None): + # The stored language (or explicit --language when metadata has none) + # overrides the saved `config agent --language` default agent_instructions_dict = dict(agent_instructions_dict or {}) agent_instructions_dict.pop("language", None) if update_language: agent_instructions_dict["language"] = update_language if verbose: + source = "metadata.json" if stored_language_known else "--language" logger.debug( - f"Output language (from metadata.json): {update_language or 'English'}" + f"Output language (from {source}): {update_language or 'English'}" ) # Create generator diff --git a/codewiki/src/be/doc_layout.py b/codewiki/src/be/doc_layout.py index a6b6d56f..c0cc98d0 100644 --- a/codewiki/src/be/doc_layout.py +++ b/codewiki/src/be/doc_layout.py @@ -124,12 +124,17 @@ def read_layout(docs_dir: str) -> str: """Layout recorded in ``metadata.json``. Docs without a recorded layout predate hierarchical output, so they are - flat. + flat—unless nested module pages already exist on disk (e.g., an incomplete + run whose metadata.json only persisted usage stats). """ metadata = _load_json(os.path.join(docs_dir, METADATA_FILENAME)) info = metadata.get("generation_info") if isinstance(metadata, dict) else None layout = info.get("layout") if isinstance(info, dict) else None - return layout if layout in LAYOUTS else LAYOUT_FLAT + if layout in LAYOUTS: + return layout + if any("/" in rel for rel in list_doc_files(docs_dir).values()): + return LAYOUT_HIERARCHICAL + return LAYOUT_FLAT def docs_layout(docs_dir: str) -> str: diff --git a/codewiki/src/be/documentation_generator.py b/codewiki/src/be/documentation_generator.py index b920d10a..228d3885 100644 --- a/codewiki/src/be/documentation_generator.py +++ b/codewiki/src/be/documentation_generator.py @@ -587,6 +587,14 @@ async def run(self) -> None: metadata = file_manager.load_json(path) if os.path.exists(path) else {} if not isinstance(metadata, dict): metadata = {} + if "generation_info" not in metadata and ( + os.path.exists(os.path.join(self.config.docs_dir, MODULE_TREE_FILENAME)) + or list_doc_files(self.config.docs_dir) + ): + metadata["generation_info"] = { + "language": getattr(self.config, "language", None), + "layout": config_layout(self.config), + } metadata["usage"] = self.usage_ledger.summary() file_manager.ensure_directory(self.config.docs_dir) file_manager.save_json(metadata, path) diff --git a/codewiki/src/language.py b/codewiki/src/language.py index 407ef516..59280c10 100644 --- a/codewiki/src/language.py +++ b/codewiki/src/language.py @@ -84,14 +84,20 @@ def format_language_directive(language: str | None) -> str: return LANGUAGE_DIRECTIVE.format(language=name) if name else "" -def resolve_update_language(stored: str | None, requested: str | None) -> str | None: +def resolve_update_language( + stored: str | None, requested: str | None, *, known: bool = True +) -> str | None: """ Language for an incremental update of docs generated in `stored`. The stored language wins over any saved default, so updated pages match the existing ones. An explicit `requested` language that differs raises - ValueError: switching language needs a full regeneration. + ValueError: switching language needs a full regeneration. When `known` is + False (the previous metadata did not record a language), any explicit + `requested` language is accepted rather than assumed to conflict with English. """ + if not known: + return normalize_language(requested) if requested is not None else None stored_name = normalize_language(stored) if requested is not None and normalize_language(requested) != stored_name: raise ValueError( diff --git a/tests/test_doc_layout.py b/tests/test_doc_layout.py index 3dc34c4b..4607e4aa 100644 --- a/tests/test_doc_layout.py +++ b/tests/test_doc_layout.py @@ -84,6 +84,13 @@ def test_read_layout_defaults_to_flat_for_old_docs(tmp_path): assert L.read_layout(str(tmp_path)) == "hierarchical" +def test_read_layout_detects_nested_docs_when_metadata_lacks_generation_info(tmp_path): + (tmp_path / "module_tree.json").write_text(json.dumps(TREE)) + _write(tmp_path, "auth/login.md") + (tmp_path / "metadata.json").write_text(json.dumps({"usage": {"incomplete": True}})) + assert L.read_layout(str(tmp_path)) == "hierarchical" + + def test_docs_layout_defaults_to_hierarchical_for_new_docs(tmp_path): assert L.docs_layout(str(tmp_path)) == "hierarchical" diff --git a/tests/test_language.py b/tests/test_language.py index f31d7a98..46e36c6a 100644 --- a/tests/test_language.py +++ b/tests/test_language.py @@ -5,7 +5,10 @@ import pytest -from codewiki.cli.commands.generate import _read_stored_language +from codewiki.cli.commands.generate import ( + _read_stored_language, + _read_stored_language_state, +) from codewiki.cli.html_generator import HTMLGenerator from codewiki.cli.models.config import AgentInstructions, Configuration from codewiki.src.be.documentation_generator import DocumentationGenerator @@ -185,3 +188,147 @@ def test_metadata_tolerates_config_stub_without_language(tmp_path): gen.commit_id = None gen.create_documentation_metadata(str(tmp_path), {}, 0) assert _read_stored_language(tmp_path) is None + + +def test_read_stored_language_state_distinguishes_recorded_vs_missing(tmp_path): + assert _read_stored_language_state(tmp_path) == (False, None) + + (tmp_path / "metadata.json").write_text(json.dumps({"usage": {"incomplete": True}})) + assert _read_stored_language_state(tmp_path) == (False, None) + + (tmp_path / "metadata.json").write_text(json.dumps({"generation_info": {"commit_id": "abc"}})) + assert _read_stored_language_state(tmp_path) == (False, None) + + (tmp_path / "metadata.json").write_text(json.dumps({"generation_info": {"language": None}})) + assert _read_stored_language_state(tmp_path) == (True, None) + + (tmp_path / "metadata.json").write_text( + json.dumps({"generation_info": {"language": "Spanish"}}) + ) + assert _read_stored_language_state(tmp_path) == (True, "Spanish") + + +def test_resolve_update_language_unknown_metadata(): + assert resolve_update_language(None, "es", known=False) == "Spanish" + assert resolve_update_language(None, "en", known=False) is None + assert resolve_update_language(None, None, known=False) is None + + +def test_generate_update_language_handling(tmp_path, monkeypatch): + from click.testing import CliRunner + import codewiki.cli.commands.generate as gen + + class Stop(Exception): + pass + + seen = {} + saved_agent = AgentInstructions() + cfg = SimpleNamespace( + main_model="m", + cluster_model="m", + fallback_model="m", + base_url="http://x", + provider="openai-compatible", + aws_region="us-east-1", + agent_instructions=saved_agent, + max_tokens=1, + min_token_per_module=1000, + max_token_per_module=1, + max_token_per_leaf_module=1, + max_depth=1, + request_limit=1, + agent_retries=1, + use_gitignore=True, + prompt_caching=False, + ) + + class FakeManager: + def load(self): + return True + + def is_configured(self): + return True + + def get_config(self): + return cfg + + def get_api_key(self): + return "k" + + def fake_generator(**kwargs): + seen.clear() + seen.update(kwargs["config"]) + raise Stop + + monkeypatch.setattr(gen, "ConfigManager", FakeManager) + monkeypatch.setattr(gen, "CLIDocumentationGenerator", fake_generator) + (tmp_path / "a.py").write_text("def f():\n return 1\n") + out = tmp_path / "out" + out.mkdir() + monkeypatch.chdir(tmp_path) + + # Incomplete metadata (no generation_info): --update --language es is accepted + (out / "metadata.json").write_text(json.dumps({"usage": {"incomplete": True}})) + CliRunner().invoke(gen.generate_command, ["--update", "--language", "es", "-o", str(out)]) + assert seen["agent_instructions"]["language"] == "Spanish" + + # Metadata without language key: saved config language is preserved when --language omitted + saved_agent.language = "es" + (out / "metadata.json").write_text(json.dumps({"generation_info": {"commit_id": "abc"}})) + CliRunner().invoke(gen.generate_command, ["--update", "-o", str(out)]) + assert seen["agent_instructions"]["language"] == "es" + saved_agent.language = None + + # Explicit English metadata still rejects --update --language es + (out / "metadata.json").write_text(json.dumps({"generation_info": {"language": None}})) + res = CliRunner().invoke( + gen.generate_command, ["--update", "--language", "es", "-o", str(out)] + ) + assert res.exit_code != 0 + assert "generated in English, but --language asks for Spanish" in res.output + + # Explicit Spanish metadata accepts --language es and rejects --language fr + (out / "metadata.json").write_text(json.dumps({"generation_info": {"language": "Spanish"}})) + CliRunner().invoke(gen.generate_command, ["--update", "--language", "es", "-o", str(out)]) + assert seen["agent_instructions"]["language"] == "Spanish" + + res = CliRunner().invoke( + gen.generate_command, ["--update", "--language", "fr", "-o", str(out)] + ) + assert res.exit_code != 0 + assert "generated in Spanish, but --language asks for French" in res.output + + +def test_incomplete_run_records_language_and_layout(tmp_path, monkeypatch): + from codewiki.cli.adapters.doc_generator import CLIDocumentationGenerator + from codewiki.cli.utils.errors import APIError + from codewiki.src.be.backend import UsageLedger + + out = tmp_path / "docs" + out.mkdir() + (out / "module_tree.json").write_text("{}") + + instance = CLIDocumentationGenerator( + tmp_path, + out, + { + "main_model": "m", + "cluster_model": "m", + "base_url": "http://x", + "api_key": "k", + "agent_instructions": {"language": "es"}, + "layout": "hierarchical", + }, + ) + + async def fail(cfg): + instance._usage_ledger = UsageLedger() + raise APIError("module failed") + + monkeypatch.setattr(instance, "_run_backend_generation", fail) + with pytest.raises(APIError): + instance.generate() + + metadata = json.loads((out / "metadata.json").read_text(encoding="utf-8")) + assert metadata["usage"]["incomplete"] is True + assert metadata["generation_info"] == {"language": "Spanish", "layout": "hierarchical"} From 93379b1126e1128e57fc2d51b69aca14eb13001a Mon Sep 17 00:00:00 2001 From: anhnh2002 Date: Mon, 16 Nov 2026 15:18:54 +0700 Subject: [PATCH 2/7] test: isolate backend logging in partial-generation regression --- tests/test_language.py | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/tests/test_language.py b/tests/test_language.py index 46e36c6a..fdce4355 100644 --- a/tests/test_language.py +++ b/tests/test_language.py @@ -281,9 +281,7 @@ def fake_generator(**kwargs): # Explicit English metadata still rejects --update --language es (out / "metadata.json").write_text(json.dumps({"generation_info": {"language": None}})) - res = CliRunner().invoke( - gen.generate_command, ["--update", "--language", "es", "-o", str(out)] - ) + res = CliRunner().invoke(gen.generate_command, ["--update", "--language", "es", "-o", str(out)]) assert res.exit_code != 0 assert "generated in English, but --language asks for Spanish" in res.output @@ -292,9 +290,7 @@ def fake_generator(**kwargs): CliRunner().invoke(gen.generate_command, ["--update", "--language", "es", "-o", str(out)]) assert seen["agent_instructions"]["language"] == "Spanish" - res = CliRunner().invoke( - gen.generate_command, ["--update", "--language", "fr", "-o", str(out)] - ) + res = CliRunner().invoke(gen.generate_command, ["--update", "--language", "fr", "-o", str(out)]) assert res.exit_code != 0 assert "generated in Spanish, but --language asks for French" in res.output @@ -308,6 +304,8 @@ def test_incomplete_run_records_language_and_layout(tmp_path, monkeypatch): out.mkdir() (out / "module_tree.json").write_text("{}") + monkeypatch.setattr(CLIDocumentationGenerator, "_configure_backend_logging", lambda self: None) + instance = CLIDocumentationGenerator( tmp_path, out, From 76764aa898daabfc5f82cbe7be5864fd24c6721b Mon Sep 17 00:00:00 2001 From: anhnh2002 Date: Mon, 16 Nov 2026 15:21:33 +0700 Subject: [PATCH 3/7] fix: preserve unknown language after unsuccessful updates --- .gitignore | 1 + codewiki/cli/adapters/doc_generator.py | 25 ++-- codewiki/src/be/documentation_generator.py | 13 +- codewiki/src/be/generation_metadata.py | 67 ++++++++++ tests/test_generation_metadata.py | 142 +++++++++++++++++++++ tests/test_language.py | 2 +- 6 files changed, 225 insertions(+), 25 deletions(-) create mode 100644 codewiki/src/be/generation_metadata.py create mode 100644 tests/test_generation_metadata.py diff --git a/.gitignore b/.gitignore index aed831bd..352d15ae 100644 --- a/.gitignore +++ b/.gitignore @@ -96,6 +96,7 @@ Thumbs.db !tests/test_updater_write_guard.py !tests/test_updater_orchestrator.py !tests/test_usage_ledger.py +!tests/test_generation_metadata.py !tests/test_pricing.py !tests/smoke_test_costs.py diff --git a/codewiki/cli/adapters/doc_generator.py b/codewiki/cli/adapters/doc_generator.py index 6acc2c6f..d33ebabe 100644 --- a/codewiki/cli/adapters/doc_generator.py +++ b/codewiki/cli/adapters/doc_generator.py @@ -20,6 +20,7 @@ # Import backend modules from codewiki.src.be.documentation_generator import DocumentationGenerator from codewiki.src.be.doc_layout import list_doc_files +from codewiki.src.be.generation_metadata import GenerationArtifacts, save_metadata from codewiki.src.config import DEFAULT_LAYOUT, DEFAULT_MAX_TOKEN_PER_LEAF_MODULE from codewiki.src.config import Config as BackendConfig from codewiki.src.config import set_cli_context @@ -138,6 +139,7 @@ def generate(self) -> DocumentationJob: Raises: APIError: If LLM API call fails """ + self._generation_artifacts = GenerationArtifacts(self.output_dir) self.job.start() try: @@ -177,6 +179,8 @@ def generate(self) -> DocumentationJob: layout=self.config.get("layout", DEFAULT_LAYOUT), ) + self._backend_config = backend_config + # Run backend documentation generation asyncio.run(self._run_backend_generation(backend_config)) self._record_usage_statistics() @@ -520,6 +524,7 @@ def _move_docs_aside(self) -> None: n += 1 shutil.move(str(self.output_dir), str(target)) self.output_dir.mkdir(parents=True, exist_ok=True) + self._generation_artifacts = GenerationArtifacts(self.output_dir) self._preserved_docs_dir = str(target) record = getattr(self, "_last_update_record", None) if record is not None: @@ -664,18 +669,10 @@ def _finish_usage(self, incomplete: bool = False): metadata = {} if not isinstance(metadata, dict): metadata = {} - if "generation_info" not in metadata and ( - (self.output_dir / "module_tree.json").exists() - or list_doc_files(str(self.output_dir)) - ): - from codewiki.src.be.doc_layout import normalize_layout - from codewiki.src.language import normalize_language - - instructions = self.config.get("agent_instructions") or {} - metadata["generation_info"] = { - "language": normalize_language(instructions.get("language")), - "layout": normalize_layout(self.config.get("layout")), - } + artifacts = getattr(self, "_generation_artifacts", None) + backend_config = getattr(self, "_backend_config", None) + if artifacts is not None and backend_config is not None: + artifacts.add_generation_info(metadata, backend_config) metadata["usage"] = report record = getattr(self, "_last_update_record", None) if record is not None: @@ -692,9 +689,7 @@ def _finish_usage(self, incomplete: bool = False): else: history.append(summary) metadata.update(last_update=summary, update_history=history) - from codewiki.cli.utils.fs import safe_write - - safe_write(path, json.dumps(metadata, indent=2, ensure_ascii=False)) + save_metadata(path, metadata) except Exception: logging.getLogger(__name__).warning("Could not save the run usage report") if incomplete: diff --git a/codewiki/src/be/documentation_generator.py b/codewiki/src/be/documentation_generator.py index 228d3885..9aefb074 100644 --- a/codewiki/src/be/documentation_generator.py +++ b/codewiki/src/be/documentation_generator.py @@ -23,6 +23,7 @@ organize_docs, relative_link, ) +from codewiki.src.be.generation_metadata import GenerationArtifacts, save_metadata from codewiki.src.be.utils import validate_mermaid_content from codewiki.src.be.overview_support import ( bounded_overview_prompt, @@ -477,6 +478,7 @@ async def generate_parent_module_docs( async def run(self) -> None: """Run the complete documentation generation process using dynamic programming.""" + artifacts = GenerationArtifacts(self.config.docs_dir) try: # Build dependency graph components, leaf_nodes = self.graph_builder.build_dependency_graph() @@ -587,17 +589,10 @@ async def run(self) -> None: metadata = file_manager.load_json(path) if os.path.exists(path) else {} if not isinstance(metadata, dict): metadata = {} - if "generation_info" not in metadata and ( - os.path.exists(os.path.join(self.config.docs_dir, MODULE_TREE_FILENAME)) - or list_doc_files(self.config.docs_dir) - ): - metadata["generation_info"] = { - "language": getattr(self.config, "language", None), - "layout": config_layout(self.config), - } + artifacts.add_generation_info(metadata, self.config) metadata["usage"] = self.usage_ledger.summary() file_manager.ensure_directory(self.config.docs_dir) - file_manager.save_json(metadata, path) + save_metadata(path, metadata) except Exception: logger.warning("Could not save the incomplete run usage report") raise diff --git a/codewiki/src/be/generation_metadata.py b/codewiki/src/be/generation_metadata.py new file mode 100644 index 00000000..357dd1ee --- /dev/null +++ b/codewiki/src/be/generation_metadata.py @@ -0,0 +1,67 @@ +"""Generation context must describe artifacts produced by the current run.""" + +from __future__ import annotations + +import hashlib +import json +import os +from pathlib import Path +import tempfile +from typing import Any + +from codewiki.src.be.doc_layout import config_layout, list_doc_files +from codewiki.src.config import MODULE_TREE_FILENAME + + +class GenerationArtifacts: + """Remember existing pages so a failed attempt cannot relabel untouched docs.""" + + def __init__(self, docs_dir: str | Path): + self.docs_dir = Path(docs_dir) + self.pages = self._pages() + self.had_tree = (self.docs_dir / MODULE_TREE_FILENAME).exists() + + def _pages(self) -> dict[str, bytes | None]: + pages = {} + for rel in list_doc_files(str(self.docs_dir)).values(): + try: + pages[rel] = hashlib.sha256((self.docs_dir / rel).read_bytes()).digest() + except OSError: + # An unreadable page is not evidence of a write by this run. + pages[rel] = None + return pages + + def produced_artifacts(self) -> bool: + if not self.pages and not self.had_tree and (self.docs_dir / MODULE_TREE_FILENAME).exists(): + return True + return any( + digest is not None + and ( + rel not in self.pages or (self.pages[rel] is not None and self.pages[rel] != digest) + ) + for rel, digest in self._pages().items() + ) + + def add_generation_info(self, metadata: dict[str, Any], config: Any) -> None: + if "generation_info" not in metadata and self.produced_artifacts(): + metadata["generation_info"] = { + "language": getattr(config, "language", None), + "layout": config_layout(config), + } + + +def save_metadata(path: str | Path, metadata: dict[str, Any]) -> None: + """Replace metadata atomically, retaining the previous file on write failure.""" + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True) + temporary = None + try: + with tempfile.NamedTemporaryFile( + mode="w", encoding="utf-8", dir=path.parent, prefix=".metadata-", delete=False + ) as stream: + temporary = Path(stream.name) + json.dump(metadata, stream, indent=2, ensure_ascii=False) + os.replace(temporary, path) + finally: + if temporary is not None: + temporary.unlink(missing_ok=True) diff --git a/tests/test_generation_metadata.py b/tests/test_generation_metadata.py new file mode 100644 index 00000000..8f9124f6 --- /dev/null +++ b/tests/test_generation_metadata.py @@ -0,0 +1,142 @@ +"""Recovery metadata describes this run's artifacts, not merely its settings.""" + +import asyncio +import json +from types import SimpleNamespace + +import pytest + +from codewiki.cli.adapters.doc_generator import CLIDocumentationGenerator +from codewiki.cli.commands.generate import _read_stored_language_state +from codewiki.cli.utils.errors import APIError +from codewiki.src.be.backend import UsageLedger +from codewiki.src.be.documentation_generator import DocumentationGenerator +from codewiki.src.language import resolve_update_language + + +def _fail_generation(tmp_path, monkeypatch, entrypoint, produce, language=None): + """Fail through the real entrypoint and its metadata/usage cleanup.""" + if entrypoint == "cli": + monkeypatch.setattr( + CLIDocumentationGenerator, "_configure_backend_logging", lambda self: None + ) + generator = CLIDocumentationGenerator( + tmp_path, + tmp_path, + { + "main_model": "m", + "cluster_model": "m", + "base_url": "http://unused", + "api_key": "unused", + "agent_instructions": {"language": language}, + "layout": "hierarchical", + }, + ) + + async def fail(config): + generator._usage_ledger = UsageLedger() + produce(config) + raise APIError("injected generation failure") + + monkeypatch.setattr(generator, "_run_backend_generation", fail) + with pytest.raises(APIError, match="injected generation failure"): + generator.generate() + else: + generator = object.__new__(DocumentationGenerator) + generator.config = SimpleNamespace( + docs_dir=str(tmp_path), language=language, layout="hierarchical" + ) + + def fail(): + produce(generator.config) + raise APIError("injected generation failure") + + generator.graph_builder = SimpleNamespace(build_dependency_graph=fail) + with pytest.raises(APIError, match="injected generation failure"): + asyncio.run(generator.run()) + return json.loads((tmp_path / "metadata.json").read_text()) + + +@pytest.mark.parametrize("entrypoint", ["cli", "backend"]) +@pytest.mark.parametrize("old_tree", [False, True]) +def test_early_failure_does_not_relabel_existing_spanish_docs( + tmp_path, monkeypatch, entrypoint, old_tree +): + page = tmp_path / "overview.md" + page.write_text("# Resumen\nDocumentación en español.\n") + if old_tree: + (tmp_path / "module_tree.json").write_text("{}") + (tmp_path / "metadata.json").write_text(json.dumps({"usage": {"incomplete": True}})) + + metadata = _fail_generation(tmp_path, monkeypatch, entrypoint, lambda config: None) + + assert "generation_info" not in metadata + assert metadata["usage"]["incomplete"] is True + assert _read_stored_language_state(tmp_path) == (False, None) + assert resolve_update_language(None, "es", known=False) == "Spanish" + assert "Documentación en español" in page.read_text() + + +@pytest.mark.parametrize("entrypoint", ["cli", "backend"]) +def test_new_tree_in_empty_output_records_context(tmp_path, monkeypatch, entrypoint): + def produce(config): + (tmp_path / "module_tree.json").write_text("{}") + + metadata = _fail_generation(tmp_path, monkeypatch, entrypoint, produce, "Spanish") + assert metadata["generation_info"] == {"language": "Spanish", "layout": "hierarchical"} + + +@pytest.mark.parametrize("entrypoint", ["cli", "backend"]) +def test_new_tree_does_not_relabel_old_pages(tmp_path, monkeypatch, entrypoint): + (tmp_path / "overview.md").write_text("# Resumen\nTexto español.\n") + + def produce(config): + (tmp_path / "module_tree.json").write_text("{}") + + metadata = _fail_generation(tmp_path, monkeypatch, entrypoint, produce) + assert "generation_info" not in metadata + + +@pytest.mark.parametrize("entrypoint", ["cli", "backend"]) +@pytest.mark.parametrize("existing_page", [False, True]) +def test_written_page_records_effective_context(tmp_path, monkeypatch, entrypoint, existing_page): + if existing_page: + (tmp_path / "overview.md").write_text("# Resumen anterior\n") + + def produce(config): + config.layout = "flat" # The updater can change the effective backend config. + (tmp_path / "overview.md").write_text("# Resumen actualizado\nTexto español.\n") + + metadata = _fail_generation(tmp_path, monkeypatch, entrypoint, produce, "Spanish") + assert metadata["generation_info"] == {"language": "Spanish", "layout": "flat"} + + +@pytest.mark.parametrize("entrypoint", ["cli", "backend"]) +def test_rewriting_identical_old_page_does_not_establish_language( + tmp_path, monkeypatch, entrypoint +): + (tmp_path / "overview.md").write_text("# Resumen\n") + + def produce(config): + (tmp_path / "overview.md").write_text("# Resumen\n") + + metadata = _fail_generation(tmp_path, monkeypatch, entrypoint, produce) + assert "generation_info" not in metadata + + +def test_failed_atomic_metadata_write_preserves_previous_file(tmp_path, monkeypatch): + from codewiki.src.be import generation_metadata + + path = tmp_path / "metadata.json" + path.write_text('{"generation_info": {"language": "Spanish"}}') + previous = path.read_bytes() + + def fail(data, stream, **kwargs): + stream.write('{"partial":') + raise OSError("disk full") + + monkeypatch.setattr(generation_metadata.json, "dump", fail) + with pytest.raises(OSError, match="disk full"): + generation_metadata.save_metadata(path, {"usage": {}}) + assert path.read_bytes() == previous + assert list(tmp_path.iterdir()) == [path] diff --git a/tests/test_language.py b/tests/test_language.py index fdce4355..f54b1471 100644 --- a/tests/test_language.py +++ b/tests/test_language.py @@ -302,7 +302,6 @@ def test_incomplete_run_records_language_and_layout(tmp_path, monkeypatch): out = tmp_path / "docs" out.mkdir() - (out / "module_tree.json").write_text("{}") monkeypatch.setattr(CLIDocumentationGenerator, "_configure_backend_logging", lambda self: None) @@ -321,6 +320,7 @@ def test_incomplete_run_records_language_and_layout(tmp_path, monkeypatch): async def fail(cfg): instance._usage_ledger = UsageLedger() + (out / "module_tree.json").write_text("{}") raise APIError("module failed") monkeypatch.setattr(instance, "_run_backend_generation", fail) From 56c8fe838a481e3da28c1f7c537c592787311e1a Mon Sep 17 00:00:00 2001 From: anhnh2002 Date: Mon, 16 Nov 2026 15:22:44 +0700 Subject: [PATCH 4/7] fix: backfill missing generation metadata fields --- codewiki/src/be/generation_metadata.py | 14 +++++--- tests/test_generation_metadata.py | 46 ++++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 5 deletions(-) diff --git a/codewiki/src/be/generation_metadata.py b/codewiki/src/be/generation_metadata.py index 357dd1ee..dbbf40f5 100644 --- a/codewiki/src/be/generation_metadata.py +++ b/codewiki/src/be/generation_metadata.py @@ -43,11 +43,15 @@ def produced_artifacts(self) -> bool: ) def add_generation_info(self, metadata: dict[str, Any], config: Any) -> None: - if "generation_info" not in metadata and self.produced_artifacts(): - metadata["generation_info"] = { - "language": getattr(config, "language", None), - "layout": config_layout(config), - } + if not self.produced_artifacts(): + return + info = metadata.get("generation_info") + if not isinstance(info, dict): + info = {} + # A recorded null language means English; only absent keys are unknown. + info.setdefault("language", getattr(config, "language", None)) + info.setdefault("layout", config_layout(config)) + metadata["generation_info"] = info def save_metadata(path: str | Path, metadata: dict[str, Any]) -> None: diff --git a/tests/test_generation_metadata.py b/tests/test_generation_metadata.py index 8f9124f6..768f7513 100644 --- a/tests/test_generation_metadata.py +++ b/tests/test_generation_metadata.py @@ -124,6 +124,52 @@ def produce(config): assert "generation_info" not in metadata +@pytest.mark.parametrize("entrypoint", ["cli", "backend"]) +@pytest.mark.parametrize( + "info, expected", + [ + (None, {"language": "Spanish", "layout": "hierarchical"}), + ({}, {"language": "Spanish", "layout": "hierarchical"}), + ( + {"commit_id": "abc"}, + {"commit_id": "abc", "language": "Spanish", "layout": "hierarchical"}, + ), + ({"language": None}, {"language": None, "layout": "hierarchical"}), + ({"layout": "flat"}, {"language": "Spanish", "layout": "flat"}), + ( + {"language": "Japanese", "layout": "flat"}, + {"language": "Japanese", "layout": "flat"}, + ), + ], +) +def test_partial_info_is_backfilled_without_overwriting_recorded_fields( + tmp_path, monkeypatch, entrypoint, info, expected +): + (tmp_path / "metadata.json").write_text( + json.dumps({"generation_info": info, "update_history": [{"run_id": "old"}], "custom": 42}) + ) + (tmp_path / "module_tree.json").write_text("{}") + + def produce(config): + (tmp_path / "overview.md").write_text("# Resumen\nTexto español.\n") + + metadata = _fail_generation(tmp_path, monkeypatch, entrypoint, produce, "Spanish") + assert metadata["generation_info"] == expected + assert metadata["update_history"] == [{"run_id": "old"}] + assert metadata["custom"] == 42 + assert metadata["usage"]["incomplete"] is True + + +@pytest.mark.parametrize("entrypoint", ["cli", "backend"]) +def test_early_failure_preserves_partial_info_as_unknown(tmp_path, monkeypatch, entrypoint): + info = {"commit_id": "abc", "layout": "hierarchical"} + (tmp_path / "metadata.json").write_text(json.dumps({"generation_info": info})) + (tmp_path / "overview.md").write_text("# Resumen\n") + metadata = _fail_generation(tmp_path, monkeypatch, entrypoint, lambda config: None, "Spanish") + assert metadata["generation_info"] == info + assert _read_stored_language_state(tmp_path) == (False, None) + + def test_failed_atomic_metadata_write_preserves_previous_file(tmp_path, monkeypatch): from codewiki.src.be import generation_metadata From 1a19e9e49686629b3376e9aa4f907f71260b37c8 Mon Sep 17 00:00:00 2001 From: anhnh2002 Date: Mon, 16 Nov 2026 15:23:57 +0700 Subject: [PATCH 5/7] fix: retain generation context on interruption --- codewiki/cli/adapters/doc_generator.py | 4 + codewiki/src/be/documentation_generator.py | 3 +- tests/test_generation_metadata.py | 93 ++++++++++++++++++++-- 3 files changed, 93 insertions(+), 7 deletions(-) diff --git a/codewiki/cli/adapters/doc_generator.py b/codewiki/cli/adapters/doc_generator.py index d33ebabe..22080a41 100644 --- a/codewiki/cli/adapters/doc_generator.py +++ b/codewiki/cli/adapters/doc_generator.py @@ -201,6 +201,10 @@ def generate(self) -> DocumentationJob: return self.job + except (KeyboardInterrupt, asyncio.CancelledError): + self.job.fail("Generation interrupted") + self._finish_usage(incomplete=True) + raise except APIError as e: self.job.fail(str(e)) self._finish_usage(incomplete=True) diff --git a/codewiki/src/be/documentation_generator.py b/codewiki/src/be/documentation_generator.py index 9aefb074..d2cc4a51 100644 --- a/codewiki/src/be/documentation_generator.py +++ b/codewiki/src/be/documentation_generator.py @@ -1,3 +1,4 @@ +import asyncio import json import logging import os @@ -580,7 +581,7 @@ async def run(self) -> None: logger.debug("Processing order: leaf modules → parent modules → repository overview") logger.debug(f"Documentation saved to: {working_dir}") - except Exception as e: + except (Exception, KeyboardInterrupt, asyncio.CancelledError) as e: logger.error(f"Documentation generation failed: {e!s}") logger.error(f"Traceback: {traceback.format_exc()}") self.usage_ledger.incomplete = True diff --git a/tests/test_generation_metadata.py b/tests/test_generation_metadata.py index 768f7513..01d1824e 100644 --- a/tests/test_generation_metadata.py +++ b/tests/test_generation_metadata.py @@ -14,7 +14,9 @@ from codewiki.src.language import resolve_update_language -def _fail_generation(tmp_path, monkeypatch, entrypoint, produce, language=None): +def _fail_generation( + tmp_path, monkeypatch, entrypoint, produce, language=None, error_type=APIError, read_report=True +): """Fail through the real entrypoint and its metadata/usage cleanup.""" if entrypoint == "cli": monkeypatch.setattr( @@ -36,10 +38,10 @@ def _fail_generation(tmp_path, monkeypatch, entrypoint, produce, language=None): async def fail(config): generator._usage_ledger = UsageLedger() produce(config) - raise APIError("injected generation failure") + raise error_type("injected generation failure") monkeypatch.setattr(generator, "_run_backend_generation", fail) - with pytest.raises(APIError, match="injected generation failure"): + with pytest.raises(error_type, match="injected generation failure"): generator.generate() else: generator = object.__new__(DocumentationGenerator) @@ -49,12 +51,13 @@ async def fail(config): def fail(): produce(generator.config) - raise APIError("injected generation failure") + raise error_type("injected generation failure") generator.graph_builder = SimpleNamespace(build_dependency_graph=fail) - with pytest.raises(APIError, match="injected generation failure"): + with pytest.raises(error_type, match="injected generation failure"): asyncio.run(generator.run()) - return json.loads((tmp_path / "metadata.json").read_text()) + if read_report: + return json.loads((tmp_path / "metadata.json").read_text()) @pytest.mark.parametrize("entrypoint", ["cli", "backend"]) @@ -170,6 +173,84 @@ def test_early_failure_preserves_partial_info_as_unknown(tmp_path, monkeypatch, assert _read_stored_language_state(tmp_path) == (False, None) +@pytest.mark.parametrize("entrypoint", ["cli", "backend"]) +@pytest.mark.parametrize("error_type", [KeyboardInterrupt, asyncio.CancelledError]) +@pytest.mark.parametrize("artifact", [None, "module_tree.json", "overview.md"]) +def test_interruption_saves_only_established_context( + tmp_path, monkeypatch, entrypoint, error_type, artifact +): + def produce(config): + if artifact: + (tmp_path / artifact).write_text("{}" if artifact.endswith(".json") else "# Resumen\n") + + metadata = _fail_generation( + tmp_path, monkeypatch, entrypoint, produce, "Spanish", error_type=error_type + ) + assert metadata["usage"]["incomplete"] is True + if artifact: + assert metadata["generation_info"] == {"language": "Spanish", "layout": "hierarchical"} + assert resolve_update_language(_read_stored_language_state(tmp_path)[1], "es") == "Spanish" + else: + assert _read_stored_language_state(tmp_path) == (False, None) + + +@pytest.mark.parametrize("entrypoint", ["cli", "backend"]) +def test_metadata_write_failure_does_not_replace_interruption(tmp_path, monkeypatch, entrypoint): + from codewiki.cli.adapters import doc_generator + from codewiki.src.be import documentation_generator + + def cannot_save(*args): + raise OSError("disk full") + + monkeypatch.setattr(doc_generator, "save_metadata", cannot_save) + monkeypatch.setattr(documentation_generator, "save_metadata", cannot_save) + _fail_generation( + tmp_path, + monkeypatch, + entrypoint, + lambda config: None, + error_type=KeyboardInterrupt, + read_report=False, + ) + + +def test_cli_interrupt_exits_130_and_preserves_context(tmp_path, monkeypatch): + from click.testing import CliRunner + from codewiki.cli.commands import generate + from codewiki.cli.models.config import Configuration + + class Manager: + def load(self): + return True + + def is_configured(self): + return True + + def get_config(self): + return Configuration(base_url="", provider="codex", main_model="m", cluster_model="m") + + def get_api_key(self): + return "" + + out = tmp_path / "docs" + (tmp_path / "example.py").write_text("def f():\n return 1\n") + + async def interrupt(self, config): + self._usage_ledger = UsageLedger() + out.mkdir() + (out / "module_tree.json").write_text("{}") + raise KeyboardInterrupt() + + monkeypatch.chdir(tmp_path) + monkeypatch.setattr(generate, "ConfigManager", Manager) + monkeypatch.setattr(CLIDocumentationGenerator, "_configure_backend_logging", lambda self: None) + monkeypatch.setattr(CLIDocumentationGenerator, "_run_backend_generation", interrupt) + result = CliRunner().invoke(generate.generate_command, ["-o", str(out), "--language", "es"]) + assert result.exit_code == 130, result.output + assert "Interrupted by user" in result.output + assert _read_stored_language_state(out) == (True, "Spanish") + + def test_failed_atomic_metadata_write_preserves_previous_file(tmp_path, monkeypatch): from codewiki.src.be import generation_metadata From b6caaeca1441fbd9d3fd740157e92b8ed4a97a05 Mon Sep 17 00:00:00 2001 From: anhnh2002 Date: Mon, 16 Nov 2026 15:25:04 +0700 Subject: [PATCH 6/7] style: satisfy PR formatting checks --- codewiki/cli/commands/generate.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/codewiki/cli/commands/generate.py b/codewiki/cli/commands/generate.py index c6b8e284..67030faa 100644 --- a/codewiki/cli/commands/generate.py +++ b/codewiki/cli/commands/generate.py @@ -828,9 +828,7 @@ def generate_command( agent_instructions_dict["language"] = update_language if verbose: source = "metadata.json" if stored_language_known else "--language" - logger.debug( - f"Output language (from {source}): {update_language or 'English'}" - ) + logger.debug(f"Output language (from {source}): {update_language or 'English'}") # Create generator # Get commit_id early so it can be stored in metadata.json for --update support From 766904ed1ccfb49f06259c2d7473f5f62fe034f3 Mon Sep 17 00:00:00 2001 From: anhnh2002 Date: Mon, 16 Nov 2026 15:31:18 +0700 Subject: [PATCH 7/7] fix: require MCP SDK compatible with current CAW tools --- pyproject.toml | 2 +- requirements.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index a96d9216..e113dba2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -63,7 +63,7 @@ dependencies = [ "colorama>=0.4.6", "logfire>=4.1.0", "coding-agent-wrapper @ git+https://github.com/anhnh2002/caw@main", - "mcp>=1.0.0" + "mcp>=1.30.0,<2" ] [external] diff --git a/requirements.txt b/requirements.txt index 1d764c05..04826226 100644 --- a/requirements.txt +++ b/requirements.txt @@ -68,7 +68,7 @@ loguru==0.7.3 markdown-it-py==3.0.0 MarkupSafe==3.0.2 matplotlib-inline==0.1.7 -mcp==1.12.3 +mcp==1.30.0 mdurl==0.1.2 mermaid-parser-py==0.0.2 mermaid-py==0.8.0