Documentation Writing

"""GitHub Pages Documentation Site Generation.

A complete solution for generating, validating, and deploying documentation
sites to GitHub Pages using MkDocs with the Material theme.

Philosophy:
- Single responsibility: Generate docs -> Validate docs -> Deploy docs
- Standard library when possible, external deps only where necessary (mkdocs, pyyaml)
- Self-contained and regeneratable
- Zero-BS: No stubs, no placeholders - everything works

Public API (the "studs"):
    SiteConfig: Configuration for site generation
    DeploymentConfig: Configuration for deployment
    GenerationResult: Result of site generation
    ValidationResult: Result of three-pass validation
    ValidationIssue: Single validation issue
    DeploymentResult: Result of deployment

    generate_site: Generate documentation site from docs/
    validate_site: Run three-pass validation
    deploy_site: Deploy to GitHub Pages
    preview_locally: Start local preview server
"""

from dataclasses import dataclass
from pathlib import Path
from typing import Literal


@dataclass
class SiteConfig:
    """Configuration for site generation.

    Attributes:
        project_name: Name of the project (used in site title)
        project_url: GitHub repository URL
        docs_dir: Path to documentation directory (default: "docs")
        output_dir: Path for generated site output (default: "site")
        theme: MkDocs theme to use (default: "material")
        theme_features: List of Material theme features to enable
        nav_structure: Custom navigation structure (auto-generated if None)
    """

    project_name: str
    project_url: str
    docs_dir: str | Path = "docs"
    output_dir: str | Path = "site"
    theme: str = "material"
    theme_features: list[str] | None = None
    nav_structure: dict | None = None


@dataclass
class DeploymentConfig:
    """Configuration for deployment.

    Attributes:
        site_dir: Path to generated site directory
        repo_path: Path to git repository root (default: ".")
        commit_message: Commit message for deployment (default: "Update docs")
        force_push: Whether to force push (DANGEROUS - default: False)
    """

    site_dir: str | Path
    repo_path: str | Path = "."
    commit_message: str = "Update docs"
    force_push: bool = False


@dataclass
class GenerationResult:
    """Result of site generation.

    Attributes:
        success: Whether generation succeeded
        site_dir: Path to generated site directory
        pages: List of generated page paths
        errors: List of error messages
        warnings: List of warning messages
        config_file: Path to generated mkdocs.yml
    """

    success: bool
    site_dir: Path
    pages: list[str]
    errors: list[str]
    warnings: list[str]
    config_file: Path | None


@dataclass
class ValidationIssue:
    """Single validation issue.

    Attributes:
        severity: Issue severity level ("error", "warning", "info")
        pass_number: Which validation pass found this (1, 2, or 3)
        location: File path and optionally line number
        message: Description of the issue
        suggestion: Optional suggestion for fixing the issue
    """

    severity: Literal["error", "warning", "info"]
    pass_number: int
    location: str
    message: str
    suggestion: str | None = None


@dataclass
class ValidationResult:
    """Result of three-pass validation.

    Attributes:
        passed: Whether validation passed all thresholds
        issues: List of all validation issues found
        pass1_coverage: Coverage percentage (target: 100%)
        pass2_clarity_score: Clarity score (target: >= 80%)
        pass3_grounded_pct: Percentage of grounded content (target: >= 95%)
    """

    passed: bool
    issues: list[ValidationIssue]
    pass1_coverage: float
    pass2_clarity_score: float
    pass3_grounded_pct: float


@dataclass
class DeploymentResult:
    """Result of deployment.

    Attributes:
        success: Whether deployment succeeded
        branch: Branch deployed to (usually "gh-pages")
        commit_sha: SHA of the deployment commit (None if failed)
        url: GitHub Pages URL (None if failed)
        errors: List of error messages
    """

    success: bool
    branch: str
    commit_sha: str | None
    url: str | None
    errors: list[str]


# Import implementations after dataclasses are defined
from .deployer import deploy_site
from .generator import generate_site, preview_locally
from .validator import validate_site

__all__ = [
    # Configuration classes
    "SiteConfig",
    "DeploymentConfig",
    # Result classes
    "GenerationResult",
    "ValidationResult",
    "ValidationIssue",
    "DeploymentResult",
    # Main functions
    "generate_site",
    "validate_site",
    "deploy_site",
    "preview_locally",
]

"""GitHub Pages deployer for documentation sites.

Deploys generated documentation sites to GitHub Pages via gh-pages branch.

Philosophy:
- Single responsibility: Deploy site to GitHub Pages
- Safe by default: Never force push unless explicitly requested
- Proper git workflow with rollback on failure
- Clear error messages for common issues
"""

import shutil
import subprocess
import tempfile
from pathlib import Path

from . import DeploymentConfig, DeploymentResult


def deploy_site(config: DeploymentConfig) -> DeploymentResult:
    """Deploy documentation site to GitHub Pages.

    Args:
        config: Deployment configuration

    Returns:
        DeploymentResult with deployment status

    Raises:
        TypeError: If config is None
        ValueError: If site_dir doesn't exist or is empty
        PermissionError: If unable to copy files
    """
    if config is None:
        raise TypeError("Config cannot be None")

    site_path = Path(config.site_dir)
    repo_path = Path(config.repo_path)
    errors: list[str] = []

    # Validate site directory exists and has content
    if not site_path.exists():
        raise ValueError(f"Site directory not found: {config.site_dir}")

    site_contents = list(site_path.iterdir())
    if not site_contents:
        raise ValueError(f"Site directory is empty: {config.site_dir}")

    # Check git status (should be clean or we might lose changes)
    try:
        is_clean = _check_git_status(repo_path)
        if not is_clean:
            # Allow deployment with uncommitted changes, but warn
            pass
    except Exception as e:
        errors.append(f"Git status check failed: {e}")
        return DeploymentResult(
            success=False,
            branch="gh-pages",
            commit_sha=None,
            url=None,
            errors=errors,
        )

    # Get current branch to return to after deployment
    try:
        original_branch = _get_current_branch(repo_path)
    except Exception:
        original_branch = "main"

    # Get repository URL for constructing Pages URL
    try:
        repo_url = _get_repo_url(repo_path)
        pages_url = _construct_pages_url(repo_url)
    except Exception:
        repo_url = ""
        pages_url = None

    # Create a temporary directory for the deployment
    with tempfile.TemporaryDirectory() as tmpdir:
        tmp_path = Path(tmpdir)

        # Copy site contents to temp directory
        try:
            for item in site_path.iterdir():
                if item.is_dir():
                    shutil.copytree(item, tmp_path / item.name)
                else:
                    shutil.copy2(item, tmp_path / item.name)
        except PermissionError:
            raise

        # Validate branch name before operations
        _validate_branch_name("gh-pages")

        # Check if gh-pages branch exists
        branch_exists = _branch_exists(repo_path, "gh-pages")

        try:
            if branch_exists:
                # Switch to existing gh-pages branch
                _run_git_command(repo_path, ["checkout", "gh-pages"])
            else:
                # Create orphan gh-pages branch
                _run_git_command(repo_path, ["checkout", "--orphan", "gh-pages"])
                # Remove all files from the new branch
                _run_git_command(repo_path, ["rm", "-rf", "."], check=False)

            # Clear the directory (except .git)
            for item in repo_path.iterdir():
                if item.name != ".git":
                    if item.is_dir():
                        shutil.rmtree(item)
                    else:
                        item.unlink()

            # Copy site contents to repo root
            for item in tmp_path.iterdir():
                dest = repo_path / item.name
                if item.is_dir():
                    shutil.copytree(item, dest)
                else:
                    shutil.copy2(item, dest)

            # Add .nojekyll file to disable Jekyll processing
            (repo_path / ".nojekyll").touch()

            # Stage all changes
            _run_git_command(repo_path, ["add", "."])

            # Check if there are changes to commit
            status_result = _run_git_command(
                repo_path, ["status", "--porcelain"], capture_output=True
            )

            if not status_result.stdout.strip():
                # No changes to commit
                _switch_branch(repo_path, original_branch)
                return DeploymentResult(
                    success=True,
                    branch="gh-pages",
                    commit_sha=None,
                    url=pages_url,
                    errors=["No changes to deploy"],
                )

            # Commit changes
            _run_git_command(repo_path, ["commit", "-m", config.commit_message])

            # Get commit SHA
            sha_result = _run_git_command(repo_path, ["rev-parse", "HEAD"], capture_output=True)
            commit_sha = sha_result.stdout.strip()

            # Push to remote
            push_args = ["push", "origin", "gh-pages"]
            if config.force_push:
                push_args.insert(1, "--force")

            try:
                _run_git_command(repo_path, push_args)
            except subprocess.CalledProcessError as e:
                # CalledProcessError always has stderr when capture_output=True
                errors.append(f"push failed: {e.stderr if e.stderr else str(e)}")
                # Rollback to original branch
                _switch_branch(repo_path, original_branch)
                return DeploymentResult(
                    success=False,
                    branch="gh-pages",
                    commit_sha=commit_sha,
                    url=None,
                    errors=errors,
                )

            # Switch back to original branch
            _switch_branch(repo_path, original_branch)

            return DeploymentResult(
                success=True,
                branch="gh-pages",
                commit_sha=commit_sha,
                url=pages_url,
                errors=[],
            )

        except subprocess.CalledProcessError as e:
            # CalledProcessError always has stderr when capture_output=True
            error_msg = e.stderr if e.stderr else str(e)
            errors.append(f"Git operation failed: {error_msg}")

            # Try to rollback to original branch
            try:
                _switch_branch(repo_path, original_branch)
            except Exception:
                pass

            return DeploymentResult(
                success=False,
                branch="gh-pages",
                commit_sha=None,
                url=None,
                errors=errors,
            )
        except OSError as e:
            errors.append(f"File operation failed: {e!s}")
            return DeploymentResult(
                success=False,
                branch="gh-pages",
                commit_sha=None,
                url=None,
                errors=errors,
            )


