Rust Strict Typing & Error Law
Relevant source files
The following files were used as context for generating this wiki page:
Rust Strict Typing & Error Law governs the architectural approach to type safety and error management within the flext-quality ecosystem. Although the primary implementation language is Python, the project enforces "Rust-like" strictness through the use of comprehensive type hints, Pydantic models for domain state, and explicit Result patterns for operation outcomes. This system ensures that every boundary transition—whether between services, MCP tools, or CLI commands—is validated and handled without silent failures.
The core of this law is "Strict Execution," which mandates that failures must be loud, no fallbacks are permitted for invalid configurations, and every effect must be preceded by a preflight validation. These principles are encoded in the AGENTS.md engineering core and enforced across all package modules.
Sources: AGENTS.md:104-124, pyproject.toml:137-160
Result-Based Error Handling
The project rejects standard exception-based flow control in favor of a Result pattern. Every critical operation returns a Result object that explicitly encodes either success or a specific failure reason. This approach forces developers to acknowledge and handle potential errors at the call site.
Execution Flow with Results
The following diagram illustrates how the Result pattern manages the flow of an operation from initiation to outcome.
The flow ensures that errors are not swallowed and that the final state is always predictable.
Sources: src/flext_quality/rules/engine.py:42-53, tests/README.md:270-285
Key Result Implementation Patterns
| Method | Behavior | Source |
|---|---|---|
r[T].ok(value) | Wraps a successful value into a Result container. | src/flext_quality/rules/engine.py:53 |
r[T].fail(error) | Wraps a failure message or error object. | src/flext_quality/rules/engine.py:44 |
result.unwrap_or(default) | Safely retrieves the value or provides a fallback. | examples/README.md:129 |
result.failure | Property used to check for an error state. | src/flext_quality/rules/engine.py:43 |
Strict Type Enforcement
Strict typing is achieved through Pydantic V2 models and static analysis configurations. The flext-quality package utilizes FlextWebModels.ManagedModel as a base for all domain entities, ensuring runtime validation of data structures.
Data Model Hierarchy
The hierarchy demonstrates how domain-specific models inherit validation capabilities from the base managed model.
Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:23-56, src/flext_quality/_models/flextqualitymodels_part_01.py:461-487
Static Analysis Configuration
The project enforces type safety at build time using mypy and pyright. Configurations in pyproject.toml set typeCheckingMode = "strict" and enable multiple error codes to prevent implicit Any types or unannotated returns.
Sources: pyproject.toml:137-160, pyproject.toml:292-315
Engineering Law: Strict Execution
The "Strict Execution" policy is universal and non-optional. It consists of eight cumulative sub-policies that govern how agents and code must behave during execution.
- Fail Loud: Errors must escape with a full traceback and cause rather than being caught and ignored.
- No Fallback: Defaulting to a safe state during an evidenced failure is considered a defect.
- Preflight Before Effects: Validation must occur before any state-changing operations are executed.
- Atomic Effects: Operations must either complete entirely or leave no residue upon failure.
- Causal Subprocess Propagation: Failures in child processes must propagate to the parent.
Sources: AGENTS.md:104-124
Validation Rules Engine
The FlextQualityRulesEngine applies the strict typing and error law to YAML-based declarative rules. It utilizes the Result pattern to load rules and validate content, ensuring that path errors or regex compilation failures are reported as explicit failures.
The sequence shows the transition from a raw YAML file to a typed rule set managed by the engine.
Sources: src/flext_quality/rules/engine.py:42-53, src/flext_quality/utilities.py:171-188
Validation Metrics
Documentation audit results are captured in a typed AuditMetrics model, preventing data corruption during the reporting phase.
| Field | Type | Description |
|---|---|---|
total_issues | int | Count of all documentation issues found. |
quality_score | int | Score from 0 to 100. |
files_analyzed | int | Count of inspected files. |
issues_per_file | float | Average issues calculated per file. |
| Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:31-56 |
Rust Strict Typing & Error Law serves as the foundation for stability in the flext-quality platform. By combining Pydantic's runtime validation with a mandatory Result pattern and strict execution laws, the system ensures that every component maintains a high-integrity baseline, preventing the "normalized failure" defects common in loosely typed environments.