builderator 0.3.15 → 1.0.0.pre.rc.1

data/docs/configuration/profile.md

@@ -0,0 +1,71 @@
+Collection `profile`
+====================
+
+A profile is a combination of Chef parameters, and Vagrant and Packer configurations. Profiles should provide
+
+* `tags, type: hash` EC2 tags to apply to instances and AMIs
+* `log_level` Chef log-level. Default `:info`
+
+## Collection `artifact`
+
+An externally managed resource to push to VMs and image builds, e.g. `bundle.tar.gz` from a Maven build.
+
+* `path` The workspace-rooted path to the artifact
+* `destination` The absolute path on the VM or image at which the artifact should be placed
+
+## Namespace `chef`
+* `run_list, type: list, singular: run_list_item, unique: true` The Chef runlist for this profile
+* `environment` The Chef environment to load for this
+* `node_attrs, type: hash` A hash of node attributes for this profile
+
+
+## Namespace `packer`
+
+Packer configurations for this profile
+
+### Collection `build`
+
+Add a packer build
+
+* `type` the build provider (e.g. amazon-ebs, virtualbox)
+* `instance_type` the EC2 instance type to use
+* `source_ami` The source AMI ID for an `amazon-ebs`
+* `ssh_username` Default `ubuntu`
+* `ami_virtualization_type` Default `hvm`
+
+## TODO: Share accounts
+
+* `ami_name` Name for new AMI
+* `ami_description` Description for the new AMI
+
+
+## Namespace `vagrant`
+
+Vagrant VM configurations
+
+### Namespace `local`
+
+Parameters for a local VM build
+
+* `provider` Default `virtualbox`
+* `box` Default `ubuntu-14.04-x86_64`
+* `box_url` Default `https://cloud-images.ubuntu.com/vagrant/trusty/current/trusty-server-cloudimg-amd64-vagrant-disk1.box`
+
+* `cpus` Default 2
+* `memory` Default 1024 (MB)
+
+## Namespace `ec2`
+
+Parameters for the provisioning EC2 nodes with Vagrant
+
+* `provider` Default `aws`
+* `box` Default `dummy`
+* `box_url` Default `https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box`
+* `instance_type`
+* `source_ami`
+* `ssh_username`
+* `virtualization_type`
+* `instance_profile`
+* `subnet_id`
+* `security_groups, type: list, singular: security_group, unique: true`
+* `public_ip`

data/docs/versioning.md

