deepdoc 0.4.1__tar.gz → 0.4.2__tar.gz

{deepdoc-0.4.1 → deepdoc-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepdoc
-Version: 0.4.1
+Version: 0.4.2
 Summary: Auto-generate beautiful docs from any codebase
 Author: Pranav Kumar
 License: MIT

{deepdoc-0.4.1 → deepdoc-0.4.2}/deepdoc/parser/routes/falcon.py

@@ -114,8 +114,20 @@ def _fallback_falcon_path(path_expr: str) -> str:
     return "".join(string_parts)
 
 
-def find_falcon_responders(content: str, class_name: str) -> list[str]:
-    """Find all on_* methods in a Falcon resource class."""
+def _base_class_name(class_body: str) -> str:
+    """Return the first base class name from a class definition line, or ''."""
+    m = re.match(r"class\s+\w+\s*\(\s*([A-Za-z_]\w*)", class_body)
+    return m.group(1) if m else ""
+
+
+def find_falcon_responders(
+    content: str,
+    class_name: str,
+    _visited: frozenset[str] | None = None,
+) -> list[str]:
+    """Find all on_* methods in a Falcon resource class, including inherited ones."""
+    if _visited is None:
+        _visited = frozenset()
     methods: list[str] = []
     class_pattern = re.compile(
         rf"class\s+{re.escape(class_name)}\b.*?(?=\nclass\s|\Z)",
@@ -128,6 +140,14 @@ def find_falcon_responders(content: str, class_name: str) -> list[str]:
             method_name = match.group(1)
             http_method = method_name.replace("on_", "").upper()
             methods.append(http_method)
+        base = _base_class_name(class_body)
+        if base and base not in _visited:
+            inherited = find_falcon_responders(
+                content, base, _visited | {class_name}
+            )
+            for m in inherited:
+                if m not in methods:
+                    methods.append(m)
     return methods
 
 

{deepdoc-0.4.1 → deepdoc-0.4.2}/deepdoc/planner/topology.py

@@ -41,6 +41,11 @@ _MAX_CLUSTER_DEPTH = 4
 # docs/planner_tuning.md.
 _MERGE_JACCARD = 0.60
 
+# Two clusters whose cross-call ratio exceeds this threshold merge even when
+# their file-Jaccard is low. Prevents tightly coupled micro-clusters from
+# getting separate doc pages.
+_CROSS_EDGE_DENSITY = 0.35
+
 
 @dataclass
 class TopologyCluster:
@@ -124,8 +129,16 @@ def build_topology_map(scan: "RepoScan") -> TopologyMap:
     }
 
     # ── 3. Foundational files ─────────────────────────────────────────────
+    # Augment call indegree with import indegree so that heavily-imported files
+    # (models.py, constants.py, exceptions.py) are treated as foundational even
+    # when they have few direct call-graph edges.
+    import_indegree, file_imports = _build_import_maps(scan, repo_files)
+    effective_indegree = {
+        f: max(file_indegree.get(f, 0), import_indegree.get(f, 0))
+        for f in repo_files
+    }
     threshold = max(3, int(len(repo_files) * _FOUNDATIONAL_FRACTION))
-    foundational_set = {f for f, deg in file_indegree.items() if deg >= threshold}
+    foundational_set = {f for f, deg in effective_indegree.items() if deg >= threshold}
 
     # ── 4. Entry-point files ──────────────────────────────────────────────
     entry_point_files: set[str] = set()
@@ -211,7 +224,9 @@ def build_topology_map(scan: "RepoScan") -> TopologyMap:
         if f not in file_cluster_id and f not in foundational_set
     ]
     for f in sorted(unassigned):
-        best_cid = _best_cluster_for_orphan(f, file_calls, file_called_by, proto)
+        best_cid = _best_cluster_for_orphan(
+            f, file_calls, file_called_by, proto, file_imports
+        )
         if best_cid:
             file_cluster_id[f] = best_cid
             proto[best_cid].add(f)
