howzit 2.1.40 → 2.1.41

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8f040ba3e136aeb10470c40de3cc8272209d176841686aa242dffee1b9fb33f
-  data.tar.gz: a0e263004a627de3104cb52bb47a04aecacb7eab2389b34819d2ece891331c42
+  metadata.gz: 30837683e82b813fd1fd8ff3e2df3177cbee3c735fc5afb2cb3394f08fb341eb
+  data.tar.gz: 4a0113424a3e36169a0f7a66f31b6dcc3adc24785d9a1a54829db7d9d907c585
 SHA512:
-  metadata.gz: 3d1ce1e58eb28518b0c977f5012436909100cc48fa56dfbf1cedf01389fb02a1ef32823d99b74f065456c07d105f54a1a9dc236a6c73050251ec6180f935af0b
-  data.tar.gz: e9197120a0dd16ca9aefae85f4dde9f09f06efe56d034faf65eee180aeb5fad02fbe158d8a59b17b007622acfaa44da9aa82312159bc488d49c2f61e5a57568c
+  metadata.gz: 1c0245bdb6e801d1efb96e800c04a7ac1177a589e9d25753322bb70a6690ce22b738fdfdc12956aae216565e93ea23b7cdcc14b6f278937e329b116b8d40b5cd
+  data.tar.gz: 986c7c270fc4d8aa21c395fab7a1edaa5669c4a72e6160dede78e45c9c9b6065e69ca47c6c4253b1eae1ec2909d4e31224dee333ba74e6b392e937fe1f7f25ae

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+### 2.1.41
+
+2026-05-10 08:18
+
+#### NEW
+
+- `-z name` and `-n name` in `@if`/`@unless` conditions for shell-style empty and non-empty checks on named and positional variables.
+
+#### IMPROVED
+
+- `Util.show` strips safely when the default external encoding rejects multibyte content (fewer crashes under strict ASCII locale when piping or highlighting).
+
+#### FIXED
+
+- @set_var and @log_level inside @if/@else/@elsif so only the active branch runs; the previous behavior ran every branch and could overwrite variables set in another branch (for example ONLY_RUN set in @if then replaced by @else).
+- Topic title parameters from arguments after `--` so they no longer shift when another topic is parsed first with `@include(...[args])` (CLI positional snapshot kept separate from mutable Howzit.arguments during load).
+
 ### 2.1.40
 
 2026-02-04 07:53

data/bin/howzit

@@ -9,6 +9,8 @@ Howzit::Color.coloring = $stdout.isatty
 parts = Shellwords.shelljoin(ARGV).split(/ -- /)
 args = parts[0] ? Shellwords.shellsplit(parts[0]) : []
 Howzit.arguments = parts[1] ? Shellwords.shellsplit(parts[1]) : []
+# Immutable snapshot for topic title (param): binding — gather_tasks/@include mutates Howzit.arguments while parsing earlier topics
+Howzit.cli_topic_positional_args = Howzit.arguments&.dup || []
 Howzit.named_arguments = {}
 
 OptionParser.new do |opts|

data/lib/howzit/condition_evaluator.rb

@@ -35,6 +35,17 @@ module Howzit
       ## Evaluate a single condition (without negation)
       ##
       def evaluate_condition(condition, context)
+        # Shell-style empty / non-empty tests (bash -z / -n)
+        if (match = condition.match(/^-z\s+(.+)$/i))
+          name = match[1].strip
+          val = get_value(name, context)
+          return val.nil? || val.to_s.strip.empty?
+        elsif (match = condition.match(/^-n\s+(.+)$/i))
+          name = match[1].strip
+          val = get_value(name, context)
+          return !val.nil? && !val.to_s.strip.empty?
+        end
+
         # Handle special conditions FIRST to avoid false matches with comparison patterns
         # Check file contents before other patterns since it has arguments and operators
         if condition =~ /^file\s+contents\s+(.+?)\s+(\*\*=|\*=|\^=|\$=|==|!=|=~)\s*(.+)$/i

data/lib/howzit/topic.rb

@@ -25,7 +25,7 @@ module Howzit
       @named_args = {}
       @metadata = metadata
       @source_file = source_file
