Make Target Registry & Rendering

Relevant source files

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

• src/flext_tests/_utilities/make_rendering.py
• src/flext_tests/_utilities/_make_parts/make_rendering_part_01.py
• src/flext_tests/_utilities/_make_parts/make_rendering_part_02.py
• src/flext_tests/_models/make.py
• src/flext_tests/_utilities/_make_parts/make_parsing_part_01.py
• src/flext_tests/_utilities/_make_parts/make_parsing_part_02.py
• src/flext_tests/_utilities/_make_parts/make_contract_part_01.py

The Make Target Registry & Rendering system provides a metadata-driven infrastructure for discovering, validating, and displaying information about the make command ecosystem within FLEXT. It transforms raw file headers into a structured registry that powers CLI help interfaces, dry-run outputs, and execution contracts.

This module ensures that any script or target promoted via a flext-command header is consistently parsed into a formal MakeCommand model. These models are then used to generate dynamic documentation and validate that environment-backed parameters meet the project's governance and technical requirements.
Sources: src/flext_tests/_models/make.py:1-12, src/flext_tests/_utilities/_make_parts/make_rendering_part_02.py:10-15

Core Data Models

The system is built upon a hierarchy of Pydantic models that define the structure of the Make registry and its constituent parts.

Command Structure

A MakeCommand represents a single executable action discovered from the workspace. It contains metadata regarding its functional domain, usage examples, and mutation status.

Field	Type	Description
verb	str	Canonical make verb (e.g., check, test, val).
what	str	Canonical WHAT value for command selection.
domain	str	Functional command domain for categorization.
mutates	bool	Flag indicating if the command alters workspace state.
params	Sequence[MakeParam]	Environment-backed parameter contract.
rules	StrSequence	Governance rules enforced by the command.

Sources: src/flext_tests/_models/make.py:46-77

Registry Model

The MakeRegistry acts as a central repository, indexing all discovered commands by their verb and "WHAT" identifier.

The diagram above shows the relationship between the central registry and the hierarchical data components.
Sources: src/flext_tests/_models/make.py:21-95

Registry Discovery and Parsing

The system populates the registry by scanning files for specific TOML-formatted headers. The FlextTestsMakeParsingUtilitiesMixin handles the extraction of this metadata.

1. Header Extraction: Reads the first 220 lines of a file to locate flext-command markers.
2. TOML Validation: Converts the extracted text into a MakeTomlTable and validates it against the Pydantic schema.
3. Body Verification: Uses the ast module to determine if a Python file contains executable code outside of its metadata (header-only vs. script).
   Sources: src/flext_tests/_utilities/_make_parts/make_parsing_part_01.py:16-65

Rendering Infrastructure

The rendering layer converts structured MakeRegistry data into human-readable text for the CLI. This is primarily handled by FlextTestsMakeRenderingUtilitiesMixin.

Global Help Generation

The make_render_global_help function generates the top-level dispatcher help, listing all available verbs, their default commands, summaries, and aliases.

The flow illustrates how the registry is traversed to build the global help interface.
Sources: src/flext_tests/_utilities/_make_parts/make_rendering_part_02.py:18-38

Detailed Verb and Command Help

Detailed help can be rendered for specific verbs or individual actions:

• Verb Help: Lists all "WHAT" actions available for a specific verb, including their parameters and examples.
• Command Help: Displays exhaustive details for a single command, including required vs. optional parameters, mutation rules, and long-form descriptions.
  Sources: src/flext_tests/_utilities/_make_parts/make_rendering_part_02.py:40-116

Mutation Logic and Dry-Runs

The system distinguishes between read-only and mutating commands. Commands that mutate workspace state often require an APPLY=Y environment variable.

• Mutation Markers: Help output includes markers like [mutates] or [conditional-mutates].
• Dry-Run Output: If a mutating command is invoked without APPLY=Y, the system renders a "DRY-RUN" summary showing what would have happened.
  Sources: src/flext_tests/_utilities/_make_parts/make_rendering_part_01.py:31-48, src/flext_tests/_utilities/_make_parts/make_rendering_part_02.py:126-153

Contract Validation

The FlextTestsMakeContractUtilitiesMixin ensures that commands and their invocations adhere to established rules.

• Invocation Validation: Checks that all required parameters are present in the environment and that provided values match allowed choices.
• Command Contract Validation: Verifies that mutating commands explicitly declare APPLY as a parameter and that file naming conventions (e.g., what.py or .sh) are followed.
• Conditional Mutation: Validates that if a command mutates only under certain conditions (e.g., TARGET=prod), those conditions reference valid parameters and choices.
  Sources: src/flext_tests/_utilities/_make_parts/make_contract_part_01.py:27-104

Summary

The Make Target Registry & Rendering system serves as the backbone for FLEXT's task execution interface. By utilizing Pydantic models and TOML header parsing, it creates a self-documenting ecosystem where commands are automatically registered, validated against strict contracts, and presented to the user with consistent help and dry-run capabilities.