openbolt 5.0.0.rc1

data/lib/bolt/module.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Is this Bolt::Pobs::Module?
+module Bolt
+  class Module
+    CONTENT_NAME_REGEX = /\A[a-z][a-z0-9_]*(::[a-z][a-z0-9_]*)*\z/.freeze
+    MODULE_NAME_REGEX  = /\A[a-z][a-z0-9_]*\z/.freeze
+
+    def self.discover(modulepath, project)
+      mods = {}
+
+      if project.load_as_module?
+        mods[project.name] = Bolt::Module.new(project.name, project.path.to_s)
+      end
+
+      modulepath.each do |path|
+        next unless File.exist?(path) && File.directory?(path)
+        Dir.children(path)
+           .map { |dir| File.join(path, dir) }
+           .select { |dir| File.directory?(dir) }
+           .each do |dir|
+          module_name = File.basename(dir)
+          if module_name =~ MODULE_NAME_REGEX
+            # Puppet will load some objects from shadowed modules but this won't
+            mods[module_name] ||= Bolt::Module.new(module_name, dir)
+          end
+        end
+      end
+
+      mods
+    end
+
+    attr_reader :name, :path
+
+    def initialize(name, path)
+      @name = name
+      @path = path
+    end
+
+    def plugin_data_file
+      File.join(path, 'bolt_plugin.json')
+    end
+
+    def plugin?
+      if File.exist?(File.join(path, 'bolt-plugin.json'))
+        msg = "Found bolt-plugin.json in module #{name} at #{path}. Bolt looks for " \
+          "bolt_plugin.json to determine if the module contains plugins. " \
+          "Rename the file for Bolt to recognize it."
+        Bolt::Logger.warn_once('plugin_file_name', msg)
+      end
+      File.exist?(plugin_data_file)
+    end
+  end
+end

data/lib/bolt/module_installer/installer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative '../../bolt/r10k_log_proxy'
+require_relative '../../bolt/error'
+
+# This class is used to install modules from a Puppetfile to a module directory.
+#
+module Bolt
+  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}",
+            path
+          )
+        end
+
+        r10k_opts = {
+          root:       File.dirname(path),
+          puppetfile: path.to_s,
+          moduledir:  moduledir.to_s
+        }
+
+        settings = R10K::Settings.global_settings.evaluate(@config)
+        R10K::Initializers::GlobalInitializer.new(settings).call
+        install_action = R10K::Action::Puppetfile::Install.new(r10k_opts, nil, {})
+
+        # Override the r10k logger with a proxy to our own logger
+        R10K::Logging.instance_variable_set(:@outputter, Bolt::R10KLogProxy.new)
+
+        install_action.call
+      rescue R10K::Error => e
+        raise PuppetfileError, e
+      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_relative '../../../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_relative '../../../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_relative '../../../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/puppetfile.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative '../../bolt/error'
+require_relative 'puppetfile/forge_module'
+require_relative '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 Puppetfile might not be 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
+
+        versionless_mods = @modules.select { |mod| mod.is_a?(ForgeModule) && mod.version.nil? }
+        command = Bolt::Util.windows? ? 'Install-BoltModule -Force' : 'bolt module install --force'
+
+        if unsatisfied_specs.any?
+          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 Puppetfile might not be managed by Bolt. To forcibly overwrite the
+            Puppetfile, run '#{command}'.
+          MESSAGE
+
+          raise Bolt::Error.new(message, 'bolt/missing-module-specs')
+        end
+
+        if versionless_mods.any?
+          message = <<~MESSAGE.chomp
+            Puppetfile includes Forge modules without a version requirement:
+            
+            #{versionless_mods.map(&:to_spec).join.chomp}
+            
+            This Puppetfile might not be managed by Bolt. To forcibly overwrite the
+            Puppetfile, run '#{command}'.
+          MESSAGE
+
+          raise Bolt::Error.new(message, 'bolt/missing-module-version-specs')
+        end
+      end
+    end
+  end
+end

