Python Rules & Reviewer Profile
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT Quality provides a unified orchestration platform for Python code quality workflows, enforcing standards through a declarative rules engine and predefined agent reviewer profiles. The system integrates static analysis tools, security scanners, and style checkers to maintain a zero-debt baseline across the workspace.
Rules Engine Architecture
The FlextQualityRulesEngine manages the loading and execution of YAML-based declarative rules. It identifies quality violations by scanning project files or raw content strings against a collection of defined patterns.
Rule Loading and Execution Flow
The engine follows a multi-step process to ensure rules are available and correctly applied during validation.
- Initialization: The engine starts with an optional rules path or defaults to
rules/default.yaml. - Rule Loading:
load_rules()triggers theFlextQualityRulesLoaderto parse YAML definitions intoRuleDefinitionmodels. - Discovery:
_get_files()locates Python files (.py) within a target path using CLI utilities. - Content Validation:
validate_content()splits file content into lines and executes pattern matching for every enabled rule. - Violation Collection: Matches generate structured JSON mappings containing the rule name, message, severity, and location.
Sources: src/flext_quality/rules/engine.py:18-60, src/flext_quality/rules/engine.py:80-120
This diagram illustrates the logical flow from rule ingestion to the generation of violation records by the Rules Engine.
Pattern Matching Logic
The engine utilizes u.Quality.compile_pattern to transform string patterns into RegexPattern objects. It supports flags for case sensitivity, multiline search, and dot-all matching. If a pattern is not provided, the engine performs a literal string check.
Sources: src/flext_quality/rules/engine.py:126-140, src/flext_quality/utilities.py:53-71
Rule Modeling and Categorization
Rules are structured using Pydantic models to ensure type safety and consistent validation outputs.
Rule Definitions
A RuleDefinition serves as the primary schema for declarative quality checks.
| Field | Type | Description |
|---|---|---|
name | str | Unique identifier for the rule. |
type | RuleType | Category: Blocking, Warning, or Info. |
description | str | Human-readable check explanation. |
pattern | str | None | Regex pattern for matching. |
action | str | Action taken upon match (e.g., flag as error). |
enabled | bool | Current activation status. |
Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:441-464
Severity Mapping
The engine maps internal rule types to standard severity levels used in reporting.
BLOCKINGmaps toERROR.WARNINGmaps toWARNING.INFOmaps toINFO.
Sources: src/flext_quality/rules/engine.py:165-175
Reviewer Orchestration and External Tools
The reviewer profile orchestrates several industry-standard tools to provide a comprehensive quality assessment. These tools are managed as project dependencies and executed via the CLI.
Integrated Tools Suite
The system assembles multiple backends to detect different issue categories:
- Ruff: Performs linting and formatting.
- basedpyright / MyPy: Executes static type checking.
- Bandit: Scans for security vulnerabilities.
- Pytest: Validates runtime behavior and calculates coverage.
- Vulture: Detects dead or unused code.
Sources: AGENTS.md:27-30, pyproject.toml:75-130, examples/basic/simple_analysis/README.md:25-35
Analysis Output
Quality assessments result in weighted scores and letter grades.
| Issue Category | Description |
|---|---|
| Security | Vulnerabilities and dangerous patterns detected by Bandit. |
| Complexity | High cyclomatic complexity indicators. |
| Dead Code | Unused imports, variables, and functions found by Vulture. |
| Duplicates | Similar or identical code blocks. |
Sources: examples/basic/simple_analysis/README.md:143-155
Agent Reviewer Profiles
FLEXT Quality defines operational profiles for AI agents and automated reviewers to govern repository interactions and task tracking.
Operational Profiles
This diagram depicts how agent behavior varies based on the assigned operational profile.
Profile Characteristics
- Conservative (Default): Uses
bdfor task tracking. Agents do not execute git commits or pushes without explicit requests. They report changed files and validation results at session handoff. - Minimal: Functions as a pointer to
bd prime. Adheres to conservative git policies. - Team-maintainer: Authorized to close issues, run quality gates, commit, and push during session completion if the repository opts in.
Sources: AGENTS.md:121-140
Conclusion
The Python Rules & Reviewer Profile system combines a robust, regex-capable YAML rules engine with a structured orchestration of external analysis tools. By defining strict agent profiles and declarative quality rules, the system ensures that every change meets the established workspace standards for security, complexity, and style before integration.