docuchango 0.1.0__py3-none-any.whl

docuchango/__init__.py

@@ -0,0 +1,49 @@
+"""Docuchango - Docusaurus Validation and Repair Framework.
+
+A comprehensive toolkit for Docusaurus documentation validation, testing, and repair.
+Designed for opinionated micro-CMS documentation systems with human-agent collaboration.
+
+This package provides:
+- Documentation validation (frontmatter, links, formatting)
+- Automated fixing of common documentation issues
+- Testing utilities for documentation workflows
+- CLI tools for all operations
+
+Example:
+    >>> from docuchango.validator import DocValidator
+    >>> validator = DocValidator(repo_root=".")
+    >>> validator.scan_documents()
+    >>> validator.check_code_blocks()
+"""
+
+__version__ = "0.1.0"
+__author__ = "Jacob Repp"
+__email__ = "jacobrepp@gmail.com"
+
+# Core validation exports
+from docuchango.schemas import (
+    ADRFrontmatter,
+    GenericDocFrontmatter,
+    MemoFrontmatter,
+    RFCFrontmatter,
+)
+
+# Testing framework exports
+from docuchango.testing import AGFAssertions, AGFCLIRunner, CLIResult, HealthChecker
+
+__all__ = [
+    # Version info
+    "__version__",
+    "__author__",
+    "__email__",
+    # Schemas
+    "ADRFrontmatter",
+    "RFCFrontmatter",
+    "MemoFrontmatter",
+    "GenericDocFrontmatter",
+    # Testing
+    "AGFCLIRunner",
+    "CLIResult",
+    "AGFAssertions",
+    "HealthChecker",
+]

docuchango/__main__.py

@@ -0,0 +1,10 @@
+"""Main entry point for docuchango package.
+
+Allows running the package as a module:
+    python -m docuchango
+"""
+
+from docuchango.cli import main
+
+if __name__ == "__main__":
+    main()

