howzit 2.1.46 → 2.1.47

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: daae85713f05d780640619a8ada2291aaa69c0eb3f2d941f6fb9e2964c9247b4
-  data.tar.gz: 5773440b0a9718af5dd0b3e66929bfa74023061b99a85c61d65558b76ac57d4d
+  metadata.gz: 477bc94918f7906d52412423ee73992f2d255279d757f36d0feed85f74c1f454
+  data.tar.gz: 926727bfe69e059367fa75d4b55b095786663487cdc8f311b13ee92dd44d15e0
 SHA512:
-  metadata.gz: 1f688d2e403997a3cf6f3b91c0ebd3746ed51b1d0bc4dfea2be5fd1297a22715d2a7b5672482b2f243dc26b38b56eee2880c9e57df98c55c16178b84eddeb8da
-  data.tar.gz: 934e5ef9e7b71bc0323475ae4c54596d7a6813f552d63fd08dd358f51805c6950780d4435b9cf830aed7712392a5a38d52077dfbcceb69293adf02f9b0970794
+  metadata.gz: 8f4c4228bc522c7608f77d0ab4e7f4f802753e71c7f37d2f41d9f81e01764a8b0b285aaed8bc5bad6a9ccaa0544d83007bde4c7aea7c0e41bc2fc834bb8304d7
+  data.tar.gz: a24505c7b3f22f7d4bb52eb91372f44d0ef200285faf4006bb8a93588bdb63318063d26b5571026374f8f67b648678d0bd4edf4223c5561c39ad625ec2a08a69

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+### 2.1.47
+
+2026-09-27 13:20
+
+#### IMPROVED
+
+- **Included topics** receive their bracketed arguments as positional arguments ($1, $2) in shell run blocks for the duration of the include
+
+#### FIXED
+
+- **default: metadata** now splits topics only on commas outside of brackets, so `default: Build, Deploy[prod, fast], Test` passes both arguments to Deploy
+- **Bracketed arguments in default:** (e.g. `Deploy[prod]`) are now bound to the topic's title parameters, so `${target}` and friends render in @run commands instead of coming out empty
+- **@include bracketed arguments** (e.g. `@include(Deploy [staging])`) now bind to the included topic's parameters, and including the same topic multiple times with different arguments works
+- **Unspecified bracketed arguments** fall back to the topic's parameter defaults
+- **Topics that use @include with arguments** no longer lose their own argument definitions
+
 ### 2.1.46
 
 2026-09-27 12:52

data/lib/howzit/buildnote.rb

@@ -1608,7 +1608,7 @@ module Howzit
                            else
                              []
                            end
-        output.push(process_topic(topic_match, Howzit.options[:run], single: true))
+        output.push(process_topic(topic_match.with_arguments(Howzit.arguments), Howzit.options[:run], single: true))
         break if stop_after_failure?(topic_specs[(idx + 1)..].map(&:first))
       end
       finalize_output(output)
@@ -1640,7 +1640,8 @@ module Howzit
     ## @return     [Array] Array of topic specification strings
     ##
     def parse_default_metadata(default_value)
-      default_value.strip.split(/\s*,\s*/).map(&:strip).reject(&:empty?)
+      # Commas inside [bracketed arguments] separate arguments, not topics
+      default_value.strip.split(/\s*,\s*(?![^\[]*\])/).map(&:strip).reject(&:empty?)
     end
 
     ##

data/lib/howzit/directive.rb

@@ -138,7 +138,7 @@ module Howzit
         if title =~ /\[(.*?)\] *$/
           args = Regexp.last_match(1).split(/ *, */).map(&:render_arguments)
           Howzit.arguments = args
-          parent.arguments
+          task_data[:include_args] = args
           title.sub!(/ *\[.*?\] *$/, '')
         end
         title = title.render_arguments if title && !title.empty?

data/lib/howzit/task.rb

@@ -27,6 +27,7 @@ module Howzit
       @prefix = "{bw}\u{25B7}\u{25B7} {x}"
       # arrow = "{bw}\u{279F}{x}"
       @arguments = attributes[:arguments] || []
+      @include_args = attributes[:include_args]
 
       @type = attributes[:type] || :run
       @title = attributes[:title]&.to_s
@@ -171,18 +172,35 @@ module Howzit
       output = []
       action = @action
 
-      matches = Howzit.buildnote.find_topic(action)
+      matches = Howzit.buildnote.find_topic(action.sub(/ *\[.*?\] *$/, ''))
       raise "Topic not found: #{action}" if matches.empty?
 
