Refactor SpyModel, structured violations, and environment validation (v0.4.0) #39
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…alidation via Environment model
- Introduced a structured error model using three generic templates: - ELEMENT_MISSING for expected but missing elements - ELEMENT_MISMATCH for elements present but not matching the contract - ELEMENT_INVALID for values outside the allowed domain - Refactored all error messages in `errors.py` to derive from these templates - Added Scope constants to centralize context classification for variables, attributes, arguments - Removed redundant or duplicated error strings already covered by scoped mappings - Updated validators to pass scope and format context-aware error messages consistently - Removed deprecated `dict_validate` method and return statements no longer used - Cleaned up debug logging with explicit scope awareness in `VariableValidator` This refactor ensures uniformity, better error readability, and easier future maintenance.
… unify context handling - Removed deprecated Scope-to-error mappings from errors.py in favor of context-based formatting - Deleted legacy validators: ArgumentValidator and AttributeValidator - Replaced them with a unified Context-based VariableValidator supporting different scopes - Simplified Errors class to retain only reusable base templates and a few module-specific messages - Introduced context-aware error rendering in variable_validator.py via Context subclasses - Updated FunctionValidator and SystemValidator to pass proper Context instances This refactoring improves modularity, eliminates redundancy, and prepares the validation engine for dynamic, pluggable scope contexts.
…ontext-aware template engine - Replaced legacy error formatting with structured, reusable error templates - Moved error definitions and context category mappings into constants.py - Removed deprecated validators (argument_validator, attribute_validator, common_validator) - Deprecated static error classes in favor of dynamic Error model generation - Introduced Contexts enum and error intros for modular, class, runtime, and environment scopes - Simplified and cleaned validation logic across modules and models - Removed legacy context classes in preparation for new context bundling layer Next step: Introduce ContextBundle classes to persist contextual state during validation, enabling precise scope-aware diagnostics (e.g. method argument inside class, or env var at runtime).
- Removed obsolete validators (argument, attribute, function, module, system, python) - Began replacing static validation flow with context-aware logic - Introduced early wiring for runtime/module validation in Spy entrypoint - Stubbed modular validator orchestration using dedicated runtime/module classes - Temporary API degradation in function/module validation pending reimplementation Note: This commit breaks some validation logic. Work is paused mid-refactor.
…l-based error formatting - Renamed error label templates to VARIABLES_LABEL_TEMPLATE and FUNCTIONS_LABEL_TEMPLATE for clarity. - Introduced abstract base class `ContractViolation` and concrete implementations: - VariableContractViolation - FunctionContractViolation - Added dataclass-based bundles for different scopes (ClassBundle, ModuleBundle, EnvironmentBundle). - Refactored `Error` model to support instantiation from a `ContractViolation` using `from_contract_violation`. - Label generation is now context-aware and dynamically formatted from scope-specific bundles. This refactor prepares the foundation for more granular and serializable error reporting in ImportSpy.
…lidation constraints - Introduced Enum-based classes in `Constants` for supported architectures, OS, Python versions, interpreters, annotations, and class attribute types. - Updated `Runtime`, `System`, `Python`, `Variable`, `Attribute`, and `Function` models to use strongly typed enums. - Removed Pydantic field validators in favor of stricter enum typing. - Extended `BaseContractViolation` with error rendering methods for missing, mismatch, and invalid violations. - Adjusted Python version extraction to return only major.minor format. This refactor improves type safety, removes redundant runtime checks, and paves the way for better validation consistency.
…ctured runtime errors - Added `RuntimeContractViolation` class to represent runtime-level contract violations with contextual error formatting. - Created `RuntimeBundle` dataclass to encapsulate runtime input for error label rendering. - Updated `RuntimeValidator` to raise structured error using `RuntimeContractViolation` when runtimes are missing. - Extended `FunctionContractViolation` to support module-level bundles for consistency. This enhancement enables type-safe and context-aware error reporting for runtime validation in ImportSpy.
…and module layers - Introduced `SystemContractViolation`, `PythonContractViolation`, and `ModuleContractViolation` classes to support context-aware error rendering. - Extended `ModuleBundle` and added `SystemBundle`, `PythonBundle` to carry context-specific metadata. - Added `MODULE_LABEL_TEMPLATE` to support dynamic error label formatting for modules. - Updated `validators.py` to raise structured violations with accurate labels for missing systems, Python configurations, modules, and environments. This improves consistency, granularity, and future serializability of validation errors.
…label rendering - Replaced per-category constructors with context-only `BaseContractViolation` base class. - Simplified construction of contract violation instances across system, runtime, python, module, variable, and function levels. - Updated `MODULE_LABEL_TEMPLATE` to refer to "module" instead of "filename" for clearer error messaging. - Refactored `VariableValidator` and `FunctionValidator` to receive structured violation context via `ContractViolation` subclasses. - Improved error messaging granularity and centralized mismatch/missing/invalid logic. This paves the way for fully contextualized error handling and better user-facing diagnostics.
…coped validation - Added `get_class_attributes()` and `get_instance_attributes()` to `Class` model to enable scoped attribute validation. - Updated `ModuleValidator` to use `get_class_attributes()` for clearer intent and improved context. - Injected `attribute_type` and `class_name` into `VariableContractViolation` for better error label rendering. - Removed unused `attribute_name` field from `ClassBundle`. This refactor improves precision of class attribute validation and lays groundwork for separate handling of instance attributes.
…cated module - Removed `ContractViolation` and related subclasses from `models.py` - Introduced `violation_systems.py` to isolate and encapsulate violation logic - Refactored `ModuleValidator` to delegate class validation to new `ClassValidator` - Added `ClassValidator` for structured validation of class attributes and methods - Improved modularity and readability of validation logic across layers This paves the way for scalable handling of violations across contexts while keeping `models.py` focused on data structure definitions.
- Introduced `Bundle` dataclass to unify and track dynamic validation state - Replaced context-specific bundles (e.g. PythonBundle, ModuleBundle) with `Bundle` across validators and contract violations - Extended `Errors` with dynamic payload key constants (e.g. KEY_MODULE_NAME, KEY_FUNCTION_NAME) - Adjusted `Spy._validate_module()` and all validators to propagate and populate a single `Bundle` instance - Simplified label rendering by removing `asdict()` calls and using `bundle.state` This update reduces duplication, improves consistency across validations, and lays the groundwork for customizable error payload introspection.
- Replaced explicit .state access with magic methods (__getitem__, __setitem__) - Renamed KEY_ENVIRONMENT_VARIABLE → KEY_ENVIRONMENT_VARIABLE_NAME for consistency - Registered variable names in bundle dynamically during validation - Updated all contract violations to use dict-style access on Bundle
…violations - Added support for `ENTITY_MESSAGES` and `COLLECTIONS_MESSAGES` in label templates - Updated all error label methods to accept a `spec` parameter for granular formatting - Standardized label generation across runtime, system, python, module, and function validators - Improved consistency in error message templates for collections and single entities
…recursion - Introduced collection-aware error labels for class validation - Extended ClassValidator to support recursive validation of superclasses - Updated MODULE_LABEL_TEMPLATE with support for ENTITY and COLLECTION specs - Improved superclass extraction logic to return full class info - Added KEY_CLASSES_1 constant for consistent bundle usage
…attributes - Replaced ArgumentValidator and AttributeValidator with a unified VariableValidator - Refactored argument and attribute tests to use VariableValidator with contextual contract violations - Introduced enum-based SupportedArchitectures and SupportedOS for stricter typing - Fixed circular import in violation_systems - Extended test coverage with bundle-aware fixtures for validation contexts
… violations - Updated `VARIABLES_DINAMIC_PAYLOAD` to support nested ENTITY_MESSAGES and COLLECTIONS_MESSAGES - Refactored `VariableValidator` to dynamically resolve keys based on scope and context - Improved `Bundle` to implement MutableMapping for cleaner access and interoperability - Adjusted error formatting to remove redundant solution templates - Extended test coverage for argument mismatch scenarios using contextual spec selection
… test suite - Refactored all validator tests to consistently use VariableContractViolation objects - Unified use of dynamic payloads with proper dispatch between ENTITY_MESSAGES and COLLECTIONS_MESSAGES - Replaced hardcoded class/function names with contextualized bundles - Updated SupportedClassAttributeTypes to use explicit Enum members - Cleaned up unused and redundant imports across tests
…ion violations - Introduced structured ENTITY_MESSAGES and COLLECTIONS_MESSAGES in FUNCTIONS_DINAMIC_PAYLOAD - Updated FunctionValidator and related tests to use FunctionContractViolation consistently - Replaced hardcoded keys in test fixtures with dynamic resolution based on violation context - Improved test clarity with Bundle mocking and accurate context injection
… state - ModuleValidator no longer stores a bundle in the constructor - All contract violations are now explicitly passed as arguments - Updated validate method to use context-aware dynamic payload injection - Adjusted tests to reflect contract-based design and error formatting
- Removed persistent bundle state from Runtime, System, Python validators - Introduced explicit `contract_violation` injection for all runtime validations - Updated label rendering to support formatted runtime messages - Standardized dynamic payload injection in bundle for error formatting - Fixed key mismatch for systems_1 in error constants - Expanded test coverage for mismatch cases using formatted contract violations - Removed unused legacy code paths and ensured full consistency with Bundle API
- Added __str__ and __repr__ methods to core model classes (Python, System, Variable, Module) for cleaner error outputs - Refactored error message templates to support entity vs. collection granularity - Corrected YAML model definition for superclass (now supports name field) - Improved runtime validation pipeline to use context-aware contract violations - Replaced DEBUG with WARN for external compliance example logging - Removed unused plugin_interface.py example module - Adjusted environment variable extraction to include annotation field - Fixed incorrect error key (systems_1) and enhanced template resolution in BaseContractViolation
- Added __str__ and __repr__ methods to Environment, Runtime, and Function classes - Simplified System.__str__ method by removing unnecessary logic - Adjusted Python.__str__ to avoid accessing .value on plain strings - Updated test fixtures to use SupportedOS enum for clarity and consistency
- Removed unused `Any` import from models.py - Updated test fixture in `test_system_validator.py` to use SupportedOS enum for setting system OS
Switched from .rst to .md format for better readability and compatibility with GitHub's native markdown renderer. Includes updated badges, architecture diagram, usage modes, and installation instructions.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR introduces a set of architectural and functional improvements in preparation for
v0.4.0. Highlights include:SpyModelnow supports a declarativeenvironmentsection for runtime environment variables and secrets. This allows contracts to validate context requirements without exposing sensitive content.SpyModelhas been streamlined for clarity and maintainability.ViolationSystem, enabling better error reporting and debugging.Variabletype is introduced, and secrets are now defined as a list of required keys—semantically enforced but not exposed, making contracts safer and versionable.This release lays the foundation for more predictable import validation and better integration with DevSecOps pipelines.
