gd-tools-cli 0.1.0__py3-none-any.whl

gd_tools/cli.py

@@ -0,0 +1,329 @@
+"""CLI entry point for gd-tools."""
+
+from pathlib import Path
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.syntax import Syntax
+
+from . import __version__
+from .config import load_config
+from .coverage.orchestrator import (
+    generate_coverage_report,
+    merge_coverage_files,
+    run_coverage_test,
+    show_coverage_summary,
+)
+from .doctor import format_doctor_table, run_doctor
+from .errors import (
+    ConfigError,
+    CoverageThresholdError,
+    GdToolsError,
+    TestFailureError,
+)
+from .format_runner import run_format
+from .init import run_init
+from .lint_runner import format_lint_json, format_lint_text, run_lint
+from .test_runner import run_tests
+
+
+class GdToolsGroup(click.Group):
+    """Custom Click group that converts NotImplementedError to exit code 2.
+
+    Stub commands raise ``NotImplementedError`` to indicate they are not
+    yet implemented. This class catches that exception and exits with
+    code 2 (configuration/usage error), consistent with the gd-tools
+    error convention.
+    """
+
+    def invoke(self, ctx) -> Any:
+        """Invoke the group, catching NotImplementedError as exit code 2.
+
+        Args:
+            ctx: The Click context for this invocation.
+
+        Returns:
+            The result of the underlying command invocation.
+
+        Raises:
+            SystemExit: With code 2 if a command raises
+                NotImplementedError.
+        """
+        try:
+            return super().invoke(ctx)
+        except NotImplementedError:
+            click.echo(
+                "Error: This command is not yet implemented.",
+                err=True,
+            )
+            ctx.exit(2)
+
+
+@click.group(cls=GdToolsGroup)
+@click.version_option(
+    version=__version__,
+    prog_name="gd-tools",
+    message="%(prog)s %(version)s",
+)
+def cli():
+    """gd-tools: A modern development workflow CLI for GDScript."""
+
+
+@cli.command()
+@click.option(
+    "--non-interactive",
+    is_flag=True,
+    help="Run without interactive prompts.",
+)
+def init(non_interactive):
+    """Initialize a new gd-tools configuration."""
+    try:
+        run_init(non_interactive=non_interactive)
+    except GdToolsError as e:
+        click.echo(f"Error: {e}", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(e.exit_code)
+
+    ctx = click.get_current_context()
+    ctx.exit(0)
+
+
+@cli.command()
+def doctor():
+    """Check the environment for required tools."""
+    result = run_doctor()
+    console = Console()
+    console.print(format_doctor_table(result))
+    ctx = click.get_current_context()
+    ctx.exit(0 if result.all_passed else 1)
+
+
+@cli.command()
+@click.option("--coverage", is_flag=True, help="Generate coverage report.")
+@click.option("--min", type=int, help="Minimum coverage threshold.")
+@click.option("--suite", help="Specify which test suite to run.")
+@click.option("--test", help="Specify which test to run.")
+@click.option("--junit-xml", help="Path to write JUnit XML report.")
+@click.option(
+    "--no-exit-code",
+    is_flag=True,
+    help="Don't exit with non-zero on test failure.",
+)
+@click.option(
+    "--timeout",
+    type=int,
+    help="Timeout in seconds for the test run.",
+)
+def test(coverage, min, suite, test, junit_xml, no_exit_code, timeout):
+    """Run GDScript tests using GUT."""
+    try:
+        config = load_config()
+    except ConfigError as e:
+        click.echo(f"Error: {e}", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(2)
+
+    try:
+        if coverage:
+            run_coverage_test(
+                config,
+                suite=suite,
+                test_name=test,
+                junit_xml=junit_xml,
+                no_exit_code=no_exit_code,
+                min_percent=min,
+                timeout=timeout,
+            )
+        else:
+            run_tests(
+                config,
+                coverage=coverage,
+                min_percent=min,
+                suite=suite,
+                test_name=test,
+                junit_xml=junit_xml,
+                no_exit_code=no_exit_code,
+            )
+    except TestFailureError as e:
+        click.echo(f"Error: {e}", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(1)
+    except GdToolsError as e:
+        click.echo(f"Error: {e}", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(e.exit_code)
+
+    ctx = click.get_current_context()
+    ctx.exit(0)
+
+
+@cli.command()
+@click.argument("path", required=False, default=".")
+@click.option(
+    "--report-format",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    help="Output format for the lint report.",
+)
+@click.option(
+    "--fix",
+    is_flag=True,
+    help="Attempt to fix lint issues (no-op for gdlint).",
+)
+def lint(path, report_format, fix):
+    """Lint GDScript files."""
+    if fix:
+        click.echo(
+            "Warning: gdlint is read-only; --fix has no effect.", err=True
+        )
+
+    try:
+        config = load_config()
+    except ConfigError as e:
+        click.echo(f"Error: {e}", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(2)
+
+    result = run_lint(config, path, report_format)
+
+    if report_format == "json":
+        output = format_lint_json(result)
+    else:
+        output = format_lint_text(result)
+
+    click.echo(output)
+
+    ctx = click.get_current_context()
+    if result.errors:
+        ctx.exit(1)
+    ctx.exit(0)
+
+
+@cli.command()
+@click.argument("path", required=False, default=".")
+@click.option("--check", is_flag=True, help="Check only, don't modify files.")
+@click.option("--diff", is_flag=True, help="Show diff of changes.")
+def format(path, check, diff):
+    """Format GDScript files."""
+    if check and diff:
+        click.echo("Error: --check and --diff are mutually exclusive", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(2)
+
+    try:
+        config = load_config()
+    except ConfigError as e:
+        click.echo(f"Error: {e}", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(2)
+
+    result = run_format(config, path, check=check, diff=diff)
+
+    ctx = click.get_current_context()
+    if result.files_checked == 0:
+        click.echo("No .gd files found.")
+        ctx.exit(0)
+
+    if check:
+        if result.files_needing_format > 0:
+            for file_path in result.files_needing_format_paths:
+                click.echo(f"  {file_path}")
+            click.echo(
+                f"\n{result.files_needing_format} file(s) need "
+                f"formatting (out of {result.files_checked} checked)."
+            )
+            ctx.exit(1)
+        else:
+            click.echo(f"All {result.files_checked} file(s) are formatted.")
+            ctx.exit(0)
+    elif diff:
+        console = Console()
+        for diff_str in result.diffs:
+            syntax = Syntax(diff_str, "diff", theme="ansi_dark")
+            console.print(syntax)
+        ctx.exit(0)
+    else:
+        if result.files_formatted > 0:
+            click.echo(
+                f"Formatted {result.files_formatted} of "
+                f"{result.files_checked} file(s)."
+            )
+        else:
+            click.echo(f"All {result.files_checked} file(s) already formatted.")
+        ctx.exit(0)
+
+
+@cli.group()
+def coverage():
+    """Coverage reporting commands."""
+
+
+@coverage.command()
+@click.option("--format", help="Output format for the report.")
+@click.option("--output-dir", help="Directory to write the report to.")
+def report(format, output_dir):
+    """Generate a coverage report."""
+    try:
+        config = load_config()
+    except ConfigError as e:
+        click.echo(f"Error: {e}", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(2)
+
+    try:
+        result = generate_coverage_report(
+            config, report_format=format, output_dir=output_dir
+        )
+        click.echo(f"Report written to: {result.output_path}")
+    except GdToolsError as e:
+        click.echo(f"Error: {e}", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(e.exit_code)
+
+
+@coverage.command()
+@click.argument("files", nargs=-1, required=True)
+@click.option("--output", help="Path for the merged output file.")
+def merge(files, output):
+    """Merge multiple coverage files."""
+    try:
+        config = load_config()
+    except ConfigError as e:
+        click.echo(f"Error: {e}", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(2)
+
+    try:
+        merge_coverage_files(
+            [Path(f) for f in files],
+            Path(output) if output else None,
+            config=config,
+        )
+    except GdToolsError as e:
+        click.echo(f"Error: {e}", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(e.exit_code)
+
+
+@coverage.command()
+@click.option("--min", type=int, help="Minimum coverage threshold.")
+def show(min):
+    """Show coverage summary."""
+    try:
+        config = load_config()
+    except ConfigError as e:
+        click.echo(f"Error: {e}", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(2)
+
+    try:
+        show_coverage_summary(config, min_percent=min)
+    except CoverageThresholdError as e:
+        click.echo(f"Error: {e}", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(1)
+    except GdToolsError as e:
+        click.echo(f"Error: {e}", err=True)
+        ctx = click.get_current_context()
+        ctx.exit(e.exit_code)

gd_tools/config.py

@@ -0,0 +1,289 @@
+"""Configuration system for gd-tools.
+
+Provides Pydantic v2 models for typed loading, validation, and
+default resolution of ``gd-tools.toml`` configuration files.
+See TDD §3.2 for model definitions and PRD §6 for config format.
+"""
+
+import sys
+from pathlib import Path
+
+import tomli_w
+import yaml
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    ValidationError,
+    field_validator,
+)
+
+from gd_tools.errors import ConfigError
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+DEFAULT_EXCLUDES = ["addons", ".godot", ".gd-tools", ".git"]
+
+
+class GodotConfig(BaseModel):
+    """Configuration for the Godot binary.
+
+    Attributes:
+        binary: Path to the Godot binary. If None, auto-detection
+            is used (Track 4).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    binary: str | None = None
+
+
+class TestConfig(BaseModel):
+    """Configuration for test discovery and GUT.
+
+    Attributes:
+        test_dirs: Directories containing test files.
+        prefix: Test file prefix (GUT convention).
+        suffix: Test file suffix.
+        gutconfig: Path to the GUT config file.
+    """
+
+    __test__ = False
+
+    model_config = ConfigDict(extra="forbid")
+
+    test_dirs: list[str] = Field(default_factory=lambda: ["test", "tests"])
+    prefix: str = "test_"
+    suffix: str = ".gd"
+    gutconfig: str = ".gutconfig.json"
+
+
+class LintConfig(BaseModel):
+    """Configuration for linting.
+
+    Attributes:
+        exclude: List of directories excluded from linting.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    exclude: list[str] = Field(default_factory=lambda: DEFAULT_EXCLUDES.copy())
+
+
+class FormatConfig(BaseModel):
+    """Configuration for formatting.
+
+    Attributes:
+        exclude: List of directories excluded from formatting.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    exclude: list[str] = Field(default_factory=lambda: DEFAULT_EXCLUDES.copy())
+
+
+class CoverageConfig(BaseModel):
+    """Configuration for code coverage.
+
+    Attributes:
+        enabled: Whether coverage is enabled.
+        min_percent: Minimum coverage percentage threshold.
+        format: Report format (html, lcov, cobertura, text).
+        output_dir: Directory for coverage data and reports.
+        exclude: Directories excluded from coverage measurement.
+        test_dirs: Directories containing test files.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = False
+    min_percent: int = 0
+    format: str = "html"
+    output_dir: str = ".gd-tools/coverage"
+    exclude: list[str] = Field(default_factory=lambda: DEFAULT_EXCLUDES.copy())
+    test_dirs: list[str] = Field(default_factory=lambda: ["test", "tests"])
+
+
+class GdToolsConfig(BaseModel):
+    """Root configuration model for gd-tools.
+
+    Contains all configuration sections and a field validator
+    that enforces coverage format and min_percent constraints.
+
+    Attributes:
+        godot: Godot binary configuration.
+        test: Test discovery configuration.
+        lint: Linting configuration.
+        format: Formatting configuration.
+        coverage: Coverage configuration.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    godot: GodotConfig = Field(default_factory=GodotConfig)
+    test: TestConfig = Field(default_factory=TestConfig)
+    lint: LintConfig = Field(default_factory=LintConfig)
+    format: FormatConfig = Field(default_factory=FormatConfig)
+    coverage: CoverageConfig = Field(default_factory=CoverageConfig)
+
+    @field_validator("coverage")
+    @classmethod
+    def validate_coverage(cls, v: CoverageConfig) -> CoverageConfig:
+        """Validate coverage format and min_percent constraints.
+
+        Args:
+            v: The coverage configuration to validate.
+
+        Returns:
+            The validated coverage configuration.
+
+        Raises:
+            ValueError: If format is not in {html, lcov,
+                cobertura, text} or min_percent is outside
+                [0, 100].
+        """
+        if v.format not in (
+            "html",
+            "lcov",
+            "cobertura",
+            "text",
+        ):
+            raise ValueError(f"Invalid coverage format: {v.format}")
+        if not 0 <= v.min_percent <= 100:
+            raise ValueError(f"min_percent must be 0-100, got {v.min_percent}")
+        return v
+
+
+def find_project_root(
+    start_path: Path | None = None,
+) -> Path:
+    """Walk up from start_path to find the nearest project.godot.
+
+    Args:
+        start_path: Directory to start searching from.
+            Defaults to the current working directory.
+
+    Returns:
+        The directory containing ``project.godot``.
+
+    Raises:
+        ConfigError: If ``project.godot`` is not found in any
+            parent directory.
+    """
+    if start_path is None:
+        start_path = Path.cwd()
+    current = start_path.resolve()
+    while True:
+        if (current / "project.godot").is_file():
+            return current
+        if current == current.parent:
+            raise ConfigError(
+                "project.godot not found in any parent "
+                f"directory starting from {start_path}"
+            )
+        current = current.parent
+
+
+def load_config(
+    project_root: Path | None = None,
+) -> GdToolsConfig:
+    """Load gd-tools.toml configuration from the project root.
+
+    If ``project_root`` is None, discovers it via
+    :func:`find_project_root`.
+
+    Args:
+        project_root: Path to the project root directory.
+            If None, the project root is discovered
+            automatically.
+
+    Returns:
+        A typed ``GdToolsConfig`` object. If
+        ``gd-tools.toml`` is missing, returns an object
+        with all default values.
+
+    Raises:
+        ConfigError: If the TOML file is invalid or contains
+            values that fail Pydantic validation.
+    """
+    if project_root is None:
+        project_root = find_project_root()
+
+    config_file = project_root / "gd-tools.toml"
+    if not config_file.is_file():
+        return GdToolsConfig()
+
+    try:
+        with open(config_file, "rb") as f:
+            data = tomllib.load(f)
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"Invalid TOML in {config_file}: {exc}") from exc
+
+    try:
+        return GdToolsConfig(**data)
+    except ValidationError as exc:
+        raise ConfigError(
+            f"Invalid configuration in {config_file}: " f"{exc}"
+        ) from exc
+
+
+def save_config(
+    config: GdToolsConfig,
+    project_root: Path,
+) -> None:
+    """Write a GdToolsConfig to gd-tools.toml in the project root.
+
+    Produces valid TOML that round-trips through
+    :func:`load_config`.
+
+    Args:
+        config: The configuration to serialize.
+        project_root: Path to the project root directory.
+    """
+    config_file = project_root / "gd-tools.toml"
+    data = config.model_dump(exclude_none=True)
+    with open(config_file, "wb") as f:
+        tomli_w.dump(data, f)
+
+
+def generate_gdlintrc(
+    config: GdToolsConfig,
+    project_root: Path,
+) -> None:
+    """Generate a gdlintrc file from the lint exclude list.
+
+    Writes the excludes as a YAML set to ``gdlintrc`` in
+    the project root, using the ``!!set`` tag format that
+    gdtoolkit expects. Overwrites the file if it already
+    exists.
+
+    Args:
+        config: The configuration to read excludes from.
+        project_root: Path to the project root directory.
+    """
+    rc_file = project_root / "gdlintrc"
+    data = {"excluded_directories": set(config.lint.exclude)}
+    content = yaml.dump(data, default_flow_style=False, sort_keys=True)
+    rc_file.write_text(content, encoding="utf-8")
+
+
+def generate_gdformatrc(
+    config: GdToolsConfig,
+    project_root: Path,
+) -> None:
+    """Generate a gdformatrc file from the format exclude list.
+
+    Writes one exclude path per line to ``gdformatrc`` in
+    the project root. Overwrites the file if it already
+    exists.
+
+    Args:
+        config: The configuration to read excludes from.
+        project_root: Path to the project root directory.
+    """
+    rc_file = project_root / "gdformatrc"
+    content = "\n".join(config.format.exclude) + "\n"
+    rc_file.write_text(content, encoding="utf-8")

gd_tools/coverage/__init__.py

@@ -0,0 +1,23 @@
+"""Coverage subsystem package.
+
+Re-exports the orchestrator functions for convenient access:
+
+- :func:`run_coverage_test`: Full coverage flow (plan -> run -> report).
+- :func:`generate_coverage_report`: Regenerate reports from existing data.
+- :func:`merge_coverage_files`: Merge multiple coverage data files.
+- :func:`show_coverage_summary`: Print terminal summary table.
+"""
+
+from gd_tools.coverage.orchestrator import (
+    generate_coverage_report,
+    merge_coverage_files,
+    run_coverage_test,
+    show_coverage_summary,
+)
+
+__all__ = [
+    "run_coverage_test",
+    "generate_coverage_report",
+    "merge_coverage_files",
+    "show_coverage_summary",
+]