refactor: restructure docs, improve logging, and fix type annotations

Author: atellaluca

docs/errors/contract-violations.md

@@ -73,7 +73,17 @@ Each message consists of:
 
 Below is a comprehensive list of all possible error messages emitted by ImportSpy:
 
---8<-- "errors/error_table.md"
+| Category   | Context       | Error Message |
+|------------|---------------|---------------|
+| `missing`  | `runtime`     | The runtime `CPython 3.12` is declared but missing. Ensure it is properly defined and implemented. |
+|            | `environment` | The environment variable `DEBUG` is declared but missing. Ensure it is properly defined and implemented. |
+|            | `module`      | The variable `plugin_name` in module `extension.py` is declared but missing. Ensure it is properly defined and implemented. |
+|            | `class`       | The method `run` in class `Plugin` is declared but missing. Ensure it is properly defined and implemented. |
+| `mismatch` | `runtime`     | The runtime `CPython 3.12` does not match the expected value. Expected: `CPython 3.11`, Found: `CPython 3.12`. Check the value and update the contract or implementation accordingly. |
+|            | `environment` | The environment variable `LOG_LEVEL` does not match the expected value. Expected: `'INFO'`, Found: `'DEBUG'`. Check the value and update the contract or implementation accordingly. |
+|            | `class`       | The class attribute `engine` in class `Extension` does not match the expected value. Expected: `'docker'`, Found: `'podman'`. Check the value and update the contract or implementation accordingly. |
+| `invalid`  | `class`       | The argument `msg` of method `send` has an invalid value. Allowed values: `[str, None]`, Found: `42`. Update the value to one of the allowed options. |
+
 
 ---
 

docs/errors/error-table.md

@@ -1,46 +1,47 @@
 # ImportSpy
 
-**Context-aware import validation for Python modules**
+**Context‑aware import validation for Python modules**
 
-ImportSpy is an open-source Python library that introduces a robust mechanism to control and validate how and when modules are imported. At its core, it relies on versioned, declarative **import contracts** — written in YAML — which describe what a module expects from its execution context and its importer.
+ImportSpy is an open‑source Python library that brings structural and environmental awareness to Python’s import system.  
+It introduces a new concept: the **import contract** — a versioned, declarative `.yml` file that describes exactly how and where a module is allowed to be imported.
 
-It brings **modularity**, **predictability**, and **security** to Python ecosystems.
+This enables predictable, secure, and modular Python codebases, especially in complex or regulated environments.
 
 ---
 
 ## What is an Import Contract?
 
-An import contract is a `.yml` file that defines:
+An import contract defines what a module expects from:
 
-- The expected **structure** of a module: functions, classes, arguments, annotations, variables
-- The allowed **environments**: OS, architecture, Python version, interpreter
-- Optional conditions on runtime **environment variables** or **superclasses**
+- The importing environment: operating system, CPU architecture, Python version, interpreter type
+- Its internal structure: functions, classes, methods, arguments, annotations, variables
+- Optional runtime conditions: environment variables, base classes, or structural patterns
 
-If these conditions are not met, ImportSpy can stop the import and raise a detailed, structured error — before any runtime failure can occur.
+If the context does not meet the declared conditions, ImportSpy blocks the import and raises a structured, human-readable error — before any runtime logic is executed.
 
 ---
 
 ## Key Features
 
-- YAML-based **import contracts**
-- Embedded and CLI-based **validation**
-- Structural validation of **variables**, **functions**, **classes**
-- Runtime checks for **OS**, **architecture**, **Python version**, **interpreter**
-- Contract-driven plugin validation for **secure extensibility**
-- Clear, explainable **error reporting** on mismatch, missing, or invalid usage
-- Fully integrable in **CI/CD pipelines**
+- Declarative, YAML-based import contracts  
+- Embedded and CLI validation modes  
+- Structural enforcement: functions, classes, variables, method signatures  
+- Runtime checks: OS, architecture, Python version, interpreter  
+- Contract-driven plugin validation and safe extensibility  
+- CI/CD‑friendly error reporting  
+- Seamless integration with DevSecOps pipelines
 
 ---
 
 ## Use Cases
 
-ImportSpy is built for teams that need:
+ImportSpy is designed for:
 
-- **Plugin-based architectures** with strict interface enforcement
-- **Runtime protection** against incompatible environments
-- Early validation in **DevSecOps** or **regulatory** pipelines
-- Defensive boundaries between **internal components**
-- **Automated structure verification** during deployment
+- Plugin frameworks with strict interface enforcement  
+- Runtime protection against unsupported environments  
+- Early validation in CI/CD and regulated deployments  
+- Defensive boundaries between internal components  
+- Automated structural checks during deployment
 
 ---
 
@@ -65,44 +66,37 @@ importspy src/mymodule.py -s contracts/spymodel.yml --log-level DEBUG
 
 ## Project Structure
 
