Compiler Architecture Validator

Validates Fakt compiler plugin implementation follows industry-standard architectural patterns and best practices.

Core Mission

Ensures Fakt follows proven Metro patterns for Kotlin compiler plugins: two-phase FIR→IR compilation, context-driven generation, proper extension registration, and professional code organization.

Instructions

1. Determine Validation Scope

Extract from conversation:

• •Specific component: "validate Metro alignment for UnifiedFaktIrGenerationExtension"
• •General check: "check Metro patterns", "validate architecture"
• •Default: Validate ALL components if no specific mention

Components available for validation:

1. •CompilerPluginRegistrar - Plugin registration and configuration
2. •IrGenerationExtension - IR generation logic
3. •FirExtensionRegistrar - FIR phase detection
4. •Context Pattern - IrFaktContext usage
5. •Error Handling - Diagnostic patterns
6. •Testing Structure - Test organization

If unclear:

Ask: "Would you like me to validate a specific component or check all Metro pattern alignment?"
Options: all | plugin-registrar | ir-extension | fir-extension | context | error-handling | testing

2. Load Metro Pattern Reference

For detailed Metro patterns:

• •Consult resources/metro-patterns-reference.md
• •Or use fakt-docs-navigator: .claude/docs/development/metro-alignment.md

Metro Architecture Baseline:

• •Two-phase FIR → IR compilation
• •Context-driven generation (IrMetroContext)
• •CompilerPluginRegistrar with supportsK2 = true
• •FirExtensionRegistrar + IrGenerationExtension
• •Professional error handling with diagnostics

3. Validate CompilerPluginRegistrar Pattern

Read Fakt implementation:

Read compiler/src/main/kotlin/com/rsicarelli/fakt/compiler/FaktCompilerPluginRegistrar.kt

Metro Pattern Checklist:

• • Extends CompilerPluginRegistrar
• • override val supportsK2: Boolean = true
• • Options loading pattern (FaktOptions.load())
• • FIR extension registration (FirExtensionRegistrarAdapter)
• • IR extension registration (IrGenerationExtension)
• • Proper enabled check before registration

Comparison with Metro:

// Metro pattern:
class MetroCompilerPluginRegistrar : CompilerPluginRegistrar() {
    override val supportsK2: Boolean = true

    override fun ExtensionStorage.registerExtensions(configuration: CompilerConfiguration) {
        val options = MetroOptions.load(configuration)
        if (!options.enabled) return

        FirExtensionRegistrarAdapter.registerExtension(MetroFirExtensionRegistrar(...))
        IrGenerationExtension.registerExtension(MetroIrGenerationExtension(...))
    }
}

// Fakt should follow similar structure

Validation Output:

🔍 VALIDATING: CompilerPluginRegistrar Pattern

📋 Metro Pattern Requirements:
✅ CompilerPluginRegistrar inheritance
✅ supportsK2 = true
✅ Options loading
✅ FIR extension registration
✅ IR extension registration

📋 Fakt Implementation:
{Check each requirement and mark ✅ or ❌}

🎯 ALIGNMENT SCORE: {percentage}%
{List deviations if any}

4. Validate IrGenerationExtension Pattern

Read Fakt implementation:

Read compiler/src/main/kotlin/com/rsicarelli/fakt/compiler/ir/UnifiedFaktIrGenerationExtension.kt

Metro Pattern Checklist:

• • Extends IrGenerationExtension
• • Creates context object (IrFaktContext)
• • Uses context() for scoping
• • Separates generate() and internal generation logic
• • Proper moduleFragment traversal
• • Error handling with diagnostics

Comparison with Metro:

// Metro pattern:
class MetroIrGenerationExtension : IrGenerationExtension {
    override fun generate(moduleFragment: IrModuleFragment, pluginContext: IrPluginContext) {
        val context = IrMetroContext(pluginContext, messageCollector, symbols)
        context(context) { generateInner(moduleFragment) }
    }

    context(context: IrMetroContext)
    private fun generateInner(moduleFragment: IrModuleFragment) {
        // Context-scoped generation logic
    }
}

