howzit 2.1.42 → 2.1.44

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8916b2ac37cd920db8008fe7a9aa28a80b4c5265083b4b257fb8ea1113938efb
-  data.tar.gz: 9486d6ca52f82ea5059bffd0de58333b82eedfc623d03f6325817caf8c956d4f
+  metadata.gz: 881188642b99f4be83a7697440251ec8890e6d847468c3984a72183939196857
+  data.tar.gz: c622b23318a075aa277a0a197e1ec93d8023e52e99018557e7eb6f8309c76927
 SHA512:
-  metadata.gz: 5819786618c45538e42f21243102043b1ed408f516b0b946adaa9a2819d0080c2804cba47987f4ba0ed98b21ad7499d42cc825c2f89efb63cc4f6d8013bd743d
-  data.tar.gz: 2a90edf5e41602e1c6fc50ab21a6bfc3531b598f3a5cc381492f284bbb588b2590589fbc23da0f007a021605d46f7246e2908eed89895c175c24838b4755b285
+  metadata.gz: 219ae789410d1ec44619f3bfb00b7f8b539a33632e9b9d9e778f384205e03c653efa83a7a090d469dd769a2cdda53ae7026e40b495363879e59f24be38da09ae
+  data.tar.gz: d0c1dd2d03ab11923e93440fb9f04bfdfb0292d63522fd21483a38a7d2ca31c691dc64e4a894063944b586ef1b2af66fd8a4bd55ea132ce743b6e69e7fd812db

data/CHANGELOG.md

@@ -1,3 +1,55 @@
+### 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,12 @@ 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
+        top_level_topics(topic_matches).each do |topic_match|
+          output.push(process_topic(topic_match, Howzit.options[:run], single: true))
+        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)

data/lib/howzit/task.rb

@@ -152,9 +152,9 @@ module Howzit
 
       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)
+      Howzit.console.info("{by}End include: #{matches[0].all_tasks.count} tasks{x}".c)
       @last_status = nil
-      [output, matches[0].tasks.count]
+      [output, matches[0].all_tasks.count]
     end
 
     ##

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,129 @@ 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
+      run_subtopics(output) unless halted?
 
-      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 do |task|
+        next if (task.optional || Howzit.options[:ask]) && !ask_task(task)
 
-      output.push(@results[:message]) if Howzit.options[:log_level] < 2 && !nested && !Howzit.options[:run]
+        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
 
-      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
+          @results[:errors] += total
+
+          break unless Howzit.options[:force]
         end
+
+        log_task_result(task, success)
       end
+      output
+    end
 
+    ##
+    ## Run each subtopic in order, adding its results to this topic's
+    ##
+    def run_subtopics(output)
+      @subtopics.each do |sub|
+        output.concat(sub.run(nested: true, as_subtopic: true))
+        %i[total success errors].each { |key| @results[key] += sub.results[key] }
+        break if halted?
+      end
       output
     end
 
@@ -178,7 +266,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 +390,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 +422,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
 
     ##
@@ -727,7 +818,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 +828,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]
@@ -905,30 +986,6 @@ module Howzit
         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.44'
 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.44
 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
@@ -331,6 +331,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 +357,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.
@@ -377,6 +378,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