pg-verify 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b580ce77eaa5f2da5c136688b09db56a3397d810188fcfe8480a59bca92760a
-  data.tar.gz: 89a4e5af16afc5186326cb12615432cb17d38fb7e986b790b7e061cc53138541
+  metadata.gz: 61be58b97dd5e5beb6546f87ef6b2f19b2d372e983fb3b93332c88a0f0b489ad
+  data.tar.gz: 6fc1e14c40748353219ca58d69b034b2970c57da5d19f2ad27ee842c66847035
 SHA512:
-  metadata.gz: c3d040e30a27cf278ff987157b97abeb045d0cf12d209eacc7f4577e81ca39ae40bff1bff51ffb9581b030f5b28628ca08e84994b554c5ca8ac01773c1a8e4f5
-  data.tar.gz: 56f901795a267c9fea53f0a203122767cb50003fc18f510df455de9f3df715421a7b788321d3538f19e3e87ac3b5cac4d6d6e8908db16f935bf5481959197e9b
+  metadata.gz: cbf7170ad7ebff0f939a1ed3309d82ae45246cfbc670475be37f7c0f72f17e516d5e9a73427ebb23dc5403de48693f4dc26db194ac299523af0c119063c75cc4
+  data.tar.gz: c0b0b0c88b8e4a54465c857f5daaaa06826e69c2d9c2149e248863b2d8e627ab6348b59e842352ea24a3c453a0319d9d6054205337ab6de6c5bd88fa6f395047

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pg-verify (0.1.1)
+    pg-verify (0.1.2)
       config (~> 4.2.1)
       plantuml_builder (~> 0.3.0)
       rainbow (~> 3.0.0)
@@ -10,7 +10,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    concurrent-ruby (1.2.2)
+    concurrent-ruby (1.2.3)
     config (4.2.1)
       deep_merge (~> 1.2, >= 1.2.1)
       dry-validation (~> 1.0, >= 1.0.0)
@@ -66,7 +66,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.0)
-    thor (1.2.1)
+    thor (1.2.2)
 
 PLATFORMS
   x86_64-darwin-19

data/README.md

@@ -26,4 +26,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/pg-verify.
+Bug reports and pull requests are welcome on GitHub at https://github.com/aweber/pg-verify.

data/data/project-template/README.md

@@ -7,6 +7,7 @@ To get started you can run `pg-verify doctor` to verify your installation and gu
 you through the steps needed to install external addons like the NuSMV model checker.
 
 You can always run `pg-verify help` to get a list of available commands.
+Run `pg-verify help <command>` to get more information about a specific command and its options.
 For example try running `pg-verify show png` to render a PNG image of your program graph
 and save that to your working directory.
 
@@ -15,4 +16,84 @@ and save that to your working directory.
 There are a couple of prelude files and directories in your project to get you started:
 
 - `program-graph.rb`: This file defines the default program graph you will be working on
+- `.pg-verify.yml`: This file can be used to configure pg-verify
 - `addon/`: This is the directory where you will place addon resources like the NuSMV executable.
