python-code-validator 0.1.2__py3-none-any.whl → 0.2.1__py3-none-any.whl

code_validator/__init__.py

@@ -1,17 +1,47 @@
 """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.
+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.
+
+The primary entry point for using this package programmatically is the
+`StaticValidator` class.
+
+Example:
+    A minimal example of using the validator as a library.
+
+    .. code-block:: python
+
+        from code_validator import StaticValidator, AppConfig, LogLevel
+        from code_validator.output import Console, setup_logging
+        from pathlib import Path
+
+        # Basic setup
+        logger = setup_logging(LogLevel.INFO)
+        console = Console(logger)
+        config = AppConfig(
+            solution_path=Path("path/to/solution.py"),
+            rules_path=Path("path/to/rules.json"),
+            log_level=LogLevel.INFO,
+            is_silent=False,
+            stop_on_first_fail=False
+        )
+
+        # Run validation
+        validator = StaticValidator(config, console)
+        is_valid = validator.run()
+
+        if is_valid:
+            print("Validation Passed!")
+
+Attributes:
+    __version__ (str): The current version of the package.
+    __all__ (list[str]): The list of public objects exposed by the package.
+
 """
 
-from .config import AppConfig, ExitCode
+from .config import AppConfig, ExitCode, LogLevel
 from .core import StaticValidator
 from .exceptions import RuleParsingError, ValidationFailedError
 
@@ -19,7 +49,9 @@ __all__ = [
     "StaticValidator",
     "AppConfig",
     "ExitCode",
+    "LogLevel",
     "ValidationFailedError",
     "RuleParsingError",
 ]
-__version__ = "0.1.2"
+
+__version__ = "0.2.1"

code_validator/__main__.py

@@ -1,8 +1,17 @@
-"""Enables running the validator as a module.
+"""Enables running the validator as a package.
 
 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.
+using the ``-m`` flag with Python (e.g., ``python -m code_validator``). It
+serves as the primary entry point that finds and invokes the command-line
+interface logic defined in the `cli` module.
+
+Example:
+    You can run the validator package like this from the project root:
+
+    .. code-block:: bash
+
+        python -m code_validator path/to/solution.py path/to/rules.json
+
 """
 
 from .cli import run_from_cli

code_validator/cli.py

@@ -2,7 +2,11 @@
 
 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.
+as the primary entry point for user interaction when the tool is called from
+the terminal.
+
+The main function, `run_from_cli`, handles the entire application lifecycle,
+including robust top-level error handling to ensure meaningful exit codes.
 """
 
 import argparse
@@ -19,70 +23,90 @@ from .output import Console, setup_logging
 def setup_arg_parser() -> argparse.ArgumentParser:
     """Creates and configures the argument parser for the CLI.
 
+    This function defines all positional and optional arguments that the
+    `validate-code` command accepts, including their types, help messages,
+    and default values.
+
     Returns:
-        An instance of argparse.ArgumentParser with all arguments defined.
+        argparse.ArgumentParser: A fully configured parser instance ready to
+            process command-line arguments.
     """
     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",
+        "--log",
         type=LogLevel,
-        choices=LogLevel,
-        default=LogLevel.WARNING,
-        help="Set the logging level (default: WARNING).",
+        default=LogLevel.ERROR,
+        help=("Set the logging level for stderr (TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL). Default: ERROR."),
     )
-    parser.add_argument("--silent", action="store_true", help="Suppress stdout output, show only logs.")
+    parser.add_argument(
+        "--quiet", action="store_true", help="Suppress all stdout output (validation errors and final verdict)."
+    )
+    parser.add_argument("--no-verdict", action="store_true", help="Suppress stdout output verdict, show failed rules.")
     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__}")
