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 4.5: Hierarchical Robustness (Inheritance Support)

• Hierarchical Annotation Lookup: Update SpringMvcDetector to scan interfaces and superclasses for inherited mapping annotations.
• Interface Implementation Mapping: Enhance CodebaseContext to index "Class -> Interfaces" and "Interface -> Classes" relationships.
• Polymorphic Call Trace: Update CallGraphBuilder to follow calls from an interface method to all known implementations in the project.
• Base Class Trigger Discovery: Ensure triggers in abstract base classes are correctly attributed to their concrete subclasses.

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

• Variable Propagation: Track values from fields/constructors to their usage in the State Machine configuration (e.g., resolving initial(initialState) where initialState is a field).
• @Value Resolution: Link @Value annotations to the PropertyResolver to substitute placeholders with literal values in the diagram.
• Spring Profile Support: Update PropertyResolver to handle application-{profile}.properties and prioritize them based on an "active profiles" setting.
• Complex ValueResolver: Handle string concatenations (e.g., "PREFIX_" + MyConstants.SUFFIX) and variable references.
• Payload Analysis: Extract payload types from entry points and track field usage in sendEvent calls.

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: Implementation complete. Supports hints.json in project root or src/main/resources/.
  • Format: [{"methodFqn": "class.method", "event": "EVENT"}]
  • Purpose: Maps external/compiled library calls to State Machine events when source code is unavailable.
• External JAR Analysis: (Optional) Configure JDT to scan source-attachments of dependencies if available.

Note on Library Hints: This feature is an optional "Power User" escape hatch. The analyzer works automatically for all local source code; hints.json is only required to bridge the gap for third-party libraries.