orfeas_petri_flow 0.6.0

data/lib/petri_flow/verification_runner.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+
+module PetriFlow
+  # Runs verification on registered workflows and generates reports.
+  # Reports are saved to reports/petri_flow_<timestamp>/ directory.
+  #
+  # @example Run verification for all workflows
+  #   runner = PetriFlow::VerificationRunner.new
+  #   runner.run_all
+  #
+  # @example Run for a specific workflow
+  #   runner.run_workflow(RefundRequestWorkflow)
+  #
+  # @example Run by workflow name
+  #   runner.run_by_name("RefundRequestWorkflow")
+  #
+  class VerificationRunner
+    attr_reader :reports_dir, :results
+
+    # @param base_dir [String] Base directory for reports (default: Rails.root or current dir)
+    # @param output [IO] Output stream for console messages (default: $stdout)
+    def initialize(base_dir: nil, output: $stdout)
+      @base_dir = base_dir || default_base_dir
+      @timestamp = Time.now.strftime("%Y%m%d_%H%M%S")
+      @reports_dir = File.join(@base_dir, "reports", "petri_flow_#{@timestamp}")
+      @output = output
+      @results = {}
+    end
+
+    # Run verification for all registered workflows
+    # @return [Hash] Results for all workflows
+    def run_all
+      ensure_reports_dir
+      print_header
+
+      Registry.all.each do |workflow_class|
+        run_workflow(workflow_class)
+      end
+
+      generate_summary_report
+      print_footer
+
+      @results
+    end
+
+    # Run verification for a specific workflow class
+    # @param workflow_class [Class] The workflow class to verify
+    # @return [Hash] Verification results
+    def run_workflow(workflow_class)
+      workflow = workflow_class.new
+      workflow_id = workflow.workflow_id
+
+      puts "\n" + "=" * 70
+      puts " #{workflow_class.name.upcase}"
+      puts "=" * 70
+
+      results = workflow.verify!
+      @results[workflow_id] = {
+        class_name: workflow_class.name,
+        workflow_name: workflow.workflow_name,
+        verification: results,
+        terminal_reachability: workflow.terminal_reachability.dup
+      }
+
+      export_workflow_diagrams(workflow)
+      print_verification_summary(workflow)
+
+      results
+    end
+
+    # Run verification for a workflow by name
+    # @param name [String] The workflow class name
+    # @return [Hash] Verification results
+    # @raise [RuntimeError] If workflow not found
+    def run_by_name(name)
+      workflow_class = Registry.get(name)
+      raise "Workflow '#{name}' not found in registry" unless workflow_class
+
+      ensure_reports_dir
+      print_header
+      run_workflow(workflow_class)
+      generate_summary_report
+      print_footer
+
+      @results
+    end
+
+    private
+
+    def default_base_dir
+      if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+        Rails.root.to_s
+      else
+        Dir.pwd
+      end
+    end
+
+    def ensure_reports_dir
+      FileUtils.mkdir_p(@reports_dir)
+    end
+
+    def puts(message = "")
+      @output.puts(message)
+    end
+
+    def print_header
+      puts
+      puts "╔═══════════════════════════════════════════════════════════════════════╗"
+      puts "║                                                                       ║"
+      puts "║   PETRIFLOW VERIFICATION                                              ║"
+      puts "║   Formal Verification of Business Workflows                           ║"
+      puts "║                                                                       ║"
+      puts "╚═══════════════════════════════════════════════════════════════════════╝"
+      puts
+      puts "  PetriFlow Version: #{PetriFlow::VERSION}"
+      puts "  Timestamp: #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}"
+      puts "  Workflows: #{Registry.count}"
+      puts "  Output: #{@reports_dir}"
+      puts
+    end
+
+    def print_footer
+      puts
+      puts "╔═══════════════════════════════════════════════════════════════════════╗"
+      puts "║  VERIFICATION COMPLETE                                                ║"
+      puts "║                                                                       ║"
+      puts "║  Reports saved to: #{@reports_dir.split('/').last.ljust(49)}║"
+      puts "╚═══════════════════════════════════════════════════════════════════════╝"
+      puts
+    end
+
+    def print_verification_summary(workflow)
+      results = workflow.verification_results
+      reachability = results[:reachability]
+      boundedness = results[:boundedness]
+      liveness = results[:liveness]
+
+      puts "\n┌─ Verification Results ──────────────────────────────────────────────┐"
+      puts "│ Reachable states: #{reachability[:total_reachable_states].to_s.ljust(50)}│"
+      puts "│ Terminal states: #{reachability[:terminal_states].to_s.ljust(51)}│"
+      puts "│ Is safe (1-bounded): #{boundedness[:is_safe].to_s.ljust(47)}│"
+      puts "│ Deadlock-free: #{liveness[:deadlock_free].to_s.ljust(53)}│"
+      puts "└─────────────────────────────────────────────────────────────────────┘"
+
+      puts "\n  Terminal State Reachability:"
+      workflow.terminal_reachability.each do |state, reachable|
+        status = reachable ? "✓ REACHABLE" : "✗ UNREACHABLE"
+        puts "    #{state.to_s.ljust(20)} #{status}"
+      end
+    end
+
+    def export_workflow_diagrams(workflow)
+      workflow_id = workflow.workflow_id
+      ensure_reports_dir
+
+      # Mermaid
+      mermaid_file = File.join(@reports_dir, "#{workflow_id}_petri.mmd")
+      File.write(mermaid_file, workflow.to_mermaid)
+
+      # DOT
+      dot_file = File.join(@reports_dir, "#{workflow_id}_petri.dot")
+      File.write(dot_file, workflow.to_dot)
+
+      # Generate images if GraphViz available
+      generate_graphviz_images(dot_file, workflow_id) if graphviz_available?
+    end
+
+    def graphviz_available?
+      system("which dot > /dev/null 2>&1")
+    end
+
+    def generate_graphviz_images(dot_file, workflow_id)
+      %w[png pdf svg].each do |format|
+        output_file = File.join(@reports_dir, "#{workflow_id}_petri.#{format}")
+        system("dot -T#{format} #{dot_file} -o #{output_file} 2>/dev/null")
+      end
+    end
+
+    def generate_summary_report
+      # Generate individual report for each workflow
+      @results.each do |workflow_id, data|
+        generate_workflow_report(workflow_id, data)
+      end
+
+      # Generate summary report
+      report_file = File.join(@reports_dir, "verification_report.md")
+      content = build_summary_report
+      File.write(report_file, content)
+    end
+
+    def generate_workflow_report(workflow_id, data)
+      report_file = File.join(@reports_dir, "#{workflow_id}.md")
+      content = build_workflow_report(workflow_id, data)
+      File.write(report_file, content)
+    end
+
+    def build_workflow_report(workflow_id, data)
+      verification = data[:verification]
+      all_reachable = data[:terminal_reachability].values.all?
+      status_icon = all_reachable ? "✓" : "✗"
+
+      lines = []
+      lines << "# #{data[:workflow_name]}"
+      lines << ""
+      lines << "**Generated:** #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}"
+      lines << "**PetriFlow Version:** #{PetriFlow::VERSION}"
+      lines << "**Status:** #{status_icon} #{all_reachable ? 'All terminal states reachable' : 'UNREACHABLE STATES DETECTED'}"
+      lines << ""
+      lines << "---"
+      lines << ""
+      lines << "## Verification Results"
+      lines << ""
+      lines << "| Property | Value |"
+      lines << "|----------|-------|"
+      lines << "| Reachable states | #{verification[:reachability][:total_reachable_states]} |"
+      lines << "| Terminal states | #{verification[:reachability][:terminal_states]} |"
+      lines << "| Is bounded | #{verification[:boundedness][:is_bounded]} |"
+      lines << "| Is safe (1-bounded) | #{verification[:boundedness][:is_safe]} |"
+      lines << "| Deadlock-free | #{verification[:liveness][:deadlock_free]} |"
+      lines << ""
+      lines << "---"
+      lines << ""
+      lines << "## Terminal State Reachability"
+      lines << ""
+
+      data[:terminal_reachability].each do |state, reachable|
+        icon = reachable ? "✓" : "✗"
+        status = reachable ? "Reachable" : "**UNREACHABLE**"
+        lines << "| #{icon} | **#{state}** | #{status} |"
+      end
+
+      lines << ""
+
+      unless all_reachable
+        lines << ""
+        lines << "> **WARNING:** Some terminal states are unreachable from the initial state."
+        lines << "> This indicates a workflow design issue that should be investigated."
+        lines << ""
+      end
+
+      lines << "---"
+      lines << ""
+      lines << "## Petri Net Diagram"
+      lines << ""
+      lines << "![#{data[:workflow_name]} Petri Net](#{workflow_id}_petri.png)"
+      lines << ""
+      lines << "---"
+      lines << ""
+      lines << "*Generated by PetriFlow verification tool*"
+      lines.join("\n")
+    end
+
+    def build_summary_report
+      lines = []
+      lines << "# PetriFlow Verification Summary"
+      lines << ""
+      lines << "**Generated:** #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}"
+      lines << "**PetriFlow Version:** #{PetriFlow::VERSION}"
+      lines << "**Workflows Verified:** #{@results.count}"
+      lines << ""
+      lines << "---"
+      lines << ""
+      lines << "## Results"
+      lines << ""
+      lines << "| Workflow | States | Safe | Terminals Reachable | Report |"
+      lines << "|----------|--------|------|---------------------|--------|"
+
+      @results.each do |workflow_id, data|
+        reachability = data[:verification][:reachability]
+        boundedness = data[:verification][:boundedness]
+        all_reachable = data[:terminal_reachability].values.all?
+        status_icon = all_reachable ? "✓" : "✗"
+
+        lines << "| #{data[:workflow_name]} | #{reachability[:total_reachable_states]} | #{boundedness[:is_safe]} | #{status_icon} #{all_reachable} | [View](#{workflow_id}.md) |"
+      end
+
+      lines << ""
+      lines << "---"
+      lines << ""
+      lines << "*Generated by PetriFlow verification tool*"
+      lines.join("\n")
+    end
+  end
+end

