Project Discovery & Iteration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Project Discovery & Iteration is a core mechanism within the FLEXT infrastructure designed to programmatically identify, classify, and iterate over projects within a workspace. This system ensures that build automation, documentation generation, and quality gates are applied consistently across all governed packages. It relies on a structural analysis of the workspace, utilizing pyproject.toml files as the primary source of truth for project identity and metadata.
The scope of this system covers structural discovery (identifying project roots and packages), classification (categorizing projects as infra, integration, test, or domain), and iteration for multi-project operations such as workspace-wide health checks or documentation synchronization.
Sources: src/flext_infra/_utilities/docs_scope.py:16-30, src/flext_infra/_utilities/docs_generate.py:143-165
Workspace Discovery Logic
The discovery process scans the workspace root to identify candidate projects. A valid project is typically identified by the presence of a pyproject.toml file and a valid [project].name field. The system distinguishes between different roles a project can play within a workspace.
Project Selection & Filtering
Discovery can be filtered based on explicit project names or by excluding specific root directories. The system also supports "attached" sub-repos—external repositories with their own pyproject.toml that are not necessarily registered as Git submodules but participate in the workspace operations.
| Component | Description |
|---|---|
| Workspace Member | A project explicitly registered in the uv workspace members list. |
| Attached Project | An external sub-repo opted in via [tool.flext.workspace] attached = true. |
| Excluded Roots | Directories explicitly ignored via scope.exclude_roots in the docs configuration. |
Sources: src/flext_infra/_utilities/docs_scope.py:68-85, src/flext_infra/_utilities/docs_scope.py:277-310
Project Classification Heuristics
Projects are classified based on their name prefixes or explicit metadata in pyproject.toml. This classification determines how the project is treated during documentation generation and quality gate execution.
The diagram shows the logic for assigning a project_class to a discovered project.
Sources: src/flext_infra/_utilities/docs_scope.py:207-230
Iteration Framework
The iteration framework allows for executing standardized operations across all discovered projects. This is managed through "Scopes," which represent either the entire workspace root or individual projects.
The DocScope Model
The DocScope model is the primary data structure for iteration, containing the project's name, absolute path, report directory, and package information.
class DocScope(m.ArbitraryTypesModel):
"""Documentation scope targeting a project or workspace root."""
name: Annotated[t.NonEmptyStr, m.Field(description="Scope name")]
path: Annotated[Path, m.Field(description="Absolute path to scope root")]
report_dir: Annotated[Path, m.Field(description="Report output directory for scope")]
project_class: Annotated[str, m.Field(description="Docs scope classification")] = "root"
package_name: Annotated[str, m.Field(description="Primary package name for scope")] = ""
Sources: src/flext_infra/_models/docs.py:62-76
Scoped Execution Flow
Operations like documentation generation use the run_scoped utility, which builds a list of scopes and applies a handler to each.
The sequence diagram illustrates the flow of scoped iteration for infrastructure tasks.
Sources: src/flext_infra/_utilities/docs.py:120-138, src/flext_infra/_utilities/docs_generate.py:195-235
Metadata Extraction and Resolution
Accurate iteration depends on resolving the Python package name and metadata from code and configuration.
Package Name Resolution
The system resolves the primary package name using a specific order of precedence:
- Override:
[tool.flext.docs].package_nameinpyproject.toml. - Build Target: The first entry in
[tool.hatch.build.targets.wheel.packages]. - Source Discovery: The first directory found under
src/containing an__init__.py.
Sources: src/flext_infra/_utilities/docs_scope.py:232-251
Public API Contract Extraction
During iteration, the system extracts a "Public Contract" for each project. This includes identifying exported symbols (via __all__), facades (prefixed with Flext), and modules. It uses Rope analysis to verify that exported symbols actually exist in the source code.
| Field | Description |
|---|---|
aliases | Short exports like c, t, u used for MRO access. |
facades | Primary entry point classes for the package. |
target_map | Mapping of exported symbols to their defining modules. |
public_symbols | List of symbols verified to exist via static analysis. |
Sources: src/flext_infra/_utilities/docs_api.py:126-193
Reporting and Outcome Tracking
Every iteration produces standardized reports in Markdown and JSON/SARIF formats to track the success or failure of the operation across the workspace.
Workspace Report Structure
The FlextInfraWorkspaceCheckReportsMixin generates a summary table and detailed breakdown of every project processed during the iteration.
# Workspace Check Report
| Project | Status | Errors |
|---|---:|---:|
| flext-core | PASS | 0 |
| flext-infra | FAIL | 2 |
Sources: src/flext_infra/check/_workspace_check_reports.py:25-50
Summary
Project Discovery & Iteration provides a structured and automated way to manage a large collection of Python projects. By combining filesystem discovery with pyproject.toml metadata and static code analysis, it creates a reliable iteration loop for documentation, validation, and maintenance tasks. This ensures that every project in the FLEXT workspace adheres to the same architectural standards and quality gates.