docwright 0.1.0__py3-none-any.whl

ai_docgen/analyzer.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import fnmatch
+import re
+from dataclasses import dataclass
+
+
+@dataclass
+class ChangedFile:
+    path: str
+
+
+class DiffAnalyzer:
+    def __init__(
+        self,
+        diff_text: str,
+        trigger_paths: list[str],
+        ignore_paths: list[str],
+    ) -> None:
+        self.diff_text = diff_text
+        self.trigger_paths = trigger_paths
+        self.ignore_paths = ignore_paths
+
+    def changed_files(self) -> list[ChangedFile]:
+        paths: list[str] = []
+        for line in self.diff_text.splitlines():
+            match = re.match(r"^\+\+\+ b/(.+)$", line)
+            if match:
+                paths.append(match.group(1))
+        return [ChangedFile(path=p) for p in paths]
+
+    def has_relevant_changes(self) -> bool:
+        for changed in self.changed_files():
+            if self.is_ignored(changed.path):
+                continue
+            if self.matches_trigger(changed.path):
+                return True
+        return False
+
+    def diff_summary(self) -> str:
+        files = self.changed_files()
+        if not files:
+            return "No changed files."
+        lines = ["Changed files:"]
+        for f in files:
+            lines.append(f"  - {f.path}")
+        lines.append("")
+        lines.append(self.diff_text[:3000])
+        if len(self.diff_text) > 3000:
+            lines.append("... (truncated)")
+        return "\n".join(lines)
+
+    def is_ignored(self, path: str) -> bool:
+        return any(fnmatch.fnmatch(path, pattern) for pattern in self.ignore_paths)
+
+    def matches_trigger(self, path: str) -> bool:
+        if not self.trigger_paths:
+            return True
+        return any(fnmatch.fnmatch(path, pattern) for pattern in self.trigger_paths)

ai_docgen/built_in_templates/readme/default.md.j2

@@ -0,0 +1,30 @@
+# {{ service_name }}
+
+<!-- AUTO:overview -->
+<!-- /AUTO:overview -->
+
+## Getting Started
+
+<!-- AUTO:getting_started -->
+<!-- /AUTO:getting_started -->
+
+## Architecture
+
+<!-- AUTO:architecture -->
+<!-- /AUTO:architecture -->
+
+## API
+
+<!-- AUTO:api -->
+<!-- /AUTO:api -->
+
+## Development
+
+<!-- AUTO:development -->
+<!-- /AUTO:development -->
+
+<!-- MANUAL -->
+## Contributing
+
+Add contributing notes here.
+<!-- /MANUAL -->

ai_docgen/built_in_templates/wiki/adr.md.j2

@@ -0,0 +1,27 @@
+# Architecture Decision Records
+
+## Recent Decisions
+
+<!-- AUTO:recent_decisions -->
+<!-- /AUTO:recent_decisions -->
+
+## Decision Index
+
+<!-- AUTO:decision_index -->
+<!-- /AUTO:decision_index -->
+
+<!-- MANUAL -->
+## ADR Template
+
+Use this format for new decisions:
+
+### ADR-NNN: Title
+
+**Status:** Proposed / Accepted / Deprecated / Superseded
+
+**Context:** What prompted this decision.
+
+**Decision:** What was decided.
+
+**Consequences:** What changes as a result.
+<!-- /MANUAL -->

ai_docgen/built_in_templates/wiki/api-contracts.md.j2

@@ -0,0 +1,20 @@
+# API Contracts
+
+<!-- AUTO:endpoints -->
+<!-- /AUTO:endpoints -->
+
+## Authentication
+
+<!-- AUTO:authentication -->
+<!-- /AUTO:authentication -->
+
+## Error Codes
+
+<!-- AUTO:error_codes -->
+<!-- /AUTO:error_codes -->
+
+<!-- MANUAL -->
+## Changelog
+
+Document breaking changes here.
+<!-- /MANUAL -->

ai_docgen/built_in_templates/wiki/architecture.md.j2