// Fakt should align

Validation Output:

🔍 VALIDATING: IrGenerationExtension Pattern

📋 Metro Pattern Requirements:
✅ IrGenerationExtension inheritance
✅ Context object creation
✅ context() scoping usage
✅ Separated generation logic
✅ Module traversal patterns

📋 Fakt Implementation:
{Check each requirement}

🎯 ALIGNMENT SCORE: {percentage}%
{List deviations}

5. Validate Context Pattern

Check for IrFaktContext:

Grep pattern="class.*Context" compiler/src/main/kotlin/com/rsicarelli/fakt/compiler/

Metro Context Pattern Requirements:

• • Dedicated context class (IrFaktContext)
• • Bundles all generation dependencies
• • Contains pluginContext, messageCollector, options
• • Used with context() for scoping
• • Provides context-specific utilities

Comparison:

// Metro pattern:
data class IrMetroContext(
    val pluginContext: IrPluginContext,
    val messageCollector: MessageCollector,
    val symbols: Symbols,
    val options: MetroOptions
) {
    val irFactory = pluginContext.irFactory
    val irBuiltIns = pluginContext.irBuiltIns
}

// Fakt should have similar IrFaktContext

Validation Output:

🔍 VALIDATING: Context Pattern

📋 Metro Pattern Requirements:
✅ Dedicated context class
✅ Bundles dependencies
✅ Used for scoping
✅ Provides utilities

📋 Fakt Implementation:
{Check each}

🎯 ALIGNMENT SCORE: {percentage}%

6. Validate FIR Phase Implementation

Check for FirExtensionRegistrar:

Read compiler/src/main/kotlin/com/rsicarelli/fakt/compiler/fir/FaktFirExtensionRegistrar.kt

Metro FIR Pattern Requirements:

• • FirExtensionRegistrar implementation
• • @Fake annotation detection in FIR phase
• • Validation before IR phase
• • Passes metadata to IR phase
• • Proper error reporting

Validation Output:

🔍 VALIDATING: FIR Phase Implementation

📋 Metro Pattern Requirements:
✅ FirExtensionRegistrar present
✅ Annotation detection
✅ Validation logic
✅ Metadata passing

📋 Fakt Implementation:
{Check each}

🎯 ALIGNMENT SCORE: {percentage}%

7. Validate Error Handling Patterns

Check diagnostic patterns:

Grep pattern="(messageCollector|reportError|reportWarning)" compiler/src/main/kotlin/com/rsicarelli/fakt/compiler/

Metro Error Handling Requirements:

• • MessageCollector usage
• • Proper error reporting with location
• • Warning for non-critical issues
• • Graceful failures (no crashes)
• • User-friendly error messages

Comparison:

// Metro pattern:
if (!isValidComponent(element)) {
    context.messageCollector.report(
        CompilerMessageSeverity.ERROR,
        "Invalid component structure",
        CompilerMessageLocationWithRange.create(element.location)!!
    )
    return
}

// Fakt should follow similar diagnostic patterns

Validation Output:

🔍 VALIDATING: Error Handling Patterns

📋 Metro Pattern Requirements:
✅ MessageCollector usage
✅ Error reporting with location
✅ Warning for non-critical
✅ Graceful failures

📋 Fakt Implementation:
{Check each}

🎯 ALIGNMENT SCORE: {percentage}%

8. Validate Testing Structure

Check test organization:

ls -la compiler/src/test/kotlin/com/rsicarelli/fakt/compiler/

Metro Testing Pattern Requirements:

• • Separate compiler-tests/ module (optional, future)
• • Comprehensive integration tests
• • Test fixtures for common scenarios
• • Compilation validation tests
• • GIVEN-WHEN-THEN naming

Note: Metro has compiler-tests/ module. Fakt can follow similar organization in future.

Validation Output:

🔍 VALIDATING: Testing Structure