@@ -221,7 +236,7 @@ def build_topology_map(scan: "RepoScan") -> TopologyMap:
             proto[fallback].add(f)
 
     # ── 7. Merge high-overlap clusters ───────────────────────────────────
-    merged = _merge_proto_clusters(proto, file_cluster_id)
+    merged = _merge_proto_clusters(proto, file_cluster_id, file_calls)
 
     # ── 8. Build TopologyCluster objects ─────────────────────────────────
     clusters: list[TopologyCluster] = []
@@ -313,10 +328,12 @@ def _empty_map() -> TopologyMap:
 def _merge_proto_clusters(
     proto: dict[str, set[str]],
     file_cluster_id: dict[str, str],
+    file_calls: dict[str, set[str]] | None = None,
 ) -> dict[str, set[str]]:
-    """Merge clusters whose file Jaccard overlap exceeds _MERGE_JACCARD."""
+    """Merge clusters whose file Jaccard overlap or cross-call density is high."""
     cluster_ids = list(proto.keys())
     parent: dict[str, str] = {}
+    _fc = file_calls or {}
 
     def find(cid: str) -> str:
         while cid in parent:
@@ -347,6 +364,12 @@ def _merge_proto_clusters(
             jaccard = len(si & sj) / len(si | sj)
             if jaccard >= _MERGE_JACCARD:
                 union(ci, cj)
+                continue
+            # Also merge when cross-call traffic between the two clusters is dense
+            cross = sum(1 for f in si for c in _fc.get(f, set()) if c in sj)
+            cross += sum(1 for f in sj for c in _fc.get(f, set()) if c in si)
+            if cross and cross / min(len(si), len(sj)) >= _CROSS_EDGE_DENSITY:
+                union(ci, cj)
 
     # Re-assign file_cluster_id to canonical roots
     for f in list(file_cluster_id.keys()):
@@ -355,14 +378,79 @@ def _merge_proto_clusters(
     return {find(cid): files for cid, files in proto.items() if files}
 
 
+def _build_import_maps(
+    scan: "RepoScan",
+    repo_files: set[str],
+) -> tuple[dict[str, int], dict[str, set[str]]]:
+    """Build import indegree and file→imported-files adjacency in one pass.
+
+    Resolves relative and absolute imports to repo file paths; ignores
+    third-party/stdlib. Returns (indegree, file_imports) where:
+      - indegree[f] = number of distinct repo files that import f
+      - file_imports[f] = set of repo files that f imports
+    """
+    indegree: dict[str, int] = defaultdict(int)
+    file_imports: dict[str, set[str]] = defaultdict(set)
+
+    _suffix_index: dict[str, list[str]] = defaultdict(list)
+    for rp in repo_files:
+        no_ext = re.sub(r"\.[^/]+$", "", rp)
+        _suffix_index[no_ext].append(rp)
+        _suffix_index[no_ext.replace("/", ".")].append(rp)
+
+    import_re = re.compile(
+        r"^(?:from\s+([\w.]+)\s+import|import\s+([\w.]+))", re.MULTILINE
+    )
+
+    for src_path, pf in scan.parsed_files.items():
+        if src_path not in repo_files:
+            continue
+        pkg_dir = src_path.rsplit("/", 1)[0] if "/" in src_path else ""
+
+        for imp_str in pf.imports:
+            m = import_re.match(imp_str.strip())
+            if not m:
+                continue
+            module = (m.group(1) or m.group(2) or "").strip()
+            if not module:
+                continue
+
+            candidates: list[str] = []
+
+            if module.startswith("."):
+                dots = len(module) - len(module.lstrip("."))
+                rel_mod = module[dots:].replace(".", "/")
+                base = pkg_dir
+                for _ in range(dots - 1):
+                    base = base.rsplit("/", 1)[0] if "/" in base else ""
+                rel_path = f"{base}/{rel_mod}".lstrip("/") if rel_mod else base
+                for ext in (".py", "/__init__.py"):
+                    candidates.append(rel_path + ext)
+            else:
+                as_path = module.replace(".", "/")
+                for ext in (".py", "/__init__.py"):
+                    candidates.append(as_path + ext)
+                candidates.extend(_suffix_index.get(module, []))
+                candidates.extend(_suffix_index.get(as_path, []))
+
+            for candidate in candidates:
+                if candidate in repo_files and candidate != src_path:
+                    indegree[candidate] += 1
+                    file_imports[src_path].add(candidate)
+                    break
+
+    return dict(indegree), dict(file_imports)
+
+
 def _best_cluster_for_orphan(
     file_path: str,
     file_calls: dict[str, set[str]],
     file_called_by: dict[str, set[str]],
     proto: dict[str, set[str]],
+    import_targets: dict[str, set[str]] | None = None,
 ) -> str | None:
-    """Find the cluster an unassigned file has the most call relationships with."""
-    scores: dict[str, int] = defaultdict(int)
+    """Find the cluster an unassigned file has the most relationships with."""
+    scores: dict[str, float] = defaultdict(float)
     cluster_file_index: dict[str, str] = {}
     for cid, files in proto.items():
         for f in files:
@@ -378,6 +466,12 @@ def _best_cluster_for_orphan(
         if cid:
             scores[cid] += 1
 
+    # Import edges provide a weaker signal than call edges
+    for imp_target in (import_targets or {}).get(file_path, set()):
+        cid = cluster_file_index.get(imp_target)
+        if cid:
+            scores[cid] += 0.5
+
     if not scores:
         return None
     return max(scores, key=lambda c: scores[c])

{deepdoc-0.4.1 → deepdoc-0.4.2}/deepdoc/site/builder/__init__.py

@@ -1,4 +1,3 @@
 from .next_builder import build_next_from_plan
-from .mkdocs_builder import build_mkdocs_from_plan  # kept for compatibility
 from .mdx_utils import _first_mdx_heading, _split_leading_frontmatter, _frontmatter_has_yaml_fields, _ensure_md_frontmatter
 from .common import *

{deepdoc-0.4.1 → deepdoc-0.4.2}/deepdoc/site/builder/next_template/next.config.mjs

@@ -1,8 +1,10 @@
 /** @type {import('next').NextConfig} */
 const basePath = process.env.NEXT_PUBLIC_BASE_PATH || '';
+const isProd = process.env.NODE_ENV === 'production';
 
 const config = {
-  output: 'export',
+  // Static export only for production builds — dev mode needs dynamic rendering
+  ...(isProd ? { output: 'export' } : {}),
   basePath,
   assetPrefix: basePath || undefined,
   images: { unoptimized: true },

{deepdoc-0.4.1 → deepdoc-0.4.2}/deepdoc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepdoc
-Version: 0.4.1
+Version: 0.4.2
 Summary: Auto-generate beautiful docs from any codebase
 Author: Pranav Kumar
 License: MIT

{deepdoc-0.4.1 → deepdoc-0.4.2}/deepdoc.egg-info/SOURCES.txt

@@ -109,7 +109,6 @@ deepdoc/site/__init__.py
 deepdoc/site/builder/__init__.py
 deepdoc/site/builder/common.py
 deepdoc/site/builder/mdx_utils.py
-deepdoc/site/builder/mkdocs_builder.py
 deepdoc/site/builder/next_builder.py
 deepdoc/site/builder/next_template/.gitignore
 deepdoc/site/builder/next_template/deepdoc.config.json
@@ -156,7 +155,6 @@ tests/test_internal_docs_metadata.py
 tests/test_litellm_compat.py
 tests/test_llm_json_utils.py
 tests/test_llm_retry.py
-tests/test_mkdocs_builder.py
 tests/test_next_builder.py
 tests/test_parallel_pipeline.py
 tests/test_parser_ranges.py

{deepdoc-0.4.1 → deepdoc-0.4.2}/pyproject.toml

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

{deepdoc-0.4.1 → deepdoc-0.4.2}/tests/test_chatbot_query.py

@@ -2368,9 +2368,9 @@ def test_system_prompt_contains_project_name(tmp_path: Path) -> None:
         prompt = service._system_prompt()
 
     assert "MyProject" in prompt
-    assert "file path and line range" in prompt
-    assert "Sources" in prompt
-    assert "## Summary" in prompt
+    assert "evidence" in prompt.lower()
+    assert "cite" in prompt.lower()
+    assert "summary" in prompt.lower()
 
 
 def test_query_service_passes_loaded_indexes_into_similarity_search(

{deepdoc-0.4.1 → deepdoc-0.4.2}/tests/test_framework_support.py

@@ -263,6 +263,31 @@ app.add_route('/login', Login())
     assert endpoint.middleware == ["AuthMiddleware", "TraceMiddleware"]
 
 
+def test_falcon_inherited_responders_from_base_class():
+    content = """
+import falcon
+
+class BaseResource:
+    def on_get(self, req, res):
+        pass
+    def on_delete(self, req, res):
+        pass
+
+class UserResource(BaseResource):
+    def on_post(self, req, res):
+        pass
+
+app = falcon.App()
+app.add_route('/users', UserResource())
+"""
+    endpoints = detect_endpoints(Path("app.py"), content, "python")
+    user_endpoints = [ep for ep in endpoints if ep.path == "/users"]
+    methods = {ep.method for ep in user_endpoints}
+    assert "GET" in methods, "inherited on_get not detected"
+    assert "POST" in methods, "own on_post not detected"
+    assert "DELETE" in methods, "inherited on_delete not detected"
+
+
 def test_scan_repo_detects_vue_projects_and_sfc_signals(tmp_path):
     repo_root = tmp_path / "vue-app"
     component_dir = repo_root / "src" / "components"

{deepdoc-0.4.1 → deepdoc-0.4.2}/tests/test_planner_granularity.py

@@ -26,7 +26,6 @@ from deepdoc.planner.nav_shaping import _shape_plan_nav
 from deepdoc.planner.specializations import _ensure_database_runtime_and_interface_buckets
 from deepdoc.planner.topology import TopologyCluster, TopologyMap
 from deepdoc.prompts import PROMPT_STYLE_TEMPLATES
-from deepdoc.site.builder import build_mkdocs_from_plan
 
 
 def _make_scan(
@@ -1228,52 +1227,6 @@ def test_validate_coverage_prefers_semantic_attachment_over_module_bucket() -> N
     )
 
 
-def test_recursive_nav_builder_supports_three_levels(tmp_path: Path) -> None:
-    repo_root = tmp_path / "repo"
-    repo_root.mkdir()
-    output_dir = repo_root / "docs"
-    output_dir.mkdir()
-
-    overview = DocBucket(
-        bucket_type="system",
-        title="Overview",
-        slug="overview",
-        section="Overview",
-        description="Overview page",
-        generation_hints={"is_introduction_page": True},
-    )
-    flash = DocBucket(
-        bucket_type="architecture_component",
-        title="Flash Attention",
-        slug="flash-attention",
-        section="Model Architecture > Attention > Flash Attention",
-        description="Flash attention internals",
-    )
-    plan = DocPlan(
-        buckets=[overview, flash],
-        nav_structure={
-            "Model Architecture > Attention > Flash Attention": ["flash-attention"]
-        },
-        skipped_files=[],
-    )
-
-    (output_dir / "flash-attention.md").write_text(
-        "# Flash Attention\n", encoding="utf-8"
-    )
-
-    build_mkdocs_from_plan(
-        repo_root,
-        output_dir,
-        {"project_name": "Demo", "site": {"repo_url": ""}},
-        plan,
-        has_openapi=False,
-    )
-
-    mkdocs_yml = (repo_root / "site" / "mkdocs.yml").read_text(encoding="utf-8")
-    # Nested " > " sections become nested nav groups in mkdocs.yml.
-    assert "Model Architecture:" in mkdocs_yml
-    assert "Attention:" in mkdocs_yml
-    assert "Flash Attention: flash-attention.md" in mkdocs_yml
 
 
 def test_prompt_templates_and_prompts_include_new_granularity_support() -> None: