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

src/linters/file_placement/path_resolver.py

@@ -0,0 +1,61 @@
+"""
+Purpose: Path resolution and normalization for file placement linter
+
+Scope: Handles path operations including relative path calculation and normalization
+
+Overview: Provides path resolution utilities for the file placement linter. Converts
+    absolute paths to paths relative to project root, normalizes path separators for
+    cross-platform compatibility, and handles edge cases like paths outside project root.
+    Isolates path manipulation logic from rule checking and pattern matching.
+
+Dependencies: pathlib
+
+Exports: PathResolver
+
+Interfaces: get_relative_path(file_path) -> Path, normalize_path_string(path) -> str
+
+Implementation: Uses pathlib for robust path operations, handles ValueError for out-of-tree paths
+"""
+
+from pathlib import Path
+
+
+class PathResolver:
+    """Resolves and normalizes file paths for file placement linter."""
+
+    def __init__(self, project_root: Path):
+        """Initialize path resolver.
+
+        Args:
+            project_root: Project root directory
+        """
+        self.project_root = project_root
+
+    def get_relative_path(self, file_path: Path) -> Path:
+        """Get path relative to project root.
+
+        Args:
+            file_path: File path to convert
+
+        Returns:
+            Path relative to project root, or original path if outside project
+        """
+        try:
+            if file_path.is_absolute():
+                return file_path.relative_to(self.project_root)
+            return file_path
+        except ValueError:
+            # If path is outside project root, return it as-is
+            # This allows detection of absolute paths in global_deny patterns
+            return file_path
+
+    def normalize_path_string(self, path: Path) -> str:
+        """Normalize path to forward slashes for cross-platform consistency.
+
+        Args:
+            path: Path to normalize
+
+        Returns:
+            Path string with forward slashes
+        """
+        return str(path).replace("\\", "/")

src/linters/file_placement/pattern_matcher.py

@@ -0,0 +1,55 @@
+"""
+Purpose: Pattern matching utilities for file placement linter
+
+Scope: Handles regex pattern matching for allow/deny file placement rules
+
+Overview: Provides pattern matching functionality for the file placement linter. Matches
+    file paths against regex patterns for both allow and deny lists. Supports case-insensitive
+    matching and extracts denial reasons from configuration. Isolates pattern matching logic
+    from rule checking and configuration validation.
+
+Dependencies: re
+
+Exports: PatternMatcher
+
+Interfaces: match_deny_patterns(path, patterns) -> (bool, reason), match_allow_patterns(path, patterns) -> bool
+
+Implementation: Uses re.search() for pattern matching with IGNORECASE flag
+"""
+
+import re
+
+
+class PatternMatcher:
+    """Handles regex pattern matching for file paths."""
+
+    def match_deny_patterns(
+        self, path_str: str, deny_patterns: list[dict[str, str]]
+    ) -> tuple[bool, str | None]:
+        """Check if path matches any deny patterns.
+
+        Args:
+            path_str: File path to check
+            deny_patterns: List of deny pattern dicts with 'pattern' and 'reason'
+
+        Returns:
+            Tuple of (is_denied, reason)
+        """
+        for deny_item in deny_patterns:
+            pattern = deny_item["pattern"]
+            if re.search(pattern, path_str, re.IGNORECASE):
+                reason = deny_item.get("reason", "File not allowed in this location")
+                return True, reason
+        return False, None
+
+    def match_allow_patterns(self, path_str: str, allow_patterns: list[str]) -> bool:
+        """Check if path matches any allow patterns.
+
+        Args:
+            path_str: File path to check
+            allow_patterns: List of regex patterns
+
+        Returns:
+            True if path matches any pattern
+        """
+        return any(re.search(pattern, path_str, re.IGNORECASE) for pattern in allow_patterns)

src/linters/file_placement/pattern_validator.py

