tefoji 1.0.7

data/lib/tefoji.rb

@@ -0,0 +1,830 @@
+require 'date'
+require 'digest'
+require 'fileutils'
+require 'net/http'
+require 'json'
+
+require 'mixins/logging'
+require 'mixins/user_functions'
+
+require 'tefoji/cli'
+require 'tefoji/declared_value'
+require 'tefoji/jira_api'
+
+module Tefoji
+  class Tefoji
+    # Class for the main Tefoji class responsible for driving the issue creation.
+
+    include Logging
+    include UserFunctions
+
+    # @param [Hash] user_options options provided by the user through the CLI.
+    # @see CLI
+    def initialize(user_options = {}, log_location = $stderr)
+      @log_level = Logger::ERROR
+      @jira_api = nil
+      @jira_url = user_options['--jira']
+      @jira_user = user_options['--jira-user']
+      @jira_auth_string = user_options['jira-auth-string']
+      @jira_auth_file = user_options['jira-auth-file']
+      @jira_mock = user_options['--jira-mock']
+
+      @no_notes = user_options['--no-notes']
+      @template_data = {}
+
+      # For display purposes only. For displaying a tidy issue count as they
+      # are generated.
+      @issue_counter = 1
+
+      # Changable internal states
+      @feature_issue = nil
+      @default_target_epic = nil
+      @epic_security = nil
+
+      # Logging
+      @log_level = Logger::INFO
+      @log_level = Logger::WARN if user_options['--quiet']
+      @log_level = Logger::DEBUG if user_options['--debug']
+
+      @logger = logger_initialize(log_location)
+    end
+
+    # Main method for generating issues from template_data
+    # @param main_template [Hash]
+    #   uri: URI of the template
+    #   data: parsed template data
+    # @return [Hash] details of all the generated issues
+    def run(main_template)
+      main_template_data = main_template[:data]
+
+      # Print any notes.
+      if main_template_data.key?('notes') && !@no_notes
+        puts main_template_data['notes']
+      end
+
+      # Separate out any formats.
+      @formats = {}
+      @formats = main_template_data['formats'] if main_template_data['formats']
+
+      @declarations = Hash.new(DeclaredValue.new)
+      jira_predeclared_variables.each do |k, v|
+        @declarations[k] = DeclaredValue.new(v)
+      end
+
+      resolve_variables(main_template_data['declare'])
+      @logger.debug "Declarations: #{@declarations}"
+
+      # Process 'before' templates
+      main_template.dig(:includes, :before)&.each do |before|
+        default_epic_saved = @default_target_epic
+        @formats = before.dig(:data, 'formats') if before.dig(:data, 'formats')
+        process_template(before[:template_name], before[:data], before[:conditional])
+        @default_target_epic = default_epic_saved
+      end
+
+      # Process main template
+      main_template_name = File.basename(main_template[:uri], File.extname(main_template[:uri]))
+      @formats = main_template_data['formats'] if main_template_data['formats']
+      process_template(main_template_name, main_template_data)
+
+      # Process 'after' templates
+      main_template.dig(:includes, :after)&.each do |after|
+        default_epic_saved = @default_target_epic
+        @formats = after.dig(:data, 'formats') if after.dig(:data, 'formats')
+        process_template(after[:template_name], after[:data], after[:conditional])
+        @default_target_epic = default_epic_saved
+      end
+    end
+
+    def process_template(template_name, template_data, conditional = 'true')
+      unless template_data
+        @logger.info "Template \"#{template_name}\" has no tefoji data. Skipping."
+        return
+      end
+
+      if expand_right_value(conditional).falsey?
+        @logger.info "Not processing \"#{template_name}\"; template conditional evaluates to 'false'"
+        return
+      end
+
+      @logger.info "- Processing \"#{template_name}\" template"
+      @template_data = template_data
+
+      if @template_data.key?('feature')
+        generate_feature_with_issues
+      elsif @template_data.key?('epics')
+        generate_epics_with_issues('epics')
+      elsif @template_data.key?('epic')
+        generate_epics_with_issues('epic')
+      elsif @template_data.key?('issues')
+        generate_ordinary_issues
+      else
+        fatal 'Internal error finding keywords in issue template'
+      end
+    end
+
+    # @return [Array]
+    #  0: Number of errors found
+    #  1: Array of hashes [uri:, loaded-data:] of succesfully parsed templates
+    def yaml_syntax_check(template_uris)
+      errors = 0
+      checked_templates = []
+      template_uris.each do |template_uri|
+        @logger.debug "YAML syntax-check: #{template_uri}"
+        raw_yaml = if template_uri.start_with?('http://', 'https://')
+                     get_remote_yaml(template_uri)
+                   else
+                     File.open(template_uri)
+                   end
+        checked_templates << {
+          uri: template_uri,
+          data: YAML.safe_load(raw_yaml, filename: template_uri)
+        }
+      rescue Psych::SyntaxError, Errno::ENOENT => e
+        @logger.error e.message
+        errors += 1
+      end
+
+      return [errors, checked_templates]
+    end
+
+    def get_remote_yaml(issue_template_uri)
+      response = Net::HTTP.get_response(URI.parse(issue_template_uri))
+      case response
+      when Net::HTTPSuccess
+        return response.body
+      when Net::HTTPServerError
+        warn 'tefoji: Error Remote server not responding.'
+        exit 1
+      else
+        warn "tefoji: Error #{issue_template_uri}:  #{response.message}"
+        exit 1
+      end
+    end
+
+    # @return [Hash]
+    #  before: [Array] of Hashes [template_name:, conditional:, loaded-data] templates
+    #    to be included before
+    #  after: [Array] of Hashes [template_name:, conditional:, loaded-data] templates
+    #    to be included after
+    def includes(template)
+      before = {}
+      after = {}
+
+      before_section = template[:data].dig('includes', 'before')
+      after_section = template[:data].dig('includes', 'after')
+
+      if before_section
+        @logger.debug 'Found .includes.before, processing'
+        before = find_includes(template[:uri], before_section)
+      end
+
+      if after_section
+        @logger.debug 'Found .includes.after, processing'
+        after = find_includes(template[:uri], after_section)
+      end
+
+      return { before: before, after: after }
+    end
+
+    def find_includes(main_template_path, items_to_include)
+      template_directory = File.dirname(main_template_path)
+
+      # Included files can be just a template name 'foo' or a uri 'https://foo.com/bar.yaml'
+      # Consider the four cases:
+      #   1. main_template_path is URI, included template is a template name
+      #   2. main_template_path is URI, included template is a URI
+      #   3. main_template_path is local file, included template is template name
+      #   4. main_template_path is local file, included template is a URI
+
+      # Also, template_directory can be an ordinary local directory or an URL directory
+
+      items_to_include.map do |include|
+        unless include['template']
+          fatal "Include request \"#{include}\" is missing \"template\" field"
+        end
+        template_file_name = include['template']
+        template_file_name += '.yaml' unless template_file_name.end_with?('.yaml')
+
+        conditional = true
+        conditional = include['conditional'] if include.key?('conditional')
+
+        include_epics = false
+        include_epics = include['include_epics'] if include.key?('include_epics')
+
+        presumed_path = File.join(template_directory, template_file_name)
+        included_template_path = nil
+
+        if template_file_name.start_with?('http://', 'https://') || File.exist?(template_file_name)
+          # Provided URL or full viable directory path
+          included_template_path = template_file_name
+        elsif presumed_path.start_with?('http://', 'https://') || File.exist?(presumed_path)
+          # Constructed path from main template directory name
+          included_template_path = presumed_path
+        end
+
+        fatal "Cannot locate template: \"#{template_file_name}\"" if included_template_path.nil?
+
+        raw_yaml = if included_template_path.start_with?('http://', 'https://')
+                     get_remote_yaml(included_template_path)
+                   else
+                     File.open(included_template_path)
+                   end
+
+        yaml_data = YAML.safe_load(raw_yaml, filename: included_template_path)
+
+        # In included templates, we don't include features.
+        yaml_data.delete('feature')
+
+        # In included templates, we don't include epics unless they are specifically kept.
+        unless include_epics
+          yaml_data.delete('epics')
+          yaml_data.delete('epic')
+        end
+
+        @logger.debug "conditional: #{conditional}; yaml_data: #{yaml_data}"
+        { template_name: include['template'], conditional: conditional, data: yaml_data }
+      end
+    end
+
+    # Do a quick check of the templates to avoid getting too far along with
+    # detectable errors.
+    # @param [Array] templates An array of pairs of template URIs and parsed YAML data
+    # @return [Boolean] true if valid
+    def valid_templates?(templates)
+      errors = false
+
+      templates.each do |uri, template|
+        @logger.debug "Checking #{uri} for basic validity"
+        result = template_errors?(uri, template)
+        errors ||= result
+      end
+
+      return !errors
+    end
+
+    # Authenticate to the Jira instance
+    def authenticate
+      @jira_api = @jira_mock ? JiraMockApi.new : JiraApi.new
+      @jira_api.log_level = @log_level
+      @jira_api.logger = @logger
+
+      @jira_api.authenticate(@jira_url, @jira_user, @jira_auth_string)
+      @jira_api.test_authentication unless @jira_mock
+    end
+
+    # Save Jira auth data
+    def save_authentication
+      authenticate unless @jira_api
+      @jira_api.save_authentication(@jira_auth_file)
+    end
+
+    private
+
+    # Generate a feature, a list of epics, and associated issues
+    def generate_feature_with_issues
+      @feature_issue = generate_feature
+      generate_epics('epics').each do |epic|
+        @default_target_epic = epic
+        generate_ordinary_issues
+      end
+    end
+
+    # Generate a 'feature' issue
+    def generate_feature
+      feature_to_do = @template_data['feature']
+
+      feature = variable_substitute(feature_to_do)
+      feature['type'] = JiraApi::ISSUE_FEATURE
+      @feature_issue = @jira_api.create_issue(feature)
+      @logger.info "Feature issue: #{@feature_issue['key']}"
+      @feature_issue
+    end
+
+    def generate_epics_with_issues(epic_key)
+      epics = generate_epics(epic_key)
+      epics.each do |epic|
+        @default_target_epic = epic
+        generate_ordinary_issues
+      end
+    end
+
+    # @return [Array] an array of responses from Jira containing a hash of the epic fields.
+    def generate_epics(epic_key)
+      epic_to_do_list = [@template_data[epic_key]].flatten
+      @logger.debug "Generating data: #{@template_data}"
+
+      epic_to_do_list.map do |epic|
+        @epic_security = nil
+        epic = variable_substitute(epic)
+
+        # Check for a 'conditional' tag in the data, skip issue generation if falsey
+        if conflicting_conditionals?(epic)
+          fatal "Epic \"#{short_name}\" has conflicting conditionals."
+        end
+        if skip_issue?(epic)
+          @logger.info 'Epic: %16s [%s]' % ['(SKIPPED)', epic['summary']]
+          next
+        end
+        short_name = epic['short_name'] || epic['summary']
+        unset_variables = list_unset_variables(epic)
+        unless unset_variables.empty?
+          fatal "Epic \"#{short_name}\" has unset variables in these fields: " +
+                unset_variables.join(', ')
+        end
+
+        epic['type'] = JiraApi::ISSUE_EPIC
+        if private_release?(epic)
+          @epic_security = 'internal'
+
+          private_description = ''
+          private_repos = epic['private_release'].value['repos']
+
+          if private_repos
+            private_description << private_release_note
+            private_description << private_repos.value.map do |repo|
+              repo.map { |k, v| "* #{k.upcase}: #{v.value}" }
+            end.join("\n")
+            private_description << "\n\n"
+          end
+
+          private_leads = epic['private_release'].value['leads']
+          if private_leads
+            leads = private_leads.value.map { |lead| "[~#{lead}]" }.join(' ')
+            private_description << "/cc #{leads} \n\n"
+          end
+
+          epic['description'].prepend(private_description)
+          epic['security'] = 'internal'
+        end
+
+        epic_issue = @jira_api.create_issue(epic)
+        epic_issue['short_name'] = short_name
+        @logger.info 'Epic: %16s [%s]' % [epic_issue['key'], short_name]
+        @jira_api.link_issues(@feature_issue['key'], epic_issue['key']) if @feature_issue
+        epic_issue
+      end
+    end
+
+    def private_release?(template)
+      if template['private_release']
+        template['private_release'].value['conditional'].truthy?
+      else
+        false
+      end
+    end
+
+    def private_release_note
+      "NOTE: THIS IS A PRIVATE RELEASE. WORK WAS DONE IN THESE PRIVATE REPOS:\n"
+    end
+
+    # Iterate through all issues in the template, creating each one in Jira.
+    # Link the issues back to their epic, if required
+    def generate_ordinary_issues
+      # Need to keep a map of tefoji data and associated responses from Jira to perform
+      # deferred updates, like blocked_by or watchers
+      deferral_data = {}
+
+      issue_defaults = {}
+      if @template_data.key?('issue_defaults')
+        issue_defaults = variable_substitute(@template_data['issue_defaults'])
+      end
+
+      if @default_target_epic
+        @logger.info "- Creating issues for \"#{@default_target_epic['short_name']}\" epic"
+      end
+
+      @template_data['issues'].each do |issue|
+        jira_ready_data, raw_issue_data = prepare_jira_ready_data(issue, issue_defaults)
+        next if jira_ready_data.nil? || raw_issue_data.nil?
+
+        response_data = @jira_api.create_issue(jira_ready_data)
+        jira_issue = @jira_api.retrieve_issue(response_data['self'])
+        jira_issue['short_name'] = raw_issue_data['short_name']
+
+        @logger.info 'Issue %4d: %10s [%s]' % [
+                      @issue_counter,
+                      jira_issue['key'],
+                      jira_issue['fields']['summary']
+                    ]
+        @issue_counter += 1
+
+        @jira_api.add_issue_to_epic(@default_target_epic, jira_issue) if @default_target_epic
+
+        # deferral_data is kept to match the jira raw request data to the jira response data.
+        # This is needed so that deferred actions (like 'blocked_by') can be correctly mapped.
+        deferral_data[raw_issue_data['short_name'].to_s] = {
+          'jira' => jira_issue,
+          'raw' => raw_issue_data
+        }
+      end
+      process_deferred_updates(deferral_data)
+    end
+
+    # Transform the tefoji issue data and tefoji issue_defaults into a hash that is ready to
+    # send to Jira:
+    #
+    #  Perform variable substition
+    #  Calculate conditionals
+    #  Extract and save deferrals
+    #  Apply summary and description formats
+    #  Make any security settings
+    #
+    # Return the fully prepared Jira hash as well as the 'raw' variable-substituted one;
+    # The latter will be needed when processing deferrals.
+    def prepare_jira_ready_data(issue, issue_defaults)
+      raw_issue_data = variable_substitute(issue_defaults.merge(issue), except: %w[summary_format])
+      error_name = raw_issue_data['short_name']
+
+      # If the user didn't provide a short_name, make one with a hexdigest.
+      # However, errors should have a more recognizable tag. So, let's use the summary.
+      unless raw_issue_data.key?('short_name')
+        error_name = raw_issue_data['summary']
+        # Used as an id for each of the issues. If the user does not provide one,
+        # make one up with hexdigest
+        raw_issue_data['short_name'] = DeclaredValue.new(
+          Digest::MD5.hexdigest(raw_issue_data['summary'].value)
+        )
+      end
+
+      # For multi-epic templates, skip this issue if it is not part of this epic
+      if raw_issue_data.key?('epic_link') &&
+         raw_issue_data['epic_link'].value != @default_target_epic['short_name'].value
+        @logger.debug 'Issue %s "%s" does not have "%s" as epic_link, skipping' % [
+                       raw_issue_data['short_name'].value,
+                       raw_issue_data['epic_link'].value,
+                       @default_target_epic['short_name'].value
+                     ]
+        return nil
+      end
+
+      return nil if raw_issue_data.key?('epic_link') &&
+                    raw_issue_data['epic_link'].value != @default_target_epic['short_name'].value
+
+      if conflicting_conditionals?(raw_issue_data)
+        fatal "Issue \"#{error_name}\" has conflicting conditionals."
+      end
+
+      # Check for a 'conditional' tag in the data, skip issue generation if falsey
+      if skip_issue?(raw_issue_data)
+        @logger.info 'Issue %14s [%s]' % ['(SKIPPED)', raw_issue_data['summary']]
+        return nil
+      end
+
+      # If 'unless' condition is still unset, it is false.
+      if raw_issue_data.key?('unless') && raw_issue_data['unless'].unset?
+        raw_issue_data['unless'] = DeclaredValue.new(false)
+      end
+
+      @logger.debug "raw_issue_data == #{raw_issue_data}"
+
+      unset_variables = list_unset_variables(raw_issue_data)
+      unless unset_variables.empty?
+        fatal "\"#{error_name}\" has unset variables in these fields: " +
+              unset_variables.join(', ')
+      end
+
+      # raw_issue_data can include some keys that we don't want to use during the
+      # issue creation (like 'blocked_by'). We'll defer these until after
+      # all the issues have been created.
+      jira_ready_data = raw_issue_data.reject { |key, _| deferred_tags.include?(key) }
+
+      # Use summary_format and description_format, should they exist, to create
+      # summary and description fields
+      jira_ready_data['summary'] = special_format(raw_issue_data, 'summary')
+      jira_ready_data['description'] = special_format(raw_issue_data, 'description')
+
+      # If the epic has set the 'security' field, set it here too.
+      jira_ready_data['security'] = @epic_security unless @epic_security.nil?
+
+      @logger.debug "jira_ready_data: #{jira_ready_data}"
+
+      return jira_ready_data, raw_issue_data
+    end
+
+    # Apply a defined format. If no format is defined, just return back the original string.
+    # Also, we sneak in allowing 'short_name' as issue-local variable in formats.
+    def special_format(raw_issue_data, field)
+      format_key = "#{field}_format"
+
+      # Return the unformatted version unless we've defined a format AND are using it here.
+      unless @formats.key?(raw_issue_data[format_key]&.value) && raw_issue_data.key?(format_key)
+        return raw_issue_data[field]
+      end
+
+      format = @formats[raw_issue_data[format_key].value] || raw_issue_data[format_key].value
+
+      # Special-case the 'summary', 'description', and 'short_name' expansions
+      formatted = format.gsub('%{summary}', raw_issue_data['summary'].value)
+                    .gsub('%{description}', raw_issue_data['description'].value)
+                    .gsub('%{short_name}', raw_issue_data['short_name'].value)
+
+      # Now do generic expansion of anything else
+      DeclaredValue.new(expand_string(formatted))
+    end
+
+    # These tags must not be in the issue creation because they need to be
+    # resolved after the issue is created in Jira.
+    def deferred_tags
+      %w[blocked_by status watchers]
+    end
+
+    # For items in issues that need to be deferred until all the issues are created.
+    # For example, 'blocked_by'
+    #
+    # @param deferral_data [Hash] raw template and jira response data
+    # @see generate_ordinary_issues
+    def process_deferred_updates(deferral_data)
+      ## Find deferred tags in the jira_epic_issues and do the required work
+      deferred_tags.each do |deferred_tag|
+        case deferred_tag
+        when 'blocked_by'
+          process_blocked_by(deferral_data)
+        when 'status'
+          process_status(deferral_data)
+        when 'watchers'
+          process_watchers(deferral_data)
+        else
+          raise "Unimplemented deferred_tag: #{deferred_tag}"
+        end
+      end
+    end
+
+    ## The process_* methods have repeated code. This could be cleaned up
+    ## with some well-thought-through functional techniques. Since the list
+    ## of methods is short, I'll pass on that for now.
+    def process_blocked_by(deferral_data)
+      deferred_tag = 'blocked_by'
+
+      deferral_data.each_value do |deferral_hash|
+        raw_issue_data = deferral_hash['raw']
+        jira_issue_data = deferral_hash['jira']
+        next unless raw_issue_data.key?(deferred_tag)
+
+        target_issues = [raw_issue_data[deferred_tag].value].flatten
+        target_issues.each do |target_issue_name|
+          this_issue_key = jira_issue_data['key']
+
+          # If we skipped creating the target issue because of a 'conditional',
+          # don't try to link to it.
+          target_issue_key = deferral_data.dig(target_issue_name, 'jira', 'key')
+          next if target_issue_key.nil?
+
+          @jira_api.link_issues(target_issue_key, this_issue_key)
+          @logger.info '%14s: blocked by %s' % [this_issue_key, target_issue_key]
+        end
+      end
+    end
+
+    def process_status(deferral_data)
+      deferred_tag = 'status'
+
+      deferral_data.each_value do |deferral_hash|
+        raw_issue_data = deferral_hash['raw']
+        jira_issue_data = deferral_hash['jira']
+        next unless raw_issue_data.key?(deferred_tag)
+
+        issue_key = jira_issue_data['key']
+        new_status = raw_issue_data[deferred_tag].value
+        begin
+          @jira_api.transition(issue_key, new_status)
+        rescue RestClient::BadRequest => e
+          fatal "setting the status on #{issue_key} to #{new_status} failed: #{e}"
+        end
+        status_human_readable = jira_statuses.key(new_status.to_i)
+        @logger.info '%14s: status set to %s' % [issue_key, status_human_readable]
+      end
+    end
+
+    def process_watchers(deferral_data)
+      deferred_tag = 'watchers'
+
+      deferral_data.each_value do |deferral_hash|
+        raw_issue_data = deferral_hash['raw']
+        jira_issue_data = deferral_hash['jira']
+
+        next unless raw_issue_data.key?(deferred_tag)
+
+        issue_key = jira_issue_data['key']
+        watchers = raw_issue_data[deferred_tag].value
+        watchers.each do |watcher|
+          @jira_api.add_watcher(issue_key, watcher)
+          @logger.info '%14s: watched by %s' % [issue_key, watcher]
+        end
+      end
+    end
+
+    # Handle user function calls
+    # Instead of a straight assignment, the issue template can have function calls:
+    #
+    # <some_variable>:
+    #   function:
+    #     name: <function_name>
+    #     argument: <argument>
+    # OR
+    #   function:
+    #     name: <function_name>
+    #     arguments:
+    #       - <arg1>
+    #       - <arg2>
+    #       [ etc ]
+    #
+    # Function calls are intended to be simple, hopefully pure, functions, and free
+    # of conditionals. They are intended to help the user reduce repetition in the
+    # templates and allow calculation of simple formula.
+    #
+    # They should not be allowed to grow into a programming language.
+    #
+    # The action user function implementations are kept in a seperate file
+    # (mixins/user_functions.rb) for clarity and documentation ease.
+
+    def user_function_call(function_definition)
+      @logger.debug "function_definition is: #{function_definition}"
+      function_name = function_definition['name']
+      if function_definition.key?('arguments')
+        function_arguments = function_definition['arguments'].map do |a|
+          expand_right_value(a).value
+        end
+      elsif function_definition.key?('argument')
+        function_arguments = [expand_right_value(function_definition['argument']).value]
+      else
+        fatal("No arguments supplied to function \"#{function_name}\"")
+      end
+
+      unless user_function_allowlist.include?(function_name)
+        fatal "Unknown function call: \"#{function_name}\""
+      end
+
+      return_value = send(function_name, function_arguments)
+      @logger.debug "send(#{function_name}, #{function_arguments}) => #{return_value}"
+      DeclaredValue.new(return_value)
+    end
+
+    # Descend through the 'declare:' section, compiling the @declarations dictionary
+    # from it.
+    def resolve_variables(declarations)
+      environment_keys = ENV.keys
+      declarations&.each do |key, value|
+        right_value = expand_right_value(value)
+
+        # Try to resolve unset variables from the environment. Fall through if we
+        # cannot.
+        if right_value.unset?
+          # Convert %{FOO} to FOO
+          environment_variable = value.gsub(/^%{(.+?)}/, '\1')
+          if environment_keys.include?(environment_variable)
+            @logger.info "Setting \"#{key}\" to \"#{ENV[environment_variable]}\" "\
+                        'from environment variable.'
+            @declarations[key.to_sym] = DeclaredValue.new(ENV[environment_variable])
+            next
+          end
+        end
+        @declarations[key.to_sym] = right_value
+      end
+    end
+
+    # Perform '%{variable}' substition from the template_data structure on all items in
+    # the template_data with some allowed exceptions
+    def variable_substitute(template_data, except: [])
+      template_data.map do |key, value|
+        substituted = if except.include?(key)
+                        DeclaredValue.new(value)
+                      else
+                        expand_right_value(value)
+                      end
+        [key, substituted]
+      end.to_h
+    end
+
+    # Return a value from a key/value pair, substituting variables & function calls
+    # with the evaluated result.
+    def expand_right_value(value)
+      # Some simple cases
+      return value if value.is_a?(DeclaredValue)
+      return DeclaredValue.new(value) if value.is_a?(Numeric)
+      return DeclaredValue.new(expand_string(value)) if value.is_a?(String)
+
+      # Do a user-function call
+      if value.is_a?(Hash) && value.key?('function')
+        return DeclaredValue.new(user_function_call(value['function']))
+      end
+
+      # Return the original hash with the values variable-expanded
+      if value.is_a?(Hash)
+        expanded_hash = value.inject({}) do |hash2, (key2, value2)|
+          expanded_key = expand_right_value(key2)
+          expanded_value = expand_right_value(value2)
+          hash2[expanded_key.value] = expanded_value
+          hash2
+        end
+        return DeclaredValue.new(expanded_hash)
+      end
+
+      # Expand every value element in an array
+      if value.is_a?(Array)
+        return DeclaredValue.new(value.map { |element| expand_right_value(element).value })
+      end
+
+      # Convert booleans to strings
+      # rubocop:disable Style/DoubleNegation
+      return DeclaredValue.new(value.to_s) if !!value == value
+      # rubocop:enable Style/DoubleNegation
+
+      raise "Unimplemented condition in expand_right_value: (#{value.class}) #{value}"
+    end
+
+    def expand_string(value)
+      # Special-case where 'foo: "%{bar}"'; this allows for passing around hashes and
+      # arrays without interpolation into strings
+      single_value = /\A%{(.+?)}\Z/.match(value)
+      return @declarations[single_value[1].to_sym] if single_value
+
+      return value % @declarations
+    end
+
+    # Return a list of all the unset variables in a template
+    def list_unset_variables(template)
+      unset_variables = []
+      template.each do |key, value|
+        if value.is_a?(Hash)
+          unset_variables << list_unset_variables(value)
+          next
+        end
+        if value.unset?
+          unset_variables << key
+        end
+      end
+      unset_variables.flatten
+    end
+
+    def conflicting_conditionals?(template)
+      if template.key?('unless') && (template.key?('conditional') || template.key?('if'))
+        true
+      elsif template.key?('if') && template.key?('conditional')
+        true
+      else
+        false
+      end
+    end
+
+    # Try to find reasons to skip making an issue
+    def skip_issue?(template)
+      if template.key?('conditional')
+        conditional = template['conditional']
+        @logger.debug "Conditional 'conditional' found, value is #{conditional.value}"
+        return conditional.falsey?
+      end
+
+      if template.key?('if')
+        conditional = template['if']
+        @logger.debug "Conditional 'if' found, value is #{conditional.value}"
+        return conditional.falsey?
+      end
+
+      if template.key?('unless')
+        conditional = template['unless']
+        @logger.debug "Conditional 'unless' found, value is #{conditional}"
+        return conditional.truthy?
+      end
+
+      return false
+    end
+
+    # Error-check the expanded template. This section is likely to grow and may want
+    # it's own class.
+    def template_errors?(template_uri, template)
+      return true if nil_template?(template_uri, template) ||
+                     missing_expected_keys?(template_uri, template)
+
+      return false
+    end
+
+    def nil_template?(template_uri, template)
+      return false unless template.nil?
+
+      @logger.error "Cannot find any known template keywords in \"#{template_uri}\""
+      return true
+    end
+
+    def missing_expected_keys?(template_uri, template)
+      expected_keys = %w[epic epics feature issues]
+      return false if (template.keys & expected_keys).any?
+
+      @logger.error "Cannot find any known template keywords in \"#{template_uri}\""
+      return true
+    end
+
+    def logger_initialize(log_location)
+      logger = Logger.new(log_location, progname: 'tefoji', level: @log_level)
+      logger.formatter = proc do |severity, _, script_name, message|
+        if severity == 'INFO'
+          "#{message}\n"
+        else
+          "#{script_name}: #{severity} #{message}\n"
+        end
+      end
+
+      logger
+    end
+  end
+end