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

src/cli/linters/shared.py

@@ -4,27 +4,172 @@ Purpose: Shared utilities for linter CLI commands
 Scope: Common helper functions and patterns used across all linter command modules
 
 Overview: Provides reusable utilities for linter CLI commands including config section management,
-    config value setting with logging, and rule ID filtering. Centralizes shared patterns to reduce
-    duplication across linter command modules (code_quality, code_patterns, structure, documentation).
-    All utilities are designed to work with the orchestrator configuration system.
+    config value setting with logging, rule ID filtering, CLI context extraction, and help text
+    generation. Centralizes shared patterns to reduce duplication across linter command modules
+    (code_quality, code_patterns, structure, documentation, performance). All utilities are designed
+    to work with the orchestrator configuration system and Click CLI framework.
 
-Dependencies: logging for debug output, pathlib for Path type hints
+Dependencies: logging for debug output, pathlib for Path type hints, click for Context type,
+    dataclasses for CommandContext
 
-Exports: ensure_config_section, set_config_value, filter_violations_by_prefix
+Exports: ensure_config_section, set_config_value, filter_violations_by_prefix, CommandContext,
+    extract_command_context, make_linter_help, ExecuteParams, prepare_standard_command,
+    run_linter_command, standard_linter_options, filter_violations_by_startswith,
+    create_linter_command
 
-Interfaces: Orchestrator config dict manipulation, violation list filtering
+Interfaces: Orchestrator config dict manipulation, violation list filtering, CLI context extraction,
+    help text generation
 
 Implementation: Pure helper functions with no side effects beyond config mutation and logging
 """
 
 import logging
+from dataclasses import dataclass
+from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
+import click
+
+from src.cli.utils import format_option, get_project_root_from_context, handle_linting_error
 from src.core.types import Violation
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from src.orchestrator.core import Orchestrator
 
+
+def standard_linter_options(f: Any) -> Any:
+    """Apply standard linter CLI options to a command.
+
+    Bundles the common options used by most linter commands:
+    - paths argument (variadic)
+    - config file option
+    - format option
+    - recursive option
+    - pass_context
+
+    Usage:
+        @cli.command("my-linter")
+        @standard_linter_options
+        def my_linter(ctx, paths, config_file, format, recursive):
+            ...
+    """
+    f = click.pass_context(f)
+    f = click.option(
+        "--recursive/--no-recursive", default=True, help="Scan directories recursively"
+    )(f)
+    f = format_option(f)
+    f = click.option(
+        "--config", "-c", "config_file", type=click.Path(), help="Path to config file"
+    )(f)
+    f = click.argument("paths", nargs=-1, type=click.Path())(f)
+    return f
+
+
+@dataclass
+class CommandContext:
+    """Extracted context from CLI command invocation.
+
+    Consolidates common CLI command setup into a reusable structure.
+    """
+
+    verbose: bool
+    project_root: Path | None
+    path_objs: list[Path]
+
+
+@dataclass
+class ExecuteParams:
+    """Parameters for linter execution functions.
+
+    Bundles the common parameters passed to _execute_*_lint functions
+    to reduce function signature duplication across CLI modules.
+    """
+
+    path_objs: list[Path]
+    config_file: str | None
+    format: str
+    recursive: bool
+    verbose: bool
+    project_root: Path | None
+
+
+def extract_command_context(ctx: click.Context, paths: tuple[str, ...]) -> CommandContext:
+    """Extract common context values from CLI command invocation.
+
+    Consolidates the repeated pattern of extracting verbose, project_root,
+    and converting paths to Path objects with default handling.
+
+    Args:
+        ctx: Click context from command invocation
+        paths: Tuple of path strings from command arguments
+
+    Returns:
+        CommandContext with extracted values
+    """
+    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]
+
+    return CommandContext(verbose=verbose, project_root=project_root, path_objs=path_objs)
+
+
+def prepare_standard_command(
+    ctx: click.Context,
+    paths: tuple[str, ...],
+    config_file: str | None,
+    format: str,
+    recursive: bool,
+) -> ExecuteParams:
+    """Prepare standard linter command execution parameters.
+
+    Combines context extraction and ExecuteParams creation into a single call.
+    Use with commands that have the standard options (config, format, recursive).
+
+    Args:
+        ctx: Click context from command invocation
+        paths: Tuple of path strings from command arguments
+        config_file: Optional config file path
+        format: Output format
+        recursive: Whether to scan recursively
+
+    Returns:
+        ExecuteParams ready for _execute_*_lint function
+    """
+    cmd_ctx = extract_command_context(ctx, paths)
+    return ExecuteParams(
+        path_objs=cmd_ctx.path_objs,
+        config_file=config_file,
+        format=format,
+        recursive=recursive,
+        verbose=cmd_ctx.verbose,
+        project_root=cmd_ctx.project_root,
+    )
+
+
+def run_linter_command(
+    execute_fn: "Callable[[ExecuteParams], None]",
+    params: ExecuteParams,
+) -> None:
+    """Run a linter command with standard error handling.
+
+    Wraps the try/except pattern used by all linter commands.
+
+    Args:
+        execute_fn: The _execute_*_lint function to call
+        params: ExecuteParams for the execution
+    """
+    try:
+        execute_fn(params)
+    except Exception as e:
+        handle_linting_error(e, params.verbose)
+
+
 # Configure module logger
 logger = logging.getLogger(__name__)
 
@@ -87,3 +232,84 @@ def filter_violations_by_startswith(violations: list[Violation], prefix: str) ->
         Filtered list of violations where rule_id starts with the prefix
     """
     return [v for v in violations if v.rule_id.startswith(prefix)]