@@ -0,0 +1,106 @@
+"""
+Purpose: Regex pattern validation for file placement linter configuration
+
+Scope: Validates regex patterns in configuration files to ensure they are compilable
+
+Overview: Provides validation functionality for regex patterns used in file placement rules.
+    Validates patterns in allow/deny lists, directory-specific rules, and global patterns.
+    Raises descriptive errors when patterns are invalid, helping users debug configuration
+    issues early. Isolates pattern validation logic from rule checking and config loading.
+
+Dependencies: re, typing
+
+Exports: PatternValidator
+
+Interfaces: validate_config(config) -> None (raises ValueError on invalid patterns)
+
+Implementation: Uses re.compile() to test pattern validity, provides detailed error messages
+"""
+
+import re
+from typing import Any
+
+
+class PatternValidator:
+    """Validates regex patterns in file placement configuration."""
+
+    def validate_config(self, config: dict[str, Any]) -> None:
+        """Validate all regex patterns in configuration.
+
+        Args:
+            config: Full configuration dict
+
+        Raises:
+            ValueError: If any regex pattern is invalid
+        """
+        fp_config = config.get("file-placement", {})
+        self._validate_directory_patterns(fp_config)
+        self._validate_global_patterns(fp_config)
+        self._validate_global_deny_patterns(fp_config)
+
+    def _validate_pattern(self, pattern: str) -> None:
+        """Validate a single regex pattern.
+
+        Args:
+            pattern: Regex pattern to validate
+
+        Raises:
+            ValueError: If pattern is invalid
+        """
+        try:
+            re.compile(pattern)
+        except re.error as e:
+            raise ValueError(f"Invalid regex pattern '{pattern}': {e}") from e
+
+    def _validate_allow_patterns(self, rules: dict[str, Any]) -> None:
+        """Validate allow patterns in a rules dict.
+
+        Args:
+            rules: Rules dictionary containing allow patterns
+        """
+        if "allow" in rules:
+            for pattern in rules["allow"]:
+                self._validate_pattern(pattern)
+
+    def _validate_deny_patterns(self, rules: dict[str, Any]) -> None:
+        """Validate deny patterns in a rules dict.
+
+        Args:
+            rules: Rules dictionary containing deny patterns
+        """
+        if "deny" in rules:
+            for deny_item in rules["deny"]:
+                pattern = deny_item.get("pattern", "")
+                self._validate_pattern(pattern)
+
+    def _validate_directory_patterns(self, fp_config: dict[str, Any]) -> None:
+        """Validate all directory-specific patterns.
+
+        Args:
+            fp_config: File placement configuration section
+        """
+        if "directories" in fp_config:
+            for _dir_path, rules in fp_config["directories"].items():
+                self._validate_allow_patterns(rules)
+                self._validate_deny_patterns(rules)
+
+    def _validate_global_patterns(self, fp_config: dict[str, Any]) -> None:
+        """Validate global patterns section.
+
+        Args:
+            fp_config: File placement configuration section
+        """
+        if "global_patterns" in fp_config:
+            self._validate_allow_patterns(fp_config["global_patterns"])
+            self._validate_deny_patterns(fp_config["global_patterns"])
+
+    def _validate_global_deny_patterns(self, fp_config: dict[str, Any]) -> None:
+        """Validate global_deny patterns.
+
+        Args:
+            fp_config: File placement configuration section
+        """
+        if "global_deny" in fp_config:
+            for deny_item in fp_config["global_deny"]:
+                pattern = deny_item.get("pattern", "")
+                self._validate_pattern(pattern)

src/linters/file_placement/rule_checker.py

