thailint 0.5.0__py3-none-any.whl → 0.15.3__py3-none-any.whl

src/cli/main.py

@@ -0,0 +1,120 @@
+"""
+Purpose: Main CLI group definition and core setup for thai-lint command-line interface
+
+Scope: Core Click group configuration, version handling, global options, and context setup
+
+Overview: Defines the root CLI command group using Click framework with version option and global
+    options (verbose, config, project-root). Handles context initialization, logging setup, and
+    configuration loading. Serves as the central entry point that other CLI modules register
+    commands against. Provides the foundation for modular CLI architecture where commands are
+    defined in separate modules but registered to this main group.
+
+Dependencies: click for CLI framework, src.config for configuration loading, src.__version__ for
+    version info
+
+Exports: cli (main Click command group), setup_logging function
+
+Interfaces: Click context object with config, verbose, project_root options stored in ctx.obj
+
+Implementation: Uses Click decorators for group definition, stores parsed options in context
+    for child commands to access. Defers project root determination to avoid import issues
+    in test environments.
+"""
+
+import logging
+import sys
+from pathlib import Path
+
+import click
+
+from src import __version__
+from src.config import ConfigError, load_config
+
+# Configure module logger
+logger = logging.getLogger(__name__)
+
+
+def setup_logging(verbose: bool = False) -> None:
+    """Configure logging for the CLI application.
+
+    Args:
+        verbose: Enable DEBUG level logging if True, INFO otherwise.
+    """
+    level = logging.DEBUG if verbose else logging.INFO
+
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s | %(levelname)-8s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+        stream=sys.stdout,
+    )
+
+
+@click.group()
+@click.version_option(version=__version__)
+@click.option("--verbose", "-v", is_flag=True, help="Enable verbose output")
+@click.option("--config", "-c", type=click.Path(), help="Path to config file")
+@click.option(
+    "--project-root",
+    type=click.Path(),
+    help="Explicitly specify project root directory (overrides auto-detection)",
+)
+@click.pass_context
+def cli(ctx: click.Context, verbose: bool, config: str | None, project_root: str | None) -> None:
+    """thai-lint - AI code linter and governance tool
+
+    Lint and governance for AI-generated code across multiple languages.
+    Identifies common mistakes, anti-patterns, and security issues.
+
+    Examples:
+
+        \b
+        # Check for duplicate code (DRY violations)
+        thai-lint dry .
+
+        \b
+        # Lint current directory for file placement issues
+        thai-lint file-placement .
+
+        \b
+        # Lint with custom config
+        thai-lint file-placement --config .thailint.yaml src/
+
+        \b
+        # Specify project root explicitly (useful in Docker)
+        thai-lint --project-root /workspace/root magic-numbers backend/
+
+        \b
+        # Get JSON output
+        thai-lint file-placement --format json .
+
+        \b
+        # Show help
+        thai-lint --help
+    """
+    # Ensure context object exists
+    ctx.ensure_object(dict)
+
+    # Setup logging
+    setup_logging(verbose)
+
+    # Store CLI options for later project root determination
+    # (deferred to avoid pyprojroot import issues in test environments)
+    ctx.obj["cli_project_root"] = project_root
+    ctx.obj["cli_config_path"] = config
+
+    # Load configuration
+    try:
+        if config:
+            ctx.obj["config"] = load_config(Path(config))
+            ctx.obj["config_path"] = Path(config)
+        else:
+            ctx.obj["config"] = load_config()
+            ctx.obj["config_path"] = None
+
+        logger.debug("Configuration loaded successfully")
+    except ConfigError as e:
+        click.echo(f"Error loading configuration: {e}", err=True)
+        sys.exit(2)
+
+    ctx.obj["verbose"] = verbose

src/cli/utils.py

