diff --git a/lombok.config b/lombok.config new file mode 100644 index 0000000..abb3ca1 --- /dev/null +++ b/lombok.config @@ -0,0 +1,3 @@ +lombok.anyConstructor.addConstructorProperties = true +lombok.jacksonized.flagUsage = WARNING +config.stopBubbling = true diff --git a/state_machine_exporter/flow_renderer_plan/html_generator_architecture.md b/state_machine_exporter/flow_renderer_plan/html_generator_architecture.md deleted file mode 100644 index 9bae1fc..0000000 --- a/state_machine_exporter/flow_renderer_plan/html_generator_architecture.md +++ /dev/null @@ -1,101 +0,0 @@ -# Interactive HTML Generator: Architecture & Flow Definition Format - -Following the success of the interactive SVG PoC, this document outlines the proposed architecture for adding an **HTML Generator** to the State Machine Exporter, allowing users to define and visualize specific business flows dynamically. - -## 1. The Flow Definition Format (JSON & JSON Schema) - -To make the interactive HTML generator useful and intuitive, users need a way to define their business flows externally. Rather than reinventing the wheel, we looked at industry standards for defining graph paths, workflows, and execution traces: -* **Workflow Definitions:** Tools like *Amazon States Language (ASL)*, *SCXML*, and *XState* are highly structured but define the *entire* machine's logic. They are too heavy for simply defining a "path" through an existing machine. -* **Trace Formats:** *OpenTelemetry (OTel)* uses "Spans" to represent individual steps forming a "Trace". This is closer to what we want (a history of states). -* **Graph Formats:** The *JSON Graph Format (JGF)* standardizes graph nodes and edges representation but is geared towards raw data modeling rather than human-readable business flows. - -**Conclusion on Format:** We will use a lightweight custom JSON format inspired by execution traces. It is designed to be highly readable for humans defining business flows, relying simply on ordered arrays of State names. - -### JSON Schema for IDE Autocomplete -To make the format truly intuitive and prevent typos, we will publish a **JSON Schema** (`flow-schema.json`). -By referencing this schema, developers writing `flows.json` in IDEs like VS Code or IntelliJ will get **instant autocomplete, hover tooltips, and real-time validation** for fields like `id`, `title`, and `color`. -* *Future Enhancement:* The Java exporter could dynamically generate a project-specific JSON Schema on the fly that hardcodes the allowed `enum` values for the `path` array (e.g., restricted exactly to `"SUBMITTED"`, `"PAID"`, etc.), providing perfect autocomplete for state names! - -### Proposed Schema (`flows.json`) - -```json -{ - "$schema": "./flow-schema.json", - "stateMachine": "click.kamil.examples.statemachine.simple.SimpleEnumStateMachineConfiguration", - "flows": [ - { - "id": "flow-happy-path", - "title": "Happy Path (Success)", - "description": "The standard flow for a successful order: Submitted -> Paid -> Fulfilled.", - "color": "#32CD32", - "path": [ - ".start.", - "SUBMITTED", - "PAID", - "FULFILLED", - ".end." - ] - }, - { - "id": "flow-cancel-post-pay", - "title": "Cancel Post-Payment", - "description": "Order is canceled after payment.", - "color": "#FF6347", - "path": [ - ".start.", - "SUBMITTED", - "PAID", - "CANCELED", - ".end." - ] - } - ] -} -``` - -### Format Details: -* **`$schema`**: Points to the JSON schema for IDE tooling. -* **`stateMachine`**: Links these flows to a specific state machine configuration in the codebase. -* **`id`**: A unique identifier for the flow (used for DOM elements). -* **`title` & `description`**: Rendered in the HTML sidebar for the user. -* **`color` (Optional)**: Allows overriding the default highlight color (e.g., green for success, red for errors). -* **`path`**: An ordered array of **State Names** (acting like an OpenTelemetry trace). - * *Note on Edges:* The user only needs to define the *states* they pass through. The generator will automatically calculate the edges (transitions) between these states to highlight the lines. Special tokens like `.start.` and `.end.` map to the initial and terminal pseudo-states. - -## 2. Robust Error Handling & Input Validation - -Before generating the HTML, the exporter **must validate** that the provided `flows.json` is logically sound against the actual codebase AST. If a user defines a flow that isn't physically possible in the state machine, the tool must fail fast with highly descriptive errors. - -### Validation Rules & Error Handling Strategy: -1. **Schema Validation (Syntax):** - * *Check:* Is the JSON structurally correct (required fields present, correct types)? - * *Error:* "Invalid format in flows.json: 'title' is required for flow 'flow-cancel-post-pay'." -2. **State Existence (Dangling Pointers):** - * *Check:* Every state listed in the `path` array must exist in the parsed `StateMachineModel`. - * *Error:* "Validation Error in 'Happy Path': State 'FULLFILLED' does not exist in StateMachine 'SimpleEnum'. Did you mean 'FULFILLED'?" (implementing a Levenshtein distance check for typos would be excellent here). -3. **Transition Validity (Impossible Paths):** - * *Check:* For every adjacent pair in the `path` array (e.g., `["SUBMITTED", "PAID"]`), the validator must check the `StateMachineModel.getTransitions()` to ensure a valid transition exists where `source == "SUBMITTED"` and `target == "PAID"`. - * *Error:* "Validation Error in 'Happy Path': No transition exists from 'PAID' to 'SUBMITTED'. Please check your state machine configuration." -4. **Ambiguous Transitions (Multiple Edges):** - * *Check:* If multiple transitions exist between the same two states (e.g., two different events trigger a move from A -> B). - * *Handling:* By default, highlight *all* edges between A and B to represent the general path. - * *Future Enhancement:* Expand the JSON format to allow specifying the exact `event` name in the path array (e.g., `["SUBMITTED", {"state": "PAID", "event": "PAY_CREDIT_CARD"}]`) to disambiguate. - -## 3. HTML Generation Strategy - -The HTML Exporter will be a new class implementing the `StateMachineExporter` interface (or a specialized decorator around the `PlantUml` exporter). - -### Steps for Generation: -1. **Generate PlantUML SVG:** First, use the existing PlantUML engine to generate the raw SVG string in memory (using the modern CSS ` - -
- - - -