howzit 2.1.44 → 2.1.45

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 881188642b99f4be83a7697440251ec8890e6d847468c3984a72183939196857
-  data.tar.gz: c622b23318a075aa277a0a197e1ec93d8023e52e99018557e7eb6f8309c76927
+  metadata.gz: 3b5d2120c8484147d2d3cb8f8844073ca027e7a54655385749ee721f645d05a5
+  data.tar.gz: 3cef9cda18bf1b43b28d9288e9eda81d30b07fc9ac2505dd932e508240abf86b
 SHA512:
-  metadata.gz: 219ae789410d1ec44619f3bfb00b7f8b539a33632e9b9d9e778f384205e03c653efa83a7a090d469dd769a2cdda53ae7026e40b495363879e59f24be38da09ae
-  data.tar.gz: d0c1dd2d03ab11923e93440fb9f04bfdfb0292d63522fd21483a38a7d2ca31c691dc64e4a894063944b586ef1b2af66fd8a4bd55ea132ce743b6e69e7fd812db
+  metadata.gz: 4dc4af7fce8a375a33a3dfee3ed2e6f9d914ea3069601aa3426ae552f4c5488d5aafa332522c4eef0a6b4318bd63afef20eda2d638e9c6fd09ce9784c5e6a434
+  data.tar.gz: fe60529771944221e4f7acd4bd9883669782f413c5a367ae3c03c8c7d8ce0a0e0413fcf4e086e37584868c58bbea10bb4e24ab49c28583521d901166404146be

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+### 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

data/lib/howzit/buildnote.rb

@@ -1558,8 +1558,10 @@ module Howzit
         end
         topic_matches.compact! # Remove any nil values from failed matches
         # A matched subtopic is already output/run with its matched parent
-        top_level_topics(topic_matches).each do |topic_match|
+        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
         top_level_topics.each { |k| output.push(process_topic(k, false, single: false)) }
@@ -1599,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)
@@ -1607,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].all_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].all_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

@@ -157,7 +157,11 @@ module Howzit
         Howzit.console.warn "{r}--run: No {br}@directive{xr} found in {bw}#{@title}{x}".c
       end
 
-      run_subtopics(output) unless halted?
+      if halted?
+        log_skipped_tasks(@subtopics.flat_map(&:all_tasks))
+      else
+        run_subtopics(output)
+      end
 
       if @results[:total].positive? || (all_tasks.any? && !sequential?)
         @results[:message] += results_message
@@ -225,37 +229,76 @@ module Howzit
     ## Run tasks without conditional evaluation
     ##
     def run_tasks(output)
-      @tasks.each do |task|
+      @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
 
-        if success
-          @results[:success] += total
-        else
-          Howzit.console.warn %({bw}\u{2297} {br}Error running task {bw}"#{task.title}"{x}).c
+      log_task_result(task, success)
+      Howzit.console.warn %({bw}\u{2297} {br}Error running task {bw}"#{task.title}"{x}).c unless success
+    end
 
-          @results[:errors] += total
+    ##
+    ## 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]
 
-          break unless Howzit.options[:force]
+      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
 
-        log_task_result(task, success)
+        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
-      output
     end
 
     ##
     ## Run each subtopic in order, adding its results to this topic's
     ##
     def run_subtopics(output)
-      @subtopics.each do |sub|
+      @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] }
-        break if halted?
+        next unless halted?
+
+        log_skipped_tasks(@subtopics[(idx + 1)..].flat_map(&:all_tasks))
+        break
       end
       output
     end
@@ -538,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
@@ -968,20 +1009,14 @@ 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

data/lib/howzit/version.rb

@@ -3,5 +3,5 @@
 # Primary module for this gem.
 module Howzit
   # Current Howzit version.
-  VERSION = '2.1.44'
+  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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.1.44
+  version: 2.1.45
 platform: ruby
 authors:
 - Brett Terpstra
@@ -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
@@ -371,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