@@ -0,0 +1,395 @@
+"""
+Purpose: Shared CLI utilities and helper functions for thai-lint commands
+
+Scope: Project root resolution, path validation, common decorators, and orchestrator setup
+
+Overview: Provides reusable utilities for CLI commands including project root determination with
+    precedence rules (explicit > config-inferred > auto-detected), path existence validation,
+    common Click option decorators (format, project-root), and orchestrator setup helpers.
+    Centralizes shared logic to reduce duplication across linter command modules while
+    maintaining consistent behavior for all CLI operations.
+
+Dependencies: click for CLI framework, pathlib for file paths, logging for debug output,
+    src.orchestrator for linting execution, src.utils.project_root for auto-detection
+
+Exports: format_option decorator, get_project_root_from_context, validate_paths_exist,
+    setup_base_orchestrator, execute_linting_on_paths, handle_linting_error
+
+Interfaces: Click context integration via ctx.obj, Path objects for file operations
+
+Implementation: Uses Click decorators for option definitions, deferred imports for orchestrator
+    to support test environments, caches project root in context for efficiency
+"""
+
+import logging
+import sys
+from collections.abc import Callable
+from contextlib import suppress
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, TypeVar, cast
+
+import click
+
+if TYPE_CHECKING:
+    from src.orchestrator.core import Orchestrator
+
+# Configure module logger
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Common Option Decorators
+# =============================================================================
+
+
+F = TypeVar("F", bound=Callable[..., object])
+
+
+def format_option(func: F) -> F:
+    """Add --format option to a command for output format selection."""
+    return click.option(
+        "--format",
+        "-f",
+        type=click.Choice(["text", "json", "sarif"]),
+        default="text",
+        help="Output format",
+    )(func)
+
+
+def parallel_option(func: F) -> F:
+    """Add --parallel option to enable multi-core file processing."""
+    return click.option(
+        "--parallel",
+        "-p",
+        is_flag=True,
+        default=False,
+        help="Enable parallel file processing (uses multiple CPU cores)",
+    )(func)
+
+
+# =============================================================================
+# Project Root Determination
+# =============================================================================
+
+
+def _determine_project_root(
+    explicit_root: str | None, config_path: str | None, verbose: bool
+) -> Path:
+    """Determine project root with precedence rules.
+
+    Precedence order:
+    1. Explicit --project-root (highest priority)
+    2. Inferred from --config path directory
+    3. Auto-detection via get_project_root() (fallback)
+
+    Args:
+        explicit_root: Explicitly specified project root path (from --project-root)
+        config_path: Config file path (from --config)
+        verbose: Whether verbose logging is enabled
+
+    Returns:
+        Path to determined project root
+
+    Raises:
+        SystemExit: If explicit_root doesn't exist or is not a directory
+    """
+    from src.utils.project_root import get_project_root
+
+    # Priority 1: Explicit --project-root
+    if explicit_root:
+        return _resolve_explicit_project_root(explicit_root, verbose)
+
+    # Priority 2: Infer from --config path
+    if config_path:
+        return _infer_root_from_config(config_path, verbose)
+
+    # Priority 3: Auto-detection (fallback)
+    return _autodetect_project_root(verbose, get_project_root)
+
+
+def _resolve_explicit_project_root(explicit_root: str, verbose: bool) -> Path:
+    """Resolve and validate explicitly specified project root.
+
+    Args:
+        explicit_root: Explicitly specified project root path
+        verbose: Whether verbose logging is enabled
+
+    Returns:
+        Resolved project root path
+
+    Raises:
+        SystemExit: If explicit_root doesn't exist or is not a directory
+    """
+    root = Path(explicit_root)
+    # Check existence before resolving to handle relative paths in test environments
+    if not root.exists():
+        click.echo(f"Error: Project root does not exist: {explicit_root}", err=True)
+        sys.exit(2)
+    if not root.is_dir():
+        click.echo(f"Error: Project root must be a directory: {explicit_root}", err=True)
+        sys.exit(2)
+
+    # Now resolve after validation
+    root = root.resolve()
+
+    if verbose:
+        logger.debug(f"Using explicit project root: {root}")
+    return root
+
+
+def _infer_root_from_config(config_path: str, verbose: bool) -> Path:
+    """Infer project root from config file path.
+
+    Args:
+        config_path: Config file path
+        verbose: Whether verbose logging is enabled
+
+    Returns:
+        Inferred project root (parent directory of config file)
+    """
+    config_file = Path(config_path).resolve()
+    inferred_root = config_file.parent
+
+    if verbose:
+        logger.debug(f"Inferred project root from config path: {inferred_root}")
+    return inferred_root
+
+
+def _autodetect_project_root(
+    verbose: bool, get_project_root: Callable[[Path | None], Path]
+) -> Path:
+    """Auto-detect project root using project root detection.
+
+    Args:
+        verbose: Whether verbose logging is enabled
+        get_project_root: Function to detect project root
+
+    Returns:
+        Auto-detected project root
+    """
+    auto_root = get_project_root(None)
+    if verbose:
+        logger.debug(f"Auto-detected project root: {auto_root}")
+    return auto_root
+
+
+def get_project_root_from_context(ctx: click.Context) -> Path | None:
+    """Get or determine project root from Click context.
+
+    This function defers the actual determination until needed to avoid
+    importing pyprojroot in test environments where it may not be available.
+
+    Returns None when no explicit root is specified (via --project-root or --config),
+    allowing the orchestrator to auto-detect from target paths instead of CWD.
+
+    Args:
+        ctx: Click context containing CLI options
+
+    Returns:
+        Path to determined project root, or None for auto-detection from target paths
+    """
+    # Check if already determined and cached
+    with suppress(KeyError):
+        return cast(Path | None, ctx.obj["project_root"])
+
+    project_root = _determine_project_root_for_context(ctx)
+    ctx.obj["project_root"] = project_root
+    return project_root
+
+
+def _determine_project_root_for_context(ctx: click.Context) -> Path | None:
+    """Determine project root from context options.
+
+    Args:
+        ctx: Click context containing CLI options
+
+    Returns:
+        Path if explicit root or config specified, None for auto-detection
+    """
+    explicit_root = ctx.obj.get("cli_project_root")
+    config_path = ctx.obj.get("cli_config_path")
+    verbose = ctx.obj.get("verbose", False)
+
+    if explicit_root:
+        return _resolve_explicit_project_root(explicit_root, verbose)
+
+    if config_path:
+        return _infer_root_from_config(config_path, verbose)
+
+    # No explicit root - return None for auto-detection from target paths
+    if verbose:
+        logger.debug("No explicit project root, will auto-detect from target paths")
+    return None
+
+
+# =============================================================================
+# Path Validation
+# =============================================================================
+
+
+def validate_paths_exist(path_objs: list[Path]) -> None:
+    """Validate that all provided paths exist.
+
+    Args:
+        path_objs: List of Path objects to validate
+
+    Raises:
+        SystemExit: If any path doesn't exist (exit code 2)
+    """
+    for path in path_objs:
+        if not path.exists():
+            click.echo(f"Error: Path does not exist: {path}", err=True)
+            click.echo("", err=True)
+            click.echo(
+                "Hint: When using Docker, ensure paths are inside the mounted volume:", err=True
+            )
+            click.echo(
+                "  docker run -v $(pwd):/data thailint <command> /data/your-file.py", err=True
+            )
+            sys.exit(2)
+
+
+# =============================================================================
+# Error Handling
+# =============================================================================
+
+
+def handle_linting_error(error: Exception, verbose: bool) -> None:
+    """Handle linting errors.
+
+    Args:
+        error: The exception that occurred
+        verbose: Whether verbose logging is enabled
+    """
+    click.echo(f"Error during linting: {error}", err=True)
+    if verbose:
+        logger.exception("Linting failed with exception")
+    sys.exit(2)
+
+
+# =============================================================================
+# Orchestrator Setup
+# =============================================================================
+
+
+def get_or_detect_project_root(path_objs: list[Path], project_root: Path | None) -> Path:
+    """Get provided project root or auto-detect from paths.
+
+    Args:
+        path_objs: List of path objects
+        project_root: Optionally provided project root
+
+    Returns:
+        Project root path
+    """
+    if project_root is not None:
+        return project_root
+
+    from src.utils.project_root import get_project_root
+
+    # Find actual project root (where .git or pyproject.toml exists)
+    first_path = path_objs[0] if path_objs else Path.cwd()
+    search_start = first_path if first_path.is_dir() else first_path.parent
+    return get_project_root(search_start)
+
+
+def setup_base_orchestrator(
+    path_objs: list[Path], config_file: str | None, verbose: bool, project_root: Path | None = None
+) -> "Orchestrator":
+    """Set up orchestrator for linter commands.
+
+    Args:
+        path_objs: List of path objects to lint
+        config_file: Optional config file path
+        verbose: Whether verbose logging is enabled
+        project_root: Optional explicit project root
+
+    Returns:
+        Configured Orchestrator instance
+    """
+    from src.orchestrator.core import Orchestrator
+
+    root = get_or_detect_project_root(path_objs, project_root)
+    orchestrator = Orchestrator(project_root=root)
+
+    if config_file:
+        load_config_file(orchestrator, config_file, verbose)
+
+    return orchestrator
+
+
+def load_config_file(orchestrator: "Orchestrator", config_file: str, verbose: bool) -> None:
+    """Load configuration from external file.
+
+    Args:
+        orchestrator: Orchestrator instance
+        config_file: Path to config file
+        verbose: Whether verbose logging is enabled
+    """
+    config_path = Path(config_file)
+    if not config_path.exists():
+        click.echo(f"Error: Config file not found: {config_file}", err=True)
+        sys.exit(2)
+
+    # Load config into orchestrator
+    orchestrator.config = orchestrator.config_loader.load(config_path)
+
+    if verbose:
+        logger.debug(f"Loaded config from: {config_file}")
+
+
+# =============================================================================
+# Linting Execution
+# =============================================================================
+
+
+def separate_files_and_dirs(path_objs: list[Path]) -> tuple[list[Path], list[Path]]:
+    """Separate file paths from directory paths.
+
+    Args:
+        path_objs: List of Path objects
+
+    Returns:
+        Tuple of (files, directories)
+    """
+    files = [p for p in path_objs if p.is_file()]
+    dirs = [p for p in path_objs if p.is_dir()]
+    return files, dirs
+
+
+def execute_linting_on_paths(
+    orchestrator: "Orchestrator",
+    path_objs: list[Path],
+    recursive: bool,
+    parallel: bool = False,
+) -> list[Any]:
+    """Execute linting on list of file/directory paths.
+
+    Args:
+        orchestrator: Orchestrator instance
+        path_objs: List of Path objects (files or directories)
+        recursive: Whether to scan directories recursively
+        parallel: Whether to use parallel processing for multiple files
+
+    Returns:
+        List of violations from all paths
+    """
+    files, dirs = separate_files_and_dirs(path_objs)
+
+    violations = []
+
+    # Lint files
+    if files:
+        if parallel:
+            violations.extend(orchestrator.lint_files_parallel(files))
+        else:
+            violations.extend(orchestrator.lint_files(files))
+
+    # Lint directories
+    for dir_path in dirs:
+        if parallel:
+            violations.extend(orchestrator.lint_directory_parallel(dir_path, recursive=recursive))
+        else:
+            violations.extend(orchestrator.lint_directory(dir_path, recursive=recursive))
+
+    return violations

