CLI and API Facade Reference
Relevant source files
The following files were used as context for generating this wiki page:
The FLEXT Quality platform provides a unified orchestration surface for code quality tooling and documentation audits. The system exposes its functionality through a Command Line Interface (CLI) and an API facade, integrating multiple static analysis tools such as Ruff, basedpyright, and Bandit into a single workflow.
This reference details the entry points, command structures, and data models that define the public interface of the flext_quality package.
CLI Architecture
The CLI is built using a declarative routing pattern that maps class-based service definitions to command-line routes. It uses the flext_cli framework to register results-based commands, ensuring consistent output and error handling across different quality operations.
The diagram shows the flow from the main entry point through the declarative routes to the underlying execution bridge that invokes external analysis tools.
Sources: src/flext_quality/cli.py:108-144, AGENTS.md:19-25
Core CLI Commands
The CLI supports three primary operations, each represented by a class inheriting from a service base.
| Command | Class | Description |
|---|---|---|
status | FlextQualityCli.Status | Fetches and displays the canonical quality service status. |
check | FlextQualityCli.Check | Executes static analysis (Ruff and basedpyright) on a target path. |
validate | FlextQualityCli.Validate | Performs a full validation including linting, typing, security (Bandit), and tests (Pytest/Coverage). |
Sources: src/flext_quality/cli.py:27-77, src/flext_quality/cli.py:118-129
Command Parameters
Commands that perform analysis utilize standardized parameters for target selection and execution control.
class Check(s[t.SequenceOf[t.StrSequence]]):
"""Run lint + type check on --target-path."""
target_path: Annotated[
Path,
u.Field(default_factory=Path.cwd, description="Target path"),
]
Sources: src/flext_quality/cli.py:37-41
API Facade and Orchestration
The API facade, primarily defined in api.py (referenced via AGENTS.md), acts as the high-level interface for programmatic interaction. It orchestrates complex workflows such as Model Context Protocol (MCP) tool execution and hook management.
Component Map
| Symbol | Kind | Role |
|---|---|---|
FlextQuality | class | Main facade for executing hooks and loading rules. |
FlextQualityMcpTools | class | Provides MCP tools like search_code and execute_hook. |
FlextQualityHookManager | class | Handles hook registration, configuration, and execution. |
Sources: AGENTS.md:27-33
MCP Configuration
The system defines specific constants for MCP integration to ensure reliable communication with agentic tools like Claude.
| Constant | Value | Description |
|---|---|---|
MCP_SERVER_NAME | "flext-quality" | The identifier for the quality MCP server. |
MCP_TIMEOUT_MS | 30000 | Timeout for MCP tool invocations (30 seconds). |
MCP_DEFAULT_PORT | 3100 | Default network port for the MCP server. |
Sources: src/flext_quality/_constants/values.py:38-42
Data Models (Pydantic-2)
FLEXT Quality uses Pydantic-2 models to define the structure of analysis results, configuration, and issues. These models are split into multiple parts to maintain module size limits.
Validation and Issue Models
The Quality.Issue model serves as the canonical representation of a documentation or code violation.
| Field | Type | Description |
|---|---|---|
type | str | Type identifier for the issue. |
severity | str | Severity level (critical, high, medium, low). |
file | str | Path to the file containing the issue. |
line | int | None | Line number of the violation. |
description | str | Human-readable description. |
context | Mapping | None | Structured metadata for the issue. |
Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:446-483
Configuration Schemas
The system uses managed models for complex configurations, such as link validation and content analysis.
The class diagram illustrates the hierarchical structure of the ValidationConfig model and its child configuration components.
Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:433-455, src/flext_quality/_models/flextqualitymodels_part_01.py:317-360
Utility and Support Functions
The u (FlextQualityUtilities) namespace provides helpers for executing shell commands, parsing hook inputs, and compiling quality rules.
Shell Execution
The run_shell_command utility executes external processes with a standard timeout and result mapping.
- Timeout: Defaults to
HOOK_TIMEOUT_MS(5000ms). - Return: A
Result[str]containing stdout on success or an error message on non-zero exit codes.
Sources: src/flext_quality/utilities.py:164-180, src/flext_quality/_constants/values.py:32
Hook Interaction
Utilities for hook orchestration handle the standard JSON input/output format required for agentic tool integration.
parse_hook_input(raw): Validates and coerces raw string input into a JSON mapping.format_hook_output(continue_exec, message, blocked_reason): Serializes hook results into the canonical JSON structure used by the platform.
Sources: src/flext_quality/utilities.py:108-124, src/flext_quality/utilities.py:149-160
Conclusion
The CLI and API facades of FLEXT Quality provide a structured, typed, and declarative way to manage code and documentation quality. By centralizing the configuration and execution of multiple static analysis tools, the system ensures a "zero-debt" baseline for projects within the FLEXT ecosystem. The use of Pydantic-2 models and a dedicated execution bridge allows for robust, predictable interaction whether triggered by a developer via the CLI or an AI agent via the API.