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

src/linters/srp/violation_builder.py

@@ -0,0 +1,117 @@
+"""
+Purpose: Violation creation with suggestions for SRP linter
+
+Scope: Builds Violation objects with contextual messages and refactoring suggestions
+
+Overview: Provides violation building functionality for the SRP linter. Creates violations
+    from class metrics and issue descriptions, generates contextual error messages, and
+    provides actionable refactoring suggestions based on issue types (methods, lines, keywords).
+    Isolates violation construction and suggestion generation from metrics evaluation and
+    class analysis to maintain single responsibility.
+
+Dependencies: BaseLintContext, Violation, Severity, typing, src.core.violation_builder
+
+Exports: ViolationBuilder
+
+Interfaces: build_violation(metrics, issues, rule_id, context) -> Violation
+
+Implementation: Formats messages from metrics, generates targeted suggestions per issue type,
+    extends BaseViolationBuilder for consistent violation construction
+"""
+
+from typing import Any
+
+from src.core.base import BaseLintContext
+from src.core.types import Severity, Violation
+from src.core.violation_builder import BaseViolationBuilder, ViolationInfo
+
+
+class ViolationBuilder(BaseViolationBuilder):
+    """Builds SRP violations with messages and suggestions."""
+
+    def build_violation(
+        self,
+        metrics: dict[str, Any],
+        issues: list[str],
+        rule_id: str,
+        context: BaseLintContext,
+    ) -> Violation:
+        """Build violation from metrics and issues.
+
+        Args:
+            metrics: Class metrics dictionary
+            issues: List of issue descriptions
+            rule_id: Rule identifier
+            context: Lint context
+
+        Returns:
+            Violation with message and suggestion
+        """
+        message = f"Class '{metrics['class_name']}' may violate SRP: {', '.join(issues)}"
+        suggestion = self._generate_suggestion(issues)
+
+        info = ViolationInfo(
+            rule_id=rule_id,
+            file_path=str(context.file_path or ""),
+            line=metrics["line"],
+            column=metrics["column"],
+            message=message,
+            severity=Severity.ERROR,
+            suggestion=suggestion,
+        )
+        return self.build(info)
+
+    def _generate_suggestion(self, issues: list[str]) -> str:
+        """Generate refactoring suggestion based on issues.
+
+        Args:
+            issues: List of issue descriptions
+
+        Returns:
+            Suggestion string with refactoring advice
+        """
+        suggestions = [
+            self._suggest_for_methods(issues),
+            self._suggest_for_lines(issues),
+            self._suggest_for_keywords(issues),
+        ]
+        return ". ".join(filter(None, suggestions))
+
+    def _suggest_for_methods(self, issues: list[str]) -> str:
+        """Suggest fix for too many methods.
+
+        Args:
+            issues: List of issue descriptions
+
+        Returns:
+            Suggestion string or empty string
+        """
+        if any("methods" in issue for issue in issues):
+            return "Consider extracting related methods into separate classes"
+        return ""
+
+    def _suggest_for_lines(self, issues: list[str]) -> str:
+        """Suggest fix for too many lines.
+
+        Args:
+            issues: List of issue descriptions
+
+        Returns:
+            Suggestion string or empty string
+        """
+        if any("lines" in issue for issue in issues):
+            return "Consider breaking the class into smaller, focused classes"
+        return ""
+
+    def _suggest_for_keywords(self, issues: list[str]) -> str:
+        """Suggest fix for responsibility keywords.
+
+        Args:
+            issues: List of issue descriptions
+
+        Returns:
+            Suggestion string or empty string
+        """
+        if any("keyword" in issue for issue in issues):
+            return "Avoid generic names like Manager, Handler, Processor"
+        return ""

src/orchestrator/core.py

@@ -89,26 +89,32 @@ class Orchestrator:
     detection to provide comprehensive linting of files and directories.
     """
 
-    def __init__(self, project_root: Path | None = None):
+    def __init__(self, project_root: Path | None = None, config: dict | None = None):
         """Initialize orchestrator.
 
         Args:
             project_root: Root directory of project. Defaults to current directory.
+            config: Optional pre-loaded configuration dict. If provided, skips config file loading.
         """
         self.project_root = project_root or Path.cwd()
         self.registry = RuleRegistry()
         self.config_loader = LinterConfigLoader()
         self.ignore_parser = IgnoreDirectiveParser(self.project_root)
 
-        # Auto-discover and register all linting rules from src.linters
-        self.registry.discover_rules("src.linters")
+        # Performance optimization: Defer rule discovery until first file is linted
+        # This eliminates ~0.077s overhead for commands that don't need rules (--help, config, etc.)
+        self._rules_discovered = False
 
-        # Load configuration from project root
-        config_path = self.project_root / ".thailint.yaml"
-        if not config_path.exists():
-            config_path = self.project_root / ".thailint.json"
+        # Use provided config or load from project root
+        if config is not None:
+            self.config = config
+        else:
+            # Load configuration from project root
+            config_path = self.project_root / ".thailint.yaml"
+            if not config_path.exists():
+                config_path = self.project_root / ".thailint.json"
 
-        self.config = self.config_loader.load(config_path)
+            self.config = self.config_loader.load(config_path)
 
     def lint_file(self, file_path: Path) -> list[Violation]:
         """Lint a single file.