+
+## Writing specifications
+
+The specification framework for the Ruby DSL is inspired by the popular 
+testing library [rspec](https://rspec.info/). Here is an example of the syntax:
+
+```ruby
+# Wrap two specifications which are related to some "Car" model.
+specify "The car" do
+    it "won't crash" => :"G distance_to_tree > 0" # Becomes: The car won't crash
+    it "will drive"  => :"F velocity > 0"         # Becomes: The car will drive
+end
+```
+
+You wrap your specification using one or more `specify` blocks.
+Within those blocks you can declare a *specification* using the `it` keyword.
+Each specification consists of two parts:
+- A **text** which is used to describe the spec in natural language
+- An **expression** given in LTL or CTL. This will actually be checked
+
+The outer block serves as a wrapper for specifications which are related.
+In the example above we declare two specifications which are both concerning
+some "Car" model.
+
+You can read those specifications from outside to inside.
+The `it` semantically refers to the outer block (the car in our case).
+So when reading `it "won't crash"`, **it** refers to **the car**.
+Thus this specification becomes "The car won't crash" when it is expanded.
+
+### Assumption blocks
+
+You can consolidate multiple preconditions for your specifications into
+an `assuming` block. Here's the syntax:
+
+```Ruby
+specify "The car" do
+    assuming "the breaks don't fail" => :"G BreakFailure == No" do
+        it "won't crash" => :"G distance_to_tree > 0" # Becomes: The car (assuming the breaks don't fail) won't crash
+        it "will drive"  => :"F velocity > 0"         # Becomes: The car (assuming the breaks don't fail) will drive
+    end
+end
+```
+
+Much like the specifications themselves, the assuming block expects a `text` and an `expression`.
+For each contained specification, the assumption expression will be prepended to the spec
+while expanding. Thus for the example above we get two expanded specifications:
+
+```
+1) The car (assuming the breaks don't fail) won't crash
+( G BreakFailure == No ) => G distance_to_tree > 0
+
+2) The car (assuming the breaks don't fail) will drive
+( G BreakFailure == No ) => F velocity > 0
+```
+
+### Assuming no errors
+
+The imagined use case for the `assume` block is to specify model properties under exclusion of errors.
+
+```Ruby
+specify "The car" do
+    assuming no_errors do
+        it "won't crash" => :"G distance_to_tree > 0" # Becomes: The car (assuming the breaks don't fail) won't crash
+        it "will drive"  => :"F velocity > 0"         # Becomes: The car (assuming the breaks don't fail) will drive
+    end
+end
+```
+
+The thing that's new here is the `no_errors` keyword.
+All this does is generate a *text* and *expression* to be used by the `assuming` block.
+Say you had three error graphs: `BreakFailure`, `UsageFailure` and `MotorFailure`.
+Then `no_errors` would produce this expression:
+
+```
+G ( BreakFailure == No && UsageFailure == No && MotorFailure == No )
+```
+
+Instead of `no_errors` you can also use `only(...)` to limit the possibility of errors to the
+ones you provide. e.g: `assuming only(:BreakFailure, :UsageFailure) do ...`.

data/doc/examples/vending_machine/checkpoint_1.rb

@@ -0,0 +1,29 @@
+# Create graphs with default states
+
+model :VendingMachine do
+
+    graph :User do
+        states :todo
+    end
+  
+    graph :CoinReader do
+        states :todo
+    end
+  
+    graph :Controller do
+        states :todo
+    end
+  
+    graph :LED do
+        states :todo
+    end
+  
+    graph :Dispenser do
+        states :todo
+    end
+  
+    graph :CoinDispenser do
+        states :todo
+    end
+  
+end

data/doc/examples/vending_machine/checkpoint_2.rb

@@ -0,0 +1,47 @@
+# Add products and coins
+
+model :VendingMachine do
+
+    products = {
+        cola:  1.2,
+        chips: 2.5
+    }
+    products = products.map { |c, v| [c, (v * 10).to_i] }.to_h
+  
+    coins = {
+        ten_cents: 10,
+        twenty_cents: 20,
+        fifty_cents: 50,
+        one_euro: 100,
+        two_euro: 200
+    }
+    coins = coins.map { |c, v| [c, (v / 10).to_i] }.to_h
+  
+    MAX_MONEY = 100
+    START_MONEY = 20
+  
+    graph :User do
+        states :todo
+    end
+  
+    graph :CoinReader do
+        states :todo
+    end
+  
+    graph :Controller do
+        states :todo
+    end
+  
+    graph :LED do
+        states :todo
+    end
+  
+    graph :Dispenser do
+        states :todo
+    end
+  
+    graph :CoinDispenser do
+        states :todo
+    end
+  
+end

data/doc/examples/vending_machine/checkpoint_3.rb

@@ -0,0 +1,68 @@
+# Add states and variables
+
+model :VendingMachine do
+
+    products = {
+        cola:  1.2,
+        chips: 2.5
+    }
+    products = products.map { |c, v| [c, (v * 10).to_i] }.to_h
+  
+    coins = {
+        ten_cents: 10,
+        twenty_cents: 20,
+        fifty_cents: 50,
+        one_euro: 100,
+        two_euro: 200
+    }
+    coins = coins.map { |c, v| [c, (v / 10).to_i] }.to_h
+  
+  
+    MAX_MONEY = 100
+    START_MONEY = 20
+  
+    graph :User do
+        press_states = products.keys.map { |product| :"press_#{product}" }
+        grab_states  = products.keys.map { |product| :"grab_#{product}" }
+        insert_states = coins.keys.map { |coin| :"insert_#{coin}" }
+  
+        var pocket_money: (0..MAX_MONEY), init: START_MONEY
+        var value_in_products: (0..MAX_MONEY), init: 0
+  
+        states :inserting, *insert_states, \
+               :pressing, *press_states, \
+               :waiting, :grab_product, \
+               :grab_change, \
+               :done, \
+               init: :inserting
+    end
+  
+    graph :CoinReader do
+      states :reading
+  
+      var read_value: (0..coins.values.max), init: 0
+    end
+  
+    graph :Controller do
+      var budget: (0..MAX_MONEY), init: 0
+  
+      dispense_states = products.keys.map { |product| :"dispense_#{product}" }
+      states :accepting, *dispense_states, :rejected, :done, init: :accepting
+  
+    end
+  
+    graph :LED do
+      states :idle, :red, :green, init: :idle
+    end
+  
+    graph :Dispenser do
+      dispensed_states = products.keys.map { |product| :"dispensed_#{product}" }
+      states :empty, *dispensed_states, init: :empty
+    end
+  
+    graph :CoinDispenser do
+      states :idle, :dispensed_change, init: :idle
+      var change: (0..MAX_MONEY), init: 0
+    end
+  
+end

data/doc/examples/vending_machine/checkpoint_4.rb

@@ -0,0 +1,202 @@
+# Finish it all up
+
+# CONFIG
+# trace:
+#   colors:
+#     insert_*: green
+#     press_*: yellow
+#     dispense_*: yellow
+#     accepting: sidenote
+#     idle: sidenote
+#     empty: sidenote
+#     reading: sidenote
+
+model :VendingMachine do
+
+    products = {
+        cola:  1.2,
+        chips: 2.5
+    }.map { |c, v| [c, (v * 10).to_i] }.to_h
+  
+    coins = {
+        ten_cents: 10,
+        twenty_cents: 20,
+        fifty_cents: 50,
+        one_euro: 100,
+        two_euro: 200
+    }.map { |c, v| [c, (v / 10).to_i] }.to_h
+  
+    MAX_MONEY = 100
+    START_MONEY = 20
+  
+    transient error :CoinReadFails
+  
+    graph :User do
+        press_states = products.keys.map { |product| :"press_#{product}" }
+        grab_states  = products.keys.map { |product| :"grab_#{product}" }
+        insert_states = coins.keys.map { |coin| :"insert_#{coin}" }
+  
+        var pocket_money: (0..MAX_MONEY), init: START_MONEY
+        var value_in_products: (0..MAX_MONEY), init: 0
+  
+        states :inserting, *insert_states, \
+               :pressing, *press_states, \
+               :waiting, :grab_product, \
+               :grab_change, \
+               :done, \
+               init: :inserting
+  
+        # The user can insert coins until the money runs out
+        coins.each { |coin, value|
+          transition :inserting => :"insert_#{coin}" do
+            guard  "pocket_money - #{value} >= 0"
+            action "pocket_money := pocket_money - #{value}"
+          end
+          transition :"insert_#{coin}" => :inserting
+        }
+        # The user can decide at any point to start pressing buttons
+        transition :inserting => :pressing
+  
+        # Press one button and wait for the result
+        products.each { |product, value|
+          transition :pressing => :"press_#{product}"
+          transition :"press_#{product}" => :waiting
+        }
+  
+        # Grab a product and take note of the value
+        products.each { |product, value|
+          transition :waiting => :grab_product do
+            precon "value_in_products + #{value} < #{MAX_MONEY}"
+            guard  "LED == green && Dispenser == dispensed_#{product}"
+            action "value_in_products := value_in_products + #{value}"
+          end
+        }
+        transition :grab_product => :grab_change
+  
+        # Grab change directly on fail
+        transition :waiting => :grab_change do
+          guard "LED == red"
+        end
+  
+        # Grab the change and be done
+        transition :grab_change => :done do
+          precon "pocket_money + change <= #{MAX_MONEY}"
+          action "pocket_money := pocket_money + change"
+        end
+    end
+  
+    graph :CoinReader do
+      states :reading
+  
+      var read_value: (0..coins.values.max), init: 0
+  
+      coins.each { |coin, value|
+        transition :reading => :reading do
+          guard  "User == insert_#{coin} && CoinReadFails == No"
+          action "read_value := #{value}"
+        end
+      }
+  
+      transition :reading => :reading do
+        guard  coins.keys.map { |coin| "User != insert_#{coin}" }.join(" && ")
+        action "read_value := 0"
+      end
+  
+    end
+  
+    graph :Controller do
+      var budget: (0..MAX_MONEY), init: 0
+  
+      dispense_states = products.keys.map { |product| :"dispense_#{product}" }
+  
+      states :accepting, *dispense_states, :rejected, :done, init: :accepting
+  
+      # Accept coin reads from the reader
+      transition :accepting => :accepting do
+        precon "budget + read_value <= #{MAX_MONEY}"
+        guard "read_value > 0"
+        action "budget := budget + read_value"
+      end
+  
+     
+      products.each { |product, value|
+
+        # Accept button presses when enough money
+        transition :accepting => :"dispense_#{product}" do
+          guard  "User == press_#{product} && budget >= #{value}"
+          action "budget := budget - #{value}"
+        end
+        transition :"dispense_#{product}" => :done
+  
+        # Reject button presses when not enough money
+        transition :accepting => :rejected do
+          guard "User == press_#{product} && budget < #{value}"
+        end
+      }
+
+      # Reset when the coin dispenser has dispensed
+      transition :accepting => :accepting do
+        guard  "CoinDispenser == dispensed_change"
+        action "budget := 0"
+      end
+      transition :done => :accepting do
+        guard  "CoinDispenser == dispensed_change"
+        action "budget := 0"
+      end
+  
+  
+    end
+  
+    graph :LED do
+      states :idle, :red, :green, init: :idle
+  
+      transition :idle => :green do
+        guard "Controller == done"
+      end
+      transition :idle => :red do
+        guard "Controller == rejected"
+      end
+  
+    end
+  
+    graph :Dispenser do
+      dispensed_states = products.keys.map { |product| :"dispensed_#{product}" }
+      states :empty, *dispensed_states, init: :empty
+  
+      # Dispense the product the Controller tells us to
+      products.each { |product, value|
+        transition :empty => :"dispensed_#{product}" do
+          guard "Controller == dispense_#{product}"
+        end
+      }
+    end
+  
+    graph :CoinDispenser do
+      states :idle, :dispensed_change, init: :idle
+      var change: (0..MAX_MONEY), init: 0
+  
+      # Eject the change money
+      transition :idle => :dispensed_change do
+        guard  "Controller == rejected || Controller == done"
+        action "change := budget"
+      end
+  
+    end
+  
+    specify "The vending machine" do
+  
+      it "allows the user to buy something" => :"EF value_in_products > 0"
+      it "always completes the transaction" => :"F User == done"
+  
+      products.each { |product, value|
+        assuming "the product can be bough" => :"pocket_money >= #{value}" do
+          it "allows the user to buy #{product}" => :"EF Dispenser == dispensed_#{product}"
+        end
+      }
+  
+    end
+  
+    hazard "The user looses money" => :"User == done && pocket_money + value_in_products < #{START_MONEY}"
+    hazard "The machine looses money" => :"User == done && pocket_money + value_in_products > #{START_MONEY}"
+  
+end

data/integration_tests/ruby_dsl/001_states.rb

@@ -4,7 +4,8 @@ model :TestTransitions do
     end
     specify "The state" do
         it "starts in initial" => :"Test == initial"
-        it "stays in initial"  => :"G Test == initial"
+        it "stays in initial (LTL)"  => :"G Test == initial"
+        it "stays in initial (CTL)"  => :"AG Test == initial"
         it "never leaves initial" => :"! F Test != initial"
     end
 end

data/integration_tests/ruby_dsl/002_transitions.rb

@@ -5,6 +5,7 @@ model :TestTransitions do
     end
     specify "The state" do
         it "starts in one" => :"Test == one"
-        it "transitions to two" => :"X Test == two"
+        it "transitions to two (LTL)" => :"X Test == two"
+        it "transitions to two (CTL)" => :"AX Test == two"
     end
 end

data/integration_tests/ruby_dsl/017_ctl_specifications.rb

@@ -0,0 +1,19 @@
+model :CtlSpecifications do
+
+    graph :Example do
+        states :one, :two, :three, init: :one
+
+        transition :one => :two
+        transition :two => :one
+        transition :one => :three
+
+    end
+
+    specify "The model" do
+        it "starts in state one" => :"Example == one"
+        it "cannot stay in one" => :"! G Example == one"
+        it "can stay in three" => :"EX AG Example == three"
+        it "cannot go back to one from three" => :"AG ( (Example == three) => ! EF Example == one)"
+    end
+
+end

data/integration_tests/ruby_dsl/018_non_atomic_hazard.rb

@@ -0,0 +1,17 @@
+model :NonAtomicHazard do
+
+    persistent error :KeysForgotten
+
+    graph :Person do
+        states :inside, :outside, init: :inside
+        transition :inside => :outside
+        transition :outside => :inside do
+            guard "KeysForgotten == No"
+        end
+    end
+
+    # This does not work as at any point the fault could not have occurred
+    # (KeysForgotten == No) already but then it happens at a later point
+    # Expected Cut Sets: { :"" }
+    # hazard "The person can't get in" => :"G Person == outside"
+end

data/integration_tests/ruby_dsl/019_multiple_actions.rb

@@ -0,0 +1,21 @@
+model :MultipleActions do
+
+    graph :GraphWithMultipleActions do
+        states :one, :two, init: :one
+
+        var a: (0..10), init: 0
+        var b: (0..10), init: 0
+        var c: (0..10), init: 0
+
+        transition :one => :two do
+           action "a := 1 + 1 | b := 0 | c := 25 - (2 * 10)"
+        end
+    end
+
+    specify "The graph" do
+        it "set a = 2" => :"X a == 2"
+        it "set b = 0" => :"X b == 0"
+        it "set c = 5" => :"X c == 5"
+    end
+
+end