tefoji 1.0.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 26059a47709ee9c7a4c33054c4da05d66b43e77cd3042497ffa7f7f48ccc2831
+  data.tar.gz: fe60fc5a310f2147e07c050483bb4a86665ef697396afbf8027ada79a7f25e48
+SHA512:
+  metadata.gz: 29eb974c65570687064562c4ca3a6acf1b5fdefe3a75a913003fe3ee6bbf930f0bac749821705817e7d6fd8e4e00b51fdc81d937d4ddd62fe5038b291aeef22d
+  data.tar.gz: f115c57f3ba7c00ee7ae24f581d544da201964cb5a896080f4b2d92f132d0522a350cf340ab43a33eebf4933f3f6f087129f4d88bd4983f6cfc5ca1e84a80935

data/exe/tefoji

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'tefoji'
+
+Tefoji::CLI.new(ARGV).run

data/lib/mixins/logging.rb

@@ -0,0 +1,9 @@
+# Handles all logging output for Tefoji
+module Logging
+  # Another cheap hack to wrap 'logger' above. Called as 'fatal' rather than 'logger.fatal'
+  # directly, does the exit for us so we can be lazy.
+  def fatal(message)
+    logger.fatal(message)
+    exit 1
+  end
+end

data/lib/mixins/user_functions.rb