# ==============================================================================
# Git Helper Functions
# ==============================================================================


def _validate_branch_name(branch_name: str) -> None:
    """Validate git branch name for security.

    Args:
        branch_name: Branch name to validate

    Raises:
        ValueError: If branch name is invalid or potentially dangerous
    """
    if not branch_name:
        raise ValueError("Branch name cannot be empty")

    # Check for dangerous characters
    dangerous_chars = [";", "&", "|", "`", "$", "(", ")", "<", ">", "\n", "\r"]
    for char in dangerous_chars:
        if char in branch_name:
            raise ValueError(f"Branch name contains invalid character: {char}")

    # Check for path traversal attempts
    if ".." in branch_name or branch_name.startswith("/"):
        raise ValueError(f"Branch name contains invalid path components: {branch_name}")

    # Validate against git branch naming rules
    # Cannot start/end with slash, contain consecutive slashes, or end with .lock
    if (
        branch_name.startswith("/")
        or branch_name.endswith("/")
        or "//" in branch_name
        or branch_name.endswith(".lock")
    ):
        raise ValueError(f"Branch name violates git naming rules: {branch_name}")


def _validate_github_url(url: str) -> None:
    """Validate GitHub repository URL for security.

    Args:
        url: GitHub URL to validate

    Raises:
        ValueError: If URL is invalid or potentially dangerous
    """
    if not url:
        raise ValueError("GitHub URL cannot be empty")

    # Check for dangerous characters that could be used for injection
    dangerous_chars = [";", "&", "|", "`", "$", "(", ")", "<", ">", "\n", "\r", " "]
    for char in dangerous_chars:
        if char in url:
            raise ValueError(f"GitHub URL contains invalid character: {char}")

    # Validate URL format (must be GitHub)
    valid_prefixes = [
        "https://github.com/",
        "git@github.com:",
        "http://github.com/",  # Will be upgraded to HTTPS
    ]

    if not any(url.startswith(prefix) for prefix in valid_prefixes):
        raise ValueError(
            f"URL must be a valid GitHub URL (https://github.com/... or git@github.com:...): {url}"
        )


def _run_git_command(
    repo_path: Path,
    args: list[str],
    capture_output: bool = False,
    check: bool = True,
) -> subprocess.CompletedProcess:
    """Run a git command in the repository.

    Args:
        repo_path: Path to repository
        args: Git command arguments
        capture_output: Whether to capture stdout/stderr
        check: Whether to raise on non-zero exit

    Returns:
        CompletedProcess result
    """
    cmd = ["git"] + args

    result = subprocess.run(
        cmd,
        cwd=str(repo_path),
        capture_output=capture_output,
        text=True,
        check=check,
    )

    return result


def _check_git_status(repo_path: Path) -> bool:
    """Check if git working directory is clean.

    Args:
        repo_path: Path to repository

    Returns:
        True if clean, False if dirty
    """
    result = _run_git_command(
        repo_path,
        ["status", "--porcelain"],
        capture_output=True,
    )

    # Empty output means clean
    return len(result.stdout.strip()) == 0


def _get_current_branch(repo_path: Path) -> str:
    """Get current git branch name.

    Args:
        repo_path: Path to repository

    Returns:
        Current branch name
    """
    result = _run_git_command(
        repo_path,
        ["rev-parse", "--abbrev-ref", "HEAD"],
        capture_output=True,
    )

    return result.stdout.strip()


def _get_repo_url(repo_path: Path) -> str:
    """Get repository URL from git remote.

    Args:
        repo_path: Path to repository

    Returns:
        Repository URL
    """
    result = _run_git_command(
        repo_path,
        ["remote", "get-url", "origin"],
        capture_output=True,
    )

    return result.stdout.strip()


def _branch_exists(repo_path: Path, branch_name: str) -> bool:
    """Check if a branch exists.

    Args:
        repo_path: Path to repository
        branch_name: Name of branch to check

    Returns:
        True if branch exists, False otherwise
    """
    try:
        result = _run_git_command(
            repo_path,
            ["show-ref", "--verify", f"refs/heads/{branch_name}"],
            capture_output=True,
            check=False,
        )
        return result.returncode == 0
    except Exception:
        return False


def _switch_branch(repo_path: Path, branch_name: str) -> None:
    """Switch to a different branch.

    Args:
        repo_path: Path to repository
        branch_name: Branch to switch to

    Raises:
        ValueError: If branch name is invalid
    """
    _validate_branch_name(branch_name)
    _run_git_command(repo_path, ["checkout", branch_name])


def _construct_pages_url(repo_url: str) -> str:
    """Construct GitHub Pages URL from repository URL.

    Args:
        repo_url: Repository URL (SSH or HTTPS)

    Returns:
        GitHub Pages URL

    Raises:
        ValueError: If URL is invalid

    Examples:
        >>> _construct_pages_url("git@github.com:user/repo.git")
        'https://user.github.io/repo/'
        >>> _construct_pages_url("https://github.com/user/repo.git")
        'https://user.github.io/repo/'
    """
    _validate_github_url(repo_url)
    url = repo_url.rstrip("/")
    if url.endswith(".git"):
        url = url[:-4]

    # Handle SSH format: git@github.com:user/repo
    if "git@github.com:" in url:
        parts = url.split("git@github.com:")[-1].split("/")
    # Handle HTTPS format: https://github.com/user/repo
    elif "github.com/" in url:
        parts = url.split("github.com/")[-1].split("/")
    else:
        # Unknown format, try to extract last two parts
        parts = url.split("/")[-2:]

    owner = parts[0] if len(parts) > 0 else "unknown"
    repo = parts[1] if len(parts) > 1 else "unknown"

    return f"https://{owner}.github.io/{repo}/"