@@ -124,10 +130,33 @@ class Orchestrator:
 
         language = detect_language(file_path)
         rules = self._get_rules_for_file(file_path, language)
-        context = FileLintContext(file_path, language, metadata=self.config)
+
+        # Add project_root to metadata for rules that need it (e.g., DRY linter cache)
+        metadata = {**self.config, "_project_root": self.project_root}
+        context = FileLintContext(file_path, language, metadata=metadata)
 
         return self._execute_rules(rules, context)
 
+    def lint_files(self, file_paths: list[Path]) -> list[Violation]:
+        """Lint multiple files.
+
+        Args:
+            file_paths: List of file paths to lint.
+
+        Returns:
+            List of violations found across all files.
+        """
+        violations = []
+
+        for file_path in file_paths:
+            violations.extend(self.lint_file(file_path))
+
+        # Call finalize() on all rules after processing all files
+        for rule in self.registry.list_all():
+            violations.extend(rule.finalize())
+
+        return violations
+
     def _execute_rules(
         self, rules: list[BaseLintRule], context: BaseLintContext
     ) -> list[Violation]:
@@ -150,6 +179,9 @@ class Orchestrator:
         """Safely check a rule, returning empty list on error."""
         try:
             return rule.check(context)
+        except ValueError:
+            # Re-raise configuration validation errors (these are user-facing)
+            raise
         except Exception:  # nosec B112
             # Skip rules that fail (defensive programming)
             return []
@@ -171,8 +203,18 @@ class Orchestrator:
             if file_path.is_file():
                 violations.extend(self.lint_file(file_path))
 
+        # Call finalize() on all rules after processing all files
+        for rule in self.registry.list_all():
+            violations.extend(rule.finalize())
+
         return violations
 
+    def _ensure_rules_discovered(self) -> None:
+        """Ensure rules have been discovered and registered (lazy initialization)."""
+        if not self._rules_discovered:
+            self.registry.discover_rules("src.linters")
+            self._rules_discovered = True
+
     def _get_rules_for_file(self, file_path: Path, language: str) -> list[BaseLintRule]:
         """Get rules applicable to this file.
 
@@ -183,6 +225,9 @@ class Orchestrator:
         Returns:
             List of rules to execute against this file.
         """
+        # Lazy initialization: discover rules on first lint operation
+        self._ensure_rules_discovered()
+
         # For now, return all registered rules
         # Future: filter by language, configuration, etc.
         return self.registry.list_all()

src/templates/thailint_config_template.yaml

