ceedling 1.1.10 → 1.2.0

data/lib/ceedling/test_invoker/test_search_paths.rb

@@ -0,0 +1,73 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# A test's compiler search paths, in the order the compiler searches them. Generated
+# directories come first, so a test's mocks and Partials shadow the real headers they
+# stand in for, then TEST_INCLUDE_PATH() entries, then the project's configured paths.
+class TestSearchPaths
+
+  constructor :configurator, :include_pathinator, :test_context_extractor
+
+  # `paths` is a Testable's paths Hash. `mock_search_paths` are its mocks' mirrored
+  # directories, which sit right after the flat mock root.
+  def compose(filepath, paths, mock_search_paths = [])
+    return (generated_paths( filepath, paths, mock_search_paths ) + configured_paths( filepath )).uniq
+  end
+
+  # Sets a test's mock search paths and composes its search paths around them. `lock`
+  # guards the write, since other threads read the Testable.
+  def assign_mock_search_paths(testable, mock_search_paths, lock)
+    paths = compose( testable.filepath, testable.paths, mock_search_paths )
+    lock.synchronize do
+      testable.mock_search_paths = mock_search_paths
+      testable.search_paths      = paths
+    end
+  end
+
+  private
+
+  # Where this test's mocks and Partials are generated
+  def generated_paths(filepath, paths, mock_search_paths)
+    _paths = []
+    _paths << paths[:mocks] if paths[:mocks]
+    _paths += mock_search_paths
+    _paths << paths[:partials] if paths[:partials]
+    return _paths + partial_search_paths( filepath, paths )
+  end
+
+  # TEST_INCLUDE_PATH() entries, then the project's configured paths
+  def configured_paths(filepath)
+    return @include_pathinator.lookup_test_directive_include_paths( filepath ) +
+           @include_pathinator.collect_test_include_paths() +
+           @configurator.collection_paths_support +
+           @configurator.collection_paths_include +
+           @configurator.collection_paths_libraries +
+           @configurator.collection_paths_vendor +
+           @configurator.collection_paths_test_toolchain_include
+  end
+
+  # Every Partialized module's own directory below this test's Partials root.
+  #
+  # A generated Partial is only findable by the compiler via a search path pointing
+  # directly at where it sits, since C's own #include resolution has no notion of a
+  # recursive search path. Each mock's mirrored directory is on the search path for the
+  # same reason, and this also covers the generated test runner, which includes a
+  # Partial header by basename alone.
+  #
+  # The module keys carry the directory, so nothing has to exist on disk yet.
+  def partial_search_paths(filepath, paths)
+    return [] unless paths[:partials]
+
+    dirs = @test_context_extractor.lookup_partials_config( filepath ).keys.map do |_module|
+      dir = File.dirname( _module )
+      dir == '.' ? nil : File.join( paths[:partials], dir )
+    end
+
+    return dirs.compact.uniq
+  end
+
+end

data/lib/ceedling/test_invoker/test_source_file_directive_resolver.rb

@@ -0,0 +1,78 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'ceedling/constants'
+require 'ceedling/exceptions'
+require 'ceedling/file_path_utils'
+require 'ceedling/path_matcher'
+require 'ceedling/test_invoker/test_build_validations'
+
+# Owns everything about the TEST_SOURCE_FILE() build directive's own path
+# content: collecting a test's raw directive strings, telling additive
+# entries apart from subtractive ones, resolving each to a real project
+# file, and validating that every entry names something real. Callers care
+# about what a test's directive entries resolve to and whether they're
+# valid; they don't need to know the +:/-: convention or how a raw string
+# becomes a real filepath.
+class TestSourceFileDirectiveResolver
+
+  include TestBuildValidations
+
+  constructor :test_context_extractor, :file_finder, :configurator, :loginator
+
+  # Splits a test's TEST_SOURCE_FILE() entries into files to add and files to
+  # remove, using the same +:/-: convention :paths list entries use, then
+  # resolves each side to a real project file exactly as a bare entry always
+  # has. The removal side is returned as resolved path => original directive
+  # text, so a caller can both act on the resolved path and name the entry
+  # that caused it.
+  def resolve(test_filepath, context)
+    raw = @test_context_extractor.lookup_build_directive_sources_list( test_filepath )
+    additive, subtractive = raw.partition { |source| FilePathUtils.add_path?( source ) }
+
+    # A directive's own text is written directly in the test file, so its `..`, if
+    # any, is anchored to that same test file's own directory -- exactly as a
+    # directory-relative #include would be.
+    anchor = File.dirname( test_filepath )
+
+    find = -> (source) {
+      stripped = FilePathUtils.no_aggregation_decorators( source )
+      @file_finder.find_build_input_file(
+        filepath: PathMatcher.resolve_relative( stripped, anchor: anchor ),
+        complain: :ignore,
+        context:  context
+      )
+    }
+
+    additive_sources = additive.map(&find).compact
+
+    subtractive_sources = subtractive.each_with_object({}) do |source, hash|
+      resolved = find.call( source )
+      hash[resolved] = source unless resolved.nil?
+    end
+
+    return [additive_sources, subtractive_sources]
+  end
+
+  # Applies this test's TEST_SOURCE_FILE("-:...") entries against the fully
+  # assembled source list, regardless of how each removed file originally got
+  # there -- the implicit header/source convention, a positive directive, or
+  # a Partial. Each removal that actually changes the list is logged by name
+  # so the resulting build is never quietly different from what the source
+  # list would otherwise suggest.
+  def remove_subtracted(sources, subtractive:, test_filepath:)
+    subtractive.each do |removed_path, raw|
+      next unless sources.include?( removed_path )
+      msg = "TEST_SOURCE_FILE(\"#{raw}\") removed '#{removed_path}' from " \
+            "#{test_filepath}'s compile/link list."
+      @loginator.log( msg, Verbosity::COMPLAIN, LogLabels::NOTICE )
+    end
+
+    return sources - subtractive.keys
+  end
+
+end

