Introduction & Purpose
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT Quality serves as the unified orchestration platform for Claude Code tooling and agentic quality workflows. It provides a centralized system for executing project checks, validating code against declarative rules, and maintaining quality standards across the FLEXT ecosystem. The project enables developers to perform multi-backend analysis covering security, complexity, and structural integrity.
Sources: README.md:16-18, AGENTS.md:14-16, examples/README.md:21-24
Core Platform Objectives
The primary purpose of FLEXT Quality is to orchestrate various quality analysis tools into a single, cohesive interface. It manages the execution of external tools like Ruff, basedpyright, Bandit, and pytest, providing a unified surface for project validation.
Key Capabilities
- Unified Orchestration: Manages MCP tools, hooks, and external integrations through a facade pattern.
- Declarative Rules: Executes YAML-based rules for code and documentation validation.
- Automated Quality Gates: Enforces standards via CLI commands like
checkandvalidate. - Ecosystem Integration: Connects with
flext-core,flext-api, andflext-webto provide cross-project analysis.
Sources: README.md:32-37, AGENTS.md:27-31, examples/README.md:47-50
Architecture & System Flow
The system uses a layered architecture, separating the public CLI and API surfaces from the underlying rule engines and tool integrations. The FlextQuality facade in api.py acts as the primary entry point for orchestrating hooks and loading rules.
The diagram shows the flow from public interfaces through the central facade to specialized execution components.
Sources: AGENTS.md:18-25, src/flext_quality/rules/engine.py:20-25
Core Components
| Component | Class/Location | Responsibility |
|---|---|---|
| Facade | FlextQuality | Orchestrates hook execution and rule loading. |
| MCP Tools | FlextQualityMcpTools | Provides search_code and execute_hook capabilities. |
| Hook Manager | FlextQualityHookManager | Manages registration and execution of lifecycle hooks. |
| Rules Engine | FlextQualityRulesEngine | Validates content against declarative YAML patterns. |
Sources: AGENTS.md:27-31, src/flext_quality/rules/engine.py:17-20
Analysis Operations
FLEXT Quality performs multi-backend analysis to assess project health. The CodeAnalyzer (demonstrated in examples) calculates quality scores and assigns grades based on detected issues.
The sequence illustrates how the analyzer aggregates data from external tools and the internal rules engine to produce a final assessment.
Sources: examples/README.md:73-87, src/flext_quality/rules/engine.py:65-80
Quality Scoring Standards
The platform employs a standardized grading scale to communicate project health:
- A+ to A: Exceptional to Excellent (93-100 points).
- B+ to B: Very Good to Good (83-92 points).
- C+ to C: Satisfactory (73-82 points).
- D+ to D: Poor (60-72 points).
- F: Failing (Below 60 points).
Sources: examples/basic/simple_analysis/README.md:155-163
Technical Implementation Details
The project utilizes Pydantic v2 for robust data modeling and validation. Models are split across multiple files (e.g., FlextQualityModelsPart01) to maintain modularity and honor LOC ceilings.
Rules Validation Logic
The FlextQualityRulesEngine compiles regex patterns from YAML definitions and checks them against file content. If a match is found, it generates a violation including the rule name, file path, and severity.
# src/flext_quality/rules/engine.py:109-122
def _check_rule(self, rule: m.Quality.RuleDefinition, content: str, filename: str):
violations = []
pattern = u.Quality.compile_pattern(rule.pattern)
lines = content.splitlines()
for line_num, line in enumerate(lines, start=1):
if pattern.search(line):
violations.append({
"rule": rule.name,
"file": filename,
"line": line_num,
"message": rule.description,
"severity": self._rule_type_to_severity(rule.type),
})
return violations
Sources: src/flext_quality/rules/engine.py:100-128, src/flext_quality/_models/flextqualitymodels_part_01.py:19-25
Summary & Significance
FLEXT Quality acts as the governance layer for the FLEXT ecosystem. By consolidating disparate tools into a single orchestration platform, it ensures consistent enforcement of engineering laws, security standards, and documentation quality. It provides the necessary infrastructure for CI/CD quality gates and agentic code maintenance.
Sources: README.md:46-48, AGENTS.md:33-35, tests/README.md:278-285