@@ -0,0 +1,319 @@
+module UserFunctions
+  ##
+  ## These are functions defined to be called from within the yaml files, thus the funny
+  ## calling signatures. The functions are called with a simple array of arguments.
+  ## It is up to the function to unwind those arguments.
+  ##
+  ## It is essential that the user functions remain as spare as possible. Pure functions
+  ## are best, but 'prompt' violates that already.
+  ##
+
+  # A bit of paranoia that lists the allowable function names so that arbitrary
+  # function calls aren't permitted from the YAML files.
+  def user_function_allowlist
+    %w[
+      chooser
+      conditional
+      date_after
+      date_before
+      default
+      jira_project
+      jira_sprint
+      jira_status
+      jira_team
+      jira_user
+      n_digit_version
+      prompt
+      prompt_only
+      random
+      release_type
+      split
+    ]
+  end
+
+  # Maps of Winston-style Jira names (projects, sprints, to the actual assets
+  def jira_projects
+    {
+      BOLT: 'BOLT',
+      BUILD_TOOLS: 'BUILD',
+      CLIENT_TOOLS: 'CT',
+      CODE_MANAGEMENT: 'CODEMGMT',
+      COMMUNITY_PACKAGE_REPO: 'CPR',
+      DOC: 'DOC',
+      DOCS: 'DOC',
+      EZBAKE: 'EZ',
+      FACTER: 'FACT',
+      FORGE_INTERNAL: 'PF',
+      IMAGES: 'IMAGES',
+      MODULES: 'MODULES',
+      MODULES_INTERNAL: 'FM',
+      OPERATIONS: 'OPS',
+      PDK: 'PDK',
+      PE_INTERNAL: 'PE',
+      PROJECT_CENTRAL: 'PC',
+      PUPPETDB: 'PDB',
+      PUPPETSERVER: 'SERVER',
+      PUPPET_AGENT: 'PA',
+      PUPPET: 'PUP',
+      QUALITY_ENGINEERING: 'QENG',
+      DIO: 'DIO',
+      RAZOR: 'RAZOR',
+      RELEASE_ENGINEERING: 'RE',
+      SLV: 'SLV',
+      SUPPORT: 'SUP',
+      VANAGON: 'VANAGON',
+      WEB: 'WWM',
+      WHO: 'WHO'
+    }
+  end
+
+  def jira_sprints
+    {
+      RE_KANBAN: 3150,
+      DUMPLING_READY_TO_WORK: 5515
+    }
+  end
+
+  def jira_statuses
+    {
+      READY_FOR_ENGINEERING: 111,
+      ACCEPTED: 271,
+      DEVELOPING_FEATURE: 61,
+      DEVELOPING_EPIC: 41
+    }
+  end
+
+  def jira_teams
+    {
+      BOLT: 'Bolt',
+      CD4PE: 'CD4PE',
+      CODE_MANAGEMENT: 'Dumpling',
+      DUMPLING: 'Dumpling',
+      FACTER: "Phoenix",
+      INSTALLER: 'Installer and Management',
+      NETWORKING: 'Network Automation',
+      OPERATIONS: 'Operations',
+      PE: 'Dumpling',
+      PLATFORM_OS: "Phoenix",
+      PUPPETDB: 'Dumpling',
+      PUPPETSERVER: 'Dumpling',
+      QE: 'Quality Engineering',
+      RELEASE_ENGINEERING: 'Release Engineering',
+      SKELETOR: 'Skeletor',
+      SLV: 'System Level Validation'
+    }
+  end
+
+  def jira_predeclared_variables
+    variables = {}
+
+    projects = jira_projects.transform_keys { |k| "#{k.downcase}_project".to_sym }
+    sprints = jira_sprints.transform_keys { |k| "#{k.downcase}_sprint".to_sym }
+    statuses = jira_statuses.transform_keys { |k| "#{k.downcase}_status".to_sym }
+    teams = jira_teams.transform_keys { |k| "#{k.downcase}_team".to_sym }
+
+    variables.merge(**projects, **sprints, **statuses, **teams)
+  end
+
+  # Takes at least two arguments.
+  # The first is a string to match against.
+  # The remainders are single key -> value hashes. If the string matches the key, the value
+  # is returned.
+  #
+  # Returns '' if nothing matches.
+  def chooser(args)
+    _fail_if_unset(__method__.to_s, args)
+    match_string = args[0]
+    args[1..].each do |match_case|
+      return match_case[match_string] if match_case.key? match_string
+    end
+    return ''
+  end
+
+  # Takes three arguments. If the first is truthy, return the 2nd. Else return the 3rd
+  def conditional(args)
+    case args[0]
+    when nil, '', false, 'false'
+      args[2]
+    else
+      args[1]
+    end
+  end
+
+  # Date `number_of_days` after `date_string`
+  def date_after(args)
+    _fail_if_unset(__method__.to_s, args)
+    date_string = args[0]
+    number_of_days = args[1].to_i
+
+    date = _date_string_to_date(date_string)
+    _date_to_date_string(date + number_of_days)
+  end
+
+  # Date `number_of_days` before `date_string`
+  def date_before(args)
+    _fail_if_unset(__method__.to_s, args)
+    date_string = args[0]
+    number_of_days = args[1].to_i
+
+    date = _date_string_to_date(date_string)
+    _date_to_date_string(date - number_of_days)
+  end
+
+  # From the argument list, returns the first that isn't empty or unset
+  # Return an empty string if none are.
+  def default(args)
+    args.each do |a|
+      next if a.nil?
+
+      return a
+    end
+    return ''
+  end
+
+  def jira_project(args)
+    _jira_key('project', jira_projects, args[0])
+  end
+
+  def jira_sprint(args)
+    _jira_key('sprint', jira_sprints, args[0])
+  end
+
+  def jira_status(args)
+    _jira_key('status', jira_statuses, args[0])
+  end
+
+  def jira_team(args)
+    _jira_key('team', jira_teams, args[0])
+  end
+
+  # Return the first n fields of '.' - delimited version string
+  def n_digit_version(args)
+    _fail_if_unset(__method__.to_s, args)
+
+    n = args[0].to_i - 1
+    version = args[1]
+    version.split('.')[0..n].join('.')
+  end
+
+  # Prompt if the value isn't defined or in the environment
+  # Arguments:
+  #  0: The name of the user variable to prompt for
+  # Returns:
+  #  The first found
+  #    value of declared variable
+  #    value from the shell environment
+  #    the string the user types at the prompt
+  def prompt(args)
+    if args.nil?
+      fatal 'function "prompt_only" requires variable name.'
+    end
+    _fail_if_unset(__method__.to_s, args)
+
+    variable_name = args[0]
+    variable_symbol = variable_name.to_sym
+
+    return @declarations[variable_symbol] if @declarations.key?(variable_symbol)
+    return ENV[variable_name] if ENV.key?(variable_name)
+
+    print "Enter value for \"#{variable_name}\": "
+    return $stdin.gets.chomp
+  end
+
+  # Explicitly prompt for a value
+  # Arguments:
+  #  0: The name of the user variable to prompt for
+  # Returns:
+  #  The string user types from STDIN
+  def prompt_only(args)
+    if args.nil?
+      fatal 'function "prompt_only" requires variable name.'
+    end
+    _fail_if_unset(__method__.to_s, args)
+    variable_name = args[0]
+    print "Enter value for \"#{variable_name}\": "
+    $stdin.gets.chomp
+  end
+
+  # Randomly pick from a list of strings
+  # Arguments:
+  #   *: a list of strings from which to pick
+  #
+  def random(args)
+    _fail_if_unset(__method__.to_s, args)
+    args[Random.new.rand(args.count)]
+  end
+
+  # Return a conditional value based upon a version string
+  # Arguments:
+  #   0: a semver version string.
+  #   1: a hash with keys of 'X', 'Y', or 'Z' representing the semver fields
+  #     and a value to set for that corresponding release type.
+  # For example:
+  #   0: "2.5.9"
+  #   1: {'X' => 'foo', 'Y' => 'bar', 'Z' => 'baz'}
+  # will return 'baz'
+  def release_type(args)
+    _fail_if_unset(__method__.to_s, args)
+    this_type = _string_to_xyz(args[0])
+    condition_hash = args[1]
+
+    unless condition_hash.keys.sort == %w[X Y Z].sort
+      fatal 'function "release_type" requires a hash with keys ("X", "Y", "Z") as 2nd argument. '\
+            "Got: #{condition_hash}"
+    end
+
+    return condition_hash[this_type] if condition_hash.key?(this_type)
+
+    fatal "function \"release_type\" could not find a matching case for #{args[0]}\""
+  end
+
+  # Split a string into a packed array given a regular expression to split with
+  # Arguments:
+  #  0: a regular expression for splitting, typically '\s*,\s*'
+  #  1: string to split
+  def split(args)
+    _fail_if_unset(__method__.to_s, args)
+    fatal('function "split" requires exactly two arguments') unless args.size == 2
+    args[1].split(/#{args[0]}/)
+  end
+
+  ## Jira fields helper functions
+  def _jira_key(item_name, hash, key)
+    key_symbol = key.upcase.to_sym
+    unless hash.key? key_symbol
+      fatal "Unknown #{item_name} \"#{key}\""
+    end
+    hash[key_symbol]
+  end
+
+  ## Date calculation helper functions
+
+  # Expects date_string in the format YYYY-MM-DD
+  def _date_string_to_date(date_string)
+    year, month, day = date_string.split('-').map(&:to_i)
+    Date.new(year, month, day)
+  end
+
+  def _date_to_date_string(date)
+    "#{date.year}-#{date.month}-#{date.day}"
+  end
+
+  ## Release type helper functions
+  def _string_to_xyz(version)
+    y_value = version.split('.')[1]
+    z_value = version.split('.')[2]
+    return 'Z' unless z_value == '0'
+
+    return 'Y' unless y_value == '0'
+
+    return 'X'
+  end
+
+  ## Fail on unset arguments
+  def _fail_if_unset(function_name, arguments)
+    arguments.each do |a|
+      fatal "\"#{function_name}\" called with unset variable." if a.nil?
+    end
+  end
+end

data/lib/tefoji/cli.rb

@@ -0,0 +1,113 @@
+require 'docopt'
+require 'rubygems'
+require 'uri'
+require 'yaml'
+
+module Tefoji
+  class CLI
+    DEFAULT_JIRA_URL = 'https://tickets.puppetlabs.com'
+    JIRA_TEST_URL = 'https://jira-app-dev-1.ops.puppetlabs.net'
+    DEFAULT_JIRA_AUTH_FILE = "#{ENV['HOME']}/.tefoji-auth.yaml"
+
+    DOCUMENTATION = <<~DOCOPT
+      Generate Jira issues from YAML files.
+
+      Usage:
+          tefoji [--jira=URL] [--jira-test] [--jira-auth=FILE] [--jira-save-auth] [--jira-user=USER] [--jira-mock] [--no-notes] [--version] [--quiet|--debug] <issue_template> ...
+          tefoji [--debug] [--quiet] --print-notes <issue_template> ...
+          tefoji [--debug] [--quiet] --verify-only <issue_template> ...
+          tefoji --version
+
+      Options:
+      -j --jira URL             URL of the Jira instance (defaults to #{DEFAULT_JIRA_URL})
+      -J --jira-test            Use the jira test environment (#{JIRA_TEST_URL})
+      -a --jira-auth=FILE       Alternate YAML file with Base64-encoded 'username:password' string
+                                  for Jira authentication
+      -S --jira-save-auth       Save/overwrite Base64-encoded yaml authentication to the jira-auth
+                                file (defaults to #{DEFAULT_JIRA_AUTH_FILE}) after succesfully
+                                authenticating to the Jira server.
+      -u USER --jira-user USER  User name for Jira
+      -M --jira-mock            Mock the Jira API. Useful only for development testing.
+      -n --no-notes             Do not print the template 'notes' section. This is mainly for tefoji
+                                wrappers that prefer to handle notes their own way.
+      -p --print-notes          Just print the notes for templates but do no other processing
+      -v --version              Show version
+      -q --quiet                Turn off (INFO) logging
+
+      -D --debug                Turn on debug (DEBUG) logging
+      -V --verify-only          Perform template verification and exit.
+      -h --help                 Show this help
+    DOCOPT
+
+    def initialize(argv)
+      @user_options = parse_options(argv)
+
+      if @user_options['--version']
+        warn "tefoji version #{Gem.loaded_specs['tefoji'].version.to_s}"
+        exit 0
+      end
+
+      @user_options['jira-auth-string'] = nil
+      @user_options['jira-auth-file'] = @user_options['--jira-auth'] || DEFAULT_JIRA_AUTH_FILE
+
+      jira_auth_file = @user_options['jira-auth-file']
+      if File.file?(jira_auth_file)
+        authentication = YAML.load_file(jira_auth_file)
+        if authentication.key?('jira-auth')
+          @user_options['jira-auth-string'] = authentication['jira-auth']
+        end
+      end
+
+      @user_options['--jira'] = JIRA_TEST_URL if @user_options['--jira-test']
+      @user_options['--jira'] = DEFAULT_JIRA_URL if @user_options['--jira'].nil?
+    end
+
+    # Iterate through issue templates, validating each. If that goes well, generate
+    # Jira issues from them.
+    def run
+      tefoji = Tefoji.new(@user_options)
+
+      template_uris = @user_options['<issue_template>']
+
+      # 1st pass, try to find each of the templates, verify each for syntax,
+      # keep going even if we find errors in some templates
+      error_count, templates = tefoji.yaml_syntax_check(template_uris)
+
+      # 2nd pass, scan any templates that passed syntax-check for semantic problems
+      exit 1 unless error_count.zero?
+
+      if @user_options['--verify-only']
+        warn 'tefoji: no errors found.'
+        exit 0
+      end
+
+      if @user_options['--print-notes']
+        templates.each do |template|
+          warn template[1]['notes'] if template[1].key?('notes')
+        end
+        exit 0
+      end
+
+      # Retrieve any included templates
+      templates.each do |template|
+        template[:includes] = tefoji.includes(template)
+      end
+
+      # Looks like we're good to go, authenticate to jira and do the work
+      tefoji.authenticate
+      tefoji.save_authentication if @user_options['--jira-save-auth']
+      templates.each { |template| tefoji.run(template) }
+
+      warn 'tefoji: completed sucessfully.'
+    end
+
+    private
+
+    def parse_options(argv = nil)
+      Docopt.docopt(DOCUMENTATION, { argv: argv })
+    rescue Docopt::Exit => e
+      warn e.message
+      exit 1
+    end
+  end
+end

data/lib/tefoji/declared_value.rb

@@ -0,0 +1,51 @@
+module Tefoji
+  class DeclaredValue
+    attr_accessor :value, :properties
+
+    def initialize(value = nil)
+      @value = value
+      @value = value.value if value.is_a? DeclaredValue
+      @properties = {}
+    end
+
+    def prepend(*prepended_things)
+      @value.prepend(*prepended_things)
+    end
+
+    def to_i
+      @value.to_i
+    end
+
+    def to_s
+      @value.to_s
+    end
+
+    def to_a
+      if @value.is_a? Array
+        @value
+      else
+        [@value]
+      end
+    end
+
+    def %(other)
+      @value % other
+    end
+
+    def unset?
+      @value.nil?
+    end
+
+    def falsey?
+      if @value.nil? || @value.empty? || @value.downcase == 'false' || @value == false
+        true
+      else
+        false
+      end
+    end
+
+    def truthy?
+      !falsey?
+    end
+  end
+end