spring-state-machine-renderer/plan-extended-anaylis/PLAN.md

Execution Plan for Extended Analysis (Revised for Robustness)

Phase 0: Surgical Refactoring (The Enrichment Hook)

• Create AnalysisResult and CodebaseMetadata models.
• Update ExportService.generateOutputs to accept AnalysisResult.
• Implement EnrichmentService and AnalysisEnricher interface.
• Wrap current parser outputs in AnalysisResult within ExportService.

Phase 1: Foundation & Semantic Core

• JDT Binding Resolution: Configure ASTParser with project classpath and setResolveBindings(true).
• Workspace Scoping: Implement scanner with configurable exclude patterns (test/, build/, node_modules/).
• ConstantResolver: Implement lookup for public static final constants across class boundaries using JDT bindings.
• Basic PropertyResolver: Scan application.properties/yml for simple key-value pairs.
• Implement JdtIntelligenceProvider as the primary semantic analyzer.

Phase 2: Trigger Discovery & Instance Identity

• GenericEventDetector: Find sendEvent calls using ASTVisitor.
• InstanceIdentifier: Detect which State Machine is being targeted (via @Qualifier, bean names, or generic types StateMachine<S, E>).
• Trigger Filter: Link sendEvent calls to specific SM instances to avoid noise in multi-SM projects.
• Enhance CodebaseContext to provide mapping from MethodDeclaration to its callers using bindings.

Phase 3: Entry Point Mapping

• SpringMvcDetector: Detect REST endpoints (using ConstantResolver for paths).
• MessageListenerDetector: Detect Kafka/JMS listeners (using ConstantResolver for topics/queues).
• ConfigurableTriggerDetector: Support user-defined patterns for custom frameworks.

Phase 4: Call Graph Integration

• Develop a call graph builder to link Entry Points to Trigger Points via intermediate service calls.
• Support inheritance in call graph resolution (using JDT bindings to resolve method overrides).

Phase 5: Visualization & Diagnostics

• Update ExportService to include trigger information.
• Update DOT/SCXML exporters to show entry points.
• Diagnostic Nodes: Show "Potential/Unresolved Trigger" nodes when a sendEvent is found but the event name or SM instance cannot be resolved.

Phase 6: Validation (Milestone 1)

• Create a "Complex Sample Project" with REST controllers, services, and multiple state machines.
• Add unit tests for each detector and the aggregator.
• Verify that inheritance in both state machine config and controllers is correctly handled.

Phase 7: Advanced Resolution & Data Flow

• Complex ValueResolver: Handle string concatenations and variable references in annotations/logic.
• Payload Analysis: Extract payload types from entry points and track field usage in sendEvent calls.
• @Value Propagation: Track property values injected into fields and constructors.

Phase 8: Persistence & Lifecycle Mapping

• Detect persistence restoration logic (persister.restore).
• Map "Resume" points where the machine state is loaded from a DB based on external identifiers.
• Update metadata to distinguish between "New Instance" and "Restored Instance" triggers.

Phase 9: Advanced Ecosystem Support

• Reactive Chains: Analyze WebFlux/Project Reactor lambdas (doOnNext, flatMap) for hidden triggers.
• Interceptors & Filters: Detect HandlerInterceptor and Filter implementations and map them to endpoints.

Phase 10: External Dependency Interop

• Library Hints: Allow users to provide a JSON map of "Method -> Event" for third-party libraries where source is unavailable.
• External JAR Analysis: (Optional) Configure JDT to scan source-attachments of dependencies if available.