src/cli_main.py

@@ -0,0 +1,37 @@
+"""
+Purpose: Main CLI entrypoint for thai-lint command-line interface
+
+Scope: CLI package initialization and command registration via module imports
+
+Overview: Thin entry point that imports and re-exports the fully configured CLI from the modular
+    src.cli package. All linter commands are registered via decorator side effects when their
+    modules are imported. Configuration commands (hello, config group, init-config) are in
+    src.cli.config, and linter commands (nesting, srp, dry, magic-numbers, file-placement,
+    print-statements, file-header, method-property, stateless-class, pipeline) are in
+    src.cli.linters submodules.
+
+Dependencies: click for CLI framework, src.cli for modular CLI package
+
+Exports: cli (main command group with all commands registered)
+
+Interfaces: Click CLI commands, integration with Orchestrator for linting execution
+
+Implementation: Module imports trigger command registration via Click decorator side effects
+
+Suppressions:
+    - F401: Module re-exports and imports trigger Click command registration via decorator side effects
+"""
+
+# Import the main CLI group from the modular package
+# Import config module to register configuration commands
+# (hello, config group, init-config)
+from src.cli import config as _config_module  # noqa: F401
+
+# Import linters package to register all linter commands
+# (nesting, srp, dry, magic-numbers, file-placement, print-statements,
+#  file-header, method-property, stateless-class, pipeline)
+from src.cli import linters as _linters_module  # noqa: F401
+from src.cli.main import cli  # noqa: F401
+
+if __name__ == "__main__":
+    cli()

