jujube 0.5.0

data/lib/jujube/components/triggers.rb

@@ -0,0 +1,105 @@
+module Jujube
+  module Components
+
+    # Helper methods for creating trigger components.
+    module Triggers
+
+      # Specify a `pollscm` trigger for a job.
+      #
+      # See {http://ci.openstack.org/jenkins-job-builder/triggers.html#triggers.pollscm}.
+      #
+      # @param interval [String] The polling interval, using `cron` syntax.
+      # @return [Hash] The specification for the component.
+      def pollscm(interval)
+        {'pollscm' => interval}
+      end
+
+      # Specify a `pollurl` trigger for a job.
+      #
+      # This trigger requires support in jenkins-job-builder that has not yet been merged.
+      # See {https://review.openstack.org/#/c/83524/} for the patch.
+      #
+      # `pollurl` can poll several URLs.  Each URL specification is added
+      # in a nested configuration block using the {#url} method.
+      #
+      # @example
+      #   job "pollurl-example" do |j|
+      #     j.triggers << pollurl(cron: "CRON") do |urls|
+      #       urls << url("URL", check_date: true) do |content|
+      #         content << json("JSON_PATH1", "JSON_PATH2")
+      #       end
+      #     end
+      #   end
+      #
+      # @param options [Hash] Top-level options for configuring the component.
+      # @yieldparam urls [Array] An array to which nested URL specifications should be
+      #   added by the block.
+      # @return [Hash] The specification for the component.
+      def pollurl(options = {}, &block)
+        to_config("pollurl", nested_options(:urls, options, &block))
+      end
+
+      # @!group pollurl Helpers
+
+      # Configure a URL to poll in a {#pollurl} component.
+      #
+      # If you want to check for changes to the actual content returned from the URL,
+      # (the `check-content` setting), pass a block that configures the content-type
+      # specifications using one or more of {#simple}, {#json}, {#xml}, or {#text}.
+      #
+      # @param the_url [String] The URL to monitor.
+      # @param options [Hash] Top-level options for this URL.
+      # @yieldparam content_types [Array] An array to which nested content-type
+      #   specifications should be added by the block.
+      # @return [Hash] The specification for the URL.
+      def url(the_url, options = {}, &block)
+        options = {url: the_url}.merge!(options)
+        canonicalize_options(nested_options(:check_content, options, &block))
+      end
+
+      # @!endgroup
+
+      # @!group pollurl Content Types
+
+      # Configure a simple content check inside a {#url} specification of a
+      # {#pollurl} component.
+      # @return [Hash] The specification for the content type.
+      def simple
+        {"simple" => true}
+      end
+
+      # Configure a JSON content check inside a {#url} specification of a
+      # {#pollurl} component.
+      #
+      # @param paths [String...] Zero or more JSONPath expressions.  Only changes to
+      #   the parts of the JSON response that match one of the `paths` will trigger a build.
+      # @return [Hash] The specification for the content type.
+      def json(*paths)
+        {"json" => paths}
+      end
+
+      # Configure an XML content check inside a {#url} specification of a
+      # {#pollurl} component.
+      #
+      # @param xpaths [String...] Zero or more XPath expressions.  Only changes to
+      #   the parts of the XML response that match one of the `xpaths` will trigger a build.
+      # @return [Hash] The specification for the content type.
+      def xml(*xpaths)
+        {"xml" => xpaths}
+      end
+
+      # Configure a text content check inside a {#url} specification of a
+      # {#pollurl} component.
+      #
+      # @param regexes [String...] Zero or more regular expressions.  Only changes to
+      #   the parts of the text response that match one of the `regexes` will trigger a build.
+      # @return [Hash] The specification for the content type.
+      def text(*regexes)
+        {"text" => regexes}
+      end
+
+      # @!endgroup
+
+    end
+  end
+end

data/lib/jujube/components/wrappers.rb

@@ -0,0 +1,28 @@
+module Jujube
+  module Components
+
+    # Helper methods for creating wrapper components.
+    module Wrappers
+      extend Macros
+
+      # @!method timeout(options = {})
+      # Specify a `timeout` component for a job.
+      #
+      # See {http://ci.openstack.org/jenkins-job-builder/publishers.html#wrappers.timeout}.
+      #
+      # @param options [Hash] The configuration options for the component.
+      # @return [Hash] The specification for the component.
+      standard_component :timeout
+
+      # Specify a `timestamps` component for a job.
+      #
+      # See {http://ci.openstack.org/jenkins-job-builder/wrappers.html#wrappers.timestamps}.
+      #
+      # @return [Hash] The specification for the component.
+      def timestamps
+        'timestamps'
+      end
+
+    end
+  end
+end

data/lib/jujube/driver.rb

