plating 0.0.0.dev0__py3-none-any.whl

plating/cli.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+#
+# plating/cli.py
+#
+"""CLI interface for documentation generation."""
+
+from pathlib import Path
+
+import click
+from provide.foundation import logger, pout, perr
+
+from plating.adorner import adorn_components
+from plating.errors import PlatingError, handle_error
+from plating.plater import generate_docs
+
+
+@click.group()
+def main() -> None:
+    """Plating - Documentation generator for Terraform/OpenTofu providers."""
+    pass
+
+
+@main.command("adorn")
+@click.option(
+    "--component-type",
+    type=click.Choice(["resource", "data_source", "function"]),
+    multiple=True,
+    help="Filter by component type (can be used multiple times).",
+)
+def adorn_command(component_type: tuple[str, ...]) -> None:
+    """Adorn components with missing .plating directories."""
+    try:
+        pout("💎 Adorning components with .plating directories...")
+
+        component_types = list(component_type) if component_type else None
+        results = adorn_components(component_types)
+
+        total = sum(results.values())
+        if total > 0:
+            pout(f"✅ Adorned {total} components:")
+            for comp_type, count in results.items():
+                if count > 0:
+                    pout(f"  - {count} {comp_type}{'s' if count != 1 else ''}")
+        else:
+            pout("ℹ️ No missing .plating directories found")
+
+        click.secho("✅ Adorning completed successfully!", fg="green")
+
+    except PlatingError as e:
+        # Our custom errors have good messages
+        click.secho(f"❌ {e}", fg="red", err=True)
+        logger.error(f"Adorning failed: {e}")
+        raise click.Abort() from e
+    except Exception as e:
+        import traceback
+
+        error_msg = handle_error(e, logger)
+        click.secho(f"❌ Adorning failed: {error_msg}", fg="red", err=True)
+        click.secho(f"Stack trace:\n{traceback.format_exc()}", fg="red", err=True)
+        raise click.Abort() from e
+
+
+@main.command("plate")
+@click.option(
+    "--output-dir",
+    type=click.Path(file_okay=False, resolve_path=True),
+    default="docs",
+    help="Output directory for plated documentation.",
+)
+@click.option(
+    "--provider-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=".",
+    help="Path to the provider directory.",
+)
+@click.option(
+    "--component-type",
+    type=click.Choice(["resource", "data_source", "function"]),
+    multiple=True,
+    help="Filter by component type (can be used multiple times).",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Force documentation generation even if not in a provider directory.",
+)
+def plate_command(
+    output_dir: str, provider_dir: str, component_type: tuple[str, ...], force: bool
+) -> None:
+    """Plate all plating bundles into final documentation."""
+    try:
+        provider_path = Path(provider_dir)
+
+        # Validate that we're in a provider directory unless --force is used
+        if not force and not _is_provider_directory(provider_path):
+            click.secho(
+                "❌ This does not appear to be a provider directory. "
+                "Expected to find a pyproject.toml with provider configuration "
+                "or templates directory. Use --force to override.",
+                fg="red",
+                err=True,
+            )
+            raise click.Abort()
+
+        pout("🍽️ Plating documentation...")
+        generate_docs(output_dir=output_dir)
+        click.secho("✅ Documentation plated successfully!", fg="green")
+
+    except PlatingError as e:
+        # Our custom errors have good messages
+        click.secho(f"❌ {e}", fg="red", err=True)
+        logger.error(f"Documentation plating failed: {e}")
+        raise click.Abort() from e
+    except Exception as e:
+        import traceback
+
+        error_msg = handle_error(e, logger)
+        click.secho(f"❌ Documentation plating failed: {error_msg}", fg="red", err=True)
+        click.secho(f"Stack trace:\n{traceback.format_exc()}", fg="red", err=True)
+        raise click.Abort() from e
+
+
+def _is_provider_directory(path: Path) -> bool:
+    """Check if the given path appears to be a provider directory."""
+    # Check for pyproject.toml with terraform-provider or pyvider in name
+    pyproject_toml = path / "pyproject.toml"
+    if pyproject_toml.exists():
+        try:
+            import tomllib
+
+            with open(pyproject_toml, "rb") as f:
+                data = tomllib.load(f)
+
+            # Check project name for provider indicators
+            project_name = data.get("project", {}).get("name", "")
+            if "terraform-provider" in project_name or "pyvider" in project_name:
+                return True
+
+            # Check for pyvider configuration
+            if "tool" in data and "pyvider" in data["tool"]:
+                return True
+
+        except Exception:
+            pass
+
+    # Check for templates directory (common in provider repos)
+    if (path / "templates").exists():
+        return True
+
+    # Check for provider-specific files
+    provider_indicators = [
+        "terraform-registry-manifest.json",
+        "pyvider.toml",
+        ".plating",
+    ]
+
+    for indicator in provider_indicators:
+        if (path / indicator).exists():
+            return True
+
+    return False
+
+
+# Add 'render' as an alias for 'plate' for backward compatibility
+@main.command("render", hidden=True)  # Hidden from help but still works
+@click.option(
+    "--output-dir",
+    type=click.Path(file_okay=False),
+    default="docs",
+    help="Output directory for plated documentation.",
+)
+@click.option(
+    "--provider-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=".",
+    help="Path to the provider directory.",
+)
+@click.option(
+    "--component-type",
+    type=click.Choice(["resource", "data_source", "function"]),
+    multiple=True,
+    help="Filter by component type (can be used multiple times).",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Force documentation generation even if not in a provider directory.",
+)
+def render_command(
+    output_dir: str, provider_dir: str, component_type: tuple[str, ...], force: bool
+) -> None:
+    """(Deprecated) Alias for 'plate' command. Use 'garnish plate' instead."""
+    click.echo("Note: 'render' is deprecated. Please use 'plate' instead.")
+    # Call the plate command directly
+    ctx = click.get_current_context()
+    ctx.invoke(
+        plate_command,
+        output_dir=output_dir,
+        provider_dir=provider_dir,
+        component_type=component_type,
+        force=force,
+    )
+
+
+@main.command("test")
+@click.option(
+    "--component-type",
+    type=click.Choice(["resource", "data_source", "function"]),
+    multiple=True,
+    help="Filter by component type (can be used multiple times).",
+)
+@click.option(
+    "--parallel",
+    type=int,
+    default=4,
+    help="Number of tests to run in parallel.",
+)
+@click.option(
+    "--output-dir",
+    type=click.Path(file_okay=False),
+    default=".plating-tests",
+    help="Temporary directory for test execution.",
+)
+@click.option(
+    "--output-file",
+    type=click.Path(dir_okay=False),
+    help="File to write test results to.",
+)
+@click.option(
+    "--output-format",
+    type=click.Choice(["json", "markdown", "html"]),
+    default="json",
+    help="Format for test results output.",
+)
+def test_command(
+    component_type: tuple[str, ...],
+    parallel: int,
+    output_dir: str,
+    output_file: str | None,
+    output_format: str,
+) -> None:
+    """Run all plating example files as Terraform tests."""
+    try:
+        # Import here to avoid circular imports
+        from .test_runner import run_plating_tests
+
+        component_types = list(component_type) if component_type else None
+        results = run_plating_tests(
+            component_types=component_types,
+            parallel=parallel,
+            output_dir=Path(output_dir),
+            output_file=Path(output_file) if output_file else None,
+            output_format=output_format,
+        )
+
+        # Display results
+        total_tests = results["total"]
+        passed = results["passed"]
+        failed = results["failed"]
+        warnings = results.get("warnings", 0)
+        skipped = results.get("skipped", 0)
+
+        if total_tests == 0:
+            pout("ℹ️ No plating examples found to test")
+            return
+
+        pout("\n📊 Test Results:")
+        pout(f"  Total: {total_tests}")
+        pout(f"  ✅ Passed: {passed}")
+        if failed > 0:
+            pout(f"  ❌ Failed: {failed}")
+        if warnings > 0:
+            pout(f"  ⚠️  Warnings: {warnings}")
+        if skipped > 0:
+            pout(f"  ⏭️  Skipped: {skipped}")
+
+        # Show warnings if any
+        if warnings > 0:
+            pout("\n⚠️  Tests with warnings:")
+            for test_name, details in results.get("test_details", {}).items():
+                if details.get("warnings"):
+                    pout(f"  - {test_name} ({len(details['warnings'])} warnings)")
+                    for warning in details["warnings"][:2]:  # Show first 2 warnings
+                        pout(f"    • {warning['message']}")
+                    if len(details["warnings"]) > 2:
+                        pout(f"    • ... and {len(details['warnings']) - 2} more")
+
+        if failed > 0:
+            pout("\n❌ Failed tests:")
+            for test_name, error in results["failures"].items():
+                pout(f"  - {test_name}: {error}")
+            click.secho("\n❌ Some tests failed!", fg="red", err=True)
+            raise click.Abort()
+        else:
+            click.secho("\n✅ All tests passed!", fg="green")
+
+    except PlatingError as e:
+        # Our custom errors have good messages
+        click.secho(f"❌ {e}", fg="red", err=True)
+        logger.error(f"Test execution failed: {e}")
+        raise click.Abort() from e
+    except Exception as e:
+        import traceback
+
+        error_msg = handle_error(e, logger)
+        click.secho(f"❌ Test execution failed: {error_msg}", fg="red", err=True)
+        click.secho(f"Stack trace:\n{traceback.format_exc()}", fg="red", err=True)
+        raise click.Abort() from e
+
+
+if __name__ == "__main__":
+    main()
+
+
+# 🥄📚🪄

