howzit 2.0.9 → 2.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e11e4e9f19c26666de0d9dbfbfd0ab1b3c1bee495575fe0962ab5157a185e613
-  data.tar.gz: 7430c1da6d45f7dc873e01a8c1e6618da2dab503659921b9b72d690ad7aff181
+  metadata.gz: bd8307dc1bdbf51c7a78333c5880990b0bf82acb3fb2401d9e9969fe312ce125
+  data.tar.gz: 72ef1a744da1debcd5faf9ff9ee170eae3389b04e585cd652450eb65ba177c30
 SHA512:
-  metadata.gz: 739879dd1a53689e005511745003dd9b9d2ff5a8fa964cec3cb1754ef78e740c488d0a9040cee6b6de5e5eaf62a4a9c50dcc74a236db732e1c78ef4f9c8978cd
-  data.tar.gz: '009601634be888e709ee5709fc2bb990b5dff1a274144469621a9b23dc5108778fec2f8838fc46f03999df8c31d9872f3ad8b9de57afb6bb534035a8f8070c25'
+  metadata.gz: affa665e5f83a8b836f5fe0a3d3c8e178d6fc880bcf3cecfe13afe44e61f4392831a45ff57f1a412a6ae7878f5cd7c00cd541aea1d780eb2b61aa01247268855
+  data.tar.gz: 85449c9184c5927d56acbd00e4086f11a9f4ee85085bfe07c12eb3e7b27e71c00eccee203fd73bda94919dfef000ead8f99f61e275b4d73700b442e25caa38c9

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+### 2.0.10
+
+2022-08-05 08:17
+
+#### IMPROVED
+
+- Provide more helpful feedback if no content is found in build note
+- Confirm whether the user wants to create a new note when one isn't found
+
 ### 2.0.9
 
 2022-08-05 07:29

data/lib/howzit/buildnote.rb

@@ -7,10 +7,27 @@ module Howzit
 
     attr_reader :metadata, :title
 
+    ##
+    ## Initialize a build note
+    ##
+    ## @param      file  [String] The path to the build note file
+    ## @param      args  [Array] additional args
+    ##
     def initialize(file: nil, args: [])
       @topics = []
