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

src/analyzers/__init__.py

@@ -9,15 +9,16 @@ Overview: Package containing base analyzer classes for different programming lan
     (TypeScriptBaseAnalyzer, etc.) that linter-specific analyzers extend. Centralizes
     language parsing infrastructure to improve maintainability and consistency.
 
-Dependencies: tree-sitter, language-specific tree-sitter bindings
+Dependencies: tree-sitter, language-specific tree-sitter bindings, ast module
 
-Exports: TypeScriptBaseAnalyzer
+Exports: TypeScriptBaseAnalyzer, build_parent_map
 
 Interfaces: Base analyzer classes with parse(), walk_tree(), and extract() methods
 
 Implementation: Composition-based design for linter analyzers to use base utilities
 """
 
+from .ast_utils import build_parent_map
 from .typescript_base import TypeScriptBaseAnalyzer
 
-__all__ = ["TypeScriptBaseAnalyzer"]
+__all__ = ["TypeScriptBaseAnalyzer", "build_parent_map"]

src/analyzers/ast_utils.py

@@ -0,0 +1,54 @@
+"""
+Purpose: Common Python AST utilities for linter analyzers
+
+Scope: Shared AST traversal utilities for Python code analysis
+
+Overview: Provides common AST utility functions used across multiple Python linters.
+    Centralizes shared patterns like parent map building to eliminate code duplication.
+    The build_parent_map function creates a dictionary mapping AST nodes to their parents,
+    enabling upward tree traversal for context detection.
+
+Dependencies: ast module for AST node types
+
+Exports: build_parent_map
+
+Interfaces: build_parent_map(tree: ast.AST) -> dict[ast.AST, ast.AST]
+
+Implementation: Recursive AST traversal with parent tracking
+"""
+
+import ast
+
+
+def build_parent_map(tree: ast.AST) -> dict[ast.AST, ast.AST]:
+    """Build a map of AST nodes to their parent nodes.
+
+    Enables upward tree traversal for context detection (e.g., finding if a node
+    is inside a particular block type).
+
+    Args:
+        tree: Root AST node to build map from
+
+    Returns:
+        Dictionary mapping each node to its parent node
+    """
+    parent_map: dict[ast.AST, ast.AST] = {}
+    _build_parent_map_recursive(tree, None, parent_map)
+    return parent_map
+
+
+def _build_parent_map_recursive(
+    node: ast.AST, parent: ast.AST | None, parent_map: dict[ast.AST, ast.AST]
+) -> None:
+    """Recursively build parent map.
+
+    Args:
+        node: Current AST node
+        parent: Parent of current node
+        parent_map: Dictionary to populate
+    """
+    if parent is not None:
+        parent_map[node] = parent
+
+    for child in ast.iter_child_nodes(node):
+        _build_parent_map_recursive(child, node, parent_map)

src/analyzers/typescript_base.py

@@ -18,6 +18,10 @@ Exports: TypeScriptBaseAnalyzer class with parsing and traversal utilities
 Interfaces: parse_typescript(code), walk_tree(node, node_type), extract_node_text(node)
 
 Implementation: Tree-sitter parser singleton, recursive AST traversal, composition pattern
+
+Suppressions:
+    - type:ignore[assignment]: Tree-sitter TS_PARSER fallback when import fails
+    - type:ignore[assignment,misc]: Tree-sitter Node type alias (optional dependency fallback)
 """
 
 from typing import Any

src/cli/__init__.py

@@ -16,6 +16,9 @@ Exports: cli (main Click command group with all commands registered)
 Interfaces: Single import point for CLI access via 'from src.cli import cli'
 
 Implementation: Imports submodules to trigger command registration via Click decorators
