[chore:docs] Update all docstring in files

Author: Qu1nel

src/code_validator/__init__.py

@@ -1,25 +1,57 @@
 """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
 
 __all__ = [
     "StaticValidator",
     "AppConfig",
     "ExitCode",
+    "LogLevel",
     "ValidationFailedError",
     "RuleParsingError",
 ]
-__version__ = "0.1.2"
+
+__version__ = "0.1.3"

src/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

src/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,8 +23,13 @@
 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",
@@ -32,7 +41,7 @@ def setup_arg_parser() -> argparse.ArgumentParser:
         "-l",
         "--log-level",
         type=LogLevel,
-        choices=LogLevel,
+        choices=list(LogLevel),
         default=LogLevel.WARNING,
         help="Set the logging level (default: WARNING).",
     )
@@ -45,14 +54,20 @@ def setup_arg_parser() -> argparse.ArgumentParser:
 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)
     config = AppConfig(
@@ -63,7 +78,6 @@ def run_from_cli() -> None:
         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)

src/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
 
@@ -36,4 +41,4 @@ def get_full_name(node: ast.AST) -> str | None:
     if isinstance(node, ast.Attribute):
         base = get_full_name(node.value)
         return f"{base}.{node.attr}" if base else node.attr
-    return None
+    return None

src/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

src/code_validator/components/factories.py

@@ -1,9 +1,10 @@
 """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

src/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

src/code_validator/config.py

@@ -34,7 +34,15 @@ 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_silent: 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
@@ -45,7 +53,18 @@ class AppConfig:
 
 @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 +74,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,15 +102,27 @@ 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
 
 
 @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 +132,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