na 1.2.84 → 1.2.86

data/lib/na/benchmark.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 module NA
+  # Provides benchmarking utilities for measuring code execution time.
+  #
+  # @example Measure a block of code
+  #   NA::Benchmark.measure('sleep') { sleep(1) }
   module Benchmark
     class << self
       attr_accessor :enabled, :timings
@@ -18,6 +22,8 @@ module NA
       #
       # @param label [String] Label for the measurement
       # @return [Object] Result of the block
+      # @example
+      #   NA::Benchmark.measure('sleep') { sleep(1) }
       def measure(label)
         return yield unless @enabled
 
@@ -31,6 +37,8 @@ module NA
       # Output a performance report to STDERR
       #
       # @return [void]
+      # @example
+      #   NA::Benchmark.report
       def report
         return unless @enabled
 

data/lib/na/colors.rb

@@ -3,6 +3,9 @@
 # Cribbed from <https://github.com/flori/term-ansicolor>
 module NA
   # Terminal output color functions.
+  #
+  # @example Clear the color template cache
+  #   NA::Color.clear_template_cache
   module Color
     # Regexp to match excape sequences
     ESCAPE_REGEX = /(?<=\[)(?:(?:(?:[349]|10)[0-9]|[0-9])?;?)+(?=m)/.freeze
@@ -199,6 +202,10 @@ module NA
         @template_cache ||= {}
       end
 
+      # Clears the cached compiled color templates.
+      # @return [void]
+      # @example
+      #   NA::Color.clear_template_cache
       def clear_template_cache
         @template_cache = {}
       end
@@ -231,15 +238,15 @@ module NA
       # i: italic, x: reset (remove background, color,
       # emphasis)
       #
-      # Also accepts {#RGB} and {#RRGGBB} strings. Put a b
+      # Also accepts `{#RGB}` and `{#RRGGBB}` strings. Put a b
       # before the hash to make it a background color
       #
       # @example    Convert a templated string
-      # Color.template('{Rwb}Warning:{x} {w}you look a
-      # little {g}ill{x}')
+      # Color.template('\\{Rwb\\}Warning:\\{x\\} \\{w\}\you look a
+      # little \\{g\\}ill\\{x\\}')
       #
       # @example    Convert using RGB colors
-      # Color.template('{#f0a}This is an RGB color')
+      # Color.template('\\{#f0a\\}This is an RGB color')
       #
       # @param      input  [String, Array] The template
       #                    string. If this is an array, the

data/lib/na/editor.rb

@@ -3,8 +3,12 @@
 require 'English'
 
 module NA
+  # Provides editor selection and argument helpers for launching text editors.
   module Editor
     class << self
+      # Returns the default editor command, checking environment variables and available editors.
+      # @param prefer_git_editor [Boolean] Prefer GIT_EDITOR over EDITOR
+      # @return [String, nil] Editor command or nil if not found
       def default_editor(prefer_git_editor: true)
         editor ||= if prefer_git_editor
                      ENV['NA_EDITOR'] || ENV['GIT_EDITOR'] || ENV.fetch('EDITOR', nil)
@@ -29,10 +33,15 @@ module NA
         nil
       end
 
+      # Returns the default editor command with its arguments.
+      # @return [String] Editor command with arguments
       def editor_with_args
         args_for_editor(default_editor)
       end
 
+      # Returns the editor command with appropriate arguments for file opening.
+      # @param editor [String] Editor command
+      # @return [String] Editor command with arguments
       def args_for_editor(editor)
         return editor if editor =~ /-\S/
 
@@ -91,7 +100,12 @@ module NA
           tmpfile.unlink
         end
 
-        input.split("\n").delete_if(&:ignore?).join("\n")
+        # Don't strip comments if this looks like multi-action format (has # ------ markers)
+        if input.include?('# ------ ')
+          input
+        else
+          input.split("\n").delete_if(&:ignore?).join("\n")
+        end
       end
 
       # Takes a multi-line string and formats it as an entry
@@ -120,6 +134,80 @@ module NA
 
         [title, note]
       end
+
+      # Format multiple actions for multi-edit
+      # @param actions [Array<Action>] Actions to edit
+      # @return [String] Formatted editor content
+      def format_multi_action_input(actions)
+        header = <<~EOF
+          # Instructions:
+          # - Edit the action text (the lines WITHOUT # comment markers)
+          # - DO NOT remove or edit the lines starting with "# ------"
+          # - Add notes on new lines after the action
+          # - Blank lines are ignored
+          #
+
+        EOF
+
+        # Use + to create a mutable string
+        content = +header
+
+        actions.each do |action|
+          # Use file_path to get the path and file_line to get the line number
+          content << "# ------ #{action.file_path}:#{action.file_line}\n"
+          content << "#{action.action}\n"
+          content << "#{action.note.join("\n")}\n" if action.note.any?
+          content << "\n" # Blank line separator
+        end
+
+        content
+      end
+
+      # Parse multi-action editor output
+      # @param content [String] Editor output
+      # @return [Hash] Hash mapping file:line to [action, note]
+      def parse_multi_action_output(content)
+        results = {}
+        current_file = nil
+        current_action = nil
+        current_note = []
+
+        content.lines.each do |line|
+          stripped = line.strip
+
+          # Check for file marker: # ------ path:line
+          match = stripped.match(/^# ------ (.+?):(\d+)$/)
+          if match
+            # Save previous action if exists
+            results[current_file] = [current_action, current_note] if current_file && current_action
+
+            # Start new action
+            current_file = "#{match[1]}:#{match[2]}"
+            current_action = nil
+            current_note = []
+            next
+          end
+
+          # Skip other comment lines
+          next if stripped.start_with?('#')
+
+          # Skip blank lines
+          next if stripped.empty?
+
+          # Store as action or note based on what we've seen so far
+          if current_action.nil?
+            current_action = stripped
+          else
+            # Subsequent lines are notes
+            current_note << stripped
+          end
+        end
+
+        # Save last action
+        results[current_file] = [current_action, current_note] if current_file && current_action
+
+        results
+      end
     end
   end
 end

data/lib/na/hash.rb

@@ -1,9 +1,16 @@
 # frozen_string_literal: true
 
+##
+# Extensions to Ruby's Hash class for symbolizing keys and deep freezing values.
+#
+# @example Symbolize all keys in a hash
+#   { 'foo' => 1, 'bar' => { 'baz' => 2 } }.symbolize_keys #=> { :foo => 1, :bar => { :baz => 2 } }
 class ::Hash
   # Convert all keys in the hash to symbols recursively
   #
   # @return [Hash] Hash with symbolized keys
+  # @example
+  #   { 'foo' => 1, 'bar' => { 'baz' => 2 } }.symbolize_keys #=> { :foo => 1, :bar => { :baz => 2 } }
   def symbolize_keys
     each_with_object({}) { |(k, v), hsh| hsh[k.to_sym] = v.is_a?(Hash) ? v.symbolize_keys : v }
   end
@@ -12,6 +19,8 @@ class ::Hash
   # Freeze all values in a hash
   #
   # @return     Hash with all values frozen
+  # @example
+  #   { foo: { bar: 'baz' } }.deep_freeze
   def deep_freeze
     chilled = {}
     each do |k, v|

data/lib/na/help_monkey_patch.rb

@@ -1,17 +1,26 @@
 # frozen_string_literal: true
 
+##
+# Monkeypatches for GLI CLI framework to support paginated help output.
+#
+# @example Show help for a command
+#   GLI::Commands::Help.new.show_help({}, {}, [], $stdout, $stderr)
 module GLI
+  ##
+  # Command extensions for GLI CLI framework.
   module Commands
     # Help Command Monkeypatch for paginated output
     class Help < Command
       # Show help output for GLI commands with paginated output
       #
-      # @param global_options [Hash] Global CLI options
+      # @param _global_options [Hash] Global CLI options
       # @param options [Hash] Command-specific options
       # @param arguments [Array] Command arguments
       # @param out [IO] Output stream
       # @param error [IO] Error stream
       # @return [void]
+      # @example
+      #   GLI::Commands::Help.new.show_help({}, {}, [], $stdout, $stderr)
       def show_help(_global_options, options, arguments, out, error)
         NA::Pager.paginate = true
 

data/lib/na/next_action.rb

@@ -8,10 +8,17 @@ module NA
     attr_accessor :verbose, :extension, :include_ext, :na_tag, :command_line, :command, :globals, :global_file,
                   :cwd_is, :cwd, :stdin, :show_cwd_indicator
 
+    # Returns the current theme hash for color and style settings.
+    # @return [Hash] The theme settings
     def theme
       @theme ||= NA::Theme.load_theme
     end
 
+    # Print a message to stderr, optionally exit or debug.
+    # @param msg [String] The message to print
+    # @param exit_code [Integer, Boolean] Exit code or false for no exit
+    # @param debug [Boolean] Only print if verbose
+    # @return [void]
     def notify(msg, exit_code: false, debug: false)
       return if debug && !NA.verbose
 
@@ -23,6 +30,8 @@ module NA
       Process.exit exit_code if exit_code
     end
 
+    # Returns a map of priority levels to numeric values.
+    # @return [Hash{String=>Integer}] Priority mapping
     def priority_map
       {
         'h' => 5,
@@ -128,6 +137,11 @@ module NA
       end
     end
 
+    # Shift project indices after a given index by a length.
+    # @param projects [Array<NA::Project>] Projects to shift
+    # @param idx [Integer] Index after which to shift
+    # @param length [Integer] Amount to shift
+    # @return [Array<NA::Project>] Shifted projects
     def shift_index_after(projects, idx, length = 1)
       projects.map do |proj|
         proj.line = proj.line - length if proj.line > idx
@@ -155,8 +169,9 @@ module NA
     # @param done [Boolean] Include done actions
     # @param project [String, nil] Project name
     # @param search_note [Boolean] Search notes
+    # @param target_line [Integer] Specific line number to target
     # @return [Array] Projects and actions
-    def find_actions(target, search, tagged = nil, all: false, done: false, project: nil, search_note: true)
+    def find_actions(target, search, tagged = nil, all: false, done: false, project: nil, search_note: true, target_line: nil)
       todo = NA::Todo.new({ search: search,
                             search_note: search_note,
                             require_na: false,
@@ -173,7 +188,17 @@ module NA
 
       return [todo.projects, todo.actions] if todo.actions.count == 1 || all
 
-      options = todo.actions.map { |action| "#{action.line} % #{action.parent.join('/')} : #{action.action}" }
+      # If target_line is specified, find the action at that specific line
+      if target_line
+        matching_action = todo.actions.find { |a| a.line == target_line }
+        return [todo.projects, NA::Actions.new([matching_action])] if matching_action
+
+        NA.notify("#{NA.theme[:error]}No action found at line #{target_line}", exit_code: 1)
+        return [todo.projects, NA::Actions.new]
+
+      end
+
+      options = todo.actions.map { |action| "#{action.file} : #{action.action}" }
       res = choose_from(options, prompt: 'Make a selection: ', multiple: true, sorted: true)
 
       unless res&.length&.positive?
@@ -183,9 +208,14 @@ module NA
 
       selected = NA::Actions.new
       res.each do |result|
-        idx = result.match(/^(\d+)(?= % )/)[1]
-        action = todo.actions.select { |a| a.line == idx.to_i }.first
-        selected.push(action)
+        # Extract file:line from result (e.g., "./todo.taskpaper:21 : action text")
+        match = result.match(/^(.+?):(\d+) : /)
+        next unless match
+
+        file_path = match[1]
+        line_num = match[2].to_i
+        action = todo.actions.select { |a| a.file_path == file_path && a.file_line == line_num }.first
+        selected.push(action) if action
       end
       [todo.projects, selected]
     end
@@ -194,9 +224,8 @@ module NA
     #
     # @param target [String] Path to the todo file
     # @param project [String] Project name
-    # @param projects [Array<NA::Project>] Existing projects
     # @return [NA::Project] The new project
-    def insert_project(target, project, _projects)
+    def insert_project(target, project)
       path = project.split(%r{[:/]})
       todo = NA::Todo.new(file_path: target)
       built = []
@@ -299,6 +328,9 @@ module NA
                       remove_tag: [],
                       replace: nil,
                       tagged: nil)
+      # Expand target to absolute path to avoid path resolution issues
+      target = File.expand_path(target) unless Pathname.new(target).absolute?
+
       projects = find_projects(target)
       affected_actions = []
 
@@ -323,11 +355,14 @@ module NA
       contents = target.read_file.split("\n")
 
       if add.is_a?(Action)
+        # NOTE: Edit is handled in the update command before calling update_action
+        # So we don't need to handle it here - the action is already edited
+
         add_tag ||= []
         add.process(priority: priority, finish: finish, add_tag: add_tag, remove_tag: remove_tag)
 
         # Remove the original action and its notes
-        action_line = add.line
+        action_line = add.file_line
         note_lines = add.note.is_a?(Array) ? add.note.count : 0
         contents.slice!(action_line, note_lines + 1)
 
@@ -376,27 +411,36 @@ module NA
         changes << "moved to #{target_proj.project}" if move && target_proj
         affected_actions << { action: add, desc: changes.join(', ') }
       else
+        # Check if search is actually target_line
+        target_line = search.is_a?(Hash) && search[:target_line] ? search[:target_line] : nil
         _, actions = find_actions(target, search, tagged, done: done, all: all, project: project,
-                                                          search_note: search_note)
+                                                          search_note: search_note, target_line: target_line)
 
         return if actions.nil?
 
-        actions.sort_by(&:line).reverse.each do |action|
-          contents.slice!(action.line, action.note.count + 1)
+        # Handle edit (single or multi-action)
+        if edit
+          editor_content = Editor.format_multi_action_input(actions)
+          edited_content = Editor.fork_editor(editor_content)
+          edited_actions = Editor.parse_multi_action_output(edited_content)
+
+          # Map edited content back to actions
+          actions.each do |action|
+            # Use file_path:file_line as the key
+            key = "#{action.file_path}:#{action.file_line}"
+            action.action, action.note = edited_actions[key] if edited_actions[key]
+          end
+        end
+
+        actions.sort_by(&:file_line).reverse.each do |action|
+          contents.slice!(action.file_line, action.note.count + 1)
           if delete
             # Track deletion before skipping re-insert
             affected_actions << { action: action, desc: 'deleted' }
             next
           end
 
-          projects = shift_index_after(projects, action.line, action.note.count + 1)
-
-          if edit
-            editor_content = "#{action.action}\n#{action.note.join("\n")}"
-            new_action, new_note = Editor.format_input(Editor.fork_editor(editor_content))
-            action.action = new_action
-            action.note = new_note
-          end
+          projects = shift_index_after(projects, action.file_line, action.note.count + 1)
 
           # If replace is defined, use search to search and replace text in action
           action.action.sub!(Regexp.new(Regexp.escape(search), Regexp::IGNORECASE), replace) if replace
@@ -602,6 +646,19 @@ module NA
       end
     end
 
+    # Find files matching criteria and containing actions.
+    # @param options [Hash] Options for file search
+    # @option options [Integer] :depth Search depth
+    # @option options [Boolean] :done Include done actions
+    # @option options [String] :file_path File path
+    # @option options [Boolean] :negate Negate search
+    # @option options [Boolean] :hidden Include hidden files
+    # @option options [String] :project Project name
+    # @option options [String] :query Query string
+    # @option options [Boolean] :regex Use regex
+    # @option options [String] :search Search string
+    # @option options [String] :tag Tag to filter
+    # @return [Array<String>] Matching files
     def find_files_matching(options = {})
       defaults = {
         depth: 1,
@@ -690,6 +747,10 @@ module NA
       end
     end
 
+    # Find a directory with an exact match from a list.
+    # @param dirs [Array<String>] Directories to search
+    # @param search [Array<Hash>] Search tokens
+    # @return [Array<String>] Matching directories
     def find_exact_dir(dirs, search)
       terms = search.filter { |s| !s[:negate] }.map { |t| t[:token] }.join(' ')
       out = dirs
@@ -878,6 +939,12 @@ module NA
       File.open(file, 'w') { |f| f.puts dirs.join("\n") }
     end
 
+    # List projects in a todo file or matching query.
+    # @param query [Array] Query tokens
+    # @param file_path [String, nil] File path
+    # @param depth [Integer] Search depth
+    # @param paths [Boolean] Show full paths
+    # @return [void]
     def list_projects(query: [], file_path: nil, depth: 1, paths: true)
       files = if NA.global_file
                 [NA.global_file]
@@ -906,6 +973,9 @@ module NA
       end
     end
 
+    # List todo files matching a query.
+    # @param query [Array] Query tokens
+    # @return [void]
     def list_todos(query: [])
       dirs = if query
                match_working_dir(query, distance: 2, require_last: false)
@@ -922,6 +992,10 @@ module NA
       puts NA::Color.template(dirs.join("\n"))
     end
 
+    # Save a search definition to the database.
+    # @param title [String] The search title
+    # @param search [String] The search string
+    # @return [void]
     def save_search(title, search)
       file = database_path(file: 'saved_searches.yml')
       searches = load_searches

data/lib/na/project.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 module NA
+  # Represents a project section in a todo file, with indentation and line tracking.
+  #
+  # @example Create a new project
+  #   project = NA::Project.new('Inbox', 0, 1, 5)
   class Project < Hash
     attr_accessor :project, :indent, :line, :last_line
 
@@ -11,6 +15,8 @@ module NA
     # @param line [Integer] Starting line number
     # @param last_line [Integer] Ending line number
     # @return [void]
+    # @example
+    #   project = NA::Project.new('Inbox', 0, 1, 5)
     def initialize(project, indent = 0, line = 0, last_line = 0)
       super()
       @project = project
@@ -22,6 +28,8 @@ module NA
     # String representation of the project
     #
     # @return [String]
+    # @example
+    #   project.to_s #=> "{ project: 'Inbox', ... }"
     def to_s
       { project: @project, indent: @indent, line: @line, last_line: @last_line }.to_s
     end

data/lib/na/string.rb

@@ -1,15 +1,39 @@
 # frozen_string_literal: true
 
+# Special handling for nil strings
+class ::NilClass
+  # Always returns an empty string for nil.
+  # @return [String]
+  def highlight_filename
+    ''
+  end
+
+  # Always returns an empty string for nil.
+  # @param max [Integer] Maximum allowed length
+  # @return [String]
+  def trunc_middle(max)
+    ''
+  end
+end
+
+# Matches day names (e.g., mon, tue, wednesday)
+# @return [Regexp]
 REGEX_DAY = /^(mon|tue|wed|thur?|fri|sat|sun)(\w+(day)?)?$/i.freeze
+
+# Matches clock times (e.g., 12:30 pm, midnight)
+# @return [String]
 REGEX_CLOCK = '(?:\d{1,2}+(?::\d{1,2}+)?(?: *(?:am|pm))?|midnight|noon)'
+
+# Matches time strings using REGEX_CLOCK
+# @return [Regexp]
 REGEX_TIME = /^#{REGEX_CLOCK}$/i.freeze
 
 # String helpers
 class ::String
   # Insert a comment character at the start of every line
   # @param char [String] The character to insert (default #)
-  def comment(_char = '#')
-    split("\n").map { |l| "# #{l}" }.join("\n")
+  def comment(char = '#')
+    split("\n").map { |l| "#{char} #{l}" }.join("\n")
   end
 
   # Tests if object is nil or empty
@@ -25,6 +49,10 @@ class ::String
     line =~ /^#/ || line.strip.empty?
   end
 
+  # Returns the contents of the file, or raises if missing.
+  # Handles directories and NA extension.
+  # @return [String] Contents of the file
+  # @raise [RuntimeError] if the file does not exist
   def read_file
     file = File.expand_path(self)
     raise "Missing file #{file}" unless File.exist?(file)
@@ -64,11 +92,15 @@ class ::String
     !action? && self =~ /:( +@\S+(\([^)]*\))?)*$/
   end
 
+  # Returns the project name if matched, otherwise nil.
+  # @return [String, nil]
   def project
     m = match(/^([ \t]*)([^\-][^@:]*?): *(@\S+ *)*$/)
     m ? m[2] : nil
   end
 
+  # Returns the action text with leading dash and whitespace removed.
+  # @return [String]
   def action
     sub(/^[ \t]*- /, '')
   end
@@ -84,6 +116,8 @@ class ::String
   # Colorize the dirname and filename of a path
   # @return [String] Colorized string
   def highlight_filename
+    return '' if nil?
+
     dir = File.dirname(self).shorten_path.trunc_middle(TTY::Screen.columns / 3)
     file = NA.include_ext ? File.basename(self) : File.basename(self, ".#{NA.extension}")
     "#{NA.theme[:dirname]}#{dir}/#{NA.theme[:filename]}#{file}{x}"
@@ -115,13 +149,17 @@ class ::String
   # @param color [String] The highlight color template
   # @param last_color [String] Color to restore after highlight
   def highlight_search(regexes, color: NA.theme[:search_highlight], last_color: NA.theme[:action])
+    # Skip if string already contains ANSI codes - applying regex to colored text
+    # will break escape sequences (e.g., searching for "3" will match "3" in "38;2;236;204;135m")
+    return self if include?("\e")
+
+    # Original simple approach for strings without ANSI codes
     string = dup
     color = NA::Color.template(color.dup)
     regexes.each do |rx|
       next if rx.nil?
 
       rx = Regexp.new(rx, Regexp::IGNORECASE) if rx.is_a?(String)
-
       string.gsub!(rx) do
         m = Regexp.last_match
         last = m.pre_match.last_color
@@ -135,14 +173,15 @@ class ::String
   # @param max [Integer] Maximum allowed length of the string
   # @return [String] Truncated string with middle replaced if necessary
   def trunc_middle(max)
-  return '' if self.nil?
-  return self unless length > max
+    return '' if nil?
+
+    return self unless length > max
 
-  half = (max / 2).floor - 3
-  chars = chars
-  pre = chars.slice(0, half)
-  post = chars.reverse.slice(0, half).reverse
-  "#{pre.join}[...]#{post.join}"
+    half = (max / 2).floor - 3
+    cs = chars
+    pre = cs.slice(0, half)
+    post = cs.reverse.slice(0, half).reverse
+    "#{pre.join}[...]#{post.join}"
   end
 
   # Wrap the string to a given width, indenting each line and preserving tag formatting.
@@ -155,9 +194,9 @@ class ::String
     output = []
     line = []
     length = 0
-    gsub!(/(@\S+)\((.*?)\)/) { "#{Regexp.last_match(1)}(#{Regexp.last_match(2).gsub(/ /, '†')})" }
+    text = gsub(/(@\S+)\((.*?)\)/) { "#{Regexp.last_match(1)}(#{Regexp.last_match(2).gsub(/ /, '†')})" }
 
-    split(' ').each do |word|
+    text.split.each do |word|
       uncolored = NA::Color.uncolor(word)
       if (length + uncolored.length + 1) <= width
         line << word