+
+Suppressions:
+    - F401: Module re-exports required for public API interface
 """
 
 # Import the CLI group from main module

src/cli/config.py

@@ -26,9 +26,11 @@ import sys
 from pathlib import Path
 
 import click
+import yaml
 
 from src.config import ConfigError, save_config, validate_config
 
+from .config_merge import perform_merge
 from .main import cli
 
 # Configure module logger
@@ -98,8 +100,6 @@ def _format_config_json(cfg: dict) -> None:
 
 def _format_config_yaml(cfg: dict) -> None:
     """Format configuration as YAML."""
-    import yaml
-
     click.echo(yaml.dump(cfg, default_flow_style=False, sort_keys=False))
 
 
@@ -285,6 +285,9 @@ def init_config(preset: str, non_interactive: bool, force: bool, output: str) ->
     Creates a richly-commented configuration file with sensible defaults
     and optional customizations for different strictness levels.
 
+    If a config file already exists, missing linter sections will be added
+    without modifying existing settings. Use --force to completely overwrite.
+
     For AI agents, use --non-interactive mode:
       thailint init-config --non-interactive --preset lenient
 
@@ -308,7 +311,7 @@ def init_config(preset: str, non_interactive: bool, force: bool, output: str) ->
         thailint init-config --preset lenient
 
         \\b
-        # Overwrite existing config
+        # Overwrite existing config (replaces entire file)
         thailint init-config --force
 
         \\b
@@ -317,19 +320,16 @@ def init_config(preset: str, non_interactive: bool, force: bool, output: str) ->
     """
     output_path = Path(output)
 
-    # Check if file exists (unless --force)
-    if output_path.exists() and not force:
-        click.echo(f"Error: {output} already exists", err=True)
-        click.echo("", err=True)
-        click.echo("Use --force to overwrite:", err=True)
-        click.echo("  thailint init-config --force", err=True)
-        sys.exit(1)
-
     # Interactive mode: Ask user for preferences
     if not non_interactive:
         preset = _run_interactive_preset_selection(preset)
 
-    # Generate config based on preset
+    # If file exists and not forcing overwrite, merge missing sections
+    if output_path.exists() and not force:
+        perform_merge(output_path, preset, output, _generate_config_content)
+        return
+
+    # Generate full config based on preset
     config_content = _generate_config_content(preset)
 
     # Write config file

src/cli/config_merge.py

@@ -0,0 +1,241 @@
+"""
+Purpose: Configuration merge utilities for init-config command
+
+Scope: Functions for merging missing linter sections into existing config files
+
+Overview: Provides utilities for the init-config command to add missing linter sections
+    to existing configuration files without overwriting user customizations. Handles
+    template parsing, section extraction, missing section identification, and content
+    merging while preserving comments and formatting.
+
+Dependencies: re for pattern matching, yaml for config parsing, click for output,
+    pathlib for file operations
+
+Exports: perform_merge, LINTER_SECTIONS
+
+Interfaces: perform_merge(output_path, preset, output, generate_config_fn) -> None
+
+Implementation: Text-based parsing and merging to preserve YAML comments
+"""
+
+import re
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+import click
+import yaml
+
+# Known linter section names that should be in the template
+LINTER_SECTIONS = [
+    "magic-numbers",
+    "nesting",
+    "srp",
+    "dry",
+    "file-placement",
+    "print-statements",
+    "stringly-typed",
+    "file-header",
+    "method-property",
+    "stateless-class",
+    "pipeline",
+    "lazy-ignores",
+]
+
+
+def _is_section_header_line(line: str) -> bool:
+    """Check if line is a section header (# ==== style comment)."""
+    return line.startswith("# ===")
+
+
+def _get_linter_section_name(line: str) -> str | None:
+    """Extract linter section name from line if it's a known linter section."""
+    section_match = re.match(r"^([a-z][a-z0-9-]*):$", line)
+    if section_match and section_match.group(1) in LINTER_SECTIONS:
+        return section_match.group(1)
+    return None
+
+
+def _is_buffer_line(line: str) -> bool:
+    """Check if line should be buffered (comment or empty)."""
+    stripped = line.strip()
+    return stripped.startswith("#") or stripped == ""
+
+
+def _save_current_section(
+    sections: dict[str, str], current_section: str | None, current_content: list[str]
+) -> None:
+    """Save current section to sections dict if valid."""
+    if current_section and current_content:
+        sections[current_section] = "\n".join(current_content)
+
+
+def _handle_section_header(
+    line: str, sections: dict[str, str], current_section: str | None, current_content: list[str]
+) -> tuple[str | None, list[str], list[str]]:
+    """Handle a section header line (# === style)."""
+    _save_current_section(sections, current_section, current_content)
+    return None, [], [line]
+
+
+def _start_linter_section(
+    section_name: str, line: str, header_buffer: list[str]
+) -> tuple[str | None, list[str], list[str]]:
+    """Start a new linter section with the header buffer and section line."""
+    return section_name, header_buffer + [line], []
+
+
+def _handle_content_line(
+    line: str, current_section: str | None, current_content: list[str], header_buffer: list[str]
+) -> tuple[str | None, list[str], list[str]]:
+    """Handle a regular content line."""
+    if current_section:
+        current_content.append(line)
+        return current_section, current_content, header_buffer
+    if _is_buffer_line(line):
+        header_buffer.append(line)
+        return current_section, current_content, header_buffer
+    return current_section, current_content, []
+
+
+def _process_template_line(
+    line: str,
+    sections: dict[str, str],
+    current_section: str | None,
+    current_content: list[str],
+    header_buffer: list[str],
+) -> tuple[str | None, list[str], list[str]]:
+    """Process a single template line and update state."""
+    if _is_section_header_line(line):
+        return _handle_section_header(line, sections, current_section, current_content)
+
+    section_name = _get_linter_section_name(line)
+    if section_name:
+        _save_current_section(sections, current_section, current_content)
+        return _start_linter_section(section_name, line, header_buffer)
+
+    return _handle_content_line(line, current_section, current_content, header_buffer)
+
+
+def extract_linter_sections(template: str) -> dict[str, str]:
+    """Extract each linter section from template as text blocks.
+
+    Args:
+        template: Full template content
+
+    Returns:
+        Dict mapping section name to section content (with header comments)
+    """
+    sections: dict[str, str] = {}
+    lines = template.split("\n")
+    current_section: str | None = None
+    current_content: list[str] = []
+    header_buffer: list[str] = []
+
+    for line in lines:
+        current_section, current_content, header_buffer = _process_template_line(
+            line, sections, current_section, current_content, header_buffer
+        )
+
+    # Save last section
+    if current_section and current_content:
+        sections[current_section] = "\n".join(current_content)
+
+    return sections
+
+
+def identify_missing_sections(existing_config: dict, all_sections: list[str]) -> list[str]:
+    """Identify which linter sections are missing from existing config.
+
+    Args:
+        existing_config: Parsed existing config dict
+        all_sections: List of all linter section names
+
+    Returns:
+        List of section names missing from existing config
+    """
+    return [s for s in all_sections if s not in existing_config]
+
+
+def _find_global_settings_position(content: str) -> int:
+    """Find position of GLOBAL SETTINGS section in content."""
+    marker = "# ============================================================================\n# GLOBAL SETTINGS"
+    return content.find(marker)
+
+
+def _insert_before_global_settings(content: str, sections_text: str, insert_pos: int) -> str:
+    """Insert sections before GLOBAL SETTINGS marker."""
+    return content[:insert_pos] + sections_text + "\n\n" + content[insert_pos:]
+
+
+def merge_config_sections(existing_content: str, missing_sections: dict[str, str]) -> str:
+    """Merge missing sections into existing config content.
+
+    Args:
+        existing_content: Original config file content
+        missing_sections: Dict of section name -> section content to add
+
+    Returns:
+        Merged config content with missing sections appended
+    """
+    if not missing_sections:
+        return existing_content
+
+    sections_text = "\n".join(missing_sections.values())
+    insert_pos = _find_global_settings_position(existing_content)
+
+    if insert_pos > 0:
+        return _insert_before_global_settings(existing_content, sections_text, insert_pos)
+    return existing_content.rstrip() + "\n\n" + sections_text + "\n"
+
+
+def _parse_existing_config(content: str, output: str) -> dict:
+    """Parse existing config file content as YAML."""
+    try:
+        return yaml.safe_load(content) or {}
+    except yaml.YAMLError:
+        click.echo(f"Error: Could not parse {output} as YAML", err=True)
+        click.echo("Use --force to overwrite with a fresh config", err=True)
+        sys.exit(1)
+
+
+def _build_missing_sections_dict(
+    missing_names: list[str], template_sections: dict[str, str]
+) -> dict[str, str]:
+    """Build dict of missing section name -> content."""
+    return {name: template_sections[name] for name in missing_names if name in template_sections}
+
+
+def _report_merge_results(missing_names: list[str], output: str) -> None:
+    """Report which sections were added."""
+    click.echo(f"Added {len(missing_names)} missing linter section(s) to {output}:")
+    for name in missing_names:
+        click.echo(f"  - {name}")
+
+
+def perform_merge(
+    output_path: Path, preset: str, output: str, generate_config_fn: Callable[[str], str]
+) -> None:
+    """Merge missing linter sections into existing config.
+
+    Args:
+        output_path: Path to existing config file
+        preset: Preset to use for missing sections
+        output: Output filename for display
+        generate_config_fn: Function to generate config content from preset
+    """
+    existing_content = output_path.read_text(encoding="utf-8")
+    existing_config = _parse_existing_config(existing_content, output)
+
+    template_sections = extract_linter_sections(generate_config_fn(preset))
+    missing_names = identify_missing_sections(existing_config, list(template_sections.keys()))
+
+    if not missing_names:
+        click.echo(f"{output} already contains all linter sections")
+        return
+
+    missing_sections = _build_missing_sections_dict(missing_names, template_sections)
+    merged_content = merge_config_sections(existing_content, missing_sections)
+    output_path.write_text(merged_content, encoding="utf-8")
+
+    _report_merge_results(missing_names, output)