-      arguments
+      arguments(from_cli_snapshot: true)
 
       @directives = parse_directives_with_conditionals
       @tasks = gather_tasks
@@ -33,10 +33,23 @@ module Howzit
     end
 
     # Get named arguments from title
-    def arguments
+    # from_cli_snapshot: use Howzit.cli_topic_positional_args (set once from argv after ` -- `) so earlier topics' gather_tasks
+    # cannot clobber positional binding. Re-entrant calls (e.g. @include with [a,b]) pass false to use live Howzit.arguments.
+    def arguments(from_cli_snapshot: false)
       @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 || []
+                     else
+                       Howzit.cli_topic_positional_args
+                     end
+                   else
+                     Howzit.arguments || []
+                   end
+
       a = @title.match(/\((?<args>.*?)\) *$/)
       args = a['args'].split(/ *, */).each(&:strip)
 
@@ -45,8 +58,8 @@ module Howzit
         # Store original definition for display purposes
         @arg_definitions << (default ? "#{arg_name}:#{default}" : arg_name)
 
-        @named_args[arg_name] = if Howzit.arguments && Howzit.arguments.count >= idx + 1
-                                  Howzit.arguments[idx]
+        @named_args[arg_name] = if positional && positional.count >= idx + 1
+                                  positional[idx]
                                 else
                                   default
                                 end
@@ -642,6 +655,7 @@ module Howzit
         if line =~ /^@log_level\s*\(([^)]+)\)\s*$/i
           log_level = Regexp.last_match(1).strip
           conditional_path = conditional_stack.dup