-      topic = matches[0]
+      topic = matches[0].with_arguments(@include_args)
       Howzit.console.info("#{@prefix}{by}Running tasks from {bw}#{topic.title}{x}".c)
-      output.concat(topic.run(nested: true))
+      output.concat(with_positional_arguments(@include_args) { topic.run(nested: true) })
       Howzit.console.info("{by}End include: #{topic.all_tasks.count} tasks{x}".c)
       @last_status = nil
       @include_results = topic.results.slice(:total, :success, :errors)
       [output, @include_results[:total], @include_results[:errors].zero?]
     end
 
+    ##
+    ## Temporarily set Howzit.arguments (e.g. $1 in included shell blocks)
+    ##
+    ## @param      args  [Array] Positional values, or nil to leave unchanged
+    ##
+    def with_positional_arguments(args)
+      return yield if args.nil? || args.empty?
+
+      previous = Howzit.arguments
+      Howzit.arguments = args
+      begin
+        yield
+      ensure
+        Howzit.arguments = previous
+      end
+    end
+
     ##
     ## Apply log level for this task
     ##

data/lib/howzit/topic.rb

@@ -18,8 +18,11 @@ module Howzit
     ## @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.)
+    ## @param      positional  [Array] Values to bind to the title's (arguments),
+    ##                         overriding CLI arguments
     ##
-    def initialize(title, content, metadata = nil, source_file: nil, level: 2)
+    def initialize(title, content, metadata = nil, source_file: nil, level: 2, positional: nil)
+      @raw_title = title
       @title = title
       @content = content
       @parent = nil
@@ -30,7 +33,7 @@ module Howzit
       @named_args = {}
       @metadata = metadata
       @source_file = source_file
-      arguments(from_cli_snapshot: true)
+      arguments(from_cli_snapshot: positional.nil?, positional: positional)
 
       @directives = parse_directives_with_conditionals
       @tasks = gather_tasks
@@ -71,24 +74,43 @@ module Howzit
       list
     end
 
+    ##
+    ## A copy of this topic with bracketed arguments (e.g.
+    ## `@include(Deploy [prod])` or `default: Deploy[prod]`) bound to the
+    ## title's (arguments). Tasks are rebuilt so commands render with them.
+    ##
+    ## @param      args  [Array] Positional values
+    ##
+    ## @return     [Topic] a new Topic, or self if no args given
+    ##
+    def with_arguments(args)
+      return self if args.nil? || args.empty?
+
+      topic = Topic.new(@raw_title, @content, @metadata, source_file: @source_file, level: @level, positional: args)
+      topic.parent = @parent
+      topic.parent_topic = @parent_topic
+      topic.subtopics.concat(@subtopics)
+      topic
+    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]
-    # calls pass false to use live Howzit.arguments.
-    def arguments(from_cli_snapshot: false)
+    # topics' gather_tasks cannot clobber positional binding. positional: binds
+    # bracketed arguments from @include [a,b] and default: (see #with_arguments).
+    def arguments(from_cli_snapshot: false, positional: nil)
       @arg_definitions = []
       return unless @title =~ /\(.*?\) *$/
 
-      positional = if from_cli_snapshot
-                     # Specs / non-CLI: leave unset to keep using Howzit.arguments
-                     if Howzit.cli_topic_positional_args.nil?
-                       Howzit.arguments || []
+      positional ||= if from_cli_snapshot
+                       # Specs / non-CLI: leave unset to keep using Howzit.arguments
+                       if Howzit.cli_topic_positional_args.nil?
+                         Howzit.arguments || []
+                       else
+                         Howzit.cli_topic_positional_args
+                       end
                      else
-                       Howzit.cli_topic_positional_args
+                       Howzit.arguments || []
                      end
-                   else
-                     Howzit.arguments || []
-                   end
 
       a = @title.match(/\((?<args>.*?)\) *$/)
       args = a['args'].split(/ *, */).each(&:strip)
@@ -538,7 +560,7 @@ module Howzit
         if title =~ /\[(.*?)\] *$/
           args = Regexp.last_match(1).split(/ *, */).map(&:render_arguments)
           Howzit.arguments = args
-          arguments
+          task_args[:include_args] = args
           title.sub!(/ *\[.*?\] *$/, '')
         end
         # Apply variable substitution to title after bracket processing

data/lib/howzit/version.rb

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