-ImportSpy is built around 3 key components:
+ImportSpy is built around:
 
-- `SpyModel`: represents the structural and runtime definition of a module
-- `Spy`: the validation engine that compares real vs expected modules
-- `Violation System`: formal system for raising errors with human-readable messages
+- `SpyModel`: defines expected structure and runtime environment  
+- `Spy`: the engine that validates real vs declared conditions  
+- Violation system: structured, human‑readable error reporting
 
 ---
 
 ## Documentation Overview
 
-### 👣 Get Started
-
-- [Quickstart](intro/quickstart.md)
-- [Install](intro/install.md)
+### Get Started
+- [Quickstart](intro/quickstart.md)  
+- [Installation](intro/install.md)  
 - [Overview](intro/overview.md)
 
-### ⚙️ Modes of Operation
-
-- [Embedded Mode](modes/embedded.md)
+### Modes of Operation
+- [Embedded Mode](modes/embedded.md)  
 - [CLI Mode](modes/cli.md)
 
-### 📄 Import Contracts
-
-- [Contract Syntax](contracts/syntax.md)
+### Import Contracts
+- [Contract Syntax](contracts/syntax.md)  
 - [SpyModel Specification](advanced/spymodel.md)
 
-### 🧠 Validation Engine
-
-- [Violation System](advanced/violations.md)
+### Validation Engine
+- [Violation System](advanced/violations.md)  
 - [Contract Violations](errors/contract-violations.md)
-- [Error Table](errors/error-table.md)
-
-### 📦 Use Cases
 
+### Use Cases
 - [Plugin-based Architectures](use_cases/index.md)
 
-### 📘 API Reference
-
+### API Reference
 - [API Docs](api-reference.md)
 
 ---
@@ -115,25 +109,26 @@ ImportSpy is built around 3 key components:
 
 ## Why ImportSpy?
 
-Python’s import system is powerful, but not context-aware. ImportSpy solves this by adding a **layer of structural governance** and **runtime filtering**.
+Python’s import mechanism is flexible, but not context-aware.  
+ImportSpy adds a layer of governance and runtime validation, making your code more robust and secure.
 
-This makes it ideal for:
+It’s ideal for:
 
-- Plugin systems
-- Isolated runtimes
-- Package compliance
-- Security-aware applications
-- CI enforcement of expected module interfaces
+- Securing plugin boundaries  
+- Enforcing internal interfaces  
+- Preventing unsupported imports  
+- CI/CD enforcement of import assumptions  
+- Runtime compatibility in multi-environment systems
 
 ---
 
-## Sponsorship & Community
+## Support and Community
 
-If ImportSpy is useful in your infrastructure, help us grow by:
+If ImportSpy is useful in your infrastructure, consider:
 