src/cli/linters/__init__.py

@@ -16,6 +16,9 @@ Exports: All linter command functions for reference and testing
 Interfaces: Click command decorators, integration with main CLI group
 
 Implementation: Module imports trigger command registration via Click decorator side effects
+
+Suppressions:
+    - F401: Module imports trigger Click command registration via decorator side effects
 """
 
 # Import all linter command modules to register them with the CLI

src/cli/linters/code_patterns.py

@@ -1,17 +1,17 @@
 """
-Purpose: CLI commands for code pattern linters (print-statements, method-property, stateless-class)
+Purpose: CLI commands for code pattern linters (print-statements, method-property, stateless-class, lazy-ignores)
 
 Scope: Commands that detect code patterns and anti-patterns in Python code
 
 Overview: Provides CLI commands for code pattern linting: print-statements detects print() and
     console.log calls that should use proper logging, method-property finds methods that should be
-    @property decorators, and stateless-class detects classes without state that should be module
-    functions. Each command supports standard options (config, format, recursive) and integrates
-    with the orchestrator for execution.
+    @property decorators, stateless-class detects classes without state that should be module
+    functions, and lazy-ignores detects unjustified linting suppressions. Each command supports
+    standard options (config, format, recursive) and integrates with the orchestrator for execution.
 
 Dependencies: click for CLI framework, src.cli.main for CLI group, src.cli.utils for shared utilities
 
-Exports: print_statements command, method_property command, stateless_class command
+Exports: print_statements command, method_property command, stateless_class command, lazy_ignores command
 
 Interfaces: Click CLI commands registered to main CLI group
 
@@ -19,6 +19,9 @@ 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
 