+    parser.add_argument("--version", "-v", 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.
+    This is the main entry point for the `validate-code` script. It performs
+    the following steps:
+    1. Parses command-line arguments.
+    2. Initializes the logger, console, and configuration.
+    3. Instantiates and runs the `StaticValidator`.
+    4. Handles all top-level exceptions and exits with an appropriate status code.
+
+    Raises:
+        SystemExit: This function will always terminate the process with an
+            exit code defined in the `ExitCode` enum.
     """
     parser = setup_arg_parser()
     args = parser.parse_args()
 
-    # 1. Setup environment
-    logger = setup_logging(args.log_level)
-    console = Console(logger, is_silent=args.silent)
+    logger = setup_logging(args.log)
+    console = Console(logger, is_quiet=args.quiet, show_verdict=not args.no_verdict)
+    console.print(f"Level of logging: {args.log}", level=LogLevel.DEBUG)
     config = AppConfig(
         solution_path=args.solution_path,
         rules_path=args.rules_path,
-        log_level=args.log_level,
-        is_silent=args.silent,
+        log_level=args.log,
+        is_quiet=args.quiet,
         stop_on_first_fail=args.stop_on_first_fail,
     )
+    console.print(f"Config is: {config}", level=LogLevel.TRACE)
 
-    # 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)
+
+        console.print("Start of validation..", level=LogLevel.TRACE)
         is_valid = validator.run()
+        console.print(f"End of validation with result: {is_valid = }", level=LogLevel.TRACE)
 
         if is_valid:
-            console.print("Validation successful.", level=LogLevel.INFO)
+            console.print("Validation successful.", level=LogLevel.INFO, is_verdict=True)
             sys.exit(ExitCode.SUCCESS)
         else:
-            console.print("Validation failed.", level=LogLevel.ERROR)
+            console.print("Validation failed.", level=LogLevel.INFO, is_verdict=True)
             sys.exit(ExitCode.VALIDATION_FAILED)
 
     except CodeValidatorError as e:
-        console.print(str(e), level=LogLevel.CRITICAL)
+        console.print("Error: Internal Error of validator!", level=LogLevel.CRITICAL)
+        logger.exception(f"Traceback for CodeValidatorError: {e}")
         sys.exit(ExitCode.VALIDATION_FAILED)
     except FileNotFoundError as e:
-        console.print(f"Error: File not found - {e.strerror}: {e.filename}", level=LogLevel.CRITICAL)
+        console.print(f"Error: File not found - {e.filename}!", level=LogLevel.CRITICAL)
+        logger.exception(f"Traceback for FileNotFoundError: {e}")
         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:")
+        console.print(f"An unexpected error occurred: {e.__class__.__name__}!", level=LogLevel.CRITICAL)
+        logger.exception(f"Traceback for unexpected error: {e}")
         sys.exit(ExitCode.UNEXPECTED_ERROR)

code_validator/components/ast_utils.py

@@ -1,4 +1,9 @@
-"""Provides utility functions for working with Python's Abstract Syntax Trees (AST)."""
+"""Provides utility functions for working with Python's Abstract Syntax Trees (AST).
+
+This module contains helper functions that perform common operations on AST nodes,
+such as enriching the tree with parent references. These utilities are used by
+various components of the validator to simplify complex tree analysis.
+"""
 
 import ast
 
@@ -15,7 +20,6 @@ def enrich_ast_with_parents(tree: ast.Module) -> None:
     """
     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
 
 

code_validator/components/definitions.py

@@ -1,10 +1,11 @@
-"""Defines the core component interfaces using Protocols.
+"""Defines the core component interfaces for the validator 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.
+components: Rules, Selectors, and Constraints. By using `typing.Protocol`, we
+ensure that any class conforming to these interfaces can be used interchangeably
+by the system's factories and core engine. This enables a flexible and
+decoupled plugin-style architecture, where new components can be added without
+modifying the core logic.
 """
 
 import ast

code_validator/components/factories.py

@@ -1,17 +1,18 @@
 """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.
+validator engine from the concrete implementations of its components. Factories
+are responsible for parsing raw dictionary configurations from the main JSON
+rules file and instantiating the appropriate handler classes from the
+`rules_library`.
 """
 
 import dataclasses
 from typing import Any, Type, TypeVar
 
-from ..config import ConstraintConfig, FullRuleCheck, FullRuleConfig, SelectorConfig, ShortRuleConfig
+from ..config import ConstraintConfig, FullRuleCheck, FullRuleConfig, LogLevel, SelectorConfig, ShortRuleConfig
 from ..exceptions import RuleParsingError
-from ..output import Console
+from ..output import Console, log_initialization
 from ..rules_library.basic_rules import CheckLinterRule, CheckSyntaxRule, FullRuleHandler
 from ..rules_library.constraint_logic import (
     IsForbiddenConstraint,
@@ -70,6 +71,7 @@ class RuleFactory:
         _constraint_factory (ConstraintFactory): A factory for creating constraint objects.
     """
 
+    @log_initialization(level=LogLevel.TRACE)
     def __init__(self, console: Console):
         """Initializes the RuleFactory.
 
@@ -100,8 +102,10 @@ class RuleFactory:
                 required keys, or specifies an unknown type.
         """
         rule_id = rule_config.get("rule_id")
+        self._console.print(f"Start parsing rule ({rule_id}):\n{rule_config}", level=LogLevel.TRACE)
         try:
             if "type" in rule_config:
+                self._console.print(f"Rule {rule_id} is shorted rule - {rule_config['type']}", level=LogLevel.DEBUG)
                 config = _create_dataclass_from_dict(ShortRuleConfig, rule_config)
                 return self._create_short_rule(config)
 
@@ -109,20 +113,31 @@ class RuleFactory:
                 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)
+
+                selector = self._selector_factory.create(selector_cfg)
+                constraint = self._constraint_factory.create(constraint_cfg)
+
+                self._console.print(
+                    f"Rule {rule_id} is general rule with: selector - "
+                    f"{selector_cfg.type}, constraint - {raw_constraint_cfg['type']}",
+                    level=LogLevel.DEBUG,
+                )
+
                 check_cfg = FullRuleCheck(selector=selector_cfg, constraint=constraint_cfg)
+                self._console.print(f"Create FullRuleCheck: {check_cfg}", level=LogLevel.TRACE)
+
                 config = FullRuleConfig(
                     rule_id=rule_config["rule_id"],
                     message=rule_config["message"],
                     check=check_cfg,
                     is_critical=rule_config.get("is_critical", False),
                 )
+                self._console.print(f"Create FullRuleConfig: {config}", level=LogLevel.TRACE)
                 return FullRuleHandler(config, selector, constraint, self._console)
             else:
+                self._console.print(f"Invalid syntax of rule: {rule_id}", level=LogLevel.WARNING)
                 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
@@ -164,21 +179,23 @@ class SelectorFactory:
     any state.
     """
 
+    @log_initialization(level=LogLevel.TRACE)
+    def __init__(self) -> None:
+        pass
+
     @staticmethod
-    def create(selector_config: dict[str, Any]) -> Selector:
+    def create(config: SelectorConfig) -> 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.
+            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)
@@ -209,21 +226,23 @@ class ConstraintFactory:
     to a list of AST nodes. This class uses a static `create` method.
     """
 
+    @log_initialization(level=LogLevel.TRACE)
+    def __init__(self) -> None:
+        pass
+
     @staticmethod
-    def create(constraint_config: dict[str, Any]) -> Constraint:
+    def create(config: ConstraintConfig) -> 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.
+            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)

code_validator/components/scope_handler.py

@@ -1,8 +1,10 @@
 """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.
+This module contains a key helper function, `find_scope_node`, which is used
+by `ScopedSelector` instances. Its purpose is to traverse the AST and return
+a specific subtree (e.g., a function body or class body) based on the
+`in_scope` configuration from a JSON rule. This allows rules to be applied
+with high precision to specific parts of the source code.
 """
 
 import ast

code_validator/config.py

@@ -25,6 +25,7 @@ class ExitCode(IntEnum):
 class LogLevel(StrEnum):
     """Defines the supported logging levels for the application."""
 
+    TRACE = "TRACE"
     DEBUG = "DEBUG"
     INFO = "INFO"
     WARNING = "WARNING"
@@ -34,18 +35,37 @@ class LogLevel(StrEnum):
 
 @dataclass(frozen=True)
 class AppConfig:
-    """Stores the main application configuration from CLI arguments."""
+    """Stores the main application configuration from CLI arguments.
+
+    Attributes:
+        solution_path: The file path to the Python solution to be validated.
+        rules_path: The file path to the JSON rules file.
+        log_level: The minimum logging level for console output.
+        is_quiet: If True, suppresses all non-log output to stdout.
+        stop_on_first_fail: If True, halts validation after the first failed rule.
+    """
 
     solution_path: Path
     rules_path: Path
     log_level: LogLevel
-    is_silent: bool
+    is_quiet: bool
     stop_on_first_fail: bool
 
 
 @dataclass(frozen=True)
 class SelectorConfig:
-    """Represents the configuration for a Selector component from a JSON rule."""
+    """Represents the configuration for a Selector component from a JSON rule.
+
+    This dataclass captures all possible keys within the "selector" block
+    of a JSON validation rule.
+
+    Attributes:
+        type: The type of the selector to be used (e.g., "function_def").
+        name: A generic name parameter used by many selectors (e.g., the name
+            of a function, class, or module).
+        node_type: The AST node type name for the `ast_node` selector.
+        in_scope: The scope in which to apply the selector.
+    """
 
     type: str
     name: str | None = None
@@ -55,7 +75,21 @@ class SelectorConfig:
 
 @dataclass(frozen=True)
 class ConstraintConfig:
-    """Represents the configuration for a Constraint component from a JSON rule."""
+    """Represents the configuration for a Constraint component from a JSON rule.
+
+    This dataclass captures all possible keys within the "constraint" block
+    of a JSON validation rule.
+
+    Attributes:
+        type: The type of the constraint to be applied (e.g., "is_required").
+        count: The exact number of nodes expected. Used by `is_required`.
+        parent_name: The expected parent class name. Used by `must_inherit_from`.
+        expected_type: The expected Python type name. Used by `must_be_type`.
+        allowed_names: A list of permitted names. Used by `name_must_be_in`.
+        allowed_values: A list of permitted literal values. Used by `value_must_be_in`.
+        names: A list of expected argument names. Used by `must_have_args`.
+        exact_match: A boolean flag for argument matching. Used by `must_have_args`.
+    """
 
     type: str
     count: int | None = None
@@ -69,7 +103,12 @@ class ConstraintConfig:
 
 @dataclass(frozen=True)
 class FullRuleCheck:
-    """Represents the 'check' block within a full validation rule."""
+    """Represents the 'check' block within a full validation rule.
+
+    Attributes:
+        selector: The configuration for the selector component.
+        constraint: The configuration for the constraint component.
+    """
 
     selector: SelectorConfig
     constraint: ConstraintConfig
@@ -77,7 +116,14 @@ class FullRuleCheck:
 
 @dataclass(frozen=True)
 class ShortRuleConfig:
-    """Represents a 'short' (pre-defined) validation rule from JSON."""
+    """Represents a 'short' (pre-defined) validation rule from JSON.
+
+    Attributes:
+        rule_id: The unique integer identifier for the rule.
+        type: The string identifier for the short rule (e.g., "check_syntax").
+        message: The error message to display if the rule fails.
+        params: A dictionary of optional parameters for the rule.
+    """
 
     rule_id: int
     type: str
@@ -87,7 +133,14 @@ class ShortRuleConfig:
 
 @dataclass(frozen=True)
 class FullRuleConfig:
-    """Represents a 'full' (custom) validation rule with selector and constraint."""
+    """Represents a 'full' (custom) validation rule with a selector and constraint.
+
+    Attributes:
+        rule_id: The unique integer identifier for the rule.
+        message: The error message to display if the rule fails.
+        check: An object containing the selector and constraint configurations.
+        is_critical: If True, validation halts if this rule fails.
+    """
 
     rule_id: int
     message: str