enrichment schema

plan-extended-anaylis/enrichment_strategy.md

@@ -0,0 +1,67 @@
+# Low-Impact Abstraction: The Enrichment Pipeline
+
+## 1. Goal
+Support enhanced codebase analysis (Endpoints, Listeners, etc.) without a massive refactor of the existing JDT state machine parsers.
+
+## 2. The Core Model: `AnalysisResult`
+We wrap the existing output into a container that can hold optional metadata.
+
+```java
+public class AnalysisResult {
+    // Current Core Data
+    private final String name;
+    private final List<Transition> transitions;
+    private final Set<String> startStates;
+    private final Set<String> endStates;
+    
+    // Optional Enhanced Data
+    private CodebaseMetadata metadata = CodebaseMetadata.empty();
+
+    public AnalysisResult(String name, List<Transition> transitions, Set<String> startStates, Set<String> endStates) {
+        this.name = name;
+        this.transitions = transitions;
+        this.startStates = startStates;
+        this.endStates = endStates;
+    }
+
+    public void setMetadata(CodebaseMetadata metadata) {
+        this.metadata = metadata;
+    }
+}
+```
+
+## 3. The "Enricher" Abstraction
+Instead of modifying the parser, we "enrich" the result after it's produced.
+
+```java
+public interface AnalysisEnricher {
+    /**
+     * Examines the core analysis result and the codebase context
+     * to add extra metadata (triggers, endpoints, etc.).
+     */
+    void enrich(AnalysisResult result, CodebaseContext context);
+}
+```
+
+## 4. Implementation Tiers
+
+### Tier 1: Current State (No-Op)
+The `ExportService` calls `enrich()`, but since no enrichers are registered, it just returns the core data. This is zero-impact refactoring.
+
+### Tier 2: Enhanced Analysis
+Once we implement `SpringMvcEnricher` or `RabbitMqEnricher`, we register them. They will:
+1. Scan the `CodebaseContext`.
+2. Find `TriggerPoints`.
+3. Link them to the `transitions` already present in the `AnalysisResult`.
+4. Update the `metadata` field.
+
+## 5. Why this is "Good":
+- **Non-Breaking**: `StateMachineAggregator` remains untouched.
+- **Pluggable**: You can add/remove "Intelligence" without changing the core parser.
+- **Future-Proof**: If you switch from JDT to another tool for code analysis, you only change the `Enricher` implementation.
+
+## 6. Refactoring Steps
+1. **Create `AnalysisResult`** and **`CodebaseMetadata`** classes.
+2. **Update `ExportService.generateOutputs`** to take an `AnalysisResult` object instead of 4 separate parameters.
+3. **Introduce `EnrichmentService`** that holds a list of `AnalysisEnricher`s.
+4. **Modify `ExportService`** to call `enrichmentService.enrich(result, context)` before passing the result to exporters.