Rules Engine Overview

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/__init__.py
• src/flext_quality/_models/flextqualitymodels_part_01.py
• src/flext_quality/utilities.py
• tests/unit/test_rules_engine_validators.py
• config/rules/mod/sed.yaml

The Rules Engine provides a YAML-based declarative framework for validating code and documentation within the FLEXT Quality ecosystem. It automates the detection of style violations, forbidden patterns, and structural inconsistencies by applying a set of predefined or custom rules against target files or raw string content.

Sources: src/flext_quality/rules/engine.py:1-12, src/flext_quality/rules/__init__.py, tests/unit/test_rules_engine_validators.py:16-20

Core Architecture

The FlextQualityRulesEngine acts as the central coordinator for rule management and execution. It utilizes a dedicated loader to parse YAML definitions into structured RuleDefinition models and executes validation logic through internal check methods.

Rules Engine Components

The engine interacts with several key internal components to perform its duties:

• Rules Loader: Parses YAML files and validates the schema of rule definitions.
• Pattern Compiler: Converts string-based patterns from YAML into optimized regex patterns.
• File Scanner: Identifies relevant Python files within a directory for batch analysis.
• Validator Registry: (Accessible via FlextQualityValidators) Maintains a set of specialized validators like ForbiddenPattern and Tier.

Sources: src/flext_quality/rules/engine.py:16-55, src/flext_quality/utilities.py:53-76, tests/unit/test_rules_engine_validators.py:133-160

Validation Workflow

The following diagram illustrates the sequence of events when the engine validates a file path.

The engine ensures rules are present before proceeding with file discovery and line-by-line pattern matching.

Sources: src/flext_quality/rules/engine.py:52-84

Rule Definitions

Rules are defined in YAML and mapped to the RuleDefinition model. Each rule specifies a name, type, description, and an optional pattern to match against content.

Rule Schema

Field	Type	Description
name	str	Unique identifier for the rule.
type	RuleType	Category: BLOCKING, WARNING, or INFO.
description	str	Human-readable explanation of the violation.
pattern	str | None	Regex or literal string to search for.
action	str	Action taken on match (e.g., "warn" or "error").
enabled	bool	Toggle to activate or deactivate the rule.

Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:612-646, src/flext_quality/rules/engine.py:116-136

Severity Mapping

The engine maps RuleType constants to Severity levels to standardize reporting:

• RuleType.BLOCKING maps to Severity.ERROR
• RuleType.WARNING maps to Severity.WARNING
• RuleType.INFO maps to Severity.INFO

Sources: src/flext_quality/rules/engine.py:151-163

Specialized Validators

Beyond generic regex matching, the system includes FlextQualityValidators for complex architectural and suppression checks.

Forbidden Patterns and Tiers

• ForbiddenPattern: Specifically targets suppression markers that bypass quality gates, such as # type: ignore.
• Tier Validator: Enforces architectural layering rules (e.g., preventing a tier-0 constants.py from importing from a higher-tier services module).

Sources: tests/unit/test_rules_engine_validators.py:149-178

Validator Class Diagram

Specialized validators inherit or extend the base pattern-matching logic to provide domain-specific validation.

Sources: src/flext_quality/rules/engine.py:16-40, tests/unit/test_rules_engine_validators.py:133-178

Implementation Details

The engine performs line-by-line scanning of file content. It supports both raw string validation via validate_content and filesystem-based validation via validate.

Context Handling

You can pass a context mapping to validation methods. The engine attaches this structured data to every violation produced, allowing for metadata like CI stage or branch information to be persisted in results.

Sources: src/flext_quality/rules/engine.py:52-56, tests/unit/test_rules_engine_validators.py:100-112

Pattern Matching Logic

If a rule provides a valid regex pattern, the engine uses u.Quality.compile_pattern for execution. If regex compilation fails or no regex is provided, it falls back to a literal string membership check (rule.pattern in line).

Sources: src/flext_quality/rules/engine.py:116-130, src/flext_quality/utilities.py:53-73

# Example YAML Rule Structure
# Sources: [config/rules/mod/sed.yaml:1-6](https://github.com/flext-sh/flext-quality/blob/7b922cf5df30885cc8d3e152b253521e53368e83/config/rules/mod/sed.yaml#L1-L6)
rules:
  - id: quality-document-runtime-dependencies
    description: Keep the package scope guide aligned.
    include: [AGENTS.md]
    find: 'pattern_to_find'
    replace: 'replacement_text'

Summary

The Rules Engine provides a robust mechanism for enforcing quality standards through declarative YAML configurations. By combining standard regex matching with specialized architectural validators and flexible context injection, it enables consistent code and documentation audits across the FLEXT project. Its design emphasizes failure propagation through p.Result types and provides a clear mapping between rule types and reporting severities.

Sources: src/flext_quality/rules/engine.py:1-12, tests/unit/test_rules_engine_validators.py:16-25