@@ -0,0 +1,25 @@
+# Architecture
+
+<!-- AUTO:overview -->
+<!-- /AUTO:overview -->
+
+## Components
+
+<!-- AUTO:components -->
+<!-- /AUTO:components -->
+
+## Data Flow
+
+<!-- AUTO:data_flow -->
+<!-- /AUTO:data_flow -->
+
+## Dependencies
+
+<!-- AUTO:dependencies -->
+<!-- /AUTO:dependencies -->
+
+<!-- MANUAL -->
+## Decision Log
+
+Document architectural decisions here.
+<!-- /MANUAL -->

ai_docgen/built_in_templates/wiki/data-model.md.j2

@@ -0,0 +1,22 @@
+# Data Model
+
+## Domain Entities
+
+<!-- AUTO:entities -->
+<!-- /AUTO:entities -->
+
+## Business Rules
+
+<!-- AUTO:business_rules -->
+<!-- /AUTO:business_rules -->
+
+## Relationships
+
+<!-- AUTO:relationships -->
+<!-- /AUTO:relationships -->
+
+<!-- MANUAL -->
+## Glossary
+
+Define domain terms here.
+<!-- /MANUAL -->

ai_docgen/built_in_templates/wiki/db-schema.md.j2

@@ -0,0 +1,22 @@
+# Database Schema
+
+## Tables
+
+<!-- AUTO:tables -->
+<!-- /AUTO:tables -->
+
+## Indexes
+
+<!-- AUTO:indexes -->
+<!-- /AUTO:indexes -->
+
+## Migrations
+
+<!-- AUTO:migrations -->
+<!-- /AUTO:migrations -->
+
+<!-- MANUAL -->
+## Migration Runbook
+
+Document manual migration steps and rollback procedures here.
+<!-- /MANUAL -->

ai_docgen/built_in_templates/wiki/development-guide.md.j2

@@ -0,0 +1,22 @@
+# Development Guide
+
+## Setup
+
+<!-- AUTO:setup -->
+<!-- /AUTO:setup -->
+
+## Running Tests
+
+<!-- AUTO:testing -->
+<!-- /AUTO:testing -->
+
+## Code Style
+
+<!-- AUTO:code_style -->
+<!-- /AUTO:code_style -->
+
+<!-- MANUAL -->
+## Team Conventions
+
+Add team-specific conventions here.
+<!-- /MANUAL -->

ai_docgen/built_in_templates/wiki/integrations.md.j2

@@ -0,0 +1,22 @@
+# Integrations
+
+## External Services
+
+<!-- AUTO:external_services -->
+<!-- /AUTO:external_services -->
+
+## Authentication & Credentials
+
+<!-- AUTO:auth_credentials -->
+<!-- /AUTO:auth_credentials -->
+
+## Data Exchange
+
+<!-- AUTO:data_exchange -->
+<!-- /AUTO:data_exchange -->
+
+<!-- MANUAL -->
+## Integration Contacts
+
+Document vendor contacts and SLA details here.
+<!-- /MANUAL -->

ai_docgen/built_in_templates/wiki/operations.md.j2

@@ -0,0 +1,27 @@
+# Operations
+
+## Deployment
+
+<!-- AUTO:deployment -->
+<!-- /AUTO:deployment -->
+
+## Monitoring
+
+<!-- AUTO:monitoring -->
+<!-- /AUTO:monitoring -->
+
+## Runbooks
+
+<!-- AUTO:runbooks -->
+<!-- /AUTO:runbooks -->
+
+## Incident Response
+
+<!-- AUTO:incident_response -->
+<!-- /AUTO:incident_response -->
+
+<!-- MANUAL -->
+## On-Call Contacts
+
+Document on-call rotation and escalation paths here.
+<!-- /MANUAL -->

ai_docgen/built_in_templates/wiki/security.md.j2

@@ -0,0 +1,22 @@
+# Security
+
+## Access Model
+
+<!-- AUTO:access_model -->
+<!-- /AUTO:access_model -->
+
+## Sensitive Data Handling
+
+<!-- AUTO:sensitive_data -->
+<!-- /AUTO:sensitive_data -->
+
+## Security Requirements
+
+<!-- AUTO:requirements -->
+<!-- /AUTO:requirements -->
+
+<!-- MANUAL -->
+## Security Contacts
+
+Document responsible disclosure process and security team contacts here.
+<!-- /MANUAL -->