plating/config.py

@@ -0,0 +1,106 @@
+#
+# plating/config.py
+#
+"""Configuration management for plating."""
+
+import os
+from pathlib import Path
+from typing import Any
+
+from attrs import define
+from provide.foundation.config import RuntimeConfig, field
+
+
+@define
+class PlatingConfig(RuntimeConfig):
+    """Configuration for plating operations."""
+
+    # Terraform/OpenTofu configuration
+    terraform_binary: str | None = field(
+        default=None,
+        description="Path to terraform/tofu binary",
+        env_var="GARNISH_TF_BINARY"
+    )
+    plugin_cache_dir: Path | None = field(
+        default=None,
+        description="Terraform plugin cache directory",
+        env_var="TF_PLUGIN_CACHE_DIR"
+    )
+
+    # Test execution configuration
+    test_timeout: int = field(
+        default=120,
+        description="Timeout for test execution in seconds",
+        env_var="GARNISH_TEST_TIMEOUT"
+    )
+    test_parallel: int = field(
+        default=4,
+        description="Number of parallel test executions",
+        env_var="GARNISH_TEST_PARALLEL"
+    )
+
+    # Output configuration
+    output_dir: Path = field(
+        default=Path("./docs"),
+        description="Default output directory for documentation",
+        env_var="GARNISH_OUTPUT_DIR"
+    )
+
+    # Component directories
+    resources_dir: Path = field(
+        default=Path("./resources"),
+        description="Directory containing resource definitions"
+    )
+    data_sources_dir: Path = field(
+        default=Path("./data_sources"),
+        description="Directory containing data source definitions"
+    )
+    functions_dir: Path = field(
+        default=Path("./functions"),
+        description="Directory containing function definitions"
+    )
+
+    def __attrs_post_init__(self) -> None:
+        """Initialize derived configuration values."""
+        super().__attrs_post_init__()
+        
+        # Auto-detect terraform binary if not specified
+        if self.terraform_binary is None:
+            import shutil
+            self.terraform_binary = (
+                shutil.which("tofu") or
+                shutil.which("terraform") or
+                "terraform"
+            )
+
+        # Set default plugin cache directory
+        if self.plugin_cache_dir is None:
+            self.plugin_cache_dir = Path.home() / ".terraform.d" / "plugin-cache"
+
+
+    def get_terraform_env(self) -> dict[str, str]:
+        """Get environment variables for terraform execution."""
+        env = os.environ.copy()
+
+        if self.plugin_cache_dir and self.plugin_cache_dir.exists():
+            env["TF_PLUGIN_CACHE_DIR"] = str(self.plugin_cache_dir)
+
+        return env
+
+
+# Global configuration instance
+_config: PlatingConfig | None = None
+
+
+def get_config() -> PlatingConfig:
+    """Get the global configuration instance."""
+    global _config
+    if _config is None:
+        _config = PlatingConfig.from_env()
+    return _config
+
+
+def set_config(config: PlatingConfig) -> None:
+    """Set the global configuration instance."""
+    global _config
+    _config = config

plating/error_handling.py

@@ -0,0 +1,125 @@
+#
+# plating/error_handling.py
+#
+"""Centralized error handling and reporting for plating."""
+
+from pathlib import Path
+import subprocess
+
+from rich.console import Console
+
+console = Console()
+
+
+class ErrorReporter:
+    """Centralized error reporting for plating operations."""
+
+    @staticmethod
+    def report_subprocess_error(
+        cmd: list[str],
+        error: subprocess.CalledProcessError,
+        context: str = ""
+    ) -> None:
+        """Report subprocess execution errors consistently."""
+        console.print(f"[red]Error executing command: {' '.join(cmd)}[/red]")
+        if context:
+            console.print(f"[yellow]Context: {context}[/yellow]")
+        if error.stderr:
+            console.print(f"[red]Error output:[/red]\n{error.stderr}")
+        if error.returncode:
+            console.print(f"[red]Exit code: {error.returncode}[/red]")
+
+    @staticmethod
+    def report_file_error(
+        path: Path,
+        operation: str,
+        error: Exception
+    ) -> None:
+        """Report file operation errors consistently."""
+        console.print(f"[red]File operation failed: {operation}[/red]")
+        console.print(f"[yellow]Path: {path}[/yellow]")
+        console.print(f"[red]Error: {error}[/red]")
+
+    @staticmethod
+    def report_validation_error(
+        component: str,
+        errors: list[str],
+        warnings: list[str] | None = None
+    ) -> None:
+        """Report validation errors and warnings consistently."""
+        console.print(f"[red]Validation failed for {component}[/red]")
+        for error in errors:
+            console.print(f"  [red]✗[/red] {error}")
+        if warnings:
+            for warning in warnings:
+                console.print(f"  [yellow]⚠[/yellow] {warning}")
+
+    @staticmethod
+    def report_warning(message: str, details: str | None = None) -> None:
+        """Report warnings consistently."""
+        console.print(f"[yellow]Warning: {message}[/yellow]")
+        if details:
+            console.print(f"[dim]{details}[/dim]")
+
+    @staticmethod
+    def report_success(message: str, details: str | None = None) -> None:
+        """Report success messages consistently."""
+        console.print(f"[green]✓ {message}[/green]")
+        if details:
+            console.print(f"[dim]{details}[/dim]")
+
+
+def handle_subprocess_execution(
+    cmd: list[str],
+    cwd: Path | None = None,
+    timeout: int = 120,
+    context: str = "",
+    capture_output: bool = True
+) -> subprocess.CompletedProcess[str]:
+    """Execute subprocess with consistent error handling.
+    
+    Args:
+        cmd: Command to execute
+        cwd: Working directory for command
+        timeout: Command timeout in seconds
+        context: Context description for error reporting
+        capture_output: Whether to capture stdout/stderr
+        
+    Returns:
+        CompletedProcess result
+        
+    Raises:
+        subprocess.CalledProcessError: If command fails
+        subprocess.TimeoutExpired: If command times out
+    """
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=cwd,
+            capture_output=capture_output,
+            text=True,
+            timeout=timeout,
+            check=False
+        )
+
+        if result.returncode != 0:
+            error = subprocess.CalledProcessError(
+                result.returncode, cmd, result.stdout, result.stderr
+            )
+            ErrorReporter.report_subprocess_error(cmd, error, context)
+            raise error
+
+        return result
+
+    except subprocess.TimeoutExpired:
+        ErrorReporter.report_warning(
+            f"Command timed out after {timeout} seconds",
+            f"Command: {' '.join(cmd)}"
+        )
+        raise
+    except FileNotFoundError:
+        ErrorReporter.report_warning(
+            f"Command not found: {cmd[0]}",
+            "Please ensure the required tool is installed"
+        )
+        raise

