thailint 0.5.0__py3-none-any.whl → 0.15.3__py3-none-any.whl

src/linters/stringly_typed/config.py

@@ -0,0 +1,189 @@
+"""
+Purpose: Configuration dataclass for stringly-typed linter
+
+Scope: Define configurable options for stringly-typed pattern detection
+
+Overview: Provides StringlyTypedConfig for customizing linter behavior including minimum
+    occurrences required to flag patterns, enum value thresholds, cross-file detection
+    settings, and ignore patterns. The stringly-typed linter detects code patterns where
+    plain strings are used instead of proper enums or typed alternatives. Integrates with
+    the orchestrator's configuration system to allow users to customize detection via
+    .thailint.yaml configuration files. Follows the same configuration pattern as other
+    thai-lint linters.
+
+Dependencies: dataclasses, typing
+
+Exports: StringlyTypedConfig dataclass, default constants
+
+Interfaces: StringlyTypedConfig.from_dict() class method for configuration loading
+
+Implementation: Dataclass with sensible defaults, validation in __post_init__, and config
+    loading from dictionary with language-specific override support
+
+Suppressions:
+    - too-many-instance-attributes: Configuration dataclass with cohesive detection settings
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# Default thresholds
+DEFAULT_MIN_OCCURRENCES = 2
+DEFAULT_MIN_VALUES_FOR_ENUM = 2
+DEFAULT_MAX_VALUES_FOR_ENUM = 6
+
+# Default ignore patterns - test directories are excluded by default
+# because test fixtures commonly use string literals for mocking
+DEFAULT_IGNORE_PATTERNS: list[str] = [
+    "**/tests/**",
+    "**/test/**",
+    "**/*_test.py",
+    "**/*_test.ts",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    "**/*.stories.ts",
+    "**/*.stories.tsx",
+    "**/conftest.py",
+    "**/fixtures/**",
+]
+
+
+@dataclass
+class StringlyTypedConfig:  # pylint: disable=too-many-instance-attributes
+    """Configuration for stringly-typed linter.
+
+    Note: Pylint too-many-instance-attributes disabled. This is a configuration
+    dataclass serving as a data container for related stringly-typed linter settings.
+    All 8 attributes are cohesively related (detection thresholds, filtering options,
+    cross-file settings, exclusion patterns). Splitting would reduce cohesion and make
+    configuration loading more complex without meaningful benefit. This follows the
+    established pattern in DRYConfig.
+    """
+
+    enabled: bool = True
+    """Whether the linter is enabled."""
+
+    min_occurrences: int = DEFAULT_MIN_OCCURRENCES
+    """Minimum number of cross-file occurrences required to flag a violation."""
+
+    min_values_for_enum: int = DEFAULT_MIN_VALUES_FOR_ENUM
+    """Minimum number of unique string values to suggest an enum."""
+
+    max_values_for_enum: int = DEFAULT_MAX_VALUES_FOR_ENUM
+    """Maximum number of unique string values to suggest an enum (above this, not enum-worthy)."""
+
+    require_cross_file: bool = True
+    """Whether to require cross-file occurrences to flag violations."""
+
+    ignore: list[str] = field(default_factory=list)
+    """File patterns to ignore. Defaults merged with test directories in from_dict."""
+
+    allowed_string_sets: list[list[str]] = field(default_factory=list)
+    """String sets that are allowed and should not be flagged."""
+
+    exclude_variables: list[str] = field(default_factory=list)
+    """Variable names to exclude from detection."""
+
+    def __post_init__(self) -> None:
+        """Validate configuration values."""
+        if self.min_occurrences < 1:
+            raise ValueError(f"min_occurrences must be at least 1, got {self.min_occurrences}")
+        if self.min_values_for_enum < 2:
+            raise ValueError(
+                f"min_values_for_enum must be at least 2, got {self.min_values_for_enum}"
+            )
+        if self.max_values_for_enum < self.min_values_for_enum:
+            raise ValueError(
+                f"max_values_for_enum ({self.max_values_for_enum}) must be >= "
+                f"min_values_for_enum ({self.min_values_for_enum})"
+            )
+
+    @classmethod
+    def from_dict(
+        cls, config: dict[str, Any], language: str | None = None
+    ) -> "StringlyTypedConfig":
+        """Load configuration from dictionary.
+
+        Args:
+            config: Dictionary containing configuration values
+            language: Programming language for language-specific overrides
+
+        Returns:
+            StringlyTypedConfig instance with values from dictionary
+        """
+        # Check for language-specific overrides first
+        if language and language in config:
+            lang_config = config[language]
+            return cls._from_merged_config(config, lang_config)
+
+        return cls._from_base_config(config)
+
+    @classmethod
+    def _from_base_config(cls, config: dict[str, Any]) -> "StringlyTypedConfig":
+        """Create config from base configuration dictionary.
+
+        Args:
+            config: Base configuration dictionary
+
+        Returns:
+            StringlyTypedConfig instance
+        """
+        # Merge user ignore patterns with defaults
+        user_ignore = config.get("ignore", [])
+        merged_ignore = DEFAULT_IGNORE_PATTERNS.copy() + user_ignore
+
+        return cls(
+            enabled=config.get("enabled", True),
+            min_occurrences=config.get("min_occurrences", DEFAULT_MIN_OCCURRENCES),
+            min_values_for_enum=config.get("min_values_for_enum", DEFAULT_MIN_VALUES_FOR_ENUM),
+            max_values_for_enum=config.get("max_values_for_enum", DEFAULT_MAX_VALUES_FOR_ENUM),
+            require_cross_file=config.get("require_cross_file", True),
+            ignore=merged_ignore,
+            allowed_string_sets=config.get("allowed_string_sets", []),
+            exclude_variables=config.get("exclude_variables", []),
+        )
+
+    @classmethod
+    def _from_merged_config(
+        cls, base_config: dict[str, Any], lang_config: dict[str, Any]
+    ) -> "StringlyTypedConfig":
+        """Create config with language-specific overrides merged.
+
+        Args:
+            base_config: Base configuration dictionary
+            lang_config: Language-specific configuration overrides
+
+        Returns:
+            StringlyTypedConfig instance with merged values
+        """
+        # Merge user ignore patterns with defaults
+        user_ignore = lang_config.get("ignore", base_config.get("ignore", []))
+        merged_ignore = DEFAULT_IGNORE_PATTERNS.copy() + user_ignore
+
+        return cls(
+            enabled=lang_config.get("enabled", base_config.get("enabled", True)),
+            min_occurrences=lang_config.get(
+                "min_occurrences",
+                base_config.get("min_occurrences", DEFAULT_MIN_OCCURRENCES),
+            ),
+            min_values_for_enum=lang_config.get(
+                "min_values_for_enum",
+                base_config.get("min_values_for_enum", DEFAULT_MIN_VALUES_FOR_ENUM),
+            ),
+            max_values_for_enum=lang_config.get(
+                "max_values_for_enum",
+                base_config.get("max_values_for_enum", DEFAULT_MAX_VALUES_FOR_ENUM),
+            ),
+            require_cross_file=lang_config.get(
+                "require_cross_file", base_config.get("require_cross_file", True)
+            ),
+            ignore=merged_ignore,
+            allowed_string_sets=lang_config.get(
+                "allowed_string_sets", base_config.get("allowed_string_sets", [])
+            ),
+            exclude_variables=lang_config.get(
+                "exclude_variables", base_config.get("exclude_variables", [])
+            ),
+        )

src/linters/stringly_typed/context_filter.py

@@ -0,0 +1,451 @@
+"""
+Purpose: Context-aware filtering for stringly-typed function call violations
+
+Scope: Filter out false positive function call patterns based on function names and contexts
+
+Overview: Implements a blocklist-based filtering approach to reduce false positives in the
+    stringly-typed linter's function call detection. Excludes known false positive patterns
+    including dictionary access methods, string processing functions, logging calls, framework
+    validators, and external API functions. Uses function name pattern matching and parameter
+    position filtering to achieve <5% false positive rate.
+
+Dependencies: re module for pattern matching
+
+Exports: should_include, are_all_values_excluded functions
+
+Interfaces: should_include(function_name, param_index, string_values) -> bool,
+    are_all_values_excluded(unique_values) -> bool
+
+Implementation: Blocklist-based filtering with function name patterns, parameter position rules,
+    and string value pattern detection
+"""
+
+import re
+
+# Function name suffixes that always indicate false positives
+_EXCLUDED_FUNCTION_SUFFIXES: tuple[str, ...] = (
+    # Exception constructors - error messages are inherently unique strings
+    "Error",
+    "Exception",
+    "Warning",
+)
+
+# Function name patterns to always exclude (case-insensitive suffix/contains match)
+_EXCLUDED_FUNCTION_PATTERNS: tuple[str, ...] = (
+    # Dictionary/object access - these are metadata access, not domain values
+    ".get",
+    ".set",
+    ".pop",
+    ".setdefault",
+    ".update",
+    # List/collection operations
+    ".append",
+    ".extend",
+    ".insert",
+    ".add",
+    ".remove",
+    ".push",
+    ".set",
+    ".has",
+    "hasItem",
+    "push",
+    # String processing - delimiters and format strings
+    # Note: both .method and method forms to catch both method calls and standalone functions
+    ".split",
+    "split",
+    ".rsplit",
+    ".replace",
+    "replace",
+    ".strip",
+    ".rstrip",
+    ".lstrip",
+    ".startswith",
+    "startswith",
+    ".startsWith",
+    "startsWith",
+    ".endswith",
+    "endswith",
+    ".endsWith",
+    "endsWith",
+    ".includes",
+    "includes",
+    ".indexOf",
+    "indexOf",
+    ".lastIndexOf",
+    ".match",
+    ".search",
+    ".format",
+    ".join",
+    "join",
+    ".encode",
+    ".decode",
+    ".lower",
+    ".upper",
+    ".trim",
+    ".trimStart",
+    ".trimEnd",
+    ".padStart",
+    ".padEnd",
+    "strftime",
+    "strptime",
+    # Logging and output - human-readable messages
+    "logger.debug",
+    "logger.info",
+    "logger.warning",
+    "logger.error",
+    "logger.critical",
+    "logger.exception",
+    "logging.debug",
+    "logging.info",
+    "logging.warning",
+    "logging.error",
+    "print",
+    "echo",
+    "console.print",
+    "console.log",
+    "typer.echo",
+    "click.echo",
+    # Regex - pattern strings
+    "re.sub",
+    "re.match",
+    "re.search",
+    "re.compile",
+    "re.findall",
+    "re.split",
+    # Environment variables
+    "os.environ.get",
+    "os.getenv",
+    "environ.get",
+    "getenv",
+    # File operations
+    "open",
+    "Path",
+    # Framework validators - must be strings matching field names
+    "field_validator",
+    "validator",
+    "computed_field",
+    # Type system - required Python syntax
+    "TypeVar",
+    "Generic",
+    "cast",
+    # Numeric - string representations of numbers
+    "Decimal",
+    "int",
+    "float",
+    # Exception constructors - error messages
+    "ValueError",
+    "TypeError",
+    "KeyError",
+    "AttributeError",
+    "RuntimeError",
+    "Exception",
+    "raise",
+    "APIException",
+    "HTTPException",
+    "ValidationError",
+    # CLI frameworks - short flags, option names, prompts
+    "typer.Option",
+    "typer.Argument",
+    "typer.confirm",
+    "typer.prompt",
+    "click.option",
+    "click.argument",
+    "click.confirm",
+    "click.prompt",
+    ".command",
+    # HTTP/API clients - external protocol strings
+    "requests.get",
+    "requests.post",
+    "requests.put",
+    "requests.delete",
+    "requests.patch",
+    "httpx.get",
+    "httpx.post",
+    "axios.get",
+    "axios.post",
+    "axios.put",
+    "axios.delete",
+    "axios.patch",
+    "client.get",
+    "client.post",
+    "client.put",
+    "client.delete",
+    "session.client",
+    "session.resource",
+    "_request",
+    # Browser/DOM APIs - CSS selectors and data URLs
+    "document.querySelector",
+    "document.querySelectorAll",
+    "document.getElementById",
+    "document.getElementsByClassName",
+    "canvas.toDataURL",
+    "canvas.toBlob",
+    "createElement",
+    "getAttribute",
+    "setAttribute",
+    "addEventListener",
+    "removeEventListener",
+    "localStorage.getItem",
+    "localStorage.setItem",
+    "sessionStorage.getItem",
+    "sessionStorage.setItem",
+    "window.confirm",
+    "window.alert",
+    "window.prompt",
+    "confirm",
+    "alert",
+    "prompt",
+    # React hooks - internal state identifiers
+    "useRef",
+    "useState",
+    "useCallback",
+    "useMemo",
+    # AWS SDK - service names and API parameters
+    "boto3.client",
+    "boto3.resource",
+    "generate_presigned_url",
+    # AWS CDK - infrastructure as code (broad patterns)
+    "s3.",
+    "ec2.",
+    "logs.",
+    "route53.",
+    "lambda_.",
+    "_lambda.",
+    "tasks.",
+    "iam.",
+    "dynamodb.",
+    "sqs.",
+    "sns.",
+    "apigateway.",
+    "cloudfront.",
+    "cdk.",
+    "sfn.",
+    "acm.",
+    "cloudwatch.",
+    "secretsmanager.",
+    "cr.",
+    "pipes.",
+    "rds.",
+    "elasticache.",
+    "from_lookup",
+    "generate_resource_name",
+    "CfnPipe",
+    "CfnOutput",
+    # FastAPI/Starlette routing
+    "router.get",
+    "router.post",
+    "router.put",
+    "router.delete",
+    "router.patch",
+    "app.get",
+    "app.post",
+    "app.put",
+    "app.delete",
+    "@app.",
+    "@router.",
+    # DynamoDB attribute access
+    "Key",
+    "Attr",
+    "ConditionExpression",
+    # Azure CLI - external tool invocation
+    "az",
+    # Database/ORM - schema definitions
+    "op.add_column",
+    "op.drop_column",
+    "op.create_table",
+    "op.alter_column",
+    "sa.Column",
+    "sa.PrimaryKeyConstraint",
+    "sa.ForeignKeyConstraint",
+    "Column",
+    "relationship",
+    "postgresql.ENUM",
+    "ENUM",
+    # Python built-ins
+    "getattr",
+    "setattr",
+    "hasattr",
+    "delattr",
+    "isinstance",
+    "issubclass",
+    # Pydantic/dataclass fields
+    "Field",
+    "PrivateAttr",
+    # UI frameworks - display text
+    "QLabel",
+    "QPushButton",
+    "QMessageBox",
+    "QCheckBox",
+    "setWindowTitle",
+    "setText",
+    "setToolTip",
+    "setPlaceholderText",
+    "setStatusTip",
+    "Static",
+    "Label",
+    "Button",
+    # Table/grid display - formatting
+    "table.add_row",
+    "add_row",
+    "add_column",
+    "Table",
+    "Panel",
+    "Console",
+    # Testing - mocks and fixtures
+    "monkeypatch.setattr",
+    "patch",
+    "Mock",
+    "MagicMock",
+    "PropertyMock",
+    # String parsing methods - internal message processing
+    ".index",
+    ".find",
+    ".rfind",
+    ".rindex",
+    # Storybook - action handlers
+    "action",
+    "fn",
+    # React state setters - UI state names
+    "setMessage",
+    "setError",
+    "setLoading",
+    "setStatus",
+    "setText",
+    # API clients - external endpoints
+    "API.",
+    "api.",
+    # CSS/styling
+    "setStyleSheet",
+    "add_class",
+    "remove_class",
+    # JSON/serialization - output identifiers
+    "_output",
+    "json.dumps",
+    "json.loads",
+    # Health checks - framework pattern
+    "register_health_check",
+    # Config management - dynamic config keys
+    "ensure_config_section",
+    "set_config_value",
+    "get_config_value",
+)
+
+# Function names where second parameter (index 1) should be excluded
+# These are typically default values, not keys
+_EXCLUDE_PARAM_INDEX_1: tuple[str, ...] = (
+    ".get",
+    "os.environ.get",
+    "environ.get",
+    "getattr",
+    "os.getenv",
+    "getenv",
+)
+
+# String value patterns that indicate false positives
+_EXCLUDED_VALUE_PATTERNS: tuple[re.Pattern[str], ...] = (
+    # strftime format strings
+    re.compile(r"^%[A-Za-z%-]+$"),
+    # Single character delimiters
+    re.compile(r"^[\n\t\r,;:|/\\.\-_]$"),
+    # Empty string or whitespace only
+    re.compile(r"^\s*$"),
+    # HTTP methods (external protocol)
+    re.compile(r"^(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)$"),
+    # Numeric strings (should use Decimal or int)
+    re.compile(r"^-?\d+\.?\d*$"),
+    # Short CLI flags
+    re.compile(r"^-[a-zA-Z]$"),
+    # CSS/Rich markup
+    re.compile(r"^\[/?[a-z]+\]"),
+    # File modes (only multi-char modes to avoid false positives on single letters)
+    re.compile(r"^[rwa][bt]\+?$|^[rwa]\+$"),
+)
+
+
+def should_include(
+    function_name: str,
+    param_index: int,
+    unique_values: set[str],
+) -> bool:
+    """Determine if a function call pattern should be included in violations.
+
+    Args:
+        function_name: Name of the function being called
+        param_index: Index of the parameter (0-based)
+        unique_values: Set of unique string values passed to this parameter
+
+    Returns:
+        True if this pattern should generate a violation, False to filter it out
+    """
+    # Check function name patterns
+    if _is_excluded_function(function_name):
+        return False
+
+    # Check parameter position for specific functions
+    if _is_excluded_param_position(function_name, param_index):
+        return False
+
+    # Check if all values match excluded patterns
+    if _all_values_excluded(unique_values):
+        return False
+
+    return True
+
+
+def are_all_values_excluded(unique_values: set[str]) -> bool:
+    """Check if all values match excluded patterns (numeric strings, delimiters, etc.).
+
+    Public interface for value-based filtering used by violation generator.
+
+    Args:
+        unique_values: Set of unique string values to check
+
+    Returns:
+        True if all values match excluded patterns, False otherwise
+    """
+    return _all_values_excluded(unique_values)
+
+
+def _is_excluded_function(function_name: str) -> bool:
+    """Check if function name matches any excluded pattern."""
+    # Check suffix patterns (e.g., *Error, *Exception)
+    if _matches_suffix(function_name):
+        return True
+    return _matches_pattern(function_name.lower())
+
+
+def _matches_suffix(function_name: str) -> bool:
+    """Check if function name ends with an excluded suffix."""
+    return any(function_name.endswith(s) for s in _EXCLUDED_FUNCTION_SUFFIXES)
+
+
+def _matches_pattern(func_lower: str) -> bool:
+    """Check if function name matches any excluded pattern."""
+    return any(
+        pattern.lower() in func_lower or func_lower.endswith(pattern.lower())
+        for pattern in _EXCLUDED_FUNCTION_PATTERNS
+    )
+
+
+def _is_excluded_param_position(function_name: str, param_index: int) -> bool:
+    """Check if this parameter position should be excluded for this function."""
+    if param_index != 1:
+        return False
+
+    func_lower = function_name.lower()
+    return any(
+        pattern.lower() in func_lower or func_lower.endswith(pattern.lower())
+        for pattern in _EXCLUDE_PARAM_INDEX_1
+    )
+
+
+def _all_values_excluded(unique_values: set[str]) -> bool:
+    """Check if all values in the set match excluded patterns."""
+    if not unique_values:
+        return True
+    return all(_is_excluded_value(value) for value in unique_values)
+
+
+def _is_excluded_value(value: str) -> bool:
+    """Check if a single value matches any excluded pattern."""
+    return any(pattern.match(value) for pattern in _EXCLUDED_VALUE_PATTERNS)