📋 Metro Pattern Recommendations:
⚠️ Dedicated compiler-tests module (future improvement)
✅ Integration tests present
✅ GIVEN-WHEN-THEN patterns
✅ Compilation validation

📋 Fakt Implementation:
{Check each}

🎯 ALIGNMENT SCORE: {percentage}%

9. Generate Comprehensive Report

Overall alignment report:

═══════════════════════════════════════════════════
🏗️ METRO PATTERN COMPLIANCE VALIDATION REPORT
═══════════════════════════════════════════════════

📊 OVERALL ALIGNMENT SCORE: {average}%

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ COMPONENT SCORES:

1. CompilerPluginRegistrar Pattern: {score}%
   {Brief status and key points}

2. IrGenerationExtension Pattern: {score}%
   {Brief status}

3. Context Pattern: {score}%
   {Brief status}

4. FIR Phase Implementation: {score}%
   {Brief status}

5. Error Handling: {score}%
   {Brief status}

6. Testing Structure: {score}%
   {Brief status}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 KEY ALIGNMENTS (What's working well):
- {List strong alignments}

⚠️  DEVIATIONS FROM METRO (Areas for improvement):
- {List deviations}

📋 RECOMMENDATIONS:
1. {Recommendation 1}
2. {Recommendation 2}
...

🔗 REFERENCES:
- Metro Source: metro/compiler/src/main/kotlin/.../
- Fakt Docs: .claude/docs/development/metro-alignment.md
- Pattern Guide: resources/metro-patterns-reference.md

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✨ NEXT STEPS:
{Actionable next steps to improve alignment}

═══════════════════════════════════════════════════

10. Suggest Improvements

Based on validation results, suggest:

High Priority (Low alignment scores):

• •Missing patterns that are critical
• •Architectural deviations that impact quality
• •Safety/correctness issues

Medium Priority:

• •Style/organization improvements
• •Optional Metro patterns not yet adopted
• •Documentation gaps

Low Priority:

• •Nice-to-have Metro features
• •Advanced patterns for future consideration

Supporting Files

Progressive disclosure for Metro patterns:

• •resources/metro-patterns-reference.md - Complete Metro pattern catalog (loaded on-demand)
• •resources/compiler-plugin-best-practices.md - Best practices from Metro (loaded on-demand)
• •resources/metro-code-examples.md - Code examples from Metro source (loaded on-demand)

Related Skills

This Skill composes with:

• •fakt-docs-navigator - Access Metro alignment docs
• •kotlin-ir-debugger - Debug IR generation issues found
• •kotlin-api-consultant - Validate Kotlin API usage

Validation Scope Matrix

Best Practices

1. •Compare don't copy - Understand Metro patterns but adapt to Fakt needs
2. •Score objectively - Base scores on actual code inspection
3. •Prioritize critical patterns - CompilerPluginRegistrar and IrGenerationExtension first
4. •Document deviations - Explain why Fakt deviates if intentional
5. •Actionable recommendations - Suggest concrete next steps

Metro Alignment Philosophy

Why follow Metro patterns:

• •Proven in production (Slack uses Metro)
• •K2 compiler ready
• •Professional architecture
• •Clear separation of concerns
• •Robust error handling

When to deviate:

• •Fakt-specific requirements
• •Simpler patterns work better
• •Different problem domain (test fakes vs DI)

Goal: Not blind copying but principled adaptation

Known Metro Patterns to Follow

1. •Two-Phase Compilation: FIR detection → IR generation
2. •Context-Driven: Bundle dependencies in context object
3. •Options Pattern: Load configuration from CompilerConfiguration
4. •Error Diagnostics: MessageCollector with proper severity
5. •K2 Support: supportsK2 = true
6. •Testing Rigor: Comprehensive compiler tests

Current Fakt Status (Phase 1)

Expected alignment ~70-80% because:

• •✅ IR generation working
• •✅ Two-phase approach started
• •⚠️ Context pattern partial
• •⚠️ FIR phase basic
• •⚠️ Testing structure evolving

Phase 2 Target: 90%+ alignment with full Metro patterns