Architecture Validation Engine

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
• crates/mcb-utils/src/constants/validate/architecture.rs
• config/mcb-validate.toml
• crates/mcb-domain/src/ports/services/validation_service.rs
• crates/mcb-validate/rules/schema.json
• crates/mcb-validate/src/validators/mod.rs

The Architecture Validation Engine is a core component of the Memory Context Browser (MCB) designed to enforce structural integrity and code quality across the workspace. It primarily functions through the mcb-validate crate, utilizing a declarative, rule-based approach to ensure compliance with Clean Architecture principles, SOLID design, and performance standards.

The engine provides a high-performance verification layer that AI coding agents and developers use to maintain persistent codebase understanding. It integrates with the standard Model Context Protocol (MCP) to expose tools such as validate_code, analyze_code, and list_rules, enabling automated architectural gatekeeping.

Sources: README.md:14-16, README.md:67-69, crates/mcb-domain/src/ports/services/validation_service.rs:90-116

Core Components and Architecture

The engine is structured into several specialized validators, each responsible for a specific domain of code health. The ValidationServiceInterface defines the primary operations for workspace-wide validation, file-specific analysis, and complexity metrics gathering.

Validator Modules

The engine leverages a modular registry of validators. Key specialized modules include:

• CleanArchitectureValidator: Enforces layer boundaries and dependency injection patterns.
• DependencyValidator: Validates crate boundaries and forbidden internal dependencies.
• QualityValidator: Scans for code smells like unwrap(), expect(), or excessive file length.
• SolidValidator: Ensures adherence to SOLID principles (e.g., limiting trait method counts).
• Metric Engine: Uses RcaAnalyzer (Rust Code Analysis) to calculate cyclomatic and cognitive complexity.

Sources: crates/mcb-validate/src/validators/mod.rs:7-60, crates/mcb-validate/tests/integration/integration_metrics.rs:11-14

Data Flow for Architectural Analysis

The following diagram illustrates the flow of a validation request through the service interface to the specialized validators and finally to a consolidated report.

Rule Definition and Schema

Validation is driven by a declarative system where rules are defined in YAML/TOML and validated against a strict JSON schema. Rules are categorized by concern (e.g., architecture, quality, naming) and assigned severity levels (error, warning, info).

Rule Metadata Fields

Field	Type	Description
id	String	Unique ID (e.g., CA001, QUAL001).
engine	Enum	The execution engine (e.g., ast, regex, rust-rule-engine).
severity	Enum	Impact level: error, warning, or info.
selectors	Array	Tree-sitter AST selectors for multi-language matching.

Sources: crates/mcb-validate/rules/schema.json:15-100, config/mcb-validate.toml:15-50

Clean Architecture Rule Definitions (CA Series)

The engine specifically targets Clean Architecture violations through the CleanArchitectureViolation enum.

Complexity Metrics and Analysis

The engine provides deep code analysis through complexity metrics. This is handled by the ComplexityReport structure, which aggregates data at both the file and function levels.

Metrics Collected

1. Cyclomatic Complexity: Measures the number of linearly independent paths through source code.
2. Cognitive Complexity: Measures how difficult the code is for humans to understand.
3. Maintainability Index: A calculated score (0-100) representing the relative ease of maintaining the code.
4. Source Lines of Code (SLOC): Total lines excluding comments and whitespace.

Sources: crates/mcb-domain/src/ports/services/validation_service.rs:55-88, crates/mcb-validate/tests/integration/integration_metrics.rs:37-60

Configuration and Defaults

The engine's behavior is governed by mcb-validate.toml, which is embedded in the binary at compile time. It defines thresholds for file sizes, function lengths, and naming patterns.

General Configuration

[rules.quality]
enabled = true
allow_expect_with_message = true
allow_unwrap_in_tests = true
max_file_lines = 500
max_function_lines = 50

[rules.solid]
enabled = true
max_trait_methods = 10
max_impl_methods = 15

Sources: config/mcb-validate.toml:44-55, config/mcb-validate.toml:70-75

Conclusion

The Architecture Validation Engine serves as the primary gatekeeper for the MCB project's structural integrity. By combining Tree-sitter AST parsing, custom Rust rule engines, and standard code analysis metrics, it ensures that every contribution adheres to the defined inward-only dependency flow and business logic isolation required by Clean Architecture.

Sources: README.md:65-75, crates/mcb-validate/src/validators/clean_architecture/validator.rs:60-65