src/config.py

@@ -26,6 +26,7 @@ from typing import Any
 import yaml
 
 from src.core.config_parser import ConfigParseError, parse_config_file
+from src.core.constants import CONFIG_EXTENSIONS
 
 logger = logging.getLogger(__name__)
 
@@ -103,9 +104,8 @@ def _load_from_explicit_path(config_path: Path) -> dict[str, Any]:
 
 def _load_from_default_locations() -> dict[str, Any]:
     """Load config from default locations."""
-    for location in CONFIG_LOCATIONS:
-        if not location.exists():
-            continue
+    existing_locations = (loc for loc in CONFIG_LOCATIONS if loc.exists())
+    for location in existing_locations:
         loaded_config = _try_load_from_location(location)
         if loaded_config:
             return loaded_config
@@ -171,7 +171,7 @@ def _validate_before_save(config: dict[str, Any]) -> None:
 
 def _write_config_file(config: dict[str, Any], path: Path) -> None:
     """Write config to file based on extension."""
-    if path.suffix in [".yaml", ".yml"]:
+    if path.suffix in CONFIG_EXTENSIONS:
         _write_yaml_config(config, path)
     elif path.suffix == ".json":
         _write_json_config(config, path)
@@ -237,37 +237,47 @@ def _validate_required_keys(config: dict[str, Any], errors: list[str]) -> None:
 def _validate_log_level(config: dict[str, Any], errors: list[str]) -> None:
     """Validate log level is a valid value."""
     valid_log_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
