Rules Loader and Validators

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_quality/rules/engine.py
• src/flext_quality/rules/loader.py
• src/flext_quality/rules/validators.py
• src/flext_quality/utilities.py
• src/flext_quality/_models/flextqualitymodels_part_01.py
• tests/unit/test_rules_engine_validators.py
• config/rules/mod/sed.yaml

Rules Loader and Validators comprise the core declarative validation system within flext-quality. This system enables users to define quality requirements in YAML files, load them into an execution engine, and validate code content or file structures against these rules.

The system utilizes a structured pipeline where FlextQualityRulesLoader parses YAML definitions, FlextQualityRulesEngine orchestrates the validation process, and FlextQualityValidators provides specialized logic for pattern matching and architectural tier enforcement.

Sources: src/flext_quality/rules/engine.py:10-15, src/flext_quality/rules/loader.py, src/flext_quality/rules/validators.py

Rules Engine Architecture

The FlextQualityRulesEngine acts as the primary orchestrator for YAML-based declarative rules validation. It manages the lifecycle of rules from loading to execution against target files or content strings.

Core Engine Workflow

The engine follows a lazy-loading pattern where rules are loaded upon the first validation request if not previously initialized. It supports validating specific file paths or raw strings.

The diagram shows the validation flow from an initial request through rule loading, file discovery, and pattern matching.
Sources: src/flext_quality/rules/engine.py:27-100, tests/unit/test_rules_engine_validators.py:112-118

Validation Logic

The engine evaluates rules by iterating through the lines of a file and applying regular expression patterns defined in the RuleDefinition. When a pattern match occurs, it generates a violation dictionary containing metadata about the rule, file, line number, and severity.

Component	Responsibility
validate(path, context)	Scans a directory or file path for .py files and runs all enabled rules.
validate_content(content, filename)	Validates a raw string against loaded rules without requiring a physical file.
_check_rule(rule, content, filename)	Performs the actual line-by-line regex matching for a specific rule.
_rule_type_to_severity(type)	Maps internal rule types (BLOCKING, WARNING, INFO) to severity levels (ERROR, WARNING, INFO).

Sources: src/flext_quality/rules/engine.py:46-135

Rules Loader

FlextQualityRulesLoader handles the deserialization of YAML files into typed RuleDefinition models. It ensures that rule configurations adhere to the required schema and provides safe defaults for optional fields.

Rule Definition Schema

Rules are defined in YAML under a root rules key. Each rule must contain a name and a type.

rules:
  - name: no-todo
    type: warning
    description: TODO markers are discouraged
    pattern: TODO
    enabled: true
    action: warn

Sources: tests/unit/test_rules_engine_validators.py:27-37, src/flext_quality/_models/flextqualitymodels_part_01.py:532-557

Loading Process

The loader validates the structure of the YAML mapping and utilizes Pydantic models for individual rule validation.

1. Path Verification: Checks if the YAML file exists.
2. YAML Parsing: Uses u.Cli.yaml_safe_load to parse the file into a dictionary.
3. List Extraction: Validates that a rules key exists and contains a list.
4. Model Instantiation: Converts each list item into a m.Quality.RuleDefinition.

Sources: src/flext_quality/rules/loader.py:25-50, src/flext_quality/utilities.py:127-142

Validators Registry

FlextQualityValidators provides a registry-based system for built-in and custom validators. Unlike the pattern-based YAML rules, these validators can implement complex logic, such as architectural tier enforcement.

Built-in Validators

The system ships with several specialized validators:

• Pattern Validator: A parameterized validator for general regex matching.
• ForbiddenPattern Validator: Specifically targets discouraged suppression markers like # type: ignore.
• Tier Validator: Enforces architectural layer constraints, such as preventing tier-0 modules (like constants.py) from importing from higher-tier services.

Sources: src/flext_quality/rules/validators.py:10-150, tests/unit/test_rules_engine_validators.py:176-218

Validator Relationships

The class diagram illustrates the relationship between the Validator protocol, the Registry, and specific implementations like Pattern and Tier validators.
Sources: src/flext_quality/rules/validators.py:18-120

Data Models

The validation system relies on Pydantic-2 models to define the structure of rules and the results of validation runs. These models are split across package parts to manage module size.

Quality Rule Definition

The RuleDefinition model defines the attributes for declarative rules.

Field	Type	Description
name	str	Unique identifier for the rule.
type	RuleType	Category (e.g., content, style, link, accessibility).
description	str	Human-readable explanation of the check.
pattern	str | None	Optional regex pattern for matching.
action	str	Action taken on match (e.g., flag as error).
enabled	bool	Activation status (default: True).

Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:532-557

Issue Model

The Issue model represents a single violation found during a validation run.

Field	Type	Description
type	str	Issue type identifier.
severity	str	Severity level (critical, high, medium, low).
file	str	Path to the file where the issue was found.
line	int | None	Line number of the violation.
description	str	Detailed description of the issue.
recommendation	str	Suggested fix for the issue.

Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:559-598

Summary

The Rules Loader and Validators system provides a flexible, model-driven framework for enforcing code quality. By combining declarative YAML rules with programmatic validators and a robust engine, it allows for both simple pattern matching and complex architectural enforcement. The use of Pydantic models ensures data integrity throughout the validation pipeline, from loading configurations to reporting issues.

Sources: src/flext_quality/rules/engine.py, src/flext_quality/rules/validators.py