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

src/linters/lazy_ignores/directive_utils.py

@@ -0,0 +1,164 @@
+"""
+Purpose: Shared utility functions for creating IgnoreDirective objects
+
+Scope: Common directive creation and path normalization for ignore detectors
+
+Overview: Provides shared utility functions used across Python, TypeScript, and test skip
+    detectors. Centralizes logic for normalizing file paths, extracting rule IDs from
+    regex matches, extracting inline justifications, and creating IgnoreDirective objects
+    to avoid code duplication.
+
+Dependencies: re for match handling, pathlib for file paths, types module for dataclasses
+
+Exports: normalize_path, extract_rule_ids, create_directive, create_directive_no_rules,
+    extract_inline_justification
+
+Interfaces: Pure utility functions with no state
+
+Implementation: Simple helper functions for directive creation
+
+Suppressions:
+    too-many-arguments: create_directive needs all params for proper IgnoreDirective construction
+    too-many-positional-arguments: Factory function mirrors IgnoreDirective fields
+"""
+
+import re
+from pathlib import Path
+
+from src.linters.lazy_ignores.types import IgnoreDirective, IgnoreType
+
+# Pattern for inline justification: space-dash-space followed by text
+INLINE_JUSTIFICATION_PATTERN = re.compile(r"\s+-\s+(.+)$")
+
+
+def normalize_path(file_path: Path | str | None) -> Path:
+    """Normalize file path to Path object.
+
+    Args:
+        file_path: Path object, string path, or None
+
+    Returns:
+        Path object, defaults to Path("unknown") if None
+    """
+    if file_path is None:
+        return Path("unknown")
+    if isinstance(file_path, str):
+        return Path(file_path)
+    return file_path
+
+
+def extract_inline_justification(raw_text: str) -> str | None:
+    """Extract inline justification from raw directive text.
+
+    Looks for the pattern " - " (space-dash-space) followed by justification text.
+    This allows inline justifications like:
+        # noqa: PLR0912 - state machine inherently complex
+        # type: ignore[arg-type] - library has typing bug
+
+    Args:
+        raw_text: The raw comment text containing the ignore directive
+
+    Returns:
+        The justification text if found, None otherwise.
+        Returns None for empty/whitespace-only justifications.
+    """
+    match = INLINE_JUSTIFICATION_PATTERN.search(raw_text)
+    if not match:
+        return None
+
+    justification = match.group(1).strip()
+    return justification if justification else None
+
+
+def _get_captured_group(match: re.Match[str]) -> str | None:
+    """Get the first captured group from a regex match if it exists.
+
+    Args:
+        match: Regex match object
+
+    Returns:
+        Captured group text or None if no capture groups
+    """
+    if match.lastindex is None or match.lastindex < 1:
+        return None
+    return match.group(1)
+
+
+def extract_rule_ids(match: re.Match[str]) -> list[str]:
+    """Extract rule IDs from regex match group 1.
+
+    Args:
+        match: Regex match object with optional group 1 containing rule IDs
+
+    Returns:
+        List of rule ID strings, empty if no specific rules
+    """
+    group = _get_captured_group(match)
+    if not group:
+        return []
+
+    ids = [rule_id.strip() for rule_id in group.split(",")]
+    return [rule_id for rule_id in ids if rule_id]
+
+
+def create_directive(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    match: re.Match[str],
+    ignore_type: IgnoreType,
+    line_num: int,
+    file_path: Path,
+    rule_ids: tuple[str, ...] | None = None,
+    full_line: str | None = None,
+) -> IgnoreDirective:
+    """Create an IgnoreDirective from a regex match.
+
+    Args:
+        match: Regex match object
+        ignore_type: Type of ignore pattern
+        line_num: 1-indexed line number
+        file_path: Path to source file
+        rule_ids: Optional tuple of rule IDs; if None, extracts from match group 1
+        full_line: Optional full line text for extracting inline justification
+
+    Returns:
+        IgnoreDirective for this match
+    """
+    if rule_ids is None:
+        rule_ids = tuple(extract_rule_ids(match))
+
+    # Use full line from match position to capture inline justification
+    if full_line is not None:
+        raw_text = full_line[match.start() :].strip()
+    else:
+        raw_text = match.group(0).strip()
+
+    inline_justification = extract_inline_justification(raw_text)
+
+    return IgnoreDirective(
+        ignore_type=ignore_type,
+        rule_ids=rule_ids,
+        line=line_num,
+        column=match.start() + 1,
+        raw_text=raw_text,
+        file_path=file_path,
+        inline_justification=inline_justification,
+    )
+
+
+def create_directive_no_rules(
+    match: re.Match[str],
+    ignore_type: IgnoreType,
+    line_num: int,
+    file_path: Path,
+) -> IgnoreDirective:
+    """Create an IgnoreDirective without rule IDs (for patterns like test skips).
+
+    Args:
+        match: Regex match object
+        ignore_type: Type of ignore pattern
+        line_num: 1-indexed line number
+        file_path: Path to source file
+
+    Returns:
+        IgnoreDirective with empty rule_ids tuple
+    """
+    return create_directive(match, ignore_type, line_num, file_path, rule_ids=())

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,168 @@
+"""
+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, min_justification_length: int = 10) -> None:
+        """Initialize the matcher.
+
+        Args:
+            parser: SuppressionsParser for rule ID normalization.
+            min_justification_length: Minimum length for valid inline justification.
+        """
+        self._parser = parser
+        self._min_justification_length = min_justification_length
+
+    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.
+
+        Checks inline justification first (higher precedence), then falls back
+        to header-based suppressions.
+
+        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 self._has_valid_inline_justification(ignore):
+            return []
+
+        if not ignore.rule_ids:
+            return self._check_bare_ignore(ignore, suppressions)
+
+        return self._check_rule_specific_ignore(ignore, suppressions)
+
+    def _check_bare_ignore(
+        self, ignore: IgnoreDirective, suppressions: dict[str, str]
+    ) -> list[str]:
+        """Check if a bare ignore (no specific rules) is justified."""
+        type_key = self._normalize(ignore.ignore_type.value)
+        if type_key in suppressions:
+            return []
+        return [ignore.ignore_type.value]
+
+    def _check_rule_specific_ignore(
+        self, ignore: IgnoreDirective, suppressions: dict[str, str]
+    ) -> list[str]:
+        """Check which specific rule IDs are not justified."""
+        return [
+            rule_id
+            for rule_id in ignore.rule_ids
+            if not self._is_rule_justified(ignore, rule_id, suppressions)
+        ]
+
+    def _has_valid_inline_justification(self, ignore: IgnoreDirective) -> bool:
+        """Check if the ignore has a valid inline justification.
+
+        Args:
+            ignore: The ignore directive to check.
+
+        Returns:
+            True if the ignore has an inline justification meeting minimum length.
+        """
+        if not ignore.inline_justification:
+            return False
+        return len(ignore.inline_justification) >= self._min_justification_length
+
+    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)