bolt 2.31.0 → 2.35.0

data/lib/bolt/{puppetfile → module_installer}/installer.rb

@@ -1,19 +1,20 @@
 # frozen_string_literal: true
 
-require 'r10k/cli'
 require 'bolt/r10k_log_proxy'
 require 'bolt/error'
 
 # This class is used to install modules from a Puppetfile to a module directory.
 #
 module Bolt
-  class Puppetfile
+  class ModuleInstaller
     class Installer
       def initialize(config = {})
         @config = config
       end
 
       def install(path, moduledir)
+        require 'r10k/cli'
+
         unless File.exist?(path)
           raise Bolt::FileError.new(
             "Could not find a Puppetfile at #{path}",

data/lib/bolt/module_installer/puppetfile.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/module_installer/puppetfile/forge_module'
+require 'bolt/module_installer/puppetfile/git_module'
+
+# This class manages the logical contents of a Puppetfile. It includes methods
+# for parsing and generating a Puppetfile.
+#
+module Bolt
+  class ModuleInstaller
+    class Puppetfile
+      attr_reader :modules
+
+      def initialize(modules = [])
+        @modules = modules
+      end
+
+      # Loads a Puppetfile and parses its modules.
+      #
+      def self.parse(path, skip_unsupported_modules: false)
+        require 'puppetfile-resolver'
+
+        return new unless path.exist?
+
+        begin
+          parsed = ::PuppetfileResolver::Puppetfile::Parser::R10KEval.parse(File.read(path))
+        rescue StandardError => e
+          raise Bolt::Error.new(
+            "Unable to parse Puppetfile #{path}: #{e.message}",
+            'bolt/puppetfile-parsing'
+          )
+        end
+
+        unless parsed.valid?
+          raise Bolt::ValidationError, <<~MSG
+            Unable to parse Puppetfile #{path}:
+            #{parsed.validation_errors.join("\n\n")}.
+            This may not be a Puppetfile managed by Bolt.
+          MSG
+        end
+
+        modules = parsed.modules.each_with_object([]) do |mod, acc|
+          case mod.module_type
+          when :forge
+            acc << ForgeModule.new(
+              mod.title,
+              mod.version.is_a?(String) ? mod.version[1..-1] : nil
+            )
+          when :git
+            acc << GitModule.new(
+              mod.name,
+              mod.remote,
+              mod.ref || mod.commit || mod.tag
+            )
+          else
+            unless skip_unsupported_modules
+              raise Bolt::ValidationError,
+                    "Cannot parse Puppetfile at #{path}, module '#{mod.title}' is not a "\
+                    "Puppet Forge or Git module."
+            end
+          end
+        end
+
+        new(modules)
+      end
+
+      # Writes a Puppetfile that includes specifications for each of the
+      # modules.
+      #
+      def write(path, moduledir = nil)
+        File.open(path, 'w') do |file|
+          if moduledir
+            file.puts "# This Puppetfile is managed by Bolt. Do not edit."
+            file.puts "# For more information, see https://pup.pt/bolt-modules"
+            file.puts
+            file.puts "# The following directive installs modules to the managed moduledir."
+            file.puts "moduledir '#{moduledir.basename}'"
+            file.puts
+          end
+
+          @modules.each { |mod| file.puts mod.to_spec }
+        end
+      rescue SystemCallError => e
+        raise Bolt::FileError.new(
+          "#{e.message}: unable to write Puppetfile.",
+          path
+        )
+      end
+
+      # Asserts that the Puppetfile satisfies the given specifications.
+      #
+      def assert_satisfies(specs)
+        unsatisfied_specs = specs.specs.reject do |spec|
+          @modules.any? do |mod|
+            spec.satisfied_by?(mod)
+          end
+        end
+
+        return if unsatisfied_specs.empty?
+
+        command = Bolt::Util.windows? ? 'Install-BoltModule -Force' : 'bolt module install --force'
+
+        message = <<~MESSAGE.chomp
+          Puppetfile does not include modules that satisfy the following specifications:
+
+          #{unsatisfied_specs.map(&:to_hash).to_yaml.lines.drop(1).join.chomp}
+          
+          This may not be a Puppetfile managed by Bolt. To forcibly overwrite the
+          Puppetfile, run '#{command}'.
+        MESSAGE
+
+        raise Bolt::Error.new(message, 'bolt/missing-module-specs')
+      end
+    end
+  end
+end

data/lib/bolt/module_installer/puppetfile/forge_module.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'semantic_puppet'
+require 'bolt/module_installer/puppetfile/module'
+
+# This class represents a resolved Forge module.
+#
+module Bolt
+  class ModuleInstaller
+    class Puppetfile
+      class ForgeModule < Module
+        attr_reader :version
+
+        def initialize(name, version)
+          super(name)
+          @version = parse_version(version)
+          @type    = :forge
+        end
+
+        # Parses the version into a Semantic Puppet version.
+        #
+        private def parse_version(version)
+          return unless version.is_a?(String)
+
+          unless SemanticPuppet::Version.valid?(version)
+            raise Bolt::ValidationError,
+                  "Invalid version for Forge module #{@full_name}: #{version.inspect}"
+          end
+
+          SemanticPuppet::Version.parse(version)
+        end
+
+        # Returns a Puppetfile module specification.
+        #
+        def to_spec
+          if @version
+            "mod '#{@full_name}', '#{@version}'"
+          else
+            "mod '#{@full_name}'"
+          end
+        end
+
+        # Returns a hash that can be used to create a module specification.
+        #
+        def to_hash
+          {
+            'name'                => @full_name,
+            'version_requirement' => @version ? @version.to_s : nil
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/bolt/module_installer/puppetfile/git_module.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'bolt/module_installer/puppetfile/module'
+
+# This class represents a resolved Git module.
+#
+module Bolt
+  class ModuleInstaller
+    class Puppetfile
+      class GitModule < Module
+        attr_reader :git, :ref
+
+        def initialize(name, git, ref)
+          super(name)
+          @git  = git
+          @ref  = ref
+          @type = :git
+        end
+
+        # Returns a Puppetfile module specification.
+        #
+        def to_spec
+          "mod '#{@name}',\n  git: '#{@git}',\n  ref: '#{@ref}'"
+        end
+
+        # Returns a hash that can be used to create a module specification.
+        #
+        def to_hash
+          {
+            'git' => @git,
+            'ref' => @ref
+          }
+        end
+      end
+    end
+  end
+end

data/lib/bolt/module_installer/puppetfile/module.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+module Bolt
+  class ModuleInstaller
+    class Puppetfile
+      class Module
+        attr_reader :full_name, :name, :type
+
+        def initialize(name)
+          @full_name, @name = parse_name(name)
+        end
+
+        # Formats the full name and extracts the module name.
+        #
+        protected def parse_name(name)
+          full_name     = name.tr('-', '/')
+          first, second = full_name.split('/', 2)
+
+          [full_name, second || first]
+        end
+      end
+    end
+  end
+end

data/lib/bolt/module_installer/resolver.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/module_installer/puppetfile'
+require 'bolt/module_installer/specs'
+
+module Bolt
+  class ModuleInstaller
+    class Resolver
+      # Resolves module specs and returns a Puppetfile object.
+      #
+      def resolve(specs)
+        require 'puppetfile-resolver'
+
+        # Build the document model from the specs.
+        document = PuppetfileResolver::Puppetfile::Document.new('')
+
+        specs.specs.each do |spec|
+          document.add_module(spec.to_resolver_module)
+        end
+
+        # Make sure the document model is valid.
+        unless document.valid?
+          message = <<~MESSAGE.chomp
+            Unable to resolve module specifications:
+
+            #{document.validation_errors.map(&:message).join("\n")}
+          MESSAGE
+
+          raise Bolt::Error.new(message, 'bolt/module-resolver-error')
+        end
+
+        # Create the resolver using the Puppetfile model. nil disables Puppet
+        # version restrictions.
+        resolver = PuppetfileResolver::Resolver.new(document, nil)
+
+        # Configure and resolve the dependency graph, catching any errors
+        # raised by puppetfile-resolver and re-raising them as Bolt errors.
+        begin
+          result = resolver.resolve(
+            cache:                 nil,
+            ui:                    nil,
+            module_paths:          [],
+            allow_missing_modules: false
+          )
+        rescue StandardError => e
+          raise Bolt::Error.new(e.message, 'bolt/module-resolver-error')
+        end
+
+        # Convert the specs returned from the resolver into Bolt module objects.
+        modules = result.specifications.values.each_with_object([]) do |mod, acc|
+          # Skip over anything that isn't a module spec, such as a Puppet spec.
+          next unless mod.is_a? PuppetfileResolver::Models::ModuleSpecification
+
+          case mod.origin
+          when :forge
+            acc << Bolt::ModuleInstaller::Puppetfile::ForgeModule.new(
+              "#{mod.owner}/#{mod.name}",
+              mod.version.to_s
+            )
+          when :git
+            spec = specs.specs.find { |s| s.name == mod.name }
+            acc << Bolt::ModuleInstaller::Puppetfile::GitModule.new(
+              spec.name,
+              spec.git,
+              spec.sha
+            )
+          end
+        end
+
+        # Create the Puppetfile object.
+        Bolt::ModuleInstaller::Puppetfile.new(modules)
+      end
+    end
+  end
+end

data/lib/bolt/module_installer/specs.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/module_installer/specs/forge_spec'
+require 'bolt/module_installer/specs/git_spec'
+
+module Bolt
+  class ModuleInstaller
+    class Specs
+      def initialize(specs = [])
+        @specs = []
+        add_specs(specs)
+        assert_unique_names
+      end
+
+      # Creates a list of specs from the modules in a Puppetfile object.
+      #
+      def self.from_puppetfile(puppetfile)
+        new(puppetfile.modules.map(&:to_hash))
+      end
+
+      # Returns a list of specs.
+      #
+      def specs
+        @specs.uniq(&:name)
+      end
+
+      # Returns true if the specs includes the given name.
+      #
+      def include?(name)
+        _owner, name = name.tr('-', '/').split('/', 2)
+        @specs.any? { |spec| spec.name == name }
+      end
+
+      # Adds a spec.
+      #
+      def add_specs(*specs)
+        specs.flatten.map do |spec|
+          case spec
+          when Hash
+            @specs.unshift spec_from_hash(spec)
+          else
+            @specs.unshift spec
+          end
+        end
+      end
+
+      # Parses a spec hash into a spec object.
+      #
+      private def spec_from_hash(hash)
+        return ForgeSpec.new(hash) if ForgeSpec.implements?(hash)
+        return GitSpec.new(hash)   if GitSpec.implements?(hash)
+
+        raise Bolt::ValidationError, <<~MESSAGE.chomp
+          Invalid module specification:
+          #{hash.to_yaml.lines.drop(1).join.chomp}
+
+          To read more about specifying modules, see https://pup.pt/bolt-modules
+        MESSAGE
+      end
+
+      # Returns true if all specs are satisfied by the modules in a Puppetfile.
+      #
+      def satisfied_by?(puppetfile)
+        @specs.all? do |spec|
+          puppetfile.modules.any? do |mod|
+            spec.satisfied_by?(mod)
+          end
+        end
+      end
+
+      # Asserts that all specs are unique by name. The puppetfile-resolver
+      # library also does this, but the error it raises isn't as helpful.
+      #
+      private def assert_unique_names
+        duplicates = @specs.group_by(&:name).select { |_name, specs| specs.count > 1 }
+
+        if duplicates.any?
+          message = String.new
+
+          duplicates.each do |name, duplicate_specs|
+            message << <<~MESSAGE
+              Detected multiple module specifications with name #{name}:
+              #{duplicate_specs.map(&:to_hash).to_yaml.lines.drop(1).join}
+            MESSAGE
+          end
+
+          raise Bolt::Error.new(message.chomp, "bolt/duplicate-spec-name-error")
+        end
+      end
+    end
+  end
+end

data/lib/bolt/module_installer/specs/forge_spec.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'semantic_puppet'
+require 'set'
+
+require 'bolt/error'
+
+# This class represents a Forge module specification.
+#
+module Bolt
+  class ModuleInstaller
+    class Specs
+      class ForgeSpec
+        NAME_REGEX    = %r{\A[a-zA-Z0-9]+[-/](?<name>[a-z][a-z0-9_]*)\z}.freeze
+        REQUIRED_KEYS = Set.new(%w[name]).freeze
+        KNOWN_KEYS    = Set.new(%w[name version_requirement]).freeze
+
+        attr_reader :full_name, :name, :semantic_version, :type
+
+        def initialize(init_hash)
+          @full_name, @name                       = parse_name(init_hash['name'])
+          @version_requirement, @semantic_version = parse_version_requirement(init_hash['version_requirement'])
+          @type                                   = :forge
+        end
+
+        def self.implements?(hash)
+          KNOWN_KEYS.superset?(hash.keys.to_set) && REQUIRED_KEYS.subset?(hash.keys.to_set)
+        end
+
+        # Formats the full name and extracts the module name.
+        #
+        private def parse_name(name)
+          unless (match = name.match(NAME_REGEX))
+            raise Bolt::ValidationError,
+                  "Invalid name for Forge module specification: #{name}. Name must match "\
+                  "'owner/name'. Owner segment may only include letters or digits. Name "\
+                  "segment must start with a lowercase letter and may only include lowercase "\
+                  "letters, digits, and underscores."
+          end
+
+          [name.tr('-', '/'), match[:name]]
+        end
+
+        # Parses the version into a Semantic Puppet version range.
+        #
+        private def parse_version_requirement(version_requirement)
+          [version_requirement, SemanticPuppet::VersionRange.parse(version_requirement || '>= 0')]
+        rescue StandardError
+          raise Bolt::ValidationError,
+                "Invalid version requirement for Forge module specification #{@full_name}: "\
+                "#{version_requirement.inspect}"
+        end
+
+        # Returns true if the specification is satisfied by the module.
+        #
+        def satisfied_by?(mod)
+          @type == mod.type &&
+            @full_name.downcase == mod.full_name.downcase &&
+            !mod.version.nil? &&
+            @semantic_version.cover?(mod.version)
+        end
+
+        # Returns a hash matching the module spec in bolt-project.yaml
+        #
+        def to_hash
+          {
+            'name'                => @full_name,
+            'version_requirement' => @version_requirement
+          }.compact
+        end
+
+        # Creates a PuppetfileResolver::Puppetfile::ForgeModule object, which is
+        # used to generate a graph of resolved modules.
+        #
+        def to_resolver_module
+          require 'puppetfile-resolver'
+
+          PuppetfileResolver::Puppetfile::ForgeModule.new(@full_name).tap do |mod|
+            mod.version = @version_requirement
+          end
+        end
+      end
+    end
+  end
+end