python-code-validator 0.1.1__py3-none-any.whl

code_validator/__init__.py

@@ -0,0 +1,25 @@
+"""A flexible framework for static validation of Python code.
+
+This package provides a comprehensive toolkit for statically analyzing Python source
+code based on a declarative set of rules defined in a JSON format. It allows
+for checking syntax, style, structure, and constraints without executing the code.
+
+Key components exposed by this package include:
+    - StaticValidator: The main orchestrator for running the validation process.
+    - AppConfig: A dataclass for configuring the validator's behavior.
+    - ExitCode: An Enum defining exit codes for CLI operations.
+    - Custom Exceptions: For fine-grained error handling during validation.
+"""
+
+from .config import AppConfig, ExitCode
+from .core import StaticValidator
+from .exceptions import RuleParsingError, ValidationFailedError
+
+__all__ = [
+    "StaticValidator",
+    "AppConfig",
+    "ExitCode",
+    "ValidationFailedError",
+    "RuleParsingError",
+]
+__version__ = "0.1.0"

code_validator/__main__.py

@@ -0,0 +1,11 @@
+"""Enables running the validator as a module.
+
+This file allows the package to be executed directly from the command line
+using `python -m code_validator`. It serves as the main entry point
+that invokes the command-line interface logic.
+"""
+
+from .cli import run_from_cli
+
+if __name__ == "__main__":
+    run_from_cli()

code_validator/cli.py

@@ -0,0 +1,88 @@
+"""Defines the command-line interface for the code validator.
+
+This module is responsible for parsing command-line arguments, setting up the
+application configuration, and orchestrating the main validation workflow. It acts
+as the primary entry point for user interaction.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import AppConfig, ExitCode, LogLevel
+from .core import StaticValidator
+from .exceptions import CodeValidatorError
+from .output import Console, setup_logging
+
+
+def setup_arg_parser() -> argparse.ArgumentParser:
+    """Creates and configures the argument parser for the CLI.
+
+    Returns:
+        An instance of argparse.ArgumentParser with all arguments defined.
+    """
+    parser = argparse.ArgumentParser(
+        prog="validate-code",
+        description="Validates a Python source file against a set of JSON rules.",
+    )
+    parser.add_argument("solution_path", type=Path, help="Path to the Python solution file to validate.")
+    parser.add_argument("rules_path", type=Path, help="Path to the JSON file with validation rules.")
+    parser.add_argument(
+        "-l",
+        "--log-level",
+        type=LogLevel,
+        choices=LogLevel,
+        default=LogLevel.WARNING,
+        help="Set the logging level (default: WARNING).",
+    )
+    parser.add_argument("--silent", action="store_true", help="Suppress stdout output, show only logs.")
+    parser.add_argument("--stop-on-first-fail", action="store_true", help="Stop after the first failed rule.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def run_from_cli() -> None:
+    """Runs the full application lifecycle from the command line.
+
+    This function parses arguments, initializes logging and configuration,
+    runs the validator, and handles all top-level exceptions, exiting with an
+    appropriate exit code.
+    """
+    parser = setup_arg_parser()
+    args = parser.parse_args()
+
+    # 1. Setup environment
+    logger = setup_logging(args.log_level)
+    console = Console(logger, is_silent=args.silent)
+    config = AppConfig(
+        solution_path=args.solution_path,
+        rules_path=args.rules_path,
+        log_level=args.log_level,
+        is_silent=args.silent,
+        stop_on_first_fail=args.stop_on_first_fail,
+    )
+
+    # 2. Run main logic with robust error handling
+    try:
+        console.print(f"Starting validation for: {config.solution_path}", level=LogLevel.INFO)
+        validator = StaticValidator(config, console)
+        is_valid = validator.run()
+
+        if is_valid:
+            console.print("Validation successful.", level=LogLevel.INFO)
+            sys.exit(ExitCode.SUCCESS)
+        else:
+            console.print("Validation failed.", level=LogLevel.ERROR)
+            sys.exit(ExitCode.VALIDATION_FAILED)
+
+    except CodeValidatorError as e:
+        console.print(str(e), level=LogLevel.CRITICAL)
+        sys.exit(ExitCode.VALIDATION_FAILED)
+    except FileNotFoundError as e:
+        console.print(f"Error: File not found - {e.strerror}: {e.filename}", level=LogLevel.CRITICAL)
+        sys.exit(ExitCode.FILE_NOT_FOUND)
+    except Exception as e:
+        console.print(f"An unexpected error occurred: {e}", level=LogLevel.CRITICAL)
+        logger.exception("Traceback for unexpected error:")
+        sys.exit(ExitCode.UNEXPECTED_ERROR)

code_validator/components/ast_utils.py

@@ -0,0 +1,40 @@
+"""Provides utility functions for working with Python's Abstract Syntax Trees (AST)."""
+
+import ast
+
+
+def enrich_ast_with_parents(tree: ast.Module) -> None:
+    """Walks the AST and adds a 'parent' attribute to each node.
+
+    This function mutates the AST in-place, making it easier to traverse upwards
+    or determine the context of a specific node. This is a crucial preprocessing
+    step for many complex validation rules.
+
+    Args:
+        tree: The root node of the AST (typically an ast.Module object) to enrich.
+    """
+    for node in ast.walk(tree):
+        for child in ast.iter_child_nodes(node):
+            # Dynamically add a reference to the parent node.
+            child.parent = node
+
+
+def get_full_name(node: ast.AST) -> str | None:
+    """A helper function to recursively build a full attribute name from an AST node.
+
+    For example, for an `ast.Attribute` node representing `foo.bar.baz`, this
+    function will return the string "foo.bar.baz".
+
+    Args:
+        node: The AST node to extract the name from.
+
+    Returns:
+        The full, dot-separated name as a string, or None if a name cannot be
+        constructed.
+    """
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        base = get_full_name(node.value)
+        return f"{base}.{node.attr}" if base else node.attr
+    return None

