Merge branch 'wip/documentation' into dev

Author: LittleCoinCoin

README.md

@@ -17,25 +17,11 @@ A validation package for Hatch packages and dependencies.
 pip install git+https://github.com/CrackingShells/Hatch-Validator.git
 
 # Or install local copy
+git clone https://github.com/CrackingShells/Hatch-Validator.git
+cd Hatch-Validator
 pip install /path/to/Hatch-Validator
 ```
 
-### As a Submodule
-
-If using as a git submodule:
-
-1. Add as a submodule to your project:
-
-   ```bash
-   git submodule add https://github.com/CrackingShells/Hatch-Validator.git validator
-   ```
-
-2. Install the submodule as a package:
-
-   ```bash
-   pip install ./validator
-   ```
-
 ## Usage
 
 ```python
@@ -69,8 +55,7 @@ We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md)
 3. **Create a feature branch**: `git checkout -b feat/your-feature`
 4. **Make changes** and add tests
 5. **Use conventional commits**: `npm run commit` for guided commits
-6. **Run tests**: `python -c "import hatch_validator; print('Package imports successfully')"`
-7. **Create a pull request**
+6. **Create a pull request**
 
 ### Commit Messages
 

docs/articles/appendices/glossary.md

@@ -0,0 +1,231 @@
+# Glossary
+
+## A
+
+**Auto-Approval**
+A configuration option for dependency installation that automatically approves installation operations without user confirmation.
+
+## B
+
+**Background Updates**
+The ability to update schemas in background threads without blocking main application operations.
+
+**Backward Compatibility**
+The guarantee that newer components can handle packages and data from older schema versions through delegation.
+
+**Backward Compatibility Testing**
+Testing that newer components can properly handle data from older schema versions.
+
+## C
+
+**Cache Corruption Recovery**
+The ability of the schema cache system to detect and recover from corrupted cache files by redownloading schemas.
+
+**Cache Directory**
+The local directory where schemas are cached, defaulting to `~/.hatch/schemas/` but configurable through constructor parameters.
+
+**Cache TTL (Time To Live)**
+The duration for which cached schemas are considered fresh before triggering update checks. Default is 24 hours (86400 seconds).
+
+**Chain Construction**
+The process by which factory classes create and link components in the correct order (newest to oldest) to form functional chains.
+
+**Chain of Responsibility Pattern**
+A behavioral design pattern that allows passing requests along a chain of handlers. In Hatch-Validator, this pattern enables extensible functionality by allowing new components to inherit and modify only changed logic from previous versions.
+
+**Chain Behavior Testing**
+Testing the delegation behavior between components to ensure proper flow of requests through the chain.
+
+**Chain Validation**
+The process of verifying that component chains are properly constructed and cover all required functionality.
+
+**CLI Integration**
+The integration of Hatch-Validator functionality into command-line interfaces for package validation and management operations.
+
+**Component Registration**
+The process of registering component classes with factory classes to enable automatic discovery and chain construction.
+
+**Component Reuse**
+The practice of reusing component instances across multiple operations to reduce object creation overhead.
+
+**CrackingShells Package Registry**
+A package registry format supported by Hatch-Validator, featuring repository-based organization with packages containing multiple versions.
+
+## D
+
+**Delegation**
+The process by which a component in the Chain of Responsibility passes unchanged concerns to the next component in the chain. This enables code reuse and maintains separation of concerns across schema versions.
+
+**Dependency Types**
+Categories of dependencies supported by Hatch packages: hatch (Hatch packages), python (PyPI packages), system (system packages), and docker (Docker images).
+
+## E
+
+**Environment Management**
+The process of managing isolated package environments, which integrates with Hatch-Validator for package validation and dependency resolution.
+
+**Extension Mechanisms**
+The methods and patterns used to add support for new schema versions without modifying existing component implementations.
+
+## F
+
+**Factory Pattern**
+A creational design pattern used to create chains of components. HatchPkgAccessorFactory, ValidatorFactory, and RegistryAccessorFactory automatically discover and link components from newest to oldest versions.
+
+**First-Party Consumer**
+Applications and tools that use Hatch-Validator as a library, such as the Dependency Installation Orchestrator, Environment Manager, and CLI tools.
+
+**Force Update**
+A configuration option that bypasses cache freshness checks and forces schema updates from the remote repository.
+
+## G
+
+**GitHub API Integration**
+The use of GitHub's REST API to discover latest schema versions and download schema files from the Hatch-Schemas repository.
+
+**Graceful Degradation**
+The ability of the validation system to continue operating when certain components fail, typically by falling back to cached data or alternative validation methods.
+
+## H
+
+**Hatch Package Manager**
+The broader package management system that Hatch-Validator supports, providing package creation, validation, and distribution capabilities.
+
+**Hatch-Schemas Repository**
+An external GitHub repository (CrackingShells/Hatch-Schemas) that provides versioned schema definitions for package metadata and registry data.
+
+**HatchPkgAccessorFactory**
+A factory class that creates package accessor chains by automatically discovering and linking package accessors from newest to oldest versions.
+
+## I
+
+**Integration Testing**
+Testing complete component chains to verify proper delegation flow and end-to-end functionality.
+
+## J
+
+**JSON Schema Validation**
+The use of JSON Schema specifications to validate package metadata structure and content against schema definitions.
+
+## L
+
+**Lazy Loading**
+The practice of loading schemas and creating component chains only when needed, improving application startup time and memory usage.
+
+## M
+
+**MCP (Model Context Protocol)**
+A protocol supported by Hatch packages for AI model integration, with entry point configurations handled by the validation system.
+
+**Metadata Structure**
+The organization of data within package metadata files, which varies across schema versions (e.g., separate vs. unified dependencies).
+
+## N
+
+**Network Resilience**
+The ability of the schema management system to handle network failures gracefully by falling back to cached schemas.
+
+## P
+
+**Package Accessors**
+Components that provide unified access to package metadata across schema versions, abstracting differences in metadata structure and field organization.
+
+**PackageService**
+A high-level service class that provides version-agnostic access to package metadata using package accessor chains.
+
+**Programmatic Usage**
+The use of Hatch-Validator through its API rather than command-line interfaces, enabling integration into larger applications and workflows.
+
+## R
+
+**Real-World Usage Patterns**
+Common integration patterns derived from actual production implementations, demonstrating practical benefits of version-agnostic data access.
+
+**Registry Accessors**
+Components that enable consistent registry data access regardless of registry schema version, providing unified interfaces for package discovery and version resolution.
+
+**Registry Schema**
+The schema defining the structure of registry data, currently at version v1.1.0 with support for the CrackingShells Package Registry format.
+
+**RegistryAccessorFactory**
+A factory class that creates registry accessor chains by automatically discovering and linking registry accessors based on registry data format.
+
+**RegistryService**
+A high-level service class that provides version-agnostic access to registry data using registry accessor chains.
+
+## S
+
+**Schema Evolution**
+The process of updating schema definitions to support new features while maintaining backward compatibility. Handled through the Chain of Responsibility pattern.
+
+**SchemaCache**
+A class that manages local schema storage and retrieval, providing offline operation capabilities and cache freshness validation.
+
+**SchemaFetcher**
+A class that handles network operations to retrieve schema definitions from the Hatch-Schemas GitHub repository.
+
+**SchemaRetriever**
+The main interface for schema operations, coordinating between SchemaFetcher and SchemaCache to provide automatic schema management.
+
+**Schema Version**
+A version identifier that specifies the structure and format of package metadata or registry data. Examples include v1.1.0, v1.2.0, and v1.2.1.
+
+**Service Layer**
+High-level interfaces (PackageService, RegistryService, HatchPackageValidator) that abstract the complexity of the Chain of Responsibility pattern from consumers.
+
+**Simulation Mode**
+A configuration mode that prevents network operations and relies entirely on cached or local data for testing purposes.
+
+**Strategy Pattern**
+A behavioral design pattern used within validators to encapsulate validation algorithms. Examples include EntryPointValidation, DependencyValidation, and ToolsValidation strategies.
+
+## T
+
+**Terminal Component**
+The oldest version component in a chain that implements complete functionality without delegation. In Hatch-Validator, v1.1.0 components serve as terminal components.
+
+## U
+
+**Unit Testing**
+Testing individual components in isolation to verify their specific functionality and delegation behavior.
+
+## V
+
+**v1.1.0 Schema**
+The initial package schema version featuring separate dependency structures (hatch_dependencies and python_dependencies) and basic entry point configuration.
+
+**v1.2.0 Schema**
+An updated package schema version introducing unified dependency structure with support for multiple dependency types (hatch, python, system, docker).
+
+**v1.2.1 Schema**
+The latest package schema version adding dual entry point support (mcp_server and hatch_mcp_server) while maintaining the unified dependency structure from v1.2.0.
+
+**Validation Chain**
+A sequence of validators linked together using the Chain of Responsibility pattern, ordered from newest to oldest schema version.
+
+**Validation Error Aggregation**
+The process of collecting and organizing validation errors from multiple validation strategies into comprehensive error reports.
+
+**Validation Strategy**
+A specific validation algorithm encapsulated within a strategy class. Examples include schema validation, entry point validation, and dependency validation.
+
+**ValidationContext**
+A data structure that carries state and configuration information across validator chains, including registry data and validation settings.
+
+**Validators**
+Components that handle validation logic for different schema versions. They implement comprehensive package validation while delegating unchanged validation concerns to previous validators in the chain.
+
+**ValidatorFactory**
+A factory class that creates validator chains by automatically discovering and linking validators from newest to oldest versions.
+
+**Version Ordering**
+The practice of organizing schema versions from newest to oldest in factory classes to ensure proper chain construction.
+
+**Version-Agnostic Access**
+The ability to access package or registry data without needing to know the specific schema version. Achieved through the Chain of Responsibility pattern and service layer abstraction.
+
+**Environment Management**
+The process of managing isolated package environments, which integrates with Hatch-Validator for package validation and dependency resolution.
+
+**CLI Integration**
+The integration of Hatch-Validator functionality into command-line interfaces for package validation and management operations.