plating/errors.py

@@ -0,0 +1,142 @@
+"""
+Custom error types for plating.
+"""
+
+from pathlib import Path
+from typing import Any
+from provide.foundation.errors import FoundationError
+
+
+class PlatingError(FoundationError):
+    """Base error for all plating-related errors."""
+
+    pass
+
+
+class BundleError(PlatingError):
+    """Error related to plating bundles."""
+
+    def __init__(self, bundle_name: str, message: str):
+        self.bundle_name = bundle_name
+        super().__init__(f"Bundle '{bundle_name}': {message}")
+
+
+class PlatingRenderError(PlatingError):
+    """Error during documentation plating."""
+
+    def __init__(self, bundle_name: str, reason: str):
+        self.bundle_name = bundle_name
+        self.reason = reason
+        super().__init__(f"Failed to plate '{bundle_name}': {reason}")
+
+
+class AdorningError(PlatingError):
+    """Error during component adorning."""
+
+    def __init__(self, component_name: str, component_type: str, reason: str):
+        self.component_name = component_name
+        self.component_type = component_type
+        self.reason = reason
+        super().__init__(
+            f"Failed to adorn {component_type} '{component_name}': {reason}"
+        )
+
+
+class SchemaError(PlatingError):
+    """Error related to schema extraction or processing."""
+
+    def __init__(self, provider_name: str, reason: str):
+        self.provider_name = provider_name
+        self.reason = reason
+        super().__init__(f"Schema error for provider '{provider_name}': {reason}")
+
+
+class TemplateError(PlatingError):
+    """Error during template rendering."""
+
+    def __init__(self, template_path: Path | str, reason: str):
+        self.template_path = template_path
+        self.reason = reason
+        super().__init__(f"Template error in '{template_path}': {reason}")
+
+
+class DiscoveryError(PlatingError):
+    """Error during bundle discovery."""
+
+    def __init__(self, package_name: str, reason: str):
+        self.package_name = package_name
+        self.reason = reason
+        super().__init__(f"Discovery error for package '{package_name}': {reason}")
+
+
+class ConfigurationError(PlatingError):
+    """Error in plating configuration."""
+
+    def __init__(self, config_key: str, reason: str):
+        self.config_key = config_key
+        self.reason = reason
+        super().__init__(f"Configuration error for '{config_key}': {reason}")
+
+
+class TestRunnerError(PlatingError):
+    """Error during test execution."""
+
+    def __init__(self, test_name: str, reason: str):
+        self.test_name = test_name
+        self.reason = reason
+        super().__init__(f"Test '{test_name}' failed: {reason}")
+
+
+class FileSystemError(PlatingError):
+    """Error related to file system operations."""
+
+    def __init__(self, path: Path | str, operation: str, reason: str):
+        self.path = path
+        self.operation = operation
+        self.reason = reason
+        super().__init__(f"File system error during {operation} on '{path}': {reason}")
+
+
+def handle_error(error: Exception, logger: Any = None, reraise: bool = False) -> str:
+    """
+    Handle an error with proper logging and optional re-raising.
+
+    Args:
+        error: The exception to handle
+        logger: Optional logger instance to use
+        reraise: Whether to re-raise the error after handling
+
+    Returns:
+        A formatted error message
+    """
+    error_msg = str(error)
+
+    if isinstance(error, PlatingError):
+        # It's one of our custom errors, we have more context
+        if logger:
+            logger.error(error_msg)
+    elif isinstance(error, FileNotFoundError):
+        error_msg = f"File not found: {error}"
+        if logger:
+            logger.error(error_msg)
+    elif isinstance(error, PermissionError):
+        error_msg = f"Permission denied: {error}"
+        if logger:
+            logger.error(error_msg)
+    elif isinstance(error, (OSError, IOError)):
+        error_msg = f"I/O error: {error}"
+        if logger:
+            logger.error(error_msg)
+    else:
+        # Generic error
+        error_msg = f"Unexpected error: {error}"
+        if logger:
+            logger.exception("Unexpected error occurred")
+
+    if reraise:
+        raise
+
+    return error_msg
+
+
+# 🍲❌🪄