thailint 0.4.6__py3-none-any.whl → 0.7.0__py3-none-any.whl

src/linters/file_header/markdown_parser.py

@@ -0,0 +1,124 @@
+"""
+Purpose: Markdown YAML frontmatter extraction and parsing
+
+Scope: Markdown file header parsing from YAML frontmatter
+
+Overview: Extracts YAML frontmatter from Markdown files. Frontmatter must be at the
+    start of the file, enclosed in --- markers. Parses YAML content to extract
+    field values using PyYAML when available, falling back to regex parsing if not.
+    Handles both simple key-value pairs and complex YAML structures including lists.
+    Flattens nested structures into string representations for field validation.
+
+Dependencies: re module for frontmatter pattern matching, yaml module (optional) for parsing, logging module
+
+Exports: MarkdownHeaderParser class
+
+Interfaces: extract_header(code) -> str | None for frontmatter extraction,
+    parse_fields(header) -> dict[str, str] for field parsing
+
+Implementation: YAML frontmatter extraction with PyYAML parsing and regex fallback for robustness
+"""
+
+import logging
+import re
+
+logger = logging.getLogger(__name__)
+
+
+class MarkdownHeaderParser:  # thailint: ignore[srp]
+    """Extracts and parses Markdown file headers from YAML frontmatter.
+
+    Method count (10) exceeds SRP guideline (8) because proper A-grade complexity
+    refactoring requires extracting small focused helper methods. Class maintains
+    single responsibility of YAML frontmatter parsing - all methods support this
+    core purpose through either PyYAML or simple regex parsing fallback.
+    """
+
+    # Pattern to match YAML frontmatter at start of file
+    FRONTMATTER_PATTERN = re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL)
+
+    def extract_header(self, code: str) -> str | None:
+        """Extract YAML frontmatter from Markdown file."""
+        if not code or not code.strip():
+            return None
+
+        match = self.FRONTMATTER_PATTERN.match(code)
+        return match.group(1).strip() if match else None
+
+    def parse_fields(self, header: str) -> dict[str, str]:
+        """Parse YAML frontmatter into field dictionary."""
+        yaml_result = self._try_yaml_parse(header)
+        if yaml_result is not None:
+            return yaml_result
+
+        return self._parse_simple_yaml(header)
+
+    def _try_yaml_parse(self, header: str) -> dict[str, str] | None:
+        """Try to parse with PyYAML, returning None if unavailable or failed."""
+        try:
+            import yaml
+
+            data = yaml.safe_load(header)
+            if isinstance(data, dict):
+                return self._flatten_yaml_dict(data)
+        except ImportError:
+            logger.debug("PyYAML not available, using simple parser")
+        except Exception:  # noqa: BLE001
+            logger.debug("YAML parsing failed, falling back to simple parser")
+        return None
+
+    def _flatten_yaml_dict(self, data: dict) -> dict[str, str]:
+        """Convert YAML dict to string values."""
+        result: dict[str, str] = {}
+        for key, value in data.items():
+            result[str(key)] = self._convert_value(value)
+        return result
+
+    def _convert_value(self, value: object) -> str:
+        """Convert a single YAML value to string."""
+        if isinstance(value, list):
+            return ", ".join(str(v) for v in value)
+        if value is not None:
+            return str(value)
+        return ""
+
+    def _parse_simple_yaml(  # thailint: ignore[nesting,dry]
+        self, header: str
+    ) -> dict[str, str]:
+        """Simple regex-based YAML parsing fallback."""
+        fields: dict[str, str] = {}
+        current_field: str | None = None
+        current_value: list[str] = []
+
+        for line in header.split("\n"):
+            if self._is_field_start(line):
+                self._save_field(fields, current_field, current_value)
+                current_field, current_value = self._start_field(line)
+            elif current_field and line.strip():
+                current_value.append(self._process_continuation(line))
+
+        self._save_field(fields, current_field, current_value)
+        return fields
+
+    def _is_field_start(self, line: str) -> bool:
+        """Check if line starts a new field (not indented, has colon)."""
+        return not line.startswith(" ") and ":" in line
+
+    def _start_field(self, line: str) -> tuple[str, list[str]]:
+        """Parse field start and return field name and initial value."""
+        parts = line.split(":", 1)
+        field_name = parts[0].strip()
+        value = parts[1].strip() if len(parts) > 1 else ""
+        return field_name, [value] if value else []
+
+    def _process_continuation(self, line: str) -> str:
+        """Process a continuation line (list item or multiline value)."""
+        stripped = line.strip()
+        return stripped[2:] if stripped.startswith("- ") else stripped
+
+    def _save_field(
+        self, fields: dict[str, str], field_name: str | None, values: list[str]
+    ) -> None:
+        """Save field to dictionary if field name exists."""
+        if field_name:
+            fields[field_name] = "\n".join(values).strip()