+
+
+def create_linter_command(
+    name: str,
+    execute_fn: "Callable[[ExecuteParams], None]",
+    brief: str,
+    description: str,
+) -> "Callable[..., None]":
+    """Create a standard linter CLI command.
+
+    Factory function that generates Click commands with consistent structure,
+    eliminating boilerplate duplication across linter command modules.
+
+    Args:
+        name: CLI command name (e.g., "magic-numbers")
+        execute_fn: The _execute_*_lint function to call
+        brief: Brief one-line description
+        description: Detailed multi-line description
+
+    Returns:
+        Decorated Click command function
+    """
+    from src.cli.main import cli
+
+    @cli.command(name, help=make_linter_help(name, brief, description))
+    @standard_linter_options
+    def command(
+        ctx: click.Context,
+        paths: tuple[str, ...],
+        config_file: str | None,
+        format: str,
+        recursive: bool,
+    ) -> None:
+        params = prepare_standard_command(ctx, paths, config_file, format, recursive)
+        run_linter_command(execute_fn, params)
+
+    return command
+
+
+def make_linter_help(command: str, brief: str, description: str) -> str:
+    """Generate standardized CLI help text for linter commands.
+
+    Creates consistent help text following the established pattern with
+    examples showing common usage patterns.
+
+    Args:
+        command: CLI command name (e.g., "magic-numbers")
+        brief: Brief one-line description
+        description: Detailed multi-line description
+
+    Returns:
+        Formatted help text string for Click command
+    """
+    return f"""{brief}
+
+    {description}
+
+    PATHS: Files or directories to lint (defaults to current directory if none provided)
+
+    Examples:
+
+        \\b
+        # Check current directory (all files recursively)
+        thai-lint {command}
+
+        \\b
+        # Check specific directory
+        thai-lint {command} src/
+
+        \\b
+        # Check single file
+        thai-lint {command} src/app.py
+
+        \\b
+        # Get JSON output
+        thai-lint {command} --format json .
+
+        \\b
+        # Use custom config file
+        thai-lint {command} --config .thailint.yaml src/
+    """

src/cli/linters/structure.py

@@ -23,7 +23,6 @@ SRP Exception: CLI command modules follow Click framework patterns requiring sim
 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
@@ -33,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,
@@ -155,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
@@ -278,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

@@ -23,7 +23,6 @@ SRP Exception: CLI command modules follow Click framework patterns requiring sim
 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
@@ -32,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,
@@ -153,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
@@ -280,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/core/linter_utils.py

@@ -1,17 +1,19 @@
 """
 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)
 
@@ -20,11 +22,27 @@ Implementation: Type-safe metadata access with fallbacks, generic config loading
 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
@@ -170,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/linters/file_header/atemporal_detector.py

@@ -15,7 +15,7 @@ Exports: AtemporalDetector class with detect_violations method
 
 Interfaces: detect_violations(text) -> list[tuple[str, str, int]] returns pattern matches with line numbers
 
-Implementation: Regex-based pattern matching with predefined patterns organized by category
+Implementation: Regex-based pattern matching with pre-compiled patterns organized by category
 
 Suppressions:
     - nesting: detect_violations iterates over pattern categories and their patterns.
@@ -23,46 +23,60 @@ Suppressions:
 """
 
 import re
