thailint 0.1.0__py3-none-any.whl

src/config.py

@@ -0,0 +1,386 @@
+"""
+Purpose: Configuration management for CLI application with YAML/JSON support
+
+Scope: Load, validate, save, and merge configuration from multiple sources
+
+Overview: Provides comprehensive configuration management including loading from YAML and JSON files,
+    searching multiple default locations, merging configurations with clear precedence rules, schema
+    validation with helpful error messages, and safe persistence with atomic writes. Supports both
+    user-level and system-level configuration files with environment-specific overrides. Includes
+    default values for all settings to ensure the application works out of the box.
+
+Dependencies: PyYAML for YAML parsing, json for JSON parsing, pathlib for file operations, logging
+
+Exports: load_config(), save_config(), validate_config(), merge_configs(), ConfigError, DEFAULT_CONFIG
+
+Interfaces: Configuration dictionaries, Path objects for file locations, validation results
+
+Implementation: Multi-location config search, recursive dict merging, comprehensive validation
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigError(Exception):
+    """Configuration-related errors."""
+
+
+# Default configuration values
+DEFAULT_CONFIG: dict[str, Any] = {
+    "app_name": "{{PROJECT_NAME}}",
+    "version": "0.1.0",
+    "log_level": "INFO",
+    "output_format": "text",
+    "greeting": "Hello",
+    "max_retries": 3,
+    "timeout": 30,
+}
+
+# Configuration file search paths (in priority order)
+# First match wins
+CONFIG_LOCATIONS: list[Path] = [
+    Path.cwd() / "config.yaml",  # Current directory YAML
+    Path.cwd() / "config.json",  # Current directory JSON
+    Path.home() / ".config" / "{{PROJECT_NAME}}" / "config.yaml",  # User config YAML
+    Path.home() / ".config" / "{{PROJECT_NAME}}" / "config.json",  # User config JSON
+    Path("/etc/{{PROJECT_NAME}}/config.yaml"),  # System config YAML (Unix/Linux)
+]
+
+
+def _load_and_merge_config(config_path: Path) -> dict[str, Any]:
+    """Load config file and merge with defaults."""
+    config = DEFAULT_CONFIG.copy()
+    user_config = _load_config_file(config_path)
+    return merge_configs(config, user_config)
+
+
+def _validate_and_return_config(config: dict[str, Any], config_path: Path) -> dict[str, Any]:
+    """Validate config and return if valid, otherwise raise error."""
+    is_valid, errors = validate_config(config)
+    if not is_valid:
+        error_msg = "Configuration validation failed:\n" + "\n".join(f"  - {e}" for e in errors)
+        raise ConfigError(error_msg)
+    logger.info("Loaded config from: %s", config_path)
+    return config
+
+
+def _try_load_from_location(location: Path) -> dict[str, Any] | None:
+    """Try to load and validate config from a location."""
+    try:
+        config = _load_and_merge_config(location)
+        is_valid, errors = validate_config(config)
+        if not is_valid:
+            logger.warning("Invalid config at %s: %s", location, errors)
+            return None
+        logger.info("Loaded config from: %s", location)
+        return config
+    except ConfigError as e:
+        logger.warning("Failed to load config from %s: %s", location, e)
+        return None
+
+
+def _load_from_explicit_path(config_path: Path) -> dict[str, Any]:
+    """Load config from explicit path."""
+    if not config_path.exists():
+        logger.warning("Config file not found: %s, using defaults", config_path)
+        return DEFAULT_CONFIG.copy()
+    merged_config = _load_and_merge_config(config_path)
+    return _validate_and_return_config(merged_config, config_path)
+
+
+def _load_from_default_locations() -> dict[str, Any]:
+    """Load config from default locations."""
+    for location in CONFIG_LOCATIONS:
+        if not location.exists():
+            continue
+        loaded_config = _try_load_from_location(location)
+        if loaded_config:
+            return loaded_config
+    logger.info("No config file found, using defaults")
+    return DEFAULT_CONFIG.copy()
+
+
+def load_config(config_path: Path | None = None) -> dict[str, Any]:
+    """
+    Load configuration with fallback to defaults.
+
+    Searches default locations if no explicit path provided. Validates
+    configuration after loading and merges with defaults to ensure all
+    keys are present.
+
+    Args:
+        config_path: Explicit path to config file. If None, searches
+                     CONFIG_LOCATIONS in priority order.
+
+    Returns:
+        Configuration dictionary with defaults merged in.
+
+    Raises:
+        ConfigError: If config file exists but cannot be parsed or is invalid.
+
+    Example:
+        >>> config = load_config()
+        >>> config = load_config(Path('custom-config.yaml'))
+    """
+    if config_path:
+        return _load_from_explicit_path(config_path)
+    return _load_from_default_locations()
+
+
+def _parse_yaml_file(f, path: Path) -> dict[str, Any]:
+    """Parse YAML file and return data."""
+    try:
+        data = yaml.safe_load(f)
+        return data if data is not None else {}
+    except yaml.YAMLError as e:
+        raise ConfigError(f"Invalid YAML in {path}: {e}") from e
+
+
+def _parse_json_file(f, path: Path) -> dict[str, Any]:
+    """Parse JSON file and return data."""
+    try:
+        return json.load(f)
+    except json.JSONDecodeError as e:
+        raise ConfigError(f"Invalid JSON in {path}: {e}") from e
+
+
+def _load_config_file(path: Path) -> dict[str, Any]:
+    """
+    Load config from YAML or JSON file based on extension.
+
+    Args:
+        path: Path to configuration file.
+
+    Returns:
+        Configuration dictionary.
+
+    Raises:
+        ConfigError: If file cannot be parsed.
+    """
+    try:
+        return _parse_config_by_extension(path)
+    except ConfigError:
+        raise
+    except Exception as e:
+        raise ConfigError(f"Failed to load config from {path}: {e}") from e
+
+
+def _parse_config_by_extension(path: Path) -> dict[str, Any]:
+    """Parse config file based on its extension."""
+    with path.open() as f:
+        if path.suffix in [".yaml", ".yml"]:
+            return _parse_yaml_file(f, path)
+        if path.suffix == ".json":
+            return _parse_json_file(f, path)
+        raise ConfigError(f"Unsupported config format: {path.suffix}")
+
+
+def _validate_before_save(config: dict[str, Any]) -> None:
+    """Validate config before saving."""
+    is_valid, errors = validate_config(config)
+    if not is_valid:
+        error_msg = "Cannot save invalid configuration:\n" + "\n".join(f"  - {e}" for e in errors)
+        raise ConfigError(error_msg)
+
+
+def _write_config_file(config: dict[str, Any], path: Path) -> None:
+    """Write config to file based on extension."""
+    if path.suffix in [".yaml", ".yml"]:
+        _write_yaml_config(config, path)
+    elif path.suffix == ".json":
+        _write_json_config(config, path)
+    else:
+        raise ConfigError(f"Unsupported config format: {path.suffix}")
+
+
+def _write_yaml_config(config: dict[str, Any], path: Path) -> None:
+    """Write config as YAML."""
+    with path.open("w") as f:
+        yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+
+
+def _write_json_config(config: dict[str, Any], path: Path) -> None:
+    """Write config as JSON."""
+    with path.open("w") as f:
+        json.dump(config, f, indent=2, sort_keys=False)
+
+
+def save_config(config: dict[str, Any], config_path: Path | None = None):
+    """
+    Save configuration to file.
+
+    Creates parent directory if it doesn't exist. Format determined by
+    file extension. Validates configuration before saving.
+
+    Args:
+        config: Configuration dictionary to save.
+        config_path: Path to save config. If None, uses first CONFIG_LOCATIONS entry.
+
+    Raises:
+        ConfigError: If config cannot be saved or is invalid.
+
+    Example:
+        >>> save_config({'log_level': 'DEBUG'})
+        >>> save_config({'log_level': 'DEBUG'}, Path('my-config.yaml'))
+    """
+    path = config_path or CONFIG_LOCATIONS[0]
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _validate_before_save(config)
+    _write_and_log_config(config, path)
+
+
+def _write_and_log_config(config: dict[str, Any], path: Path) -> None:
+    """Write config file and log success."""
+    try:
+        _write_config_file(config, path)
+        logger.info("Saved config to: %s", path)
+    except ConfigError:
+        raise
+    except Exception as e:
+        raise ConfigError(f"Failed to save config to {path}: {e}") from e
+
+
+def _validate_required_keys(config: dict[str, Any], errors: list[str]) -> None:
+    """Validate that all required keys are present in config."""
+    required_keys = ["app_name", "log_level"]
+    for key in required_keys:
+        if key not in config:
+            errors.append(f"Missing required key: {key}")
+
+
+def _validate_log_level(config: dict[str, Any], errors: list[str]) -> None:
+    """Validate log level is a valid value."""
+    valid_log_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+    if "log_level" in config:
+        if config["log_level"] not in valid_log_levels:
+            errors.append(
+                f"Invalid log_level: {config['log_level']}. "
+                f"Must be one of: {', '.join(valid_log_levels)}"
+            )
+
+
+def _validate_output_format(config: dict[str, Any], errors: list[str]) -> None:
+    """Validate output format is a valid value."""
+    valid_formats = ["text", "json", "yaml"]
+    if "output_format" in config:
+        if config["output_format"] not in valid_formats:
+            errors.append(
+                f"Invalid output_format: {config['output_format']}. "
+                f"Must be one of: {', '.join(valid_formats)}"
+            )
+
+
+def _validate_max_retries(config: dict[str, Any], errors: list[str]) -> None:
+    """Validate max_retries configuration value."""
+    if "max_retries" in config:
+        if not isinstance(config["max_retries"], int) or config["max_retries"] < 0:
+            errors.append("max_retries must be a non-negative integer")
+
+
+def _validate_timeout(config: dict[str, Any], errors: list[str]) -> None:
+    """Validate timeout configuration value."""
+    if "timeout" in config:
+        if not isinstance(config["timeout"], (int, float)) or config["timeout"] <= 0:
+            errors.append("timeout must be a positive number")
+
+
+def _validate_numeric_values(config: dict[str, Any], errors: list[str]) -> None:
+    """Validate numeric configuration values."""
+    _validate_max_retries(config, errors)
+    _validate_timeout(config, errors)
+
+
+def _validate_string_values(config: dict[str, Any], errors: list[str]) -> None:
+    """Validate string configuration values."""
+    if "app_name" in config:
+        if not isinstance(config["app_name"], str) or not config["app_name"].strip():
+            errors.append("app_name must be a non-empty string")
+
+
+def validate_config(config: dict[str, Any]) -> tuple[bool, list[str]]:
+    """
+    Validate configuration schema and values.
+
+    Checks for required keys, validates value types and ranges, and ensures
+    enum values are within allowed sets.
+
+    Args:
+        config: Configuration dictionary to validate.
+
+    Returns:
+        Tuple of (is_valid, error_messages). is_valid is True if no errors,
+        error_messages is list of validation error strings.
+
+    Example:
+        >>> is_valid, errors = validate_config(config)
+        >>> if not is_valid:
+        ...     for error in errors:
+        ...         print(f"Error: {error}")
+    """
+    errors: list[str] = []
+
+    _validate_required_keys(config, errors)
+    _validate_log_level(config, errors)
+    _validate_output_format(config, errors)
+    _validate_numeric_values(config, errors)
+    _validate_string_values(config, errors)
+
+    return len(errors) == 0, errors
+
+
+def merge_configs(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """
+    Merge two configurations, with override taking precedence.
+
+    Recursively merges nested dictionaries. Override values completely
+    replace base values for non-dict types.
+
+    Args:
+        base: Base configuration.
+        override: Override configuration (takes precedence).
+
+    Returns:
+        Merged configuration dictionary.
+
+    Example:
+        >>> base = {'a': 1, 'b': {'c': 2, 'd': 3}}
+        >>> override = {'b': {'d': 4}, 'e': 5}
+        >>> merged = merge_configs(base, override)
+        >>> # Result: {'a': 1, 'b': {'c': 2, 'd': 4}, 'e': 5}
+    """
+    result = base.copy()
+
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            # Recursively merge nested dicts
+            result[key] = merge_configs(result[key], value)
+        else:
+            # Override value
+            result[key] = value
+
+    return result
+
+
+def get_config_path() -> Path | None:
+    """
+    Find the first existing config file in CONFIG_LOCATIONS.
+
+    Returns:
+        Path to config file if found, None otherwise.
+
+    Example:
+        >>> path = get_config_path()
+        >>> if path:
+        ...     print(f"Config at: {path}")
+    """
+    for location in CONFIG_LOCATIONS:
+        if location.exists():
+            return location
+    return None

src/core/__init__.py

@@ -0,0 +1,17 @@
+"""Core framework components for thai-lint.
+
+This package contains the foundational abstractions and types that
+power the plugin architecture.
+"""
+
+from .base import BaseLintContext, BaseLintRule
+from .registry import RuleRegistry
+from .types import Severity, Violation
+
+__all__ = [
+    "BaseLintContext",
+    "BaseLintRule",
+    "RuleRegistry",
+    "Severity",
+    "Violation",
+]

src/core/base.py

@@ -0,0 +1,122 @@
+"""
+Purpose: Abstract base classes defining the core plugin architecture interfaces
+
+Scope: Foundation interfaces for all linting rules, contexts, and plugin implementations
+
+Overview: Establishes the contract that all linting plugins must follow through abstract base
+    classes, enabling the plugin architecture that allows dynamic rule discovery and execution.
+    Defines BaseLintRule which all concrete linting rules inherit from, specifying required
+    properties (rule_id, rule_name, description) and the check() method for violation detection.
+    Provides BaseLintContext as the interface for accessing file information during analysis,
+    exposing file_path, file_content, and language properties. These abstractions enable the
+    rule registry to discover and instantiate rules dynamically without tight coupling, supporting
+    the extensible plugin system where new rules can be added by simply placing them in the
+    appropriate directory structure.
+
+Dependencies: abc for abstract base class support, pathlib for Path types, Violation from types
+
+Exports: BaseLintRule (abstract rule interface), BaseLintContext (abstract context interface)
+
+Interfaces: BaseLintRule.check(context) -> list[Violation], BaseLintContext properties
+    (file_path, file_content, language), all abstract methods must be implemented by subclasses
+
+Implementation: ABC-based interface definitions with @abstractmethod decorators, property-based
+    API for rule metadata, context-based execution pattern for rule checking
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from .types import Violation
+
+
+class BaseLintContext(ABC):
+    """Base class for lint context.
+
+    A lint context provides all the information a rule needs to analyze
+    a file, including the file path, content, and language.
+    """
+
+    @property
+    @abstractmethod
+    def file_path(self) -> Path | None:
+        """Get the file path being analyzed.
+
+        Returns:
+            Path to the file, or None if analyzing content without a file.
+        """
+        raise NotImplementedError("Subclasses must implement file_path")
+
+    @property
+    @abstractmethod
+    def file_content(self) -> str | None:
+        """Get the file content being analyzed.
+
+        Returns:
+            Content of the file as a string, or None if file not available.
+        """
+        raise NotImplementedError("Subclasses must implement file_content")
+
+    @property
+    @abstractmethod
+    def language(self) -> str:
+        """Get the programming language of the file.
+
+        Returns:
+            Language identifier (e.g., 'python', 'javascript', 'go').
+        """
+        raise NotImplementedError("Subclasses must implement language")
+
+
+class BaseLintRule(ABC):
+    """Base class for all linting rules.
+
+    All concrete linting rules must inherit from this class and implement
+    all abstract methods and properties. Rules are discovered and registered
+    automatically by the rule registry.
+    """
+
+    @property
+    @abstractmethod
+    def rule_id(self) -> str:
+        """Unique identifier for this rule.
+
+        The rule ID should follow the format 'category.rule-name', e.g.,
+        'file-placement.deny-pattern' or 'naming.class-pascal-case'.
+
+        Returns:
+            Unique rule identifier.
+        """
+        raise NotImplementedError("Subclasses must implement rule_id")
+
+    @property
+    @abstractmethod
+    def rule_name(self) -> str:
+        """Human-readable name for this rule.
+
+        Returns:
+            Descriptive name for display to users.
+        """
+        raise NotImplementedError("Subclasses must implement rule_name")
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Description of what this rule checks.
+
+        Returns:
+            Detailed description of the rule's purpose and behavior.
+        """
+        raise NotImplementedError("Subclasses must implement description")
+
+    @abstractmethod
+    def check(self, context: BaseLintContext) -> list[Violation]:
+        """Check for violations in the given context.
+
+        Args:
+            context: The lint context containing file information.
+
+        Returns:
+            List of violations found. Empty list if no violations.
+        """
+        raise NotImplementedError("Subclasses must implement check")

src/core/registry.py

@@ -0,0 +1,170 @@
+"""
+Purpose: Rule registry with automatic plugin discovery and registration
+
+Scope: Dynamic rule management and discovery across all linter plugin packages
+
+Overview: Implements the plugin discovery system that enables the extensible architecture by
+    automatically finding and registering linting rules from specified packages without requiring
+    explicit registration code. The RuleRegistry maintains a collection of discovered rules indexed
+    by rule_id, providing methods to register individual rules, retrieve rules by identifier, and
+    list all available rules. Auto-discovery works by scanning Python packages for classes that
+    inherit from BaseLintRule, filtering out abstract base classes, instantiating concrete rule
+    classes, and registering them for use by the orchestrator. This enables developers to add new
+    rules simply by creating a class in the appropriate package structure without modifying any
+    framework code. The registry handles import errors gracefully and supports both package-level
+    and module-level discovery patterns.
+
+Dependencies: importlib for dynamic module loading, inspect for class introspection,
+    pkgutil for package traversal, BaseLintRule for type checking
+
+Exports: RuleRegistry class with register(), get(), list_all(), and discover_rules() methods
+
+Interfaces: register(rule: BaseLintRule) -> None, get(rule_id: str) -> BaseLintRule | None,
+    list_all() -> list[BaseLintRule], discover_rules(package_path: str) -> int
+
+Implementation: Package scanning with pkgutil.iter_modules(), class introspection with inspect,
+    subclass detection for BaseLintRule, abstract class filtering, graceful error handling for
+    failed imports, duplicate rule_id validation
+"""
+
+import importlib
+import inspect
+import pkgutil
+from typing import Any
+
+from .base import BaseLintRule
+
+
+class RuleRegistry:
+    """Registry for linting rules with auto-discovery.
+
+    The registry maintains a collection of registered rules and provides
+    methods to register, retrieve, and discover rules dynamically.
+    """
+
+    def __init__(self) -> None:
+        """Initialize empty registry."""
+        self._rules: dict[str, BaseLintRule] = {}
+
+    def register(self, rule: BaseLintRule) -> None:
+        """Register a new rule.
+
+        Args:
+            rule: The rule instance to register.
+
+        Raises:
+            ValueError: If a rule with the same ID is already registered.
+        """
+        rule_id = rule.rule_id
+
+        if rule_id in self._rules:
+            raise ValueError(f"Rule {rule_id} already registered")
+
+        self._rules[rule_id] = rule
+
+    def get(self, rule_id: str) -> BaseLintRule | None:
+        """Get a rule by ID.
+
+        Args:
+            rule_id: The unique identifier of the rule.
+
+        Returns:
+            The rule instance if found, None otherwise.
+        """
+        return self._rules.get(rule_id)
+
+    def list_all(self) -> list[BaseLintRule]:
+        """Get all registered rules.
+
+        Returns:
+            List of all registered rule instances.
+        """
+        return list(self._rules.values())
+
+    def discover_rules(self, package_path: str) -> int:
+        """Discover and register rules from a package.
+
+        This method automatically discovers all concrete BaseLintRule
+        subclasses in the specified package and registers them.
+
+        Args:
+            package_path: Python package path (e.g., 'src.linters').
+
+        Returns:
+            Number of rules discovered and registered.
+        """
+        try:
+            package = importlib.import_module(package_path)
+        except ImportError:
+            return 0
+
+        if not hasattr(package, "__path__"):
+            return self._discover_from_module(package_path)
+
+        return self._discover_from_package_modules(package_path, package)
+
+    def _discover_from_package_modules(self, package_path: str, package: Any) -> int:
+        """Discover rules from all modules in a package."""
+        discovered_count = 0
+        for _, module_name, _ in pkgutil.iter_modules(package.__path__):
+            full_module_name = f"{package_path}.{module_name}"
+            discovered_count += self._try_discover_from_module(full_module_name)
+        return discovered_count
+
+    def _try_discover_from_module(self, module_name: str) -> int:
+        """Try to discover rules from a module, return 0 on error."""
+        try:
+            return self._discover_from_module(module_name)
+        except (ImportError, AttributeError):
+            return 0
+
+    def _discover_from_module(self, module_path: str) -> int:
+        """Discover rules from a specific module.
+
+        Args:
+            module_path: Full module path to search.
+
+        Returns:
+            Number of rules discovered from this module.
+        """
+        try:
+            module = importlib.import_module(module_path)
+        except (ImportError, AttributeError):
+            return 0
+
+        return self._register_rules_from_module(module)
+
+    def _register_rules_from_module(self, module: Any) -> int:
+        """Register all rule classes from a module."""
+        discovered_count = 0
+        for _name, obj in inspect.getmembers(module):
+            if not self._is_rule_class(obj):
+                continue
+            if self._try_register_rule_class(obj):
+                discovered_count += 1
+        return discovered_count
+
+    def _try_register_rule_class(self, rule_class: Any) -> bool:
+        """Try to instantiate and register a rule class."""
+        try:
+            rule_instance = rule_class()
+            self.register(rule_instance)
+            return True
+        except (TypeError, AttributeError, ValueError):
+            return False
+
+    def _is_rule_class(self, obj: Any) -> bool:
+        """Check if an object is a valid rule class.
+
+        Args:
+            obj: Object to check.
+
+        Returns:
+            True if obj is a concrete BaseLintRule subclass.
+        """
+        return (
+            inspect.isclass(obj)
+            and issubclass(obj, BaseLintRule)
+            and obj is not BaseLintRule  # Don't instantiate the base class
+            and not inspect.isabstract(obj)  # Don't instantiate abstract classes
+        )