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

src/cli/linters/structure.py

@@ -19,8 +19,10 @@ Implementation: Click decorators for command definition, orchestrator-based lint
 
 SRP Exception: CLI command modules follow Click framework patterns requiring similar command
     structure across all linter commands. This is intentional design for consistency.
+
+Suppressions:
+    - too-many-arguments,too-many-positional-arguments: Click commands require many parameters by framework design
 """
-# dry: ignore-block - CLI commands follow Click framework pattern with intentional repetition
 
 import json
 import logging
@@ -30,13 +32,16 @@ from typing import TYPE_CHECKING, Any, NoReturn
 
 import click
 
-from src.cli.linters.shared import ensure_config_section, set_config_value
+from src.cli.linters.shared import (
+    ensure_config_section,
+    extract_command_context,
+    set_config_value,
+)
 from src.cli.main import cli
 from src.cli.utils import (
     execute_linting_on_paths,
     format_option,
     get_or_detect_project_root,
-    get_project_root_from_context,
     handle_linting_error,
     load_config_file,
     setup_base_orchestrator,
@@ -152,20 +157,20 @@ def file_placement(  # pylint: disable=too-many-arguments,too-many-positional-ar
         # Inline JSON rules
         thai-lint file-placement --rules '{"allow": [".*\\.py$"]}' .
     """
-    verbose: bool = ctx.obj.get("verbose", False)
-    project_root = get_project_root_from_context(ctx)
-
-    if not paths:
-        paths = (".",)
-
-    path_objs = [Path(p) for p in paths]
+    cmd_ctx = extract_command_context(ctx, paths)
 
     try:
         _execute_file_placement_lint(
-            path_objs, config_file, rules, format, recursive, verbose, project_root
+            cmd_ctx.path_objs,
+            config_file,
+            rules,
+            format,
+            recursive,
+            cmd_ctx.verbose,
+            cmd_ctx.project_root,
         )
     except Exception as e:
-        handle_linting_error(e, verbose)
+        handle_linting_error(e, cmd_ctx.verbose)
 
 
 def _execute_file_placement_lint(  # pylint: disable=too-many-arguments,too-many-positional-arguments
@@ -275,20 +280,20 @@ def pipeline(  # pylint: disable=too-many-arguments,too-many-positional-argument
         # Use custom config file
         thai-lint pipeline --config .thailint.yaml src/
     """
-    verbose: bool = ctx.obj.get("verbose", False)
-    project_root = get_project_root_from_context(ctx)
-
-    if not paths:
-        paths = (".",)
-
-    path_objs = [Path(p) for p in paths]
+    cmd_ctx = extract_command_context(ctx, paths)
 
     try:
         _execute_pipeline_lint(
-            path_objs, config_file, format, min_continues, recursive, verbose, project_root
+            cmd_ctx.path_objs,
+            config_file,
+            format,
+            min_continues,
+            recursive,
+            cmd_ctx.verbose,
+            cmd_ctx.project_root,
         )
     except Exception as e:
-        handle_linting_error(e, verbose)
+        handle_linting_error(e, cmd_ctx.verbose)
 
 
 def _execute_pipeline_lint(  # pylint: disable=too-many-arguments,too-many-positional-arguments

src/cli/linters/structure_quality.py

@@ -19,8 +19,10 @@ Implementation: Click decorators for command definition, orchestrator-based lint
 
 SRP Exception: CLI command modules follow Click framework patterns requiring similar command
     structure across all linter commands. This is intentional design for consistency.
+
+Suppressions:
+    - too-many-arguments,too-many-positional-arguments: Click commands require many parameters by framework design
 """
-# dry: ignore-block - CLI commands follow Click framework pattern with intentional repetition
 
 import logging
 import sys
@@ -29,12 +31,15 @@ from typing import TYPE_CHECKING, NoReturn
 
 import click
 
-from src.cli.linters.shared import ensure_config_section, set_config_value
+from src.cli.linters.shared import (
+    ensure_config_section,
+    extract_command_context,
+    set_config_value,
+)
 from src.cli.main import cli
 from src.cli.utils import (
     execute_linting_on_paths,
     format_option,
-    get_project_root_from_context,
     handle_linting_error,
     parallel_option,
     setup_base_orchestrator,
@@ -150,20 +155,21 @@ def nesting(  # pylint: disable=too-many-arguments,too-many-positional-arguments
         # Use custom config file
         thai-lint nesting --config .thailint.yaml src/
     """
-    verbose: bool = ctx.obj.get("verbose", False)
-    project_root = get_project_root_from_context(ctx)
-
-    if not paths:
-        paths = (".",)
-
-    path_objs = [Path(p) for p in paths]
+    cmd_ctx = extract_command_context(ctx, paths)
 
     try:
         _execute_nesting_lint(
-            path_objs, config_file, format, max_depth, recursive, parallel, verbose, project_root
+            cmd_ctx.path_objs,
+            config_file,
+            format,
+            max_depth,
+            recursive,
+            parallel,
+            cmd_ctx.verbose,
+            cmd_ctx.project_root,
         )
     except Exception as e:
-        handle_linting_error(e, verbose)
+        handle_linting_error(e, cmd_ctx.verbose)
 
 
 def _execute_nesting_lint(  # pylint: disable=too-many-arguments,too-many-positional-arguments
@@ -277,20 +283,21 @@ def srp(  # pylint: disable=too-many-arguments,too-many-positional-arguments
         # Use custom config file
         thai-lint srp --config .thailint.yaml src/
     """
-    verbose: bool = ctx.obj.get("verbose", False)
-    project_root = get_project_root_from_context(ctx)
-
-    if not paths:
-        paths = (".",)
-
-    path_objs = [Path(p) for p in paths]
+    cmd_ctx = extract_command_context(ctx, paths)
 
     try:
         _execute_srp_lint(
-            path_objs, config_file, format, max_methods, max_loc, recursive, verbose, project_root
+            cmd_ctx.path_objs,
+            config_file,
+            format,
+            max_methods,
+            max_loc,
+            recursive,
+            cmd_ctx.verbose,
+            cmd_ctx.project_root,
         )
     except Exception as e:
-        handle_linting_error(e, verbose)
+        handle_linting_error(e, cmd_ctx.verbose)
 
 
 def _execute_srp_lint(  # pylint: disable=too-many-arguments,too-many-positional-arguments

src/cli_main.py

@@ -17,6 +17,9 @@ Exports: cli (main command group with all commands registered)
 Interfaces: Click CLI commands, integration with Orchestrator for linting execution
 
 Implementation: Module imports trigger command registration via Click decorator side effects
+
+Suppressions:
+    - F401: Module re-exports and imports trigger Click command registration via decorator side effects
 """
 
 # Import the main CLI group from the modular package

src/config.py

@@ -26,6 +26,7 @@ from typing import Any
 import yaml
 
 from src.core.config_parser import ConfigParseError, parse_config_file
+from src.core.constants import CONFIG_EXTENSIONS
 
 logger = logging.getLogger(__name__)
 
@@ -170,7 +171,7 @@ def _validate_before_save(config: dict[str, Any]) -> None:
 
 def _write_config_file(config: dict[str, Any], path: Path) -> None:
     """Write config to file based on extension."""
-    if path.suffix in [".yaml", ".yml"]:
+    if path.suffix in CONFIG_EXTENSIONS:
         _write_yaml_config(config, path)
     elif path.suffix == ".json":
         _write_json_config(config, path)

src/core/base.py

@@ -31,6 +31,7 @@ from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import Any
 
+from .constants import Language
 from .types import Violation
 
 
@@ -176,10 +177,10 @@ class MultiLanguageLintRule(BaseLintRule):
         if not config.enabled:
             return []
 
-        if context.language == "python":
+        if context.language == Language.PYTHON:
             return self._check_python(context, config)
 
-        if context.language in ("typescript", "javascript"):
+        if context.language in (Language.TYPESCRIPT, Language.JAVASCRIPT):
             return self._check_typescript(context, config)
 
         return []

src/core/cli_utils.py

@@ -26,6 +26,8 @@ from typing import Any
 
 import click
 
+from src.core.constants import CONFIG_EXTENSIONS
+
 
 def common_linter_options(func: Callable) -> Callable:
     """Add common linter CLI options to command.
@@ -103,7 +105,7 @@ def _load_config_by_format(config_file: Path) -> dict[str, Any]:
     Returns:
         Loaded configuration dictionary
     """
-    if config_file.suffix in {".yaml", ".yml"}:
+    if config_file.suffix in CONFIG_EXTENSIONS:
         return _load_yaml_config(config_file)
     if config_file.suffix == ".json":
         return _load_json_config(config_file)

src/core/config_parser.py

@@ -27,6 +27,8 @@ from typing import Any, TextIO
 
 import yaml
 
+from src.core.constants import CONFIG_EXTENSIONS
+
 
 class ConfigParseError(Exception):
     """Configuration file parsing errors."""
@@ -113,11 +115,12 @@ def parse_config_file(path: Path, encoding: str = "utf-8") -> dict[str, Any]:
     """
     suffix = path.suffix.lower()
 
-    if suffix not in [".yaml", ".yml", ".json"]:
+    valid_suffixes = (*CONFIG_EXTENSIONS, ".json")
+    if suffix not in valid_suffixes:
         raise ConfigParseError(f"Unsupported config format: {suffix}")
 
     with path.open(encoding=encoding) as f:
-        if suffix in [".yaml", ".yml"]:
+        if suffix in CONFIG_EXTENSIONS:
             config = parse_yaml(f, path)
         else:
             config = parse_json(f, path)

src/core/constants.py

@@ -0,0 +1,54 @@
+"""
+Purpose: Core constants and enums used across the thai-lint codebase
+
+Scope: Centralized definitions for language names, storage modes, config extensions
+
+Overview: Provides type-safe enums and constants for consistent stringly-typed patterns
+    across the codebase. Includes Language enum for programming language detection,
+    StorageMode for cache storage options, and CONFIG_EXTENSIONS for config file
+    discovery. Using enums ensures compile-time safety and IDE autocompletion.
+
+Dependencies: enum module
+
+Exports: Language enum, StorageMode enum, CONFIG_EXTENSIONS, IgnoreDirective enum,
+    HEADER_SCAN_LINES, MAX_ATTRIBUTE_CHAIN_DEPTH
+
+Interfaces: Use enum values instead of string literals throughout codebase
+
+Implementation: Standard Python enums with string values for compatibility
+"""
+
+from enum import Enum
+
+
+class Language(str, Enum):
+    """Supported programming languages for linting."""
+
+    PYTHON = "python"
+    TYPESCRIPT = "typescript"
+    JAVASCRIPT = "javascript"
+    MARKDOWN = "markdown"
+
+
+class StorageMode(str, Enum):
+    """Storage modes for DRY linter cache."""
+
+    MEMORY = "memory"
+    TEMPFILE = "tempfile"
+
+
+class IgnoreDirective(str, Enum):
+    """Inline ignore directive types."""
+
+    IGNORE = "ignore"
+    IGNORE_FILE = "ignore-file"
+
+
+# Valid config file extensions
+CONFIG_EXTENSIONS: tuple[str, str] = (".yaml", ".yml")
+
+# Number of lines to scan at file start for ignore directives and headers
+HEADER_SCAN_LINES: int = 10
+
+# Maximum depth for attribute chain traversal (e.g., obj.attr.attr2.attr3)
+MAX_ATTRIBUTE_CHAIN_DEPTH: int = 3

src/core/linter_utils.py

@@ -1,26 +1,48 @@
 """
 Purpose: Shared utility functions for linter framework patterns
 
-Scope: Common config loading, metadata access, and context validation utilities for all linters
+Scope: Common config loading, metadata access, context validation, and AST parsing utilities
 
 Overview: Provides reusable helper functions to eliminate duplication across linter implementations.
     Includes utilities for loading configuration from context metadata with language-specific overrides,
-    extracting metadata fields safely with type validation, and validating context state. Standardizes
-    common patterns used by srp, nesting, dry, and file_placement linters. Reduces boilerplate code
-    while maintaining type safety and proper error handling.
+    extracting metadata fields safely with type validation, validating context state, and parsing
+    Python AST with syntax error handling. Standardizes common patterns used by srp, nesting, dry,
+    performance, and file_placement linters. Reduces boilerplate code while maintaining type safety
+    and proper error handling.
 
-Dependencies: BaseLintContext from src.core.base
+Dependencies: BaseLintContext from src.core.base, ast for Python parsing
 
-Exports: get_metadata, get_metadata_value, load_linter_config, has_file_content
+Exports: get_metadata, get_metadata_value, load_linter_config, has_file_content, parse_python_ast,
+    with_parsed_python
 
 Interfaces: All functions take BaseLintContext and return typed values (dict, str, bool, Any)
 
 Implementation: Type-safe metadata access with fallbacks, generic config loading with language support
+
+Suppressions:
+    - invalid-name: T type variable follows Python generic naming convention
+    - type:ignore[return-value]: Generic config factory with runtime type checking
+    - unnecessary-ellipsis: Protocol method bodies use ellipsis per PEP 544
+    - B101: Assert used to narrow type after parse_python_ast returns non-None tree
 """
 
+import ast
+from collections.abc import Callable
 from typing import Any, Protocol, TypeVar
 
 from src.core.base import BaseLintContext
+from src.core.types import Violation
+
+
+# Protocol for violation builders that support syntax error handling
+class SyntaxErrorViolationBuilder(Protocol):
+    """Protocol for violation builders that can create syntax error violations."""
+
+    def create_syntax_error_violation(
+        self, error: SyntaxError, context: BaseLintContext
+    ) -> Violation:
+        """Create a violation for a syntax error."""
+        ...  # pylint: disable=unnecessary-ellipsis
 
 
 # Protocol for config classes that support from_dict
@@ -166,3 +188,70 @@ def should_process_file(context: BaseLintContext) -> bool:
         True if file has both content and path available
     """
     return has_file_content(context) and has_file_path(context)
+
+
+def parse_python_ast(
+    context: BaseLintContext,
+    violation_builder: SyntaxErrorViolationBuilder,
+) -> tuple[ast.Module | None, list[Violation]]:
+    """Parse Python AST from context, handling syntax errors gracefully.
+
+    Provides a standard pattern for Python linters to parse AST and handle
+    syntax errors by returning a violation instead of crashing.
+
+    Args:
+        context: Lint context containing file content
+        violation_builder: Builder to create syntax error violations
+
+    Returns:
+        Tuple of (ast_tree, violations):
+        - On success: (ast.Module, [])
+        - On syntax error: (None, [syntax_error_violation])
+
+    Example:
+        tree, errors = parse_python_ast(context, self._violation_builder)
+        if errors:
+            return errors
+        # ... use tree for analysis
+    """
+    try:
+        tree = ast.parse(context.file_content or "")
+        return tree, []
+    except SyntaxError as e:
+        violation = violation_builder.create_syntax_error_violation(e, context)
+        return None, [violation]
+
+
+def with_parsed_python(
+    context: BaseLintContext,
+    violation_builder: SyntaxErrorViolationBuilder,
+    on_success: Callable[[ast.Module], list[Violation]],
+) -> list[Violation]:
+    """Parse Python and call on_success with the AST, or return parse errors.
+
+    Eliminates the repeated parse-check-assert pattern across Python linters.
+    On parse success, calls on_success with a guaranteed non-None AST tree.
+    On parse failure, returns syntax error violations.
+
+    Args:
+        context: Lint context containing file content
+        violation_builder: Builder to create syntax error violations
+        on_success: Callback receiving the parsed AST tree, returns violations
+
+    Returns:
+        Violations from on_success callback, or syntax error violations
+
+    Example:
+        def _check_python(self, context, config):
+            return with_parsed_python(
+                context,
+                self._violation_builder,
+                lambda tree: self._analyze_tree(tree, config, context),
+            )
+    """
+    tree, errors = parse_python_ast(context, violation_builder)
+    if errors:
+        return errors
+    # tree is guaranteed non-None when errors is empty (parse_python_ast contract)
+    assert tree is not None  # nosec B101
+    return on_success(tree)

src/core/rule_discovery.py

@@ -19,12 +19,15 @@ Implementation: Package traversal with pkgutil, class introspection with inspect
 
 import importlib
 import inspect
+import logging
 import pkgutil
 from types import ModuleType
 from typing import Any
 
 from .base import BaseLintRule
 
+logger = logging.getLogger(__name__)
+
 
 def discover_from_package(package_path: str) -> list[BaseLintRule]:
     """Discover rules from a package and its modules.
@@ -37,7 +40,8 @@ def discover_from_package(package_path: str) -> list[BaseLintRule]:
     """
     try:
         package = importlib.import_module(package_path)
-    except ImportError:
+    except ImportError as e:
+        logger.debug("Failed to import package %s: %s", package_path, e)
         return []
 
     if not hasattr(package, "__path__"):

src/core/violation_builder.py

@@ -21,6 +21,9 @@ Interfaces: ViolationInfo(rule_id, file_path, line, message, column, severity),
 
 Implementation: Uses dataclass for type-safe violation info, functions provide build logic
     that constructs Violation objects with proper defaults
+
+Suppressions:
+    - too-many-arguments,too-many-positional-arguments: Violation fields as parameters
 """
 
 from dataclasses import dataclass

src/linter_config/directive_markers.py

@@ -0,0 +1,109 @@
+"""
+Purpose: Ignore directive marker detection for thailint comments
+
+Scope: Detection of thailint and design-lint ignore markers in source code
+
+Overview: Provides functions for detecting various ignore directive markers in code
+    comments. Supports file-level ignores, line-level ignores, block ignores, and
+    next-line ignores. Works with both Python (#) and JavaScript (//) comment styles.
+    All checks are case-insensitive.
+
+Dependencies: None (pure string operations)
+
+Exports: Marker detection functions for various ignore directive types
+
+Interfaces: has_*_marker(line) -> bool for each marker type
+
+Implementation: String-based pattern detection with case-insensitive matching
+"""
+
+
+def has_ignore_directive_marker(line: str) -> bool:
+    """Check if line contains a file-level ignore directive marker.
+
+    Args:
+        line: Line of code to check
+
+    Returns:
+        True if line has ignore-file marker
+    """
+    line_lower = line.lower()
+    return "# thailint: ignore-file" in line_lower or "# design-lint: ignore-file" in line_lower
+
+
+def has_line_ignore_marker(code: str) -> bool:
+    """Check if code line has an inline ignore marker.
+
+    Args:
+        code: Line of code to check
+
+    Returns:
+        True if line has inline ignore marker
+    """
+    code_lower = code.lower()
+    return (
+        "# thailint: ignore" in code_lower
+        or "# design-lint: ignore" in code_lower
+        or "// thailint: ignore" in code_lower
+        or "// design-lint: ignore" in code_lower
+    )
+
+
+def has_ignore_next_line_marker(line: str) -> bool:
+    """Check if line has ignore-next-line marker.
+
+    Args:
+        line: Line of code to check
+
+    Returns:
+        True if line has ignore-next-line marker
+    """
+    return "# thailint: ignore-next-line" in line or "# design-lint: ignore-next-line" in line
+
+
+def has_ignore_start_marker(line: str) -> bool:
+    """Check if line has ignore-start comment marker.
+
+    Only matches actual comment lines (starting with # or //), not strings
+    containing the marker text.
+
+    Args:
+        line: Line of code to check
+
+    Returns:
+        True if line is a proper ignore-start comment
+    """
+    stripped = line.strip().lower()
+    if not (stripped.startswith("#") or stripped.startswith("//")):
+        return False
+    return "ignore-start" in stripped and ("thailint:" in stripped or "design-lint:" in stripped)
+
+
+def has_ignore_end_marker(line: str) -> bool:
+    """Check if line has ignore-end comment marker.
+
+    Only matches actual comment lines (starting with # or //), not strings
+    containing the marker text.
+
+    Args:
+        line: Line of code to check
+
+    Returns:
+        True if line is a proper ignore-end comment
+    """
+    stripped = line.strip().lower()
+    if not (stripped.startswith("#") or stripped.startswith("//")):
+        return False
+    return "ignore-end" in stripped and ("thailint:" in stripped or "design-lint:" in stripped)
+
+
+def check_general_ignore(line: str) -> bool:
+    """Check if line has general ignore directive (no specific rules).
+
+    Args:
+        line: Line containing ignore directive
+
+    Returns:
+        True if no specific rules are specified (not bracket syntax)
+    """
+    return "ignore-file[" not in line