spring-state-machine-renderer/AGENTS.md

AGENTS.md

Project Overview

Spring State Machine Explorer is a static analysis tool that extracts and visualizes Spring State Machines from source code. It does not run Maven/Gradle on target projects.

Build System

• Java 21 required (toolchain configured in all build.gradle files)
• Gradle build system with shadow plugin for fat JARs
• Run from root: ./gradlew <task>

Key Commands

Run the exporter

./gradlew :state_machine_exporter:run --args="-i ./my-project -o ./out -f json"

Run the HTML generator

./gradlew :state_machine_exporter_html:run --args="-i ./my-project -o ./out_html"

Update golden test files

./gradlew :state_machine_exporter:runGolden

Run tests

./gradlew :state_machine_exporter:test
./gradlew :state_machine_exporter_html:test

Module Structure

• state_machine_exporter: Core Java AST analyzer (Main class: click.kamil.springstatemachineexporter.Main)
• state_machine_exporter_html: HTML portal generator (Main class: click.kamil.springstatemachineexporter.html.Main)
• state_machine_exporter_spring_based: Spring-based exporter sample
• file_combine: Utility for concatenating Java files
• state_machines/: Sample state machine projects for testing

Architecture Notes

• Source-first analysis: Reads source + build metadata (pom.xml, settings.gradle) statically
• Accessor inlining: Enabled by default (O(1) lookup for trivial getters/setters). Disable with --no-inline-accessors
• Generated sources: Scans target//build/ by default. Control with --include-generated-sources
• Debug mode: Use --debug flag for verbose logging and unresolved chain diagnostics
• Spring profiles: Pass with -p, --profiles for property placeholder resolution

Testing

• Golden tests: JSON/PNG/PUML/DOT/SCXML outputs are compared against golden files in state_machine_exporter/src/test/resources/golden/
• E2E tests: Tagged with @Tag("e2e") in PlantUmlE2ETest.java
• Test scenarios: Defined in TestScenario.java record with name, inputPath, goldenPath, baseName, activeProfiles

Important Constraints

• No Maven/Gradle execution: The tool does not run the target project's build
• JDT bindings: Limited to library types (Spring Boot 3.2.0, Spring State Machine 3.2.0) - external JARs not resolved
• Monorepo structure: All modules in root; state_machines/ contains sample projects
• Java 21 only: All modules require Java 21 toolchain