docuchango/cli.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""Docuchango CLI.
+
+Docusaurus validation and repair framework for opinionated micro-CMS documentation.
+"""
+
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+@click.group()
+@click.version_option(version="0.1.0")
+def main():
+    """Docuchango - Docusaurus validation and repair framework."""
+    pass
+
+
+@main.command()
+@click.option(
+    "--repo-root",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=Path.cwd(),
+    help="Repository root directory (default: current directory)",
+)
+@click.option("--verbose", "-v", is_flag=True, help="Enable verbose output")
+@click.option("--skip-build", is_flag=True, help="Skip Docusaurus build validation")
+@click.option("--fix", is_flag=True, help="Auto-fix issues where possible")
+def validate(
+    repo_root: Path,
+    verbose: bool,
+    skip_build: bool,
+    fix: bool,
+):
+    """Validate documentation files for correctness.
+
+    Validates markdown documents for:
+    - YAML frontmatter format and required fields
+    - Internal link reachability
+    - Markdown formatting issues
+    - Consistent ADR/RFC numbering
+    - MDX compilation compatibility
+    - Docusaurus build validation (unless --skip-build)
+    """
+    try:
+        from docuchango.validator import DocValidator
+    except ImportError as e:
+        console.print(f"[red]Error importing validator: {e}[/red]")
+        sys.exit(2)
+
+    console.print("[bold blue]🔍 Validating Documentation[/bold blue]\n")
+    console.print(f"Repository root: {repo_root}")
+    console.print(f"Verbose: {verbose}")
+    console.print(f"Skip build: {skip_build}")
+    console.print(f"Auto-fix: {fix}\n")
+
+    try:
+        validator = DocValidator(repo_root=repo_root, verbose=verbose)
+        validator.scan_documents()
+        validator.check_code_blocks()
+        validator.check_formatting()
+
+        # Check if we should run build validation
+        if not skip_build:
+            # This would need to be implemented based on the validate_docs.py logic
+            pass
+
+        # Check for errors
+        has_errors = False
+        for doc in validator.documents:
+            if doc.errors:
+                has_errors = True
+                console.print(f"[red]✗[/red] {doc.file_path}")
+                for error in doc.errors:
+                    console.print(f"  [red]{error}[/red]")
+
+        if validator.errors:
+            has_errors = True
+            for error in validator.errors:
+                console.print(f"[red]{error}[/red]")
+
+        if has_errors:
+            console.print("\n[bold red]❌ Validation failed[/bold red]")
+            sys.exit(1)
+        else:
+            console.print("\n[bold green]✅ All documents valid[/bold green]")
+            sys.exit(0)
+
+    except Exception as e:
+        console.print(f"[bold red]Error during validation: {e}[/bold red]")
+        if verbose:
+            import traceback
+
+            traceback.print_exc()
+        sys.exit(2)
+
+
+@main.group()
+def fix():
+    """Fix documentation issues automatically."""
+    pass
+
+
+@fix.command("all")
+@click.option(
+    "--repo-root",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=Path.cwd(),
+    help="Repository root directory (default: current directory)",
+)
+@click.option("--dry-run", is_flag=True, help="Show what would be fixed without making changes")
+def fix_all(repo_root: Path, dry_run: bool):
+    """Run all automatic fixes on documentation."""
+
+    console.print("[bold blue]🔧 Fixing Documentation Issues[/bold blue]\n")
+    if dry_run:
+        console.print("[yellow]DRY RUN - No changes will be made[/yellow]\n")
+
+    # This would call the fix functions
+    # For now, just show what would happen
+    console.print("Would fix:")
+    console.print("  • Trailing whitespace")
+    console.print("  • Code fence languages")
+    console.print("  • Blank lines before fences")
+    console.print("  • Missing frontmatter fields")
+
+
+@fix.command("links")
+@click.option(
+    "--repo-root",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=Path.cwd(),
+    help="Repository root directory (default: current directory)",
+)
+@click.option("--dry-run", is_flag=True, help="Show what would be fixed without making changes")
+def fix_links(repo_root: Path, dry_run: bool):
+    """Fix broken links in documentation."""
+    console.print("[bold blue]🔗 Fixing Broken Links[/bold blue]\n")
+    if dry_run:
+        console.print("[yellow]DRY RUN - No changes will be made[/yellow]\n")
+
+    # Import and run the fix_broken_links module
+    console.print("Fixing broken links...")
+
+
+@fix.command("code-blocks")
+@click.option(
+    "--repo-root",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=Path.cwd(),
+    help="Repository root directory (default: current directory)",
+)
+@click.option("--dry-run", is_flag=True, help="Show what would be fixed without making changes")
+def fix_code_blocks(repo_root: Path, dry_run: bool):
+    """Fix code block formatting issues."""
+    console.print("[bold blue]📝 Fixing Code Blocks[/bold blue]\n")
+    if dry_run:
+        console.print("[yellow]DRY RUN - No changes will be made[/yellow]\n")
+
+    console.print("Fixing code blocks...")
+
+
+@main.group()
+def test():
+    """Testing utilities and helpers."""
+    pass
+
+
+@test.command("health")
+@click.option("--url", default="http://localhost:8080", help="Service URL to check")
+@click.option("--timeout", default=30, help="Timeout in seconds")
+def test_health(url: str, timeout: int):
+    """Check service health."""
+    console.print(f"[bold blue]🏥 Checking Health: {url}[/bold blue]\n")
+
+    # Placeholder for health check implementation
+    # HealthChecker would be initialized and used here
+    console.print(f"[yellow]ℹ[/yellow] Health check not yet implemented for {url}")
+    console.print(f"[dim]Timeout: {timeout}s[/dim]")
+    console.print("[green]✓[/green] Placeholder completed")
+
+
+@main.command()
+@click.option(
+    "--guide",
+    type=click.Choice(["bootstrap", "agent", "best-practices"], case_sensitive=False),
+    default="bootstrap",
+    help="Which guide to display (default: bootstrap)",
+)
+@click.option(
+    "--output",
+    type=click.Path(path_type=Path),
+    help="Save guide to file instead of displaying",
+)
+def bootstrap(guide: str, output: Path | None):
+    """Display or save docs-cms bootstrap and agent guides.
+
+    Provides quick access to documentation for setting up and using docs-cms:
+
+    - bootstrap: Step-by-step setup guide for docs-cms
+    - agent: Instructions for AI agents using docs-cms
+    - best-practices: Best practices for agent-CMS interaction
+
+    Examples:
+
+        \b
+        # Display bootstrap guide
+        docuchango bootstrap
+
+        \b
+        # Display agent guide
+        docuchango bootstrap --guide agent
+
+        \b
+        # Save bootstrap guide to file
+        docuchango bootstrap --output /path/to/BOOTSTRAP_GUIDE.md
+    """
+    # Map guide names to file names
+    guide_files = {
+        "bootstrap": "BOOTSTRAP_GUIDE.md",
+        "agent": "AGENT_GUIDE.md",
+        "best-practices": "BEST_PRACTICES.md",
+    }
+
+    guide_file = guide_files[guide]
+
+    # Try to find the guide in the package
+    try:
+        # First, try to find it in the installed package
+        import importlib.resources as resources
+
+        try:
+            # Python 3.9+
+            guide_path = resources.files("docuchango") / ".." / "docs" / guide_file
+            guide_content = guide_path.read_text()
+        except AttributeError:
+            # Python 3.8 fallback
+            with resources.path("docuchango", "__init__.py") as pkg_path:
+                docs_dir = pkg_path.parent.parent / "docs"
+                guide_path = docs_dir / guide_file
+                guide_content = guide_path.read_text()
+
+    except (FileNotFoundError, ModuleNotFoundError):
+        # Fallback: try relative to the script location
+        script_dir = Path(__file__).parent.parent
+        guide_path = script_dir / "docs" / guide_file
+
+        if not guide_path.exists():
+            from rich.console import Console as RichConsole
+
+            stderr_console = RichConsole(stderr=True)
+            stderr_console.print(f"[red]✗[/red] Guide not found: {guide_file}")
+            stderr_console.print(f"[dim]Searched in: {guide_path}[/dim]")
+            sys.exit(1)
+
+        guide_content = guide_path.read_text()
+
+    # Output or display
+    if output:
+        output.write_text(guide_content)
+        console.print(f"[green]✓[/green] Saved {guide} guide to: {output}")
+    else:
+        # Display with rich markdown rendering
+        from rich.markdown import Markdown
+
+        console.print(Markdown(guide_content))
+
+
+# Export the validate command as a separate entry point
+def validate_main():
+    """Entry point for agf-validate command."""
+    validate()
+
+
+# Export the fix command as a separate entry point
+def fix_main():
+    """Entry point for agf-fix command."""
+    fix()
+
+
+if __name__ == "__main__":
+    main()

docuchango/fixes/__init__.py

@@ -0,0 +1,17 @@
+"""Documentation fix modules.
+
+This package contains modules for automatically fixing common documentation issues:
+- broken_links: Fix broken internal and cross-reference links
+- code_blocks: Fix code block formatting and language tags
+- docs: General documentation fixes (whitespace, frontmatter, etc.)
+- internal_links: Fix internal link references
+- mdx_syntax: Fix MDX syntax issues
+"""
+
+__all__ = [
+    "broken_links",
+    "code_blocks",
+    "docs",
+    "internal_links",
+    "mdx_syntax",
+]

docuchango/fixes/broken_links.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Fix broken documentation links by converting full filenames to short-form IDs.
+
+Usage:
+    uv run tooling/fix_broken_links.py [--dry-run]
+"""
+
+import argparse
+import re
+from pathlib import Path
+
+# Mapping of common broken link patterns to correct formats
+LINK_FIXES = {
+    # RFCs - full filename to short ID
+    r"/rfc/rfc-(\d+)-[a-z-]+": r"/rfc/rfc-\1",
+    r"/prism-data-layer/rfc/rfc-(\d+)-[a-z-]+": r"/rfc/rfc-\1",
+    r"/prism-data-layer/rfc/RFC-(\d+)-[a-z-]+": r"/rfc/rfc-\1",
+    r"\.\/RFC-(\d+)-[a-z-]+": r"/rfc/rfc-\1",
+    # ADRs - full filename to short ID
+    r"/adr/adr-(\d+)-[a-z-]+": r"/adr/adr-\1",
+    r"/prism-data-layer/adr/adr-(\d+)-[a-z-]+": r"/adr/adr-\1",
+    # MEMOs - full filename to short ID
+    r"/memos/memo-(\d+)-[a-z-]+": r"/memos/memo-\1",
+    r"/prism-data-layer/memos/memo-(\d+)-[a-z-]+": r"/memos/memo-\1",
+    # Remove /prism-data-layer prefix from already short paths
+    r"/prism-data-layer/(adr/adr-\d+)": r"/\1",
+    r"/prism-data-layer/(rfc/rfc-\d+)": r"/\1",
+    r"/prism-data-layer/(memos/memo-\d+)": r"/\1",
+    r"/prism-data-layer/(prd)": r"/\1",
+    r"/prism-data-layer/(key-documents)": r"/\1",
+    r"/prism-data-layer/(netflix/[a-z\-]+)": r"/\1",
+    # Fix incorrectly converted RFC numbers (rfc-211 should be rfc-021)
+    r"/rfc/rfc-211([^0-9])": r"/rfc/rfc-021\1",
+    r"/rfc/rfc-211$": r"/rfc/rfc-021",
+    # Fix netflix links - add netflix- prefix to all document names
+    r"/netflix/abstractions\b": r"/netflix/netflix-abstractions",
+    r"/netflix/write-ahead-log\b": r"/netflix/netflix-write-ahead-log",
+    r"/netflix/scale\b": r"/netflix/netflix-scale",
+    r"/netflix/dual-write-migration\b": r"/netflix/netflix-dual-write-migration",
+    r"/netflix/data-evolve-migration\b": r"/netflix/netflix-data-evolve-migration",
+    r"/netflix/summary\b": r"/netflix/netflix-summary",
+    r"/netflix/key-use-cases\b": r"/netflix/netflix-key-use-cases",
+    r"/netflix/netflix-index\b": r"/netflix/netflix-index",  # This one is already correct but keeping for completeness
+    r"/netflix/video1\b": r"/netflix/netflix-video1",
+    r"/netflix/video2\b": r"/netflix/netflix-video2",
+}
+
+
+def fix_links_in_file(file_path: Path, dry_run: bool = False) -> int:
+    """Fix broken links in a single file."""
+    try:
+        content = file_path.read_text()
+        original_content = content
+        changes = 0
+
+        for pattern, replacement in LINK_FIXES.items():
+            new_content, count = re.subn(pattern, replacement, content)
+            if count > 0:
+                changes += count
+                content = new_content
+
+        if content != original_content:
+            if dry_run:
+                print(f"Would fix {changes} links in: {file_path}")
+            else:
+                file_path.write_text(content)
+                print(f"Fixed {changes} links in: {file_path}")
+            return changes
+
+        return 0
+    except Exception as e:
+        print(f"Error processing {file_path}: {e}")
+        return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Fix broken documentation links")
+    parser.add_argument("--dry-run", action="store_true", help="Show what would be changed without making changes")
+    args = parser.parse_args()
+
+    repo_root = Path(__file__).parent.parent
+    docs_cms = repo_root / "docs-cms"
+    docusaurus_docs = repo_root / "docusaurus" / "docs"
+
+    total_changes = 0
+    total_files = 0
+
+    # Process all markdown files in docs-cms
+    for md_file in docs_cms.rglob("*.md"):
+        changes = fix_links_in_file(md_file, args.dry_run)
+        if changes > 0:
+            total_changes += changes
+            total_files += 1
+
+    # Process all markdown files in docusaurus/docs
+    for md_file in docusaurus_docs.rglob("*.md"):
+        changes = fix_links_in_file(md_file, args.dry_run)
+        if changes > 0:
+            total_changes += changes
+            total_files += 1
+
+    print(f"\n{'[DRY RUN] ' if args.dry_run else ''}Fixed {total_changes} links in {total_files} files")
+
+
+if __name__ == "__main__":
+    main()