data/lib/ceedling/tool_executor.rb

@@ -16,12 +16,13 @@ class ToolExecutor
     tool[:name] = default if tool[:name].nil?
   end
 
-  constructor :configurator, :tool_executor_helper, :loginator, :verbosinator, :system_wrapper, :ruby_expandinator
+  constructor :tool_executor_helper, :loginator, :verbosinator, :system_wrapper, :ruby_expandinator
 
   # build up a command line from yaml provided config
 
   # @param extra_params is an array of parameters to append to executable (prepend to rest of command line)
-  def build_command_line(tool_config, extra_params, *args)
+  # @param trailing is an array of parameters to append after the tool's own arguments
+  def build_command_line(tool_config, extra_params, *args, trailing: [])
     command = {}
 
     command[:name] = tool_config[:name]
@@ -40,6 +41,7 @@ class ToolExecutor
       executable,
       extra_params.join(' ').strip,
       build_arguments(tool_config[:name], tool_config[:arguments], *args),
+      trailing.join(' ').strip,
       ].reject{|s| s.nil? || s.empty?}.join(' ').strip
 
     # Log command as is
@@ -88,7 +90,7 @@ class ToolExecutor
       # Scrub the string for illegal output
       unless shell_result[:output].nil?
         shell_result[:output] = shell_result[:output].scrub if "".respond_to?(:scrub)