data/lib/bolt/module_installer/resolver.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative '../../bolt/error'
+require_relative '../../bolt/module_installer/puppetfile'
+require_relative '../../bolt/module_installer/specs'
+
+module Bolt
+  class ModuleInstaller
+    class Resolver
+      # Resolves module specs and returns a Puppetfile object.
+      #
+      def resolve(specs, config = {})
+        require 'puppetfile-resolver'
+
+        # Build the document model from the specs.
+        document   = PuppetfileResolver::Puppetfile::Document.new('')
+        unresolved = []
+
+        specs.specs.each do |spec|
+          if spec.resolve
+            document.add_module(spec.to_resolver_module)
+          else
+            unresolved << spec
+          end
+        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,
+            allow_missing_modules:       false,
+            spec_searcher_configuration: spec_searcher_config(config)
+          )
+        rescue StandardError => e
+          raise Bolt::Error.new("Unable to resolve modules: #{e.message}", 'bolt/module-resolver-error')
+        end
+
+        # Create the Puppetfile object.
+        generate_puppetfile(specs, result.specifications.values, unresolved)
+      end
+
+      # Creates a puppetfile-resolver config object.
+      #
+      private def spec_searcher_config(config)
+        PuppetfileResolver::SpecSearchers::Configuration.new.tap do |obj|
+          obj.forge.proxy     = config.dig('forge', 'proxy') || config.dig('proxy')
+          obj.git.proxy       = config.dig('proxy')
+          obj.forge.forge_api = config.dig('forge', 'baseurl')
+        end
+      end
+
+      # Creates a Puppetfile object with Module objects created from resolved and
+      # unresolved specs.
+      #
+      private def generate_puppetfile(specs, resolved, unresolved)
+        modules = []
+
+        # Convert the resolved specs into Bolt module objects.
+        resolved.each do |mod|
+          # 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
+            modules << Bolt::ModuleInstaller::Puppetfile::ForgeModule.new(
+              "#{mod.owner}/#{mod.name}",
+              mod.version.to_s
+            )
+          when :git
+            spec = specs.specs.find { |s| s.name == mod.name }
+            modules << Bolt::ModuleInstaller::Puppetfile::GitModule.new(
+              spec.name,
+              spec.git,
+              spec.sha
+            )
+          end
+        end
+
+        # Error if there are any name conflicts between unresolved specs and
+        # resolved modules. r10k will error if a Puppetfile includes duplicate
+        # names, but we error early here to provide a more helpful message.
+        if (name_conflicts = modules.map(&:name) & unresolved.map(&:name)).any?
+          raise Bolt::Error.new(
+            "Detected unresolved module specifications with the same name as a resolved module "\
+            "dependency: #{name_conflicts.join(', ')}. Either remove the unresolved module specification "\
+            "or set the module with the conflicting dependency to not resolve.",
+            "bolt/module-name-conflict-error"
+          )
+        end
+
+        # Convert the unresolved specs into Bolt module objects.
+        unresolved.each do |spec|
+          case spec.type
+          when :forge
+            modules << Bolt::ModuleInstaller::Puppetfile::ForgeModule.new(
+              spec.full_name,
+              spec.version_requirement
+            )
+          when :git
+            modules << Bolt::ModuleInstaller::Puppetfile::GitModule.new(
+              spec.name,
+              spec.git,
+              spec.ref
+            )
+          end
+        end
+
+        Bolt::ModuleInstaller::Puppetfile.new(modules)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'semantic_puppet'
+require 'set'
+
+require_relative '../../../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 resolve version_requirement]).freeze
+
+        attr_reader :full_name, :name, :resolve, :semantic_version, :type, :version_requirement
+
+        def initialize(init_hash)
+          @resolve                                = init_hash.key?('resolve') ? init_hash['resolve'] : true
+          @full_name, @name                       = parse_name(init_hash['name'])
+          @version_requirement, @semantic_version = parse_version_requirement(init_hash['version_requirement'])
+          @type                                   = :forge
+
+          unless @resolve == true || @resolve == false
+            raise Bolt::ValidationError,
+                  "Option 'resolve' for module spec #{@full_name} must be a Boolean"
+          end
+        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 can only include letters or digits. Name "\
+                  "segment must start with a lowercase letter and can 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