deepdoc 1.9.3__tar.gz → 2.0.0__tar.gz

{deepdoc-1.9.3 → deepdoc-2.0.0}/PKG-INFO

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

{deepdoc-1.9.3 → deepdoc-2.0.0}/deepdoc/__init__.py

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

deepdoc-2.0.0/deepdoc/changelog_writer.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .persistence_v2 import append_changelog_entry, load_changelog, load_plan, save_plan
+
+
+def record_and_write(
+    repo_root: Path,
+    output_dir: Path,
+    *,
+    commit: str,
+    commit_message: str,
+    commit_date: str,
+    strategy: str,
+    pages_updated: list[str],
+    files_changed: list[str],
+    is_initial: bool = False,
+) -> None:
+    """Append one changelog entry and regenerate whats-changed.mdx."""
+    entry = {
+        "commit": commit[:8],
+        "date": commit_date,
+        "commit_message": commit_message,
+        "strategy": strategy,
+        "pages_updated": pages_updated,
+        "files_changed": files_changed[:20],
+        "is_initial": is_initial,
+    }
+    append_changelog_entry(repo_root, entry)
+    write_whats_changed_page(repo_root, output_dir)
+
+
+def write_whats_changed_page(repo_root: Path, output_dir: Path) -> None:
+    """Write docs/whats-changed.mdx from .deepdoc/changelog.json."""
+    entries = load_changelog(repo_root)
+    mdx = _build_mdx(entries)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    (output_dir / "whats-changed.mdx").write_text(mdx, encoding="utf-8")
+    _ensure_in_nav(repo_root)
+
+
+def _build_mdx(entries: list[dict]) -> str:
+    lines = [
+        "---",
+        'title: "What\'s Changed"',
+        'description: "Documentation changes per commit"',
+        "---",
+        "",
+        "# What's Changed",
+        "",
+    ]
+
+    if not entries:
+        lines.append("No changes recorded yet — this is the initial documentation.")
+        return "\n".join(lines)
+
+    lines.append("<Accordions>")
+    for entry in entries:
+        date = entry.get("date", "")
+        msg = entry.get("commit_message", "update")[:80]
+        sha = entry.get("commit", "")
+        pages = entry.get("pages_updated", [])
+        files = entry.get("files_changed", [])
+        is_initial = entry.get("is_initial", False)
+
+        title = f"{date} — {msg} ({sha})"
+        lines.append(f'<Accordion title="{title}">')
+        lines.append("")
+
+        if is_initial:
+            lines.append(f"**{len(pages)} pages generated** — initial documentation run.")
+        else:
+            if pages:
+                page_links = ", ".join(f"[{_slug_to_title(s)}](/{s})" for s in pages)
+                lines.append(f"**{len(pages)} page(s) updated:** {page_links}")
+            else:
+                lines.append("No pages regenerated.")
+
+        if files and not is_initial:
+            file_list = ", ".join(f"`{f}`" for f in files[:10])
+            if len(files) > 10:
+                file_list += f" +{len(files) - 10} more"
+            lines.append("")
+            lines.append(f"**Files changed:** {file_list}")
+
+        lines.append("")
+        lines.append("</Accordion>")
+
+    lines.append("</Accordions>")
+    return "\n".join(lines)
+
+
+def _slug_to_title(slug: str) -> str:
+    return slug.replace("-", " ").title()
+
+
+def _ensure_in_nav(repo_root: Path) -> None:
+    """Add whats-changed to Start Here section of the saved plan if not already there."""
+    plan = load_plan(repo_root)
+    if plan is None or not hasattr(plan, "nav_structure"):
+        return
+    section = plan.nav_structure.setdefault("Start Here", [])
+    if "whats-changed" not in section:
+        section.append("whats-changed")
+    save_plan(plan, repo_root)

{deepdoc-1.9.3 → deepdoc-2.0.0}/deepdoc/cli.py

@@ -1200,13 +1200,17 @@ def _warn_if_deprecated_generated_version(cfg: dict, repo_root: Path) -> None:
     if not warning_cfg.get("enabled", True):
         return
 
