How its-hmny/choreia works
Main Components
• CLI/Entry Point: Represented by cmd/main.go. This component is responsible for accepting user inputs and passing the Go source file to the rest of the system.
• Static Analysis Module: Found in internal/static_analysis, which contains several files (branch.go, channel.go, loop.go, function.go, etc.). This module parses the AST, extracts code constructs, and gathers metadata.
• Data Structures Module: Under internal/data_structures/fsa, this is where the basic types and transitions of the Finite State Automata (FSA) are defined.
• Transformation Layer: Located in internal/transforms (with files like determinization.go, extraction.go, reconciliation.go). This layer takes the raw static analysis output and converts it into a deterministic or well-formed Choreography Automata.
• Examples: Although not part of the core system, the example directory provides use cases that might be helpful when discussing how the tool works on sample inputs.
Establish Component Relationships & Data Flow
• The CLI captures the input Go file (using command-line flags such as -i, -o, -t) and invokes the main analysis flow.
• The Go source file is then sent into the Static Analysis Module, where different aspects (branches, loops, channels, function calls) are parsed and analyzed.
• The output of static analysis feeds into the Transformation Layer. Here, processes such as extraction, determinization, and reconciliation are applied to convert the initial metadata into a formal FSA.
• The FSA constructed using the definitions in internal/data_structures/fsa represents the Choreography Automata.
• The final result (e.g., an SVG file for visualization) is output to a user-specified location.
Architectural Patterns & Design Principles
• Layered Architecture: Visually represent a pipeline where the input flows through distinct modules.
• Modularity & Extensibility: Each internal package (static_analysis, data_structures, transforms) is built as a modular component. This should be highlighted to show how the system is organized for maintainability and future enhancements.
Technologies and Libraries
• Go: As the primary language and runtime.
• Standard Library Packages for AST parsing and file I/O (even if not explicitly shown, mention that the Go toolchain might be leveraged for parsing).
• Any third-party libraries the project might depend on (as mentioned in the README dependencies section).
Elements
– "CLI/Entry Point (cmd/main.go)"
– "Static Analyzer (internal/static_analysis)" with subcomponents: Branch, Loop, Channel, Function modules, etc.
– "FSA Data Structures (internal/data_structures/fsa)"
– "Transformation Modules (internal/transforms)" listing determinization, extraction, and reconciliation.
– "Output Generator/Visualizer" (implicitly represented by the SVG output in the README).
– Show data flowing from the CLI to Static Analysis.
– Indicate the subsequent creation and processing of the FSA.
Detailed Breakdown
1. Input Collection:
– Command-line interface module accepts flags (-i, -o, -t) and passes the Go file to the analysis engine.
2. Static Analysis Engine:
– Decompose this module further into submodules focusing on different AST elements such as loops, conditions, and channels.
3. Transformation Engine:
– Illustrate the process steps (extraction, determinization, reconciliation) that manipulate and refine the raw analysis data into an FSA.
4. FSA Generation:
5. Output Generation:
– Show the final step where the generated Choreography Automata is rendered (e.g., to an SVG file) and saved.