-        shell_result[:output].gsub!(/\033\[\d\dm/,'')
+        shell_result[:output].gsub!(/\033\[[\d;]*m/,'')
       end
 
       @tool_executor_helper.log_results( command_line, shell_result )
@@ -103,6 +105,20 @@ class ToolExecutor
     return shell_result
   end
 
+  # Reports whether an executed command failed, whatever its `:boom` setting.
+  #
+  # A command run with `:boom` false always reports an `:exit_code` of 0 (see
+  # SystemWrapper#shell_capture3). Callers handling a failure themselves need the process
+  # status instead. A process killed by a signal has no exit status and counts as failed.
+  # A result without a status, such as a test double, falls back to its `:exit_code`.
+  def failed?(shell_result)
+    status = shell_result[:status]
+
+    return !status.success? unless status.nil?
+
+    return shell_result[:exit_code] != 0
+  end
+
   private #############################
 
 
@@ -140,12 +156,14 @@ class ToolExecutor
   def expandify_element(tool_name, element, *args)
     match = //
     to_process = nil
-    args_index = 0
 
-    # Handle ${#} input replacement
-    if (element =~ PATTERNS::TOOL_EXECUTOR_ARGUMENT_REPLACEMENT)
+    # Handle ${#} input replacement, unless the operator itself is escaped (`\${#}`) --
+    # an escaped token is left for the unconditional `\$` unescape below to turn into
+    # literal '${#}' text instead of triggering substitution.
+    match_data = element.match(PATTERNS::TOOL_EXECUTOR_ARGUMENT_REPLACEMENT)
+    if match_data && !match_data.pre_match.end_with?('\\')
       # Convert argument numbering from configuration 1-indexed to array 0-indexed
-      args_index = ($2.to_i - 1)
+      args_index = (match_data[2].to_i - 1)
 
       args_size = args.nil? ? 0 : args.size()
 
@@ -155,11 +173,11 @@ class ToolExecutor
       end
 
       if (args_index >= args_size)
-        error = "Command building for tool '#{tool_name}' was provided only #{args_size} arguments but references a replacement operator #{$1}."
+        error = "Command building for tool '#{tool_name}' was provided only #{args_size} arguments but references a replacement operator #{match_data[1]}."
         raise CeedlingException.new( error )
       end
 
-      match = /#{Regexp.escape($1)}/
+      match = /#{Regexp.escape(match_data[1])}/
       to_process = args[args_index]
     end
 
@@ -201,11 +219,18 @@ class ToolExecutor
     expansion = ((expand.class == String) ? [expand] : expand)
 
     expansion.each do |item|
+      # `item.class == String` guards every check that calls `=~` on `item` below --
+      # Ruby 3.2 removed the default Object#=~, so calling it on a non-String item
+      # (an Array, an Integer, ...) raises NoMethodError instead of returning nil the
+      # way it harmlessly used to. Checking the class first, before ever calling `=~`,
+      # keeps a non-String item flowing to the Array/literal/unsupported-type checks
+      # below instead of crashing here.
+      #
       # String eval substitution
-      if (item =~ PATTERNS::RUBY_STRING_REPLACEMENT)
+      if (item.class == String) && (item =~ PATTERNS::RUBY_STRING_REPLACEMENT)
         elements << @ruby_expandinator.expand(item, source: "tool '#{tool_name}'")
       # Global constants
-      elsif (@system_wrapper.constants_include?(item))
+      elsif (item.class == String) && @system_wrapper.constants_include?(item)
         const = Object.const_get(item)
         if (const.nil?)
           error = "Tool '#{tool_name}' found constant '#{item}' to be nil."
@@ -216,8 +241,12 @@ class ToolExecutor
       elsif (item.class == Array)
         elements << item
       elsif (item.class == String)
-        error = "Tool '#{tool_name}' cannot expand nonexistent value '#{item}' for substitution string '#{substitution}'."
-        raise CeedlingException.new( error )
+        # Neither a Ruby-replacement pattern nor a recognized global constant -- use the
+        # literal text as-is. The array-substitution shortcut documented in tools.md
+        # (`-l$-lib:` with a YAML array of plain library names) depends on this: each
+        # name is a literal value to drop into the substitution string, not a reference
+        # to anything else.
+        elements << item
       else
         error = "Tool '#{tool_name}' cannot expand value having type '#{item.class}' for substitution string '#{substitution}'."
         raise CeedlingException.new( error )

data/lib/ceedling/tool_executor_helper.rb

@@ -20,7 +20,7 @@ class ToolExecutorHelper
   # * _executable_:  The executable's path.
   #
   def osify_path_separators(executable)
-    return executable.gsub(/\//, '\\') if (@system_wrapper.windows?)
+    return executable.tr('/', '\\') if (@system_wrapper.windows?)
     return executable
   end
 

data/lib/ceedling/tool_validator.rb

@@ -7,25 +7,66 @@
 
 require 'rake' # For ext()
 require 'ceedling/constants'
-require 'ceedling/tool_executor'    # For argument replacement pattern
-require 'ceedling/file_path_utils'  # For glob handling class methods
+require 'ceedling/filename_extension'
+require 'ceedling/exceptions'
+
+# Confirms a tool's configuration can run before a build depends on it.
+#
+# A tool is valid when its executable can be found and its stderr redirect is a known
+# option. The executable is an explicit path or a bare name searched on PATH, and either
+# may omit the extension its file carries on disk. An executable built at run time, from
+# an argument or a Ruby expansion, is left for the shell to resolve.
+class ToolValidator
 
+  constructor :file_wrapper, :loginator, :system_wrapper, :ruby_expandinator
 
-class ToolValidator
-  
-  constructor :file_wrapper, :loginator, :system_wrapper, :reportinator, :ruby_expandinator
+  # The executable a tool's command names, or nil when it names none.
+  #
+  # A quoted executable may contain spaces (e.g. `"Code Cruncher" --fast`). Otherwise
+  # the executable ends at the first space, ahead of the command's arguments.
+  def self.executable_from(command)
+    return nil if command.nil?
 
-  def validate(tool:, name:nil, extension:EXTENSION_EXECUTABLE, respect_optional:false, boom:false)
-    # Redefine name with name inside tool hash if it's not provided
-    # If the name is provided it's likely the formatted key path into the configuration file
-    name = tool[:name] if name.nil? or name.empty?
+    command = command.strip
+    return nil if command.empty?
+
+    matched = command.match( /\A"(.+)"/ )
+    return matched ? matched[1] : command.split( ' ' ).first
+  end
+
+  # Whether `executable` names a path rather than a name to search for. Windows' `\`
+  # counts as a separator, since not every caller's paths pass through load-time cleanup.
+  def self.explicit_path?(executable)
+    return executable.match?( %r{[/\\]} )
+  end
+
+  # Every file that would satisfy `executable`, in the order they are tried.
+  #
+  # An explicit path is tried as written, and a bare name in each search path. Each is
+  # also tried under every configured extension, and as .exe on Windows, since a command
+  # may omit the extension its file carries on disk.
+  def self.candidates(executable, extension:, windows:, search_paths:)
+    bases = explicit_path?( executable ) ? [executable] : search_paths.map { |path| File.join( path, executable ) }
+
+    return bases.flat_map { |base| variants( base, extension, windows ) }.uniq
+  end
+
+  def self.variants(path, extension, windows)
+    variants = [path] + extension.map { |ext| path.ext( ext ) }
+    variants << path.ext( EXTENSION_WIN_EXE ) if windows
+    return variants
+  end
+  private_class_method :variants
 
-    valid = true
+  def validate(tool:, name:nil, extension:nil, respect_optional:false, boom:false)
+    # A given name is usually the tool's key path into the configuration
+    name = tool[:name] if name.nil? or name.empty?
+    extension ||= default_extension()
 
-    valid &= validate_executable( tool:tool, name:name, extension:extension, respect_optional:respect_optional, boom:boom )
-    valid &= validate_stderr_redirect( tool:tool, name:name, boom:boom )
+    valid = validate_executable( tool:tool, name:name, extension:extension, respect_optional:respect_optional, boom:boom )
 
-    return valid
+    # Both checks run, so a tool with two problems reports both
+    return valid & validate_stderr_redirect( tool:tool, name:name, boom:boom )
   end
 
   ### Private ###
@@ -33,133 +74,93 @@ class ToolValidator
   private
 
   def validate_executable(tool:, name:, extension:, respect_optional:, boom:)
-    exists = false
-    error = ''
-
-    # Get unfrozen copy so we can modify for our processing
-    executable = tool[:executable].dup()
+    command    = tool[:executable]
+    executable = ToolValidator.executable_from( command )
 
-    # Handle a missing :executable
-    if (executable.nil?)
-      error = "Tool #{name} is missing :executable in its configuration!"
-      if !boom
-        @loginator.log( error, Verbosity::ERRORS )
-        return false 
-      end
+    return true if tool[:optional] and respect_optional
+    
+    return fail_validation( "Tool #{name} is missing :executable in its configuration!", boom ) if executable.nil?
 
-      raise CeedlingException.new(error)
-    end
+    return run_time_executable_valid?( command, name, boom ) if run_time_executable?( command )
 
-    # If tool is optional and we're respecting that, don't bother to check if executable is legit
-    return true if tool[:optional] and respect_optional
+    return true if executable_exists?( executable, extension )
 
-    # Skip everything if we've got an argument replacement pattern in :executable
-    # (Allow executable to be validated by shell at run time)
-    return true if (executable =~ PATTERNS::TOOL_EXECUTOR_ARGUMENT_REPLACEMENT)
-
-    # Skip shell-time validation for Ruby string replacement in :executable, but fail
-    # fast here (rather than deferring to tool_executor.rb's later expansion attempt)
-    # if the feature isn't enabled -- no reason to let the build proceed further only
-    # to blow up when this tool is actually invoked.
-    if (executable =~ PATTERNS::RUBY_STRING_REPLACEMENT)
-      begin
-        @ruby_expandinator.check!( executable, source: "tool '#{name}' :executable" )
-      rescue CeedlingException => e
-        if !boom
-          @loginator.log( e.message, Verbosity::ERRORS )
-          return false
-        end
-        raise
-      end
-      return true
-    end
+    location = ToolValidator.explicit_path?( executable ) ? 'on disk' : 'in system search paths'
+    return fail_validation( "#{name} ↳ :executable ➡️ `#{executable}` does not exist #{location}", boom )
+  end
 
-    # Extract the executable (including optional filepath) apart from any additional arguments
-    # Be mindful of legal quote enclosures (e.g. `"Code Cruncher" foo bar`)
-    executable.strip!
-    if (matched = executable.match(/^"(.+)"/))
-      # If the regex matched, extract contents of match group within parens
-      executable = matched[1]
-    else
-      # Otherwise grab first token before arguments
-      executable = executable.split(' ')[0]
-    end
+  # Whether the executable is built only when the tool runs, from an argument or a Ruby
+  # expansion, so no file can be checked for now
+  def run_time_executable?(command)
+    return command.match?( PATTERNS::TOOL_EXECUTOR_ARGUMENT_REPLACEMENT ) ||
+           command.match?( PATTERNS::RUBY_STRING_REPLACEMENT )
+  end
 
-    # If no path included, verify file exists in system search paths
-    if (not executable.include?('/'))      
-
-      # Iterate over search paths
-      @system_wrapper.search_paths.each do |path|
-        # File exists as named
-        if (@file_wrapper.exist?( File.join(path, executable)) )
-          exists = true
-          break
-        # File exists with executable file extension
-        elsif (@file_wrapper.exist?( (File.join(path, executable)).ext( extension ) ))
-          exists = true
-          break
-        # We're on Windows and file exists with .exe file extension
-        elsif (@system_wrapper.windows? and @file_wrapper.exist?( (File.join(path, executable)).ext( EXTENSION_WIN_EXE ) ))
-          exists = true
-          break
-        end
-      end
-
-      # Construct end of error message
-      error = "does not exist in system search paths" if not exists
-      
-    # If there is a path included, check that explicit filepath exists
-    else
-      if @file_wrapper.exist?( executable )
-        exists = true
-      else
-        # Construct end of error message
-        error = "does not exist on disk" if not exists
-      end      
-    end
+  # The shell resolves an argument whenever the tool runs. A Ruby expansion resolves only
+  # when that feature is enabled, so a disabled feature fails here rather than at run time.
+  def run_time_executable_valid?(command, name, boom)
+    return true if command.match?( PATTERNS::TOOL_EXECUTOR_ARGUMENT_REPLACEMENT )
 
-    if !exists
-      error = "#{name} ↳ :executable ➡️ `#{executable}` " + error
-    end
+    @ruby_expandinator.check!( command, source: "tool '#{name}' :executable" )
+    return true
+  rescue CeedlingException => e
+    return fail_validation( e.message, boom )
+  end
 
-    # Raise exception if executable can't be found and boom is set
-    if !exists and boom
-      raise CeedlingException.new( error )
-    end
+  # Search paths are read only for a bare name, which is the only kind searched for
+  def executable_exists?(executable, extension)
+    search_paths = ToolValidator.explicit_path?( executable ) ? [] : @system_wrapper.search_paths
 
-    # Otherwise, log error
-    if !exists
-      @loginator.log( error, Verbosity::ERRORS )
-    end
+    candidates = ToolValidator.candidates(
+      executable,
+      extension:    extension,
+      windows:      @system_wrapper.windows?,
+      search_paths: search_paths
+    )
 
-    return exists
+    return candidates.any? { |candidate| @file_wrapper.exist?( candidate ) }
   end
-  
+
   def validate_stderr_redirect(tool:, name:, boom:)
-    error = ''
     redirect = tool[:stderr_redirect]
 
-    # If no redirect set at all, it's cool
-    return if redirect.nil?
+    # No redirect and a custom redirect string are both valid
+    return true if redirect.nil? or redirect.is_a?( String )
 
-    # Otherwise, process the redirect that's been set
-    if redirect.class == Symbol
-      if not StdErrRedirect.constants.map{|constant| constant.to_s}.include?( redirect.to_s.upcase )
-        options = StdErrRedirect.constants.map{|constant| ':' + constant.to_s.downcase}.join(', ')
-        error = "#{name} ↳ :stderr_redirect ➡️ :#{redirect} is not a recognized option {#{options}}"
-
-        # Raise exception if requested
-        raise CeedlingException.new( error ) if boom
-
-        # Otherwise log error
-        @loginator.log( error, Verbosity::ERRORS )
-        return false
-      end    
-    elsif redirect.class != String
+    # A value of the wrong type is a malformed configuration rather than a bad choice
+    # among options, so it stops the build whatever `boom` is
+    unless redirect.is_a?( Symbol )
       raise CeedlingException.new( "#{name} ↳ :stderr_redirect is neither a recognized value nor custom string" )
     end
 
-    return true
+    return true if recognized_redirect?( redirect )
+
+    return fail_validation( "#{name} ↳ :stderr_redirect ➡️ :#{redirect} is not a recognized option {#{redirect_options()}}", boom )
   end
-  
+
+  # Options match case-insensitively, so :auto and :AUTO both name StdErrRedirect::AUTO
+  def recognized_redirect?(redirect)
+    return StdErrRedirect.constants.map( &:to_s ).include?( redirect.to_s.upcase )
+  end
+
+  def redirect_options()
+    return StdErrRedirect.constants.map { |constant| ':' + constant.to_s.downcase }.join( ', ' )
+  end
+
+  # A loaded project configuration defines EXTENSION_EXECUTABLE. Before one loads, the
+  # platform's own executable extension applies.
+  def default_extension()
+    return EXTENSION_EXECUTABLE if defined?( EXTENSION_EXECUTABLE )
+
+    return FilenameExtension.new( @system_wrapper.windows? ? EXTENSION_WIN_EXE : EXTENSION_NONWIN_EXE )
+  end
+
+  # Raises under `boom`, and otherwise logs the error and reports the tool invalid
+  def fail_validation(error, boom)
+    raise CeedlingException.new( error ) if boom
+
+    @loginator.log( error, Verbosity::ERRORS )
+    return false
+  end
+
 end

data/lib/ceedling/yaml_wrapper.rb

@@ -10,12 +10,14 @@ require 'ceedling/exceptions'
 
 class YamlWrapper
 
+  constructor :file_wrapper
+
   # Ceedling loads YAML from project config files, cache files, and generated test-result
   # files. `YAML.load` can instantiate arbitrary Ruby objects from that content, which is
   # unnecessary and unsafe -- `YAML.safe_load` restricts deserialization to plain data types
   # plus whatever is explicitly permitted below.
   #
-  # Ceedling's YAML convention (see assets/project.yml, cacheinator.rb, generator_test_results.rb)
+  # Ceedling's YAML convention (see assets/features/project.yml, cacheinator.rb, generator_test_results.rb)
   # uses colon-prefixed keys (`:foo:`) to mean "this key is a Ruby Symbol"; unprefixed keys
   # stay Strings. Psych recognizes `:foo` scalar notation as Symbol by default -- safe_load
   # just needs `Symbol` added to its class allowlist to permit it. Aliases (`&anchor`/`*alias`)
@@ -36,7 +38,7 @@ class YamlWrapper
 
   def load(filepath)
     begin
-      source = File.read(filepath)
+      source = @file_wrapper.read(filepath)
     rescue Errno::ENOENT
       raise YamlLoadException.new(
         reason: :not_found, source: filepath, original_error: nil,
@@ -89,7 +91,7 @@ class YamlWrapper
   end
 
   def dump(filepath, structure)
-    File.open(filepath, 'w') do |output|
+    @file_wrapper.open(filepath, 'w') do |output|
       YAML.dump(structure, output)
     end
   end

data/lib/version.rb

@@ -11,11 +11,28 @@
 ##     `ruby Ceedling/lib/version.rb`
 ##  2. As a code module of constants consumed by Ruby's gem building process
 ##
+## The version reported here distinguishes a published gem from any other build.
+## Only the release pipeline produces a bare version. Everything else carries a
+## `.dev` suffix, so `ceedling version` says plainly which kind of install it is.
+##
 
 module Ceedling
   module Version
-    # Convenience constants for gem building, etc.
-    GEM = '1.1.10'
+    # Target version for the current release cycle. Maintained by hand, one edit
+    # per minor or major cycle. Never edited to match a release tag. The release
+    # pipeline rewrites this line from the tag that triggered it.
+    BASE = '1.2.0'
+
+    # Marker for a build the release pipeline did not produce. That pipeline
+    # empties this line, so a published gem reports a bare version while a local
+    # build reports `.dev`. RubyGems reads a `.dev` version as a prerelease, which
+    # also keeps a local gem from ever satisfying a plain `gem install ceedling`.
+    DEV = ''
+
+    # Appended at most once. A BASE that already carries the marker cannot yield
+    # `1.2.0.dev.dev`. An emptied DEV is a no-op here too, since every string ends
+    # with the empty string.
+    GEM = BASE.end_with?( DEV ) ? BASE : "#{BASE}#{DEV}"
     TAG = GEM
 
     # If run as a script print Ceedling's version to $stdout