generator.py

"""
Fleet Wiki Documentation Generator — Auto-generate documentation from fleet agents.

Scans agent repos for docstrings and README.md, generates API reference pages,
architecture diagrams from fleet config, agent status pages, and change logs.
"""

import ast
import json
import os
import re
import subprocess
from datetime import datetime, timezone
from pathlib import Path
from typing import Optional


class DocGenerator:
    """Auto-generate documentation from fleet agents."""

    def __init__(self, wiki=None, wiki_root: Optional[str | Path] = None):
        self._wiki = wiki
        self._wiki_root = Path(wiki_root) if wiki_root else None

    def _get_wiki(self):
        if self._wiki is not None:
            return self._wiki
        if self._wiki_root:
            from wiki import FleetWiki
            self._wiki = FleetWiki(self._wiki_root)
            return self._wiki
        raise RuntimeError("DocGenerator needs either a wiki instance or wiki_root")

    def scan_readme(self, repo_path: str | Path) -> Optional[dict]:
        """Scan a repository for README.md and extract key info."""
        repo = Path(repo_path)
        if not repo.exists():
            return None
        readme_paths = [
            repo / "README.md",
            repo / "readme.md",
            repo / "Readme.md",
        ]
        readme = None
        for rp in readme_paths:
            if rp.exists():
                readme = rp
                break
        if not readme:
            return None
        try:
            text = readme.read_text(encoding="utf-8")
        except OSError:
            return None
        title = repo.name
        first_h1 = re.search(r"^#\s+(.+)", text, re.MULTILINE)
        if first_h1:
            title = first_h1.group(1).strip()
        description = ""
        first_p = re.search(r"^#\s+.+\s*\n+(.+?)(?:\n#|\n\n-|\Z)", text, re.DOTALL | re.MULTILINE)
        if first_p:
            description = first_p.group(1).strip()
        return {
            "title": title,
            "description": description,
            "content": text,
            "path": str(readme),
        }

    def extract_docstrings(self, file_path: str | Path) -> list[dict]:
        """Extract docstrings from a Python module using AST."""
        path = Path(file_path)
        if not path.exists() or path.suffix != ".py":
            return []
        try:
            source = path.read_text(encoding="utf-8")
        except OSError:
            return []
        try:
            tree = ast.parse(source)
        except SyntaxError:
            return []
        results = []
        module_doc = ast.get_docstring(tree)
        if module_doc:
            results.append({
                "name": path.stem,
                "kind": "module",
                "docstring": module_doc,
                "line": 1,
            })
        for node in ast.walk(tree):
            if isinstance(node, ast.ClassDef):
                doc = ast.get_docstring(node)
                if doc:
                    results.append({
                        "name": node.name,
                        "kind": "class",
                        "docstring": doc,
                        "line": node.lineno,
                        "bases": [self._name_of(b) for b in node.bases],
                    })
            elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
                doc = ast.get_docstring(node)
                if doc:
                    args = [
                        a.arg for a in node.args.args
                        if a.arg != "self" and a.arg != "cls"
                    ]
                    results.append({
                        "name": node.name,
                        "kind": "function",
                        "docstring": doc,
                        "line": node.lineno,
                        "args": args,
                        "is_async": isinstance(node, ast.AsyncFunctionDef),
                    })
        results.sort(key=lambda x: x["line"])
        return results

    @staticmethod
    def _name_of(node) -> str:
        if isinstance(node, ast.Name):
            return node.id
        if isinstance(node, ast.Attribute):
            return f"{DocGenerator._name_of(node.value)}.{node.attr}"
        return "?"

    def generate_api_page(
        self,
        agent_name: str,
        repo_path: str | Path,
        wiki_category: str = "api-docs",
    ) -> dict:
        """Generate an API reference wiki page from a Python agent repo."""
        repo = Path(repo_path)
        if not repo.exists():
            return {"success": False, "error": f"Repo not found: {repo_path}"}
        wiki = self._get_wiki()
        readme_info = self.scan_readme(repo)
        docstrings = []
        for py_file in sorted(repo.rglob("*.py")):
            if "__pycache__" in str(py_file) or ".venv" in str(py_file):
                continue
            ds = self.extract_docstrings(py_file)
            rel = py_file.relative_to(repo)
            for d in ds:
                d["file"] = str(rel)
            docstrings.extend(ds)
        sections = []
        modules_seen = set()
        for ds in docstrings:
            if ds["kind"] == "module":
                if ds["name"] not in modules_seen:
                    sections.append(
                        f"## Module: `{ds['file']}`\n\n"
                        f"{ds['docstring']}\n"
                    )
                    modules_seen.add(ds["name"])
            elif ds["kind"] == "class":
                bases = f"({', '.join(ds.get('bases', []))})" if ds.get("bases") else ""
                sections.append(
                    f"### Class: `{ds['name']}`{bases}\n\n"
                    f"**File**: `{ds['file']}` (line {ds['line']})\n\n"
                    f"{ds['docstring']}\n"
                )
            elif ds["kind"] == "function":
                prefix = "async " if ds.get("is_async") else ""
                args = ", ".join(ds.get("args", []))
                sections.append(
                    f"#### {prefix}`{ds['name']}({args})`\n\n"
                    f"**File**: `{ds['file']}` (line {ds['line']})\n\n"
                    f"{ds['docstring']}\n"
                )
        title = f"API Reference — {agent_name}"
        if readme_info and readme_info["description"]:
            header = f"# {title}\n\n> Auto-generated API reference\n\n{readme_info['description']}\n"
        else:
            header = f"# {title}\n\n> Auto-generated API reference\n"
        content = header + "\n".join(sections)
        tags = ["api", "auto-generated", agent_name.lower().replace(" ", "-")]
        try:
            page = wiki.create_page(
                title=title,
                content=content,
                category=wiki_category,
                author="doc-generator",
                tags=tags,
            )
            return {"success": True, "page_id": page.page_id, "title": title}
        except FileExistsError:
            page = wiki.edit_page(
                page.title,
                content=content,
                author="doc-generator",
                tags=tags,
            )
            return {"success": True, "page_id": page.page_id, "title": title, "updated": True}

    def generate_architecture_overview(
        self,
        fleet_config: Optional[dict] = None,
        wiki_category: str = "architecture",
    ) -> dict:
        """Generate an architecture overview page from fleet configuration."""
        wiki = self._get_wiki()
        title = "Fleet Architecture Overview"
        if fleet_config is None:
            fleet_config = self._load_fleet_config()
        agents = fleet_config.get("agents", [])
        services = fleet_config.get("services", [])
        diagram = self._build_ascii_diagram(fleet_config)
        agent_rows = ""
        for agent in agents:
            name = agent.get("name", agent.get("id", "unknown"))
            role = agent.get("role", agent.get("description", ""))
            status = agent.get("status", "unknown")
            icon = "🟢" if status == "active" else "🟡" if status == "idle" else "🔴"
            agent_rows += f"| {icon} **{name}** | {role} | {status} |\n"
        service_rows = ""
        for svc in services:
            name = svc.get("name", svc.get("id", "unknown"))
            port = svc.get("port", "?")
            desc = svc.get("description", "")
            service_rows += f"| `{name}` | {port} | {desc} |\n"
        content = (
            f"# {title}\n\n"
            f"> Auto-generated from fleet configuration\n\n"
            f"## Architecture Diagram\n\n"
            f"```\n{diagram}\n```\n\n"
            f"## Agents ({len(agents)})\n\n"
            f"| Agent | Role | Status |\n"
            f"|-------|------|--------|\n"
            f"{agent_rows}\n"
        )
        if services:
            content += (
                f"## Services ({len(services)})\n\n"
                f"| Service | Port | Description |\n"
                f"|---------|------|-------------|\n"
                f"{service_rows}\n"
            )
        tags = ["architecture", "auto-generated", "overview"]
        try:
            page = wiki.create_page(
                title=title,
                content=content,
                category=wiki_category,
                author="doc-generator",
                tags=tags,
            )
            return {"success": True, "page_id": page.page_id, "title": title}
        except FileExistsError:
            page = wiki.edit_page(
                page.title,
                content=content,
                author="doc-generator",
                tags=tags,
            )
            return {"success": True, "page_id": page.page_id, "title": title, "updated": True}

    def _load_fleet_config(self) -> dict:
        """Try to load fleet configuration from standard locations."""
        config_paths = [
            Path(os.path.expanduser("~/.superinstance/fleet.json")),
            Path(os.path.expanduser("~/.superinstance/config.json")),
            Path("fleet.json"),
            Path("config.json"),
        ]
        for cp in config_paths:
            if cp.exists():
                try:
                    with open(cp, "r", encoding="utf-8") as f:
                        return json.load(f)
                except (json.JSONDecodeError, OSError):
                    continue
        return {
            "agents": [
                {"name": "Fleet Wiki", "role": "Documentation & Knowledge Management",
                 "status": "active"},
                {"name": "Lighthouse", "role": "Fleet Monitoring & Health Checks",
                 "status": "active"},
                {"name": "Orchestrator", "role": "Task Coordination & Routing",
                 "status": "active"},
            ],
            "services": [
                {"name": "wiki-api", "port": 8001, "description": "Wiki HTTP server"},
                {"name": "lighthouse-api", "port": 8002, "description": "Lighthouse API"},
            ],
        }

    @staticmethod
    def _build_ascii_diagram(config: dict) -> str:
        """Build a simple ASCII architecture diagram."""
        agents = config.get("agents", [])
        services = config.get("services", [])
        lines = [
            "┌─────────────────────────────────────────────┐",
            "│              FLEET ORCHESTRATOR              │",
            "└──────────┬──────────────┬──────────────────┘",
        ]
        for i, agent in enumerate(agents):
            name = agent.get("name", "?")[:20]
            connector = "├" if i < len(agents) - 1 else "└"
            branch = "│" if i < len(agents) - 1 else " "
            lines.append(f"           {connector}── [{name}]")
        lines.append("    ┌──────────┴──────────────────────┐")
        lines.append("    │         MESSAGE BUS              │")
        lines.append("    └──────────┬──────────────────────┘")
        for i, svc in enumerate(services):
            name = svc.get("name", "?")[:20]
            port = svc.get("port", "?")
            connector = "├" if i < len(services) - 1 else "└"
            branch = "│" if i < len(services) - 1 else " "
            lines.append(f"    {connector}── {name} (:{port})")
        return "\n".join(lines)

    def generate_status_page(
        self,
        lighthouse_data: Optional[dict] = None,
        wiki_category: str = "runbooks",
    ) -> dict:
        """Generate agent status pages from lighthouse data."""
        wiki = self._get_wiki()
        title = "Fleet Status Report"
        now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
        if lighthouse_data is None:
            lighthouse_data = {
                "timestamp": now,
                "agents": [
                    {"name": "Fleet Wiki", "status": "healthy", "uptime": "99.9%",
                     "last_heartbeat": now, "tasks_completed": 42},
                    {"name": "Lighthouse", "status": "healthy", "uptime": "99.8%",
                     "last_heartbeat": now, "tasks_completed": 128},
                    {"name": "Orchestrator", "status": "healthy", "uptime": "99.7%",
                     "last_heartbeat": now, "tasks_completed": 256},
                ],
            }
        agent_rows = ""
        for agent in lighthouse_data.get("agents", []):
            name = agent.get("name", "unknown")
            status = agent.get("status", "unknown")
            uptime = agent.get("uptime", "N/A")
            tasks = agent.get("tasks_completed", 0)
            heartbeat = agent.get("last_heartbeat", "N/A")
            icon = "🟢" if status == "healthy" else "🟡" if status == "degraded" else "🔴"
            agent_rows += f"| {icon} {name} | {status} | {uptime} | {tasks} | {heartbeat} |\n"
        content = (
            f"# {title}\n\n"
            f"> Generated: {now}\n\n"
            f"## Agent Health\n\n"
            f"| Agent | Status | Uptime | Tasks | Last Heartbeat |\n"
            f"|-------|--------|--------|-------|----------------|\n"
            f"{agent_rows}\n"
        )
        tags = ["status", "auto-generated", "health"]
        try:
            page = wiki.create_page(
                title=title,
                content=content,
                category=wiki_category,
                author="doc-generator",
                tags=tags,
            )
            return {"success": True, "page_id": page.page_id, "title": title}
        except FileExistsError:
            page = wiki.edit_page(
                page.title,
                content=content,
                author="doc-generator",
                tags=tags,
            )
            return {"success": True, "page_id": page.page_id, "title": title, "updated": True}

    def generate_changelog(
        self,
        repo_path: str | Path,
        wiki_category: str = "general",
        max_commits: int = 50,
    ) -> dict:
        """Generate a change log from git history."""
        repo = Path(repo_path)
        if not repo.exists():
            return {"success": False, "error": f"Repo not found: {repo_path}"}
        wiki = self._get_wiki()
        try:
            result = subprocess.run(
                ["git", "log", f"-{max_commits}", "--pretty=format:%h|%ai|%an|%s", "--no-merges"],
                capture_output=True, text=True, cwd=str(repo), timeout=10,
            )
            if result.returncode != 0:
                return {"success": False, "error": "Failed to read git log"}
            commits = []
            for line in result.stdout.strip().split("\n"):
                if not line.strip():
                    continue
                parts = line.split("|", 3)
                if len(parts) >= 4:
                    commits.append({
                        "hash": parts[0],
                        "date": parts[1][:10],
                        "author": parts[2],
                        "message": parts[3],
                    })
        except (subprocess.TimeoutExpired, FileNotFoundError):
            return {"success": False, "error": "Git not available"}
        if not commits:
            return {"success": False, "error": "No commits found"}
        grouped: dict[str, list] = {}
        for commit in commits:
            date = commit["date"]
            grouped.setdefault(date, []).append(commit)
        sections = []
        for date in sorted(grouped.keys(), reverse=True):
            day_commits = grouped[date]
            entries = "\n".join(
                f"- **{c['hash']}** {c['message']} ({c['author']})"
                for c in day_commits
            )
            sections.append(f"### {date}\n\n{entries}\n")
        repo_name = repo.name
        title = f"Changelog — {repo_name}"
        content = (
            f"# {title}\n\n"
            f"> Auto-generated from git history\n\n"
            f"## Recent Changes\n\n"
            + "\n".join(sections)
        )
        tags = ["changelog", "auto-generated", repo_name.lower()]
        try:
            page = wiki.create_page(
                title=title,
                content=content,
                category=wiki_category,
                author="doc-generator",
                tags=tags,
            )
            return {"success": True, "page_id": page.page_id, "title": title}
        except FileExistsError:
            page = wiki.edit_page(
                page.title,
                content=content,
                author="doc-generator",
                tags=tags,
            )
            return {"success": True, "page_id": page.page_id, "title": title, "updated": True}