@@ -0,0 +1,65 @@
+Versioning
+==========
+
+This functionality is currently supported for Git.
+
+## Version Bump Steps
+
+* `major` - Increment major version.
+* `major-prerelease` - Start a pre-release train from the next major version (increments major version).
+* `minor` - Increment minor version.
+* `minor-prerelease` - Start a pre-release train from the next minor version (increments minor version).
+* `patch` - Increment the patch version.
+* `patch-prerelease` - Force a new pre-release train from the next patch version, even if the current version is a pre-release.
+* `release` - Release a pre-release train a the current `major`.`minor`.`patch` version.
+* `prerelease NAME` Create or increment a pre-release version. If the current version is not a pre-release, the patch version will also be incremented.
+* `build` Add or increment a build number.
+
+Step types are an ordered-set. Incrementing a higher step resets all lower parameters.
+
+## Commands
+
+### `build version current`
+
+Searches for the newest SCM tag that is a valid sem-ver string and writes it to VERSION in the project root.
+
+### `build version bump [STEP [PRERELEASE_NAME=alpha]]`
+
+Increment the current version by the desired step and create a new SCM tag at HEAD.
+
+If STEP is omitted, Builderator will scan messages of commits between HEAD and the current version tag for hash-tag style annotations indicating how to increment the version, finally defaulting to a `patch` step if no annotations are found. If multiple `#STEP` annotations are detected, the largest (e.g. `#major` > `#patch`) step will be applied.
+
+## Configuration
+
+The `autoversion` namespace has two attributes:
+
+* `create_tags BOOLEAN` enables auto-generation of SCM tags after `bump` tasks. Default `true`.
+* `search_tags` enables detection of the current version from SCM tags. Default `true`.
+
+```ruby
+autoversion do |version|
+  version.create_tags true
+  version.search_tags true
+end
+```
+
+## Adding Providers
+
+SCM providers must extend the `Builderator::Control::Version::SCM` module, and must implement two methods in their singleton class:
+
+* `self._history` Return an array of hashes with the following keys:
+  - `:id` SCM commit identity
+  - `:message` SCM commit message
+  - `:tags` `nil` or an array of semver strings
+* `self.supported?` Return `true` if the provider supports the build environment (e.g. the `Git` provider checks that `pwd` is a git repository), else return `false`.
+
+To enable a provider module, pass it to `SCM.register`. See [blob/auto-version/lib/builderator/control/version/git.rb] for an example.
+
+## This looks like `thor-scmversion`
+
+_Why aren't you using `thor-scmversion`?!_
+
+Well yes, it's based upon `thor-scmversion`, which I've been using for a while. `thor-scmversion` provides a nice model to ensure correct versioning of automatically built modules, but the project is largely abandoned, lacks some key features required for Builderator, and has a very inefficient access path for reading Git SCM data.
+
+This implementation adds `TYPE-prerelease` bump steps, improves semver matching regular-expressions, dramatically improves git-data access time for repositories with many tags (only reads from git-blobs once),
+and de-couples core functionality for parsing and incrementing versions from Thor tasks and actual mutation of the repository.

data/lib/builderator.rb

@@ -1,4 +1,7 @@
 require 'builderator/metadata'
 
+##
+# Start Namespace
+##
 module Builderator
 end

data/lib/builderator/config.rb

@@ -0,0 +1,93 @@
+require_relative './config/file'
+require_relative './config/defaults'
+
+module Builderator
+  ##
+  # Global Configuration
+  ##
+  module Config
+    class << self
+      ## GLOBAL_DEFAULTS is the lowest-precedence layer, followed by dynamically
+      ## defined instance-defaults.
+      def layers
+        @layers ||= []
+      end
+
+      def all_layers
+        ([GLOBAL_DEFAULTS, defaults] + layers + [overrides, argv])
+      end
+
+      def defaults
+        @defaults ||= File.new({}, :source => 'defaults')
+      end
+
+      def overrides
+        @overrides ||= File.new({}, :source => 'overrides')
+      end
+
+      def argv(options = {})
+        @argv ||= File.new(options, :source => 'argv')
+      end
+
+      def append(path)
+        layers << File.from_file(path) if ::File.exist?(path)
+      end
+      alias_method :load, :append
+
+      def append_json(path)
+        layers << File.from_json(path) if ::File.exist?(path)
+      end
+      alias_method :load_json, :append_json
+
+      def prepend(path)
+        layers.unshift(File.from_file(path)) if ::File.exist?(path)
+      end
+
+      def prepend_json(path)
+        layers.unshift(File.from_json(path)) if ::File.exist?(path)
+      end
+
+      def compile(max_iterations = 4)
+        compiled.unseal
+        compile_iterations = 0
+
+        ## Automatically recompile while layers are dirty
+        loop do
+          fail "Re-compile iteration limit of #{max_iterations} has been exceeded" if compile_iterations >= max_iterations
+
+          ## Reset flags before next iteration
+          compiled.clean
+
+          ## Merge layers from lowest to highest
+          all_layers.each { |layer| compiled.merge(layer.compile) }
+
+          break unless dirty?
+          compile_iterations += 1
+        end
+
+        ## Don't auto-populate keys anymore
+        compiled.seal
+      end
+      alias_method :recompile, :compile
+
+      def dirty?
+        all_layers.any?(&:dirty) || compiled.dirty
+      end
+
+      def compiled
+        @compiled ||= File.new
+      end
+
+      def fetch(key, *args)
+        compiled.send(key, *args)
+      end
+      alias_method :[], :fetch
+
+      def method_missing(method_name, *args)
+        return super unless compiled.respond_to?(method_name)
+
+        compiled.send(method_name, *args)
+      end
+    end
+  end
+end