"""Site generator for GitHub Pages documentation.

Generates MkDocs documentation sites with Material theme from docs/ directory,
README.md, and command help text.

Philosophy:
- Single responsibility: Generate documentation site
- Discover content from multiple sources (docs/, README, commands)
- Build with MkDocs
- Graceful error handling with clear messages
"""

import subprocess
from pathlib import Path

from . import GenerationResult, SiteConfig
from .mkdocs_config import (
    build_mkdocs_config,
    write_mkdocs_yaml,
)


def generate_site(config: SiteConfig) -> GenerationResult:
    """Generate documentation site using MkDocs.

    Args:
        config: Site configuration

    Returns:
        GenerationResult with success status and details

    Raises:
        FileNotFoundError: If docs_dir doesn't exist
        PermissionError: If unable to write to output directory
        subprocess.CalledProcessError: If mkdocs build fails
    """
    if config is None:
        raise TypeError("Config cannot be None")

    docs_path = Path(config.docs_dir)
    output_path = Path(config.output_dir)
    project_root = docs_path.parent

    # Verify docs directory exists
    if not docs_path.exists():
        raise FileNotFoundError(f"Documentation directory not found: {config.docs_dir}")

    errors: list[str] = []
    warnings: list[str] = []

    # Discover content
    content_files = discover_content(docs_path)

    if not content_files:
        warnings.append("No markdown files found in docs directory")

    # Check for README to potentially include
    readme = discover_readme(project_root)
    if readme:
        # If no index.md exists, create one from README
        index_path = docs_path / "index.md"
        if not index_path.exists():
            try:
                readme_content = readme.read_text()
                index_path.write_text(readme_content)
                content_files.insert(0, index_path)
            except Exception as e:
                warnings.append(f"Could not copy README to index.md: {e}")
    else:
        if not (docs_path / "index.md").exists():
            warnings.append("No README.md or index.md found")

    # Discover commands for reference documentation
    commands = discover_commands()
    if commands:
        _generate_command_reference(docs_path, commands)
        # Refresh content list
        content_files = discover_content(docs_path)

    # Build MkDocs configuration
    mkdocs_config = build_mkdocs_config(
        project_name=config.project_name,
        project_url=config.project_url,
        docs_dir=str(docs_path),
        theme_features=config.theme_features,
        nav_structure=config.nav_structure,
    )

    # Write mkdocs.yml to project root
    config_path = project_root / "mkdocs.yml"
    write_mkdocs_yaml(mkdocs_config, config_path)

    # Create output directory
    output_path.mkdir(parents=True, exist_ok=True)

    # Build site with MkDocs
    try:
        result = subprocess.run(
            ["mkdocs", "build", "--site-dir", str(output_path)],
            cwd=str(project_root),
            capture_output=True,
            text=True,
            timeout=120,
        )

        if result.returncode != 0:
            errors.append(f"MkDocs build failed: {result.stderr}")
            return GenerationResult(
                success=False,
                site_dir=output_path,
                pages=[],
                errors=errors,
                warnings=warnings,
                config_file=config_path,
            )

        # Collect generated pages
        pages = _collect_generated_pages(output_path)

        return GenerationResult(
            success=True,
            site_dir=output_path,
            pages=pages,
            errors=errors,
            warnings=warnings,
            config_file=config_path,
        )

    except FileNotFoundError:
        raise FileNotFoundError(
            "MkDocs not found. Install with: pip install mkdocs mkdocs-material"
        )
    except subprocess.TimeoutExpired:
        errors.append("MkDocs build timed out after 120 seconds")
        return GenerationResult(
            success=False,
            site_dir=output_path,
            pages=[],
            errors=errors,
            warnings=warnings,
            config_file=config_path,
        )


def preview_locally(config_path: Path | str = "mkdocs.yml", port: int = 8000) -> None:
    """Start local preview server for documentation site.

    Args:
        config_path: Path to mkdocs.yml configuration
        port: Port to serve on (default: 8000)

    Note:
        This function blocks until the server is stopped (Ctrl+C).
    """
    config_path = Path(config_path)
    project_root = config_path.parent

    subprocess.run(
        ["mkdocs", "serve", "--dev-addr", f"127.0.0.1:{port}"],
        cwd=str(project_root),
    )


def discover_content(docs_dir: Path) -> list[Path]:
    """Discover markdown content in documentation directory.

    Args:
        docs_dir: Path to docs directory

    Returns:
        List of markdown file paths (sorted)
    """
    if not docs_dir.exists():
        return []

    # Find all markdown files
    md_files = list(docs_dir.rglob("*.md"))

    # Filter to only markdown files (exclude other file types)
    md_files = [f for f in md_files if f.suffix.lower() == ".md"]

    # Sort with index.md first, then alphabetically
    def sort_key(path: Path) -> tuple[int, str]:
        if path.name.lower() == "index.md":
            return (0, str(path))
        return (1, str(path))

    return sorted(md_files, key=sort_key)


def discover_readme(project_root: Path) -> Path | None:
    """Discover README.md in project root.

    Args:
        project_root: Path to project root directory

    Returns:
        Path to README.md if it exists, None otherwise
    """
    readme_names = ["README.md", "readme.md", "Readme.md", "README.MD"]

    for name in readme_names:
        readme_path = project_root / name
        if readme_path.exists():
            return readme_path

    return None


def discover_commands() -> dict[str, str]:
    """Discover command help text from CLI.

    Returns:
        Dictionary mapping command names to help text
    """
    commands: dict[str, str] = {}

    # Try to discover amplihack commands
    try:
        result = subprocess.run(
            ["amplihack", "--help"],
            capture_output=True,
            text=True,
            timeout=30,
        )
        if result.returncode == 0:
            commands["amplihack"] = result.stdout
    except (FileNotFoundError, subprocess.TimeoutExpired):
        pass  # No amplihack CLI available

    return commands


def _generate_command_reference(docs_dir: Path, commands: dict[str, str]) -> None:
    """Generate command reference documentation.

    Args:
        docs_dir: Path to docs directory
        commands: Dictionary of command names to help text
    """
    if not commands:
        return

    reference_dir = docs_dir / "reference"
    reference_dir.mkdir(exist_ok=True)

    cli_doc = reference_dir / "cli.md"

    content = "# CLI Reference\n\n"
    content += "Command-line interface reference documentation.\n\n"

    for cmd_name, help_text in commands.items():
        content += f"## {cmd_name}\n\n"
        content += "```\n"
        content += help_text
        content += "\n```\n\n"

    cli_doc.write_text(content)


def _collect_generated_pages(site_dir: Path) -> list[str]:
    """Collect list of generated HTML pages.

    Args:
        site_dir: Path to generated site directory

    Returns:
        List of relative paths to HTML pages
    """
    if not site_dir.exists():
        return []

    pages = []
    for html_file in site_dir.rglob("*.html"):
        rel_path = html_file.relative_to(site_dir)
        pages.append(str(rel_path))

    return sorted(pages)

"""MkDocs configuration builder for GitHub Pages.

Generates mkdocs.yml configuration with Material theme for GitHub Pages deployment.

Philosophy:
- Single responsibility: Build and write MkDocs configuration
- Standard YAML output compatible with MkDocs
- Material theme with sensible defaults
- Auto-generate navigation from docs/ structure
"""

from pathlib import Path
from typing import Any


def _validate_github_url(url: str) -> None:
    """Validate GitHub repository URL for security.

    Args:
        url: GitHub URL to validate

    Raises:
        ValueError: If URL is invalid or potentially dangerous
    """
    if not url:
        raise ValueError("GitHub URL cannot be empty")

    # Check for dangerous characters that could be used for injection
    dangerous_chars = [";", "&", "|", "`", "$", "(", ")", "<", ">", "\n", "\r", " "]
    for char in dangerous_chars:
        if char in url:
            raise ValueError(f"GitHub URL contains invalid character: {char}")

    # Validate URL format (must be GitHub)
    valid_prefixes = [
        "https://github.com/",
        "git@github.com:",
        "http://github.com/",  # Will be upgraded to HTTPS
    ]

    if not any(url.startswith(prefix) for prefix in valid_prefixes):
        raise ValueError(
            f"URL must be a valid GitHub URL (https://github.com/... or git@github.com:...): {url}"
        )