+from re import Pattern
+
+
+def _compile_patterns(patterns: list[tuple[str, str]]) -> list[tuple[Pattern[str], str]]:
+    """Compile regex patterns for efficient reuse."""
+    return [(re.compile(pattern, re.IGNORECASE), desc) for pattern, desc in patterns]
 
 
 class AtemporalDetector:
     """Detects temporal language patterns in text."""
 
-    # Date patterns
-    DATE_PATTERNS = [
-        (r"\d{4}-\d{2}-\d{2}", "ISO date format (YYYY-MM-DD)"),
-        (
-            r"(?:January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{4}",
-            "Month Year format",
-        ),
-        (r"(?:Created|Updated|Modified):\s*\d{4}", "Date metadata"),
-    ]
-
-    # Temporal qualifiers
-    TEMPORAL_QUALIFIERS = [
-        (r"\bcurrently\b", 'temporal qualifier "currently"'),
-        (r"\bnow\b", 'temporal qualifier "now"'),
-        (r"\brecently\b", 'temporal qualifier "recently"'),
-        (r"\bsoon\b", 'temporal qualifier "soon"'),
-        (r"\bfor now\b", 'temporal qualifier "for now"'),
-    ]
-
-    # State change language
-    STATE_CHANGE = [
-        (r"\breplaces?\b", 'state change "replaces"'),
-        (r"\bmigrated from\b", 'state change "migrated from"'),
-        (r"\bformerly\b", 'state change "formerly"'),
-        (r"\bold implementation\b", 'state change "old"'),
-        (r"\bnew implementation\b", 'state change "new"'),
-    ]
-
-    # Future references
-    FUTURE_REFS = [
-        (r"\bwill be\b", 'future reference "will be"'),
-        (r"\bplanned\b", 'future reference "planned"'),
-        (r"\bto be added\b", 'future reference "to be added"'),
-        (r"\bcoming soon\b", 'future reference "coming soon"'),
-    ]
+    # Pre-compiled date patterns
+    DATE_PATTERNS = _compile_patterns(
+        [
+            (r"\d{4}-\d{2}-\d{2}", "ISO date format (YYYY-MM-DD)"),
+            (
+                r"(?:January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{4}",
+                "Month Year format",
+            ),
+            (r"(?:Created|Updated|Modified):\s*\d{4}", "Date metadata"),
+        ]
+    )
+
+    # Pre-compiled temporal qualifiers
+    TEMPORAL_QUALIFIERS = _compile_patterns(
+        [
+            (r"\bcurrently\b", 'temporal qualifier "currently"'),
+            (r"\bnow\b", 'temporal qualifier "now"'),
+            (r"\brecently\b", 'temporal qualifier "recently"'),
+            (r"\bsoon\b", 'temporal qualifier "soon"'),
+            (r"\bfor now\b", 'temporal qualifier "for now"'),
+        ]
+    )
+
+    # Pre-compiled state change language
+    STATE_CHANGE = _compile_patterns(
+        [
+            (r"\breplaces?\b", 'state change "replaces"'),
+            (r"\bmigrated from\b", 'state change "migrated from"'),
+            (r"\bformerly\b", 'state change "formerly"'),
+            (r"\bold implementation\b", 'state change "old"'),
+            (r"\bnew implementation\b", 'state change "new"'),
+        ]
+    )
+
+    # Pre-compiled future references
+    FUTURE_REFS = _compile_patterns(
+        [
+            (r"\bwill be\b", 'future reference "will be"'),
+            (r"\bplanned\b", 'future reference "planned"'),
+            (r"\bto be added\b", 'future reference "to be added"'),
+            (r"\bcoming soon\b", 'future reference "coming soon"'),
+        ]
+    )
 
     def detect_violations(  # thailint: ignore[nesting]
         self, text: str
@@ -77,15 +91,15 @@ class AtemporalDetector:
         """
         violations = []
 
-        # Check all pattern categories
+        # Check all pattern categories (patterns are pre-compiled)
         all_patterns = (
             self.DATE_PATTERNS + self.TEMPORAL_QUALIFIERS + self.STATE_CHANGE + self.FUTURE_REFS
         )
 
         lines = text.split("\n")
         for line_num, line in enumerate(lines, start=1):
-            for pattern, description in all_patterns:
-                if re.search(pattern, line, re.IGNORECASE):
-                    violations.append((pattern, description, line_num))
+            for compiled_pattern, description in all_patterns:
+                if compiled_pattern.search(line):
+                    violations.append((compiled_pattern.pattern, description, line_num))
 
         return violations