@@ -370,3 +373,108 @@ def _execute_stateless_class_lint(  # pylint: disable=too-many-arguments,too-man
 
     format_violations(stateless_class_violations, format)
     sys.exit(1 if stateless_class_violations else 0)
+
+
+# =============================================================================
+# Lazy Ignores Command
+# =============================================================================
+
+
+def _setup_lazy_ignores_orchestrator(
+    path_objs: list[Path], config_file: str | None, verbose: bool, project_root: Path | None = None
+) -> "Orchestrator":
+    """Set up orchestrator for lazy-ignores command."""
+    return setup_base_orchestrator(path_objs, config_file, verbose, project_root)
+
+
+def _run_lazy_ignores_lint(
+    orchestrator: "Orchestrator", path_objs: list[Path], recursive: bool
+) -> list[Violation]:
+    """Execute lazy-ignores lint on files or directories."""
+    all_violations = execute_linting_on_paths(orchestrator, path_objs, recursive)
+    return [v for v in all_violations if v.rule_id.startswith("lazy-ignores")]
+
+
+@cli.command("lazy-ignores")
+@click.argument("paths", nargs=-1, type=click.Path())
+@click.option("--config", "-c", "config_file", type=click.Path(), help="Path to config file")
+@format_option
+@click.option("--recursive/--no-recursive", default=True, help="Scan directories recursively")
+@click.pass_context
+def lazy_ignores(
+    ctx: click.Context,
+    paths: tuple[str, ...],
+    config_file: str | None,
+    format: str,
+    recursive: bool,
+) -> None:
+    """Check for unjustified linting suppressions.
+
+    Detects ignore directives (noqa, type:ignore, pylint:disable, nosec) that lack
+    corresponding entries in the file header's Suppressions section. Enforces a
+    header-based suppression model requiring human approval for all linting bypasses.
+
+    PATHS: Files or directories to lint (defaults to current directory if none provided)
+
+    Examples:
+
+        \b
+        # Check current directory (all files recursively)
+        thai-lint lazy-ignores
+
+        \b
+        # Check specific directory
+        thai-lint lazy-ignores src/
+
+        \b
+        # Check single file
+        thai-lint lazy-ignores src/routes.py
+
+        \b
+        # Check multiple files
+        thai-lint lazy-ignores src/routes.py src/utils.py
+
+        \b
+        # Get JSON output
+        thai-lint lazy-ignores --format json .
+
+        \b
+        # Get SARIF output for CI/CD integration
+        thai-lint lazy-ignores --format sarif src/
+
+        \b
+        # Use custom config file
+        thai-lint lazy-ignores --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]
+
+    try:
+        _execute_lazy_ignores_lint(path_objs, config_file, format, recursive, verbose, project_root)
+    except Exception as e:
+        handle_linting_error(e, verbose)
+
+
+def _execute_lazy_ignores_lint(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    path_objs: list[Path],
+    config_file: str | None,
+    format: str,
+    recursive: bool,
+    verbose: bool,
+    project_root: Path | None = None,
+) -> NoReturn:
+    """Execute lazy-ignores lint."""
+    validate_paths_exist(path_objs)
+    orchestrator = _setup_lazy_ignores_orchestrator(path_objs, config_file, verbose, project_root)
+    lazy_ignores_violations = _run_lazy_ignores_lint(orchestrator, path_objs, recursive)
+
+    if verbose:
+        logger.info(f"Found {len(lazy_ignores_violations)} lazy-ignores violation(s)")
+
+    format_violations(lazy_ignores_violations, format)
+    sys.exit(1 if lazy_ignores_violations else 0)

src/cli/linters/code_smells.py

@@ -20,6 +20,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: Click commands require many parameters by framework design
+    too-many-positional-arguments: Click positional params match CLI arg structure
 """
 # dry: ignore-block - CLI commands follow Click framework pattern with intentional repetition
 

src/cli/linters/documentation.py

@@ -19,6 +19,9 @@ 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
 

src/cli/linters/structure.py

@@ -19,6 +19,9 @@ 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
 

src/cli/linters/structure_quality.py

@@ -19,6 +19,9 @@ 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
 

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)