@@ -0,0 +1,229 @@
+"""
+Purpose: Rule checking logic for file placement linter
+
+Scope: Executes file placement rules including directory-specific and global patterns
+
+Overview: Provides core rule checking functionality for the file placement linter. Checks
+    files against directory-specific allow/deny rules, global patterns, and global deny lists.
+    Uses pattern matcher for regex matching, directory matcher for finding rules, and violation
+    factory for creating violations. Implements deny-takes-precedence logic. Isolates rule
+    execution logic from configuration, validation, and violation creation.
+
+Dependencies: pathlib, typing, dataclasses, PatternMatcher, DirectoryMatcher, ViolationFactory, src.core.types
+
+Exports: RuleChecker
+
+Interfaces: check_all_rules(path_str, rel_path, fp_config) -> list[Violation]
+
+Implementation: Checks deny before allow, delegates directory matching to DirectoryMatcher,
+    uses RuleCheckContext dataclass to reduce parameter duplication
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from src.core.types import Violation
+
+from .directory_matcher import DirectoryMatcher
+from .pattern_matcher import PatternMatcher
+from .violation_factory import ViolationFactory
+
+
+@dataclass
+class RuleCheckContext:
+    """Context information for rule checking.
+
+    Attributes:
+        path_str: Normalized path string
+        rel_path: Relative path object
+        dir_rule: Directory rule configuration
+        matched_path: Matched directory path
+    """
+
+    path_str: str
+    rel_path: Path
+    dir_rule: dict[str, Any]
+    matched_path: str
+
+
+class RuleChecker:
+    """Checks file placement rules and returns violations."""
+
+    def __init__(self, pattern_matcher: PatternMatcher, violation_factory: ViolationFactory):
+        """Initialize rule checker.
+
+        Args:
+            pattern_matcher: Pattern matcher for regex matching
+            violation_factory: Factory for creating violations
+        """
+        self.pattern_matcher = pattern_matcher
+        self.violation_factory = violation_factory
+        self.directory_matcher = DirectoryMatcher()
+
+    def check_all_rules(
+        self, path_str: str, rel_path: Path, fp_config: dict[str, Any]
+    ) -> list[Violation]:
+        """Check all file placement rules.
+
+        Args:
+            path_str: Normalized path string
+            rel_path: Relative path object
+            fp_config: File placement configuration
+
+        Returns:
+            List of violations found
+        """
+        violations: list[Violation] = []
+
+        if "directories" in fp_config:
+            dir_violations = self._check_directory_rules(
+                path_str, rel_path, fp_config["directories"]
+            )
+            violations.extend(dir_violations)
+
+        if "global_deny" in fp_config:
+            deny_violations = self._check_global_deny(path_str, rel_path, fp_config["global_deny"])
+            violations.extend(deny_violations)
+
+        if "global_patterns" in fp_config:
+            global_violations = self._check_global_patterns(
+                path_str, rel_path, fp_config["global_patterns"]
+            )
+            violations.extend(global_violations)
+
+        return violations
+
+    def _check_directory_deny_rules(self, ctx: RuleCheckContext) -> Violation | None:
+        """Check directory deny rules.
+
+        Args:
+            ctx: Rule check context with file and rule information
+
+        Returns:
+            Violation if denied, None otherwise
+        """
+        if "deny" not in ctx.dir_rule:
+            return None
+
+        is_denied, reason = self.pattern_matcher.match_deny_patterns(
+            ctx.path_str, ctx.dir_rule["deny"]
+        )
+        if is_denied:
+            return self.violation_factory.create_deny_violation(
+                ctx.rel_path, ctx.matched_path, reason or "Pattern denied"
+            )
+        return None
+
+    def _check_directory_allow_rules(self, ctx: RuleCheckContext) -> Violation | None:
+        """Check directory allow rules.
+
+        Args:
+            ctx: Rule check context with file and rule information
+
+        Returns:
+            Violation if not allowed, None otherwise
+        """
+        if "allow" not in ctx.dir_rule:
+            return None
+
+        is_allowed = self.pattern_matcher.match_allow_patterns(ctx.path_str, ctx.dir_rule["allow"])
+        if not is_allowed:
+            return self.violation_factory.create_allow_violation(ctx.rel_path, ctx.matched_path)
+        return None
+
+    def _check_directory_rules(
+        self, path_str: str, rel_path: Path, directories: dict[str, Any]
+    ) -> list[Violation]:
+        """Check file against directory-specific rules.
+
+        Args:
+            path_str: Normalized path string
+            rel_path: Relative path object
+            directories: Directory rules config
+
+        Returns:
+            List of violations
+        """
+        dir_rule, matched_path = self.directory_matcher.find_matching_rule(path_str, directories)
+        if not dir_rule or not matched_path:
+            return []
+
+        ctx = RuleCheckContext(
+            path_str=path_str,
+            rel_path=rel_path,
+            dir_rule=dir_rule,
+            matched_path=matched_path,
+        )
+
+        # Check deny patterns first (takes precedence)
+        deny_violation = self._check_directory_deny_rules(ctx)
+        if deny_violation:
+            return self._wrap_violation(deny_violation)
+
+        # Check allow patterns
+        allow_violation = self._check_directory_allow_rules(ctx)
+        return self._wrap_violation(allow_violation)
+
+    def _wrap_violation(self, violation: Violation | None) -> list[Violation]:
+        """Wrap single violation in list, or return empty list if None.
+
+        Args:
+            violation: Violation to wrap, or None
+
+        Returns:
+            List containing violation, or empty list
+        """
+        return [violation] if violation else []
+
+    def _check_global_deny(
+        self, path_str: str, rel_path: Path, global_deny: list[dict[str, str]]
+    ) -> list[Violation]:
+        """Check file against global deny patterns.
+
+        Args:
+            path_str: Normalized path string
+            rel_path: Relative path object
+            global_deny: Global deny patterns
+
+        Returns:
+            List of violations
+        """
+        is_denied, reason = self.pattern_matcher.match_deny_patterns(path_str, global_deny)
+        if is_denied:
+            violation = self.violation_factory.create_global_deny_violation(rel_path, reason)
+            return self._wrap_violation(violation)
+        return []
+
+    def _check_global_patterns(
+        self, path_str: str, rel_path: Path, global_patterns: dict[str, Any]
+    ) -> list[Violation]:
+        """Check file against global patterns.
+
+        Args:
+            path_str: Normalized path string
+            rel_path: Relative path object
+            global_patterns: Global patterns config
+
+        Returns:
+            List of violations
+        """
+        # Check deny patterns first
+        if "deny" in global_patterns:
+            is_denied, reason = self.pattern_matcher.match_deny_patterns(
+                path_str, global_patterns["deny"]
+            )
+            if is_denied:
+                violation = self.violation_factory.create_global_deny_violation(rel_path, reason)
+                return self._wrap_violation(violation)
+
+        # Check allow patterns
+        if "allow" in global_patterns:
+            is_allowed = self.pattern_matcher.match_allow_patterns(
+                path_str, global_patterns["allow"]
+            )
+            if not is_allowed:
+                violation = self.violation_factory.create_global_allow_violation(rel_path)
+                return self._wrap_violation(violation)
+
+        return []

src/linters/file_placement/violation_factory.py

@@ -0,0 +1,177 @@
+"""
+Purpose: Violation creation with helpful suggestions for file placement linter
+
+Scope: Creates Violation objects with contextual messages and actionable suggestions
+
+Overview: Provides violation creation functionality for the file placement linter. Generates
+    descriptive error messages, creates helpful suggestions based on file type and location,
+    and encapsulates all violation construction logic. Separates violation building from
+    rule checking to maintain single responsibility and improve message consistency.
+
+Dependencies: pathlib, src.core.types (Violation, Severity), src.core.violation_builder
+
+Exports: ViolationFactory
+
+Interfaces: create_deny_violation, create_allow_violation, create_global_deny_violation
+
+Implementation: Uses file extension and name patterns to generate context-aware suggestions,
+    extends BaseViolationBuilder for consistent violation construction
+"""
+
+from pathlib import Path
+
+from src.core.types import Severity, Violation
+from src.core.violation_builder import BaseViolationBuilder
+
+
+class ViolationFactory(BaseViolationBuilder):
+    """Creates violations with helpful suggestions for file placement linter."""
+
+    # Suggestion lookup by file type
+    _SUGGESTIONS = {
+        "test": "Move to tests/ directory",
+        "component": "Move to src/components/",
+        "source": "Move to src/",
+        "temp": "Move to debug/logs/ or add to .gitignore",
+    }
+    _DEFAULT_SUGGESTION = "Review file organization and move to appropriate directory"
+
+    def create_deny_violation(self, rel_path: Path, matched_path: str, reason: str) -> Violation:
+        """Create violation for denied file.
+
+        Args:
+            rel_path: Relative path to file
+            matched_path: Directory path that matched
+            reason: Reason file is denied
+
+        Returns:
+            Violation with message and suggestion
+        """
+        message = f"File '{rel_path}' not allowed in {matched_path}: {reason}"
+        suggestion = self._get_suggestion(rel_path.name)
+        return self.build_from_params(
+            rule_id="file-placement",
+            file_path=str(rel_path),
+            line=1,
+            column=0,
+            message=message,
+            severity=Severity.ERROR,
+            suggestion=suggestion,
+        )
+
+    def create_allow_violation(self, rel_path: Path, matched_path: str) -> Violation:
+        """Create violation for file not matching allow patterns.
+
+        Args:
+            rel_path: Relative path to file
+            matched_path: Directory path that matched
+
+        Returns:
+            Violation with message and suggestion
+        """
+        message = f"File '{rel_path}' does not match allowed patterns for {matched_path}"
+        suggestion = f"Move to {matched_path} or ensure file type is allowed"
+        return self.build_from_params(
+            rule_id="file-placement",
+            file_path=str(rel_path),
+            line=1,
+            column=0,
+            message=message,
+            severity=Severity.ERROR,
+            suggestion=suggestion,
+        )
+
+    def create_global_deny_violation(self, rel_path: Path, reason: str | None) -> Violation:
+        """Create violation for global deny pattern match.
+
+        Args:
+            rel_path: Relative path to file
+            reason: Reason file is denied (optional)
+
+        Returns:
+            Violation with message and suggestion
+        """
+        message = reason or f"File '{rel_path}' matches denied pattern"
+        suggestion = self._get_suggestion(rel_path.name)
+        return self.build_from_params(
+            rule_id="file-placement",
+            file_path=str(rel_path),
+            line=1,
+            column=0,
+            message=message,
+            severity=Severity.ERROR,
+            suggestion=suggestion,
+        )
+
+    def create_global_allow_violation(self, rel_path: Path) -> Violation:
+        """Create violation for file not matching global allow patterns.
+
+        Args:
+            rel_path: Relative path to file
+
+        Returns:
+            Violation with message and suggestion
+        """
+        message = f"File '{rel_path}' does not match any allowed patterns"
+        suggestion = "Ensure file matches project structure patterns"
+        return self.build_from_params(
+            rule_id="file-placement",
+            file_path=str(rel_path),
+            line=1,
+            column=0,
+            message=message,
+            severity=Severity.ERROR,
+            suggestion=suggestion,
+        )
+
+    def _is_temp_file(self, filename: str) -> bool:
+        """Check if file is a temporary or utility file.
+
+        Args:
+            filename: File name
+
+        Returns:
+            True if file is temporary/utility file
+        """
+        return filename.startswith(("debug", "temp")) or filename.endswith(".log")
+
+    def _classify_file_type(self, filename: str) -> str | None:
+        """Classify file type based on filename patterns.
+
+        Args:
+            filename: File name
+
+        Returns:
+            File type classification key, or None if no pattern matches
+        """
+        filename_lower = filename.lower()
+
+        # Check keyword-based patterns
+        if "test" in filename_lower:
+            return "test"
+        if "component" in filename_lower:
+            return "component"
+
+        # Check extension-based patterns
+        if filename.endswith((".ts", ".tsx", ".jsx", ".py")):
+            return "source"
+
+        # Check temp/utility patterns
+        if self._is_temp_file(filename):
+            return "temp"
+
+        return None
+
+    def _get_suggestion(self, filename: str) -> str:
+        """Get suggestion for file placement based on filename patterns.
+
+        Args:
+            filename: File name
+
+        Returns:
+            Suggestion string with actionable guidance
+        """
+        file_type = self._classify_file_type(filename)
+        if file_type is None:
+            return self._DEFAULT_SUGGESTION
+        return self._SUGGESTIONS.get(file_type, self._DEFAULT_SUGGESTION)

src/linters/magic_numbers/__init__.py

@@ -0,0 +1,48 @@
+"""
+Purpose: Magic numbers linter package exports and convenience functions
+
+Scope: Public API for magic numbers linter module
+
+Overview: Provides the public interface for the magic numbers linter package. Exports main
+    MagicNumberRule class for use by the orchestrator and MagicNumberConfig for configuration.
+    Includes lint() convenience function that provides a simple API for running the magic numbers
+    linter on a file or directory without directly interacting with the orchestrator. This module
+    serves as the entry point for users of the magic numbers linter, hiding implementation details
+    and exposing only the essential components needed for linting operations.
+
+Dependencies: .linter for MagicNumberRule, .config for MagicNumberConfig
+
+Exports: MagicNumberRule class, MagicNumberConfig dataclass, lint() convenience function
+
+Interfaces: lint(path, config) -> list[Violation] for simple linting operations
+
+Implementation: Module-level exports with __all__ definition, convenience function wrapper
+"""
+
+from .config import MagicNumberConfig
+from .linter import MagicNumberRule
+
+__all__ = ["MagicNumberRule", "MagicNumberConfig", "lint"]
+
+
+def lint(file_path: str, config: dict | None = None) -> list:
+    """Convenience function for linting a file for magic numbers.
+
+    Args:
+        file_path: Path to the file to lint
+        config: Optional configuration dictionary
+
+    Returns:
+        List of violations found
+    """
+    from pathlib import Path
+
+    from src.orchestrator.core import FileLintContext
+
+    rule = MagicNumberRule()
+    context = FileLintContext(
+        path=Path(file_path),
+        lang="python",
+    )
+
+    return rule.check(context)