Rules Engine

Relevant source files

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

• src/flext_cli/_models/rules.py
• src/flext_cli/_utilities/_rules_parts/flextcliutilitiesrules_part_01.py
• src/flext_cli/_utilities/_rules_parts/flextcliutilitiesrules_part_02.py
• tests/unit/_cases/test_rules_cov/testsflextclirulescov_part_01.py
• tests/unit/_cases/test_rules_cov/testsflextclirulescov_part_02.py
• src/flext_cli/_utilities/_rules_parts/__init__.py

The Rules Engine in flext-cli provides a declarative framework for loading, resolving, and validating local rule definitions. It is designed to handle both packaged default rules and local YAML-based configurations, enabling flexible extension of CLI behavior through structured metadata. The engine facilitates the extraction of scoped configurations from settings and the matching of specific rule identifiers against catalogs of actions and checks.

Sources: src/flext_cli/_utilities/_rules_parts/flextcliutilitiesrules_part_01.py:1-12, src/flext_cli/_models/rules.py:1-12

Architecture and Components

The Rules Engine is structured around a utility-based implementation that interacts with Pydantic domain models for configuration validation. It operates by resolving rule directories, loading YAML registries, and parsing individual rule files into typed structures.

Key Components

• Rule Resolver: Normalizes and extracts declarative rule scopes from JSON-like settings.
• Definition Loader: Iterates through directories to load local YAML definitions, filtering them by rule kind and availability.
• Catalog Matcher: Maps rule actions and checks to specific implementations defined in a RuleCatalog.

Sources: src/flext_cli/_utilities/_rules_parts/flextcliutilitiesrules_part_01.py:16-30, src/flext_cli/_utilities/_rules_parts/flextcliutilitiesrules_part_02.py:18-35

Data Flow for Rule Loading

The following diagram illustrates the sequence of operations performed when loading local rule definitions.

This flow ensures that only active and applicable rules are loaded into the runtime environment.

Sources: src/flext_cli/_utilities/_rules_parts/flextcliutilitiesrules_part_02.py:25-115

Core Data Models

The system uses Pydantic models to ensure that options and definitions provided to the engine are strictly typed and validated.

LocalDefinitionsOptions

This model defines the parameters required to load and filter local rules.

Field	Type	Description
package_rules_dir	Path	Directory for default rule YAMLs
rule_filters	t.StrSequence	Glob/substring filters for rule IDs
rule_catalog	RuleCatalog[TRuleKind]	Map of rule kinds to matchers
registry_filename	str	Default: engine-registry.yml
rules_key	str	Top-level key in YAML (default: rules)
rule_id_key	str	Key for unique identifier (default: id)

Sources: src/flext_cli/_models/rules.py:16-65

Logic and Implementation

Rule Scope Resolution

The engine can extract specific subsets of configuration from a larger settings object based on a scope_key and a list of allowed_keys. This prevents irrelevant settings from polluting rule definitions.

@staticmethod
def rules_resolve_scope(
    settings: t.JsonValue,
    *,
    scope_key: str,
    allowed_keys: t.StrSequence,
) -> t.JsonMapping:
    normalized = uj.json_as_mapping(settings)
    scope_raw = normalized.get(scope_key)
    scope_map = uj.json_as_mapping(scope_raw)
    return t.Cli.JSON_MAPPING_ADAPTER.validate_python({
        key: value for key, value in scope_map.items() if key in allowed_keys
    })

Sources: src/flext_cli/_utilities/_rules_parts/flextcliutilitiesrules_part_01.py:19-32

Registry Loading Hierarchy

When loading a rules registry, the engine follows a specific search order to allow local overrides of packaged defaults:

1. Local Directory: Checks for a registry file in the directory resolved from the configuration path.
2. Package Directory: Falls back to the packaged rules directory provided in the options.

Sources: src/flext_cli/_utilities/_rules_parts/flextcliutilitiesrules_part_01.py:56-78, tests/unit/_cases/test_rules_cov/testsflextclirulescov_part_01.py:77-100

Multi-Catalog Matching

The engine supports matching rules against multiple catalogs simultaneously (e.g., standard rules and file-specific rules). It uses the action_key or check_key within the YAML definition to determine which catalog entry applies.

Validation and Error Handling

The Rules Engine employs a "fail-fast" strategy. If a rule file is found but cannot be validated against the provided catalogs, or if the YAML structure is invalid, the engine returns a failure Result.

• Missing ID: Rules without a valid ID key are skipped silently.
• Disabled Rules: Rules with the enabled key set to False are ignored during the loading phase.
• Filter Exclusion: Rules that do not match the glob or substring patterns in rule_filters are excluded.
• Validation Failures: If rules exist but fail schema validation or contain unknown actions, a failure result containing the specific error details is returned.

Sources: src/flext_cli/_utilities/_rules_parts/flextcliutilitiesrules_part_02.py:55-75, tests/unit/_cases/test_rules_cov/testsflextclirulescov_part_02.py:100-115

Summary

The Rules Engine acts as a robust configuration layer within flext-cli, ensuring that behavioral rules are loaded from disk with high integrity. By leveraging Pydantic models and hierarchical lookups, it allows developers to define complex CLI logic in YAML while maintaining strict type safety and clear error reporting during the resolution process.