src/linters/file_header/python_parser.py

@@ -1,29 +1,29 @@
 """
-File: src/linters/file_header/python_parser.py
 Purpose: Python docstring extraction and parsing for file headers
-Exports: PythonHeaderParser class
-Depends: Python ast module
-Implements: AST-based docstring extraction with field parsing
-Related: linter.py for parser usage, field_validator.py for field validation
 
-Overview:
-    Extracts module-level docstrings from Python files using AST parsing.
+Scope: Python file header parsing from module-level docstrings
+
+Overview: Extracts module-level docstrings from Python files using AST parsing.
     Parses structured header fields from docstring content and handles both
     well-formed and malformed headers. Provides field extraction and validation
-    support for FileHeaderRule.
+    support for FileHeaderRule. Uses ast.get_docstring() for reliable extraction
+    and gracefully handles syntax errors in source code.
+
+Dependencies: Python ast module for AST parsing, base_parser.BaseHeaderParser for field parsing
+
+Exports: PythonHeaderParser class
 
-Usage:
-    parser = PythonHeaderParser()
-    header = parser.extract_header(code)
-    fields = parser.parse_fields(header)
+Interfaces: extract_header(code) -> str | None for docstring extraction, parse_fields(header) inherited from base
 
-Notes: Uses ast.get_docstring() for reliable module-level docstring extraction
+Implementation: AST-based docstring extraction with syntax error handling
 """
 
 import ast
 
+from src.linters.file_header.base_parser import BaseHeaderParser
 
-class PythonHeaderParser:
+
+class PythonHeaderParser(BaseHeaderParser):
     """Extracts and parses Python file headers from docstrings."""
 
     def extract_header(self, code: str) -> str | None:
@@ -40,47 +40,3 @@ class PythonHeaderParser:
             return ast.get_docstring(tree)
         except SyntaxError:
             return None
-
-    def parse_fields(self, header: str) -> dict[str, str]:  # thailint: ignore[nesting]
-        """Parse structured fields from header text.
-
-        Args:
-            header: Header docstring text
-
-        Returns:
-            Dictionary mapping field_name -> field_value
-        """
-        fields: dict[str, str] = {}
-        current_field: str | None = None
-        current_value: list[str] = []
-
-        for line in header.split("\n"):
-            if self._is_new_field_line(line):
-                current_field = self._save_and_start_new_field(
-                    fields, current_field, current_value, line
-                )
-                current_value = [line.split(":", 1)[1].strip()]
-            elif current_field:
-                current_value.append(line.strip())
-
-        self._save_current_field(fields, current_field, current_value)
-        return fields
-
-    def _is_new_field_line(self, line: str) -> bool:
-        """Check if line starts a new field."""
-        return ":" in line and not line.startswith(" ")
-
-    def _save_and_start_new_field(
-        self, fields: dict[str, str], current_field: str | None, current_value: list[str], line: str
-    ) -> str:
-        """Save current field and start new one."""
-        if current_field:
-            fields[current_field] = "\n".join(current_value).strip()
-        return line.split(":", 1)[0].strip()
-
-    def _save_current_field(
-        self, fields: dict[str, str], current_field: str | None, current_value: list[str]
-    ) -> None:
-        """Save the last field."""
-        if current_field:
-            fields[current_field] = "\n".join(current_value).strip()

src/linters/file_header/typescript_parser.py

@@ -0,0 +1,73 @@
+"""
+Purpose: TypeScript/JavaScript JSDoc comment extraction and parsing
+
+Scope: TypeScript and JavaScript file header parsing from JSDoc comments
+
+Overview: Extracts JSDoc-style comments (/** ... */) from TypeScript and JavaScript files.
+    Parses structured header fields from JSDoc content and handles both single-line
+    and multi-line field values. Distinguishes JSDoc comments from regular block
+    comments (/* ... */) by requiring the double asterisk syntax. Cleans formatting
+    characters including leading asterisks from content lines.
+
+Dependencies: re module for regex-based JSDoc pattern matching, base_parser.BaseHeaderParser for field parsing
+
+Exports: TypeScriptHeaderParser class
+
+Interfaces: extract_header(code) -> str | None for JSDoc extraction, parse_fields(header) inherited from base
+
+Implementation: Regex-based JSDoc extraction with content cleaning and formatting removal
+"""
+
+import re
+
+from src.linters.file_header.base_parser import BaseHeaderParser
+
+
+class TypeScriptHeaderParser(BaseHeaderParser):
+    """Extracts and parses TypeScript/JavaScript file headers from JSDoc comments."""
+
+    # Pattern to match JSDoc comment at start of file (allowing whitespace before)
+    JSDOC_PATTERN = re.compile(r"^\s*/\*\*\s*(.*?)\s*\*/", re.DOTALL)
+
+    def extract_header(self, code: str) -> str | None:
+        """Extract JSDoc comment from TypeScript/JavaScript code.
+
+        Args:
+            code: TypeScript/JavaScript source code
+
+        Returns:
+            JSDoc content or None if not found
+        """
+        if not code or not code.strip():
+            return None
+
+        match = self.JSDOC_PATTERN.match(code)
+        if not match:
+            return None
+
+        # Extract the content inside the JSDoc
+        jsdoc_content = match.group(1)
+
+        # Clean up the JSDoc content - remove leading * from each line
+        return self._clean_jsdoc_content(jsdoc_content)
+
+    def _clean_jsdoc_content(self, content: str) -> str:
+        """Remove JSDoc formatting (leading asterisks) from content.
+
+        Args:
+            content: Raw JSDoc content
+
+        Returns:
+            Cleaned content without leading asterisks
+        """
+        lines = content.split("\n")
+        cleaned_lines = []
+
+        for line in lines:
+            # Remove leading whitespace and asterisk
+            stripped = line.strip()
+            if stripped.startswith("*"):
+                stripped = stripped[1:].strip()
+            cleaned_lines.append(stripped)
+
+        return "\n".join(cleaned_lines)