ai_docgen/built_in_templates/wiki/troubleshooting.md.j2

@@ -0,0 +1,22 @@
+# Troubleshooting
+
+## Common Issues
+
+<!-- AUTO:common_issues -->
+<!-- /AUTO:common_issues -->
+
+## Diagnostics
+
+<!-- AUTO:diagnostics -->
+<!-- /AUTO:diagnostics -->
+
+## Known Limitations
+
+<!-- AUTO:known_limitations -->
+<!-- /AUTO:known_limitations -->
+
+<!-- MANUAL -->
+## Escalation Path
+
+Document when and how to escalate unresolved issues here.
+<!-- /MANUAL -->

ai_docgen/cli.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import subprocess
+from pathlib import Path
+
+import click
+
+from ai_docgen.config import Config
+from ai_docgen.engine import DocsEngine
+from ai_docgen.outputs.factory import build_output
+from ai_docgen.providers.factory import build_provider
+
+
+def get_repo_root() -> Path:
+    return Path.cwd()
+
+
+def build_engine(repo_root: Path) -> DocsEngine:
+    config = Config.load(repo_root)
+    provider = build_provider(config.provider)
+    output = build_output(config.output, repo_root)
+    return DocsEngine(repo_root=repo_root, provider=provider, output=output)
+
+
+@click.group()
+def cli() -> None:
+    """AI-powered documentation agent."""
+
+
+@cli.command()
+def init() -> None:
+    """Generate documentation from scratch."""
+    engine = build_engine(get_repo_root())
+    asyncio.run(engine.init())
+    click.echo("Documentation initialized.")
+
+
+@cli.command()
+@click.option("--dry-run", is_flag=True, help="Show what would change without writing files.")
+def run(dry_run: bool) -> None:
+    """Incrementally update documentation based on recent git diff."""
+    repo_root = get_repo_root()
+    base_sha = os.environ.get("AI_DOCGEN_BASE_SHA", "HEAD~1")
+    try:
+        diff_text = subprocess.check_output(
+            ["git", "diff", f"{base_sha}..HEAD"], cwd=repo_root
+        ).decode()
+    except subprocess.CalledProcessError:
+        diff_text = ""
+    if dry_run:
+        config = Config.load(repo_root)
+        triggers = config.triggers
+        from ai_docgen.analyzer import DiffAnalyzer
+
+        analyzer = DiffAnalyzer(
+            diff_text=diff_text,
+            trigger_paths=triggers.paths if triggers else [],
+            ignore_paths=triggers.ignore if triggers else [],
+        )
+        if analyzer.has_relevant_changes():
+            click.echo("Relevant changes detected — documentation would be updated.")
+        else:
+            click.echo("No relevant changes — documentation would be skipped.")
+        return
+    engine = build_engine(repo_root)
+    skipped = asyncio.run(engine.run(diff_text=diff_text))
+    click.echo(
+        "No relevant changes — documentation up to date." if skipped else "Documentation updated."
+    )
+
+
+@cli.command()
+def sync() -> None:
+    """Force re-sync all documentation against current templates."""
+    engine = build_engine(get_repo_root())
+    asyncio.run(engine.sync())
+    click.echo("Documentation synced.")
+
+
+@cli.command("install")
+@click.option("--auto", is_flag=True, help="Non-interactive mode with auto-detected defaults.")
+@click.option("--provider", default=None, type=click.Choice(["claude", "openai", "ollama"]))
+@click.option("--output", "output_mode", default=None, type=click.Choice(["pr", "direct"]))
+def install(auto: bool, provider: str | None, output_mode: str | None) -> None:
+    """Bootstrap this repo with ai-docgen configuration."""
+    from ai_docgen.scaffolder import Scaffolder
+
+    repo_root = get_repo_root()
+    scaffolder = Scaffolder(repo_root=repo_root)
+    profile = scaffolder.detect_profile()
+
+    if auto:
+        final_provider = provider or "claude"
+        final_output = output_mode or "pr"
+    else:
+        click.echo(
+            f"Detected: {profile.language} project '{profile.service_name}', CI: {profile.ci}"
+        )
+        final_provider = provider or click.prompt(
+            "LLM provider",
+            type=click.Choice(["claude", "openai", "ollama"]),
+            default="claude",
+        )
+        final_output = output_mode or click.prompt(
+            "Output mode",
+            type=click.Choice(["pr", "direct"]),
+            default="pr",
+        )
+
+    scaffolder.generate(profile, provider_type=final_provider, output_mode=final_output)
+    click.echo(f"Installed ai-docgen for '{profile.service_name}'.")
+    click.echo("Next: set your API key env var, then run 'make docs'.")
+
+
+@cli.command()
+@click.option("--registry", "registry_path", default=None, help="Path to registry.yml")
+def dashboard(registry_path: str | None) -> None:
+    """Show status of all registered projects."""
+    from ai_docgen.reporters.terminal import render_dashboard
+
+    path = Path(registry_path) if registry_path else Path.cwd() / ".ai-docgen" / "registry.yml"
+    render_dashboard(path)
+
+
+@cli.command()
+@click.option("--registry", "registry_path", default=None, help="Path to registry.yml")
+@click.option("--output", "output_file", default="ai-docgen-report.html", help="Output HTML file")
+def report(registry_path: str | None, output_file: str) -> None:
+    """Generate a static HTML status report."""
+    from ai_docgen.reporters.html import render_html_report
+
+    reg_path = Path(registry_path) if registry_path else Path.cwd() / ".ai-docgen" / "registry.yml"
+    render_html_report(reg_path, Path(output_file))
+    click.echo(f"Report saved to {output_file}")