@@ -0,0 +1,78 @@
+require_relative "job_loader"
+require_relative "job_file_generator"
+require 'optparse'
+require 'ostruct'
+require 'pathname'
+
+module Jujube
+
+  # The command-line driver for the Jujube application.
+  class Driver
+
+    # Run the Jujube application.
+    def self.run
+      self.new.run
+    end
+
+    # Initialize the driver.
+    #
+    # @param loader [JobLoader] Loads jobs from user-specified files and/or directories.
+    # @param generator [JobFileGenerator] Generates the jenkins-job-builder YAML file from
+    #   any jobs that have been loaded.
+    def initialize(loader = JobLoader.new, generator = JobFileGenerator.new)
+      @loader = loader
+      @generator = generator
+    end
+
+    # Run the Jujube application.
+    #
+    # @param argv [Array] The command-line arguments that control the application.
+    def run(argv = ARGV)
+      argv = adjusted_for_jruby(argv)
+      options = handle_options(argv)
+      jobs = @loader.load_jobs(*options.paths || Pathname.getwd)
+      @generator.generate(jobs, options.output || Pathname.new("jobs.yml"))
+    end
+
+    private
+
+    # Parse the command-line options.
+    #
+    # @param argv [Array] The command-line options.
+    # @return [OpenStruct] The options specified on the command-line.  May include
+    #   `paths`, a list of `Pathname`s to load and `output`, the `Pathname` of the
+    #   output file to generate.
+    def handle_options(argv)
+      options = OpenStruct.new
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: #{$PROGRAM_NAME} [options] paths..."
+
+        opts.on('-o', '--output FILENAME', 'Specify output file (default = "jobs.yml")') do |file|
+          options.output = Pathname.new(file)
+        end
+
+        opts.on('-h', '--help', "Display this screen") do
+          puts opts
+          exit
+        end
+      end.parse!(argv)
+
+      options.paths = argv.map { |file| Pathname.new(file) } unless argv.empty?
+
+      options
+    end
+
+    # Adjust the command-line arguments for running acceptance tests under JRuby.
+    #
+    # When running the acceptance tests under JRuby, an extra '{}' argument
+    # is passed in ARGV.  We remove it here so that it doesn't affect the
+    # rest of the program logic.
+    #
+    # See {https://github.com/jruby/jruby/issues/1290}.
+    def adjusted_for_jruby(argv)
+      argv.pop if argv.last == "{}"
+      argv
+    end
+  end
+end

data/lib/jujube/dsl.rb

@@ -0,0 +1,43 @@
+module Jujube
+  # The top-level DSL to be used when defining jobs.
+  module DSL
+    include Jujube::Components
+
+    # Define a new Jenkins job.
+    #
+    # Takes a configuration block that is used to configure the job by
+    # setting attribute values and adding components to the various sections
+    # of the job.
+    #
+    # @example
+    #   job "my-job" do |j|
+    #     j.description = "This is my job."  # Specify attributes
+    #     j.quiet_period = 5
+    #
+    #     j.axes << slave(:arch, %w{i386 amd64}) # Add components to sections
+    #
+    #     j.scm << git(url: "https://example.com/git/my-project", branches: %w{master dev})
+    #
+    #     j.triggers << pollscm("@hourly")
+    #
+    #     j.wrappers << timeout(type: 'elastic', elastic_percentage: 150, elastic_default_timeout: 5, fail: true)
+    #     j.wrappers << timestamps
+    #
+    #     j.builders << shell("bundle && bundle exec rake deploy")
+    #
+    #     j.publishers << email_ext(recipients: %w{me@example.com you@example.com})
+    #   end
+    #
+    # @param name [String] The name of the job as will be shown by Jenkins.
+    # @yieldparam job [Job] The job being created.
+    def job(name, &block)
+      Job.new(name, &block)
+    end
+
+  end
+end
+
+# Extend the main object with the DSL commands.  This allows top-level
+# calls to the DSL functions to work from a job file without polluting
+# the object inheritance tree.
+self.extend Jujube::DSL

data/lib/jujube/job.rb

