thailint 0.1.0__py3-none-any.whl

src/core/types.py

@@ -0,0 +1,83 @@
+"""
+Purpose: Core type definitions for the linter framework
+
+Scope: Fundamental data types used across all linter components and rules
+
+Overview: Defines the essential data structures that form the foundation of the linter
+    framework, including violation reporting and severity classification. Provides the
+    Violation dataclass for representing linting issues with complete location and context
+    information, and the Severity enum implementing a binary error model (violations are
+    either errors or not violations). These types are used throughout the framework by
+    rules, orchestrators, and output formatters to maintain consistent violation reporting
+    and severity handling across all linting operations.
+
+Dependencies: dataclasses for Violation structure, enum for Severity classification
+
+Exports: Severity enum (ERROR level), Violation dataclass with serialization support
+
+Interfaces: Violation.to_dict() -> dict for JSON serialization, Severity.ERROR constant
+
+Implementation: Binary severity model (errors only), dataclass-based violation structure
+    with comprehensive field set (rule_id, file_path, line, column, message, severity, suggestion)
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Severity(Enum):
+    """Binary severity model - errors only.
+
+    Following the design principle that linting violations are either
+    errors that must be fixed or they're not violations at all.
+    No warnings, info, or other severity levels.
+    """
+
+    ERROR = "error"
+
+
+@dataclass
+class Violation:
+    """Represents a linting violation.
+
+    A violation contains all the information needed to report a linting
+    issue to the user, including location, message, and optional suggestion
+    for how to fix it.
+    """
+
+    rule_id: str
+    """Unique identifier of the rule that detected this violation."""
+
+    file_path: str
+    """Path to the file containing the violation."""
+
+    line: int
+    """Line number where the violation occurs (1-indexed)."""
+
+    column: int
+    """Column number where the violation occurs (0-indexed)."""
+
+    message: str
+    """Human-readable description of the violation."""
+
+    severity: Severity = Severity.ERROR
+    """Severity level of the violation (always ERROR in binary model)."""
+
+    suggestion: str | None = None
+    """Optional suggestion for how to fix the violation."""
+
+    def to_dict(self) -> dict[str, str | int | None]:
+        """Convert violation to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation of the violation with all fields.
+        """
+        return {
+            "rule_id": self.rule_id,
+            "file_path": self.file_path,
+            "line": self.line,
+            "column": self.column,
+            "message": self.message,
+            "severity": self.severity.value,
+            "suggestion": self.suggestion,
+        }

src/linter_config/__init__.py

@@ -0,0 +1,13 @@
+"""Linter configuration system.
+
+This package provides configuration loading and ignore directive parsing
+for the thai-lint linter framework.
+"""
+
+from .ignore import IgnoreDirectiveParser
+from .loader import LinterConfigLoader
+
+__all__ = [
+    "IgnoreDirectiveParser",
+    "LinterConfigLoader",
+]

src/linter_config/ignore.py

@@ -0,0 +1,403 @@
+"""
+Purpose: Comprehensive 5-level ignore directive parser for suppressing linting violations
+
+Scope: Multi-level ignore system across repository, directory, file, method, and line scopes
+
+Overview: Implements a sophisticated ignore directive system that allows developers to suppress
+    linting violations at five different granularity levels, from entire repository patterns down
+    to individual lines of code. Repository level uses .thailintignore file with gitignore-style
+    glob patterns for excluding files like build artifacts and dependencies. File level scans the
+    first 10 lines for ignore-file directives (performance optimization). Method level supports
+    ignore-next-line directives placed before functions. Line level enables inline ignore comments
+    at the end of code lines. All levels support rule-specific ignores using bracket syntax
+    [rule-id] and wildcard rule matching (literals.* matches literals.magic-number). The
+    should_ignore_violation() method provides unified checking across all levels, integrating
+    with the violation reporting system to filter out suppressed violations before displaying
+    results to users.
+
+Dependencies: fnmatch for gitignore-style pattern matching, re for regex-based directive parsing,
+    pathlib for file operations, Violation type for violation checking
+
+Exports: IgnoreDirectiveParser class
+
+Interfaces: is_ignored(file_path: Path) -> bool for repo-level checking,
+    has_file_ignore(file_path: Path, rule_id: str | None) -> bool for file-level,
+    has_line_ignore(code: str, line_num: int, rule_id: str | None) -> bool for line-level,
+    should_ignore_violation(violation: Violation, file_content: str) -> bool for unified checking
+
+Implementation: Gitignore-style pattern matching with fnmatch, first-10-lines scanning for
+    performance, regex-based directive parsing with rule ID extraction, wildcard rule matching
+    with prefix comparison, graceful error handling for malformed directives
+"""
+
+import fnmatch
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from src.core.types import Violation
+
+
+class IgnoreDirectiveParser:
+    """Parse and check ignore directives at all 5 levels.
+
+    Provides comprehensive ignore checking for repository-level patterns,
+    file-level directives, and inline code comments.
+    """
+
+    def __init__(self, project_root: Path | None = None):
+        """Initialize parser.
+
+        Args:
+            project_root: Root directory of the project. Defaults to current directory.
+        """
+        self.project_root = project_root or Path.cwd()
+        self.repo_patterns = self._load_repo_ignores()
+
+    def _load_repo_ignores(self) -> list[str]:
+        """Load .thailintignore file patterns.
+
+        Returns:
+            List of gitignore-style patterns.
+        """
+        ignore_file = self.project_root / ".thailintignore"
+        if not ignore_file.exists():
+            return []
+
+        patterns = []
+        for line in ignore_file.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            # Skip comments and blank lines
+            if line and not line.startswith("#"):
+                patterns.append(line)
+        return patterns
+
+    def is_ignored(self, file_path: Path) -> bool:
+        """Check if file matches repository-level ignore patterns.
+
+        Args:
+            file_path: Path to check against ignore patterns.
+
+        Returns:
+            True if file should be ignored.
+        """
+        # Convert to string relative to project root if possible
+        try:
+            relative_path = file_path.relative_to(self.project_root)
+            path_str = str(relative_path)
+        except ValueError:
+            # Path is not relative to project root
+            path_str = str(file_path)
+
+        for pattern in self.repo_patterns:
+            if self._matches_pattern(path_str, pattern):
+                return True
+        return False
+
+    def _matches_pattern(self, path: str, pattern: str) -> bool:
+        """Check if path matches gitignore-style pattern.
+
+        Args:
+            path: File path to check.
+            pattern: Gitignore-style pattern.
+
+        Returns:
+            True if path matches pattern.
+        """
+        # Handle directory patterns (trailing /)
+        if pattern.endswith("/"):
+            # Match directory and all its contents
+            dir_pattern = pattern.rstrip("/")
+            # Check if path starts with the directory
+            path_parts = Path(path).parts
+            if dir_pattern in path_parts:
+                return True
+            # Also check direct match
+            if fnmatch.fnmatch(path, dir_pattern + "*"):
+                return True
+
+        # Standard fnmatch for file patterns
+        return fnmatch.fnmatch(path, pattern) or fnmatch.fnmatch(str(Path(path)), pattern)
+
+    def _has_ignore_directive_marker(self, line: str) -> bool:
+        """Check if line contains an ignore directive marker."""
+        return "# thailint: ignore-file" in line or "# design-lint: ignore-file" in line
+
+    def _check_specific_rule_ignore(self, line: str, rule_id: str) -> bool:
+        """Check if line ignores a specific rule."""
+        match = re.search(r"ignore-file\[([^\]]+)\]", line)
+        if match:
+            ignored_rules = [r.strip() for r in match.group(1).split(",")]
+            return any(self._rule_matches(rule_id, r) for r in ignored_rules)
+        return False
+
+    def _check_general_ignore(self, line: str) -> bool:
+        """Check if line has general ignore directive (no specific rules)."""
+        return "ignore-file[" not in line
+
+    def _read_file_first_lines(self, file_path: Path) -> list[str]:
+        """Read first 10 lines of file, return empty list on error."""
+        if not file_path.exists():
+            return []
+        try:
+            content = file_path.read_text(encoding="utf-8")
+            return content.splitlines()[:10]
+        except (UnicodeDecodeError, OSError):
+            return []
+
+    def _check_line_for_ignore(self, line: str, rule_id: str | None) -> bool:
+        """Check if line has matching ignore directive."""
+        if not self._has_ignore_directive_marker(line):
+            return False
+        if rule_id:
+            return self._check_specific_rule_ignore(line, rule_id)
+        return self._check_general_ignore(line)
+
+    def has_file_ignore(self, file_path: Path, rule_id: str | None = None) -> bool:
+        """Check for file-level ignore directive.
+
+        Scans the first 10 lines of the file for ignore directives.
+
+        Args:
+            file_path: Path to file to check.
+            rule_id: Optional specific rule ID to check for.
+
+        Returns:
+            True if file has ignore directive (general or for specific rule).
+        """
+        first_lines = self._read_file_first_lines(file_path)
+        return any(self._check_line_for_ignore(line, rule_id) for line in first_lines)
+
+    def _has_line_ignore_marker(self, code: str) -> bool:
+        """Check if code line has ignore marker."""
+        return (
+            "# thailint: ignore" in code
+            or "# design-lint: ignore" in code
+            or "// thailint: ignore" in code
+            or "// design-lint: ignore" in code
+        )
+
+    def _check_specific_rule_in_line(self, code: str, rule_id: str) -> bool:
+        """Check if line's ignore directive matches specific rule."""
+        # Check for bracket syntax: # thailint: ignore[rule1, rule2]
+        bracket_match = re.search(r"ignore\[([^\]]+)\]", code)
+        if bracket_match:
+            return self._check_bracket_rules(bracket_match.group(1), rule_id)
+
+        # Check for space-separated syntax: # thailint: ignore rule1 rule2
+        space_match = re.search(r"ignore\s+([^\s#]+(?:\s+[^\s#]+)*)", code)
+        if space_match:
+            return self._check_space_separated_rules(space_match.group(1), rule_id)
+
+        # No specific rules - check for "ignore-all"
+        return "ignore-all" in code
+
+    def _check_bracket_rules(self, rules_text: str, rule_id: str) -> bool:
+        """Check if bracketed rules match the rule ID."""
+        ignored_rules = [r.strip() for r in rules_text.split(",")]
+        return any(self._rule_matches(rule_id, r) for r in ignored_rules)
+
+    def _check_space_separated_rules(self, rules_text: str, rule_id: str) -> bool:
+        """Check if space-separated rules match the rule ID."""
+        ignored_rules = [r.strip() for r in re.split(r"[,\s]+", rules_text) if r.strip()]
+        return any(self._rule_matches(rule_id, r) for r in ignored_rules)
+
+    def has_line_ignore(self, code: str, line_num: int, rule_id: str | None = None) -> bool:
+        """Check for line-level ignore directive.
+
+        Args:
+            code: Line of code to check.
+            line_num: Line number (currently unused, for API compatibility).
+            rule_id: Optional specific rule ID to check for.
+
+        Returns:
+            True if line has ignore directive.
+        """
+        if not self._has_line_ignore_marker(code):
+            return False
+
+        if rule_id:
+            return self._check_specific_rule_in_line(code, rule_id)
+        return True
+
+    def _rule_matches(self, rule_id: str, pattern: str) -> bool:
+        """Check if rule ID matches pattern (supports wildcards and prefixes).
+
+        Args:
+            rule_id: Rule ID to check (e.g., "nesting.excessive-depth").
+            pattern: Pattern with optional wildcard (e.g., "nesting.*" or "nesting").
+
+        Returns:
+            True if rule matches pattern.
+        """
+        if pattern.endswith("*"):
+            # Wildcard match: literals.* matches literals.magic-number
+            prefix = pattern[:-1]
+            return rule_id.startswith(prefix)
+
+        # Exact match
+        if rule_id == pattern:
+            return True
+
+        # Prefix match: "nesting" matches "nesting.excessive-depth"
+        if rule_id.startswith(pattern + "."):
+            return True
+
+        return False
+
+    def _has_ignore_next_line_marker(self, prev_line: str) -> bool:
+        """Check if line has ignore-next-line marker."""
+        return (
+            "# thailint: ignore-next-line" in prev_line
+            or "# design-lint: ignore-next-line" in prev_line
+        )
+
+    def _matches_ignore_next_line_rules(self, prev_line: str, rule_id: str) -> bool:
+        """Check if ignore-next-line directive matches the rule."""
+        match = re.search(r"ignore-next-line\[([^\]]+)\]", prev_line)
+        if match:
+            ignored_rules = [r.strip() for r in match.group(1).split(",")]
+            return any(self._rule_matches(rule_id, r) for r in ignored_rules)
+        return True
+
+    def _is_valid_prev_line_index(self, lines: list[str], violation: "Violation") -> bool:
+        """Check if previous line index is valid."""
+        if violation.line <= 1 or violation.line > len(lines) + 1:
+            return False
+        prev_line_idx = violation.line - 2
+        return 0 <= prev_line_idx < len(lines)
+
+    def _check_prev_line_ignore(self, lines: list[str], violation: "Violation") -> bool:
+        """Check if previous line has ignore-next-line directive."""
+        if not self._is_valid_prev_line_index(lines, violation):
+            return False
+
+        prev_line_idx = violation.line - 2
+        prev_line = lines[prev_line_idx]
+        if not self._has_ignore_next_line_marker(prev_line):
+            return False
+
+        return self._matches_ignore_next_line_rules(prev_line, violation.rule_id)
+
+    def _check_current_line_ignore(self, lines: list[str], violation: "Violation") -> bool:
+        """Check if current line has inline ignore directive."""
+        if violation.line <= 0 or violation.line > len(lines):
+            return False
+
+        current_line = lines[violation.line - 1]  # Convert to 0-indexed
+        return self.has_line_ignore(current_line, violation.line, violation.rule_id)
+
+    def should_ignore_violation(self, violation: "Violation", file_content: str) -> bool:
+        """Check if a violation should be ignored based on all levels."""
+        file_path = Path(violation.file_path)
+
+        # Repository and file level checks
+        if self._is_ignored_at_file_level(file_path, violation.rule_id):
+            return True
+
+        # Line-based checks
+        return self._is_ignored_in_content(file_content, violation)
+
+    def _is_ignored_at_file_level(self, file_path: Path, rule_id: str) -> bool:
+        """Check repository and file level ignores."""
+        if self.is_ignored(file_path):
+            return True
+        return self.has_file_ignore(file_path, rule_id)
+
+    def _is_ignored_in_content(self, file_content: str, violation: "Violation") -> bool:
+        """Check content-based ignores (block, line, method level)."""
+        lines = file_content.splitlines()
+
+        if self._check_block_ignore(lines, violation):
+            return True
+        if self._check_prev_line_ignore(lines, violation):
+            return True
+        if self._check_current_line_ignore(lines, violation):
+            return True
+
+        return False
+
+    def _check_block_ignore(self, lines: list[str], violation: "Violation") -> bool:
+        """Check if violation is within an ignore-start/ignore-end block."""
+        if violation.line <= 0 or violation.line > len(lines):
+            return False
+
+        block_state = {"in_block": False, "rules": set()}
+
+        for i, line in enumerate(lines):
+            if self._process_block_line(line, i + 1, violation, block_state):
+                return True
+
+        return False
+
+    def _process_block_line(
+        self, line: str, line_num: int, violation: "Violation", block_state: dict
+    ) -> bool:
+        """Process a single line for block ignore checking."""
+        if "ignore-start" in line:
+            block_state["rules"] = self._parse_ignore_start_rules(line)
+            block_state["in_block"] = True
+            return False
+
+        if self._is_block_end_matching(
+            line, block_state["in_block"], line_num, violation, block_state["rules"]
+        ):
+            return True
+
+        if self._is_violation_line_ignored(
+            line_num, violation, block_state["in_block"], block_state["rules"]
+        ):
+            return True
+
+        if "ignore-end" in line:
+            block_state["in_block"] = False
+            block_state["rules"] = set()
+
+        return False
+
+    def _is_block_end_matching(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+        self,
+        line: str,
+        in_ignore_block: bool,
+        line_num: int,
+        violation: "Violation",
+        current_ignored_rules: set[str],
+    ) -> bool:
+        """Check if ignore-end matches and violation was in the block."""
+        if "ignore-end" not in line:
+            return False
+        if not in_ignore_block or line_num <= violation.line:
+            return False
+        return self._rules_match_violation(current_ignored_rules, violation.rule_id)
+
+    def _is_violation_line_ignored(
+        self,
+        line_num: int,
+        violation: "Violation",
+        in_ignore_block: bool,
+        current_ignored_rules: set[str],
+    ) -> bool:
+        """Check if current line is the violation line in an ignore block."""
+        if line_num != violation.line or not in_ignore_block:
+            return False
+        return self._rules_match_violation(current_ignored_rules, violation.rule_id)
+
+    def _parse_ignore_start_rules(self, line: str) -> set[str]:
+        """Extract rule names from ignore-start directive."""
+        match = re.search(r"ignore-start\s+([^\s#]+(?:\s+[^\s#]+)*)", line)
+        if match:
+            rules_text = match.group(1).strip()
+            rules = [r.strip() for r in re.split(r"[,\s]+", rules_text) if r.strip()]
+            return set(rules)
+        return {"*"}
+
+    def _rules_match_violation(self, ignored_rules: set[str], rule_id: str) -> bool:
+        """Check if any of the ignored rules match the violation rule ID."""
+        if "*" in ignored_rules:
+            return True
+        return any(self._rule_matches(rule_id, pattern) for pattern in ignored_rules)
+
+
+# Alias for backwards compatibility
+IgnoreParser = IgnoreDirectiveParser