def build_mkdocs_config(
    project_name: str,
    project_url: str,
    docs_dir: str | Path = "docs",
    theme_features: list[str] | None = None,
    nav_structure: dict | list | None = None,
) -> dict[str, Any]:
    """Build complete MkDocs configuration dictionary.

    Args:
        project_name: Name of the project (used in site title)
        project_url: GitHub repository URL
        docs_dir: Path to documentation directory
        theme_features: List of Material theme features to enable
        nav_structure: Custom navigation (auto-generated if None)

    Returns:
        Dictionary ready to be written as mkdocs.yml

    Raises:
        ValueError: If project_url is invalid
    """
    _validate_github_url(project_url)
    docs_path = Path(docs_dir)

    # Build site URL from repo URL
    site_url = _construct_site_url(project_url)

    # Build theme configuration
    theme_config = build_material_theme_config(features=theme_features)

    # Build navigation
    if nav_structure is not None:
        nav = nav_structure
    else:
        # Auto-generate navigation from docs structure
        if docs_path.exists():
            md_files = list(docs_path.rglob("*.md"))
            nav = generate_nav_structure(md_files)
        else:
            nav = [{"Home": "index.md"}]

    config = {
        "site_name": project_name,
        "site_url": site_url,
        "repo_url": project_url,
        "repo_name": _extract_repo_name(project_url),
        "edit_uri": "edit/main/docs/",
        "theme": theme_config,
        "plugins": ["search"],
        "nav": nav,
        "markdown_extensions": [
            "pymdownx.highlight",
            "pymdownx.superfences",
            "pymdownx.tabbed",
            "admonition",
            "toc",
        ],
    }

    return config


def build_material_theme_config(
    features: list[str] | None = None,
) -> dict[str, Any]:
    """Build Material theme configuration.

    Args:
        features: List of Material theme features to enable

    Returns:
        Theme configuration dictionary
    """
    default_features = [
        "navigation.tabs",
        "navigation.sections",
        "navigation.expand",
        "search.highlight",
        "search.suggest",
        "content.code.copy",
    ]

    theme_config = {
        "name": "material",
        "features": features if features is not None else default_features,
        "palette": {
            "primary": "indigo",
            "accent": "indigo",
        },
        "icon": {
            "repo": "fontawesome/brands/github",
        },
    }

    return theme_config


def generate_nav_structure(files: list[Path]) -> list[dict[str, Any]]:
    """Generate navigation structure from documentation files.

    Args:
        files: List of markdown file paths

    Returns:
        Navigation structure as list of dicts for mkdocs.yml
    """
    if not files:
        return [{"Home": "index.md"}]

    # Group files by directory
    sections: dict[str, list[tuple[str, str]]] = {}
    root_files: list[tuple[str, str]] = []

    for file_path in files:
        # Get relative path from docs directory
        parts = file_path.parts
        # Find 'docs' in path and get relative path after it
        try:
            docs_idx = parts.index("docs")
            rel_parts = parts[docs_idx + 1 :]
        except ValueError:
            rel_parts = parts

        if len(rel_parts) == 1:
            # Root level file
            filename = rel_parts[0]
            name = _format_page_name(filename)
            root_files.append((name, filename))
        else:
            # File in subdirectory
            section = rel_parts[0]
            section_name = _format_section_name(section)
            filename = str(Path(*rel_parts))

            if section_name not in sections:
                sections[section_name] = []

            page_name = _format_page_name(rel_parts[-1])
            sections[section_name].append((page_name, filename))

    # Build navigation list
    nav: list[dict[str, Any]] = []

    # Add Home first if index.md exists
    home_files = [(name, path) for name, path in root_files if "index" in path.lower()]
    if home_files:
        nav.append({"Home": home_files[0][1]})
        root_files = [(n, p) for n, p in root_files if "index" not in p.lower()]

    # Add remaining root files
    for name, path in root_files:
        nav.append({name: path})

    # Add sections in Diataxis order if they exist
    diataxis_order = ["Tutorials", "How-To", "Reference", "Concepts"]
    added_sections = set()

    for section_name in diataxis_order:
        if section_name in sections:
            section_items = [{name: path} for name, path in sections[section_name]]
            nav.append({section_name: section_items})
            added_sections.add(section_name)

    # Add remaining sections alphabetically
    for section_name in sorted(sections.keys()):
        if section_name not in added_sections:
            section_items = [{name: path} for name, path in sections[section_name]]
            nav.append({section_name: section_items})

    return nav if nav else [{"Home": "index.md"}]


def write_mkdocs_yaml(config: dict[str, Any], output_path: Path) -> Path:
    """Write MkDocs configuration to YAML file.

    Args:
        config: Configuration dictionary
        output_path: Path to write mkdocs.yml

    Returns:
        Path to written file
    """
    import yaml

    yaml_content = yaml.dump(
        config,
        default_flow_style=False,
        sort_keys=False,
        allow_unicode=True,
        indent=2,
    )

    output_path.write_text(yaml_content)
    return output_path


def validate_config(config: dict[str, Any]) -> None:
    """Validate MkDocs configuration.

    Args:
        config: Configuration dictionary to validate

    Raises:
        ValueError: If configuration is invalid
    """
    if "site_name" not in config:
        raise ValueError("Configuration missing required field: site_name")

    if "theme" not in config:
        raise ValueError("Configuration missing required field: theme")

    if config["theme"].get("name") != "material":
        raise ValueError("Theme must be 'material' for GitHub Pages generation")


def _format_section_name(section: str) -> str:
    """Format directory name as section title.

    Args:
        section: Directory name (e.g., "api-reference", "howto")

    Returns:
        Formatted section name (e.g., "API Reference", "How-To")
    """
    # Handle special cases
    special_cases = {
        "api": "API",
        "api-reference": "API Reference",
        "howto": "How-To",
        "how-to": "How-To",
        "cli": "CLI",
    }

    lower_section = section.lower()
    if lower_section in special_cases:
        return special_cases[lower_section]

    # General formatting: replace dashes/underscores, title case
    formatted = section.replace("-", " ").replace("_", " ")
    return formatted.title()


def _format_page_name(filename: str) -> str:
    """Format filename as page title.

    Args:
        filename: Markdown filename (e.g., "getting-started.md")

    Returns:
        Formatted page name (e.g., "Getting Started")
    """
    # Remove .md extension
    name = filename.replace(".md", "")

    # Handle special cases
    if name.lower() == "index":
        return "Home"

    # General formatting
    formatted = name.replace("-", " ").replace("_", " ")
    return formatted.title()


def _extract_repo_info(repo_url: str) -> tuple[str, str]:
    """Extract owner and repository name from GitHub URL.

    Args:
        repo_url: GitHub repository URL

    Returns:
        Tuple of (owner, repo_name)

    Raises:
        ValueError: If URL is invalid
    """
    _validate_github_url(repo_url)

    # Handle both HTTPS and SSH formats
    # https://github.com/owner/repo
    # git@github.com:owner/repo.git

    url = repo_url.rstrip("/")
    if url.endswith(".git"):
        url = url[:-4]

    if "github.com/" in url:
        parts = url.split("github.com/")[-1].split("/")
    elif "github.com:" in url:
        parts = url.split("github.com:")[-1].split("/")
    else:
        parts = url.split("/")[-2:]

    owner = parts[0] if len(parts) > 0 else "unknown"
    repo = parts[1] if len(parts) > 1 else "unknown"

    return owner, repo


def _extract_repo_name(repo_url: str) -> str:
    """Extract repository name from URL for display.

    Args:
        repo_url: GitHub repository URL

    Returns:
        Repository name in owner/repo format
    """
    owner, repo = _extract_repo_info(repo_url)
    return f"{owner}/{repo}"