src/linters/file_header/violation_builder.py

@@ -1,21 +1,22 @@
 """
-File: src/linters/file_header/violation_builder.py
 Purpose: Builds violation messages for file header linter
-Exports: ViolationBuilder class
-Depends: Violation type from core
-Implements: Message templates with context-specific details
-Related: linter.py for builder usage, atemporal_detector.py for temporal violations
 
-Overview:
-    Creates formatted violation messages for file header validation failures.
+Scope: Violation message creation for file header validation failures
+
+Overview: Creates formatted violation messages for file header validation failures.
     Handles missing fields, atemporal language, and other header issues with clear,
-    actionable messages. Provides consistent violation format across all validation types.
+    actionable messages. Provides consistent violation format across all validation types
+    including rule_id, message, location, severity, and helpful suggestions. Supports
+    multiple violation types with appropriate error messages and remediation guidance.
+
+Dependencies: Violation and Severity types from core.types module
+
+Exports: ViolationBuilder class
 
-Usage:
-    builder = ViolationBuilder("file-header.validation")
-    violation = builder.build_missing_field("Purpose", "test.py", 1)
+Interfaces: build_missing_field(field_name, file_path, line) -> Violation,
+    build_atemporal_violation(pattern, description, file_path, line) -> Violation
 
-Notes: Follows standard violation format with rule_id, message, location, severity, suggestion
+Implementation: Builder pattern with message templates for different violation types
 """
 
 from src.core.types import Severity, Violation

src/linters/file_placement/linter.py

@@ -6,22 +6,20 @@ Scope: Validate file organization against allow/deny patterns
 Overview: Implements file placement validation using regex patterns from JSON/YAML config.
     Orchestrates configuration loading, pattern validation, path resolution, rule checking,
     and violation creation through focused helper classes. Supports directory-specific rules,
-    global patterns, and generates helpful suggestions. Main linter class acts as coordinator.
+    global patterns, and generates helpful suggestions. Main linter class acts as coordinator
+    using composition pattern with specialized helper classes for configuration loading,
+    path resolution, pattern matching, and violation creation.
 
-Dependencies: src.core (base classes, types), pathlib, typing
+Dependencies: src.core (base classes, types), pathlib, typing, json, yaml modules
 
 Exports: FilePlacementLinter, FilePlacementRule
 
-Implementation: Composition pattern with helper classes for each responsibility
+Interfaces: lint_path(file_path) -> list[Violation], check_file_allowed(file_path) -> bool,
+    lint_directory(dir_path) -> list[Violation]
 