-      create_note if note_file.nil?
-      @metadata = Util.read_file(note_file).split(/^#/)[0].strip.get_metadata
+      if note_file.nil?
+        res = Prompt.yn('No build notes file found, create one?', default: true)
+
+        create_note if res
+        Process.exit 0
+      end
+      content = Util.read_file(note_file)
+      if content.nil? || content.empty?
+        Howzit.console.error("{br}No content found in build note (#{note_file}){x}".c)
+        Process.exit 1
+      else
+        @metadata = content.split(/^#/)[0].strip.get_metadata
+      end
 
       read_help(file)
     end
@@ -19,14 +36,25 @@ module Howzit
       puts "#<Howzit::BuildNote @topics=[#{@topics.count}]>"
     end
 
+    ##
+    ## Public method to begin processing the build note based on command line options
+    ##
     def run
       process
     end
 
+    ##
+    ## Public method to open build note in editor
+    ##
     def edit
       edit_note
     end
 
+    ##
+    ## Find a topic based on a fuzzy match
+    ##
+    ## @param      term  [String] The search term
+    ##
     def find_topic(term)
       @topics.filter do |topic|
         rx = term.to_rx
@@ -34,11 +62,19 @@ module Howzit
       end
     end
 
+    ##
+    ## Call grep on all topics, filtering out those that don't match
+    ##
+    ## @param      term  [String] The search pattern
+    ##
     def grep(term)
       @topics.filter { |topic| topic.grep(term) }
     end
 
     # Output a list of topic titles
+    #
+    # @return     [String] formatted list of topics in build note
+    #
     def list
       output = []
       output.push("{bg}Topics:{x}\n".c)
@@ -48,14 +84,32 @@ module Howzit
       output.join("\n")
     end
 
+
+    ##
+    ## Return an array of topic titles
+    ##
+    ## @return     [Array] array of topic titles
+    ##
     def list_topics
       @topics.map { |topic| topic.title }
     end
 
+    ##
+    ## Return a list of topic titles suitable for shell completion
+    ##
+    ## @return     [String] newline-separated list of topic titles
+    ##
     def list_completions
       list_topics.join("\n")
     end
 
+    ##
+    ## Return a list of topics containing @directives,
+    ## suitable for shell completion
+    ##
+    ## @return     [String] newline-separated list of topic
+    ##             titles
+    ##
     def list_runnable_completions
       output = []
       @topics.each do |topic|
@@ -64,6 +118,12 @@ module Howzit
       output.join("\n")
     end
 
+    ##
+    ## Return a formatted list of topics containing
+    ## @directives suitable for console output
+    ##
+    ## @return     [String] formatted list
+    ##
     def list_runnable
       output = []
       output.push(%({bg}"Runnable" Topics:{x}\n).c)
@@ -82,6 +142,11 @@ module Howzit
       output.join("\n")
     end
 
+    ##
+    ## Read the help file contents
+    ##
+    ## @param      file  [String] The filepath
+    ##
     def read_file(file)
       read_help_file(file)
     end
@@ -210,6 +275,13 @@ module Howzit
       buildnotes.reverse
     end
 
+    ##
+    ## Test if the filename matches the conditions to be a build note
+    ##
+    ## @param      filename  [String] The filename to test
+    ##
+    ## @return     [Boolean] true if filename passes test
+    ##
     def build_note?(filename)
       return false if filename.downcase !~ /^(howzit[^.]*|build[^.]+)/
 
@@ -218,6 +290,11 @@ module Howzit
       true
     end
 
+    ##
+    ## Glob current directory for valid build note filenames
+    ##
+    ## @return     [String] file path
+    ##
     def glob_note
       filename = nil
       # Check for a build note file in the current folder. Filename must start
@@ -232,6 +309,13 @@ module Howzit
       filename
     end
 
+    ##
+    ## Search for a valid build note, checking current
+    ## directory, git top level directory, and parent
+    ## directories
+    ##
+    ## @return     [String] filepath
+    ##
     def find_note_file
       filename = glob_note
 
@@ -253,6 +337,11 @@ module Howzit
       File.expand_path(filename)
     end
 
+    ##
+    ## Search upstream directories for build notes
+    ##
+    ## @return     [Array] array of build note paths
+    ##
     def read_upstream
       buildnotes = glob_upstream
 
@@ -263,6 +352,13 @@ module Howzit
       topics_dict
     end
 
+    ##
+    ## Test to ensure that any `required` metadata in a
+    ## template is fulfilled by the build note
+    ##
+    ## @param      template  [String] The template to read
+    ##                       from
+    ##
     def ensure_requirements(template)
       t_leader = Util.read_file(template).split(/^#/)[0].strip
       if t_leader.length > 0
@@ -271,8 +367,8 @@ module Howzit
           required = t_meta['required'].strip.split(/\s*,\s*/)
           required.each do |req|
             unless @metadata.keys.include?(req.downcase)
-              Howzit.console.error %({xr}ERROR: Missing required metadata key from template '{bw}#{File.basename(template, '.md')}{xr}'{x}).c
-              Howzit.console.error %({xr}Please define {by}#{req.downcase}{xr} in build notes{x}).c
+              Howzit.console.error %({bRw}ERROR:{xbr} Missing required metadata key from template '{bw}#{File.basename(template, '.md')}{xr}'{x}).c
+              Howzit.console.error %({br}Please define {by}#{req.downcase}{xr} in build notes{x}).c
               Process.exit 1
             end
           end
@@ -280,6 +376,11 @@ module Howzit
       end
     end
 
+    ##
+    ## Read a list of topics from an included template
+    ##
+    ## @param      content  [String] The template contents
+    ##
     def get_template_topics(content)
       leader = content.split(/^#/)[0].strip
 
@@ -327,10 +428,16 @@ module Howzit
       template_topics
     end
 
-    def include_file(m)
-      file = File.expand_path(m[1])
+    ##
+    ## Import the contents of a filename as new topics
+    ##
+    ## @param      mtch  [MatchData] the filename match from
+    ##                   the include directive
+    ##
+    def include_file(mtch)
+      file = File.expand_path(mtch[1])
 
-      return m[0] unless File.exist?(file)
+      return mtch[0] unless File.exist?(file)
 
       content = Util.read_file(file)
       home = ENV['HOME']
@@ -345,6 +452,11 @@ module Howzit
       end
     end
 
+    ##
+    ## Get the title of the build note (top level header)
+    ##
+    ## @param      truncate  [Integer] Truncate to width
+    ##
     def note_title(truncate = 0)
       help = Util.read_file(note_file)
       title = help.match(/(?:^(\S.*?)(?=\n==)|^# ?(.*?)$)/)
@@ -357,7 +469,13 @@ module Howzit
       title && truncate.positive? ? title.trunc(truncate) : title
     end
 
-    # Read in the build notes file and output a hash of "Title" => contents
+    # Read in the build notes file and output a hash of
+    # "Title" => contents
+    #
+    # @param      path  [String] The build note path
+    #
+    # @return     [Array] array of Topics
+    #
     def read_help_file(path = nil)
       topics = []
 
@@ -365,6 +483,11 @@ module Howzit
 
       help = Util.read_file(filename)
 
+      if help.nil? || help.empty?
+        Howzit.console.error("{br}No content found in #{filename}{x}".c)
+        Process.exit 1
+      end
+
       @title = note_title
 
       help.gsub!(/@include\((.*?)\)/) do
@@ -403,6 +526,11 @@ module Howzit
       topics
     end
 
+    ##
+    ## Read build note and include upstream topics
+    ##
+    ## @param      path  [String] The build note path
+    ##
     def read_help(path = nil)
       @topics = read_help_file(path)
       return unless path.nil? && Howzit.options[:include_upstream]
@@ -412,8 +540,17 @@ module Howzit
       upstream_topics.each do |topic|
         @topics.push(topic) unless find_topic(title.sub(/^.+:/, '')).count.positive?
       end
+
+      if note_file && @topics.empty?
+        Howzit.console.error("{br}Note file found but no topics detected in #{note_file}{x}".c)
+        Process.exit 1
+      end
+
     end
 
+    ##
+    ## Open build note in editor
+    ##
     def edit_note
       editor = Howzit.options.fetch(:editor, ENV['EDITOR'])
 
@@ -431,7 +568,16 @@ module Howzit
       end
     end
 
-    def process_topic(topic, run, single = false)
+    ##
+    ## Run or print a topic
+    ##
+    ## @param      topic   [Topic] The topic
+    ## @param      run     [Boolean] execute directives if
+    ##                     true
+    ## @param      single  [Boolean] is being output as a
+    ##                     single topic
+    ##
+    def process_topic(topic, run, single: false)
       new_topic = topic.dup
 
       # Handle variable replacement
@@ -445,6 +591,9 @@ module Howzit
       output.nil? ? '' : output.join("\n")
     end
 
+    ##
+    ## Search and process the build note
+    ##
     def process
       output = []
 
@@ -537,10 +686,10 @@ module Howzit
 
       if !topic_matches.empty?
         # If we found a match
-        topic_matches.each { |topic_match| output.push(process_topic(topic_match, Howzit.options[:run], true)) }
+        topic_matches.each { |topic_match| output.push(process_topic(topic_match, Howzit.options[:run], single: true)) }
       else
         # If there's no argument or no match found, output all
-        topics.each { |k| output.push(process_topic(k, false, false)) }
+        topics.each { |k| output.push(process_topic(k, false, single: false)) }
       end
       Howzit.options[:paginate] = false if Howzit.options[:run]
       Util.show(output.join("\n").strip, Howzit.options)

data/lib/howzit/colors.rb

@@ -4,7 +4,9 @@
 module Howzit
   # Terminal output color functions.
   module Color
+    # Regexp to match excape sequences
     ESCAPE_REGEX = /(?<=\[)(?:(?:(?:[349]|10)[0-9]|[0-9])?;?)+(?=m)/.freeze
+
     # All available color names. Available as methods and string extensions.
     #
     # @example Use a color as a method. Color reset will be added to end of string.
@@ -79,6 +81,7 @@ module Howzit
       [:default, '0;39']
     ].map(&:freeze).freeze
 
+    # Array of attribute keys only
     ATTRIBUTE_NAMES = ATTRIBUTES.transpose.first
 
     # Returns true if Howzit::Color supports the +feature+.

data/lib/howzit/console_logger.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Available log levels
 LOG_LEVELS = {
   debug: 0,
   info: 1,

data/lib/howzit/hash.rb

@@ -41,7 +41,7 @@ class ::Hash
   end
 
   def stringify_keys!
-  	replace stringify_keys
+    replace stringify_keys
   end
 
   # Turn all keys into symbols
@@ -50,6 +50,6 @@ class ::Hash
   end
 
   def symbolize_keys!
-  	replace symbolize_keys
+    replace symbolize_keys
   end
 end

data/lib/howzit/task.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Howzit
+  # Task object
   class Task
     attr_reader :type, :title, :action, :parent, :optional, :default
 

data/lib/howzit/version.rb

@@ -3,5 +3,5 @@
 # Primary module for this gem.
 module Howzit
   # Current Howzit version.
-  VERSION = '2.0.9'
+  VERSION = '2.0.10'
 end

data/lib/howzit.rb

@@ -24,11 +24,22 @@ require 'tty/screen'
 require 'tty/box'
 # require 'tty/prompt'
 
+# Main config dir
 CONFIG_DIR = '~/.config/howzit'
+
+# Config file name
 CONFIG_FILE = 'howzit.yaml'
+
+# Ignore file name
 IGNORE_FILE = 'ignore.yaml'
+
+# Available options for matching method
 MATCHING_OPTIONS = %w[partial exact fuzzy beginswith].freeze
+
+# Available options for multiple_matches method
 MULTIPLE_OPTIONS = %w[first best all choose].freeze
+
+# Available options for header formatting
 HEADER_FORMAT_OPTIONS = %w[border block].freeze
 
 # Main module for howzit

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.0.9
+  version: 2.0.10
 platform: ruby
 authors:
 - Brett Terpstra
@@ -297,7 +297,6 @@ files:
 - lib/.rubocop.yml
 - lib/howzit.rb
 - lib/howzit/buildnote.rb
-- lib/howzit/buildnotes.rb
 - lib/howzit/colors.rb
 - lib/howzit/config.rb
 - lib/howzit/console_logger.rb