data/lib/petri_flow/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PetriFlow
+  VERSION = "0.6.0"
+end

data/lib/petri_flow/visualization/graphviz.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "set"
+
+module PetriFlow
+  module Visualization
+    # GraphViz visualization for Petri nets
+    # Generates DOT format for rendering with Graphviz
+    class Graphviz
+      attr_reader :net, :options
+
+      DEFAULT_OPTIONS = {
+        place_color: "lightblue",
+        transition_color: "lightgreen",
+        marked_place_color: "yellow",
+        enabled_transition_color: "lightcoral",
+        show_token_count: true,
+        show_arc_weights: true,
+        show_pattern_labels: true,  # Label fork/choice patterns
+        layout: "dot", # dot, neato, fdp, circo
+        rankdir: "TB"  # TB (top-bottom), LR (left-right)
+      }.freeze
+
+      def initialize(net, options = {})
+        @net = net
+        @options = DEFAULT_OPTIONS.merge(options)
+        analyze_patterns if @options[:show_pattern_labels]
+      end
+
+      # Generate DOT format
+      def to_dot
+        dot = []
+        dot << "digraph #{sanitize_name(@net.name)} {"
+        dot << "  rankdir=#{@options[:rankdir]};"
+        dot << "  node [fontname=\"Helvetica\"];"
+        dot << "  edge [fontname=\"Helvetica\"];"
+        dot << ""
+
+        # Places
+        dot << "  // Places"
+        @net.places.each do |id, place|
+          dot << place_node(id, place)
+        end
+        dot << ""
+
+        # Transitions
+        dot << "  // Transitions"
+        @net.transitions.each do |id, transition|
+          dot << transition_node(id, transition)
+        end
+        dot << ""
+
+        # Arcs
+        dot << "  // Arcs"
+        @net.arcs.each do |arc|
+          dot << arc_edge(arc)
+        end
+
+        dot << "}"
+        dot.join("\n")
+      end
+
+      # Save DOT file
+      def save_dot(filename)
+        File.write(filename, to_dot)
+      end
+
+      # Generate and render to image (requires graphviz installed)
+      def render(output_file, format: "png")
+        require 'open3'
+
+        dot_content = to_dot
+        cmd = "#{@options[:layout]} -T#{format} -o #{output_file}"
+
+        stdout, stderr, status = Open3.capture3(cmd, stdin_data: dot_content)
+
+        unless status.success?
+          raise "Graphviz rendering failed: #{stderr}"
+        end
+
+        output_file
+      end
+
+      # Generate ASCII art representation
+      def to_ascii
+        ascii = []
+        ascii << "=" * 60
+        ascii << "Petri Net: #{@net.name}"
+        ascii << "=" * 60
+        ascii << ""
+
+        ascii << "Places:"
+        @net.places.each do |id, place|
+          tokens = "●" * place.tokens
+          ascii << "  #{place.name} [#{id}]: #{tokens} (#{place.tokens} token#{'s' unless place.tokens == 1})"
+        end
+        ascii << ""
+
+        ascii << "Transitions:"
+        @net.transitions.each do |id, transition|
+          enabled = transition.enabled? ? "✓" : "✗"
+          ascii << "  #{enabled} #{transition.name} [#{id}]"
+          transition.input_arcs.each do |arc|
+            ascii << "      ← #{arc.source.name} (weight: #{arc.weight})"
+          end
+          transition.output_arcs.each do |arc|
+            ascii << "      → #{arc.target.name} (weight: #{arc.weight})"
+          end
+        end
+        ascii << ""
+
+        ascii << "=" * 60
+        ascii.join("\n")
+      end
+
+      private
+
+      def place_node(id, place)
+        tokens = place.tokens
+        color = tokens > 0 ? @options[:marked_place_color] : @options[:place_color]
+
+        label = if @options[:show_token_count] && tokens > 0
+                  "#{place.name}\\n(#{tokens})"
+                else
+                  place.name
+                end
+
+        "  #{node_id(:place, id)} [shape=circle, label=\"#{label}\", style=filled, fillcolor=\"#{color}\"];"
+      end
+
+      def transition_node(id, transition)
+        enabled = transition.enabled?
+        color = enabled ? @options[:enabled_transition_color] : @options[:transition_color]
+
+        label = transition.name
+        label += "\\n[enabled]" if enabled && @options[:show_enabled]
+
+        "  #{node_id(:transition, id)} [shape=box, label=\"#{label}\", style=filled, fillcolor=\"#{color}\"];"
+      end
+
+      # Analyze the net to identify fork and choice patterns
+      def analyze_patterns
+        @fork_transitions = Set.new
+        @choice_places = Set.new
+
+        # Find fork transitions: transitions with multiple output arcs
+        @net.transitions.each do |id, transition|
+          output_arcs = @net.arcs.select { |arc| arc.source == transition }
+          if output_arcs.size > 1
+            @fork_transitions.add(id)
+          end
+        end
+
+        # Find choice places: places with multiple outgoing transitions
+        @net.places.each do |id, place|
+          outgoing_arcs = @net.arcs.select { |arc| arc.source == place }
+          if outgoing_arcs.size > 1
+            @choice_places.add(id)
+          end
+        end
+      end
+
+      def arc_edge(arc)
+        source_id = if arc.source.is_a?(Core::Place)
+                     node_id(:place, arc.source.id)
+                   else
+                     node_id(:transition, arc.source.id)
+                   end
+
+        target_id = if arc.target.is_a?(Core::Place)
+                     node_id(:place, arc.target.id)
+                   else
+                     node_id(:transition, arc.target.id)
+                   end
+
+        label = arc_label(arc)
+
+        "  #{source_id} -> #{target_id}#{label};"
+      end
+
+      def arc_label(arc)
+        labels = []
+
+        # Check for fork/choice patterns
+        if @options[:show_pattern_labels]
+          if arc.source.is_a?(Core::Transition) && @fork_transitions&.include?(arc.source.id)
+            # Fork: show target place name
+            target_name = arc.target.name.to_s.split('_').map(&:capitalize).join(' ')
+            labels << "∥ #{target_name}"
+          elsif arc.source.is_a?(Core::Place) && @choice_places&.include?(arc.source.id)
+            # Choice: show where this transition leads
+            transition = arc.target
+            output_arcs = @net.arcs.select { |a| a.source == transition }
+            if output_arcs.any?
+              targets = output_arcs.map { |a| a.target.name.to_s.split('_').map(&:capitalize).join(' ') }
+              labels << "⊕ → #{targets.join(', ')}"
+            else
+              labels << "⊕"
+            end
+          end
+        end
+
+        # Check for arc weights
+        if @options[:show_arc_weights] && arc.weight > 1
+          labels << arc.weight.to_s
+        end
+
+        labels.empty? ? "" : " [label=\"#{labels.join(' ')}\"]"
+      end
+
+      def node_id(type, id)
+        "#{type}_#{sanitize_name(id)}"
+      end
+
+      def sanitize_name(name)
+        name.to_s.gsub(/[^a-zA-Z0-9_]/, '_')
+      end
+    end
+  end
+end

