thailint 0.9.0__py3-none-any.whl → 0.11.0__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,375 @@
+"""
+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 pathlib import Path
+from typing import TYPE_CHECKING, Any, TypeVar
+
+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:
+    """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.
+
+    Args:
+        ctx: Click context containing CLI options
+
+    Returns:
+        Path to determined project root
+    """
+    # Check if already determined and cached
+    if "project_root" in ctx.obj:
+        cached_root: Path = ctx.obj["project_root"]
+        return cached_root
+
+    # Determine project root using stored CLI options
+    explicit_root = ctx.obj.get("cli_project_root")
+    config_path = ctx.obj.get("cli_config_path")
+    verbose = ctx.obj.get("verbose", False)
+
+    project_root = _determine_project_root(explicit_root, config_path, verbose)
+
+    # Cache for future use
+    ctx.obj["project_root"] = project_root
+
+    return project_root
+
+
+# =============================================================================
+# 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,34 @@
+"""
+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
+"""
+
+# 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

@@ -103,9 +103,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

src/core/rule_discovery.py

@@ -20,6 +20,7 @@ Implementation: Package traversal with pkgutil, class introspection with inspect
 import importlib
 import inspect
 import pkgutil
+from types import ModuleType
 from typing import Any
 
 from .base import BaseLintRule
@@ -87,19 +88,51 @@ def _discover_from_module(module_path: str) -> list[BaseLintRule]:
     Returns:
         List of discovered rule instances
     """
+    module = _try_import_module(module_path)
+    if module is None:
+        return []
+    return _extract_rules_from_module(module)
+
+
+def _try_import_module(module_path: str) -> ModuleType | None:
+    """Try to import a module, returning None on failure.
+
+    Args:
+        module_path: Full module path to import
+
+    Returns:
+        Module object or None if import fails
+    """
     try:
-        module = importlib.import_module(module_path)
+        return importlib.import_module(module_path)
     except (ImportError, AttributeError):
-        return []
+        return None
 
-    rules = []
-    for _name, obj in inspect.getmembers(module):
-        if not _is_rule_class(obj):
-            continue
-        rule_instance = _try_instantiate_rule(obj)
-        if rule_instance:
-            rules.append(rule_instance)
-    return rules
+
+def _extract_rules_from_module(module: ModuleType) -> list[BaseLintRule]:
+    """Extract rule instances from a module.
+
+    Args:
+        module: Imported module to scan
+
+    Returns:
+        List of discovered rule instances
+    """
+    rule_classes = [obj for _name, obj in inspect.getmembers(module) if _is_rule_class(obj)]
+    return _instantiate_rules(rule_classes)
+
+
+def _instantiate_rules(rule_classes: list[type[BaseLintRule]]) -> list[BaseLintRule]:
+    """Instantiate a list of rule classes.
+
+    Args:
+        rule_classes: List of rule classes to instantiate
+
+    Returns:
+        List of successfully instantiated rules
+    """
+    instances = (_try_instantiate_rule(cls) for cls in rule_classes)
+    return [inst for inst in instances if inst is not None]
 
 
 def _try_instantiate_rule(rule_class: type[BaseLintRule]) -> BaseLintRule | None:

src/core/types.py

@@ -81,3 +81,16 @@ class Violation:
             "severity": self.severity.value,
             "suggestion": self.suggestion,
         }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Violation":
+        """Reconstruct Violation from dictionary (for parallel processing)."""
+        return cls(
+            rule_id=data["rule_id"],
+            file_path=data["file_path"],
+            line=data["line"],
+            column=data["column"],
+            message=data["message"],
+            severity=Severity(data["severity"]),
+            suggestion=data.get("suggestion"),
+        )

src/core/violation_utils.py

@@ -0,0 +1,69 @@
+"""
+Purpose: Shared utility functions for violation processing across linters
+
+Scope: Common violation-related operations used by multiple linters
+
+Overview: Provides shared utility functions for working with violations, including
+    extracting line text and checking for ignore directives. These patterns were
+    previously duplicated across multiple linter modules (magic_numbers, print_statements,
+    method_property). Centralizing them here improves maintainability and ensures
+    consistent behavior across all linters.
+
+Dependencies: BaseLintContext, Violation types
+
+Exports: get_violation_line, has_python_noqa, has_typescript_noqa
+
+Interfaces:
+    get_violation_line(violation, context) -> str | None
+    has_python_noqa(line_text) -> bool
+    has_typescript_noqa(line_text) -> bool
+
+Implementation: Simple text extraction and pattern matching
+"""
+
+from src.core.base import BaseLintContext
+from src.core.types import Violation
+
+
+def get_violation_line(violation: Violation, context: BaseLintContext) -> str | None:
+    """Get the line text for a violation, lowercased.
+
+    Args:
+        violation: Violation to get line for
+        context: Lint context with file content
+
+    Returns:
+        Lowercased line text, or None if not available
+    """
+    if not context.file_content:
+        return None
+
+    lines = context.file_content.splitlines()
+    if violation.line <= 0 or violation.line > len(lines):
+        return None
+
+    return lines[violation.line - 1].lower()
+
+
+def has_python_noqa(line_text: str) -> bool:
+    """Check if line has Python-style noqa directive.
+
+    Args:
+        line_text: Lowercased line text
+
+    Returns:
+        True if line has # noqa comment
+    """
+    return "# noqa" in line_text
+
+
+def has_typescript_noqa(line_text: str) -> bool:
+    """Check if line has TypeScript-style noqa directive.
+
+    Args:
+        line_text: Lowercased line text
+
+    Returns:
+        True if line has // noqa comment
+    """
+    return "// noqa" in line_text