@@ -0,0 +1,158 @@
+# thai-lint Configuration File
+# Generated by: thailint init-config
+#
+# For non-interactive mode (AI agents): thailint init-config --non-interactive
+#
+# Full documentation: https://github.com/your-org/thai-lint
+
+# ============================================================================
+# MAGIC NUMBERS LINTER
+# ============================================================================
+# Detects unnamed numeric literals that should be extracted as constants
+#
+# Preset: {{PRESET}}
+#
+magic-numbers:
+  enabled: true
+
+  # Numbers that are acceptable without being named constants
+  # Default: [-1, 0, 1, 2, 3, 4, 5, 10, 100, 1000]
+  allowed_numbers: {{ALLOWED_NUMBERS}}
+
+  # Maximum integer allowed in range() or enumerate() without flagging
+  # Default: 10
+  max_small_integer: {{MAX_SMALL_INTEGER}}
+
+  # -------------------------------------------------------------------------
+  # OPTIONAL: Uncomment to add time conversions (lenient mode)
+  # -------------------------------------------------------------------------
+  # allowed_numbers: [-1, 0, 1, 2, 3, 4, 5, 10, 60, 100, 1000, 3600]
+
+  # -------------------------------------------------------------------------
+  # OPTIONAL: Uncomment to add common HTTP status codes
+  # -------------------------------------------------------------------------
+  # allowed_numbers: [-1, 0, 1, 2, 3, 4, 5, 10, 100, 200, 201, 204, 400, 401, 403, 404, 500, 502, 503, 1000]
+
+  # -------------------------------------------------------------------------
+  # OPTIONAL: Uncomment to add decimal proportions (0.0-1.0)
+  # -------------------------------------------------------------------------
+  # allowed_numbers: [-1, 0, 1, 2, 3, 4, 5, 10, 100, 1000, 0.0, 0.1, 0.2, 0.25, 0.3, 0.4, 0.5, 0.6, 0.7, 0.75, 0.8, 0.9, 1.0]
+
+# ============================================================================
+# NESTING LINTER
+# ============================================================================
+# Checks for excessive nesting depth (if/for/while/try statements)
+#
+nesting:
+  enabled: true
+
+  # Maximum nesting depth allowed
+  # Default: 4
+  max_nesting_depth: 4
+
+# ============================================================================
+# SINGLE RESPONSIBILITY PRINCIPLE (SRP) LINTER
+# ============================================================================
+# Detects classes that may have too many responsibilities
+#
+srp:
+  enabled: true
+
+  # Maximum methods per class
+  # Default: 7
+  max_methods: 7
+
+  # Maximum lines of code per class
+  # Default: 200
+  max_loc: 200
+
+# ============================================================================
+# DRY (DON'T REPEAT YOURSELF) LINTER
+# ============================================================================
+# Detects duplicate code blocks
+#
+dry:
+  enabled: true
+
+  # Minimum lines for a block to be considered duplicate
+  # Default: 6
+  min_duplicate_lines: 6
+
+  # Enable SQLite caching for faster incremental scans
+  # Default: true
+  cache_enabled: true
+
+  # Cache file location (relative to project root)
+  # Default: .thailint-cache/dry.db
+  cache_path: .thailint-cache/dry.db
+
+# ============================================================================
+# FILE PLACEMENT LINTER
+# ============================================================================
+# Ensures files are in appropriate directories
+#
+file-placement:
+  enabled: true
+
+  # Rules for file placement
+  rules:
+    # Test files should be in tests/ directory
+    - pattern: "test_*.py"
+      required_dir: "tests/"
+      message: "Test files must be in tests/ directory"
+
+    # Config files should be in config/ or root
+    - pattern: "*config*.py"
+      required_dir: ["config/", "./"]
+      message: "Config files should be in config/ or project root"
+
+# ============================================================================
+# PRINT STATEMENTS LINTER
+# ============================================================================
+# Detects print()/console.* statements that should use proper logging
+#
+print-statements:
+  enabled: true
+
+  # Allow print() in if __name__ == "__main__": blocks (Python only)
+  # Default: true
+  allow_in_scripts: true
+
+  # Console methods to detect in TypeScript/JavaScript
+  # Default: [log, warn, error, debug, info]
+  console_methods:
+    - log
+    - warn
+    - error
+    - debug
+    - info
+
+  # File patterns to ignore (glob syntax)
+  # ignore:
+  #   - "scripts/**"
+  #   - "**/debug.py"
+
+# ============================================================================
+# GLOBAL SETTINGS
+# ============================================================================
+#
+# Exclude patterns (files/directories to ignore)
+exclude:
+  - ".git/"
+  - ".venv/"
+  - "venv/"
+  - "node_modules/"
+  - "__pycache__/"
+  - "*.pyc"
+  - ".pytest_cache/"
+  - "dist/"
+  - "build/"
+  - ".eggs/"
+
+# Output format (text or json)
+# Default: text
+output_format: text
+
+# Exit with error code if violations found
+# Default: true
+fail_on_violations: true

src/utils/__init__.py

@@ -0,0 +1,4 @@
+"""Utils package for shared utilities.
+
+This package provides common utility functions used across the linter framework.
+"""

src/utils/project_root.py