def _construct_site_url(repo_url: str) -> str:
    """Construct GitHub Pages URL from repository URL.

    Args:
        repo_url: GitHub repository URL

    Returns:
        GitHub Pages URL
    """
    owner, repo = _extract_repo_info(repo_url)
    return f"https://{owner}.github.io/{repo}/"

"""Tests for GitHub Pages documentation generation module."""

"""Shared fixtures for GitHub Pages tests."""

from pathlib import Path

import pytest


@pytest.fixture
def tmp_project_root(tmp_path: Path) -> Path:
    """Create a temporary project root with basic structure."""
    # Create docs directory with content
    docs_dir = tmp_path / "docs"
    docs_dir.mkdir()

    # Create index.md
    index_md = docs_dir / "index.md"
    index_md.write_text("""# Test Project Documentation

Welcome to the test project.

## Features

- Feature one description
- Feature two description

## Getting Started

Follow these steps to get started.
""")

    # Create a reference section
    reference_dir = docs_dir / "reference"
    reference_dir.mkdir()

    api_md = reference_dir / "api.md"
    api_md.write_text("""# API Reference

## Authentication

Use the `authenticate()` function.

## Endpoints

### GET /users

Returns list of users.

### POST /users

Creates a new user.
""")

    # Create README.md
    readme = tmp_path / "README.md"
    readme.write_text("""# Test Project

This is the test project README.
""")

    # Initialize as git repo
    git_dir = tmp_path / ".git"
    git_dir.mkdir()

    return tmp_path


@pytest.fixture
def tmp_docs_dir(tmp_project_root: Path) -> Path:
    """Return the docs directory from the project root."""
    return tmp_project_root / "docs"


@pytest.fixture
def tmp_site_dir(tmp_path: Path) -> Path:
    """Create a temporary generated site directory."""
    site_dir = tmp_path / "site"
    site_dir.mkdir()

    # Create basic HTML structure
    (site_dir / "index.html").write_text("""<!DOCTYPE html>
<html>
<head><title>Test</title></head>
<body><h1>Test Project</h1></body>
</html>
""")

    # Create a subdirectory with content
    reference_dir = site_dir / "reference"
    reference_dir.mkdir()

    (reference_dir / "api.html").write_text("""<!DOCTYPE html>
<html>
<head><title>API Reference</title></head>
<body><h1>API Reference</h1></body>
</html>
""")

    return site_dir


@pytest.fixture
def sample_markdown_files(tmp_path: Path) -> list[Path]:
    """Create sample markdown files for testing navigation generation."""
    docs_dir = tmp_path / "docs"
    docs_dir.mkdir(exist_ok=True)

    files = []

    # Root level files
    index = docs_dir / "index.md"
    index.write_text("# Home\n\nWelcome page.")
    files.append(index)

    getting_started = docs_dir / "getting-started.md"
    getting_started.write_text("# Getting Started\n\nHow to begin.")
    files.append(getting_started)

    # Tutorial section
    tutorials_dir = docs_dir / "tutorials"
    tutorials_dir.mkdir()

    tutorial1 = tutorials_dir / "basic.md"
    tutorial1.write_text("# Basic Tutorial\n\nBasic tutorial content.")
    files.append(tutorial1)

    # Reference section
    reference_dir = docs_dir / "reference"
    reference_dir.mkdir()

    cli_ref = reference_dir / "cli.md"
    cli_ref.write_text("# CLI Reference\n\nCommand line reference.")
    files.append(cli_ref)

    return files


@pytest.fixture
def tmp_git_repo(tmp_path: Path) -> Path:
    """Create a temporary directory that simulates a git repo."""
    repo_dir = tmp_path / "repo"
    repo_dir.mkdir()

    # Create .git directory (basic structure)
    git_dir = repo_dir / ".git"
    git_dir.mkdir()

    (git_dir / "HEAD").write_text("ref: refs/heads/main\n")

    refs_dir = git_dir / "refs" / "heads"
    refs_dir.mkdir(parents=True)

    # Create site directory
    site_dir = repo_dir / "site"
    site_dir.mkdir()
    (site_dir / "index.html").write_text("<html><body>Test</body></html>")

    return repo_dir

"""Tests for deployer.py module."""

from pathlib import Path
from unittest.mock import MagicMock, patch

import pytest

from github_pages import DeploymentConfig, DeploymentResult
from github_pages.deployer import (
    _branch_exists,
    _check_git_status,
    _construct_pages_url,
    _get_current_branch,
    _get_repo_url,
    _run_git_command,
    _switch_branch,
    deploy_site,
)


class TestDeploySite:
    """Tests for deploy_site function."""

    def test_raises_type_error_for_none_config(self):
        """Test that None config raises TypeError."""
        with pytest.raises(TypeError, match="Config cannot be None"):
            deploy_site(None)

    def test_raises_value_error_for_missing_site_dir(self, tmp_path: Path):
        """Test that missing site directory raises ValueError."""
        config = DeploymentConfig(
            site_dir=str(tmp_path / "nonexistent"),
            repo_path=str(tmp_path),
        )

        with pytest.raises(ValueError, match="not found"):
            deploy_site(config)

    def test_raises_value_error_for_empty_site_dir(self, tmp_path: Path):
        """Test that empty site directory raises ValueError."""
        site_dir = tmp_path / "site"
        site_dir.mkdir()

        config = DeploymentConfig(
            site_dir=str(site_dir),
            repo_path=str(tmp_path),
        )

        with pytest.raises(ValueError, match="empty"):
            deploy_site(config)

    @patch("github_pages.deployer._run_git_command")
    @patch("github_pages.deployer._check_git_status")
    @patch("github_pages.deployer._get_current_branch")
    @patch("github_pages.deployer._get_repo_url")
    @patch("github_pages.deployer._branch_exists")
    def test_returns_deployment_result(
        self,
        mock_branch_exists: MagicMock,
        mock_get_repo_url: MagicMock,
        mock_get_branch: MagicMock,
        mock_git_status: MagicMock,
        mock_git_cmd: MagicMock,
        tmp_git_repo: Path,
    ):
        """Test that DeploymentResult is returned."""
        mock_git_status.return_value = True
        mock_get_branch.return_value = "main"
        mock_get_repo_url.return_value = "https://github.com/user/repo"
        mock_branch_exists.return_value = False

        # Mock git commands
        mock_git_cmd.return_value = MagicMock(
            returncode=0,
            stdout="abc123\n",
            stderr="",
        )

        site_dir = tmp_git_repo / "site"

        config = DeploymentConfig(
            site_dir=str(site_dir),
            repo_path=str(tmp_git_repo),
        )

        result = deploy_site(config)

        assert isinstance(result, DeploymentResult)
        assert hasattr(result, "success")
        assert hasattr(result, "branch")
        assert hasattr(result, "commit_sha")
        assert hasattr(result, "url")
        assert hasattr(result, "errors")

    @patch("github_pages.deployer._run_git_command")
    @patch("github_pages.deployer._check_git_status")
    @patch("github_pages.deployer._get_current_branch")
    @patch("github_pages.deployer._get_repo_url")
    @patch("github_pages.deployer._branch_exists")
    def test_uses_gh_pages_branch(
        self,
        mock_branch_exists: MagicMock,
        mock_get_repo_url: MagicMock,
        mock_get_branch: MagicMock,
        mock_git_status: MagicMock,
        mock_git_cmd: MagicMock,
        tmp_git_repo: Path,
    ):
        """Test that gh-pages branch is used."""
        mock_git_status.return_value = True
        mock_get_branch.return_value = "main"
        mock_get_repo_url.return_value = "https://github.com/user/repo"
        mock_branch_exists.return_value = False
        mock_git_cmd.return_value = MagicMock(
            returncode=0,
            stdout="abc123\n",
            stderr="",
        )

        site_dir = tmp_git_repo / "site"

        config = DeploymentConfig(
            site_dir=str(site_dir),
            repo_path=str(tmp_git_repo),
        )

        result = deploy_site(config)

        assert result.branch == "gh-pages"

    @patch("github_pages.deployer._check_git_status")
    def test_git_status_error_handled(
        self,
        mock_git_status: MagicMock,
        tmp_git_repo: Path,
    ):
        """Test that git status error is handled."""
        mock_git_status.side_effect = Exception("Git error")

        site_dir = tmp_git_repo / "site"

        config = DeploymentConfig(
            site_dir=str(site_dir),
            repo_path=str(tmp_git_repo),
        )

        result = deploy_site(config)

        assert result.success is False
        assert len(result.errors) > 0

    def test_force_push_disabled_by_default(self, tmp_path: Path):
        """Test that force push is disabled by default."""
        config = DeploymentConfig(
            site_dir=str(tmp_path),
            repo_path=str(tmp_path),
        )

        assert config.force_push is False


