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

src/linters/lazy_ignores/types.py

@@ -0,0 +1,71 @@
+"""
+Purpose: Type definitions for lazy-ignores linter
+
+Scope: Data structures for ignore directives and suppression entries
+
+Overview: Defines core types for the lazy-ignores linter including IgnoreType enum for
+    categorizing different suppression patterns, IgnoreDirective dataclass for representing
+    detected ignores in code, and SuppressionEntry dataclass for representing declared
+    suppressions in file headers. Supports Python (noqa, type:ignore, pylint, nosec, pyright),
+    TypeScript (@ts-ignore, eslint-disable), thai-lint (thailint:ignore), and test skip
+    patterns (pytest.mark.skip, it.skip, describe.skip).
+
+Dependencies: dataclasses, enum, pathlib
+
+Exports: IgnoreType, IgnoreDirective, SuppressionEntry
+
+Interfaces: Frozen dataclasses for immutable ignore representation
+
+Implementation: Enum-based categorization with frozen dataclasses for thread safety
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+
+class IgnoreType(Enum):
+    """Type of linting ignore directive."""
+
+    NOQA = "noqa"
+    TYPE_IGNORE = "type:ignore"
+    PYLINT_DISABLE = "pylint:disable"
+    NOSEC = "nosec"
+    PYRIGHT_IGNORE = "pyright:ignore"
+    TS_IGNORE = "ts-ignore"
+    TS_NOCHECK = "ts-nocheck"
+    TS_EXPECT_ERROR = "ts-expect-error"
+    ESLINT_DISABLE = "eslint-disable"
+    THAILINT_IGNORE = "thailint:ignore"
+    THAILINT_IGNORE_FILE = "thailint:ignore-file"
+    THAILINT_IGNORE_NEXT = "thailint:ignore-next-line"
+    THAILINT_IGNORE_BLOCK = "thailint:ignore-start"
+    # DRY ignore patterns
+    DRY_IGNORE_BLOCK = "dry:ignore-block"
+    # Test skip patterns
+    PYTEST_SKIP = "pytest:skip"
+    PYTEST_SKIPIF = "pytest:skipif"
+    JEST_SKIP = "jest:skip"
+    MOCHA_SKIP = "mocha:skip"
+
+
+@dataclass(frozen=True)
+class IgnoreDirective:
+    """Represents a linting ignore found in code."""
+
+    ignore_type: IgnoreType
+    rule_ids: tuple[str, ...]  # Can have multiple: noqa: PLR0912, PLR0915
+    line: int
+    column: int
+    raw_text: str  # Original comment text
+    file_path: Path
+    inline_justification: str | None = None  # Justification after " - " delimiter
+
+
+@dataclass(frozen=True)
+class SuppressionEntry:
+    """Represents a suppression declared in file header."""
+
+    rule_id: str  # Normalized rule ID
+    justification: str
+    raw_text: str  # Original header line

src/linters/lazy_ignores/typescript_analyzer.py

@@ -0,0 +1,146 @@
+"""
+Purpose: Detect TypeScript/JavaScript linting ignore directives in source code
+
+Scope: @ts-ignore, @ts-nocheck, @ts-expect-error, eslint-disable pattern detection
+
+Overview: Provides TypeScriptIgnoreDetector class that scans TypeScript and JavaScript source
+    code for common linting ignore patterns. Detects TypeScript-specific patterns (@ts-ignore,
+    @ts-nocheck, @ts-expect-error) and ESLint patterns (eslint-disable-next-line, eslint-disable
+    block comments, eslint-disable-line). Handles both single-line (//) and block (/* */)
+    comment styles. Returns list of IgnoreDirective objects with line/column positions for
+    violation reporting.
+
+Dependencies: re for pattern matching, pathlib for file paths, types module for dataclasses
+
+Exports: TypeScriptIgnoreDetector
+
+Interfaces: find_ignores(code: str, file_path: Path | str | None) -> list[IgnoreDirective]
+
+Implementation: Regex-based line-by-line scanning with pattern-specific rule ID extraction
+"""
+
+import re
+from pathlib import Path
+
+from src.linters.lazy_ignores.directive_utils import create_directive, normalize_path
+from src.linters.lazy_ignores.types import IgnoreDirective, IgnoreType
+
+
+class TypeScriptIgnoreDetector:
+    """Detects TypeScript/JavaScript linting ignore directives in source code."""
+
+    # Regex patterns for each ignore type
+    # Single-line comment patterns (//)
+    SINGLE_LINE_PATTERNS: dict[IgnoreType, re.Pattern[str]] = {
+        IgnoreType.TS_IGNORE: re.compile(
+            r"//\s*@ts-ignore(?:\s|$)",
+        ),
+        IgnoreType.TS_NOCHECK: re.compile(
+            r"//\s*@ts-nocheck(?:\s|$)",
+        ),
+        IgnoreType.TS_EXPECT_ERROR: re.compile(
+            r"//\s*@ts-expect-error(?:\s|$)",
+        ),
+        IgnoreType.THAILINT_IGNORE: re.compile(
+            r"//\s*thailint:\s*ignore(?!-)(?:\[([^\]]+)\])?",
+            re.IGNORECASE,
+        ),
+        IgnoreType.THAILINT_IGNORE_FILE: re.compile(
+            r"//\s*thailint:\s*ignore-file(?:\[([^\]]+)\])?",
+            re.IGNORECASE,
+        ),
+    }
+
+    # ESLint patterns (can be single-line or inline)
+    ESLINT_PATTERNS: dict[str, re.Pattern[str]] = {
+        "next-line": re.compile(
+            r"//\s*eslint-disable-next-line(?:\s+([a-zA-Z0-9\-/,\s]+))?(?:\s|$)",
+        ),
+        "inline": re.compile(
+            r"//\s*eslint-disable-line(?:\s+([a-zA-Z0-9\-/,\s]+))?(?:\s|$)",
+        ),
+        "block-start": re.compile(
+            r"/\*\s*eslint-disable(?:\s+([a-zA-Z0-9\-/,\s]+))?\s*\*/",
+        ),
+    }
+
+    def find_ignores(self, code: str, file_path: Path | str | None = None) -> list[IgnoreDirective]:
+        """Find all TypeScript/JavaScript ignore directives in code.
+
+        Args:
+            code: TypeScript/JavaScript source code to scan
+            file_path: Optional path to the source file (Path or string)
+
+        Returns:
+            List of IgnoreDirective objects for each detected ignore pattern
+        """
+        directives: list[IgnoreDirective] = []
+        effective_path = normalize_path(file_path)
+
+        for line_num, line in enumerate(code.splitlines(), start=1):
+            directives.extend(self._scan_line(line, line_num, effective_path))
+
+        return directives
+
+    def _scan_line(self, line: str, line_num: int, file_path: Path) -> list[IgnoreDirective]:
+        """Scan a single line for ignore patterns.
+
+        Args:
+            line: Line of code to scan
+            line_num: 1-indexed line number
+            file_path: Path to the source file
+
+        Returns:
+            List of IgnoreDirective objects found on this line
+        """
+        found: list[IgnoreDirective] = []
+
+        # Check TypeScript-specific patterns
+        found.extend(self._scan_typescript_patterns(line, line_num, file_path))
+
+        # Check ESLint patterns
+        found.extend(self._scan_eslint_patterns(line, line_num, file_path))
+
+        return found
+
+    def _scan_typescript_patterns(
+        self, line: str, line_num: int, file_path: Path
+    ) -> list[IgnoreDirective]:
+        """Scan for TypeScript-specific ignore patterns.
+
+        Args:
+            line: Line of code to scan
+            line_num: 1-indexed line number
+            file_path: Path to the source file
+
+        Returns:
+            List of IgnoreDirective objects for TypeScript patterns
+        """
+        found: list[IgnoreDirective] = []
+        for ignore_type, pattern in self.SINGLE_LINE_PATTERNS.items():
+            match = pattern.search(line)
+            if match:
+                found.append(create_directive(match, ignore_type, line_num, file_path))
+        return found
+
+    def _scan_eslint_patterns(
+        self, line: str, line_num: int, file_path: Path
+    ) -> list[IgnoreDirective]:
+        """Scan for ESLint disable patterns.
+
+        Args:
+            line: Line of code to scan
+            line_num: 1-indexed line number
+            file_path: Path to the source file
+
+        Returns:
+            List of IgnoreDirective objects for ESLint patterns
+        """
+        found: list[IgnoreDirective] = []
+        for pattern in self.ESLINT_PATTERNS.values():
+            match = pattern.search(line)
+            if match:
+                found.append(
+                    create_directive(match, IgnoreType.ESLINT_DISABLE, line_num, file_path)
+                )
+        return found

src/linters/lazy_ignores/violation_builder.py

@@ -0,0 +1,135 @@
+"""
+Purpose: Build agent-friendly violation messages for lazy-ignores linter
+
+Scope: Violation construction for unjustified ignores and orphaned header suppressions
+
+Overview: Provides functions to construct Violation objects with AI-agent-friendly error
+    messages. Messages include explicit guidance for adding Suppressions section entries to
+    file headers and emphasize the requirement for human approval before adding suppressions.
+    Designed to help AI coding assistants understand the proper workflow for handling linting
+    suppressions rather than blindly adding ignore directives.
+
+Dependencies: src.core.types for Violation dataclass
+
+Exports: build_unjustified_violation, build_orphaned_violation
+
+Interfaces: Two builder functions returning Violation objects
+
+Implementation: Template-based message construction with rule ID formatting
+"""
+
+from src.core.types import Severity, Violation
+
+
+def build_unjustified_violation(
+    file_path: str,
+    line: int,
+    column: int,
+    rule_id: str,
+    raw_text: str,
+) -> Violation:
+    """Create violation for an ignore directive without header justification.
+
+    Args:
+        file_path: Path to the file containing the violation.
+        line: Line number where the ignore was found (1-indexed).
+        column: Column number where the ignore starts (0-indexed).
+        rule_id: The rule ID(s) being suppressed (e.g., "PLR0912").
+        raw_text: The raw ignore directive text found in code.
+
+    Returns:
+        Violation object with agent-friendly guidance message.
+    """
+    message = (
+        f"Unjustified suppression found: {raw_text} "
+        f"(ASK PERMISSION before adding Suppressions header)"
+    )
+
+    suggestion = _build_unjustified_suggestion(rule_id)
+
+    return Violation(
+        rule_id="lazy-ignores.unjustified",
+        file_path=file_path,
+        line=line,
+        column=column,
+        message=message,
+        severity=Severity.ERROR,
+        suggestion=suggestion,
+    )
+
+
+def _build_unjustified_suggestion(rule_id: str) -> str:
+    """Build the suggestion text for unjustified violations.
+
+    Args:
+        rule_id: The rule ID(s) being suppressed.
+
+    Returns:
+        Formatted suggestion string with header instructions.
+    """
+    # Handle multiple rules (e.g., "PLR0912, PLR0915")
+    rule_ids = [r.strip() for r in rule_id.split(",")]
+
+    suppression_entries = "\n".join(f"    {rid}: [Your justification here]" for rid in rule_ids)
+
+    return f"""To fix, either:
+
+1. Add an inline justification (10+ chars) after the ignore directive:
+   # noqa: {rule_ids[0]} - [Your justification here]
+
+2. Or add an entry to the file header Suppressions section:
+    Suppressions:
+{suppression_entries}
+
+IMPORTANT: Adding suppressions requires human approval.
+Do not add this entry without explicit permission from a human reviewer.
+Ask first, then add if approved."""
+
+
+def build_orphaned_violation(
+    file_path: str,
+    header_line: int,
+    rule_id: str,
+    justification: str,
+) -> Violation:
+    """Create violation for a header entry without matching code ignore.
+
+    Args:
+        file_path: Path to the file containing the orphaned entry.
+        header_line: Line number of the suppression in the header (1-indexed).
+        rule_id: The orphaned rule ID from the header.
+        justification: The justification text from the header.
+
+    Returns:
+        Violation object suggesting removal of the orphaned entry.
+    """
+    message = f"Orphaned suppression in header: {rule_id}: {justification}"
+
+    suggestion = _build_orphaned_suggestion(rule_id)
+
+    return Violation(
+        rule_id="lazy-ignores.orphaned",
+        file_path=file_path,
+        line=header_line,
+        column=0,
+        message=message,
+        severity=Severity.ERROR,
+        suggestion=suggestion,
+    )
+
+
+def _build_orphaned_suggestion(rule_id: str) -> str:
+    """Build the suggestion text for orphaned violations.
+
+    Args:
+        rule_id: The orphaned rule ID.
+
+    Returns:
+        Formatted suggestion string with removal instructions.
+    """
+    return f"""This rule is declared in the Suppressions section but no matching
+ignore directive was found in the code.
+
+Either:
+1. Remove the entry for {rule_id} from the Suppressions section if the ignore was removed from code
+2. Add the ignore directive if it's missing from the code"""

src/linters/lbyl/__init__.py

@@ -0,0 +1,31 @@
+"""
+Purpose: LBYL (Look Before You Leap) linter package exports
+
+Scope: Detect LBYL anti-patterns in Python code and suggest EAFP alternatives
+
+Overview: Package providing LBYL pattern detection for Python code. Identifies common
+    anti-patterns where explicit checks are performed before operations (e.g., if key in
+    dict before dict[key]) and suggests EAFP (Easier to Ask Forgiveness than Permission)
+    alternatives using try/except blocks. Supports 8 pattern types including dict key
+    checking, hasattr, isinstance, file exists, length checks, None checks, string
+    validation, and division safety checks.
+
+Dependencies: ast module for Python parsing, src.core for base classes
+
+Exports: LBYLConfig, LBYLPattern, BaseLBYLDetector, LBYLRule
+
+Interfaces: LBYLConfig.from_dict() for YAML configuration loading
+
+Implementation: AST-based pattern detection with configurable pattern toggles
+"""
+
+from .config import LBYLConfig
+from .linter import LBYLRule
+from .pattern_detectors.base import BaseLBYLDetector, LBYLPattern
+
+__all__ = [
+    "LBYLConfig",
+    "LBYLPattern",
+    "BaseLBYLDetector",
+    "LBYLRule",
+]

src/linters/lbyl/config.py

@@ -0,0 +1,63 @@
+"""
+Purpose: Configuration dataclass for LBYL linter
+
+Scope: Pattern toggles, ignore patterns, and validation
+
+Overview: Provides LBYLConfig dataclass with pattern-specific toggles for each LBYL
+    pattern type (dict_key, hasattr, isinstance, file_exists, len_check, none_check,
+    string_validation, division_check). Some patterns like isinstance and none_check
+    are disabled by default due to many valid use cases. Configuration can be loaded
+    from dictionary (YAML) with sensible defaults.
+
+Dependencies: dataclasses, typing
+
+Exports: LBYLConfig
+
+Interfaces: LBYLConfig.from_dict() for YAML configuration loading
+
+Implementation: Dataclass with factory defaults and conservative default settings
+
+Suppressions:
+    too-many-instance-attributes: Configuration dataclass requires many toggles
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class LBYLConfig:  # pylint: disable=too-many-instance-attributes
+    """Configuration for LBYL linter."""
+
+    enabled: bool = True
+
+    # Pattern toggles
+    detect_dict_key: bool = True
+    detect_hasattr: bool = True
+    detect_isinstance: bool = False  # Disabled - many valid uses for type narrowing
+    detect_file_exists: bool = True
+    detect_len_check: bool = True
+    detect_none_check: bool = False  # Disabled - many valid uses
+    detect_string_validation: bool = True
+    detect_division_check: bool = True
+
+    # File patterns to ignore
+    ignore: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, config: dict[str, Any], language: str | None = None) -> "LBYLConfig":
+        """Load configuration from dictionary."""
+        # Language parameter reserved for future multi-language support
+        _ = language
+        return cls(
+            enabled=config.get("enabled", True),
+            detect_dict_key=config.get("detect_dict_key", True),
+            detect_hasattr=config.get("detect_hasattr", True),
+            detect_isinstance=config.get("detect_isinstance", False),
+            detect_file_exists=config.get("detect_file_exists", True),
+            detect_len_check=config.get("detect_len_check", True),
+            detect_none_check=config.get("detect_none_check", False),
+            detect_string_validation=config.get("detect_string_validation", True),
+            detect_division_check=config.get("detect_division_check", True),
+            ignore=config.get("ignore", []),
+        )

src/linters/lbyl/linter.py

@@ -0,0 +1,67 @@
+"""
+Purpose: Main LBYL linter rule implementing PythonOnlyLintRule interface
+
+Scope: Entry point for LBYL anti-pattern detection in Python code
+
+Overview: Provides LBYLRule class that implements the PythonOnlyLintRule interface for
+    detecting Look Before You Leap anti-patterns in Python code. Validates that files
+    are Python with content, loads configuration, and delegates analysis to
+    PythonLBYLAnalyzer. Returns violations with EAFP suggestions for detected patterns.
+    Supports disabling via configuration and pattern-specific toggles.
+
+Dependencies: PythonOnlyLintRule, PythonLBYLAnalyzer, LBYLConfig
+
+Exports: LBYLRule
+
+Interfaces: check(context: BaseLintContext) -> list[Violation]
+
+Implementation: Single-file analysis with config-driven pattern detection
+"""
+
+from src.core.python_lint_rule import PythonOnlyLintRule
+from src.core.types import Violation
+
+from .config import LBYLConfig
+from .python_analyzer import PythonLBYLAnalyzer
+
+
+class LBYLRule(PythonOnlyLintRule[LBYLConfig]):
+    """Detects Look Before You Leap anti-patterns in Python code."""
+
+    def __init__(self, config: LBYLConfig | None = None) -> None:
+        """Initialize the LBYL rule."""
+        super().__init__(config)
+        self._analyzer = PythonLBYLAnalyzer()
+
+    @property
+    def rule_id(self) -> str:
+        """Unique identifier for this rule."""
+        return "lbyl"
+
+    @property
+    def rule_name(self) -> str:
+        """Human-readable name for this rule."""
+        return "Look Before You Leap"
+
+    @property
+    def description(self) -> str:
+        """Description of what this rule checks."""
+        return (
+            "Detects LBYL (Look Before You Leap) anti-patterns that should be "
+            "refactored to EAFP (Easier to Ask Forgiveness than Permission) style "
+            "using try/except blocks."
+        )
+
+    @property
+    def _config_key(self) -> str:
+        """Configuration key in metadata."""
+        return "lbyl"
+
+    @property
+    def _config_class(self) -> type[LBYLConfig]:
+        """Configuration class type."""
+        return LBYLConfig
+
+    def _analyze(self, code: str, file_path: str, config: LBYLConfig) -> list[Violation]:
+        """Analyze code for LBYL violations."""
+        return self._analyzer.analyze(code, file_path, config)

src/linters/lbyl/pattern_detectors/__init__.py

@@ -0,0 +1,53 @@
+"""
+Purpose: Pattern detector exports for LBYL linter
+
+Scope: All AST-based pattern detectors for LBYL anti-pattern detection
+
+Overview: Exports pattern detector classes for the LBYL linter. Each detector is an
+    AST NodeVisitor that identifies specific LBYL anti-patterns. Detectors include
+    dict key checking, hasattr, isinstance, file exists, length checks, None checks,
+    string validators, and division zero-checks.
+
+Dependencies: ast module, base detector class
+
+Exports: BaseLBYLDetector, LBYLPattern, DictKeyDetector, DictKeyPattern, HasattrDetector,
+    HasattrPattern, IsinstanceDetector, IsinstancePattern, FileExistsDetector,
+    FileExistsPattern, LenCheckDetector, LenCheckPattern, NoneCheckDetector,
+    NoneCheckPattern, StringValidatorDetector, StringValidatorPattern,
+    DivisionCheckDetector, DivisionCheckPattern
+
+Interfaces: find_patterns(tree: ast.AST) -> list[LBYLPattern]
+
+Implementation: Modular detector pattern for extensible LBYL detection
+"""
+
+from .base import BaseLBYLDetector, LBYLPattern
+from .dict_key_detector import DictKeyDetector, DictKeyPattern
+from .division_check_detector import DivisionCheckDetector, DivisionCheckPattern
+from .file_exists_detector import FileExistsDetector, FileExistsPattern
+from .hasattr_detector import HasattrDetector, HasattrPattern
+from .isinstance_detector import IsinstanceDetector, IsinstancePattern
+from .len_check_detector import LenCheckDetector, LenCheckPattern
+from .none_check_detector import NoneCheckDetector, NoneCheckPattern
+from .string_validator_detector import StringValidatorDetector, StringValidatorPattern
+
+__all__ = [
+    "BaseLBYLDetector",
+    "LBYLPattern",
+    "DictKeyDetector",
+    "DictKeyPattern",
+    "DivisionCheckDetector",
+    "DivisionCheckPattern",
+    "FileExistsDetector",
+    "FileExistsPattern",
+    "HasattrDetector",
+    "HasattrPattern",
+    "IsinstanceDetector",
+    "IsinstancePattern",
+    "LenCheckDetector",
+    "LenCheckPattern",
+    "NoneCheckDetector",
+    "NoneCheckPattern",
+    "StringValidatorDetector",
+    "StringValidatorPattern",
+]

src/linters/lbyl/pattern_detectors/base.py

@@ -0,0 +1,63 @@
+"""
+Purpose: Base class for LBYL pattern detectors
+
+Scope: Abstract base providing common detector interface
+
+Overview: Defines BaseLBYLDetector abstract class that all pattern detectors extend.
+    Inherits from ast.NodeVisitor for AST traversal. Defines LBYLPattern base dataclass
+    for representing detected patterns with line number and column information. Each
+    concrete detector implements find_patterns() to identify specific LBYL anti-patterns.
+    Uses Generic TypeVar for type-safe subclass pattern storage.
+
+Dependencies: abc, ast, dataclasses, typing
+
+Exports: BaseLBYLDetector, LBYLPattern
+
+Interfaces: find_patterns(tree: ast.AST) -> list[LBYLPattern]
+
+Implementation: Abstract base with NodeVisitor pattern for extensibility, Generic for type safety
+"""
+
+import ast
+from abc import ABC
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+
+@dataclass
+class LBYLPattern:
+    """Base pattern data for detected LBYL anti-patterns."""
+
+    line_number: int
+    column: int
+
+
+PatternT = TypeVar("PatternT", bound=LBYLPattern)
+
+
+class BaseLBYLDetector(ast.NodeVisitor, ABC, Generic[PatternT]):
+    """Base class for LBYL pattern detectors.
+
+    Subclasses must initialize self._patterns as an empty list in __init__
+    and populate it in visit methods. The _patterns attribute stores subclass-
+    specific pattern types (DictKeyPattern, HasattrPattern, etc.) which all
+    inherit from LBYLPattern.
+
+    Type Parameters:
+        PatternT: The specific pattern type used by this detector
+    """
+
+    _patterns: list[PatternT]
+
+    def find_patterns(self, tree: ast.AST) -> list[LBYLPattern]:
+        """Find LBYL patterns in AST.
+
+        Args:
+            tree: Python AST to analyze
+
+        Returns:
+            List of detected LBYL patterns
+        """
+        self._patterns = []
+        self.visit(tree)
+        return list(self._patterns)