@@ -0,0 +1,203 @@
+"""Project root detection utility.
+
+Purpose: Centralized project root detection for consistent file placement
+Scope: Single source of truth for finding project root directory
+
+Overview: Uses pyprojroot package to provide reliable project root detection across
+    different environments (development, CI/CD, user installations). Falls back to
+    manual detection if pyprojroot is not available (e.g., in test environments).
+    Searches for standard project markers like .git, .thailint.yaml, and pyproject.toml.
+
+Dependencies: pyprojroot (optional, with manual fallback)
+
+Exports: is_project_root(), get_project_root()
+
+Interfaces: Path-based functions for checking and finding project roots
+
+Implementation: pyprojroot delegation with manual fallback for test environments
+"""
+
+from pathlib import Path
+
+# Try to import pyprojroot, but don't fail if it's not available
+try:
+    from pyprojroot import find_root
+
+    HAS_PYPROJROOT = True
+except ImportError:
+    HAS_PYPROJROOT = False
+
+
+def _has_marker(path: Path, marker_name: str, is_dir: bool = False) -> bool:
+    """Check if a directory contains a specific marker.
+
+    Args:
+        path: Directory path to check
+        marker_name: Name of marker file or directory
+        is_dir: True if marker is a directory, False if it's a file
+
+    Returns:
+        True if marker exists, False otherwise
+    """
+    marker_path = path / marker_name
+    if is_dir:
+        return marker_path.is_dir()
+    return marker_path.is_file()
+
+
+def is_project_root(path: Path) -> bool:
+    """Check if a directory is a project root.
+
+    Uses pyprojroot if available, otherwise checks for common project markers
+    like .git, .thailint.yaml, or pyproject.toml.
+
+    Args:
+        path: Directory path to check
+
+    Returns:
+        True if the directory is a project root, False otherwise
+
+    Examples:
+        >>> is_project_root(Path("/home/user/myproject"))
+        True
+        >>> is_project_root(Path("/home/user/myproject/src"))
+        False
+    """
+    if not path.exists() or not path.is_dir():
+        return False
+
+    if HAS_PYPROJROOT:
+        return _check_root_with_pyprojroot(path)
+
+    return _check_root_with_markers(path)
+
+
+def _check_root_with_pyprojroot(path: Path) -> bool:
+    """Check if path is project root using pyprojroot.
+
+    Args:
+        path: Directory path to check
+
+    Returns:
+        True if path is a project root, False otherwise
+    """
+    try:
+        # Find root from this path - if it equals this path, it's a root
+        found_root = find_root(path)
+        return found_root == path.resolve()
+    except (OSError, RuntimeError):
+        # pyprojroot couldn't find a root
+        return False
+
+
+def _check_root_with_markers(path: Path) -> bool:
+    """Check if path contains project root markers.
+
+    Args:
+        path: Directory path to check
+
+    Returns:
+        True if path contains .git, .thailint.yaml, or pyproject.toml
+    """
+    return (
+        _has_marker(path, ".git", is_dir=True)
+        or _has_marker(path, ".thailint.yaml", is_dir=False)
+        or _has_marker(path, "pyproject.toml", is_dir=False)
+    )
+
+
+def _try_find_with_criterion(criterion: object, start_path: Path) -> Path | None:
+    """Try to find project root with a specific criterion.
+
+    Args:
+        criterion: pyprojroot criterion function (e.g., has_dir(".git"))
+        start_path: Path to start searching from
+
+    Returns:
+        Found project root or None if not found
+    """
+    try:
+        return find_root(criterion, start=start_path)  # type: ignore[arg-type]
+    except (OSError, RuntimeError):
+        return None
+
+
+def _find_root_manual(start_path: Path) -> Path:
+    """Manually find project root by walking up directory tree.
+
+    Fallback implementation when pyprojroot is not available.
+
+    Args:
+        start_path: Directory to start searching from
+
+    Returns:
+        Path to project root, or start_path if no markers found
+    """
+    current = start_path.resolve()
+
+    # Walk up the directory tree
+    for parent in [current] + list(current.parents):
+        # Check for project markers
+        if (
+            _has_marker(parent, ".git", is_dir=True)
+            or _has_marker(parent, ".thailint.yaml", is_dir=False)
+            or _has_marker(parent, "pyproject.toml", is_dir=False)
+        ):
+            return parent
+
+    # No markers found, return start path
+    return current
+
+
+def get_project_root(start_path: Path | None = None) -> Path:
+    """Find project root by walking up the directory tree.
+
+    This is the single source of truth for project root detection.
+    All code that needs to find the project root should use this function.
+
+    Uses pyprojroot if available, otherwise uses manual detection searching for
+    standard project markers (.git directory, pyproject.toml, .thailint.yaml, etc)
+    starting from start_path and walking upward.
+
+    Args:
+        start_path: Directory to start searching from. If None, uses current working directory.
+
+    Returns:
+        Path to project root directory. If no root markers found, returns the start_path.
+
+    Examples:
+        >>> root = get_project_root()
+        >>> config_file = root / ".thailint.yaml"
+    """
+    if start_path is None:
+        start_path = Path.cwd()
+
+    current = start_path.resolve()
+
+    if HAS_PYPROJROOT:
+        return _find_root_with_pyprojroot(current)
+
+    # Manual fallback for test environments
+    return _find_root_manual(current)
+
+
+def _find_root_with_pyprojroot(current: Path) -> Path:
+    """Find project root using pyprojroot library.
+
+    Args:
+        current: Current path to start searching from
+
+    Returns:
+        Path to project root, or current if no markers found
+    """
+    from pyprojroot import has_dir, has_file
+
+    # Search for project root markers in priority order
+    # Try .git first (most reliable), then .thailint.yaml, then pyproject.toml
+    for criterion in [has_dir(".git"), has_file(".thailint.yaml"), has_file("pyproject.toml")]:
+        root = _try_find_with_criterion(criterion, current)
+        if root is not None:
+            return root
+
+    # No markers found, return start path
+    return current