data/spec/default_metadata_spec.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'fileutils'
+require 'tmpdir'
+
+describe 'default: metadata' do
+  let(:temp_dir) { File.expand_path(Dir.mktmpdir('howzit_default_test')) }
+  let(:out_file) { File.join(temp_dir, 'out.txt') }
+  let(:default_line) { 'default: Build, Deploy[prod, fast], Test' }
+  let(:buildnote) do
+    note = Howzit::BuildNote.new
+    allow(note).to receive(:finalize_output)
+    note
+  end
+
+  before do
+    File.write(
+      File.join(temp_dir, 'buildnotes.md'),
+      <<~NOTE
+        #{default_line}
+
+        # Default Project
+
+        ## Build
+
+        @run(echo "build" >> "#{out_file}") Build it
+
+        ## Deploy (target, speed:slow)
+
+        @run(echo "deploy ${target} ${speed}" >> "#{out_file}") Deploy it
+
+        ## Test
+
+        @run(echo "test" >> "#{out_file}") Test it
+
+        ## Broken
+
+        @run(false) Fail
+
+        ## Release
+
+        @include(Deploy [staging])
+        @include(Deploy [prod, fast])
+      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.options[:log_level] = 3
+    Howzit.cli_args = []
+    Howzit.run_log = []
+  end
+
+  after do
+    Howzit.options[:run] = false
+    Howzit.options[:log_level] = 1
+    Howzit.cli_args = []
+    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 output_lines
+    File.read(out_file).lines.map(&:strip)
+  end
+
+  describe 'parsing' do
+    it 'splits topics on commas outside of brackets' do
+      expect(buildnote.send(:parse_default_metadata, 'Build, Deploy[prod, fast],Test')).to eq(
+        ['Build', 'Deploy[prod, fast]', 'Test']
+      )
+    end
+
+    it 'separates bracketed arguments from the topic name' do
+      expect(buildnote.send(:parse_topic_with_args, 'Deploy[prod, fast]')).to eq(['Deploy', 'prod, fast'])
+      expect(buildnote.send(:parse_topic_with_args, 'Build')).to eq(['Build', nil])
+    end
+  end
+
+  describe 'running' do
+    it 'runs the default topics in order with howzit -r' do
+      buildnote.run
+
+      expect(output_lines).to eq(['build', 'deploy prod fast', 'test'])
+    end
+
+    it 'runs the default topics with howzit -r default' do
+      Howzit.cli_args = ['default']
+      buildnote.run
+
+      expect(output_lines).to eq(['build', 'deploy prod fast', 'test'])
+    end
+
+    context 'with fewer arguments than the topic accepts' do
+      let(:default_line) { 'default: Deploy[prod]' }
+
+      it 'uses the topic defaults for the rest' do
+        buildnote.run
+
+        expect(output_lines).to eq(['deploy prod slow'])
+      end
+    end
+
+    context 'with a missing topic' do
+      let(:default_line) { 'default: Build, Nonexistent, Test' }
+
+      it 'runs the topics that match' do
+        buildnote.run
+
+        expect(output_lines).to eq(%w[build test])
+      end
+    end
+
+    context 'with a failing topic' do
+      let(:default_line) { 'default: Build, Broken, Test' }
+
+      it 'stops after the failure and skips the remaining topics' do
+        buildnote.run
+
+        expect(output_lines).to eq(['build'])
+        expect(Howzit.run_log.map { |e| [e[:task], e[:skipped] ? :skipped : e[:success]] }).to eq(
+          [['Build it', true], ['Fail', false], ['Test it', :skipped]]
+        )
+      end
+    end
+  end
+
+  describe '@include with bracketed arguments' do
+    it 'binds the arguments to the included topic for each include' do
+      Howzit.cli_args = ['release']
+      buildnote.run
+
+      expect(output_lines).to eq(['deploy staging slow', 'deploy prod fast'])
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.1.46
+  version: 2.1.47
 platform: ruby
 authors:
 - Brett Terpstra
@@ -320,6 +320,7 @@ files:
 - spec/condition_evaluator_spec.rb
 - spec/conditional_blocks_integration_spec.rb
 - spec/conditional_content_spec.rb
+- spec/default_metadata_spec.rb
 - spec/includes_metadata_spec.rb
 - spec/log_level_spec.rb
 - spec/prompt_spec.rb
@@ -369,6 +370,7 @@ test_files:
 - spec/condition_evaluator_spec.rb
 - spec/conditional_blocks_integration_spec.rb
 - spec/conditional_content_spec.rb
+- spec/default_metadata_spec.rb
 - spec/includes_metadata_spec.rb
 - spec/log_level_spec.rb
 - spec/prompt_spec.rb