Workspace Validation Scanning

Relevant source files

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

• src/flext_infra/validate/scanner.py
• src/flext_infra/validate/skill_validator.py
• src/flext_infra/validate/basemk_validator.py
• src/flext_infra/validate/namespace_validator.py
• src/flext_infra/check/_workspace_check_reports.py
• src/flext_infra/_utilities/docs_validate.py

Workspace Validation Scanning is a multi-layered infrastructure suite within the FLEXT ecosystem designed to enforce architectural discipline, maintain code quality, and verify documentation integrity. It operates through a series of "Quality Gates" and specialized validators that perform static analysis, pattern matching, and rule-based checks across all projects in a workspace.

The system ensures that projects adhere to canonical structures—such as the correct implementation of base.mk files and namespace hierarchies—while providing automated reporting in Markdown and SARIF formats. These validations are critical for maintaining a "zero-debt baseline" and ensuring that all governed projects remain synchronized with the workspace's global standards.

Validation Architecture

The scanning architecture is modular, consisting of specific validator classes that inherit from base service protocols. These validators are orchestrated to check different aspects of the workspace, from low-level text patterns to high-level architectural rules.

Core Validator Components

Component	Responsibility	Source
FlextInfraSkillValidator	Validates workspace skills against rules.yml using AST-grep or custom scripts.	[skill_validator.py:33](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/skill_validator.py#L33)
FlextInfraNamespaceValidator	Enforces static namespace rules (NS-000 through NS-003) via rope.	[cli_routes.py:279](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/cli_routes.py#L279)
FlextInfraBaseMkValidator	Verifies that project base.mk files are in sync with canonical templates.	[basemk_validator.py:27](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/basemk_validator.py#L27)
FlextInfraTextPatternScanner	Performs regex-based scanning across text files for forbidden or required patterns.	[cli_routes.py:252](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/cli_routes.py#L252)
FlextInfraDocValidator	Validates documentation structure, links, and project portal integrity.	[cli_routes.py:171](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/cli_routes.py#L171)

The following diagram illustrates the flow of a typical validation cycle, from project discovery to report generation:

The diagram shows how various validators feed results into a unified reporting layer. Sources: [skill_validator.py:102-120](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/skill_validator.py#L102-L120), [_workspace_check_reports.py:22-35](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/_workspace_check_reports.py#L22-L35)

Skill Validation and Policy Gates

The FlextInfraSkillValidator uses a data-driven approach to enforce policy gates. It relies on a rules.yml file located within each skill folder to define scan targets and specific rules.

Baseline Comparison

Validation can operate in two modes:

1. Strict Mode: Any violation results in a failure.
2. Baseline Mode: Violations are compared against a stored baseline. The validation passes if the current violation count is less than or equal to the baseline.

Sources: [skill_validator.py:42-50](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/skill_validator.py#L42-L50), [skill_validator.py:148-155](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/skill_validator.py#L148-L155)

Rule Evaluation Logic

The validator scans defined globs (defaulting to **/*.py) and applies AST-grep or script-based rules. It aggregates counts of violations by group and calculates an overall pass/fail status based on the selected strategy (Total vs. Per-Group).

def _skill_report_model(
    self,
    context: m.Infra.SkillReportContext,
) -> m.Infra.ValidationReport:
    """Build the canonical skill validation report model."""
    total = sum(context.counts.values())
    passed = (
        total == 0
        if context.mode == c.Infra.OperationMode.STRICT
        else self._apply_baseline_comparison(
            context.rules,
            context.root,
            context.skill_name,
            context.counts,
            total,
        )
    )
    # ... report generation

Sources: [skill_validator.py:148-168](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/skill_validator.py#L148-L168)

Namespace Governance

The FlextInfraNamespaceValidator enforces "Engineering Law" regarding symbol placement and visibility. It specifically targets four primary rules:

• NS-000: Top-level class naming and file structure discipline.
• NS-001: Constant placement; prevents "loose" constants by requiring they reside within Constants classes.
• NS-002: Type and Protocol placement; enforces that TypeVar and TypeAlias reside in typings.py.
• NS-003: Direct runtime import restrictions; forces the use of namespaced MRO aliases (e.g., c, m, p, t, u).

Sources: [cli_routes.py:279-284](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/cli_routes.py#L279-L284), [namespace_validator_tests.py:65-220](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/namespace_validator_tests.py#L65-L220)

Documentation Validation

Documentation scanning ensures that the project portal is not "fake markdown" but is generated from real code and docstrings.

Required Path Verification

The system checks for a set of mandatory files in both the workspace root and individual project scopes.

Scope	Required Files (Examples)
Root	README.md, docs/index.md, mkdocs.yml, docs/architecture/README.md
Project	README.md, docs/index.md, docs/api-reference/README.md

Sources: [docs_validate.py:90-112](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/docs_validate.py#L90-L112)

Public API Contract Validation

The docs_contract_messages helper verifies that a project's __init__.py properly exports a public API. If a package has no discovered modules or exports, it is flagged as a contract violation.
Sources: [docs_validate.py:118-135](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/docs_validate.py#L118-L135)

Reporting and SARIF Integration

Validation results are processed by the FlextInfraWorkspaceCheckReportsMixin to create standardized outputs.

Markdown Reports

A human-readable report is generated containing:

• A summary table with Project, Status (PASS/FAIL), and Error counts.
• Detail sections for each project listing specific gate executions and issue descriptions.

Sources: [_workspace_check_reports.py:27-58](https://github.com/flext-sh/flext-infra/blob/7263716345a1c14eb1247b4be4e93948e0895347/_workspace_check_reports.py#L27-L58)

SARIF 2.1.0 Support

For integration with CI/CD tools and IDEs, the system generates SARIF (Static Analysis Results Interchange Format) files. This includes mapping validator "issues" to SARIF rules, levels (warning/error), and physical locations (URI, line, column).

Summary

Workspace Validation Scanning provides the automated enforcement necessary to keep large FLEXT workspaces coherent. By combining pattern scanning, namespace rules, and baseline-aware skill validation, the system prevents architectural drift and ensures that quality gates are met before changes are integrated. Significant findings are surfaced through both developer-friendly Markdown and machine-readable SARIF reports, allowing for seamless integration into automated build pipelines.