code_validator/components/definitions.py

@@ -0,0 +1,88 @@
+"""Defines the core component interfaces using Protocols.
+
+This module establishes the fundamental "contracts" for the main architectural
+components of the validator: Rules, Selectors, and Constraints. By using
+Protocols, we ensure that any class conforming to these interfaces can be used
+interchangeably by the system's factories and core engine, enabling a flexible
+and decoupled plugin-style architecture.
+"""
+
+import ast
+from typing import Protocol, runtime_checkable
+
+from ..config import FullRuleConfig, ShortRuleConfig
+
+
+@runtime_checkable
+class Selector(Protocol):
+    """An interface for objects that find and select specific nodes from an AST.
+
+    A Selector's main responsibility is to traverse the Abstract Syntax Tree (AST)
+    of a Python source file and return a list of nodes that match a specific
+    criterion (e.g., all function definitions, all import statements).
+    """
+
+    def select(self, tree: ast.Module) -> list[ast.AST]:
+        """Selects and returns a list of relevant AST nodes from the tree.
+
+        Args:
+            tree: The full, parsed AST of the source code to be searched.
+
+        Returns:
+            A list of ast.AST nodes that match the selector's criteria.
+            An empty list should be returned if no matching nodes are found.
+        """
+        ...
+
+
+@runtime_checkable
+class Constraint(Protocol):
+    """An interface for objects that apply a condition to a set of AST nodes.
+
+    A Constraint takes the list of nodes found by a Selector and checks if they
+    satisfy a specific condition (e.g., the list must not be empty, the node
+    must inherit from a specific class).
+    """
+
+    def check(self, nodes: list[ast.AST]) -> bool:
+        """Checks if the given list of nodes satisfies the constraint.
+
+        Args:
+            nodes: A list of AST nodes provided by a Selector.
+
+        Returns:
+            True if the constraint is satisfied, False otherwise.
+        """
+        ...
+
+
+@runtime_checkable
+class Rule(Protocol):
+    """An interface for any complete, executable validation rule.
+
+    A Rule represents a single, self-contained validation check. It can be a
+    "short" rule (like a linter check) or a "full" rule that internally uses
+    a Selector and a Constraint. The core validator engine interacts with
+    objects conforming to this protocol.
+
+    Attributes:
+        config: The dataclass object holding the configuration for this rule,
+            parsed from the JSON file.
+    """
+
+    config: FullRuleConfig | ShortRuleConfig
+
+    def execute(self, tree: ast.Module | None, source_code: str | None = None) -> bool:
+        """Executes the validation rule.
+
+        Depending on the rule type, this method might operate on the AST, the
+        raw source code, or both.
+
+        Args:
+            tree: The full AST of the source code (for structural checks).
+            source_code: The raw source code string (e.g., for linter checks).
+
+        Returns:
+            True if the validation check passes, False otherwise.
+        """
+        ...

code_validator/components/factories.py