src/linter_config/loader.py

@@ -0,0 +1,77 @@
+"""
+Purpose: Multi-format configuration loader for linter settings and rule configuration
+
+Scope: Linter configuration management supporting YAML and JSON formats
+
+Overview: Loads linter configuration from .thailint.yaml or .thailint.json files with graceful
+    fallback to sensible defaults when config files don't exist or cannot be read. Supports both
+    YAML and JSON formats to accommodate different user preferences and tooling requirements,
+    using format detection based on file extension. Provides unified configuration structure for
+    rule settings, ignore patterns, and linter behavior across all deployment modes (CLI, library,
+    Docker). Returns empty defaults (empty rules dict, empty ignore list) when config files are
+    missing, allowing the linter to function without configuration. Validates file formats and
+    raises clear errors with specific exception types for malformed YAML or JSON, helping users
+    quickly identify and fix configuration syntax issues.
+
+Dependencies: PyYAML for YAML parsing with safe_load(), json (stdlib) for JSON parsing,
+    pathlib for file path handling
+
+Exports: LinterConfigLoader class
+
+Interfaces: load(config_path: Path) -> dict[str, Any] for loading config files,
+    get_defaults() -> dict[str, Any] for default configuration structure
+
+Implementation: Extension-based format detection (.yaml/.yml vs .json), yaml.safe_load()
+    for security, empty dict handling for null YAML, ValueError for unsupported formats
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class LinterConfigLoader:
+    """Load linter configuration from YAML or JSON files.
+
+    Supports loading from .thailint.yaml, .thailint.json, or custom paths.
+    Provides sensible defaults when config files don't exist.
+    """
+
+    def load(self, config_path: Path) -> dict[str, Any]:
+        """Load configuration from file.
+
+        Args:
+            config_path: Path to YAML or JSON config file.
+
+        Returns:
+            Configuration dictionary.
+
+        Raises:
+            ValueError: If file format is unsupported.
+            yaml.YAMLError: If YAML is malformed.
+            json.JSONDecodeError: If JSON is malformed.
+        """
+        if not config_path.exists():
+            return self.get_defaults()
+
+        suffix = config_path.suffix.lower()
+
+        with config_path.open(encoding="utf-8") as f:
+            if suffix in [".yaml", ".yml"]:
+                return yaml.safe_load(f) or {}
+            if suffix == ".json":
+                return json.load(f)
+            raise ValueError(f"Unsupported config format: {suffix}")
+
+    def get_defaults(self) -> dict[str, Any]:
+        """Get default configuration.
+
+        Returns:
+            Default configuration with empty rules and ignore lists.
+        """
+        return {
+            "rules": {},
+            "ignore": [],
+        }

src/linters/__init__.py

@@ -0,0 +1,4 @@
+"""
+Purpose: Linters package initialization
+Scope: Export linter modules
+"""

src/linters/file_placement/__init__.py

@@ -0,0 +1,31 @@
+"""
+Purpose: File placement linter module
+Scope: File organization and placement validation
+"""
+
+from pathlib import Path
+from typing import Any
+
+from .linter import FilePlacementLinter, FilePlacementRule
+
+__all__ = ["FilePlacementLinter", "FilePlacementRule", "lint"]
+
+
+def lint(path: Path | str, config: dict[str, Any] | None = None) -> list:
+    """Lint a file or directory using file placement rules.
+
+    Args:
+        path: Path to file or directory to lint
+        config: Configuration dict (compatible with FilePlacementLinter)
+
+    Returns:
+        List of violations
+    """
+    path_obj = Path(path) if isinstance(path, str) else path
+    linter = FilePlacementLinter(config_obj=config or {})
+
+    if path_obj.is_file():
+        return linter.lint_path(path_obj)
+    if path_obj.is_dir():
+        return linter.lint_directory(path_obj)
+    return []