class TestRunGitCommand:
    """Tests for _run_git_command helper."""

    def test_runs_git_command(self, tmp_path: Path):
        """Test that git command is executed."""
        # This will fail but we're testing it runs
        try:
            result = _run_git_command(tmp_path, ["status"], check=False)
            # If it succeeds, check structure
            assert hasattr(result, "returncode")
        except Exception:
            # Git not available or not a repo - expected
            pass

    def test_captures_output(self, tmp_path: Path):
        """Test output capture."""
        try:
            result = _run_git_command(
                tmp_path,
                ["status"],
                capture_output=True,
                check=False,
            )
            assert hasattr(result, "stdout")
            assert hasattr(result, "stderr")
        except Exception:
            pass


class TestCheckGitStatus:
    """Tests for _check_git_status helper."""

    @patch("github_pages.deployer._run_git_command")
    def test_clean_repo_returns_true(self, mock_git_cmd: MagicMock, tmp_path: Path):
        """Test that clean repo returns True."""
        mock_git_cmd.return_value = MagicMock(stdout="", returncode=0)

        result = _check_git_status(tmp_path)

        assert result is True

    @patch("github_pages.deployer._run_git_command")
    def test_dirty_repo_returns_false(self, mock_git_cmd: MagicMock, tmp_path: Path):
        """Test that dirty repo returns False."""
        mock_git_cmd.return_value = MagicMock(
            stdout="M  modified_file.py\n",
            returncode=0,
        )

        result = _check_git_status(tmp_path)

        assert result is False


class TestGetCurrentBranch:
    """Tests for _get_current_branch helper."""

    @patch("github_pages.deployer._run_git_command")
    def test_returns_branch_name(self, mock_git_cmd: MagicMock, tmp_path: Path):
        """Test that branch name is returned."""
        mock_git_cmd.return_value = MagicMock(stdout="main\n", returncode=0)

        result = _get_current_branch(tmp_path)

        assert result == "main"

    @patch("github_pages.deployer._run_git_command")
    def test_strips_whitespace(self, mock_git_cmd: MagicMock, tmp_path: Path):
        """Test that whitespace is stripped."""
        mock_git_cmd.return_value = MagicMock(stdout="  feature/branch  \n", returncode=0)

        result = _get_current_branch(tmp_path)

        assert result == "feature/branch"


class TestGetRepoUrl:
    """Tests for _get_repo_url helper."""

    @patch("github_pages.deployer._run_git_command")
    def test_returns_repo_url(self, mock_git_cmd: MagicMock, tmp_path: Path):
        """Test that repo URL is returned."""
        mock_git_cmd.return_value = MagicMock(
            stdout="https://github.com/user/repo.git\n",
            returncode=0,
        )

        result = _get_repo_url(tmp_path)

        assert result == "https://github.com/user/repo.git"


class TestBranchExists:
    """Tests for _branch_exists helper."""

    @patch("github_pages.deployer._run_git_command")
    def test_existing_branch_returns_true(
        self,
        mock_git_cmd: MagicMock,
        tmp_path: Path,
    ):
        """Test that existing branch returns True."""
        mock_git_cmd.return_value = MagicMock(returncode=0)

        result = _branch_exists(tmp_path, "main")

        assert result is True

    @patch("github_pages.deployer._run_git_command")
    def test_nonexistent_branch_returns_false(
        self,
        mock_git_cmd: MagicMock,
        tmp_path: Path,
    ):
        """Test that nonexistent branch returns False."""
        mock_git_cmd.return_value = MagicMock(returncode=1)

        result = _branch_exists(tmp_path, "nonexistent")

        assert result is False


class TestSwitchBranch:
    """Tests for _switch_branch helper."""

    @patch("github_pages.deployer._run_git_command")
    def test_switches_branch(self, mock_git_cmd: MagicMock, tmp_path: Path):
        """Test that branch is switched."""
        _switch_branch(tmp_path, "feature")

        mock_git_cmd.assert_called_once()
        call_args = mock_git_cmd.call_args[0]
        assert "checkout" in call_args[1]
        assert "feature" in call_args[1]


class TestConstructPagesUrl:
    """Tests for _construct_pages_url helper."""

    def test_https_url(self):
        """Test URL construction from HTTPS format."""
        url = _construct_pages_url("https://github.com/user/repo")

        assert url == "https://user.github.io/repo/"

    def test_https_url_with_git_extension(self):
        """Test URL construction with .git extension."""
        url = _construct_pages_url("https://github.com/user/repo.git")

        assert url == "https://user.github.io/repo/"

    def test_ssh_url(self):
        """Test URL construction from SSH format."""
        url = _construct_pages_url("git@github.com:user/repo.git")

        assert url == "https://user.github.io/repo/"

    def test_trailing_slash_handled(self):
        """Test that trailing slash is handled."""
        url = _construct_pages_url("https://github.com/user/repo/")

        assert url == "https://user.github.io/repo/"


class TestDeploymentConfig:
    """Tests for DeploymentConfig dataclass."""

    def test_default_values(self):
        """Test default configuration values."""
        config = DeploymentConfig(site_dir="/tmp/site")

        assert config.repo_path == "."
        assert config.commit_message == "Update docs"
        assert config.force_push is False

    def test_custom_values(self):
        """Test custom configuration values."""
        config = DeploymentConfig(
            site_dir="/tmp/site",
            repo_path="/tmp/repo",
            commit_message="Deploy documentation",
            force_push=True,
        )

        assert config.site_dir == "/tmp/site"
        assert config.repo_path == "/tmp/repo"
        assert config.commit_message == "Deploy documentation"
        assert config.force_push is True


class TestDeploymentResult:
    """Tests for DeploymentResult dataclass."""

    def test_success_result(self):
        """Test successful deployment result."""
        result = DeploymentResult(
            success=True,
            branch="gh-pages",
            commit_sha="abc123",
            url="https://user.github.io/repo/",
            errors=[],
        )

        assert result.success is True
        assert result.commit_sha == "abc123"
        assert result.url is not None
        assert len(result.errors) == 0

    def test_failure_result(self):
        """Test failed deployment result."""
        result = DeploymentResult(
            success=False,
            branch="gh-pages",
            commit_sha=None,
            url=None,
            errors=["Push failed"],
        )

        assert result.success is False
        assert result.commit_sha is None
        assert result.url is None
        assert len(result.errors) > 0

"""Tests for generator.py module."""

import subprocess
from pathlib import Path
from unittest.mock import MagicMock, patch

import pytest

from github_pages import GenerationResult, SiteConfig
from github_pages.generator import (
    discover_commands,
    discover_content,
    discover_readme,
    generate_navigation,
    generate_site,
    preview_locally,
)


