highway 0.0.1 → 1.0.1

data/lib/highway/compiler/build/output/invocation.rb

@@ -0,0 +1,70 @@
+#
+# invocation.rb
+# Copyright © 2019 Netguru S.A. All rights reserved.
+#
+
+module Highway
+  module Compiler
+    module Build
+      module Output
+
+        # This class represents a step invocation in the build manifest. It
+        # contains information about step definition class, parameters and
+        # execution policy.
+        class Invocation
+
+          public
+
+          # Initialize an instance.
+          #
+          # @param index [Integer] Index of invocation, 1-based.
+          # @param step_class [Class] Definition class of the step.
+          # @param parameters [Highway::Compiler::Analyze::Tree::Values::Hash] Hash value of step parameters.
+          # @param policy [Symbol] Execution policy of the step invocation.
+          # @param keypath [Array<String>] A keypath used for debugging purposes.
+          def initialize(index:, step_class:, parameters:, policy:, keypath:)
+            @index = index
+            @step_class = step_class
+            @parameters = parameters
+            @policy = policy
+            @keypath = keypath
+          end
+
+          # Index of invocation, 1-based.
+          #
+          # @return [Integer]
+          attr_reader :index
+
+          # Definition class of the step.
+          #
+          # @return [Class]
+          attr_reader :step_class
+
+          # Hash value of step parameters.
+          #
+          # @return [Highway::Compiler::Analyze::Tree::Values::Hash]
+          attr_reader :parameters
+
+          # Execution policy of the step invocation.
+          #
+          # @return [Symbol]
+          attr_reader :policy
+
+          # A keypath used for debugging purposes.
+          #
+          # @return [Array<String>]
+          attr_reader :keypath
+
+          # An identifier of the invocation, joined by index and step name.
+          #
+          # @return [String]
+          def identifier
+            return "#{index}-#{step_class.name}"
+          end
+
+        end
+
+      end
+    end
+  end
+end

data/lib/highway/compiler/build/output/manifest.rb

@@ -0,0 +1,52 @@
+#
+# manifest.rb
+# Copyright © 2019 Netguru S.A. All rights reserved.
+#
+
+require "highway/compiler/build/output/invocation"
+
+module Highway
+  module Compiler
+    module Build
+      module Output
+
+        # This class represents a build manifest. It contains compiled step
+        # invocations.
+        class Manifest
+
+          public
+
+          # Initialize an instance.
+          def initialize()
+            @invocations = Array.new()
+          end
+
+          # The preset.
+          #
+          # @return [String]
+          attr_accessor :preset
+
+          # Invocations in the manifest.
+          #
+          # @return [Array<Highway::Compiler::Build::Output::Invocation>]
+          attr_reader :invocations
+
+          # Add an invocation to the manifest.
+          #
+          # @param index [Integer] Index of invocation, 1-based.
+          # @param step_class [Class] Definition class of the step.
+          # @param parameters [Highway::Compiler::Analyze::Tree::Values::Hash] Hash value of step parameters.
+          # @param policy [:normal, :always] Execution policy of the step invocation.
+          # @param keypath [Array<String>] A keypath used for debugging purposes.
+          #
+          # @return [Void]
+          def add_invocation(index:, step_class:, parameters:, policy:, keypath:)
+            @invocations << Invocation.new(index: index, step_class: step_class, parameters: parameters, policy: policy, keypath: keypath)
+          end
+
+        end
+
+      end
+    end
+  end
+end

data/lib/highway/compiler/parse/parser.rb

@@ -0,0 +1,92 @@
+#
+# parser.rb
+# Copyright © 2019 Netguru S.A. All rights reserved.
+#
+
+require "yaml"
+
+require "highway/compiler/parse/versions/v1"
+
+module Highway
+  module Compiler
+    module Parse
+
+      # This class is responsible for syntactic analysis of a configuration
+      # file. This is the first phase of the compiler.
+      class Parser
+
+        public
+
+        # Initialize an instance.
+        #
+        # @param interface [Highway::Interface] The interface.
+        def initialize(interface:)
+          @interface = interface
+        end
+
+        # Parse the configuration file.
+        #
+        # The parser is backwards compatible with previous versions of
+        # configuration files.
+        #
+        # This method only loads the file, searches for the version declaration
+        # and then delegates the wotk to parser of a particular version.
+        #
+        # The parser produces a parse tree which is then used by semantic
+        # analysis phase to produce semantic tree.
+        #
+        # @param path [String] Path to configuration file.
+        #
+        # @return [Highway::Compiler::Parse::Tree::Root]
+        def parse(path:)
+
+          # Load the file.
+
+          unless File.exist?(path)
+            @interface.fatal!("The configuration file '#{path}' does not exist.")
+          end
+
+          begin
+            raw = YAML.load_file(path)
+          rescue StandardError => error
+            @interface.fatal!("The configuration file '#{path}' is not a valid YAML file.")
+          end
+
+          # Make sure it contains a hash.
+
+          unless raw.is_a?(Hash)
+            @interface.fatal!("The configuration file does not contain a top-level dictionary.")
+          end
+
+          # Specify the known versions and their corresponding subparsers.
+
+          known = {
+            1 => Parse::Versions::V1,
+          }
+
+          # Find and validate the version.
+
+          unless version = (Integer(raw.fetch("version", nil)) rescue nil)
+            @interface.fatal!("Missing or invalid value of: 'version'.")
+          end
+
+          unless known.keys.include?(version)
+            expected_versions = known.keys.map { |v| "'#{v}'" }.join(", ")
+            @interface.fatal!("Invalid value of: 'version'. Expected one of: [#{expected_versions}], got: '#{version}'.")
+          end
+
+          # Delegate the work to parser of a specific version.
+
+          subparser = known[version].new(interface: @interface)
+
+          # Parse and return the tree.
+
+          subparser.parse(raw: raw)
+
+        end
+
+      end
+
+    end
+  end
+end