docuchango/fixes/code_blocks.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Auto-fix code block formatting issues
+
+Fixes:
+1. Missing blank lines before opening code fences
+2. Missing blank lines after closing code fences
+3. Closing fences with extra text (```bash -> ```)
+4. Opening fences without language (``` -> ```text)
+5. Unclosed code blocks
+
+Usage:
+    uv run python -m tooling.fix_code_blocks
+"""
+
+import re
+import sys
+from pathlib import Path
+
+
+def fix_code_blocks(file_path: Path) -> tuple[bool, list[str]]:
+    """Fix code block issues in a file"""
+    changes = []
+
+    try:
+        content = file_path.read_text(encoding="utf-8")
+        lines = content.split("\n")
+        fixed_lines = []
+
+        in_code_block = False
+        in_frontmatter = False
+        frontmatter_count = 0
+        frontmatter_end_line = None
+        i = 0
+
+        while i < len(lines):
+            line = lines[i]
+            stripped = line.strip()
+
+            # Track frontmatter
+            if stripped == "---":
+                frontmatter_count += 1
+                if frontmatter_count == 1:
+                    in_frontmatter = True
+                elif frontmatter_count == 2:
+                    in_frontmatter = False
+                    frontmatter_end_line = i
+                fixed_lines.append(line)
+                i += 1
+                continue
+
+            # Skip frontmatter content
+            if in_frontmatter:
+                fixed_lines.append(line)
+                i += 1
+                continue
+
+            # Check for code fence (match beginning of stripped line)
+            fence_match = re.match(r"^(`{3,})(.*)$", stripped)
+            if fence_match:
+                fence_backticks = fence_match.group(1)
+                remainder = fence_match.group(2).strip()
+
+                if not in_code_block:
+                    # Opening fence
+                    content_start = (frontmatter_end_line + 1) if frontmatter_end_line is not None else 0
+                    is_after_frontmatter = frontmatter_end_line is not None and i == frontmatter_end_line + 1
+                    is_document_start = i == content_start
+
+                    # Check if previous line was blank
+                    previous_line_blank = len(fixed_lines) == 0 or not fixed_lines[-1].strip()
+
+                    # Add blank line before if needed
+                    if not previous_line_blank and not is_after_frontmatter and not is_document_start:
+                        fixed_lines.append("")
+                        changes.append(f"Line {i + 1}: Added blank line before opening fence")
+
+                    # Check if language is missing
+                    if not remainder:
+                        fixed_lines.append(f"{fence_backticks}text")
+                        changes.append(f"Line {i + 1}: Added 'text' language to bare opening fence")
+                    else:
+                        fixed_lines.append(line)
+
+                    in_code_block = True
+                else:
+                    # Closing fence
+                    if remainder:
+                        # Remove extra text from closing fence
+                        fixed_lines.append(fence_backticks)
+                        changes.append(f"Line {i + 1}: Removed extra text from closing fence (```{remainder} -> ```)")
+                    else:
+                        fixed_lines.append(line)
+
+                    in_code_block = False
+
+                    # Check next line for blank line requirement
+                    if i + 1 < len(lines):
+                        next_line = lines[i + 1].strip()
+                        if next_line:  # Next line has content
+                            # Insert blank line after closing fence
+                            i += 1  # Move to next line
+                            fixed_lines.append("")  # Add blank line
+                            changes.append(f"Line {i}: Added blank line after closing fence")
+                            continue  # Will process next line in next iteration
+            else:
+                # Regular line (not a code fence)
+                if not in_code_block:
+                    fixed_lines.append(line)
+                else:
+                    # Inside code block - preserve exactly
+                    fixed_lines.append(line)
+
+            i += 1
+
+        # Check for unclosed code block
+        if in_code_block:
+            fixed_lines.append("```")
+            changes.append("End of file: Added closing fence for unclosed code block")
+
+        # Write back if changes were made
+        if changes:
+            new_content = "\n".join(fixed_lines)
+            file_path.write_text(new_content, encoding="utf-8")
+            return True, changes
+
+        return False, []
+
+    except Exception as e:
+        print(f"Error processing {file_path}: {e}", file=sys.stderr)
+        return False, []
+
+
+def main():
+    repo_root = Path(__file__).parent.parent
+    docs_cms = repo_root / "docs-cms"
+
+    print("🔧 Auto-fixing code block issues...\n")
+
+    total_files = 0
+    fixed_files = 0
+    total_changes = 0
+
+    # Process all markdown files
+    for md_file in docs_cms.rglob("*.md"):
+        # Skip README and index files
+        if md_file.name in ["README.md", "index.md"]:
+            continue
+
+        total_files += 1
+        modified, changes = fix_code_blocks(md_file)
+
+        if modified:
+            fixed_files += 1
+            total_changes += len(changes)
+            print(f"✓ {md_file.relative_to(repo_root)}")
+            for change in changes:
+                print(f"  • {change}")
+            print()
+
+    print(f"\n{'=' * 80}")
+    print("📊 Summary:")
+    print(f"   Files scanned: {total_files}")
+    print(f"   Files fixed: {fixed_files}")
+    print(f"   Total changes: {total_changes}")
+    print(f"{'=' * 80}\n")
+
+    if fixed_files > 0:
+        print("✅ Fixes applied! Run validation again to verify.")
+    else:
+        print("✅ No fixes needed.")
+
+
+if __name__ == "__main__":
+    main()