@@ -0,0 +1,243 @@
+"""Contains factories for creating rule, selector, and constraint objects.
+
+This module implements the Factory Method design pattern to decouple the core
+validator engine from the concrete implementation of rules. Factories are
+responsible for parsing raw dictionary configurations from JSON and instantiating
+the appropriate handler classes.
+"""
+
+import dataclasses
+from typing import Any, Type, TypeVar
+
+from ..config import ConstraintConfig, FullRuleCheck, FullRuleConfig, SelectorConfig, ShortRuleConfig
+from ..exceptions import RuleParsingError
+from ..output import Console
+from ..rules_library.basic_rules import CheckLinterRule, CheckSyntaxRule, FullRuleHandler
+from ..rules_library.constraint_logic import (
+    IsForbiddenConstraint,
+    IsRequiredConstraint,
+    MustBeTypeConstraint,
+    MustHaveArgsConstraint,
+    MustInheritFromConstraint,
+    NameMustBeInConstraint,
+    ValueMustBeInConstraint,
+)
+from ..rules_library.selector_nodes import (
+    AssignmentSelector,
+    AstNodeSelector,
+    ClassDefSelector,
+    FunctionCallSelector,
+    FunctionDefSelector,
+    ImportStatementSelector,
+    LiteralSelector,
+    UsageSelector,
+)
+from .definitions import Constraint, Rule, Selector
+
+T = TypeVar("T")
+
+
+def _create_dataclass_from_dict(cls: Type[T], data: dict[str, Any]) -> T:
+    """Safely creates a dataclass instance from a dictionary.
+
+    This helper function filters the input dictionary to include only the keys
+    that correspond to fields in the target dataclass, preventing `TypeError`
+    for unexpected arguments.
+
+    Args:
+        cls: The dataclass type to instantiate.
+        data: The dictionary with raw data.
+
+    Returns:
+        An instance of the specified dataclass.
+    """
+    expected_fields = {f.name for f in dataclasses.fields(cls)}
+    filtered_data = {k: v for k, v in data.items() if k in expected_fields}
+    return cls(**filtered_data)
+
+
+class RuleFactory:
+    """Creates rule handler objects from raw dictionary configuration.
+
+    This is the main factory that acts as an entry point for parsing the
+    'validation_rules' list from a JSON file. It determines whether a rule is
+    a "short" pre-defined type or a "full" custom rule and delegates the
+    creation of its components to other specialized factories.
+
+    Attributes:
+        _console (Console): An instance of the console for logging.
+        _selector_factory (SelectorFactory): A factory for creating selector objects.
+        _constraint_factory (ConstraintFactory): A factory for creating constraint objects.
+    """
+
+    def __init__(self, console: Console):
+        """Initializes the RuleFactory.
+
+        Args:
+            console: An instance of the Console for logging and output,
+                to be passed to rule handlers.
+        """
+        self._console = console
+        self._selector_factory = SelectorFactory()
+        self._constraint_factory = ConstraintFactory()
+
+    def create(self, rule_config: dict[str, Any]) -> Rule:
+        """Creates a specific rule instance based on its configuration.
+
+        This method acts as a dispatcher. It determines whether the configuration
+        describes a "short" pre-defined rule or a "full" custom rule with a
+        selector/constraint pair, and then delegates to the appropriate
+        creation logic.
+
+        Args:
+            rule_config: A dictionary parsed from the JSON rules file.
+
+        Returns:
+            An instance of an object that conforms to the Rule protocol.
+
+        Raises:
+            RuleParsingError: If the rule configuration is invalid, missing
+                required keys, or specifies an unknown type.
+        """
+        rule_id = rule_config.get("rule_id")
+        try:
+            if "type" in rule_config:
+                config = _create_dataclass_from_dict(ShortRuleConfig, rule_config)
+                return self._create_short_rule(config)
+
+            elif "check" in rule_config:
+                raw_selector_cfg = rule_config["check"]["selector"]
+                raw_constraint_cfg = rule_config["check"]["constraint"]
+
+                selector = self._selector_factory.create(raw_selector_cfg)
+                constraint = self._constraint_factory.create(raw_constraint_cfg)
+
+                selector_cfg = _create_dataclass_from_dict(SelectorConfig, raw_selector_cfg)
+                constraint_cfg = _create_dataclass_from_dict(ConstraintConfig, raw_constraint_cfg)
+                check_cfg = FullRuleCheck(selector=selector_cfg, constraint=constraint_cfg)
+                config = FullRuleConfig(
+                    rule_id=rule_config["rule_id"],
+                    message=rule_config["message"],
+                    check=check_cfg,
+                    is_critical=rule_config.get("is_critical", False),
+                )
+                return FullRuleHandler(config, selector, constraint, self._console)
+            else:
+                raise RuleParsingError("Rule must contain 'type' or 'check' key.", rule_id)
+        except (TypeError, KeyError, RuleParsingError) as e:
+            raise RuleParsingError(f"Invalid config for rule '{rule_id}': {e}", rule_id) from e
+
+    def _create_short_rule(self, config: ShortRuleConfig) -> Rule:
+        """Dispatches the creation of handlers for "short" rules.
+
+        This private helper method acts as a registry for pre-defined, common
+        validation checks like syntax or PEP8 linting. It maps a rule's 'type'
+        string to a concrete Rule handler class.
+
+        Args:
+            config: The dataclass object containing the configuration for the
+                short rule.
+
+        Returns:
+            An initialized instance of a concrete class that implements the
+            Rule protocol.
+
+        Raises:
+            RuleParsingError: If the 'type' specified in the config does not
+                correspond to any known short rule.
+        """
+        if config.type == "check_syntax":
+            return CheckSyntaxRule(config, self._console)
+        elif config.type == "check_linter_pep8":
+            return CheckLinterRule(config, self._console)
+        else:
+            raise RuleParsingError(f"Unknown short rule type: '{config.type}'", config.rule_id)
+
+
+class SelectorFactory:
+    """Creates selector objects from raw dictionary configuration.
+
+    This factory is responsible for instantiating the correct Selector object
+    based on the 'type' field in a rule's selector configuration block. Each
+    concrete selector specializes in finding a specific type of AST node.
+    This class uses a static `create` method as it does not need to maintain
+    any state.
+    """
+
+    @staticmethod
+    def create(selector_config: dict[str, Any]) -> Selector:
+        """Creates a specific selector instance based on its type.
+
+        This method uses the 'type' field from the selector configuration
+        to determine which concrete Selector class to instantiate.
+
+        Args:
+            selector_config: The 'selector' block from a JSON rule.
+
+        Returns:
+            An instance of a class that conforms to the Selector protocol.
+        """
+        config = _create_dataclass_from_dict(SelectorConfig, selector_config)
+
+        match config.type:
+            case "function_def":
+                return FunctionDefSelector(name=config.name, in_scope_config=config.in_scope)
+            case "class_def":
+                return ClassDefSelector(name=config.name, in_scope_config=config.in_scope)
+            case "import_statement":
+                return ImportStatementSelector(name=config.name, in_scope_config=config.in_scope)
+            case "function_call":
+                return FunctionCallSelector(name=config.name, in_scope_config=config.in_scope)
+            case "assignment":
+                return AssignmentSelector(name=config.name, in_scope_config=config.in_scope)
+            case "usage":
+                return UsageSelector(name=config.name, in_scope_config=config.in_scope)
+            case "literal":
+                return LiteralSelector(name=config.name, in_scope_config=config.in_scope)
+            case "ast_node":
+                return AstNodeSelector(node_type=config.node_type, in_scope_config=config.in_scope)
+            case _:
+                raise RuleParsingError(f"Unknown selector type: '{config.type}'")
+
+
+class ConstraintFactory:
+    """Creates constraint objects from raw dictionary configuration.
+
+    This factory is responsible for instantiating the correct Constraint object
+    based on the 'type' field in a rule's constraint configuration block.
+    Each concrete constraint specializes in applying a specific logical check
+    to a list of AST nodes. This class uses a static `create` method.
+    """
+
+    @staticmethod
+    def create(constraint_config: dict[str, Any]) -> Constraint:
+        """Creates a specific constraint instance based on its type.
+
+        This method uses the 'type' field from the constraint configuration
+        to determine which concrete Constraint class to instantiate.
+
+        Args:
+            constraint_config: The 'constraint' block from a JSON rule.
+
+        Returns:
+            An instance of a class that conforms to the Constraint protocol.
+        """
+        config = _create_dataclass_from_dict(ConstraintConfig, constraint_config)
+
+        match config.type:
+            case "is_required":
+                return IsRequiredConstraint(count=config.count)
+            case "is_forbidden":
+                return IsForbiddenConstraint()
+            case "must_inherit_from":
+                return MustInheritFromConstraint(parent_name=config.parent_name)
+            case "must_be_type":
+                return MustBeTypeConstraint(expected_type=config.expected_type)
+            case "must_have_args":
+                return MustHaveArgsConstraint(count=config.count, names=config.names, exact_match=config.exact_match)
+            case "name_must_be_in":
+                return NameMustBeInConstraint(allowed_names=config.allowed_names)
+            case "value_must_be_in":
+                return ValueMustBeInConstraint(allowed_values=config.allowed_values)
+            case _:
+                raise RuleParsingError(f"Unknown constraint type: '{config.type}'")