@@ -0,0 +1,226 @@
+require_relative "macros"
+require 'yaml'
+
+module Jujube
+  # Models a single Jenkins job.
+  class Job
+    extend Macros
+
+    # Initialize the job.
+    #
+    # Takes a configuration block for adding atributes and sections to the job.
+    # The configuration block is passed the new `Job` as a parameter.
+    #
+    # @param job_name [String] The name of the job.  Will be the name as seen in Jenkins.
+    # @yieldparam self [Job] Passes itself to the configuration block.
+    def initialize(job_name)
+      @config = {}
+      self.name = job_name
+
+      yield(self) if block_given?
+
+      self.class.register(self)
+    end
+
+    # @!group Attributes
+
+    # @!attribute name
+    #   The name of the job - will be the name as seen in Jenkins.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/general.html}.
+    #
+    #   @return [String]
+    attribute :name
+
+    # @!attribute project_type
+    #   The type of job. This normally does not need to be specified, as it
+    #   will be inferred as `matrix` if any `axes` are added.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/general.html}.
+    #
+    #   @return [String]
+    attribute :project_type
+
+    # @!attribute description
+    #   The description of the job.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/general.html}.
+    #
+    #   @return [String]
+    attribute :description
+
+    # @!attribute node
+    #   The Jenkins node or named group where the job should be run.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/general.html}.
+    #
+    #   @return [String]
+    attribute :node
+
+    # @!attribute block_upstream
+    #   `true` if this job should block while upstream jobs are running.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/general.html}.
+    #
+    #   @return [Boolean]
+    attribute :block_upstream
+
+    # @!attribute block_downstream
+    #   `true` if this job should block while downstream jobs are running.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/general.html}.
+    #
+    #   @return [Booelan]
+    attribute :block_downstream
+
+    # @!attribute quiet_period
+    #   Number of seconds to wait between consecutive runs of the job.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/general.html}.
+    #
+    #   @return [Fixnum]
+    attribute :quiet_period
+
+    # @!endgroup
+
+    # @!group Sections
+
+    # @!method axes
+    #   The matrix axes for the job.
+    #
+    #   Add axes in the job's configuration block using helper methods defined in
+    #   {Components::Parameters}.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/project_matrix.html}.
+    #
+    #   @return [Array]
+    section :axes
+
+    # @!method scm
+    #   The SCMs for the job.
+    #
+    #   Add SCMs in the job's configuration block using helper methods defined in
+    #   {Components::Scm}.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/scm.html}.
+    #
+    #   @return [Array]
+    section :scm
+
+    # @!method triggers
+    #   The triggers for the job.
+    #
+    #   Add triggers in the job's configuration block using helper methods defined in
+    #   {Components::Triggers}.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/triggers.html}.
+    #
+    #   @return [Array]
+    section :triggers
+
+    # @!method wrappers
+    #   The wrappers for the job.
+    #
+    #   Add wrappers in the job's configuration block using helper methods defined in
+    #   {Components::Wrappers}.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/wrappers.html}.
+    #
+    #   @return [Array]
+    section :wrappers
+
+    # @!method builders
+    #   The builders for the job.
+    #
+    #   Add builders in the job's configuration block using helper methods defined in
+    #   {Components::Builders}.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/builders.html}.
+    #
+    #   @return [Array]
+    section :builders
+
+    # @!method publishers
+    #   The publishers for the job.
+    #
+    #   Add publishers in the job's configuration block using helper methods defined in
+    #   {Components::Publishers}.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/publishers.html}.
+    #
+    #   @return [Array]
+    section :publishers
+
+    # @!method notifications
+    #   The notifications for the job.
+    #
+    #   Add notifications in the job's configuration block using helper methods defined in
+    #   {Components::Notifications}.
+    #
+    #   See {http://ci.openstack.org/jenkins-job-builder/notifications.html}.
+    #
+    #   @return [Array]
+    section :notifications
+
+    # @!endgroup
+
+    # Generate a YAML representation of the `Job`.
+    def to_yaml(*args)
+      to_h.to_yaml(*args)
+    end
+
+    # Generate a `Hash` repsentation of the `Job`.
+    def to_h
+      infer_project_type
+      {'job' => config}
+    end
+
+    # Keep track of all `Job`s defined during the execution of the passed block.
+    #
+    # This is used during job loading so that no extra syntax is required in the job
+    # definition files for registering jobs and so that it is possible to create jobs
+    # for testing purposes without having them registered anywhere.
+    #
+    # @return [Array<Job>] Returns a list of all `Job`s defined within the block.
+    def self.all_defined_during
+      @registry = []
+      yield
+      @registry
+    ensure
+      @registry = []
+    end
+
+    # Register a `Job` in a registry.
+    #
+    # If no registry is active, this is a no-op.
+    #
+    # @param job [Job] The job to register.
+    def self.register(job)
+      @registry << job if @registry
+    end
+
+    # The job configuration.
+    #
+    # All configuration is stored internally as a `Hash` with `String` keys in
+    # canonical jenkins-job-builder format.  This format can readily be converted
+    # to the YAML needed by jenkins-job-builder.
+    attr_reader :config
+    private :config
+
+    private
+
+    # Set the {#project_type} to `matrix` if any `axes` have been specified.
+    def infer_project_type
+      self.project_type = "matrix" if has_axes?
+    end
+
+    # Have any `axes` been specified?
+    #
+    # Take care to not lazily-initialize an `"axes"` key when checking.
+    #
+    # @return [Boolean] `true` if any `axes` have been defined; `false` otherwise.
+    def has_axes?
+      config.has_key?("axes") && !axes.empty?
+    end
+  end
+end