-    minimum_version = str(warning_cfg.get("minimum_version") or "1.0.0")
     generated_version = _detect_generated_deepdoc_version(
         repo_root, repo_root / str(cfg.get("output_dir", "docs") or "docs")
     )
     if generated_version is None:
         return
-    if _version_tuple(generated_version) >= _version_tuple(minimum_version):
+
+    # Warn when the docs were generated by a different major version of the CLI.
+    # Minor/patch bumps are backwards-compatible — no need to nag.
+    gen_major = _version_tuple(generated_version)[0]
+    cli_major = _version_tuple(__version__)[0]
+    if gen_major >= cli_major:
         return
 
     resolved_root = repo_root.resolve()
@@ -1214,19 +1218,15 @@ def _warn_if_deprecated_generated_version(cfg: dict, repo_root: Path) -> None:
         return
     _DEPRECATED_VERSION_WARNING_REPOS.add(resolved_root)
 
-    upgrade_command = str(
-        warning_cfg.get("upgrade_command")
-        or "python3 -m pip install --upgrade deepdoc"
-    )
     console.print(
         Panel.fit(
-            "[bold yellow]DeepDoc upgrade recommended[/bold yellow]\n\n"
-            f"This repository has generated docs from DeepDoc [bold]{generated_version}[/bold], "
-            f"which is older than the supported baseline [bold]{minimum_version}[/bold].\n"
-            "Upgrade the CLI before generating or updating docs:\n\n"
-            f"[bold]{upgrade_command}[/bold]\n\n"
-            "To change or disable this warning, update "
-            "`compatibility.deprecated_version_warning.*` in `.deepdoc.yaml`.",
+            "[bold yellow]Docs need regeneration[/bold yellow]\n\n"
+            f"Your docs were generated with DeepDoc [bold]{generated_version}[/bold] "
+            f"but the current CLI is [bold]{__version__}[/bold] (different major version).\n"
+            "Run the following to bring them up to date:\n\n"
+            "[bold]deepdoc generate[/bold]\n\n"
+            "To disable this warning: set "
+            "`compatibility.deprecated_version_warning.enabled: false` in `.deepdoc.yaml`.",
             border_style="yellow",
         )
     )

{deepdoc-1.9.3 → deepdoc-2.0.0}/deepdoc/generator/generation.py

@@ -1072,6 +1072,7 @@ Re-run `deepdoc generate` to retry.
             "deepdoc_generated_version": DEEPDOC_VERSION,
             "deepdoc_status": status_value,
             "deepdoc_evidence_files": evidence_files[:50],
+            "deepdoc_prereqs": bucket.depends_on,
         }
         return _merge_frontmatter_fields(content, fields)
 

{deepdoc-1.9.3 → deepdoc-2.0.0}/deepdoc/generator/post_processors.py

@@ -957,6 +957,10 @@ def repair_mdx_component_blocks(content: str) -> str:
 
         content = pattern.sub(_rewrite, content)
 
+    # Fix Accordion nesting first (inserts missing </Accordion> before </Accordions>)
+    # so the subsequent count-based repair sees balanced tags and doesn't double-add.
+    content = _repair_accordion_nesting(content)
+
     for component in multiline_components:
         open_count = len(re.findall(rf"<{component}(?:\s[^>]*)?>", content))
         close_count = len(re.findall(rf"</{component}>", content))
@@ -968,6 +972,38 @@ def repair_mdx_component_blocks(content: str) -> str:
     return content
 
 