class TestGenerateSite:
    """Tests for generate_site function."""

    def test_raises_type_error_for_none_config(self):
        """Test that None config raises TypeError."""
        with pytest.raises(TypeError, match="Config cannot be None"):
            generate_site(None)

    def test_raises_file_not_found_for_missing_docs(self, tmp_path: Path):
        """Test that missing docs directory raises FileNotFoundError."""
        config = SiteConfig(
            project_name="Test",
            project_url="https://github.com/user/repo",
            docs_dir=str(tmp_path / "nonexistent"),
        )

        with pytest.raises(FileNotFoundError, match="not found"):
            generate_site(config)

    @patch("github_pages.generator.subprocess.run")
    def test_successful_generation(
        self,
        mock_run: MagicMock,
        tmp_project_root: Path,
    ):
        """Test successful site generation."""
        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")

        config = SiteConfig(
            project_name="Test Project",
            project_url="https://github.com/user/repo",
            docs_dir=str(tmp_project_root / "docs"),
            output_dir=str(tmp_project_root / "site"),
        )

        result = generate_site(config)

        assert isinstance(result, GenerationResult)
        assert result.config_file is not None
        # mkdocs.yml should be created
        assert (tmp_project_root / "mkdocs.yml").exists()

    @patch("github_pages.generator.subprocess.run")
    def test_mkdocs_failure_returns_error(
        self,
        mock_run: MagicMock,
        tmp_project_root: Path,
    ):
        """Test that MkDocs failure is handled."""
        mock_run.return_value = MagicMock(
            returncode=1,
            stdout="",
            stderr="Build error",
        )

        config = SiteConfig(
            project_name="Test",
            project_url="https://github.com/user/repo",
            docs_dir=str(tmp_project_root / "docs"),
            output_dir=str(tmp_project_root / "site"),
        )

        result = generate_site(config)

        assert result.success is False
        assert len(result.errors) > 0

    @patch("github_pages.generator.subprocess.run")
    def test_readme_copied_to_index(
        self,
        mock_run: MagicMock,
        tmp_path: Path,
    ):
        """Test that README is copied to index.md if index doesn't exist."""
        # Create docs dir without index
        docs_dir = tmp_path / "docs"
        docs_dir.mkdir()
        (docs_dir / "guide.md").write_text("# Guide")

        # Create README
        readme = tmp_path / "README.md"
        readme.write_text("# Project README")

        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")

        config = SiteConfig(
            project_name="Test",
            project_url="https://github.com/user/repo",
            docs_dir=str(docs_dir),
            output_dir=str(tmp_path / "site"),
        )

        generate_site(config)

        # index.md should be created from README
        index_path = docs_dir / "index.md"
        assert index_path.exists()
        assert "Project README" in index_path.read_text()

    @patch("github_pages.generator.subprocess.run")
    def test_timeout_handled(
        self,
        mock_run: MagicMock,
        tmp_project_root: Path,
    ):
        """Test that timeout is handled gracefully."""
        mock_run.side_effect = subprocess.TimeoutExpired("mkdocs", 120)

        config = SiteConfig(
            project_name="Test",
            project_url="https://github.com/user/repo",
            docs_dir=str(tmp_project_root / "docs"),
            output_dir=str(tmp_project_root / "site"),
        )

        result = generate_site(config)

        assert result.success is False
        assert any("timed out" in err for err in result.errors)


class TestDiscoverContent:
    """Tests for discover_content function."""

    def test_empty_directory(self, tmp_path: Path):
        """Test discovering content in empty directory."""
        docs_dir = tmp_path / "docs"
        docs_dir.mkdir()

        files = discover_content(docs_dir)

        assert files == []

    def test_nonexistent_directory(self, tmp_path: Path):
        """Test discovering content in nonexistent directory."""
        files = discover_content(tmp_path / "nonexistent")

        assert files == []

    def test_finds_markdown_files(self, tmp_docs_dir: Path):
        """Test that markdown files are discovered."""
        files = discover_content(tmp_docs_dir)

        assert len(files) > 0
        assert all(f.suffix == ".md" for f in files)

    def test_index_md_sorted_first(self, tmp_path: Path):
        """Test that index.md is sorted first."""
        docs_dir = tmp_path / "docs"
        docs_dir.mkdir()

        (docs_dir / "zebra.md").write_text("# Zebra")
        (docs_dir / "alpha.md").write_text("# Alpha")
        (docs_dir / "index.md").write_text("# Index")

        files = discover_content(docs_dir)

        assert files[0].name == "index.md"

    def test_finds_files_in_subdirectories(self, sample_markdown_files: list[Path]):
        """Test that files in subdirectories are found."""
        # Get the docs dir from the first file
        docs_dir = sample_markdown_files[0].parent

        files = discover_content(docs_dir)

        # Should find files in subdirectories
        paths_str = [str(f) for f in files]
        assert any("tutorials" in p or "reference" in p for p in paths_str)


class TestDiscoverReadme:
    """Tests for discover_readme function."""

    def test_finds_readme_md(self, tmp_path: Path):
        """Test finding README.md."""
        readme = tmp_path / "README.md"
        readme.write_text("# Project")

        result = discover_readme(tmp_path)

        assert result == readme

    def test_finds_lowercase_readme(self, tmp_path: Path):
        """Test finding readme.md (lowercase)."""
        readme = tmp_path / "readme.md"
        readme.write_text("# Project")

        result = discover_readme(tmp_path)

        # On case-insensitive filesystems, the canonical path may differ
        assert result is not None
        assert result.name.lower() == "readme.md"

    def test_returns_none_if_no_readme(self, tmp_path: Path):
        """Test returning None when no README exists."""
        result = discover_readme(tmp_path)

        assert result is None


class TestDiscoverCommands:
    """Tests for discover_commands function."""

    @patch("github_pages.generator.subprocess.run")
    def test_discovers_amplihack_command(self, mock_run: MagicMock):
        """Test discovering amplihack command help."""
        mock_run.return_value = MagicMock(
            returncode=0,
            stdout="amplihack help text",
            stderr="",
        )

        commands = discover_commands()

        # May or may not find commands depending on system
        assert isinstance(commands, dict)

    @patch("github_pages.generator.subprocess.run")
    def test_handles_missing_command(self, mock_run: MagicMock):
        """Test handling when amplihack is not found."""
        mock_run.side_effect = FileNotFoundError()

        commands = discover_commands()

        assert commands == {}


class TestGenerateNavigation:
    """Tests for generate_navigation function."""

    def test_empty_files(self):
        """Test navigation with empty file list."""
        nav = generate_navigation([])

        assert isinstance(nav, dict)

    def test_custom_structure_used(self):
        """Test that custom navigation structure is used when provided."""
        custom = {"Home": "index.md", "Guide": "guide.md"}

        nav = generate_navigation([], custom_structure=custom)

        assert nav == custom

    def test_auto_generation(self, sample_markdown_files: list[Path]):
        """Test auto-generation of navigation."""
        nav = generate_navigation(sample_markdown_files)

        # Should be a dict
        assert isinstance(nav, dict)


class TestPreviewLocally:
    """Tests for preview_locally function."""

    @patch("github_pages.generator.subprocess.run")
    def test_starts_server(self, mock_run: MagicMock, tmp_path: Path):
        """Test that preview starts MkDocs server."""
        config_path = tmp_path / "mkdocs.yml"
        config_path.write_text("site_name: Test")

        preview_locally(config_path, port=8000)

        mock_run.assert_called_once()
        call_args = mock_run.call_args[0][0]
        assert "mkdocs" in call_args
        assert "serve" in call_args

    @patch("github_pages.generator.subprocess.run")
    def test_custom_port(self, mock_run: MagicMock, tmp_path: Path):
        """Test preview with custom port."""
        config_path = tmp_path / "mkdocs.yml"
        config_path.write_text("site_name: Test")

        preview_locally(config_path, port=9000)

        call_args = mock_run.call_args[0][0]
        assert "9000" in str(call_args)

"""Integration tests for GitHub Pages module."""

from pathlib import Path
from unittest.mock import MagicMock, patch