data/lib/highway/compiler/parse/tree/root.rb

@@ -0,0 +1,73 @@
+#
+# root.rb
+# Copyright © 2019 Netguru S.A. All rights reserved.
+#
+
+require "highway/compiler/parse/tree/step"
+require "highway/compiler/parse/tree/variable"
+
+module Highway
+  module Compiler
+    module Parse
+      module Tree
+
+        # This class represents a root node of a parse tree. It contains other
+        # nodes, such as variables and steps.
+        class Root
+
+          public
+
+          # Initialize an instance.
+          #
+          # @param version [Integer] Version of the parse tree.
+          def initialize(version:)
+            @version = version
+            @variables = Array.new()
+            @steps = Array.new()
+          end
+
+          # Version of the parse tree.
+          #
+          # @return [Integer]
+          attr_reader :version
+
+          # Variables in the tree.
+          #
+          # @return [Array<Highway::Compiler::Parse::Tree::Variable>]
+          attr_reader :variables
+
+          # Steps in the tree.
+          #
+          # @return [Array<Highway::Compiler::Parse::Tree::Step>]
+          attr_reader :steps
+
+          # Add a variable to the tree.
+          #
+          # @param name [String] Name of the variable.
+          # @param value [String] Raw value of the variable.
+          # @param preset [String] Parent preset of the variable.
+          #
+          # @return [Void]
+          def add_variable(name:, value:, preset:)
+            @variables << Variable.new(name: name, value: value, preset: preset)
+          end
+
+          # Add a step to the tree.
+          #
+          # @param index [Integer] Index of step in its scope.
+          # @param name [String] Name of the step.
+          # @param parameters [Hash] Parameters of the step.
+          # @param preset [String] Parent preset of the step.
+          # @param stage [String] Parent stage of the step.
+          #
+          # @return [Void]
+          def add_step(name:, parameters:, preset:, stage:, index:)
+            @steps << Step.new(index: index, name: name, parameters: parameters, preset: preset, stage: stage)
+          end
+
+        end
+
+      end
+    end
+  end
+end

data/lib/highway/compiler/parse/tree/step.rb

@@ -0,0 +1,62 @@
+#
+# step.rb
+# Copyright © 2019 Netguru S.A. All rights reserved.
+#
+
+module Highway
+  module Compiler
+    module Parse
+      module Tree
+
+        # This class represents a step node in a parse tree. It contains
+        # information about a single step and its parameters.
+        class Step
+
+          public
+
+          # Initialize an instance.
+          #
+          # @param index [Integer] Index of step in its scope.
+          # @param name [String] Name of the step.
+          # @param parameters [Hash] Parameters of the step.
+          # @param preset [String] Parent preset of the step.
+          # @param stage [String] Parent stage of the step.
+          def initialize(index:, name:, parameters:, preset:, stage:)
+            @name = name
+            @parameters = parameters
+            @preset = preset
+            @stage = stage
+            @index = index
+          end
+
+          # Name of the step.
+          #
+          # @return [String]
+          attr_reader :name
+
+          # Parameters of the step.
+          #
+          # @return [Hash]
+          attr_reader :parameters
+
+          # Parent preset of the step.
+          #
+          # @return [String]
+          attr_reader :preset
+
+          # Parent stage of the step.
+          #
+          # @return [String]
+          attr_reader :stage
+
+          # Index of step in its scope.
+          #
+          # @return [Integer]
+          attr_reader :index
+
+        end
+
+      end
+    end
+  end
+end

data/lib/highway/compiler/parse/tree/variable.rb