+def _repair_accordion_nesting(content: str) -> str:
+    """Fix Accordion nesting issues emitted by the LLM.
+
+    Two cases handled:
+    1. Missing </Accordion> before </Accordions> — inserts them in the right place.
+    2. Swapped order (</Accordions> then </Accordion>) — strips the orphaned
+       </Accordion> that appears after </Accordions> with no matching open tag.
+    """
+    import re as _re
+
+    def _fix_block(m: re.Match) -> str:
+        block = m.group(0)
+        opens = len(_re.findall(r"<Accordion(?:\s[^>]*)?>", block))
+        closes = len(_re.findall(r"</Accordion>", block))
+        deficit = opens - closes
+        if deficit <= 0:
+            return block
+        return block[:-len("</Accordions>")] + ("</Accordion>\n" * deficit) + "</Accordions>"
+
+    content = re.sub(
+        r"<Accordions(?:\s[^>]*)?>[\s\S]*?</Accordions>",
+        _fix_block,
+        content,
+    )
+
+    # Strip orphaned </Accordion> tags that appear after </Accordions>
+    # (the LLM sometimes emits </Accordions>\n</Accordion> in the wrong order)
+    content = re.sub(r"(</Accordions>)(\s*</Accordion>)+", r"\1", content)
+
+    return content
+
+
 _PROVENANCE_KEYS = frozenset({
     "deepdoc_generated_at",
     "deepdoc_generated_commit",

{deepdoc-1.9.3 → deepdoc-2.0.0}/deepdoc/persistence_v2.py

@@ -37,6 +37,8 @@ LEDGER_FILE = "ledger.json"
 FILE_MAP_FILE = "file_map.json"
 STATE_FILE = "state.json"
 SYNC_RECEIPT_FILE = "sync_receipt.json"
+CHANGELOG_FILE = "changelog.json"
+CHANGELOG_MAX_ENTRIES = 50
 ENGINE_FINGERPRINT = "routes_repo_resolution_v2_trimmed_scope"
 
 # Legacy top-level files (kept for backwards-compat)
@@ -108,6 +110,31 @@ def load_sync_state(repo_root: Path) -> dict[str, Any] | None:
         return None
 
 
+def append_changelog_entry(repo_root: Path, entry: dict[str, Any]) -> None:
+    """Append one entry to .deepdoc/changelog.json, capped at CHANGELOG_MAX_ENTRIES."""
+    path = _state_dir(repo_root) / CHANGELOG_FILE
+    entries: list[dict[str, Any]] = []
+    if path.exists():
+        try:
+            entries = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            entries = []
+    entries.insert(0, entry)
+    entries = entries[:CHANGELOG_MAX_ENTRIES]
+    path.write_text(json.dumps(entries, indent=2), encoding="utf-8")
+
+
+def load_changelog(repo_root: Path) -> list[dict[str, Any]]:
+    """Read .deepdoc/changelog.json. Returns empty list if not present or corrupt."""
+    path = _state_dir(repo_root) / CHANGELOG_FILE
+    if not path.exists():
+        return []
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return []
+
+
 def save_sync_receipt(repo_root: Path, receipt: dict[str, Any]) -> None:
     """Write a top-level receipt for the latest generate/update sync run."""
     path = _state_dir(repo_root) / SYNC_RECEIPT_FILE

{deepdoc-1.9.3 → deepdoc-2.0.0}/deepdoc/pipeline_v2.py

@@ -51,8 +51,10 @@ from .openapi import (
     parse_openapi_spec,
     spec_to_context_string,
 )
+from .changelog_writer import record_and_write as _record_changelog
 from .persistence_v2 import (
     cleanup_stale_generated_files,
+    load_changelog,
     load_generation_ledger,
     prune_generation_ledger,
     save_all,
@@ -424,6 +426,19 @@ class PipelineV2:
                     "replanned": True,
                 },
             )
+            changelog_exists = bool(load_changelog(self.repo_root))
+            _commit_obj = _repo.head.commit
+            _record_changelog(
+                self.repo_root,
+                self.output_dir,
+                commit=head_sha,
+                commit_message=_commit_obj.message.strip().splitlines()[0],
+                commit_date=_commit_obj.committed_datetime.strftime("%Y-%m-%d"),
+                strategy="full_generate",
+                pages_updated=[b.slug for b in plan.buckets],
+                files_changed=[],
+                is_initial=not changelog_exists,
+            )
         except Exception:
             pass  # Not a git repo or detached HEAD — skip silently
 

{deepdoc-1.9.3 → deepdoc-2.0.0}/deepdoc/site/builder/scaffold_files.py

@@ -1421,7 +1421,9 @@ def _docs_page_tsx() -> str:
         """\
         import { notFound } from 'next/navigation';
         import { DocsBody, DocsPage } from 'fumadocs-ui/page';
+        import { findNeighbour } from 'fumadocs-core/server';
         import { docsSource } from '@/lib/source';
+        import { pageTree } from '@/lib/page-tree.generated';
         import { getMDXComponents } from '@/mdx-components';
         import type { ComponentType } from 'react';
         import type { TOCItemType } from 'fumadocs-core/server';
@@ -1442,6 +1444,7 @@ def _docs_page_tsx() -> str:
           const meta = page.data as {
             deepdoc_generated_at?: string;
             deepdoc_generated_commit?: string;
+            deepdoc_prereqs?: string[];
           };
           const lastIndexed = meta.deepdoc_generated_at
             ? new Intl.DateTimeFormat('en-GB', {
@@ -1459,10 +1462,32 @@ def _docs_page_tsx() -> str:
               : commitId
                 ? `Last indexed: (${commitId})`
                 : null;
+          const prereqs = meta.deepdoc_prereqs ?? [];
+          const { previous, next } = findNeighbour(pageTree, page.url);
 
           return (
-            <DocsPage toc={toc}>
+            <DocsPage toc={toc} prev={previous ?? false} next={next ?? false}>
               <DocsBody>
+                {prereqs.length > 0 ? (
+                  <p
+                    style={{
+                      marginTop: 0,
+                      marginBottom: '0.5rem',
+                      fontSize: '0.875rem',
+                      color: 'var(--color-fd-muted-foreground)',
+                    }}
+                  >
+                    {'Read first: '}
+                    {prereqs.map((slug: string, i: number) => (
+                      <span key={slug}>
+                        <a href={`/${slug}`} style={{ textDecoration: 'underline' }}>
+                          {slug.replace(/-/g, ' ').replace(/\\b\\w/g, (c: string) => c.toUpperCase())}
+                        </a>
+                        {i < prereqs.length - 1 ? ', ' : ''}
+                      </span>
+                    ))}
+                  </p>
+                ) : null}
                 {lastIndexedLabel ? (
                   <p
                     style={{

{deepdoc-1.9.3 → deepdoc-2.0.0}/deepdoc/smart_update_v2.py

@@ -35,14 +35,17 @@ from .generator import summarize_generation_results
 from .llm import LLMClient
 from .manifest import Manifest
 from .parser import supported_extensions
+from .changelog_writer import record_and_write as _record_changelog
 from .persistence_v2 import (
     ENGINE_FINGERPRINT,
+    cleanup_stale_generated_files,
     find_stale_buckets,
     ledger_summary,
     load_generation_ledger,
     load_plan,
     load_scan_cache,
     load_sync_state,
+    prune_generation_ledger,
     save_all,
     save_sync_receipt,
     save_sync_state,
@@ -51,10 +54,6 @@ from .v2_models import DocPlan, endpoint_owned_files, tracked_bucket_files
 
 console = Console()
 
-# What fraction of total files changed triggers a replan
-REPLAN_THRESHOLD = 0.20
-# New files added beyond this count also triggers replan
-NEW_FILES_REPLAN_THRESHOLD = 5
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -98,19 +97,13 @@ class ChangeSet:
             and not self.orphaned_bucket_slugs
         ):
             return "noop"
-        if self.deleted_files or self.orphaned_bucket_slugs:
-            return "full_replan"
-        if len(self.new_files) >= NEW_FILES_REPLAN_THRESHOLD:
-            return "full_replan"
-        # If total changes exceed the percentage threshold, replan
         if (
-            self.total_plan_files > 0
-            and self.total_changes / self.total_plan_files > REPLAN_THRESHOLD
+            self.new_files
+            or self.new_integration_signals
+            or self.deleted_files
+            or self.orphaned_bucket_slugs
+            or self.endpoint_structure_changed
         ):
-            return "full_replan"
-        if self.endpoint_structure_changed:
-            return "full_replan"
-        if self.new_files or self.new_integration_signals:
             return "targeted_replan"
         return "incremental"
 
@@ -257,11 +250,12 @@ class SmartUpdater:
             return stats
 
         elif sync_plan.strategy == "full_replan":
+            # Only reachable via engine_mismatch or explicit force_replan override
+            # in _build_sync_plan — never auto-triggered by ChangeSet.strategy.
             console.print(
                 Panel(
                     "[bold yellow]Strategy: Full Replan[/bold yellow]\n"
-                    f"Reason: {len(change_set.new_files)} new files, "
-                    f"{len(change_set.deleted_files)} deleted files",
+                    "Reason: engine fingerprint changed or replan explicitly forced",
                     border_style="yellow",
                 )
             )
@@ -276,6 +270,12 @@ class SmartUpdater:
                     f"{len(change_set.new_integration_signals)} new integration signal(s): "
                     f"{', '.join(change_set.new_integration_signals[:5])}"
                 )
+            if change_set.deleted_files:
+                reasons.append(f"{len(change_set.deleted_files)} deleted file(s)")
+            if change_set.orphaned_bucket_slugs:
+                reasons.append(f"{len(change_set.orphaned_bucket_slugs)} orphaned bucket(s)")
+            if change_set.endpoint_structure_changed:
+                reasons.append("endpoint structure changed")
             console.print(
                 Panel(
                     "[bold cyan]Strategy: Targeted Replan[/bold cyan]\n"
@@ -308,12 +308,13 @@ class SmartUpdater:
         stats["chatbot_failed"] = run_result.chatbot_failed
 
         # ── Step 4: Rebuild site nav ───────────────────────────────────
-        if executed_strategy not in {"noop", "full_replan"}:
+        if executed_strategy != "noop":
             updated_plan = load_plan(self.repo_root) or plan
             self._rebuild_nav(updated_plan)
 
         # ── Step 5: Persist sync baseline ──────────────────────────────
-        # full_replan already saves via pipeline_v2.py, so skip it here
+        # When full_replan fires (engine_mismatch / force_replan), pipeline_v2
+        # already saves state internally — skip double-save only for that case.
         if executed_strategy != "full_replan":
             self._save_update_sync_state(
                 target_commit=sync_plan.target_commit,
@@ -323,6 +324,8 @@ class SmartUpdater:
                 plan=plan,
             )
         self._save_update_sync_receipt(sync_plan, run_result)
+        if executed_strategy != "noop":
+            self._append_changelog(sync_plan, run_result)
 
         console.print(
             Panel.fit(
@@ -390,6 +393,54 @@ class SmartUpdater:
             chatbot_failed=bool(result.get("chatbot_error")),
         )
 
+    def _handle_deleted_files(
+        self, plan: DocPlan, change_set: ChangeSet
+    ) -> DocPlan:
+        """Remove deleted files from bucket owned_files; clean up fully empty buckets."""
+        if not change_set.deleted_files and not change_set.orphaned_bucket_slugs:
+            return plan
+
+        deleted_set = set(change_set.deleted_files)
+        orphaned_set = set(change_set.orphaned_bucket_slugs)
+        updated_buckets = []
+        removed_slugs: list[str] = []
+
+        for bucket in plan.buckets:
+            if bucket.slug in orphaned_set:
+                removed_slugs.append(bucket.slug)
+                continue
+            if any(f in deleted_set for f in bucket.owned_files):
+                bucket.owned_files = [
+                    f for f in bucket.owned_files if f not in deleted_set
+                ]
+                if bucket.slug not in change_set.stale_bucket_slugs:
+                    change_set.stale_bucket_slugs.append(bucket.slug)
+            updated_buckets.append(bucket)
+
+        if removed_slugs:
+            keep_slugs = {b.slug for b in updated_buckets}
+            deleted_paths = cleanup_stale_generated_files(
+                self.repo_root, self.output_dir, keep_slugs
+            )
+            prune_generation_ledger(self.repo_root, keep_slugs)
+            if deleted_paths:
+                console.print(
+                    f"  [dim]Removed {len(deleted_paths)} doc(s) for deleted bucket(s): "
+                    f"{', '.join(removed_slugs)}[/dim]"
+                )
+            plan.nav_structure = {
+                section: [s for s in slugs if s not in removed_slugs]
+                for section, slugs in plan.nav_structure.items()
+            }
+            plan.nav_structure = {
+                section: slugs
+                for section, slugs in plan.nav_structure.items()
+                if slugs
+            }
+
+        plan.buckets = updated_buckets
+        return plan
+
     def _targeted_replan(self, plan: DocPlan, change_set: ChangeSet) -> UpdateRunResult:
         """Replan only to discover new buckets for new integrations/files,
         then merge with existing plan and regenerate stale buckets.
@@ -403,6 +454,9 @@ class SmartUpdater:
             scan_repo as bucket_scan_repo,
         )
 