+          conditional_path << current_branch_index if current_branch_index
           directives << Howzit::Directive.new(
             type: :log_level,
             log_level_value: log_level,
@@ -664,6 +678,7 @@ module Howzit
               # Remove quotes from value if present (handles both single and double quotes)
               var_value = Regexp.last_match(1) if var_value =~ /^["'](.+)["']$/
               conditional_path = conditional_stack.dup
+              conditional_path << current_branch_index if current_branch_index
               directives << Howzit::Directive.new(
                 type: :set_var,
                 var_name: var_name,
@@ -818,12 +833,16 @@ module Howzit
 
         # Handle @log_level directive (before task check)
         if directive.log_level?
+          next unless directive_in_active_branch?(directive, conditional_state)
+
           current_log_level = directive.log_level_value
           next
         end
 
         # Handle @set_var directive (before task check)
         if directive.set_var?
+          next unless directive_in_active_branch?(directive, conditional_state)
+
           # Set the variable in named_arguments
           Howzit.named_arguments ||= {}
           value = directive.var_value
@@ -856,34 +875,7 @@ module Howzit
         # Handle task directives
         next unless directive.task?
 
-        # Check if all parent conditionals are true
-        should_execute = true
-
-        # If path ends with an @elsif/@else, skip the parent @if index
-        # (the index right before the elsif/else in the path)
-        path_to_check = directive.conditional_path.dup
-        if path_to_check.length >= 2
-          last_idx = path_to_check.last
-          last_state = conditional_state[last_idx]
-          if last_state && %w[elsif else].include?(last_state[:directive_type])
-            # Skip the parent @if index (the one before the elsif/else)
-            parent_if_idx = path_to_check[path_to_check.length - 2]
-            parent_if_state = conditional_state[parent_if_idx]
-            if parent_if_state && %w[if unless].include?(parent_if_state[:directive_type])
-              path_to_check.delete(parent_if_idx)
-            end
-          end
-        end
-
-        path_to_check.each do |cond_idx|
-          cond_state = conditional_state[cond_idx]
-          if cond_state.nil? || !cond_state[:evaluated] || !cond_state[:result]
-            should_execute = false
-            break
-          end
-        end
-
-        next unless should_execute
+        next unless directive_in_active_branch?(directive, conditional_state)
 
         # Convert directive to task
         task = directive.to_task(self, current_log_level: current_log_level)
@@ -939,6 +931,38 @@ module Howzit
       output
     end
 
+    ##
+    ## Whether a directive nested under @if/@unless/@elsif/@else should run (same rules as tasks).
+    ##
+    def directive_in_active_branch?(directive, conditional_state)
+      path = directive.conditional_path || []
+      return true if path.empty?
+
+      should_execute = true
+      path_to_check = path.dup
+      if path_to_check.length >= 2
+        last_idx = path_to_check.last
+        last_state = conditional_state[last_idx]
+        if last_state && %w[elsif else].include?(last_state[:directive_type])
+          parent_if_idx = path_to_check[path_to_check.length - 2]
+          parent_if_state = conditional_state[parent_if_idx]
+          if parent_if_state && %w[if unless].include?(parent_if_state[:directive_type])
+            path_to_check.delete(parent_if_idx)
+          end
+        end
+      end
+
+      path_to_check.each do |cond_idx|
+        cond_state = conditional_state[cond_idx]
+        if cond_state.nil? || !cond_state[:evaluated] || !cond_state[:result]
+          should_execute = false
+          break
+        end
+      end
+
+      should_execute
+    end
+
     ##
     ## Find the index of the matching @if/@unless for an @elsif/@else/@end
     ##

data/lib/howzit/util.rb

@@ -161,6 +161,14 @@ module Howzit
         status.success?
       end
 
+      # Strip safely when external encoding rejects multibyte content (e.g. US-ASCII default).
+      def safe_strip(str)
+        s = str.to_s
+        s.strip
+      rescue Encoding::CompatibilityError
+        s.encode('UTF-8', invalid: :replace, undef: :replace).strip
+      end
+
       # print output to terminal
       def show(string, opts = {})
         options = {
@@ -180,7 +188,10 @@ module Howzit
           pipes = "|#{hl}" if hl
         end
 
-        output = `echo #{Shellwords.escape(string.strip)}#{pipes}`.strip
+        string = safe_strip(string)
+
+        raw_output = `echo #{Shellwords.escape(string)}#{pipes}`
+        output = safe_strip(raw_output)
 
         if options[:paginate] && Howzit.options[:paginate]
           page(output)

data/lib/howzit/version.rb

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

data/lib/howzit.rb

@@ -60,7 +60,7 @@ require 'tty/box'
 # Main module for howzit
 module Howzit
   class << self
-    attr_accessor :arguments, :named_arguments, :cli_args, :run_log, :multi_topic_run
+    attr_accessor :arguments, :named_arguments, :cli_topic_positional_args, :cli_args, :run_log, :multi_topic_run
 
     ##
     ## Holds a Configuration object with methods and a @settings hash

data/spec/condition_evaluator_spec.rb

@@ -122,6 +122,30 @@ describe Howzit::ConditionEvaluator do
         expect(described_class.evaluate('${env} == "production"', {})).to be true
         expect(described_class.evaluate('${var} == "other"', {})).to be false
       end
+
+      it 'evaluates -z (empty) for named arguments' do
+        Howzit.named_arguments = { 'option' => '', other: 'x' }
+        expect(described_class.evaluate('-z option', {})).to be true
+        expect(described_class.evaluate('-z other', {})).to be false
+      end
+
+      it 'evaluates -n (non-empty) for named arguments' do
+        Howzit.named_arguments = { 'option' => '', other: 'x' }
+        expect(described_class.evaluate('-n option', {})).to be false
+        expect(described_class.evaluate('-n other', {})).to be true
+      end
+
+      it 'treats undefined named argument as empty for -z / -n' do
+        Howzit.named_arguments = {}
+        expect(described_class.evaluate('-z missing', {})).to be true
+        expect(described_class.evaluate('-n missing', {})).to be false
+      end
+
+      it 'supports not -z and not -n' do
+        Howzit.named_arguments = { opt: 'yes' }
+        expect(described_class.evaluate('not -z opt', {})).to be true
+        expect(described_class.evaluate('not -n opt', {})).to be false
+      end
     end
 
     context 'with metadata' do

data/spec/sequential_conditional_spec.rb

@@ -317,4 +317,53 @@ describe 'Sequential Conditional Evaluation' do
       expect(Howzit.named_arguments['ALL']).to eq('123')
     end
   end
+
+  describe '@set_var under @if/@else' do
+    let(:branch_note) do
+      <<~EONOTE
+        # Test
+
+        ## Branch Topic (flag)
+
+        @if -n flag
+        @set_var(RESULT, "yes")
+        @else
+        @set_var(RESULT, "no")
+        @end
+
+        ```run Echo
+        #!/bin/bash
+        echo ok
+        ```
+      EONOTE
+    end
+
+    it 'only runs @set_var from the active branch when @if is true' do
+      File.open('builda.md', 'w') { |f| f.puts branch_note }
+      Howzit.arguments = ['present']
+      Howzit.cli_topic_positional_args = ['present']
+      Howzit.named_arguments = {}
+      Howzit.instance_variable_set(:@buildnote, nil)
+      topic = Howzit.buildnote('builda.md').find_topic('Branch Topic')[0]
+      allow(Howzit::Prompt).to receive(:yn).and_return(true)
+
+      topic.run
+
+      expect(Howzit.named_arguments['RESULT']).to eq('yes')
+    end
+
+    it 'only runs @set_var from the active branch when @else is taken' do
+      File.open('builda.md', 'w') { |f| f.puts branch_note }
+      Howzit.arguments = []
+      Howzit.cli_topic_positional_args = []
+      Howzit.named_arguments = {}
+      Howzit.instance_variable_set(:@buildnote, nil)
+      topic = Howzit.buildnote('builda.md').find_topic('Branch Topic')[0]
+      allow(Howzit::Prompt).to receive(:yn).and_return(true)
+
+      topic.run
+
+      expect(Howzit.named_arguments['RESULT']).to eq('no')
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -18,11 +18,19 @@ RSpec.configure do |c|
     save_buildnote
     # Reset buildnote cache to ensure fresh instance with updated file
     Howzit.instance_variable_set(:@buildnote, nil)
+    Howzit.arguments = []
+    Howzit.cli_topic_positional_args = nil
+    Howzit.named_arguments = {}
     Howzit.options[:include_upstream] = false
     Howzit.options[:stack] = false
     Howzit.options[:default] = true
     Howzit.options[:matching] = 'partial'
     Howzit.options[:multiple_matches] = 'choose'
+    # Point singleton at test fixture (repo may also contain buildnotes.md, etc.)
+    Howzit.instance_variable_set(
+      :@buildnote,
+      Howzit::BuildNote.new(file: File.expand_path('builda.md'))
+    )
     @hz = Howzit.buildnote
   end
 

data/spec/topic_positional_snapshot_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'tempfile'
+
+describe 'Topic title positional args vs gather_tasks' do
+  it 'uses CLI positional snapshot so a prior topic @include […] does not shift later topic params' do
+    Howzit.arguments = ['from_cli']
+    Howzit.cli_topic_positional_args = ['from_cli']
+
+    Tempfile.create(['howzit-pos', '.md']) do |f|
+      f.write(<<~MD)
+        defined: snap
+
+        # Note
+
+        ## First Topic
+
+        @include(DoesNotNeedToExist[y])
+
+        ## Widget Topic (only:falafel)
+
+        ok
+      MD
+      f.flush
+
+      note = Howzit::BuildNote.new(file: f.path)
+      widget = note.topics.find { |t| t.title == 'Widget Topic' }
+      expect(widget).not_to be_nil
+      expect(widget.named_args['only']).to eq('from_cli')
+    end
+  end
+end

data/spec/topic_spec.rb

@@ -24,7 +24,7 @@ end
 
 describe Howzit::Topic do
   subject(:topic) do
-    bn = Howzit.buildnote
+    bn = Howzit.buildnote('builda.md')
     bn.find_topic('Topic Balogna')[0]
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.1.40
+  version: 2.1.41
 platform: ruby
 authors:
 - Brett Terpstra
@@ -331,6 +331,7 @@ files:
 - spec/stack_mode_spec.rb
 - spec/stringutils_spec.rb
 - spec/task_spec.rb
+- spec/topic_positional_snapshot_spec.rb
 - spec/topic_spec.rb
 - spec/util_spec.rb
 - src/_README.md
@@ -354,7 +355,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.7
 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.
@@ -375,5 +376,6 @@ test_files:
 - spec/stack_mode_spec.rb
 - spec/stringutils_spec.rb
 - spec/task_spec.rb
+- spec/topic_positional_snapshot_spec.rb
 - spec/topic_spec.rb
 - spec/util_spec.rb