-SRP Exception: FilePlacementRule has 13 methods (exceeds max 8)
-    Justification: Framework adapter class that bridges BaseLintRule interface with
-    FilePlacementLinter implementation. Must handle multiple config sources (metadata vs file),
-    multiple config formats (wrapped vs unwrapped), project root detection with fallbacks,
-    and linter caching. This complexity is inherent to adapter pattern - splitting would
-    create unnecessary indirection between framework and implementation without improving
-    maintainability. All methods are focused on the single responsibility of integrating
-    file placement validation with the linting framework.
+Implementation: Composition pattern with helper classes for each responsibility
+    (ConfigLoader, PathResolver, PatternMatcher, PatternValidator, RuleChecker,
+    ViolationFactory)
 """
 
 import json

src/linters/magic_numbers/typescript_analyzer.py

@@ -26,6 +26,7 @@ from typing import Any
 
 from src.analyzers.typescript_base import TypeScriptBaseAnalyzer
 
+# dry: ignore-block - tree-sitter import pattern (common across TypeScript analyzers)
 try:
     from tree_sitter import Node
 

src/linters/nesting/typescript_analyzer.py

@@ -22,6 +22,7 @@ from typing import Any
 
 from src.analyzers.typescript_base import TypeScriptBaseAnalyzer
 
+# dry: ignore-block - tree-sitter import pattern (common across TypeScript analyzers)
 try:
     from tree_sitter import Node
 

src/linters/print_statements/__init__.py

@@ -0,0 +1,53 @@
+"""
+File: src/linters/print_statements/__init__.py
+
+Purpose: Print statements linter package exports and convenience functions
+
+Exports: PrintStatementRule class, PrintStatementConfig dataclass, lint() convenience function
+
+Depends: .linter for PrintStatementRule, .config for PrintStatementConfig
+
+Implements: lint(file_path, config) -> list[Violation] for simple linting operations
+
+Related: src/linters/magic_numbers/__init__.py, src/core/base.py
+
+Overview: Provides the public interface for the print statements linter package. Exports main
+    PrintStatementRule class for use by the orchestrator and PrintStatementConfig for configuration.
+    Includes lint() convenience function that provides a simple API for running the print statements
+    linter on a file without directly interacting with the orchestrator. This module serves as the
+    entry point for users of the print statements linter, hiding implementation details and exposing
+    only the essential components needed for linting operations.
+
+Usage: from src.linters.print_statements import PrintStatementRule, lint
+    violations = lint("path/to/file.py")
+
+Notes: Module-level exports with __all__ definition, convenience function wrapper
+"""
+
+from .config import PrintStatementConfig
+from .linter import PrintStatementRule
+
+__all__ = ["PrintStatementRule", "PrintStatementConfig", "lint"]
+
+
+def lint(file_path: str, config: dict | None = None) -> list:
+    """Convenience function for linting a file for print statements.
+
+    Args:
+        file_path: Path to the file to lint
+        config: Optional configuration dictionary
+
+    Returns:
+        List of violations found
+    """
+    from pathlib import Path
+
+    from src.orchestrator.core import FileLintContext
+
+    rule = PrintStatementRule()
+    context = FileLintContext(
+        path=Path(file_path),
+        lang="python",
+    )
+
+    return rule.check(context)

src/linters/print_statements/config.py

@@ -0,0 +1,78 @@
+"""
+Purpose: Configuration schema for print statements linter
+
+Scope: Print statements linter configuration for all supported languages
+
+Overview: Defines configuration schema for print statements linter. Provides PrintStatementConfig
+    dataclass with enabled flag, ignore patterns list, allow_in_scripts setting (default True to
+    allow print in __main__ blocks), and console_methods set (default includes log, warn, error,
+    debug, info) for TypeScript/JavaScript console method detection. Supports per-file and
+    per-directory config overrides through from_dict class method. Integrates with orchestrator's
+    configuration system to allow users to customize detection via .thailint.yaml configuration.
+
+Dependencies: dataclasses module for configuration structure, typing module for type hints
+
+Exports: PrintStatementConfig dataclass
+
+Interfaces: from_dict(config, language) -> PrintStatementConfig for configuration loading from dictionary
+
+Implementation: Dataclass with defaults matching common use cases and language-specific override support
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class PrintStatementConfig:
+    """Configuration for print statements linter."""
+
+    enabled: bool = True
+    ignore: list[str] = field(default_factory=list)
+    allow_in_scripts: bool = True
+    console_methods: set[str] = field(
+        default_factory=lambda: {"log", "warn", "error", "debug", "info"}
+    )
+
+    @classmethod
+    def from_dict(
+        cls, config: dict[str, Any], language: str | None = None
+    ) -> "PrintStatementConfig":
+        """Load configuration from dictionary with language-specific overrides.
+
+        Args:
+            config: Dictionary containing configuration values
+            language: Programming language (python, typescript, javascript)
+                for language-specific settings
+
+        Returns:
+            PrintStatementConfig instance with values from dictionary
+        """
+        # Get language-specific config if available
+        if language and language in config:
+            lang_config = config[language]
+            allow_in_scripts = lang_config.get(
+                "allow_in_scripts", config.get("allow_in_scripts", True)
+            )
+            console_methods = set(
+                lang_config.get(
+                    "console_methods",
+                    config.get("console_methods", ["log", "warn", "error", "debug", "info"]),
+                )
+            )
+        else:
+            allow_in_scripts = config.get("allow_in_scripts", True)
+            console_methods = set(
+                config.get("console_methods", ["log", "warn", "error", "debug", "info"])
+            )
+
+        ignore_patterns = config.get("ignore", [])
+        if not isinstance(ignore_patterns, list):
+            ignore_patterns = []
+
+        return cls(
+            enabled=config.get("enabled", True),
+            ignore=ignore_patterns,
+            allow_in_scripts=allow_in_scripts,
+            console_methods=console_methods,
+        )