ctrlcode 0.1.0__py3-none-any.whl

ctrlcode/cleanup/doc_gardening.py

@@ -0,0 +1,388 @@
+"""Documentation gardening automation."""
+
+import logging
+import re
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DocHealthReport:
+    """Documentation health report."""
+
+    total_docs: int
+    stale_docs: list[dict[str, Any]]
+    broken_links: list[dict[str, Any]]
+    orphaned_docs: list[dict[str, Any]]
+    undocumented_apis: list[dict[str, Any]]
+    overall_health_score: float
+
+
+class DocGardener:
+    """Automated documentation maintenance."""
+
+    def __init__(self, workspace_root: Path, docs_dir: str = "docs"):
+        """
+        Initialize doc gardener.
+
+        Args:
+            workspace_root: Root directory of workspace
+            docs_dir: Documentation directory (relative to workspace)
+        """
+        self.workspace_root = Path(workspace_root)
+        self.docs_dir = self.workspace_root / docs_dir
+        self.stale_threshold_days = 90
+
+    def scan_documentation(self) -> DocHealthReport:
+        """
+        Scan documentation and generate health report.
+
+        Returns:
+            Documentation health report
+        """
+        logger.info("Scanning documentation...")
+
+        stale_docs = self._find_stale_docs()
+        broken_links = self._find_broken_links()
+        orphaned_docs = self._find_orphaned_docs()
+        undocumented_apis = self._find_undocumented_apis()
+
+        total_docs = sum(1 for _ in self.docs_dir.rglob("*.md"))
+
+        # Calculate health score (0-100)
+        health_score = self._calculate_health_score(
+            total_docs, stale_docs, broken_links, orphaned_docs, undocumented_apis
+        )
+
+        return DocHealthReport(
+            total_docs=total_docs,
+            stale_docs=stale_docs,
+            broken_links=broken_links,
+            orphaned_docs=orphaned_docs,
+            undocumented_apis=undocumented_apis,
+            overall_health_score=health_score,
+        )
+
+    def _find_stale_docs(self) -> list[dict[str, Any]]:
+        """Find documentation files that haven't been updated recently."""
+        stale_docs = []
+
+        for md_file in self.docs_dir.rglob("*.md"):
+            try:
+                # Get last modified time from git
+                result = subprocess.run(
+                    ["git", "log", "-1", "--format=%ct", str(md_file)],
+                    cwd=self.workspace_root,
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+
+                if result.returncode == 0 and result.stdout.strip():
+                    last_modified = int(result.stdout.strip())
+                    last_modified_date = datetime.fromtimestamp(last_modified)
+                    days_old = (datetime.now() - last_modified_date).days
+
+                    if days_old > self.stale_threshold_days:
+                        stale_docs.append({
+                            "file": str(md_file.relative_to(self.workspace_root)),
+                            "days_old": days_old,
+                            "last_modified": last_modified_date.isoformat(),
+                        })
+            except Exception as e:
+                logger.debug(f"Error checking {md_file}: {e}")
+                continue
+
+        return sorted(stale_docs, key=lambda x: x["days_old"], reverse=True)
+
+    def _find_broken_links(self) -> list[dict[str, Any]]:
+        """Find broken cross-references in documentation."""
+        broken_links = []
+
+        for md_file in self.docs_dir.rglob("*.md"):
+            try:
+                content = md_file.read_text()
+
+                # Find all markdown links
+                links = re.findall(r'\[([^\]]+)\]\(([^\)]+)\)', content)
+
+                for link_text, link_url in links:
+                    # Skip external links
+                    if link_url.startswith(("http://", "https://", "#")):
+                        continue
+
+                    # Resolve relative link
+                    link_path = (md_file.parent / link_url).resolve()
+
+                    # Check if target exists
+                    if not link_path.exists():
+                        broken_links.append({
+                            "file": str(md_file.relative_to(self.workspace_root)),
+                            "link_text": link_text,
+                            "target": link_url,
+                            "line": self._find_line_number(content, link_url),
+                        })
+
+            except Exception as e:
+                logger.debug(f"Error checking links in {md_file}: {e}")
+                continue
+
+        return broken_links
+
+    def _find_orphaned_docs(self) -> list[dict[str, Any]]:
+        """Find documentation files that aren't linked from anywhere."""
+        all_docs = set(self.docs_dir.rglob("*.md"))
+        linked_docs = set()
+
+        # Find all links from all docs
+        for md_file in self.docs_dir.rglob("*.md"):
+            try:
+                content = md_file.read_text()
+                links = re.findall(r'\[([^\]]+)\]\(([^\)]+)\)', content)
+
+                for _, link_url in links:
+                    if not link_url.startswith(("http://", "https://", "#")):
+                        link_path = (md_file.parent / link_url).resolve()
+                        if link_path in all_docs:
+                            linked_docs.add(link_path)
+            except Exception:
+                continue
+
+        # Also consider README.md and index files as non-orphans
+        entry_points = {
+            self.docs_dir / "README.md",
+            self.docs_dir / "index.md",
+            self.docs_dir / "INDEX.md",
+        }
+        linked_docs.update(p for p in entry_points if p.exists())
+
+        orphaned = all_docs - linked_docs
+
+        return [
+            {"file": str(doc.relative_to(self.workspace_root))}
+            for doc in sorted(orphaned)
+        ]
+
+    def _find_undocumented_apis(self) -> list[dict[str, Any]]:
+        """Find public APIs that lack documentation."""
+        undocumented = []
+
+        # Scan Python files for public classes/functions
+        src_dir = self.workspace_root / "src"
+        if not src_dir.exists():
+            return []
+
+        for py_file in src_dir.rglob("*.py"):
+            # Skip test files and private modules
+            if "test" in str(py_file) or py_file.name.startswith("_"):
+                continue
+
+            try:
+                content = py_file.read_text()
+
+                # Find public classes
+                classes = re.findall(r'^class\s+([A-Z][A-Za-z0-9_]*)', content, re.MULTILINE)
+
+                # Find public functions
+                functions = re.findall(r'^def\s+([a-z][a-z0-9_]*)', content, re.MULTILINE)
+
+                # Check if documented (has docstring)
+                for name in classes + functions:
+                    # Simple heuristic: look for docstring after definition
+                    pattern = rf'(class|def)\s+{re.escape(name)}.*?:\s*("""|\'\'\')(.*?)("""|\'\'\')'
+                    if not re.search(pattern, content, re.DOTALL):
+                        undocumented.append({
+                            "file": str(py_file.relative_to(self.workspace_root)),
+                            "name": name,
+                            "type": "class" if name[0].isupper() else "function",
+                        })
+
+            except Exception as e:
+                logger.debug(f"Error checking {py_file}: {e}")
+                continue
+
+        return undocumented[:20]  # Limit to first 20
+
+    def _calculate_health_score(
+        self,
+        total_docs: int,
+        stale_docs: list,
+        broken_links: list,
+        orphaned_docs: list,
+        undocumented_apis: list,
+    ) -> float:
+        """
+        Calculate overall documentation health score.
+
+        Args:
+            total_docs: Total number of doc files
+            stale_docs: List of stale docs
+            broken_links: List of broken links
+            orphaned_docs: List of orphaned docs
+            undocumented_apis: List of undocumented APIs
+
+        Returns:
+            Health score (0-100)
+        """
+        if total_docs == 0:
+            return 100.0
+
+        # Start with perfect score
+        score = 100.0
+
+        # Deduct for issues (with different weights)
+        score -= (len(stale_docs) / total_docs) * 30  # Max 30 points
+        score -= min(len(broken_links) * 5, 20)  # Max 20 points
+        score -= (len(orphaned_docs) / total_docs) * 15  # Max 15 points
+        score -= min(len(undocumented_apis) * 2, 35)  # Max 35 points
+
+        return max(0.0, score)
+
+    def _find_line_number(self, content: str, search_text: str) -> int:
+        """Find line number of text in content."""
+        for i, line in enumerate(content.split("\n"), start=1):
+            if search_text in line:
+                return i
+        return 0
+
+    def generate_report_markdown(self, report: DocHealthReport) -> str:
+        """
+        Generate markdown report from health report.
+
+        Args:
+            report: Documentation health report
+
+        Returns:
+            Markdown formatted report
+        """
+        md = f"""# Documentation Health Report
+
+Generated: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
+
+## Summary
+
+- **Total Documentation Files**: {report.total_docs}
+- **Overall Health Score**: {report.overall_health_score:.1f}/100
+
+## Issues Found
+
+### Stale Documentation ({len(report.stale_docs)})
+
+Documentation not updated in >{self.stale_threshold_days} days:
+
+"""
+
+        for doc in report.stale_docs[:10]:  # Show top 10
+            md += f"- `{doc['file']}` - {doc['days_old']} days old\n"
+
+        if len(report.stale_docs) > 10:
+            md += f"\n...and {len(report.stale_docs) - 10} more\n"
+
+        md += f"""
+
+### Broken Links ({len(report.broken_links)})
+
+"""
+
+        for link in report.broken_links[:10]:
+            md += f"- `{link['file']}:{link['line']}` - [{link['link_text']}]({link['target']})\n"
+
+        if len(report.broken_links) > 10:
+            md += f"\n...and {len(report.broken_links) - 10} more\n"
+
+        md += f"""
+
+### Orphaned Documentation ({len(report.orphaned_docs)})
+
+Documentation files not linked from anywhere:
+
+"""
+
+        for doc in report.orphaned_docs[:10]:
+            md += f"- `{doc['file']}`\n"
+
+        if len(report.orphaned_docs) > 10:
+            md += f"\n...and {len(report.orphaned_docs) - 10} more\n"
+
+        md += f"""
+
+### Undocumented APIs ({len(report.undocumented_apis)})
+
+Public classes/functions without docstrings:
+
+"""
+
+        for api in report.undocumented_apis[:10]:
+            md += f"- `{api['file']}` - {api['type']} `{api['name']}`\n"
+
+        if len(report.undocumented_apis) > 10:
+            md += f"\n...and {len(report.undocumented_apis) - 10} more\n"
+
+        md += """
+
+## Recommendations
+
+"""
+
+        if report.stale_docs:
+            md += "1. Review and update stale documentation\n"
+        if report.broken_links:
+            md += "2. Fix broken cross-references\n"
+        if report.orphaned_docs:
+            md += "3. Link orphaned docs from index or archive them\n"
+        if report.undocumented_apis:
+            md += "4. Add docstrings to public APIs\n"
+
+        if report.overall_health_score < 70:
+            md += "\n⚠️ **Documentation health is below 70%** - prioritize improvements\n"
+        elif report.overall_health_score >= 90:
+            md += "\n✅ **Documentation health is excellent!**\n"
+
+        return md
+
+    def auto_fix_stale_dates(self, dry_run: bool = False) -> list[dict[str, Any]]:
+        """
+        Auto-fix stale dates by updating "last reviewed" markers.
+
+        Args:
+            dry_run: If True, don't actually modify files
+
+        Returns:
+            List of files updated
+        """
+        updated_files = []
+
+        for md_file in self.docs_dir.rglob("*.md"):
+            try:
+                content = md_file.read_text()
+
+                # Look for "last reviewed" marker
+                pattern = r'(Last reviewed|Last updated):\s*(\d{4}-\d{2}-\d{2})'
+                match = re.search(pattern, content, re.IGNORECASE)
+
+                if match:
+                    old_date = match.group(2)
+                    new_date = datetime.now().strftime("%Y-%m-%d")
+
+                    if old_date != new_date:
+                        new_content = content.replace(match.group(0), f"{match.group(1)}: {new_date}")
+
+                        if not dry_run:
+                            md_file.write_text(new_content)
+
+                        updated_files.append({
+                            "file": str(md_file.relative_to(self.workspace_root)),
+                            "old_date": old_date,
+                            "new_date": new_date,
+                        })
+
+            except Exception as e:
+                logger.debug(f"Error updating {md_file}: {e}")
+                continue
+
+        return updated_files