TypeScript Nullability & Workflow Rules

Relevant source files

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

• AGENTS.md
• src/flext_quality/rules/engine.py
• src/flext_quality/_models/flextqualitymodels_part_02.py
• src/flext_quality/_constants/values.py
• src/flext_quality/utilities.py
• pyproject.toml
• README.md

TypeScript Nullability & Workflow Rules define the orchestration and validation logic for maintaining type safety and code quality within the FLEXT ecosystem. The flext-quality platform integrates these rules through a unified command surface to perform project checks and code generation validation.

The system utilizes specialized runtimes, including typescript and basedpyright, to enforce nullability constraints and architectural boundaries. It operates as an alpha-quality orchestration platform for Claude Code tooling and agent-driven workflows.
Sources: README.md:14-22, AGENTS.md:11-15, src/flext_quality/_models/flextqualitymodels_part_02.py:622

Orchestration Architecture

The orchestration architecture manages the registration and execution of quality hooks and rules. The FlextQuality facade serves as the primary interface for loading rules and executing hooks within the project lifecycle.

The diagram shows how the FlextQuality facade routes orchestration requests through the logic layer to specific language runtimes like TypeScript.
Sources: AGENTS.md:18-28, src/flext_quality/_models/flextqualitymodels_part_02.py:622

Execution Workflow

The system processes validation requests through a structured ExecutionRequest model. This model defines the runtime environment, script paths, and resource limits for every quality check.

1. The ExecutionRequest specifies the runtime (e.g., typescript or python).
2. The timeout_ms property enforces execution boundaries to prevent hung processes.
3. The FlextQualityUtilities class runs the shell command and captures the output.
4. The system returns an ExecutionResult containing the success status, exit_code, and standard output/error streams.

Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:615-645, src/flext_quality/utilities.py:165-177

Rules Engine and Validation Logic

The FlextQualityRulesEngine performs YAML-based declarative rules validation. It evaluates project files against configured patterns to identify violations such as forbidden suppression markers or tier-crossing imports.

Rule Evaluation Flow

The sequence diagram illustrates the process of loading declarative rules and checking them against files in the filesystem.
Sources: src/flext_quality/rules/engine.py:46-72, src/flext_quality/utilities.py:126-146

Validation Configuration

The behavior of the validation engine is controlled by the ValidationRunConfig and ValidationConfig models.

Field	Type	Description
enabled	bool	Activates or deactivates the validation run.
fail_on_errors	bool	Exits with failure status if errors are detected.
max_concurrent_requests	PositiveInt	Limits the number of parallel validation tasks.
request_timeout	PositiveInt	Sets the per-request timeout in seconds.
burst_limit	PositiveInt	Permits short bursts of requests above the sustained rate.

Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:404-434, src/flext_quality/_models/flextqualitymodels_part_02.py:581-594

Nullability and Forbidden Patterns

The system enforces strict code standards by scanning for forbidden patterns and suppression markers. These patterns are pre-compiled as regular expressions to ensure high-performance validation during the check cycle.

• Type Suppression: The engine flags # type: ignore markers as violations to prevent developers from bypassing type safety.
• Any Usage: Explicit Any type annotations are detected to maintain strict nullability and type density.
• Tier Violations: The system prevents invalid imports across architectural boundaries (e.g., importing from services or api inside a constants module).

Sources: src/flext_quality/_constants/values.py:90-112, src/flext_quality/rules/engine.py:99-125

Pre-compiled Regex Patterns

The FlextQualityConstantsValues class defines the standard patterns used by the engine.

Pattern Identifier	Regex Pattern	Description
type-ignore	#\s*type:\s*ignore	Detects suppression comments.
any-type	:\s*Any\b	Flags unsafe dynamic types.
tier-violation	from flext_.*\\.(services|api) import	Enforces MRO and tier boundaries.
cast-usage	cast\s*\(	Monitors explicit type casting.

Sources: src/flext_quality/_constants/values.py:94-118

Workflow Integration

FLEXT Quality integrates with CI/CD and development tools via CLI commands. The Check and Validate commands aggregate multiple backends including Ruff, basedpyright, and pytest.

1. Dependency Management: Project dependencies are defined in pyproject.toml, including pydantic for model validation and fastmcp for tool integration.
2. Hook Execution: The FlextQualityMcpTools class provides execute_hook as a first-class orchestration path for AI agents.
3. Governance: The system follows ADR-012 for configuration and ADR-014 for codemod governance.

Sources: AGENTS.md:27-31, pyproject.toml:23-45, README.md:27-34

The TypeScript Nullability & Workflow Rules provide the necessary guardrails for type-safe development. By orchestrating runtimes and enforcing declarative rules, the platform ensures consistent quality across the project lifecycle.