-    if "log_level" in config:
-        if config["log_level"] not in valid_log_levels:
-            errors.append(
-                f"Invalid log_level: {config['log_level']}. "
-                f"Must be one of: {', '.join(valid_log_levels)}"
-            )
+    try:
+        log_level = config["log_level"]
+    except KeyError:
+        return  # Optional key not present
+    if log_level not in valid_log_levels:
+        errors.append(
+            f"Invalid log_level: {log_level}. Must be one of: {', '.join(valid_log_levels)}"
+        )
 
 
 def _validate_output_format(config: dict[str, Any], errors: list[str]) -> None:
     """Validate output format is a valid value."""
     valid_formats = ["text", "json", "yaml"]
-    if "output_format" in config:
-        if config["output_format"] not in valid_formats:
-            errors.append(
-                f"Invalid output_format: {config['output_format']}. "
-                f"Must be one of: {', '.join(valid_formats)}"
-            )
+    try:
+        output_format = config["output_format"]
+    except KeyError:
+        return  # Optional key not present
+    if output_format not in valid_formats:
+        errors.append(
+            f"Invalid output_format: {output_format}. Must be one of: {', '.join(valid_formats)}"
+        )
 
 
 def _validate_max_retries(config: dict[str, Any], errors: list[str]) -> None:
     """Validate max_retries configuration value."""
-    if "max_retries" in config:
-        if not isinstance(config["max_retries"], int) or config["max_retries"] < 0:
-            errors.append("max_retries must be a non-negative integer")
+    try:
+        max_retries = config["max_retries"]
+    except KeyError:
+        return  # Optional key not present
+    if not isinstance(max_retries, int) or max_retries < 0:
+        errors.append("max_retries must be a non-negative integer")
 
 
 def _validate_timeout(config: dict[str, Any], errors: list[str]) -> None:
     """Validate timeout configuration value."""
-    if "timeout" in config:
-        if not isinstance(config["timeout"], (int, float)) or config["timeout"] <= 0:
-            errors.append("timeout must be a positive number")
+    try:
+        timeout = config["timeout"]
+    except KeyError:
+        return  # Optional key not present
+    if not isinstance(timeout, (int, float)) or timeout <= 0:
+        errors.append("timeout must be a positive number")
 
 
 def _validate_numeric_values(config: dict[str, Any], errors: list[str]) -> None:
@@ -278,9 +288,12 @@ def _validate_numeric_values(config: dict[str, Any], errors: list[str]) -> None:
 
 def _validate_string_values(config: dict[str, Any], errors: list[str]) -> None:
     """Validate string configuration values."""
-    if "app_name" in config:
-        if not isinstance(config["app_name"], str) or not config["app_name"].strip():
-            errors.append("app_name must be a non-empty string")
+    try:
+        app_name = config["app_name"]
+    except KeyError:
+        return  # Optional key not present
+    if not isinstance(app_name, str) or not app_name.strip():
+        errors.append("app_name must be a non-empty string")
 
 
 def validate_config(config: dict[str, Any]) -> tuple[bool, list[str]]:

src/core/base.py

@@ -31,6 +31,7 @@ from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import Any
 
+from .constants import Language
 from .types import Violation
 
 
@@ -151,6 +152,10 @@ class MultiLanguageLintRule(BaseLintRule):
     - _load_config(context) for configuration loading
     """
 
+    def __init__(self) -> None:
+        """Initialize the multi-language lint rule."""
+        pass  # Base class for multi-language linters
+
     def check(self, context: BaseLintContext) -> list[Violation]:
         """Check for violations with automatic language dispatch.
 
@@ -172,10 +177,10 @@ class MultiLanguageLintRule(BaseLintRule):
         if not config.enabled:
             return []
 
-        if context.language == "python":
+        if context.language == Language.PYTHON:
             return self._check_python(context, config)
 
-        if context.language in ("typescript", "javascript"):
+        if context.language in (Language.TYPESCRIPT, Language.JAVASCRIPT):
             return self._check_typescript(context, config)
 
         return []