howzit 2.1.42 → 2.1.45

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8916b2ac37cd920db8008fe7a9aa28a80b4c5265083b4b257fb8ea1113938efb
-  data.tar.gz: 9486d6ca52f82ea5059bffd0de58333b82eedfc623d03f6325817caf8c956d4f
+  metadata.gz: 3b5d2120c8484147d2d3cb8f8844073ca027e7a54655385749ee721f645d05a5
+  data.tar.gz: 3cef9cda18bf1b43b28d9288e9eda81d30b07fc9ac2505dd932e508240abf86b
 SHA512:
-  metadata.gz: 5819786618c45538e42f21243102043b1ed408f516b0b946adaa9a2819d0080c2804cba47987f4ba0ed98b21ad7499d42cc825c2f89efb63cc4f6d8013bd743d
-  data.tar.gz: 2a90edf5e41602e1c6fc50ab21a6bfc3531b598f3a5cc381492f284bbb588b2590589fbc23da0f007a021605d46f7246e2908eed89895c175c24838b4755b285
+  metadata.gz: 4dc4af7fce8a375a33a3dfee3ed2e6f9d914ea3069601aa3426ae552f4c5488d5aafa332522c4eef0a6b4318bd63afef20eda2d638e9c6fd09ce9784c5e6a434
+  data.tar.gz: fe60529771944221e4f7acd4bd9883669782f413c5a367ae3c03c8c7d8ce0a0e0413fcf4e086e37584868c58bbea10bb4e24ab49c28583521d901166404146be

data/CHANGELOG.md