data/lib/petri_flow/visualization/mermaid.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "set"
+
+module PetriFlow
+  module Visualization
+    # Mermaid diagram visualization for Petri nets
+    # Generates Mermaid syntax for embedding in Markdown/documentation
+    class Mermaid
+      attr_reader :net, :options
+
+      DEFAULT_OPTIONS = {
+        direction: "TB", # TB, BT, LR, RL
+        show_tokens: true,
+        show_weights: true,
+        show_pattern_labels: true  # Label fork/choice patterns
+      }.freeze
+
+      def initialize(net, options = {})
+        @net = net
+        @options = DEFAULT_OPTIONS.merge(options)
+        analyze_patterns if @options[:show_pattern_labels]
+      end
+
+      # Generate Mermaid flowchart
+      def to_mermaid
+        mermaid = []
+        mermaid << "flowchart #{@options[:direction]}"
+
+        # Places
+        @net.places.each do |id, place|
+          mermaid << place_node(id, place)
+        end
+
+        # Transitions
+        @net.transitions.each do |id, transition|
+          mermaid << transition_node(id, transition)
+        end
+
+        # Arcs
+        @net.arcs.each do |arc|
+          mermaid << arc_edge(arc)
+        end
+
+        # Styling
+        mermaid << ""
+        mermaid << style_definitions
+
+        mermaid.join("\n")
+      end
+
+      # Generate state diagram (alternative representation)
+      def to_state_diagram
+        mermaid = []
+        mermaid << "stateDiagram-v2"
+
+        @net.transitions.each do |id, transition|
+          transition.input_arcs.each do |input_arc|
+            transition.output_arcs.each do |output_arc|
+              source = input_arc.source.name
+              target = output_arc.target.name
+              label = escape_label(transition.name)
+
+              mermaid << "  #{sanitize(source)} --> #{sanitize(target)}: #{label}"
+            end
+          end
+        end
+
+        mermaid.join("\n")
+      end
+
+      private
+
+      def place_node(id, place)
+        node_id = sanitize(id)
+        label = escape_label(place.name)
+
+        if @options[:show_tokens] && place.tokens > 0
+          label = "#{label} x#{place.tokens}"
+        end
+
+        "  #{node_id}((\"#{label}\"))"
+      end
+
+      def transition_node(id, transition)
+        node_id = sanitize(id)
+        label = escape_label(transition.name)
+        enabled = transition.enabled? ? " *" : ""
+
+        "  #{node_id}[\"#{label}#{enabled}\"]"
+      end
+
+      # Analyze the net to identify fork and choice patterns
+      def analyze_patterns
+        @fork_transitions = Set.new
+        @choice_places = Set.new
+
+        # Find fork transitions: transitions with multiple output arcs
+        @net.transitions.each do |id, transition|
+          output_arcs = @net.arcs.select { |arc| arc.source == transition }
+          if output_arcs.size > 1
+            @fork_transitions.add(id)
+          end
+        end
+
+        # Find choice places: places with multiple outgoing transitions
+        @net.places.each do |id, place|
+          outgoing_arcs = @net.arcs.select { |arc| arc.source == place }
+          if outgoing_arcs.size > 1
+            @choice_places.add(id)
+          end
+        end
+      end
+
+      def arc_edge(arc)
+        source_id = sanitize(arc.source.id)
+        target_id = sanitize(arc.target.id)
+
+        label = arc_label(arc)
+
+        if label
+          "  #{source_id} -->|#{label}| #{target_id}"
+        elsif @options[:show_weights] && arc.weight > 1
+          "  #{source_id} -->|#{arc.weight}| #{target_id}"
+        else
+          "  #{source_id} --> #{target_id}"
+        end
+      end
+
+      def arc_label(arc)
+        return nil unless @options[:show_pattern_labels]
+
+        # Fork pattern: transition → multiple places (parallel outputs)
+        # Show target place name to distinguish parallel paths
+        if arc.source.is_a?(PetriFlow::Core::Transition)
+          transition_id = arc.source.id
+          if @fork_transitions&.include?(transition_id)
+            target_name = arc.target.name.to_s.split('_').map(&:capitalize).join(' ')
+            return "∥ #{target_name}"
+          end
+        end
+
+        # Choice pattern: place → multiple transitions (exclusive choice)
+        # Show where each choice leads (the transition's output place)
+        if arc.source.is_a?(PetriFlow::Core::Place)
+          place_id = arc.source.id
+          if @choice_places&.include?(place_id)
+            # Find where this transition leads
+            transition = arc.target
+            output_arcs = @net.arcs.select { |a| a.source == transition }
+            if output_arcs.any?
+              targets = output_arcs.map { |a| a.target.name.to_s.split('_').map(&:capitalize).join(' ') }
+              return "⊕ → #{targets.join(', ')}"
+            end
+            return "⊕"
+          end
+        end
+
+        nil
+      end
+
+      def style_definitions
+        styles = []
+
+        # Style places (circles) - light blue
+        place_ids = @net.places.keys.map { |id| sanitize(id) }
+        if place_ids.any?
+          styles << "  classDef placeClass fill:#add8e6,stroke:#333,stroke-width:2px"
+          styles << "  class #{place_ids.join(',')} placeClass"
+        end
+
+        # Style transitions (rectangles) - light green
+        transition_ids = @net.transitions.keys.map { |id| sanitize(id) }
+        if transition_ids.any?
+          styles << "  classDef transitionClass fill:#90ee90,stroke:#333,stroke-width:2px"
+          styles << "  class #{transition_ids.join(',')} transitionClass"
+        end
+
+        styles.join("\n")
+      end
+
+      def sanitize(name)
+        name.to_s.gsub(/[^a-zA-Z0-9]/, '_')
+      end
+
+      def escape_label(text)
+        text.to_s.gsub('"', "'").gsub(/[<>]/, '')
+      end
+    end
+  end
+end