code_validator/components/scope_handler.py

@@ -0,0 +1,59 @@
+"""Provides functionality to find and isolate specific scopes within an AST.
+
+This module contains helper functions that are used by ScopedSelectors to narrow
+down their search area from the entire module to a specific function, class,
+or method, based on the `in_scope` configuration from a JSON rule.
+"""
+
+import ast
+from typing import Any
+
+
+def find_scope_node(tree: ast.Module, scope_config: dict[str, Any]) -> ast.AST | None:
+    """Finds a specific scope node (class or function) within the AST.
+
+    This function traverses the AST to locate a node that matches the provided
+    scope configuration. It supports finding global functions, classes, and
+    methods within classes.
+
+    Args:
+        tree: The root of the AST (the module object).
+        scope_config: A dictionary defining the desired scope.
+            Expected keys:
+            - "function": name of a global function.
+            - "class": name of a class.
+            - "method": name of a method (must be used with "class").
+
+    Returns:
+        The found ast.AST node (either ast.ClassDef or ast.FunctionDef) that
+        represents the desired scope, or None if the scope is not found.
+
+    Example:
+        >>> # To find the scope of 'my_func' in 'MyClass':
+        >>> scope_config = {"class": "MyClass", "method": "my_func"}
+        >>> find_scope_node(my_ast_tree, scope_config)
+        <ast.FunctionDef object at ...>
+    """
+    class_name = scope_config.get("class")
+    if class_name:
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef) and node.name == class_name:
+                # If only a class scope is needed, return it.
+                if "method" not in scope_config:
+                    return node
+
+                # If a method is needed, search within the class body.
+                method_name = scope_config.get("method")
+                for item in node.body:
+                    if isinstance(item, ast.FunctionDef) and item.name == method_name:
+                        return item
+                return None  # Class was found, but the method was not.
+
+    function_name = scope_config.get("function")
+    if function_name:
+        # For global functions, search only the top-level body of the module.
+        for node in tree.body:
+            if isinstance(node, ast.FunctionDef) and node.name == function_name:
+                return node
+
+    return None