data/lib/builderator/config/attributes.rb

@@ -0,0 +1,287 @@
+require 'forwardable'
+require 'json'
+
+require_relative './rash'
+
+module Builderator
+  module Config
+    ##
+    # Shared Attribute Mixin
+    ##
+    class Attributes
+      ##
+      # DSL Definition
+      ##
+      class << self
+        def attribute(attribute_name, default = nil, **options)
+          ##
+          # Helpers for Array-type attributes
+          ##
+          if options[:type] == :list
+            default = Array
+
+            ## Add an appender DSL method
+            define_method(options[:singular]) do |*args|
+              append_if_valid(attribute_name, args.flatten, default, options)
+            end if options.include?(:singular)
+          end
+
+          ## Getter/Setter
+          define_method(attribute_name) do |*arg|
+            arg.flatten!
+            arg = arg.first unless options[:type] == :list
+
+            set_or_return(attribute_name, arg, default, options)
+          end
+
+          ## Setter
+          define_method("#{attribute_name}=") do |arg|
+            set_if_valid(attribute_name, arg, options)
+          end unless options[:type] == :list
+        end
+
+        ## Add a method the DSL
+        def define(method_name, &block)
+          define_method(method_name, &block)
+        end
+
+        ##
+        # A Namespace is a singleton sub-node of the attribute-set
+        #
+        # e.g. `namespace :chef ...` maps to `attributes[:chef]` and adds a
+        # method `chef(&block)` to the DSL which is used as follows:
+        #
+        # ```
+        # chef do
+        #   run_list 'foo', 'bar'
+        #   ...
+        # end
+        # ```
+        #
+        # Multiple calls to the DSL method will are safe and will
+        # update the same sub-node.
+        ##
+        def namespace(namespace_name, &definition)
+          namespace_class = Namespace.create(namespace_name, &definition)
+
+          define_method(namespace_name) do |&block|
+            nodes[namespace_name] ||= namespace_class.new(
+              @attributes[namespace_name],
+              :name => namespace_name, &block).compile
+          end
+        end
+
+        ##
+        # A Collection is a named-set of items in a sub-node of the attribute-set.
+        #
+        # Like Namespaces, Collections map to a top-level key, but they also have
+        # multiple second-order keys:
+        #
+        # e.g. `collection :vagrant ...` adds a DSL method
+        # `vagrant(name = :default, &block)` which maps to
+        # `attributes[:vagrant][<name>]`
+        #
+        # Multiple entities can be added to the collection by calling the DSL method
+        # with unique `name` arguments. Multiple calls to the DSL method with the
+        # same name argument will update the existing entity in place
+        ##
+        def collection(collection_name, &definition)
+          collection_class = Collection.create(collection_name, &definition)
+
+          define_method(collection_name) do |instance_name = nil, &block|
+            nodes[collection_name] ||= collection_class.new(
+              @attributes[collection_name])
+
+            return nodes[collection_name] if instance_name.nil?
+            nodes[collection_name].fetch(instance_name, &block).compile
+          end
+        end
+      end
+
+      extend Forwardable
+      include Enumerable
+
+      ## Delegate enumerables to underlying storage structure
+      def_delegators :@attributes, :[], :fetch,
+                     :keys, :values, :has?, :each,
+                     :to_hash
+
+      def seal
+        attributes.seal
+        self
+      end
+
+      def unseal
+        attributes.unseal
+        self
+      end
+
+      attr_reader :attributes
+      attr_reader :nodes
+      attr_reader :dirty
+
+      def initialize(attributes = {}, &block)
+        @attributes = Rash.coerce(attributes)
+        @nodes = {}
+        @block = block
+
+        ## Track change status for comsumers
+        @dirty = false
+      end
+
+      ## Clear dirty state flag
+      def clean
+        @dirty = false
+      end
+
+      def compile
+        instance_eval(&@block) if @block
+        self
+      end
+
+      def merge(other)
+        attributes.merge!(other.attributes)
+        self
+      end
+      alias_method :includes, :merge
+
+      def to_json(*_)
+        JSON.pretty_generate(to_hash)
+      end
+
+      protected
+
+      def set_if_valid(key, arg, options = {})
+        ## TODO: define validation interface
+
+        ## Mutation helpers
+
+        # Input is a path relative to the working directory
+        arg = Util.relative_path(arg).to_s if options[:relative]
+
+        # Input is a path relative to the workspace
+        arg = Util.workspace(arg).to_s if options[:workspace]
+
+        ## Unchanged
+        return if @attributes[key] == arg
+
+        @dirty = true ## A mutation has occured
+        @attributes[key] = arg
+      end
+
+      def append_if_valid(key, arg, default = Array, **options)
+        ## TODO: define validation interface
+
+        attribute = set_or_return(key, nil, default, options)
+        arg.reject! { |item| attribute.include?(item) }
+
+        return if arg.empty?
+
+        @dirty = true ## A mutation has occured
+        attribute.push(*arg)
+      end
+
+      def set_or_return(key, arg = nil, default = nil, **options)
+        if arg.nil? || (arg.is_a?(Array) && arg.empty?)
+          return @attributes[key] if @attributes.has?(key)
+
+          ## Default
+          return if default.is_a?(NilClass) ## No default
+
+          ## Allow a default to be a static value, or instantiated
+          ## at call-time from a class (e.g. Array or Hash)
+          default_value = default.is_a?(Class) ? default.new : default
+          return default_value if @attributes.sealed
+
+          return set_if_valid(key, default_value, options)
+        end
+
+        ## Set value
+        set_if_valid(key, arg, options)
+      end
+
+      ##
+      # Define a namespace for attributes
+      ##
+      class Namespace < Attributes
+        class << self
+          attr_accessor :name
+
+          ##
+          # Construct a new child-class to define the interface. The constructor
+          # accepts an attributes argument, which should be a sub-node of the root
+          # attribute-set.
+          ##
+          def create(namespace_name, &definition)
+            space = Class.new(self)
+            space.name = namespace_name
+
+            ## Define DSL interface
+            space.instance_eval(&definition) if definition
+
+            space
+          end
+        end
+
+        attr_reader :name
+        attr_reader :collection
+
+        def initialize(attributes, options = {}, &block)
+          super(attributes, &block)
+
+          @name = options.fetch(:name, self.class.name)
+          @collection = options[:collection]
+        end
+
+        def compile
+          @block.call(self) if @block
+          self
+        end
+      end
+
+      ##
+      # Enumerable wrapper for collections
+      ##
+      class Collection < Attributes
+        class << self
+          attr_accessor :name
+          attr_accessor :namespace_class
+
+          def create(collection_name, &definition)
+            collection = Class.new(self)
+            collection.name = collection_name
+            collection.namespace_class = Namespace.create(collection_name, &definition)
+
+            collection
+          end
+        end
+
+        ## Allow a single instance to be selected
+        attr_reader :current
+        def use(instance_name)
+          @current = fetch(instance_name)
+        end
+
+        ## Enumerable methods return namespace instances
+        def each(&block)
+          attributes.each_key do |instance_name|
+            block.call(instance_name, fetch(instance_name))
+          end
+        end
+
+        def name
+          self.class.name
+        end
+
+        ## Get namespace instances
+        def fetch(instance_name, &block)
+          self.class.namespace_class.new(
+            attributes[instance_name],
+            :collection => self,
+            :name => instance_name, &block)
+        end
+        alias_method :[], :fetch
+      end
+    end
+  end
+end