import pytest

from github_pages import (
    DeploymentConfig,
    DeploymentResult,
    GenerationResult,
    SiteConfig,
    ValidationResult,
    deploy_site,
    generate_site,
    validate_site,
)


class TestGenerateValidateWorkflow:
    """Integration tests for generate -> validate workflow."""

    @patch("github_pages.generator.subprocess.run")
    def test_generate_then_validate(
        self,
        mock_run: MagicMock,
        tmp_project_root: Path,
    ):
        """Test generating a site then validating it."""
        # Mock successful MkDocs build
        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")

        # Create output directory with content
        site_dir = tmp_project_root / "site"
        site_dir.mkdir(exist_ok=True)
        (site_dir / "index.html").write_text("<html><body>Test</body></html>")
        (site_dir / "docs.md").write_text("# Documentation\n\nComplete guide.")

        # Generate
        gen_config = SiteConfig(
            project_name="Test Project",
            project_url="https://github.com/user/repo",
            docs_dir=str(tmp_project_root / "docs"),
            output_dir=str(site_dir),
        )

        gen_result = generate_site(gen_config)

        # Validate
        val_result = validate_site(site_dir)

        assert isinstance(gen_result, GenerationResult)
        assert isinstance(val_result, ValidationResult)

    @patch("github_pages.generator.subprocess.run")
    def test_validation_results_match_expectations(
        self,
        mock_run: MagicMock,
        tmp_project_root: Path,
    ):
        """Test that validation results contain expected data."""
        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")

        site_dir = tmp_project_root / "site"
        site_dir.mkdir(exist_ok=True)

        # Create quality documentation
        (site_dir / "index.md").write_text("""
# Project Documentation

## Getting Started

This guide explains how to get started.

### Installation

Use pip to install the package.

### Configuration

Configure settings in config.yml.

## API Reference

See the [API documentation](api.md) for details.
""")

        val_result = validate_site(site_dir)

        # Should have all three pass scores
        assert val_result.pass1_coverage >= 0
        assert val_result.pass2_clarity_score >= 0
        assert val_result.pass3_grounded_pct >= 0


class TestFullWorkflow:
    """Integration tests for complete workflow."""

    @patch("github_pages.generator.subprocess.run")
    @patch("github_pages.deployer._run_git_command")
    @patch("github_pages.deployer._check_git_status")
    @patch("github_pages.deployer._get_current_branch")
    @patch("github_pages.deployer._get_repo_url")
    @patch("github_pages.deployer._branch_exists")
    def test_full_generate_validate_deploy(
        self,
        mock_branch_exists: MagicMock,
        mock_get_repo_url: MagicMock,
        mock_get_branch: MagicMock,
        mock_git_status: MagicMock,
        mock_git_cmd: MagicMock,
        mock_mkdocs: MagicMock,
        tmp_project_root: Path,
    ):
        """Test complete workflow: generate -> validate -> deploy."""
        # Setup mocks
        mock_mkdocs.return_value = MagicMock(returncode=0, stdout="", stderr="")
        mock_git_status.return_value = True
        mock_get_branch.return_value = "main"
        mock_get_repo_url.return_value = "https://github.com/user/repo"
        mock_branch_exists.return_value = False
        mock_git_cmd.return_value = MagicMock(
            returncode=0,
            stdout="abc123\n",
            stderr="",
        )

        # Create site dir with content
        site_dir = tmp_project_root / "site"
        site_dir.mkdir(exist_ok=True)
        (site_dir / "index.html").write_text("<html></html>")
        (site_dir / "docs.md").write_text("# Docs\n\nContent here.")

        # Initialize git
        git_dir = tmp_project_root / ".git"
        git_dir.mkdir(exist_ok=True)

        # Step 1: Generate
        gen_config = SiteConfig(
            project_name="Test",
            project_url="https://github.com/user/repo",
            docs_dir=str(tmp_project_root / "docs"),
            output_dir=str(site_dir),
        )
        gen_result = generate_site(gen_config)

        # Step 2: Validate
        val_result = validate_site(site_dir)

        # Step 3: Deploy (only if validation passes thresholds)
        deploy_config = DeploymentConfig(
            site_dir=str(site_dir),
            repo_path=str(tmp_project_root),
        )
        deploy_result = deploy_site(deploy_config)

        # All should return results
        assert isinstance(gen_result, GenerationResult)
        assert isinstance(val_result, ValidationResult)
        assert isinstance(deploy_result, DeploymentResult)


class TestErrorHandling:
    """Integration tests for error handling."""

    def test_generate_with_invalid_docs_dir(self, tmp_path: Path):
        """Test error handling for invalid docs directory."""
        config = SiteConfig(
            project_name="Test",
            project_url="https://github.com/user/repo",
            docs_dir=str(tmp_path / "nonexistent"),
        )

        with pytest.raises(FileNotFoundError):
            generate_site(config)

    def test_validate_with_invalid_site_dir(self, tmp_path: Path):
        """Test error handling for invalid site directory."""
        with pytest.raises(FileNotFoundError):
            validate_site(tmp_path / "nonexistent")

    def test_deploy_with_invalid_site_dir(self, tmp_path: Path):
        """Test error handling for invalid site directory."""
        config = DeploymentConfig(
            site_dir=str(tmp_path / "nonexistent"),
        )

        with pytest.raises(ValueError):
            deploy_site(config)


class TestPublicAPI:
    """Tests for public API consistency."""

    def test_all_exports_available(self):
        """Test that all public exports are available."""
        from github_pages import (
            DeploymentConfig,
            DeploymentResult,
            GenerationResult,
            SiteConfig,
            ValidationIssue,
            ValidationResult,
            deploy_site,
            generate_site,
            preview_locally,
            validate_site,
        )

        # All should be importable
        assert SiteConfig is not None
        assert DeploymentConfig is not None
        assert GenerationResult is not None
        assert ValidationResult is not None
        assert ValidationIssue is not None
        assert DeploymentResult is not None
        assert callable(generate_site)
        assert callable(validate_site)
        assert callable(deploy_site)
        assert callable(preview_locally)

    def test_config_dataclasses_have_defaults(self):
        """Test that config dataclasses have sensible defaults."""
        site_config = SiteConfig(
            project_name="Test",
            project_url="https://github.com/user/repo",
        )

        assert site_config.docs_dir == "docs"
        assert site_config.output_dir == "site"
        assert site_config.theme == "material"

        deploy_config = DeploymentConfig(site_dir="/tmp/site")

        assert deploy_config.repo_path == "."
        assert deploy_config.force_push is False


class TestDataclasses:
    """Tests for result dataclasses."""

    def test_generation_result_fields(self):
        """Test GenerationResult has all required fields."""
        result = GenerationResult(
            success=True,
            site_dir=Path("/tmp/site"),
            pages=["index.html"],
            errors=[],
            warnings=[],
            config_file=Path("/tmp/mkdocs.yml"),
        )

        assert result.success is True
        assert isinstance(result.site_dir, Path)
        assert isinstance(result.pages, list)
        assert isinstance(result.errors, list)
        assert isinstance(result.warnings, list)

    def test_validation_result_fields(self):
        """Test ValidationResult has all required fields."""
        result = ValidationResult(
            passed=True,
            issues=[],
            pass1_coverage=100.0,
            pass2_clarity_score=85.0,
            pass3_grounded_pct=98.0,
        )

        assert result.passed is True
        assert result.pass1_coverage == 100.0
        assert result.pass2_clarity_score == 85.0
        assert result.pass3_grounded_pct == 98.0

    def test_deployment_result_fields(self):
        """Test DeploymentResult has all required fields."""
        result = DeploymentResult(
            success=True,
            branch="gh-pages",
            commit_sha="abc123",
            url="https://user.github.io/repo/",
            errors=[],
        )

        assert result.success is True
        assert result.branch == "gh-pages"
        assert result.commit_sha is not None
        assert result.url is not None