-- [Starring the project on GitHub](https://github.com/your-org/importspy)
-- [Becoming a GitHub Sponsor](https://github.com/sponsors/your-org)
+- [Starring the project on GitHub](https://github.com/atellaluca/ImportSpy)  
+- [Becoming a GitHub Sponsor](https://github.com/sponsors/atellaluca)
 
 ---
 
-> ImportSpy is more than a validator — it's a contract of trust between Python modules.
+> ImportSpy is more than a validator — it’s a contract of trust between Python modules.

docs/index.md

@@ -1,36 +1,41 @@
-"""
-importspy.log_manager
-======================
+"""importspy.log_manager
+
+Centralized logging system for ImportSpy.
 
-This module defines ImportSpy’s centralized logging system.
+This module defines logging utilities that ensure consistent formatting,
+traceability, and developer-friendly output across both embedded and CLI modes.
+The `LogManager` provides a global configuration entry point for logging,
+while `CustomFormatter` enhances each message with context such as file name,
+line number, and function.
 
-Logging is a critical part of ImportSpy: it tracks validation steps, configuration issues,  
-execution context, and errors — all with enhanced formatting for debugging and traceability.
+Used in ImportSpy to provide high-fidelity logs during validation steps,
+contract resolution, and runtime introspection.
 
-The `LogManager` ensures that all logs across ImportSpy are consistent and traceable to their source.  
-It works in both **embedded validation** and **CLI validation**, enabling readable, structured output  
-for developers, testers, and CI pipelines.
+Example:
+    >>> from importspy.log_manager import LogManager
+    >>> log_manager = LogManager()
+    >>> log_manager.configure()
+    >>> logger = log_manager.get_logger("importspy.test")
+    >>> logger.info("Validation started.")
 """
 
 import logging
 
 
 class CustomFormatter(logging.Formatter):
-    """
-    Enhanced formatter for ImportSpy log messages.
+    """Enhanced formatter for ImportSpy log messages.
 
-    This formatter extends the default logging format by appending the exact
-    filename, line number, and function name where each log was triggered.
+    Adds contextual metadata (file, line, function) to each log entry, improving
+    traceability across CLI execution and embedded imports.
 
     Format:
-    -------
-    [timestamp] [LEVEL] [logger name] 
-    [caller: file, line, function] message
+        "[timestamp] LEVEL logger name"
+        "[caller: file, line, function] message"
 
     Example:
-    --------
-    2024-02-24 14:30:12 [INFO] [my_logger] 
-    [caller: example.py, line: 42, function: my_function] This is a log message.
+        2025-08-07 14:30:12 INFO importspy.module
+        caller: loader.py, line: 42, function: validate_import
+        Validation passed.
     """
 
     LOG_FORMAT = (
@@ -40,24 +45,20 @@ class CustomFormatter(logging.Formatter):
     )
 
     def __init__(self):
-        """
-        Initializes the formatter with the ImportSpy logging format.
-        """
+        """Initialize the formatter with ImportSpy's extended log format."""
         super().__init__(self.LOG_FORMAT)
 
-    def format(self, record):
-        """
-        Enriches the log record with caller information.
+    def format(self, record) -> str:
+        """Format the log record with caller information.
 
-        Parameters:
-        -----------
-        record : logging.LogRecord
-            The original log record to be formatted.
+        Adds custom attributes to the `LogRecord` for file name, line number,
+        and function name.
+
+        Args:
+            record (logging.LogRecord): The log record to format.
 
         Returns:
-        --------
-        str
-            A fully formatted log message including file, line, and function context.
+            str: Formatted log message string.
         """
         record.caller_file = record.pathname.split("/")[-1]
         record.caller_line = record.lineno
@@ -66,55 +67,37 @@ def format(self, record):
 
 
 class LogManager:
-    """
-    Centralized manager for all logging within ImportSpy.
+    """Centralized manager for logging configuration in ImportSpy.
 
-    This class ensures:
-    - Uniform formatting across all loggers
-    - Avoidance of duplicate configuration
-    - Consistent output in both CLI and embedded contexts
+    Ensures that all logs share a consistent format and output behavior,
+    avoiding duplicate configuration across modules. Designed for both
+    embedded validation flows and CLI analysis.
 
     Attributes:
-    -----------
-    default_level : int
-        The current log level derived from the root logger.
-
-    default_handler : logging.StreamHandler
-        Default handler for logging output, using the `CustomFormatter`.
-
-    configured : bool
-        Whether the logging system has already been configured.
+        default_level (int): Default log level from the root logger.
+        default_handler (logging.StreamHandler): Stream handler with ImportSpy formatting.
+        configured (bool): Whether the logger has already been initialized.
     """
 
     def __init__(self):
-        """
-        Sets up the default logging handler and format.
-
-        Uses `CustomFormatter` and logs to standard output by default.
-        """
+        """Initialize the default logging handler and formatter."""
         self.default_level = logging.getLogger().getEffectiveLevel()
         self.default_handler = logging.StreamHandler()
         self.default_handler.setFormatter(CustomFormatter())
         self.configured = False
 
     def configure(self, level: int = None, handlers: list = None):
-        """
-        Applies logging configuration globally.
+        """Apply logging configuration globally.
 
-        Prevents duplicate setup. This method should be called once per application.
+        Should be called once per execution to avoid duplicated handlers.
+        Adds provided handlers or defaults to the built-in stream handler.
 
-        Parameters:
-        -----------
-        level : int, optional
-            Log level (e.g., logging.DEBUG). Defaults to current system level.
-
-        handlers : list of logging.Handler, optional
-            Custom handlers to use. Falls back to `default_handler` if none provided.
+        Args:
+            level (int, optional): Logging level (e.g., logging.DEBUG). Defaults to current level.
+            handlers (list[logging.Handler], optional): Custom logging handlers.
 
         Raises:
-        -------
-        RuntimeError
-            If logging is already configured.
+            RuntimeError: If configuration is attempted more than once.
         """
         if self.configured:
             raise RuntimeError("LogManager has already been configured.")
@@ -131,20 +114,16 @@ def configure(self, level: int = None, handlers: list = None):
         self.configured = True
 
     def get_logger(self, name: str) -> logging.Logger:
-        """
-        Returns a named logger with ImportSpy's formatting applied.
+        """Return a named logger configured with ImportSpy's formatter.
 
-        Ensures the logger is properly configured and ready for use.
+        Ensures consistent behavior across all log invocations. If the logger
+        does not yet have handlers, it assigns the default handler.
 
-        Parameters:
-        -----------
-        name : str
-            The name of the logger (e.g., a module name).
+        Args:
+            name (str): Name of the logger (typically a module or subpackage name).
 
         Returns:
-        --------
-        logging.Logger
-            The initialized logger instance.
+            logging.Logger: A logger instance ready for use.
         """
         logger = logging.getLogger(name)
         if not logger.handlers: