thailint 0.12.0__py3-none-any.whl → 0.14.0__py3-none-any.whl

src/linters/lazy_ignores/header_parser.py

@@ -0,0 +1,177 @@
+"""
+Purpose: Parse Suppressions section from file headers
+
+Scope: Python docstrings and TypeScript JSDoc comment header parsing
+
+Overview: Provides SuppressionsParser class for extracting the Suppressions section from
+    file headers. Parses Python triple-quoted docstrings and TypeScript JSDoc comments.
+    Extracts rule IDs and justifications, normalizing rule IDs for case-insensitive matching.
+    Returns dictionary mapping normalized rule IDs to their justifications.
+
+Dependencies: re for pattern matching, Language enum for type safety
+
+Exports: SuppressionsParser
+
+Interfaces: parse(header: str) -> dict[str, str], extract_header(code: str, language: Language)
+
+Implementation: Regex-based section extraction with line-by-line entry parsing
+"""
+
+import re
+
+from src.core.constants import Language
+
+
+class SuppressionsParser:
+    """Parses Suppressions section from file headers."""
+
+    # Pattern to find Suppressions section (case-insensitive)
+    # Matches "Suppressions:" followed by indented lines
+    SUPPRESSIONS_SECTION = re.compile(
+        r"Suppressions:\s*\n((?:[ \t]+\S.*\n?)+)",
+        re.MULTILINE | re.IGNORECASE,
+    )
+
+    # Pattern for JSDoc-style suppressions (* prefixed lines)
+    JSDOC_SUPPRESSIONS_SECTION = re.compile(
+        r"Suppressions:\s*\n((?:\s*\*\s+\S.*\n?)+)",
+        re.MULTILINE | re.IGNORECASE,
+    )
+
+    # Pattern to parse individual entries (rule_id: justification)
+    # Rule IDs can contain colons (e.g., type:ignore[arg-type])
+    # Handles list prefixes: "- ", "* ", "• " and plain indented entries
+    # Justification must start with word char or underscore to avoid matching continuation lines
+    ENTRY_PATTERN = re.compile(
+        r"^\s*[-*•]?\s*(.+):\s+([A-Za-z_].*)$",
+        re.MULTILINE,
+    )
+
+    def parse(self, header: str) -> dict[str, str]:
+        """Parse Suppressions section, return rule_id -> justification mapping.
+
+        Args:
+            header: File header content (docstring or JSDoc)
+
+        Returns:
+            Dictionary mapping normalized rule IDs to justification strings
+        """
+        # Try standard Python-style first, then JSDoc-style
+        section_match = self.SUPPRESSIONS_SECTION.search(header)
+        if not section_match:
+            section_match = self.JSDOC_SUPPRESSIONS_SECTION.search(header)
+
+        if not section_match:
+            return {}
+
+        entries: dict[str, str] = {}
+        section_content = section_match.group(1)
+
+        for match in self.ENTRY_PATTERN.finditer(section_content):
+            rule_id = match.group(1).strip()
+            justification = match.group(2).strip()
+
+            # Skip entries with empty justification
+            if justification:
+                normalized_id = self.normalize_rule_id(rule_id)
+                entries[normalized_id] = justification
+
+        return entries
+
+    def normalize_rule_id(self, rule_id: str) -> str:
+        """Normalize rule ID for case-insensitive matching.
+
+        Strips common list prefixes (-, *, •) and normalizes to lowercase.
+
+        Args:
+            rule_id: Original rule ID string
+
+        Returns:
+            Normalized rule ID (lowercase, no list prefix)
+        """
+        normalized = rule_id.lower().strip()
+        # Strip common list prefixes (bullet points)
+        if normalized.startswith(("- ", "* ", "• ")):
+            normalized = normalized[2:]
+        elif normalized.startswith(("-", "*", "•")):
+            normalized = normalized[1:].lstrip()
+        return normalized
+
+    def extract_header(self, code: str, language: str | Language = Language.PYTHON) -> str:
+        """Extract the header section from code.
+
+        Args:
+            code: Full source code
+            language: Programming language (Language enum or string)
+
+        Returns:
+            Header content as string, or empty string if not found
+        """
+        lang = Language(language) if isinstance(language, str) else language
+        if lang == Language.PYTHON:
+            return self._extract_python_header(code)
+        if lang in (Language.TYPESCRIPT, Language.JAVASCRIPT):
+            return self._extract_ts_header(code)
+        return ""
+
+    def _extract_python_header(self, code: str) -> str:
+        """Extract Python docstring header.
+
+        Args:
+            code: Python source code
+
+        Returns:
+            Docstring content or empty string
+        """
+        # Match triple-quoted docstring at start of file
+        # Skip leading whitespace, comments, and encoding declarations
+        stripped = self._skip_leading_comments(code)
+
+        # Try double quotes first
+        match = re.match(r'^"""(.*?)"""', stripped, re.DOTALL)
+        if match:
+            return match.group(0)
+
+        # Try single quotes
+        match = re.match(r"^'''(.*?)'''", stripped, re.DOTALL)
+        if match:
+            return match.group(0)
+
+        return ""
+
+    def _skip_leading_comments(self, code: str) -> str:
+        """Skip leading comments and empty lines to find docstring.
+
+        Args:
+            code: Python source code
+
+        Returns:
+            Code with leading comments/empty lines removed
+        """
+        lines = code.split("\n")
+        for i, line in enumerate(lines):
+            stripped = line.strip()
+            # Skip empty lines
+            if not stripped:
+                continue
+            # Skip comment lines (including pylint/noqa/type comments)
+            if stripped.startswith("#"):
+                continue
+            # Found non-comment, non-empty line - return from here
+            return "\n".join(lines[i:])
+        return ""
+
+    def _extract_ts_header(self, code: str) -> str:
+        """Extract TypeScript/JavaScript JSDoc header.
+
+        Args:
+            code: TypeScript/JavaScript source code
+
+        Returns:
+            JSDoc comment content or empty string
+        """
+        stripped = code.lstrip()
+        match = re.match(r"^/\*\*(.*?)\*/", stripped, re.DOTALL)
+        if match:
+            return match.group(0)
+        return ""

src/linters/lazy_ignores/linter.py

@@ -0,0 +1,158 @@
+"""
+Purpose: Main LazyIgnoresRule class for detecting unjustified linting suppressions
+
+Scope: Orchestration of ignore detection and header suppression validation
+
+Overview: Provides LazyIgnoresRule that cross-references linting ignore directives found
+    in code (noqa, type:ignore, pylint:disable, nosec) and test skip patterns with
+    Suppressions entries declared in file headers. Detects two types of violations:
+    unjustified ignores/skips (directive without header declaration) and orphaned
+    suppressions (header declaration without matching ignore in code). Enforces the
+    header-based suppression model requiring human approval for all linting bypasses.
+
+Dependencies: PythonIgnoreDetector, TestSkipDetector, SuppressionsParser, IgnoreSuppressionMatcher
+
+Exports: LazyIgnoresRule
+
+Interfaces: check(context: BaseLintContext) -> list[Violation]
+
+Implementation: Delegation to matcher for cross-reference logic, violation builder for messages
+"""
+
+from pathlib import Path
+
+from src.core.base import BaseLintContext, BaseLintRule
+from src.core.constants import Language
+from src.core.types import Violation
+
+from .header_parser import SuppressionsParser
+from .matcher import IgnoreSuppressionMatcher
+from .python_analyzer import PythonIgnoreDetector
+from .skip_detector import TestSkipDetector
+from .types import IgnoreDirective
+from .violation_builder import build_orphaned_violation, build_unjustified_violation
+
+
+class LazyIgnoresRule(BaseLintRule):
+    """Detects unjustified linting suppressions and orphaned header entries."""
+
+    def __init__(self, check_test_skips: bool = True) -> None:
+        """Initialize the lazy ignores rule with detection components.
+
+        Args:
+            check_test_skips: Whether to check for unjustified test skips.
+        """
+        self._python_detector = PythonIgnoreDetector()
+        self._test_skip_detector = TestSkipDetector()
+        self._suppression_parser = SuppressionsParser()
+        self._matcher = IgnoreSuppressionMatcher(self._suppression_parser)
+        self._check_test_skips = check_test_skips
+
+    @property
+    def rule_id(self) -> str:
+        """Unique identifier for this rule."""
+        return "lazy-ignores"
+
+    @property
+    def rule_name(self) -> str:
+        """Human-readable name for this rule."""
+        return "Lazy Ignores"
+
+    @property
+    def description(self) -> str:
+        """Description of what this rule checks."""
+        return (
+            "Detects linting suppressions (noqa, type:ignore, pylint:disable, nosec) "
+            "and test skips without corresponding entries in the file header's "
+            "Suppressions section."
+        )
+
+    def check(self, context: BaseLintContext) -> list[Violation]:
+        """Check for violations in the given context.
+
+        Args:
+            context: The lint context containing file information.
+
+        Returns:
+            List of violations for unjustified and orphaned suppressions.
+        """
+        if context.language != Language.PYTHON:
+            return []
+
+        if not context.file_content:
+            return []
+
+        file_path = str(context.file_path) if context.file_path else "unknown"
+        return self.check_content(context.file_content, file_path)
+
+    def check_content(self, code: str, file_path: str) -> list[Violation]:
+        """Check code for unjustified ignores and orphaned suppressions.
+
+        Args:
+            code: Source code content to analyze.
+            file_path: Path to the file being analyzed.
+
+        Returns:
+            List of violations for unjustified and orphaned suppressions.
+        """
+        # Extract and parse header suppressions
+        header = self._suppression_parser.extract_header(code, "python")
+        suppressions = self._suppression_parser.parse(header)
+
+        # Find all ignore directives in code
+        ignores = self._python_detector.find_ignores(code, Path(file_path))
+
+        # Find test skip directives if enabled
+        if self._check_test_skips:
+            test_skips = self._test_skip_detector.find_skips(code, Path(file_path), "python")
+            ignores = list(ignores) + list(test_skips)
+
+        # Build set of normalized rule IDs used in code
+        used_rule_ids = self._matcher.collect_used_rule_ids(ignores)
+
+        # Find violations
+        violations: list[Violation] = []
+        violations.extend(self._find_unjustified(ignores, suppressions, file_path))
+        violations.extend(self._find_orphaned(suppressions, used_rule_ids, file_path))
+
+        return violations
+
+    def _find_unjustified(
+        self, ignores: list[IgnoreDirective], suppressions: dict[str, str], file_path: str
+    ) -> list[Violation]:
+        """Find ignore directives without matching header suppressions."""
+        violations: list[Violation] = []
+
+        for ignore in ignores:
+            unjustified = self._matcher.find_unjustified_rule_ids(ignore, suppressions)
+            if unjustified:
+                violations.append(
+                    build_unjustified_violation(
+                        file_path=file_path,
+                        line=ignore.line,
+                        column=ignore.column,
+                        rule_id=", ".join(unjustified),
+                        raw_text=ignore.raw_text,
+                    )
+                )
+
+        return violations
+
+    def _find_orphaned(
+        self, suppressions: dict[str, str], used_rule_ids: set[str], file_path: str
+    ) -> list[Violation]:
+        """Find header suppressions without matching code ignores."""
+        violations: list[Violation] = []
+        orphaned = self._matcher.find_orphaned_rule_ids(suppressions, used_rule_ids)
+
+        for rule_id, justification in orphaned:
+            violations.append(
+                build_orphaned_violation(
+                    file_path=file_path,
+                    header_line=1,  # Header entries are at file start
+                    rule_id=rule_id,
+                    justification=justification,
+                )
+            )
+
+        return violations

src/linters/lazy_ignores/matcher.py

@@ -0,0 +1,135 @@
+"""
+Purpose: Cross-reference matcher for lazy-ignores linter
+
+Scope: Matching ignore directives with header suppressions
+
+Overview: Provides IgnoreSuppressionMatcher class that cross-references linting ignore
+    directives found in code with Suppressions entries declared in file headers. Handles
+    case-insensitive rule ID normalization and special patterns like type:ignore[code].
+    Identifies unjustified ignores (code ignores without header entries) and orphaned
+    suppressions (header entries without matching code ignores).
+
+Dependencies: SuppressionsParser for normalization, types for IgnoreDirective and IgnoreType,
+    rule_id_utils for pure parsing functions
+
+Exports: IgnoreSuppressionMatcher
+
+Interfaces: find_unjustified(), find_orphaned()
+
+Implementation: Set-based matching with rule ID normalization for case-insensitive comparison
+"""
+
+from .header_parser import SuppressionsParser
+from .rule_id_utils import (
+    comma_list_has_used_rule,
+    find_rule_in_suppressions,
+    is_type_ignore_format_in_suppressions,
+    type_ignore_bracket_has_used_rule,
+)
+from .types import IgnoreDirective, IgnoreType
+
+
+class IgnoreSuppressionMatcher:
+    """Matches ignore directives with header suppressions."""
+
+    def __init__(self, parser: SuppressionsParser) -> None:
+        """Initialize the matcher.
+
+        Args:
+            parser: SuppressionsParser for rule ID normalization.
+        """
+        self._parser = parser
+
+    def collect_used_rule_ids(self, ignores: list[IgnoreDirective]) -> set[str]:
+        """Collect all normalized rule IDs used in ignore directives.
+
+        Args:
+            ignores: List of ignore directives from code.
+
+        Returns:
+            Set of normalized rule IDs that have ignore directives.
+        """
+        used: set[str] = set()
+        for ignore in ignores:
+            used.update(self._get_matchable_rule_ids(ignore))
+        return used
+
+    def _get_matchable_rule_ids(self, ignore: IgnoreDirective) -> list[str]:
+        """Get normalized rule IDs for matching, handling special formats."""
+        if not ignore.rule_ids:
+            return [self._normalize(ignore.ignore_type.value)]
+
+        ids: list[str] = []
+        for rule_id in ignore.rule_ids:
+            normalized = self._normalize(rule_id)
+            ids.append(normalized)
+            if ignore.ignore_type == IgnoreType.TYPE_IGNORE:
+                ids.append(f"type:ignore[{normalized}]")
+        return ids
+
+    def find_unjustified_rule_ids(
+        self, ignore: IgnoreDirective, suppressions: dict[str, str]
+    ) -> list[str]:
+        """Find which rule IDs in an ignore are not justified.
+
+        Args:
+            ignore: The ignore directive to check.
+            suppressions: Dict of normalized rule IDs to justifications.
+
+        Returns:
+            List of unjustified rule IDs (original case preserved).
+        """
+        if not ignore.rule_ids:
+            type_key = self._normalize(ignore.ignore_type.value)
+            if type_key not in suppressions:
+                return [ignore.ignore_type.value]
+            return []
+
+        unjustified: list[str] = []
+        for rule_id in ignore.rule_ids:
+            if not self._is_rule_justified(ignore, rule_id, suppressions):
+                unjustified.append(rule_id)
+        return unjustified
+
+    def _is_rule_justified(
+        self, ignore: IgnoreDirective, rule_id: str, suppressions: dict[str, str]
+    ) -> bool:
+        """Check if a specific rule ID is justified in suppressions."""
+        normalized = self._normalize(rule_id)
+        is_type_ignore = ignore.ignore_type == IgnoreType.TYPE_IGNORE
+
+        if normalized in suppressions:
+            return True
+        if is_type_ignore and is_type_ignore_format_in_suppressions(normalized, suppressions):
+            return True
+        return find_rule_in_suppressions(normalized, suppressions, is_type_ignore)
+
+    def find_orphaned_rule_ids(
+        self, suppressions: dict[str, str], used_rule_ids: set[str]
+    ) -> list[tuple[str, str]]:
+        """Find header suppressions without matching code ignores.
+
+        Args:
+            suppressions: Dict mapping normalized rule IDs to justifications.
+            used_rule_ids: Set of normalized rule IDs used in code.
+
+        Returns:
+            List of (rule_id, justification) tuples for orphaned suppressions.
+        """
+        orphaned: list[tuple[str, str]] = []
+        for rule_id, justification in suppressions.items():
+            if not self._suppression_is_used(rule_id, used_rule_ids):
+                orphaned.append((rule_id.upper(), justification))
+        return orphaned
+
+    def _suppression_is_used(self, suppression_key: str, used_rule_ids: set[str]) -> bool:
+        """Check if a suppression key is used by any code ignores."""
+        if suppression_key in used_rule_ids:
+            return True
+        if comma_list_has_used_rule(suppression_key, used_rule_ids):
+            return True
+        return type_ignore_bracket_has_used_rule(suppression_key, used_rule_ids)
+
+    def _normalize(self, rule_id: str) -> str:
+        """Normalize a rule ID for case-insensitive matching."""
+        return self._parser.normalize_rule_id(rule_id)

src/linters/lazy_ignores/python_analyzer.py

@@ -0,0 +1,205 @@
+"""
+Purpose: Detect Python linting ignore directives in source code
+
+Scope: noqa, type:ignore, pylint:disable, nosec, dry:ignore-block pattern detection
+
+Overview: Provides PythonIgnoreDetector class that scans Python source code for common
+    linting ignore patterns. Detects bare patterns (e.g., # noqa) and rule-specific
+    patterns (e.g., # noqa: PLR0912). Handles case-insensitive matching and extracts
+    rule IDs from comma-separated lists. Returns list of IgnoreDirective objects with
+    line/column positions for violation reporting. Skips patterns inside docstrings
+    and string literals to avoid false positives.
+
+Dependencies: re for pattern matching, pathlib for file paths, types module for dataclasses
+
+Exports: PythonIgnoreDetector
+
+Interfaces: find_ignores(code: str, file_path: Path | None) -> list[IgnoreDirective]
+
+Implementation: Regex-based line-by-line scanning with docstring-aware state tracking
+"""
+
+import re
+from pathlib import Path
+
+from src.linters.lazy_ignores.directive_utils import create_directive
+from src.linters.lazy_ignores.types import IgnoreDirective, IgnoreType
+
+
+def _count_unescaped_triple_quotes(line: str, quote: str) -> int:
+    """Count unescaped triple-quote occurrences in a line.
+
+    Uses regex to find non-escaped triple quotes.
+
+    Args:
+        line: Line to scan
+        quote: Triple-quote pattern to count (single or double)
+
+    Returns:
+        Number of unescaped triple-quote occurrences
+    """
+    # Pattern matches triple quotes not preceded by odd number of backslashes
+    # Escape the quote for regex
+    escaped_quote = re.escape(quote)
+    pattern = re.compile(rf"(?<!\\){escaped_quote}")
+    return len(pattern.findall(line))
+
+
+def _count_unescaped_single_quotes(text: str, quote_char: str) -> int:
+    """Count unescaped single quote characters in text.
+
+    Args:
+        text: Text to scan
+        quote_char: The quote character (' or ")
+
+    Returns:
+        Number of unescaped quote characters
+    """
+    count = 0
+    escaped = False
+    for char in text:
+        if escaped:
+            escaped = False
+            continue
+        if char == "\\":
+            escaped = True
+            continue
+        if char == quote_char:
+            count += 1
+    return count
+
+
+def _is_pattern_in_string_literal(line: str, match_start: int) -> bool:
+    """Check if a match position is inside a string literal.
+
+    Args:
+        line: The line of code
+        match_start: The start position of the pattern match
+
+    Returns:
+        True if the match is inside a string literal
+    """
+    before_match = line[:match_start]
+    single_count = _count_unescaped_single_quotes(before_match, "'")
+    double_count = _count_unescaped_single_quotes(before_match, '"')
+    return (single_count % 2 == 1) or (double_count % 2 == 1)
+
+
+class PythonIgnoreDetector:
+    """Detects Python linting ignore directives in source code."""
+
+    # Regex patterns for each ignore type
+    # Each pattern captures optional rule IDs in group 1
+    PATTERNS: dict[IgnoreType, re.Pattern[str]] = {
+        IgnoreType.NOQA: re.compile(
+            r"#\s*noqa(?::\s*([A-Z0-9,\s]+))?(?:\s|$)",
+            re.IGNORECASE,
+        ),
+        IgnoreType.TYPE_IGNORE: re.compile(
+            r"#\s*type:\s*ignore(?:\[([^\]]+)\])?",
+        ),
+        IgnoreType.PYLINT_DISABLE: re.compile(
+            r"#\s*pylint:\s*disable=([a-z0-9\-,\s]+)",
+            re.IGNORECASE,
+        ),
+        IgnoreType.NOSEC: re.compile(
+            r"#\s*nosec(?:\s+([A-Z0-9,\s]+))?(?:\s|$)",
+            re.IGNORECASE,
+        ),
+        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,
+        ),
+        IgnoreType.THAILINT_IGNORE_NEXT: re.compile(
+            r"#\s*thailint:\s*ignore-next-line(?:\[([^\]]+)\])?",
+            re.IGNORECASE,
+        ),
+        IgnoreType.THAILINT_IGNORE_BLOCK: re.compile(
+            r"#\s*thailint:\s*ignore-start(?:\[([^\]]+)\])?",
+            re.IGNORECASE,
+        ),
+        IgnoreType.DRY_IGNORE_BLOCK: re.compile(
+            r"#\s*dry:\s*ignore-block\b",
+            re.IGNORECASE,
+        ),
+    }
+
+    def find_ignores(self, code: str, file_path: Path | None = None) -> list[IgnoreDirective]:
+        """Find all Python ignore directives in code.
+
+        Tracks docstring state across lines to avoid false positives from
+        patterns mentioned in documentation.
+
+        Args:
+            code: Python source code to scan
+            file_path: Optional path to the source file
+
+        Returns:
+            List of IgnoreDirective objects for each detected ignore pattern
+        """
+        effective_path = file_path or Path("unknown")
+        scannable_lines = self._get_scannable_lines(code)
+        directives: list[IgnoreDirective] = []
+        for line_num, line in scannable_lines:
+            directives.extend(self._scan_line(line, line_num, effective_path))
+        return directives
+
+    def _get_scannable_lines(self, code: str) -> list[tuple[int, str]]:
+        """Get lines that are not inside docstrings.
+
+        Args:
+            code: Source code to analyze
+
+        Returns:
+            List of (line_number, line_text) tuples for scannable lines
+        """
+        in_docstring = [False, False]  # [triple_double, triple_single]
+        quotes = ['"""', "'''"]
+        scannable: list[tuple[int, str]] = []
+
+        for line_num, line in enumerate(code.splitlines(), start=1):
+            was_in_docstring = in_docstring[0] or in_docstring[1]
+            self._update_docstring_state(line, quotes, in_docstring)
+            if not was_in_docstring:
+                scannable.append((line_num, line))
+
+        return scannable
+
+    def _update_docstring_state(self, line: str, quotes: list[str], state: list[bool]) -> None:
+        """Update docstring tracking state based on quotes in line.
+
+        Args:
+            line: Line to analyze
+            quotes: List of quote patterns to check
+            state: Mutable list tracking in-docstring state for each quote type
+        """
+        for i, quote in enumerate(quotes):
+            if _count_unescaped_triple_quotes(line, quote) % 2 == 1:
+                state[i] = not state[i]
+
+    def _scan_line(self, line: str, line_num: int, file_path: Path) -> list[IgnoreDirective]:
+        """Scan a single line for ignore patterns.
+
+        Skips patterns that appear inside string literals.
+
+        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] = []
+        for ignore_type, pattern in self.PATTERNS.items():
+            match = pattern.search(line)
+            if not match:
+                continue
+            if _is_pattern_in_string_literal(line, match.start()):
+                continue
+            found.append(create_directive(match, ignore_type, line_num, file_path))
+        return found