code_validator/config.py

@@ -0,0 +1,99 @@
+"""Defines all data structures and configuration models for the validator.
+
+This module contains Enum classes for standardized codes and several frozen
+dataclasses that represent the structured configuration loaded from JSON files
+and command-line arguments. These models ensure type safety and provide a
+clear "shape" for the application's data.
+"""
+
+from dataclasses import dataclass, field
+from enum import IntEnum, StrEnum
+from pathlib import Path
+from typing import Any
+
+
+class ExitCode(IntEnum):
+    """Defines standardized exit codes for the command-line application."""
+
+    SUCCESS = 0
+    VALIDATION_FAILED = 1
+    FILE_NOT_FOUND = 2
+    JSON_ERROR = 3
+    UNEXPECTED_ERROR = 10
+
+
+class LogLevel(StrEnum):
+    """Defines the supported logging levels for the application."""
+
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    """Stores the main application configuration from CLI arguments."""
+
+    solution_path: Path
+    rules_path: Path
+    log_level: LogLevel
+    is_silent: bool
+    stop_on_first_fail: bool
+
+
+@dataclass(frozen=True)
+class SelectorConfig:
+    """Represents the configuration for a Selector component from a JSON rule."""
+
+    type: str
+    name: str | None = None
+    node_type: str | list[str] | None = None
+    in_scope: str | dict[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class ConstraintConfig:
+    """Represents the configuration for a Constraint component from a JSON rule."""
+
+    type: str
+    count: int | None = None
+    parent_name: str | None = None
+    expected_type: str | None = None
+    allowed_names: list[str] | None = None
+    allowed_values: list[Any] | None = None
+    names: list[str] | None = None
+    exact_match: bool | None = None
+
+
+@dataclass(frozen=True)
+class FullRuleCheck:
+    """Represents the 'check' block within a full validation rule."""
+
+    selector: SelectorConfig
+    constraint: ConstraintConfig
+
+
+@dataclass(frozen=True)
+class ShortRuleConfig:
+    """Represents a 'short' (pre-defined) validation rule from JSON."""
+
+    rule_id: int
+    type: str
+    message: str
+    params: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class FullRuleConfig:
+    """Represents a 'full' (custom) validation rule with selector and constraint."""
+
+    rule_id: int
+    message: str
+    check: FullRuleCheck
+    is_critical: bool = False
+
+
+# A type alias representing any possible rule configuration object.
+ValidationRuleConfig = ShortRuleConfig | FullRuleConfig