ai_docgen/config.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, Field
+
+CONFIG_DIR = ".ai-docgen"
+CONFIG_FILE = "ai-docgen.yml"
+INITIALIZED_MARKER = ".initialized"
+
+
+class ProviderConfig(BaseModel):
+    type: Literal["claude", "openai", "ollama"]
+    model: str
+    api_key_env: str = "ANTHROPIC_API_KEY"
+    base_url: str | None = None
+
+
+class OutputConfig(BaseModel):
+    mode: Literal["direct", "pr"] = "pr"
+    pr_title: str = "docs: auto-update documentation"
+    branch_prefix: str = "docs/auto-"
+
+
+class TemplatesConfig(BaseModel):
+    source: Literal["builtin", "local"] = "builtin"
+    local_path: str = ".ai-docgen/templates"
+
+
+class TriggersConfig(BaseModel):
+    paths: list[str] = Field(default_factory=lambda: ["app/**", "src/**"])
+    ignore: list[str] = Field(default_factory=lambda: ["tests/**", "**/*.md"])
+
+
+class DocumentConfig(BaseModel):
+    type: Literal["readme", "wiki"]
+    template: str
+    target: str
+
+
+class RegistryConfig(BaseModel):
+    path: str = "../.ai-docgen/registry.yml"
+
+
+class Config(BaseModel):
+    provider: ProviderConfig
+    output: OutputConfig = Field(default_factory=OutputConfig)
+    templates: TemplatesConfig = Field(default_factory=TemplatesConfig)
+    triggers: TriggersConfig | None = None
+    documents: list[DocumentConfig] = Field(default_factory=list)
+    registry: RegistryConfig = Field(default_factory=RegistryConfig)
+
+    @classmethod
+    def load(cls, repo_root: Path) -> Config:
+        config_path = repo_root / CONFIG_DIR / CONFIG_FILE
+        if not config_path.exists():
+            raise FileNotFoundError(f"Config not found: {config_path}")
+        data = yaml.safe_load(config_path.read_text())
+        return cls.model_validate(data)
+
+    @classmethod
+    def is_initialized(cls, repo_root: Path) -> bool:
+        return (repo_root / CONFIG_DIR / INITIALIZED_MARKER).exists()
+
+    @classmethod
+    def mark_initialized(cls, repo_root: Path) -> None:
+        marker = repo_root / CONFIG_DIR / INITIALIZED_MARKER
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.touch()