Architecture Validation (mcb-validate)

Relevant source files

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

• crates/mcb-validate/src/validators/clean_architecture/validator.rs
• crates/mcb-validate/src/validators/clean_architecture/violation.rs
• config/mcb-validate.toml
• config/mcb-validate-internal.toml
• crates/mcb-infrastructure/src/validation/service.rs
• crates/mcb-domain/src/ports/services/validation_service.rs
• crates/mcb-validate/src/validators/mod.rs
• AGENTS.md

Architecture Validation (mcb-validate) is a core developer toolset within the MCB project designed to enforce Clean Architecture principles, code quality standards, and structural integrity. It functions as a rule engine that analyzes source code to ensure dependencies flow inward toward the domain layer and that implementation details do not leak across prohibited boundaries. Sources: AGENTS.md:144-152, crates/mcb-validate/Cargo.toml

The system is integrated into the development workflow via make validate and pre-commit hooks, preventing the introduction of architectural "debt" such as circular dependencies, missing identity fields in entities, or direct service instantiation in handlers. Sources: AGENTS.md:112, crates/mcb-validate/src/validators/clean_architecture/violation.rs:13-20

System Architecture and Components

The validation system is structured as a tiered architecture where high-level domain ports are implemented by infrastructure services, which in turn orchestrate specialized validators.

The diagram above illustrates the dependency flow from the domain port to the concrete validator implementations. Sources: crates/mcb-domain/src/ports/services/validation_service.rs:114-142, crates/mcb-infrastructure/src/validation/service.rs:32-42, crates/mcb-validate/src/validators/mod.rs:44-70

Validation Service (InfraValidationService)

The InfraValidationService acts as the primary entry point for validation logic. It implements the ValidationServiceInterface and is responsible for:

• Workspace Traversal: Finding the workspace root by locating Cargo.toml. Sources: crates/mcb-infrastructure/src/validation/service.rs:115-128
• Validator Orchestration: Building and running a suite of named or default validators. Sources: crates/mcb-infrastructure/src/validation/service.rs:84-111
• Complexity Analysis: Calculating SLOC, cyclomatic complexity, and maintainability indices using rust-code-analysis. Sources: crates/mcb-infrastructure/src/validation/service.rs:175-207

Clean Architecture Enforcement

A primary focus of mcb-validate is ensuring strict compliance with Clean Architecture. This is handled by the CleanArchitectureValidator and defined through specific violation types.

Violation Categories (CA Series)

The system identifies several critical architectural violations:

ID	Name	Severity	Purpose
CA001	Domain Implementation	Warning	Detects implementation logic in the domain layer.
CA002	Direct Service Creation	Warning	Flags handlers creating services without Dependency Injection.
CA003	Port Missing Registration	Warning	Ensures port implementations have linkme registration.
CA004	Entity Missing Identity	Warning	Checks for id or uuid fields in domain entities.
CA005	Mutable Value Object	Warning	Detects &mut self methods in value objects.
CA006	Prohibited Import	Warning	Flags server layer importing providers directly.
CA009	Circular Dependency	Error	Blocks Infrastructure from importing the Application layer.

Sources: crates/mcb-validate/src/validators/clean_architecture/violation.rs:24-145

Implementation Logic

The CleanArchitectureValidator utilizes declarative rules (YAML) loaded by a DeclarativeValidator to perform its checks. It uses workspace-specific naming configurations to identify crate boundaries (e.g., mcb-domain, mcb-server). Sources: crates/mcb-validate/src/validators/clean_architecture/validator.rs:48-52, config/mcb-validate-internal.toml:19-35

The sequence shows how validation requests are delegated to specialized engines. Sources: crates/mcb-validate/src/validators/clean_architecture/validator.rs:48-52, crates/mcb-infrastructure/src/validation/service.rs:84-111

Configuration Management

The system uses a layered configuration approach. Default rules are embedded in the binary, while project-specific overrides are defined in TOML files.

Configuration Structure

Section	Description	Key Options
[general]	Global scan settings	exclude_patterns, rules_path, project_prefix
[rules.quality]	Coding standards	max_file_lines (800), allow_unwrap_in_tests (true)
[rules.architecture]	Layer boundaries	server_internal_deps, domain_internal_deps
[rules.naming]	Convention checks	struct_pattern, function_pattern, crate_names

Sources: config/mcb-validate.toml:10-50, config/mcb-validate-internal.toml:1-17

Dependency Layer Boundaries

The internal configuration defines exactly which crates are allowed to depend on each other:

• Server: May depend on domain, infrastructure, and utils.
• Infrastructure: May depend on domain, providers, and utils.
• Providers: May depend on domain and utils.
• Domain: May only depend on utils.

Sources: config/mcb-validate-internal.toml:12-17, AGENTS.md:144-152

Data Models

The validation results are encapsulated in structured reports defined in the domain layer.

ValidationReport

Contains the aggregate results of a validation run.

• total_violations: usize
• errors: usize (Blocks CI/CD)
• warnings: usize
• passed: bool (False if errors > 0)
• violations: Vec<ViolationEntry>

Sources: crates/mcb-domain/src/ports/services/validation_service.rs:11-23

ViolationEntry

Represents a single finding in the source code.

pub struct ViolationEntry {
    pub id: String,          // e.g., "CA001"
    pub category: String,    // e.g., "architecture"
    pub severity: String,    // "ERROR", "WARNING", "INFO"
    pub file: Option<String>,
    pub line: Option<usize>,
    pub message: String,
    pub suggestion: Option<String>,
}

Sources: crates/mcb-domain/src/ports/services/validation_service.rs:30-45

Summary

mcb-validate serves as the automated guardian of the MCB project's architectural integrity. By combining AST-aware analysis, complexity metrics, and strict dependency boundary checks, it ensures that the codebase remains maintainable and adheres to Clean Architecture principles. It transforms architectural guidelines from passive documentation into active, enforceable code gates. Sources: AGENTS.md:144-152, crates/mcb-infrastructure/src/validation/service.rs:25-30