deepdoc 0.6.0__tar.gz → 0.6.2__tar.gz

{deepdoc-0.6.0 → deepdoc-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepdoc
-Version: 0.6.0
+Version: 0.6.2
 Summary: Auto-generate beautiful docs from any codebase
 Author: Pranav Kumar
 License: MIT
@@ -420,6 +420,7 @@ Generated Markdown pages include provenance frontmatter such as `deepdoc_generat
 | `--since` | last synced commit | Git ref to diff against |
 | `--replan` | off | Force a full replan even if the change set looks incremental |
 | `--deploy` | off | Deploy after a fully successful update |
+| `--strict-quality` | off | Exit non-zero when any page fails validation — use this in CI |
 
 ### `deepdoc status`
 
@@ -484,6 +485,24 @@ deepdoc config set llm.api_key_env AZURE_API_KEY       # Change API key env var
 deepdoc config set compatibility.deprecated_version_warning.enabled false
 ```
 
+### `deepdoc clean`
+
+Reset the repository to a pre-DeepDoc state. Removes `.deepdoc.yaml`, the
+DeepDoc-owned docs and site output, and saved state under `.deepdoc/`.
+
+```bash
+deepdoc clean          # prompts before deleting
+deepdoc clean --yes    # no prompt, for scripts
+```
+
+Only files DeepDoc created are removed — deletion is tracked against its own
+manifest, so hand-written pages you added to the output directory survive.
+`chatbot_backend/` is preserved as well, since it may contain your changes.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--yes` | off | Skip the confirmation prompt |
+
 ### `deepdoc benchmark`
 
 Run planner benchmark cases and optionally generate a combined docs+chatbot quality scorecard.
@@ -493,7 +512,7 @@ deepdoc benchmark --catalog benchmarks/catalog.json
 deepdoc benchmark --repo /path/to/repo --gold benchmarks/gold.json
 deepdoc benchmark --catalog benchmarks/catalog.json --chatbot-eval benchmarks/chatbot_eval.json
 deepdoc benchmark --catalog benchmarks/catalog.json --chatbot-eval benchmarks/chatbot_eval.json --scorecard-out .deepdoc/quality_scorecard.json --strict-scorecard
-deepdoc benchmark --generated-root /Users/apple/autodoc/docs --scorecard-out /Users/apple/autodoc/docs/_scorecards/latest.json
+deepdoc benchmark --generated-root ./deepdoc-docs --scorecard-out .deepdoc/scorecards/latest.json
 ```
 
 Use `--strict-scorecard` to fail the command when completeness gates are not met.

{deepdoc-0.6.0 → deepdoc-0.6.2}/README.md

@@ -379,6 +379,7 @@ Generated Markdown pages include provenance frontmatter such as `deepdoc_generat
 | `--since` | last synced commit | Git ref to diff against |
 | `--replan` | off | Force a full replan even if the change set looks incremental |
 | `--deploy` | off | Deploy after a fully successful update |
+| `--strict-quality` | off | Exit non-zero when any page fails validation — use this in CI |
 
 ### `deepdoc status`
 
@@ -443,6 +444,24 @@ deepdoc config set llm.api_key_env AZURE_API_KEY       # Change API key env var
 deepdoc config set compatibility.deprecated_version_warning.enabled false
 ```
 
+### `deepdoc clean`
+
+Reset the repository to a pre-DeepDoc state. Removes `.deepdoc.yaml`, the
+DeepDoc-owned docs and site output, and saved state under `.deepdoc/`.
+
+```bash
+deepdoc clean          # prompts before deleting
+deepdoc clean --yes    # no prompt, for scripts
+```
+
+Only files DeepDoc created are removed — deletion is tracked against its own
+manifest, so hand-written pages you added to the output directory survive.
+`chatbot_backend/` is preserved as well, since it may contain your changes.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--yes` | off | Skip the confirmation prompt |
+
 ### `deepdoc benchmark`
 
 Run planner benchmark cases and optionally generate a combined docs+chatbot quality scorecard.
@@ -452,7 +471,7 @@ deepdoc benchmark --catalog benchmarks/catalog.json
 deepdoc benchmark --repo /path/to/repo --gold benchmarks/gold.json
 deepdoc benchmark --catalog benchmarks/catalog.json --chatbot-eval benchmarks/chatbot_eval.json
 deepdoc benchmark --catalog benchmarks/catalog.json --chatbot-eval benchmarks/chatbot_eval.json --scorecard-out .deepdoc/quality_scorecard.json --strict-scorecard
-deepdoc benchmark --generated-root /Users/apple/autodoc/docs --scorecard-out /Users/apple/autodoc/docs/_scorecards/latest.json
+deepdoc benchmark --generated-root ./deepdoc-docs --scorecard-out .deepdoc/scorecards/latest.json
 ```
 
 Use `--strict-scorecard` to fail the command when completeness gates are not met.

{deepdoc-0.6.0 → deepdoc-0.6.2}/deepdoc/__init__.py

@@ -1,3 +1,3 @@
 """DeepDoc — Auto-generate beautiful docs from any codebase."""
 
-__version__ = "0.6.0"
+__version__ = "0.6.2"

{deepdoc-0.6.0 → deepdoc-0.6.2}/deepdoc/config.py

@@ -196,7 +196,7 @@ DEFAULT_CONFIG: dict[str, Any] = {
         },
         "theme": {
             # One of the built-in palettes, or "" for DeepDoc's own.
-            # neutral | black | vitepress | ocean | catppuccin | dusk | purple | solar | shadcn
+            # neutral | black | vitepress | ocean | catppuccin | dusk | purple
             "preset": "",
             # Raw Fumadocs design-token overrides — the final word, and the
             # escape hatch for anything the named keys above don't cover.

{deepdoc-0.6.0 → deepdoc-0.6.2}/deepdoc/generator/generation.py

@@ -473,10 +473,12 @@ class BucketGenerationEngine:
         for spec_path in self.scan.openapi_paths:
             spec = parse_openapi_spec(self.repo_root / spec_path)
             if spec:
-                chunk = (
-                    f"\n## OpenAPI Spec ({spec_path}):\n"
-                    f"{spec_to_context_string(spec)[:per_spec_limit]}"
-                )
+                # Supplemental context only: a malformed spec must not abort the run.
+                try:
+                    rendered = spec_to_context_string(spec)[:per_spec_limit]
+                except Exception:
+                    continue
+                chunk = f"\n## OpenAPI Spec ({spec_path}):\n{rendered}"
                 parts.append(chunk)
                 total += len(chunk)
                 if total >= 6000:

{deepdoc-0.6.0 → deepdoc-0.6.2}/deepdoc/llm/client.py

@@ -202,11 +202,13 @@ class LLMClient:
             self._raise_if_truncated(response)
             return response.choices[0].message.content or ""
 
-        except ImportError:
+        except ImportError as e:
             error_type = "ImportError"
             raise RuntimeError(
-                "litellm not installed. Run: pip install litellm"
-            )
+                f"litellm import failed ({e}). If `pip show litellm` finds it, "
+                "this is a broken dependency in litellm's import chain, not a "
+                "missing package — reinstalling litellm alone won't fix it."
+            ) from e
         except LLMOutputTruncatedError:
             error_type = "LLMOutputTruncatedError"
             raise
@@ -261,9 +263,13 @@ class LLMClient:
                         yield delta.content
             self._raise_if_truncated(final_chunk)
 
-        except ImportError:
+        except ImportError as e:
             error_type = "ImportError"
-            raise RuntimeError("litellm not installed. Run: pip install litellm")
+            raise RuntimeError(
+                f"litellm import failed ({e}). If `pip show litellm` finds it, "
+                "this is a broken dependency in litellm's import chain, not a "
+                "missing package — reinstalling litellm alone won't fix it."
+            ) from e
         except LLMOutputTruncatedError:
             error_type = "LLMOutputTruncatedError"
             raise

{deepdoc-0.6.0 → deepdoc-0.6.2}/deepdoc/openapi.py

@@ -12,6 +12,16 @@ from typing import Any
 from urllib.parse import urlparse
 
 
+def _d(value: Any) -> dict:
+    """Coerce to a dict. YAML ``key:`` with no value parses to None, and
+    ``.get(key, default)`` returns that None instead of the default."""
+    return value if isinstance(value, dict) else {}
+
+
+def _l(value: Any) -> list:
+    return value if isinstance(value, list) else []
+
+
 def find_openapi_specs(repo_root: Path) -> list[Path]:
     """Find all OpenAPI/Swagger spec files in the repo."""
     candidates = [
@@ -35,16 +45,17 @@ def parse_openapi_spec(spec_path: Path) -> dict[str, Any] | None:
     try:
         content = spec_path.read_text(encoding="utf-8")
         if spec_path.suffix == ".json":
-            return json.loads(content)
+            parsed = json.loads(content)
         else:
             try:
                 import yaml
-                return yaml.safe_load(content)
+                parsed = yaml.safe_load(content)
             except ImportError:
                 # Try JSON anyway
-                return json.loads(content)
+                parsed = json.loads(content)
     except Exception:
         return None
+    return parsed if isinstance(parsed, dict) else None
 
 
 def extract_endpoints_from_spec(spec: dict[str, Any]) -> list[dict[str, Any]]:
@@ -55,9 +66,9 @@ def extract_endpoints_from_spec(spec: dict[str, Any]) -> list[dict[str, Any]]:
 
     # OpenAPI 3.x
     if "openapi" in spec:
-        servers = spec.get("servers", [])
+        servers = _l(spec.get("servers"))
         if servers:
-            server_url = str(servers[0].get("url", "") or "").strip()
+            server_url = str(_d(servers[0]).get("url", "") or "").strip()
             if server_url:
                 parsed = urlparse(server_url)
                 if parsed.scheme or parsed.netloc:
@@ -67,26 +78,27 @@ def extract_endpoints_from_spec(spec: dict[str, Any]) -> list[dict[str, Any]]:
 
     # Swagger 2.x
     elif "swagger" in spec:
-        base_path = spec.get("basePath", "")
+        base_path = str(spec.get("basePath") or "")
 
-    paths = spec.get("paths", {})
-    for path, methods in paths.items():
+    for path, methods in _d(spec.get("paths")).items():
+        path = str(path)
         full_path = base_path + path if not path.startswith("http") else path
 
-        for method, details in methods.items():
-            if method.lower() in ("get", "post", "put", "patch", "delete", "head", "options"):
+        for method, details in _d(methods).items():
+            details = _d(details)
+            if str(method).lower() in ("get", "post", "put", "patch", "delete", "head", "options"):
                 endpoint = {
                     "method": method.upper(),
                     "path": full_path,
-                    "summary": details.get("summary", ""),
-                    "description": details.get("description", ""),
-                    "operation_id": details.get("operationId", ""),
-                    "tags": details.get("tags", []),
+                    "summary": str(details.get("summary") or ""),
+                    "description": str(details.get("description") or ""),
+                    "operation_id": str(details.get("operationId") or ""),
+                    "tags": _l(details.get("tags")),
                     "parameters": _extract_parameters(details, spec),
                     "request_body": _extract_request_body(details, spec),
                     "responses": _extract_responses(details, spec),
-                    "security": details.get("security", spec.get("security", [])),
-                    "deprecated": details.get("deprecated", False),
+                    "security": _l(details.get("security", spec.get("security"))),
+                    "deprecated": bool(details.get("deprecated", False)),
                 }
                 endpoints.append(endpoint)
 
@@ -96,10 +108,10 @@ def extract_endpoints_from_spec(spec: dict[str, Any]) -> list[dict[str, Any]]:
 def spec_to_context_string(spec: dict[str, Any]) -> str:
     """Convert an OpenAPI spec into a compact string for LLM context."""
     lines = []
-    info = spec.get("info", {})
-    lines.append(f"API: {info.get('title', 'Unknown')} v{info.get('version', '?')}")
+    info = _d(spec.get("info"))
+    lines.append(f"API: {info.get('title') or 'Unknown'} v{info.get('version') or '?'}")
     if info.get("description"):
-        lines.append(f"Description: {info['description'][:200]}")
+        lines.append(f"Description: {str(info['description'])[:200]}")
 
     endpoints = extract_endpoints_from_spec(spec)
     lines.append(f"\nEndpoints ({len(endpoints)}):")
@@ -131,8 +143,8 @@ def spec_to_context_string(spec: dict[str, Any]) -> str:
 
 def _extract_parameters(details: dict, spec: dict) -> list[dict]:
     params = []
-    for p in details.get("parameters", []):
-        p = _resolve_ref(p, spec)
+    for p in _l(details.get("parameters")):
+        p = _d(_resolve_ref(p, spec))
         params.append({
             "name": p.get("name", "?"),
             "in": p.get("in", "?"),
@@ -144,26 +156,25 @@ def _extract_parameters(details: dict, spec: dict) -> list[dict]:
 
 
 def _extract_request_body(details: dict, spec: dict) -> str:
-    rb = details.get("requestBody", {})
+    rb = details.get("requestBody")
     if not rb:
         return ""
-    rb = _resolve_ref(rb, spec)
-    content = rb.get("content", {})
-    for _media_type, schema_info in content.items():
-        schema = _resolve_ref(schema_info.get("schema", {}), spec)
+    rb = _d(_resolve_ref(rb, spec))
+    for _media_type, schema_info in _d(rb.get("content")).items():
+        schema = _resolve_ref(_d(schema_info).get("schema", {}), spec)
         return json.dumps(schema, indent=2)[:500]
     return ""
 
 
 def _extract_responses(details: dict, spec: dict) -> dict[str, str]:
     responses = {}
-    for status, resp in details.get("responses", {}).items():
-        resp = _resolve_ref(resp, spec)
-        desc = resp.get("description", "")
-        content = resp.get("content", {})
+    for status, resp in _d(details.get("responses")).items():
+        resp = _d(_resolve_ref(resp, spec))
+        desc = str(resp.get("description") or "")
+        content = _d(resp.get("content"))
         if content:
             for _media_type, schema_info in content.items():
-                schema = _resolve_ref(schema_info.get("schema", {}), spec)
+                schema = _resolve_ref(_d(schema_info).get("schema", {}), spec)
                 desc += f" | schema: {json.dumps(schema)[:200]}"
                 break
         responses[str(status)] = desc[:300]
@@ -180,7 +191,7 @@ def _resolve_ref(obj: dict, spec: dict) -> dict:
     parts = ref.lstrip("#/").split("/")
     resolved = spec
     for part in parts:
-        resolved = resolved.get(part, {})
+        resolved = _d(resolved).get(part, {})
     return resolved if isinstance(resolved, dict) else obj
 
 

{deepdoc-0.6.0 → deepdoc-0.6.2}/deepdoc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepdoc
-Version: 0.6.0
+Version: 0.6.2
 Summary: Auto-generate beautiful docs from any codebase
 Author: Pranav Kumar
 License: MIT
@@ -420,6 +420,7 @@ Generated Markdown pages include provenance frontmatter such as `deepdoc_generat
 | `--since` | last synced commit | Git ref to diff against |
 | `--replan` | off | Force a full replan even if the change set looks incremental |
 | `--deploy` | off | Deploy after a fully successful update |
+| `--strict-quality` | off | Exit non-zero when any page fails validation — use this in CI |
 
 ### `deepdoc status`
 
@@ -484,6 +485,24 @@ deepdoc config set llm.api_key_env AZURE_API_KEY       # Change API key env var
 deepdoc config set compatibility.deprecated_version_warning.enabled false
 ```
 
+### `deepdoc clean`
+
+Reset the repository to a pre-DeepDoc state. Removes `.deepdoc.yaml`, the
+DeepDoc-owned docs and site output, and saved state under `.deepdoc/`.
+
+```bash
+deepdoc clean          # prompts before deleting
+deepdoc clean --yes    # no prompt, for scripts
+```
+
+Only files DeepDoc created are removed — deletion is tracked against its own
+manifest, so hand-written pages you added to the output directory survive.
+`chatbot_backend/` is preserved as well, since it may contain your changes.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--yes` | off | Skip the confirmation prompt |
+
 ### `deepdoc benchmark`
 
 Run planner benchmark cases and optionally generate a combined docs+chatbot quality scorecard.
@@ -493,7 +512,7 @@ deepdoc benchmark --catalog benchmarks/catalog.json
 deepdoc benchmark --repo /path/to/repo --gold benchmarks/gold.json
 deepdoc benchmark --catalog benchmarks/catalog.json --chatbot-eval benchmarks/chatbot_eval.json
 deepdoc benchmark --catalog benchmarks/catalog.json --chatbot-eval benchmarks/chatbot_eval.json --scorecard-out .deepdoc/quality_scorecard.json --strict-scorecard
-deepdoc benchmark --generated-root /Users/apple/autodoc/docs --scorecard-out /Users/apple/autodoc/docs/_scorecards/latest.json
+deepdoc benchmark --generated-root ./deepdoc-docs --scorecard-out .deepdoc/scorecards/latest.json
 ```
 
 Use `--strict-scorecard` to fail the command when completeness gates are not met.

{deepdoc-0.6.0 → deepdoc-0.6.2}/deepdoc.egg-info/SOURCES.txt

@@ -199,6 +199,7 @@ tests/test_llm_retry.py
 tests/test_manifest_performance.py
 tests/test_nav_shaping.py
 tests/test_next_builder.py
+tests/test_openapi_null_values.py
 tests/test_output_safety.py
 tests/test_parallel_pipeline.py
 tests/test_parallel_scan.py

{deepdoc-0.6.0 → deepdoc-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepdoc"
-version = "0.6.0"
+version = "0.6.2"
 description = "Auto-generate beautiful docs from any codebase"
 readme = "README.md"
 authors = [

deepdoc-0.6.2/tests/test_openapi_null_values.py

@@ -0,0 +1,62 @@
+"""Specs with empty YAML values (``info:`` with nothing under it) parse to None.
+
+``dict.get(key, default)`` returns that None, so a sloppy-but-loadable spec used
+to crash ``spec_to_context_string`` and abort the whole generation run.
+"""
+from __future__ import annotations
+
+from deepdoc.openapi import (
+    extract_endpoints_from_spec,
+    parse_openapi_spec,
+    spec_to_context_string,
+)
+
+SLOPPY_YAML = """\
+openapi: 3.0.0
+info:
+servers:
+paths:
+  /things:
+    get:
+      summary:
+      tags:
+      parameters:
+      requestBody:
+      responses:
+        "200":
+          description:
+          content:
+    post:
+  /empty:
+"""
+
+
+def test_null_valued_spec_renders_context(tmp_path):
+    path = tmp_path / "openapi.yaml"
+    path.write_text(SLOPPY_YAML, encoding="utf-8")
+    spec = parse_openapi_spec(path)
+    assert spec is not None
+
+    text = spec_to_context_string(spec)
+
+    assert "API: Unknown v?" in text
+    assert "GET /things" in text
+    assert "POST /things" in text
+
+
+def test_null_valued_spec_extracts_endpoints(tmp_path):
+    path = tmp_path / "openapi.yaml"
+    path.write_text(SLOPPY_YAML, encoding="utf-8")
+    endpoints = extract_endpoints_from_spec(parse_openapi_spec(path))
+
+    assert {(e["method"], e["path"]) for e in endpoints} == {
+        ("GET", "/things"),
+        ("POST", "/things"),
+    }
+    assert all(isinstance(e["tags"], list) for e in endpoints)
+
+
+def test_non_mapping_spec_is_rejected(tmp_path):
+    path = tmp_path / "openapi.yaml"
+    path.write_text("- just\n- a list\n", encoding="utf-8")
+    assert parse_openapi_spec(path) is None