@@ -0,0 +1,48 @@
+#
+# variable.rb
+# Copyright © 2019 Netguru S.A. All rights reserved.
+#
+
+module Highway
+  module Compiler
+    module Parse
+      module Tree
+
+        # This class represents a variable node in a parse tree. It contains
+        # information about a single variable.
+        class Variable
+
+          public
+
+          # Initialize an instance.
+          #
+          # @param name [String] Name of the variable.
+          # @param value [String] Raw value of the variable.
+          # @param preset [String] Parent preset of the variable.
+          def initialize(name:, value:, preset:)
+            @name = name
+            @value = value
+            @preset = preset
+          end
+
+          # Name of the variable.
+          #
+          # @return [String]
+          attr_reader :name
+
+          # Raw value of the variable.
+          #
+          # @return [String]
+          attr_reader :value
+
+          # Parent preset of the variable.
+          #
+          # @return [String]
+          attr_reader :preset
+
+        end
+
+      end
+    end
+  end
+end

data/lib/highway/compiler/parse/versions/v1.rb

@@ -0,0 +1,110 @@
+#
+# v1.rb
+# Copyright © 2019 Netguru S.A. All rights reserved.
+#
+
+require "highway/compiler/parse/tree/root"
+
+module Highway
+  module Compiler
+    module Parse
+      module Versions
+
+        # This class is responsible for parsing a configuration file v1.
+        class V1
+
+          public
+
+          # Initialize an instance.
+          #
+          # @param reporter [Highway::Interface] The interface.
+          def initialize(interface:)
+            @interface = interface
+          end
+
+          # Parse the configuration file v1.
+          #
+          # @param raw [Hash] Raw content of configuration file.
+          #
+          # @return [Highway::Compiler::Parse::Tree::Root]
+          def parse(raw:)
+
+            parse_tree = Parse::Tree::Root.new(version: 1)
+
+            validate_toplevel_keys(raw: raw)
+
+            parse_variables(raw: raw, parse_tree: parse_tree)
+            parse_steps(raw: raw, parse_tree: parse_tree)
+
+            parse_tree
+
+          end
+
+          private
+
+          def validate_toplevel_keys(raw:)
+            expected = %w(version variables bootstrap test deploy report)
+            raw.each_key do |key|
+              assert_toplevel_key_valid(key, expected: expected)
+            end
+          end
+
+          def parse_variables(raw:, parse_tree:)
+            variables = raw.fetch("variables", {})
+            assert_value_type(variables, expected: Hash, keypath: ["variables"])
+            variables.each_pair do |preset, names_and_values|
+              assert_value_type(names_and_values, expected: Hash, keypath: ["variables", preset])
+              names_and_values.each_pair do |name, value|
+                parse_tree.add_variable(name: name, value: value, preset: preset)
+              end
+            end
+          end
+
+          def parse_steps(raw:, parse_tree:)
+            %w(bootstrap test deploy report).each do |stage|
+              presets = raw.fetch(stage, {})
+              assert_value_type(presets, expected: Hash, keypath: [stage])
+              presets.each_pair do |preset, steps|
+                assert_value_type(steps, expected: Array, keypath: [stage, preset])
+                steps.each_with_index do |step, step_index|
+                  assert_value_type(step, expected: Hash, keypath: [stage, preset, step_index])
+                  assert_value_length(step, expected: 1, keypath: [stage, preset, step_index])
+                  assert_value_type(step.values.first, expected: Hash, keypath: [stage, preset, step.keys.first])
+                  parse_tree.add_step(index: step_index, name: step.keys.first, parameters: step.values.first, preset: preset, stage: stage)
+                end
+              end
+            end
+          end
+
+          def assert_toplevel_key_valid(actual, expected:)
+            unless expected.include?(actual)
+              expected_keys = expected.map { |key| "'#{key}'" }.join(", ")
+              @interface.fatal!("Invalid top-level key: '#{actual}'. Expected one of: [#{expected_keys}].")
+            end
+          end
+
+          def assert_value_type(actual, expected:, keypath:)
+            if expected.is_a?(Class)
+              unless actual.is_a?(expected)
+                @interface.fatal!("Invalid type of value: '#{actual}' at: '#{keypath}'. Expected: '#{expected}', got: '#{actual.class}'.")
+              end
+            elsif expected.is_a?(Array)
+              unless (expected.any? { |klass| actual.is_a?(klass) })
+                expected_types = expected.map { |klass| "'#{klass}'"}.join(", ")
+                @interface.fatal!("Invalid type of value: '#{actual}' at: '#{keypath}'. Expected one of: [#{expected_types}], got: '#{actual.class}'.")
+              end
+            end
+          end
+
+          def assert_value_length(actual, expected:, keypath:)
+            unless actual.length == expected
+              @interface.fatal!("Invalid length of value at: '#{keypath}'. Expected: #{expected}, got: #{actual}.")
+            end
+          end
+
+        end
+
+      end
+    end
+  end
+end