+        # Step 0: clean up deleted files and orphaned buckets before any LLM work
+        plan = self._handle_deleted_files(plan, change_set)
+
         # Invalidate call graph cache if source files changed
         _invalidate_call_graph_cache(
             self.repo_root,
@@ -434,9 +488,8 @@ class SmartUpdater:
 
         if change_set.new_files and not added:
             console.print(
-                "[yellow]⚠ New files did not map cleanly to new buckets — escalating to full replan[/yellow]"
+                "[yellow]⚠ New files did not map to new buckets — they will be picked up on the next explicit replan[/yellow]"
             )
-            return self._full_replan_and_generate()
 
         if added:
             console.print(f"  [green]+{len(added)} new bucket(s) discovered:[/green]")
@@ -1128,6 +1181,36 @@ class SmartUpdater:
             },
         )
 
+    def _append_changelog(
+        self,
+        sync_plan: UpdateSyncPlan,
+        run_result: UpdateRunResult,
+    ) -> None:
+        """Append a changelog entry and regenerate whats-changed.mdx."""
+        try:
+            import git as _git
+
+            repo = _git.Repo(self.repo_root)
+            commit_obj = repo.commit(sync_plan.target_commit)
+            commit_message = commit_obj.message.strip().splitlines()[0]
+            commit_date = commit_obj.committed_datetime.strftime("%Y-%m-%d")
+        except Exception:
+            commit_message = "update"
+            commit_date = ""
+
+        _record_changelog(
+            self.repo_root,
+            self.output_dir,
+            commit=sync_plan.target_commit,
+            commit_message=commit_message,
+            commit_date=commit_date,
+            strategy=run_result.strategy,
+            pages_updated=list(run_result.updated_slugs),
+            files_changed=list(
+                sync_plan.change_set.changed_files + sync_plan.change_set.new_files
+            ),
+        )
+
     def _resolve_head_commit(self) -> str:
         """Return the current HEAD commit SHA."""
         import git as _git

{deepdoc-1.9.3 → deepdoc-2.0.0}/deepdoc.egg-info/PKG-INFO

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

{deepdoc-1.9.3 → deepdoc-2.0.0}/deepdoc.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ deepdoc/__main__.py
 deepdoc/_legacy_types.py
 deepdoc/benchmark_v2.py
 deepdoc/call_graph.py
+deepdoc/changelog_writer.py
 deepdoc/cli.py
 deepdoc/config.py
 deepdoc/manifest.py
@@ -113,6 +114,7 @@ deepdoc/site/builder/scaffold_files.py
 deepdoc/site/builder/templates.py
 tests/test_benchmark_scorecard.py
 tests/test_call_graph.py
+tests/test_changelog.py
 tests/test_chatbot_config.py
 tests/test_chatbot_embeddings.py
 tests/test_chatbot_eval.py

{deepdoc-1.9.3 → deepdoc-2.0.0}/pyproject.toml

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