mcp-zen-of-languages: Instructions file for GitHub Copilot

Analyzer Architecture Refactoring

Problem Statement

The original PythonAnalyzer.analyze() method had multiple anti-patterns:

1. ❌ 400+ lines in a single method
2. ❌ Deeply nested (5+ levels)
3. ❌ Mixed concerns (parsing, metrics, detection, formatting)
4. ❌ Dictionary-based config instead of Pydantic
5. ❌ Hard to extend to other languages
6. ❌ Hard to test individual detectors
7. ❌ No separation of concerns

Solution: Architectural Patterns

We use a combination of proven design patterns:

1. Template Method Pattern (Base Structure)

Purpose: Define the analysis algorithm skeleton in the base class, with hooks for language-specific behavior.

class BaseAnalyzer(ABC):
    def analyze(self, code: str, ...) -> AnalysisResult:
        # Template method - defines the flow
        context = self._create_context(...)
        context.ast_tree = self.parse_code(code)        # Hook
        metrics = self.compute_metrics(...)             # Hook
        violations = self.pipeline.run(context, config)
        return self._build_result(context, violations)

    @abstractmethod
    def parse_code(self, code: str) -> ParserResult:
        pass  # Language-specific hook

    @abstractmethod
    def compute_metrics(self, ...) -> tuple:
        pass  # Language-specific hook

Benefits:

• ✅ Common flow defined once
• ✅ Language-specific parts isolated
• ✅ Easy to maintain the overall structure

2. Strategy Pattern (Detectors)

Purpose: Encapsulate each violation detection algorithm in its own class.

class ViolationDetector(ABC):
    @abstractmethod
    def detect(self, context: AnalysisContext, config: AnalyzerConfig) -> list[Violation]:
        pass

class CyclomaticComplexityDetector(ViolationDetector):
    def detect(self, context, config) -> list[Violation]:
        # Focused, single-responsibility logic
        ...

class NestingDepthDetector(ViolationDetector):
    def detect(self, context, config) -> list[Violation]:
        # Each detector is independent
        ...