@@ -1,3 +1,78 @@
+### 2.1.45
+
+2026-09-27 12:16
+
+#### CHANGED
+
+- **Multi-topic runs** (comma-separated topics or `default:` metadata) now stop after the first topic with a failed task and mark the remaining topics' tasks as skipped; use --force to run every topic.
+
+#### NEW
+
+- **Skipped tasks** in the run report: tasks that did not run because of an earlier failure are listed with a skipped marker and "(skipped)" label.
+- **Skipped @include tasks** are expanded to the included topic's individual tasks in the run report.
+
+#### IMPROVED
+
+- **Conditional topics** list remaining unconditional tasks as skipped after a failure; tasks inside unevaluated conditionals are omitted.
+
+#### FIXED
+
+- **Run report** now includes the task that failed and stopped a run, instead of omitting it and showing only the earlier successes.
+- **@include** directives now fail when a task in the included topic fails, so the including topic stops instead of continuing with its remaining tasks.
+- **Task totals for @include** reflect the included topic's actual successes and errors instead of counting every included task as a single result.
+
+### 2.1.44
+
+2026-09-27 11:38
+
+#### CHANGED
+
+- **Task failures** in a parent or subtopic stop the remaining subtopics from running unless --force is used.
+- **@after blocks** on a parent are shown after the parent and all of its subtopics finish.
+
+#### NEW
+
+- **Subtopics**: deeper headers (### under ##, #### under ###, etc.) are now nested under the preceding shallower topic.
+- **Displaying a parent topic** shows all of its subtopics after it, with subtopic headers drawn in a lighter style (cyan title, dotted rule).
+- **Running a parent topic** runs its own tasks, then every subtopic's tasks in order (depth-first), with a single combined "Ran N tasks" summary.
+
+#### IMPROVED
+
+- **Showing all topics** (howzit with no arguments, or howzit -r with no default) only outputs top-level topics so subtopics are not repeated.
+- **Selecting both a parent and its subtopic** outputs/runs the subtopic only once, as part of the parent.
+- **Topic lists** (howzit -l and the runnable topics list) indent subtopics under their parents.
+- **@include(Topic)** on a parent runs the parent and all of its subtopics, and task counts in include notes and menus now count subtopic tasks.
+
+#### FIXED
+
+- **Parent topics with no tasks of their own** no longer warn "No @directive found" when their subtopics contain tasks.
+
+### 2.1.43
+
+2026-09-27 11:35
+
+#### CHANGED
+
+- **Task failures** in a parent or subtopic stop the remaining subtopics from running unless --force is used.
+- **@after blocks** on a parent are shown after the parent and all of its subtopics finish.
+
+#### NEW
+
+- **Subtopics**: deeper headers (### under ##, #### under ###, etc.) are now nested under the preceding shallower topic.
+- **Displaying a parent topic** shows all of its subtopics after it, with subtopic headers drawn in a lighter style (cyan title, dotted rule).
+- **Running a parent topic** runs its own tasks, then every subtopic's tasks in order (depth-first), with a single combined "Ran N tasks" summary.
+
+#### IMPROVED
+
+- **Showing all topics** (howzit with no arguments, or howzit -r with no default) only outputs top-level topics so subtopics are not repeated.
+- **Selecting both a parent and its subtopic** outputs/runs the subtopic only once, as part of the parent.
+- **Topic lists** (howzit -l and the runnable topics list) indent subtopics under their parents.
+- **@include(Topic)** on a parent runs the parent and all of its subtopics, and task counts in include notes and menus now count subtopic tasks.
+
+#### FIXED
+
+- **Parent topics with no tasks of their own** no longer warn "No @directive found" when their subtopics contain tasks.
+
 ### 2.1.42
 
 2026-06-29 06:52

data/Rakefile

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# rspec, rubocop plugins, and the .rubocop_todo.yml cops depend on the locked bundle
+exec('bundle', 'exec', 'rake', *ARGV) unless ENV['BUNDLE_GEMFILE']
+
 # require 'bump/tasks'
 require 'English'
 require 'bundler/gem_tasks'

data/howzit.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 2.6.0'
 
-  spec.add_development_dependency 'bundler', '~> 2.2'
+  spec.add_development_dependency 'bundler', '>= 2.2'
   spec.add_development_dependency 'rake', '~> 13.0'
 
   spec.add_development_dependency 'guard', '~> 2.11'

data/lib/howzit/buildnote.rb

@@ -169,11 +169,37 @@ module Howzit
       output = []
       output.push("{bg}Topics:{x}\n".c)
       @topics.each do |topic|
-        output.push("- {bw}#{topic.title}{x}".c)
+        output.push("#{subtopic_indent(topic)}- {bw}#{topic.title}{x}".c)
       end
       output.join("\n")
     end
 
+    ##
+    ## Indentation for a topic in list output, based on
+    ## how many of its parent topics are in the list
+    ##
+    ## @param      topic  [Topic] The topic
+    ##
+    ## @return     [String] leading whitespace
+    ##
+    def subtopic_indent(topic)
+      '  ' * topic.ancestors.count { |parent| @topics.any? { |t| t.equal?(parent) } }
+    end
+
+    ##
+    ## Topics that aren't nested under another topic in
+    ## the build note (subtopics are output with their parent)
+    ##
+    ## @param      topics  [Array] Topics to filter, defaults to all topics
+    ##
+    ## @return     [Array] array of Topics
+    ##
+    def top_level_topics(topics = @topics)
+      topics.reject do |topic|
+        topic.ancestors.any? { |parent| topics.any? { |t| t.equal?(parent) } }
+      end
+    end
+
     ##
     ## Return an array of topic titles
     ##
@@ -204,7 +230,7 @@ module Howzit
     def list_runnable_completions
       output = []
       @topics.each do |topic|
-        next unless topic.tasks.count.positive?
+        next unless topic.all_tasks.any?
 
         output.push(topic.title)
       end
@@ -222,11 +248,10 @@ module Howzit
       output.push(%({bg}"Runnable" Topics:{x}\n).c)
 
       find_topic(Howzit.options[:for_topic]).each do |topic|
-        s_out = []
-
-        topic.tasks.each { |task| s_out.push(task.to_list) }
+        next if topic.all_tasks.empty?
 
-        next if s_out.empty?
+        indent = subtopic_indent(topic)
+        s_out = topic.tasks.map { |task| "#{indent}#{task.to_list}" }
 
         title = topic.title
         # Show argument definitions with colorized formatting
@@ -235,8 +260,8 @@ module Howzit
           title += " {l}({x}#{formatted_args}{l}){x}".c
         end
 
-        output.push("- {g}#{title}{x}".c)
-        output.push(s_out.join("\n"))
+        output.push("#{indent}- {g}#{title}{x}".c)
+        output.push(s_out.join("\n")) unless s_out.empty?
       end
 
       output.join("\n")
@@ -956,11 +981,13 @@ module Howzit
 
       template_topics = get_template_topics(help)
 
-      split = help.split(/^##+/)
-      split.slice!(0)
-      split.each do |sect|
-        next if sect.strip.empty?
+      sections = help.split(/^(##+)/)
+      sections.shift
+      parent_stack = []
+      sections.each_slice(2) do |marks, sect|
+        next if sect.nil? || sect.strip.empty?
 
+        level = marks.length
         lines = sect.split(/\n/)
         title = lines.slice!(0).strip
         prefix = ''
@@ -978,7 +1005,12 @@ module Howzit
         # Ensure source_file is always an absolute path
         source_file = path || note_file
         source_file = File.expand_path(source_file) if source_file
-        topic = Topic.new(title, prefix + lines.join("\n").strip.render_template(@metadata), @metadata, source_file: source_file)
+        topic = Topic.new(title, prefix + lines.join("\n").strip.render_template(@metadata), @metadata,
+                          source_file: source_file, level: level)
+
+        parent_stack.pop while parent_stack.any? && parent_stack.last.level >= level
+        parent_stack.last&.add_subtopic(topic)
+        parent_stack.push(topic)
 
         topics.push(topic)
       end
@@ -1373,13 +1405,13 @@ module Howzit
           process_default_metadata(output)
         else
           Howzit.run_log = []
-          Howzit.multi_topic_run = topics.length > 1
-          topics.each { |k| output.push(process_topic(k, false, single: false)) }
+          Howzit.multi_topic_run = top_level_topics.length > 1
+          top_level_topics.each { |k| output.push(process_topic(k, false, single: false)) }
           finalize_output(output)
         end
       else
         # Show all topics
-        topics.each { |k| output.push(process_topic(k, false, single: false)) }
+        top_level_topics.each { |k| output.push(process_topic(k, false, single: false)) }
         finalize_output(output)
       end
     end
@@ -1525,9 +1557,14 @@ module Howzit
           end
         end
         topic_matches.compact! # Remove any nil values from failed matches
-        topic_matches.each { |topic_match| output.push(process_topic(topic_match, Howzit.options[:run], single: true)) }
+        # A matched subtopic is already output/run with its matched parent
+        selected = top_level_topics(topic_matches)
+        selected.each_with_index do |topic_match, idx|
+          output.push(process_topic(topic_match, Howzit.options[:run], single: true))
+          break if stop_after_failure?(selected[(idx + 1)..])
+        end
       else
-        topics.each { |k| output.push(process_topic(k, false, single: false)) }
+        top_level_topics.each { |k| output.push(process_topic(k, false, single: false)) }
       end
 
       finalize_output(output)
@@ -1564,7 +1601,7 @@ module Howzit
       end
 
       # Run each topic with its specific arguments
-      topic_specs.each do |topic_match, args|
+      topic_specs.each_with_index do |(topic_match, args), idx|
         # Set arguments if provided, otherwise clear them
         Howzit.arguments = if args && !args.empty?
                              args.split(/ *, */).map(&:render_arguments)
@@ -1572,10 +1609,29 @@ module Howzit
                              []
                            end
         output.push(process_topic(topic_match, Howzit.options[:run], single: true))
+        break if stop_after_failure?(topic_specs[(idx + 1)..].map(&:first))
       end
       finalize_output(output)
     end
 
+    ##
+    ## After running a topic in a multi-topic run, check whether a task
+    ## failed. If so (and --force isn't set), log the remaining topics'
+    ## tasks as skipped.
+    ##
+    ## @param      remaining  [Array] Topics that haven't run yet
+    ##
+    ## @return     [Boolean] true if the run should stop
+    ##
+    def stop_after_failure?(remaining)
+      return false unless Howzit.options[:run]
+      return false if Howzit.options[:force]
+      return false unless Howzit.run_log.any? { |entry| !entry[:success] && !entry[:skipped] }
+
+      remaining.each { |topic| topic.log_skipped_tasks(topic.all_tasks) }
+      true
+    end
+
     ##
     ## Parse default metadata value into individual topic specifications
     ##

data/lib/howzit/run_report.rb

@@ -26,8 +26,20 @@ module Howzit
       output_lines.join("\n")
     end
 
+    def status_symbol(entry)
+      return '⏭️' if entry[:skipped]
+
+      entry[:success] ? '✅' : '❌'
+    end
+
+    def status_reason(entry)
+      return 'skipped' if entry[:skipped]
+
+      entry[:exit_status] ? "exit code #{entry[:exit_status]}" : 'failed'
+    end
+
     def format_line(entry, prefix_topic)
-      symbol = entry[:success] ? '✅' : '❌'
+      symbol = status_symbol(entry)
       parts = ["#{symbol} "]
       if prefix_topic && entry[:topic] && !entry[:topic].empty?
         # Escape braces and dollar signs in topic name to prevent color code interpretation
@@ -36,10 +48,11 @@ module Howzit
       end
       # Escape braces and dollar signs in task name to prevent color code interpretation
       task_escaped = entry[:task].gsub(/\{/, '\\{').gsub(/\}/, '\\}').gsub(/\$/, '\\$')
-      parts << "{by}#{task_escaped} {x}"
-      unless entry[:success]
-        reason = entry[:exit_status] ? "exit code #{entry[:exit_status]}" : 'failed'
-        parts << " {br}(#{reason}){x}"
+      if entry[:skipped]
+        parts << "{d}#{task_escaped} (skipped){x}"
+      else
+        parts << "{by}#{task_escaped} {x}"
+        parts << " {br}(#{status_reason(entry)}){x}" unless entry[:success]
       end
       parts.join.c
     end
@@ -76,7 +89,7 @@ module Howzit
     def format_row(entry, prefix_topic)
       # Use plain emoji without color codes - the emoji itself provides visual meaning
       # and complex ANSI codes interfere with mdless table rendering
-      symbol = entry[:success] ? '✅' : '❌'
+      symbol = status_symbol(entry)
 
       task_parts = []
       task_parts_plain = []
@@ -94,7 +107,7 @@ module Howzit
       task_parts_plain << entry[:task]
 
       unless entry[:success]
-        reason = entry[:exit_status] ? "exit code #{entry[:exit_status]}" : 'failed'
+        reason = status_reason(entry)
         task_parts << " {br}(#{reason}){x}"
         task_parts_plain << " (#{reason})"
       end

data/lib/howzit/task.rb

@@ -5,7 +5,8 @@ require 'English'
 module Howzit
   # Task object
   class Task
-    attr_reader :type, :title, :action, :arguments, :parent, :optional, :default, :last_status, :log_level, :source_file
+    attr_reader :type, :title, :action, :arguments, :parent, :optional, :default, :last_status, :log_level, :source_file,
+                :include_results
 
     ##
     ## Initialize a Task object
@@ -141,7 +142,7 @@ module Howzit
     ##
     ## Execute an include task
     ##
-    ## @return     [Array] [[Array] output, [Integer] number of tasks executed]
+    ## @return     [Array] [[Array] output, [Integer] number of tasks executed, [Boolean] all tasks succeeded]
     ##
     def run_include
       output = []
@@ -150,11 +151,13 @@ module Howzit
       matches = Howzit.buildnote.find_topic(action)
       raise "Topic not found: #{action}" if matches.empty?
 
-      Howzit.console.info("#{@prefix}{by}Running tasks from {bw}#{matches[0].title}{x}".c)
-      output.concat(matches[0].run(nested: true))
-      Howzit.console.info("{by}End include: #{matches[0].tasks.count} tasks{x}".c)
+      topic = matches[0]
+      Howzit.console.info("#{@prefix}{by}Running tasks from {bw}#{topic.title}{x}".c)
+      output.concat(topic.run(nested: true))
+      Howzit.console.info("{by}End include: #{topic.all_tasks.count} tasks{x}".c)
       @last_status = nil
-      [output, matches[0].tasks.count]
+      @include_results = topic.results.slice(:total, :success, :errors)
+      [output, @include_results[:total], @include_results[:errors].zero?]
     end
 
     ##
@@ -287,7 +290,8 @@ module Howzit
             else
               case @type
               when :include
-                output, tasks = run_include
+                output, tasks, include_success = run_include
+                include_success
               when :run
                 run_run
               when :copy

data/lib/howzit/topic.rb

@@ -5,9 +5,10 @@ module Howzit
   class Topic
     attr_writer :parent
 
-    attr_accessor :content
+    attr_accessor :content, :parent_topic
 
-    attr_reader :title, :tasks, :prereqs, :postreqs, :results, :named_args, :directives, :arg_definitions, :source_file
+    attr_reader :title, :tasks, :prereqs, :postreqs, :results, :named_args, :directives, :arg_definitions, :source_file,
+                :level, :subtopics
 
     ##
     ## Initialize a topic object
@@ -16,11 +17,15 @@ module Howzit
     ## @param      content     [String] The raw topic content
     ## @param      metadata    [Hash] Optional metadata hash
     ## @param      source_file [String] Optional path to the build note file this topic came from
+    ## @param      level       [Integer] Markdown header level (2 for ##, 3 for ###, etc.)
     ##
-    def initialize(title, content, metadata = nil, source_file: nil)
+    def initialize(title, content, metadata = nil, source_file: nil, level: 2)
       @title = title
       @content = content
       @parent = nil
+      @parent_topic = nil
+      @subtopics = []
+      @level = level
       @nest_level = 0
       @named_args = {}
       @metadata = metadata
@@ -32,6 +37,40 @@ module Howzit
       @results = { total: 0, success: 0, errors: 0, message: ''.c }
     end
 
+    ##
+    ## Nest a topic under this one (a deeper header following this topic)
+    ##
+    ## @param      topic  [Topic] The subtopic
+    ##
+    def add_subtopic(topic)
+      topic.parent_topic = self
+      @subtopics << topic
+    end
+
+    ##
+    ## Tasks from this topic and all nested subtopics, in run order
+    ##
+    ## @return     [Array] Array of Task objects
+    ##
+    def all_tasks
+      @tasks + @subtopics.flat_map(&:all_tasks)
+    end
+
+    ##
+    ## Parent topics from nearest to outermost
+    ##
+    ## @return     [Array] Array of Topic objects
+    ##
+    def ancestors
+      list = []
+      node = @parent_topic
+      while node
+        list << node
+        node = node.parent_topic
+      end
+      list
+    end
+
     # Get named arguments from title
     # from_cli_snapshot: use Howzit.cli_topic_positional_args (argv after `--`) so earlier
     # topics' gather_tasks cannot clobber positional binding. Re-entrant @include [a,b]
@@ -80,7 +119,7 @@ module Howzit
 
     def ask_task(task)
       note = if task.type == :include
-               task_count = Howzit.buildnote.find_topic(task.action)[0].tasks.count
+               task_count = Howzit.buildnote.find_topic(task.action)[0].all_tasks.count
                " (#{task_count} tasks)"
              else
                ''
@@ -95,80 +134,172 @@ module Howzit
       60
     end
 
-    # Handle run command, execute directives in topic
-    def run(nested: false)
+    ##
+    ## Handle run command, execute directives in topic, then in each subtopic
+    ##
+    ## @param      nested       [Boolean] Suppress the summary message (topic is being included)
+    ## @param      as_subtopic  [Boolean] Topic is being run as part of a parent topic
+    ##
+    ## @return     [Array] output lines
+    ##
+    def run(nested: false, as_subtopic: false)
+      @results = { total: 0, success: 0, errors: 0, message: ''.c }
       output = []
-
       cols = check_cols
 
-      # Use sequential processing if we have directives with conditionals
-      if @directives && @directives.any?(&:conditional?)
-        return run_sequential(nested: nested, output: output, cols: cols)
+      confirm_prereqs(cols) if !@prereqs.empty? && (all_tasks.any? || sequential?)
+
+      if sequential?
+        run_sequential(output: output)
+      elsif @tasks.any?
+        run_tasks(output)
+      elsif all_tasks.empty? && !as_subtopic && !directives?
+        Howzit.console.warn "{r}--run: No {br}@directive{xr} found in {bw}#{@title}{x}".c
       end
 
-      # Fall back to old behavior for backward compatibility
-      # Note: @set_var directives are already processed in gather_tasks for non-sequential path
-      # This section is kept for backward compatibility but shouldn't be needed
+      if halted?
+        log_skipped_tasks(@subtopics.flat_map(&:all_tasks))
+      else
+        run_subtopics(output)
+      end
 
-      if @tasks.count.positive?
-        unless @prereqs.empty?
-          begin
-            puts TTY::Box.frame("{by}#{@prereqs.join("\n\n").wrap(cols - 4)}{x}".c, width: cols)
-          rescue Errno::EPIPE
-            # Pipe closed, ignore
-          end
-          res = Prompt.yn('Have the above prerequisites been met?', default: true)
-          Process.exit 1 unless res
+      if @results[:total].positive? || (all_tasks.any? && !sequential?)
+        @results[:message] += results_message
+        output.push(@results[:message]) if Howzit.options[:log_level] < 2 && !nested && !Howzit.options[:run]
+      end
 
-        end
+      show_postreqs(cols)
 
-        @tasks.each do |task|
-          next if (task.optional || Howzit.options[:ask]) && !ask_task(task)
+      output
+    end
 
-          run_output, total, success = task.run
+    ##
+    ## Whether the topic contains conditional directives and must be run sequentially
+    ##
+    def sequential?
+      @directives&.any?(&:conditional?) || false
+    end
 
-          output.concat(run_output)
-          @results[:total] += total
+    ##
+    ## Whether this topic or any subtopic contains directives,
+    ## including non-task directives like @set_var and @log_level
+    ##
+    def directives?
+      @directives&.any? || @subtopics.any?(&:directives?)
+    end
 
-          if success
-            @results[:success] += total
-          else
-            Howzit.console.warn %({bw}\u{2297} {br}Error running task {bw}"#{task.title}"{x}).c
+    def halted?
+      @results[:errors].positive? && !Howzit.options[:force]
+    end
 
-            @results[:errors] += total
+    def confirm_prereqs(cols)
+      begin
+        puts TTY::Box.frame("{by}#{@prereqs.join("\n\n").wrap(cols - 4)}{x}".c, width: cols)
+      rescue Errno::EPIPE
+        # Pipe closed, ignore
+      end
+      res = Prompt.yn('Have the above prerequisites been met?', default: true)
+      Process.exit 1 unless res
+    end
 
-            break unless Howzit.options[:force]
-          end
+    def show_postreqs(cols)
+      return if @postreqs.empty?
 
-          log_task_result(task, success)
-        end
+      # Apply variable substitution to postreqs content, then wrap each line individually to preserve structure
+      postreqs_content = @postreqs.join("\n\n").render_arguments
+      wrapped_content = postreqs_content.split(/\n/).map { |line| line.wrap(cols - 4) }.join("\n")
+      puts TTY::Box.frame("{bw}#{wrapped_content}{x}".c, width: cols)
+    rescue Errno::EPIPE
+      # Pipe closed, ignore
+    end
 
-        total = "{bw}#{@results[:total]}{by} #{@results[:total] == 1 ? 'task' : 'tasks'}".c
-        errors = "{bw}#{@results[:errors]}{by} #{@results[:errors] == 1 ? 'error' : 'errors'}".c
-        @results[:message] += if @results[:errors].zero?
-                                "{bg}\u{2713} {by}Ran #{total}{x}".c
-                              elsif Howzit.options[:force]
-                                "{br}\u{2715} {by}Completed #{total} with #{errors}{x}".c
-                              else
-                                "{br}\u{2715} {by}Ran #{total}, terminated due to error{x}".c
-                              end
+    def results_message
+      total = "{bw}#{@results[:total]}{by} #{@results[:total] == 1 ? 'task' : 'tasks'}".c
+      errors = "{bw}#{@results[:errors]}{by} #{@results[:errors] == 1 ? 'error' : 'errors'}".c
+      if @results[:errors].zero?
+        "{bg}\u{2713} {by}Ran #{total}{x}".c
+      elsif Howzit.options[:force]
+        "{br}\u{2715} {by}Completed #{total} with #{errors}{x}".c
       else
-        Howzit.console.warn "{r}--run: No {br}@directive{xr} found in {bw}#{@title}{x}".c
+        "{br}\u{2715} {by}Ran #{total}, terminated due to error{x}".c
+      end
+    end
+
+    ##
+    ## Run tasks without conditional evaluation
+    ##
+    def run_tasks(output)
+      @tasks.each_with_index do |task, idx|
+        next if (task.optional || Howzit.options[:ask]) && !ask_task(task)
+
+        run_output, total, success = task.run
+
+        output.concat(run_output)
+        record_task_result(task, total, success)
+        next unless halted?
+
+        log_skipped_tasks(@tasks[(idx + 1)..])
+        break
+      end
+      output
+    end
+
+    ##
+    ## Add a task's results to the topic totals and the run report
+    ##
+    ## @param      task     [Task] The task that ran
+    ## @param      total    [Integer] Number of tasks it represents
+    ## @param      success  [Boolean] Whether it succeeded
+    ##
+    def record_task_result(task, total, success)
+      if task.type == :include && task.include_results
+        %i[total success errors].each { |key| @results[key] += task.include_results[key] }
+      else
+        @results[:total] += total
+        @results[success ? :success : :errors] += total
       end
 
-      output.push(@results[:message]) if Howzit.options[:log_level] < 2 && !nested && !Howzit.options[:run]
+      log_task_result(task, success)
+      Howzit.console.warn %({bw}\u{2297} {br}Error running task {bw}"#{task.title}"{x}).c unless success
+    end
+
+    ##
+    ## Log tasks that won't run because an earlier task failed.
+    ## Include tasks are expanded to the tasks of the included topic.
+    ##
+    ## @param      tasks  [Array] Task objects
+    ## @param      seen   [Array] Titles of included topics already expanded
+    ##
+    def log_skipped_tasks(tasks, seen = [])
+      return unless Howzit.options[:run]
 
-      unless @postreqs.empty?
-        begin
-          # Apply variable substitution to postreqs content, then wrap each line individually to preserve structure
-          postreqs_content = @postreqs.join("\n\n").render_arguments
-          wrapped_content = postreqs_content.split(/\n/).map { |line| line.wrap(cols - 4) }.join("\n")
-          puts TTY::Box.frame("{bw}#{wrapped_content}{x}".c, width: cols)
-        rescue Errno::EPIPE
-          # Pipe closed, ignore
+      Howzit.run_log ||= []
+      tasks.each do |task|
+        if task.type == :include
+          topic = Howzit.buildnote.find_topic(task.action)[0]
+          next if topic.nil? || seen.include?(topic.title)
+
+          topic.log_skipped_tasks(topic.all_tasks, seen + [topic.title])
+          next
         end
+
+        topic_title = task.parent.is_a?(Topic) ? task.parent.title : @title
+        Howzit.run_log << { topic: topic_title, task: task_log_title(task), success: false, skipped: true }
       end
+    end
 
+    ##
+    ## Run each subtopic in order, adding its results to this topic's
+    ##
+    def run_subtopics(output)
+      @subtopics.each_with_index do |sub, idx|
+        output.concat(sub.run(nested: true, as_subtopic: true))
+        %i[total success errors].each { |key| @results[key] += sub.results[key] }
+        next unless halted?
+
+        log_skipped_tasks(@subtopics[(idx + 1)..].flat_map(&:all_tasks))
+        break
+      end
       output
     end
 
@@ -178,7 +309,7 @@ module Howzit
     end
 
     def colored_option(color, topic, keys)
-      if topic.tasks.empty?
+      if topic.all_tasks.empty?
         ''
       else
         optional = keys[:optional] =~ /[?!]+/ ? true : false
@@ -302,7 +433,8 @@ module Howzit
           formatted_args = @arg_definitions.map { |arg| format_arg_definition(arg) }.join('{l}, '.c)
           header_title += " {l}({x}#{formatted_args}{l}){x}".c
         end
-        output.push(header_title.format_header)
+        header_opts = opt[:subtopic] ? { color: '{bc}', hr: "\u{2508}" } : {}
+        output.push(header_title.format_header(header_opts))
         output.push('')
       end
       # Process conditional blocks first
@@ -333,6 +465,8 @@ module Howzit
       end
       Howzit.named_arguments = @named_args
       output.push('')
+      @subtopics.each { |sub| output.concat(sub.print_out(opt.merge(header: true, subtopic: true))) }
+      output
     end
 
     ##
@@ -447,22 +581,20 @@ module Howzit
       return if task.type == :include
 
       Howzit.run_log ||= []
-
-      title = (task.title || '').strip
-      if title.empty?
-        action = (task.action || '').strip
-        title = action.split(/\n/).first.to_s.strip
-      end
-      title = task.type.to_s.capitalize if title.nil? || title.empty?
-
       Howzit.run_log << {
         topic: @title,
-        task: title,
+        task: task_log_title(task),
         success: success ? true : false,
         exit_status: task.last_status
       }
     end
 
+    def task_log_title(task)
+      title = (task.title || '').strip
+      title = (task.action || '').strip.split(/\n/).first.to_s.strip if title.empty?
+      title.empty? ? task.type.to_s.capitalize : title
+    end
+
     def gather_tasks
       runnable = []
       # Process conditional blocks first
@@ -727,7 +859,7 @@ module Howzit
     ##
     ## Run directives sequentially with conditional re-evaluation
     ##
-    def run_sequential(nested: false, output: [], cols: 80)
+    def run_sequential(output: [])
       # Initialize conditional state
       conditional_state = {} # { index => { evaluated: bool, result: bool, matched_chain: bool } }
       directive_index = 0
@@ -737,16 +869,6 @@ module Howzit
       Howzit.named_arguments ||= {}
       Howzit.named_arguments.merge!(@named_args) if @named_args
 
-      unless @prereqs.empty?
-        begin
-          puts TTY::Box.frame("{by}#{@prereqs.join("\n\n").wrap(cols - 4)}{x}".c, width: cols)
-        rescue Errno::EPIPE
-          # Pipe closed, ignore
-        end
-        res = Prompt.yn('Have the above prerequisites been met?', default: true)
-        Process.exit 1 unless res
-      end
-
       # Process directives sequentially
       while directive_index < @directives.length
         directive = @directives[directive_index]
@@ -887,48 +1009,18 @@ module Howzit
         run_output, total, success = task.run
 
         output.concat(run_output)
-        @results[:total] += total
-
-        if success
-          @results[:success] += total
-        else
-          Howzit.console.warn %({bw}\u{2297} {br}Error running task {bw}"#{task.title}"{x}).c
-
-          @results[:errors] += total
-
-          break unless Howzit.options[:force]
+        record_task_result(task, total, success)
+        if halted?
+          # Tasks inside conditionals are omitted, since their conditions were never evaluated
+          remaining = @directives[directive_index..].select { |d| d.task? && (d.conditional_path || []).empty? }
+          log_skipped_tasks(remaining.filter_map { |d| d.to_task(self) })
+          break
         end
 
-        log_task_result(task, success)
-
         # Re-evaluate all open conditionals after task execution
         re_evaluate_conditionals(conditional_state, directive_index - 1, context)
       end
 
-      if @results[:total].positive?
-        total = "{bw}#{@results[:total]}{by} #{@results[:total] == 1 ? 'task' : 'tasks'}".c
-        errors = "{bw}#{@results[:errors]}{by} #{@results[:errors] == 1 ? 'error' : 'errors'}".c
-        @results[:message] += if @results[:errors].zero?
-                                "{bg}\u{2713} {by}Ran #{total}{x}".c
-                              elsif Howzit.options[:force]
-                                "{br}\u{2715} {by}Completed #{total} with #{errors}{x}".c
-                              else
-                                "{br}\u{2715} {by}Ran #{total}, terminated due to error{x}".c
-                              end
-        output.push(@results[:message]) if Howzit.options[:log_level] < 2 && !nested && !Howzit.options[:run]
-      end
-
-      unless @postreqs.empty?
-        begin
-          # Apply variable substitution to postreqs content, then wrap each line individually to preserve structure
-          postreqs_content = @postreqs.join("\n\n").render_arguments
-          wrapped_content = postreqs_content.split(/\n/).map { |line| line.wrap(cols - 4) }.join("\n")
-          puts TTY::Box.frame("{bw}#{wrapped_content}{x}".c, width: cols)
-        rescue Errno::EPIPE
-          # Pipe closed, ignore
-        end
-      end
-
       output
     end
 

data/lib/howzit/version.rb

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

data/nested-topics-for-howzit.md

@@ -0,0 +1,100 @@
+---
+title: Nested topics for Howzit
+layout: post
+tags: [howzit, ruby, markdown, cli, automation]
+categories: [Blog,Code]
+post_class: 'code'
+comments: true
+---
+[Howzit](https://github.com/ttscoff/howzit) has always split build notes into topics using Markdown headers. What it didn't do was care *which* header level you used. An `##` and a `###` were both just "a topic," and they all got flattened into one long list. As of version 2.1.44, that's changed: deeper headers now nest under the header above them, and that nesting affects both how notes display and what happens when you run them.
+
+### The short version
+
+A `###` following a `##` is now a subtopic of that `##`. A `####` under the `###` is a subtopic of the `###`, and so on down. The next header at the same level (or shallower) closes out the parent.
+
+```markdown
+## Deploy
+
+@run(./scripts/preflight.sh) Preflight checks
+
+### Build assets
+
+@run(gulp) Build
+
+### Upload
+
+@run(gulp sync) Sync to server
+
+## Package management
+```
+
+Here "Build assets" and "Upload" belong to "Deploy." "Package management" is back at the top level.
+
+### Viewing a parent topic
+
+When you pull up a parent topic, you now get the whole thing: the parent, followed by all of its subtopics.
+
+```console
+$ howzit deploy
+```
+
+Subtopic headers get a slightly lighter treatment (a dotted rule and a cyan title) so you can see where the nesting happens without it getting noisy. You can still ask for a subtopic directly:
+
+```console
+$ howzit upload
+```
+
+...and you'll get just that section.
+
+### Running a parent topic
+
+This is the part I actually wanted. Running a parent now runs everything under it:
+
+```console
+$ howzit -r deploy
+```
+
+That runs Deploy's own tasks first, then each subtopic's tasks in order, depth-first. So the example above runs preflight, then the build, then the sync. You get one combined summary at the end instead of a "Ran 1 task" line for every section.
+
+A few details worth knowing:
+
+- **Errors stop the run.** If a task fails, the remaining subtopics are skipped. Add `--force` if you want it to push through anyway.
+- **`@before` and `@after` still work per topic.** Each topic shows its prerequisites before its own tasks run. A parent's `@after` block shows up once the parent *and* all of its subtopics are done, which is usually where you want that "don't forget to..." reminder.
+- **Parents don't need tasks of their own.** A parent that's just an umbrella for a few subtopics runs fine, and it won't complain about "No @directive found."
+- **Subtopics still run on their own.** `howzit -r upload` runs just the upload step.
+
+### Includes get the whole tree too
+
+If another topic does `@include(Deploy)`, it now runs Deploy and all of its subtopics, same as running it directly. Task counts in include notes and menus reflect the full tree, so you're not surprised by how much is about to happen.
+
+### Listing and "show everything"
+
+Running `howzit` with no arguments shows every topic. It now only prints top-level topics, since subtopics come along with their parents. No more seeing the same section twice.
+
+`howzit -l` indents subtopics under their parents, so the list reflects the structure of your note:
+
+```console
+$ howzit -l
+Topics:
+
+- Deploy
+  - Build assets
+  - Upload
+- Package management
+```
+
+Shell completions stay flat, so you can still tab-complete straight to a subtopic.
+
+### One thing to check in your notes
+
+If you've been using `###` headers under `##` purely as visual formatting, those are now real subtopics. Viewing the parent will include them (probably what you wanted anyway), and running the parent will run their tasks too. If you had a `###` section with tasks you *don't* want run as part of its parent, bump it up to `##`.
+
+### Grab it
+
+It's in 2.1.44:
+
+```console
+$ gem install howzit
+```
+
+The details are in the [build notes anatomy page](https://github.com/ttscoff/howzit/wiki/Anatomy-of-a-build-notes-file#subtopics) on the wiki. I've already started restructuring a few of my own notes around this. Having a single "Release" topic that fans out into build, test, and publish steps is a lot nicer than keeping them all at the same level and chaining them together with `@include`.

data/spec/run_report_accuracy_spec.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'fileutils'
+require 'tmpdir'
+
+describe 'run report accuracy' do
+  let(:temp_dir) { File.expand_path(Dir.mktmpdir('howzit_run_report_test')) }
+  let(:buildnote) { Howzit::BuildNote.new }
+
+  before do
+    File.write(
+      File.join(temp_dir, 'buildnotes.md'),
+      <<~NOTE
+        # Run Report Project
+
+        ## Failing
+
+        @run(true) First
+        @run(false) Second
+        @run(true) Third
+
+        ## Release
+
+        @include(Failing)
+        @run(true) After include
+
+        ## Early Failure
+
+        @run(false) Fails first
+        @include(Failing)
+
+        ## Conditional
+
+        @if 1 == 1
+        @run(false) Conditional failure
+        @run(true) Conditional after
+        @end
+        @run(true) Unconditional after
+
+        ## Parent
+
+        @run(true) Parent task
+
+        ### Broken Child
+
+        @run(false) Child failure
+        @run(true) Child after
+
+        ### Later Child
+
+        @run(true) Later child task
+      NOTE
+    )
+
+    Dir.chdir(temp_dir)
+    Howzit.instance_variable_set(:@buildnote, buildnote)
+    Howzit.options[:stack] = false
+    Howzit.options[:include_upstream] = false
+    Howzit.options[:run] = true
+    Howzit.options[:force] = false
+    Howzit.run_log = []
+  end
+
+  after do
+    Howzit.options[:run] = false
+    Howzit.options[:force] = false
+    Howzit.run_log = []
+    Dir.chdir(Dir.tmpdir)
+    FileUtils.rm_rf(temp_dir) if Dir.exist?(temp_dir)
+    Howzit.instance_variable_set(:@buildnote, nil)
+  end
+
+  def report
+    Howzit.run_log.map do |entry|
+      status = if entry[:skipped]
+                 :skipped
+               else
+                 entry[:success] ? :ok : :failed
+               end
+      [entry[:task], status]
+    end
+  end
+
+  it 'logs the failed task and marks the rest as skipped' do
+    buildnote.find_topic('Failing')[0].run
+
+    expect(report).to eq([['First', :ok], ['Second', :failed], ['Third', :skipped]])
+    expect(Howzit.run_log[1][:exit_status]).to eq(1)
+  end
+
+  it 'treats a failed include as a failure and skips the rest of the including topic' do
+    topic = buildnote.find_topic('Release')[0]
+    topic.run
+
+    expect(report).to eq([['First', :ok], ['Second', :failed], ['Third', :skipped], ['After include', :skipped]])
+    expect(topic.results).to include(total: 2, success: 1, errors: 1)
+  end
+
+  it 'expands skipped includes into the included topic tasks' do
+    buildnote.find_topic('Early Failure')[0].run
+
+    expect(report).to eq([['Fails first', :failed], ['First', :skipped], ['Second', :skipped], ['Third', :skipped]])
+    expect(Howzit.run_log[1][:topic]).to eq('Failing')
+  end
+
+  it 'skips only unconditional tasks after a failure in a conditional topic' do
+    buildnote.find_topic('Conditional')[0].run
+
+    expect(report).to eq([['Conditional failure', :failed], ['Unconditional after', :skipped]])
+  end
+
+  it 'skips remaining subtopics after a subtopic fails' do
+    buildnote.find_topic('Parent')[0].run
+
+    expect(report).to eq([
+                           ['Parent task', :ok],
+                           ['Child failure', :failed],
+                           ['Child after', :skipped],
+                           ['Later child task', :skipped]
+                         ])
+    expect(Howzit.run_log.last[:topic]).to eq('Later Child')
+  end
+
+  it 'continues past failures with --force and logs every result' do
+    Howzit.options[:force] = true
+    topic = buildnote.find_topic('Release')[0]
+    topic.run
+
+    expect(report).to eq([['First', :ok], ['Second', :failed], ['Third', :ok], ['After include', :ok]])
+    expect(topic.results).to include(total: 4, success: 3, errors: 1)
+  end
+
+  describe 'multi-topic runs' do
+    before do
+      allow(buildnote).to receive(:finalize_output)
+    end
+
+    let(:topics) { ['Failing', 'Parent'].map { |title| buildnote.find_topic(title)[0] } }
+
+    it 'stops after a topic fails and skips the remaining topics' do
+      buildnote.send(:process_topic_matches, topics, [])
+
+      expect(report).to eq([
+                             ['First', :ok],
+                             ['Second', :failed],
+                             ['Third', :skipped],
+                             ['Parent task', :skipped],
+                             ['Child failure', :skipped],
+                             ['Child after', :skipped],
+                             ['Later child task', :skipped]
+                           ])
+    end
+
+    it 'runs every topic with --force' do
+      Howzit.options[:force] = true
+      buildnote.send(:process_topic_matches, topics, [])
+
+      expect(report.map(&:first)).to include('Parent task', 'Later child task')
+      expect(report.map(&:last)).not_to include(:skipped)
+    end
+  end
+
+  it 'formats skipped tasks in the report' do
+    buildnote.find_topic('Failing')[0].run
+    plain = Howzit::RunReport.format.uncolor
+
+    expect(plain).to include('❌ Second  (exit code 1)')
+    expect(plain).to include('⏭️ Third (skipped)')
+  end
+end

data/spec/subtopics_spec.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'fileutils'
+require 'tmpdir'
+
+describe 'subtopics' do
+  let(:temp_dir) { File.expand_path(Dir.mktmpdir('howzit_subtopics_test')) }
+  let(:buildnote) { Howzit::BuildNote.new }
+  let(:parent) { buildnote.find_topic('Parent')[0] }
+
+  before do
+    File.write(
+      File.join(temp_dir, 'buildnotes.md'),
+      <<~NOTE
+        # Subtopic Project
+
+        ## Parent
+
+        Parent content
+
+        @run(echo parent) Parent task
+
+        ### Child One
+
+        @run(echo child1) Child one task
+
+        #### Grandchild
+
+        @run(echo grand) Grandchild task
+
+        ### Child Two
+
+        @run(echo child2) Child two task
+
+        ## Sibling
+
+        @run(echo sibling) Sibling task
+      NOTE
+    )
+
+    Dir.chdir(temp_dir)
+    Howzit.instance_variable_set(:@buildnote, nil)
+    Howzit.options[:stack] = false
+    Howzit.options[:include_upstream] = false
+  end
+
+  after do
+    Dir.chdir(Dir.tmpdir)
+    FileUtils.rm_rf(temp_dir) if Dir.exist?(temp_dir)
+    Howzit.instance_variable_set(:@buildnote, nil)
+  end
+
+  def topic_named(title)
+    buildnote.topics.find { |t| t.title == title }
+  end
+
+  it 'nests deeper headers under the preceding shallower header' do
+    expect(parent.subtopics.map(&:title)).to eq(['Child One', 'Child Two'])
+    expect(topic_named('Child One').subtopics.map(&:title)).to eq(['Grandchild'])
+    expect(topic_named('Grandchild').ancestors.map(&:title)).to eq(['Child One', 'Parent'])
+    expect(topic_named('Sibling').parent_topic).to be_nil
+  end
+
+  it 'keeps subtopics selectable on their own' do
+    expect(buildnote.find_topic('Child Two')[0].title).to eq('Child Two')
+  end
+
+  it 'collects tasks from subtopics in order' do
+    expect(parent.all_tasks.map(&:title)).to eq(['Parent task', 'Child one task', 'Grandchild task', 'Child two task'])
+  end
+
+  it 'displays subtopics with the parent topic' do
+    output = parent.print_out.join("\n").uncolor
+
+    expect(output).to include('Parent content')
+    expect(output).to include('Child One')
+    expect(output).to include('Grandchild')
+    expect(output).to include('echo child2')
+    expect(output).not_to include('Sibling')
+  end
+
+  it 'only outputs top-level topics when showing all topics' do
+    expect(buildnote.top_level_topics.map(&:title)).to eq(%w[Parent Sibling])
+  end
+
+  it 'indents subtopics in the topic list' do
+    list = buildnote.list.uncolor
+
+    expect(list).to include("\n- Parent")
+    expect(list).to include("\n  - Child One")
+    expect(list).to include("\n    - Grandchild")
+  end
+
+  describe 'running a parent topic' do
+    let(:ran) { [] }
+
+    it 'runs its own tasks followed by all subtopic tasks' do
+      ran_titles = ran
+      allow_any_instance_of(Howzit::Task).to receive(:run) do |task|
+        ran_titles << task.title
+        [[], 1, true]
+      end
+
+      parent.run
+
+      expect(ran).to eq(['Parent task', 'Child one task', 'Grandchild task', 'Child two task'])
+      expect(parent.results[:total]).to eq(4)
+    end
+
+    it 'stops running subtopics after an error' do
+      ran_titles = ran
+      allow_any_instance_of(Howzit::Task).to receive(:run) do |task|
+        ran_titles << task.title
+        [[], 1, task.title != 'Child one task']
+      end
+
+      parent.run
+
+      expect(ran).to eq(['Parent task', 'Child one task'])
+      expect(parent.results[:errors]).to eq(1)
+    end
+
+    it 'continues past errors with --force' do
+      Howzit.options[:force] = true
+      ran_titles = ran
+      allow_any_instance_of(Howzit::Task).to receive(:run) do |task|
+        ran_titles << task.title
+        [[], 1, task.title != 'Child one task']
+      end
+
+      parent.run
+
+      expect(ran).to eq(['Parent task', 'Child one task', 'Grandchild task', 'Child two task'])
+    ensure
+      Howzit.options[:force] = false
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.1.42
+  version: 2.1.45
 platform: ruby
 authors:
 - Brett Terpstra
@@ -13,14 +13,14 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.2'
 - !ruby/object:Gem::Dependency
@@ -314,6 +314,7 @@ files:
 - lib/howzit/topic.rb
 - lib/howzit/util.rb
 - lib/howzit/version.rb
+- nested-topics-for-howzit.md
 - scripts/runtests.sh
 - spec/buildnote_spec.rb
 - spec/cli_spec.rb
@@ -324,6 +325,7 @@ files:
 - spec/log_level_spec.rb
 - spec/prompt_spec.rb
 - spec/ruby_gem_spec.rb
+- spec/run_report_accuracy_spec.rb
 - spec/run_report_spec.rb
 - spec/script_comm_spec.rb
 - spec/sequential_conditional_spec.rb
@@ -331,6 +333,7 @@ files:
 - spec/spec_helper.rb
 - spec/stack_mode_spec.rb
 - spec/stringutils_spec.rb
+- spec/subtopics_spec.rb
 - spec/task_spec.rb
 - spec/topic_positional_snapshot_spec.rb
 - spec/topic_spec.rb
@@ -356,7 +359,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Provides a way to access Markdown project notes by topic with query capabilities
   and the ability to execute the tasks it describes.
@@ -370,6 +373,7 @@ test_files:
 - spec/log_level_spec.rb
 - spec/prompt_spec.rb
 - spec/ruby_gem_spec.rb
+- spec/run_report_accuracy_spec.rb
 - spec/run_report_spec.rb
 - spec/script_comm_spec.rb
 - spec/sequential_conditional_spec.rb
@@ -377,6 +381,7 @@ test_files:
 - spec/spec_helper.rb
 - spec/stack_mode_spec.rb
 - spec/stringutils_spec.rb
+- spec/subtopics_spec.rb
 - spec/task_spec.rb
 - spec/topic_positional_snapshot_spec.rb
 - spec/topic_spec.rb