ceedling 1.1.10 → 1.2.1

data/lib/ceedling/path_matcher.rb

@@ -0,0 +1,163 @@
+# =========================================================================
+#   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/exceptions'
+
+# Resolves a query -- a bare filename, a partial relative path, or a full/absolute
+# path -- against a collection of full filepaths, treating however much path the
+# query supplies as the thing to match, not merely a hint. A project may legitimately
+# contain two files with the same name in different directories; this class is the
+# one place that decides whether a given query is specific enough to mean exactly one
+# of them, so no caller has to fall back on guessing.
+class PathMatcher
+
+  # The single file `query` identifies in `collection`, or nil if none does.
+  # Raises a CeedlingException if `query` is insufficiently specific and more than
+  # one file in `collection` matches it -- a query is never allowed to silently pick
+  # a winner among genuinely ambiguous candidates.
+  def self.match(query, collection)
+    found = candidates(query, collection)
+
+    case found.length
+    when 0
+      nil
+    when 1
+      found.first
+    else
+      raise CeedlingException.new(ambiguous_message(query, found))
+    end
+  end
+
+  # As `.match`, but never raises. When more than one candidate matches, the winner
+  # is simply the first entry in `collection`'s own order -- callers hand this method
+  # a collection whose order already reflects real priority (e.g. a project's own
+  # `:paths` configuration order, which mirrors the order a compiler's own search
+  # paths would consult), so the earliest-listed candidate is the one a real build
+  # would actually find first.
+  #
+  # Returns [winner, others] -- `winner` is the resolved file or nil; `others` is
+  # every remaining candidate passed over, empty unless genuinely ambiguous, so a
+  # caller can decide whether anything is worth telling the user about.
+  def self.resolve(query, collection)
+    found = candidates(query, collection)
+    winner = found.first
+    others = found[1..] || []
+    return [winner, others]
+  end
+
+  # Every entry in `collection` that `query` could refer to.
+  def self.candidates(query, collection)
+    if absolute?(query)
+      target = File.expand_path(query)
+      return collection.select { |candidate| File.expand_path(candidate) == target }
+    end
+
+    query_segments = segments(query)
+    collection.select { |candidate| tail_matches?(query_segments, segments(candidate)) }
+  end
+
+  # Collapses a `..` segment in `query` against `anchor`, a directory path in the
+  # same representation as every other path this class handles (e.g. a test file's
+  # own `File.dirname`) -- one anchor segment is popped per leading `..`, so the
+  # result is an ordinary query ready for `.match`/`.resolve`/`.candidates` exactly as
+  # if it had been written that way to begin with. Only the leading `..` segments that
+  # climb above a relative anchor remain, naming a path outside it. A query with no `..` at
+  # all is returned completely untouched, so this is a no-op for the overwhelming
+  # majority of callers.
+  #
+  # `anchor: nil` means no file context exists to resolve against (e.g. a bare CLI
+  # task name, which names no file of its own) -- a `..` there can't mean anything,
+  # so it raises rather than silently mismatching or falling through to a confusing
+  # "not found" further down. `anchor: ''` is different: it means the query is
+  # already a complete, self-contained path that merely needs its own internal `..`
+  # collapsed, not prefixed onto anything else -- the shape GCC itself produces for a
+  # directory-relative quoted include, which is a full project-root-relative path
+  # left uncanonicalized.
+  #
+  # An absolute query (including a Windows drive letter) is returned unchanged --
+  # `candidates()`'s own `File.expand_path` comparison above already resolves `..`
+  # correctly for those, so reprocessing one here as anchor-relative would be wrong,
+  # not merely redundant.
+  def self.resolve_relative(query, anchor: nil)
+    return query if absolute?(query)
+
+    query_segments = segments(query)
+    return query unless query_segments.include?('..')
+
+    if anchor.nil?
+      raise CeedlingException.new(
+        "Relative path reference '..' in '#{query}' has no file context to resolve against here."
+      )
+    end
+
+    # segments() strips the empty string a leading "/" splits off, so a Unix
+    # absolute anchor's own "/"-ness has to be remembered separately here and
+    # reapplied below -- otherwise the result quietly turns into a relative-looking
+    # path carrying the same text minus its leading "/".
+    anchor_was_absolute = anchor.start_with?('/')
+    resolved = segments(anchor)
+
+    # A `..` beyond a relative anchor's own segments names a directory above it, as a
+    # project's paths outside its own root do (`../shared`), so it stays in the result.
+    # Nothing lies above an absolute anchor's root.
+    query_segments.each do |segment|
+      if segment != '..'
+        resolved << segment
+      elsif !resolved.empty? and resolved.last != '..'
+        resolved.pop
+      elsif anchor_was_absolute
+        raise CeedlingException.new("Relative path reference '..' in '#{query}' climbs above the filesystem root.")
+      else
+        resolved << '..'
+      end
+    end
+
+    joined = resolved.join('/')
+    anchor_was_absolute ? "/#{joined}" : joined
+  end
+
+  # Two filepaths correspond if the shorter one's path segments equal the longer
+  # one's own trailing segments, exactly, in order -- checked without regard for
+  # which side is shorter, since a query and a candidate can each be the more
+  # specific one depending on how each was discovered.
+  def self.correspond?(a, b)
+    segments_a = segments(a)
+    segments_b = segments(b)
+    shorter, longer = segments_a.length <= segments_b.length ? [segments_a, segments_b] : [segments_b, segments_a]
+    tail_matches?(shorter, longer)
+  end
+
+  # A Unix absolute path or one beginning with a Windows drive letter
+  def self.absolute?(path)
+    path.start_with?('/') || path.match?( /\A[A-Za-z]:[\\\/]/ )
+  end
+
+  ### Private ###
+
+  def self.segments(path)
+    path.split(/[\\\/]/).reject(&:empty?)
+  end
+  private_class_method :segments
+
+  # `query_segments` matches `candidate_segments` if the query's segments equal the
+  # candidate's own trailing segments exactly, in order -- a bare filename (one
+  # segment) matches any candidate ending in that filename; a deeper query only
+  # matches a candidate whose path actually ends the same way, not merely contains
+  # those segments somewhere.
+  def self.tail_matches?(query_segments, candidate_segments)
+    return false if query_segments.length > candidate_segments.length
+    candidate_segments.last(query_segments.length) == query_segments
+  end
+  private_class_method :tail_matches?
+
+  def self.ambiguous_message(query, candidates)
+    "Ambiguous file reference '#{query}' found. " \
+    "Include more trailing path to distinguish among: #{candidates.join(', ')}"
+  end
+  private_class_method :ambiguous_message
+
+end

data/lib/ceedling/path_mirror.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
+# =========================================================================
+
+require 'ceedling/file_path_utils'
+
+# Answers the question build output asks when it wants to avoid same-basename
+# collisions: given a resolved file and the raw (still possibly glob/decorator-laden)
+# `:paths` entries a project configured for that file's category, what subdirectory
+# should this file's build artifact live in so its place in the source tree survives
+# into the build tree? A file directly inside a configured root needs no
+# subdirectory at all; a file nested beneath one carries that nesting forward.
+class PathMirror
+
+  # The directory portion of `filepath` below whichever `roots` entry is its
+  # longest (most specific) matching ancestor, or '' if no root contains it at all
+  # -- the safe fallback that leaves such a file's build placement flat.
+  def self.relative_subdir(filepath, roots)
+    relative_subdir_from_clean_roots(filepath, clean_roots(roots))
+  end
+
+  # Strips decorators and glob specifiers from each entry in `roots`, dropping any that
+  # end up empty. A caller mirroring many files against the same `roots` list -- a whole
+  # build's worth of sources against one project's configured paths, say -- can compute
+  # this once and feed the result to `relative_subdir_from_clean_roots` for every file,
+  # rather than every file's own call re-parsing the same still-decorated list from scratch.
+  def self.clean_roots(roots)
+    roots
+      .map { |root| FilePathUtils.no_decorators(root) }
+      .reject(&:empty?)
+  end
+
+  # As `relative_subdir`, but distinguishes a file no root contains (nil) from one sitting
+  # directly in a root (''). `relative_subdir` answers '' for both, which is the right
+  # fallback for placing build output but hides the difference from a caller deciding
+  # whether a path belongs to a configured tree at all.
+  def self.relative_subdir_if_rooted(filepath, roots)
+    clean    = clean_roots( roots )
+    file_dir = File.dirname( filepath )
+
+    return nil unless clean.any? { |root| file_dir == root || file_dir.start_with?( root + '/' ) }
+
+    return relative_subdir_from_clean_roots( filepath, clean )
+  end
+
+  # A path as lowercased segments, split on either separator. One spelling for every caller
+  # that matches trailing path segments rather than whole paths, so all of them agree on
+  # what a segment is and on case folding.
+  def self.path_segments(path)
+    path.downcase.split( %r{[\\/]} ).reject(&:empty?)
+  end
+
+  # As `relative_subdir`, but takes roots already reduced by `clean_roots` instead of
+  # raw, possibly glob/decorator-laden `:paths` entries.
+  def self.relative_subdir_from_clean_roots(filepath, clean_roots)
+    file_dir = File.dirname(filepath)
+
+    matching_roots = clean_roots.select do |root|
+      file_dir == root || file_dir.start_with?(root + '/')
+    end
+
+    return '' if matching_roots.empty?
+
+    best_root = matching_roots.max_by(&:length)
+    return '' if file_dir == best_root
+
+    file_dir[(best_root.length + 1)..]
+  end
+
+end

data/lib/ceedling/plugins/plugin.rb

@@ -20,7 +20,7 @@ class Plugin
   # Override to prevent exception handling from walking & stringifying the object variables.
   # Plugin's object variables are gigantic and produce a flood of output.
   def inspect
-    return this.class.name
+    return self.class.name
   end
 
   def setup; end

data/lib/ceedling/plugins/plugin_manager.rb

@@ -63,7 +63,7 @@ class PluginManager
 
     # If we only ran basic unit tests, there's no need to prefix the failure messages with the context.
     if (@build_fail_registry.keys.size == 1 and @build_fail_registry.keys[0] == TEST_SYM)
-      @build_fail_registry.each do |context, messages|
+      @build_fail_registry.each do |_context, messages|
         messages.each {|message| failures << message}
       end
     # Otherwise, add the context to each message so the user knows the source of the failure.
@@ -102,6 +102,17 @@ class PluginManager
   def pre_runner_generate(arg_hash); execute_plugins(:pre_runner_generate, arg_hash); end
   def post_runner_generate(arg_hash); execute_plugins(:post_runner_generate, arg_hash); end
 
+  # Fire ahead of and separate from pre_compile_execute/pre_link_execute/
+  # pre_test_fixture_execute below -- once per object/executable/test, unconditionally,
+  # before TestBuildExecutor registers dependency-tracker meta or checks staleness,
+  # rather than only when a real (re)compile/link/fixture-run actually happens. A
+  # plugin swapping in its own tool for a build context (Gcov, Valgrind, Bullseye)
+  # implements these so that swap is what dependency-tracker meta reflects, not the
+  # plain tool it's about to replace.
+  def pre_test_compile_register(arg_hash); execute_plugins(:pre_test_compile_register, arg_hash); end
+  def pre_test_link_register(arg_hash); execute_plugins(:pre_test_link_register, arg_hash); end
+  def pre_test_fixture_register(arg_hash); execute_plugins(:pre_test_fixture_register, arg_hash); end
+
   def pre_compile_execute(arg_hash); execute_plugins(:pre_compile_execute, arg_hash); end
   def post_compile_execute(arg_hash); execute_plugins(:post_compile_execute, arg_hash); end
 
@@ -109,9 +120,16 @@ class PluginManager
   def post_link_execute(arg_hash); execute_plugins(:post_link_execute, arg_hash); end
 
   def pre_test_fixture_execute(arg_hash); execute_plugins(:pre_test_fixture_execute, arg_hash); end
+
+  # A plugin that recognizes why a test executable crashed sets `arg_hash[:explanation]` and,
+  # optionally, `:explanation_details` lines and an `:explanation_heading`. `:crash_notice` says
+  # whether the explanation will appear in a crash notice or only in a test failure.
+  def explain_test_crash(arg_hash); execute_plugins(:explain_test_crash, arg_hash); end
   def post_test_fixture_execute(arg_hash)
-    # Special arbitration: Raw test results are printed or taken over by plugins handling the job
-    @loginator.log( arg_hash[:shell_result][:output] ) if @configurator.plugins_display_raw_test_results
+    # Special arbitration: Raw test results are printed or taken over by plugins handling the job.
+    # A test reported from cached results was not run, so it has no output to show.
+    shell_result = arg_hash[:shell_result]
+    @loginator.log( shell_result[:output] ) if shell_result && @configurator.plugins_display_raw_test_results
 
     # Core failure detection independent of any reporting plugin
     register_build_failure( arg_hash[:context], 'Unit test failures' ) if arg_hash.dig(:results, :counts, :failed).to_i > 0
@@ -141,19 +159,17 @@ class PluginManager
   end
 
   def execute_plugins(method, *args)
-    @plugin_objects.each do |plugin|
-      begin
-        if plugin.respond_to?(method)
-          @loginator.lazy( Verbosity::OBNOXIOUS ) do 
-            @reportinator.generate_progress( "Plugin | #{camelize( plugin.name )} > :#{method}" )
-          end
-          plugin.send(method, *args)
-        end
-      rescue
-        @loginator.log( "Exception raised in plugin `#{plugin.name}` within build hook :#{method}", Verbosity::ERRORS )
-        raise # Raise again for backtrace, etc.
-      end
+    @plugin_objects.each { |plugin| execute_plugin( plugin, method, *args ) if plugin.respond_to?( method ) }
+  end
+
+  def execute_plugin(plugin, method, *args)
+    @loginator.lazy( Verbosity::OBNOXIOUS ) do
+      @reportinator.generate_progress( "Plugin | #{camelize( plugin.name )} > :#{method}" )
     end
+    plugin.send(method, *args)
+  rescue
+    @loginator.log( "Exception raised in plugin `#{plugin.name}` within build hook :#{method}", Verbosity::ERRORS )
+    raise # Raise again for backtrace, etc.
   end
 
 end

data/lib/ceedling/plugins/plugin_manager_helper.rb

@@ -18,7 +18,11 @@ class PluginManagerHelper
 		return include
   end
 
-  def instantiate_plugin(plugin, system_objects, name, root_path)
+  # All three arguments are read by the eval string below, which RuboCop cannot see
+  # into. The cop reads them as unused and offers to rename them with underscore
+  # prefixes. Accepting that rename leaves the eval referencing locals that no longer
+  # exist, so no plugin can be instantiated. Do not autocorrect this line.
+  def instantiate_plugin(plugin, system_objects, name, root_path) # rubocop:disable Lint/UnusedMethodArgument
     return eval( "#{plugin}.new(system_objects, name, root_path)" )
   end
 

data/lib/ceedling/plugins/plugin_reportinator.rb

@@ -5,14 +5,13 @@
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
-require 'erb'
 require 'ceedling/constants'
 require 'ceedling/defaults'
 require 'ceedling/exceptions'
 
 class PluginReportinator
   
-  constructor :plugin_reportinator_helper, :plugin_manager, :reportinator, :loginator
+  constructor :plugin_reportinator_helper, :plugin_manager, :reportinator, :loginator, :templateinator
 
   def setup
     @test_results_template = nil
@@ -23,7 +22,7 @@ class PluginReportinator
   end
 
   def set_system_objects(system_objects)
-    # Available for use inside ERB report rendering via binding()
+    # Available for use inside report template rendering via binding()
     @ceedling = system_objects
   end
   
@@ -39,6 +38,34 @@ class PluginReportinator
     return @reportinator.generate_heading(message)
   end
 
+  # Common preamble values every stdout test-results template needs before
+  # rendering -- centralized so sibling templates can't silently drift the
+  # way two of them once did over which of these values got computed at all.
+  def test_report_preamble(hash)
+    {
+      ignored:        hash[:results][:counts][:ignored],
+      failed:         hash[:results][:counts][:failed],
+      stdout_count:   hash[:results][:counts][:stdout],
+      header_prepend: (hash[:context] != TEST_SYM ? "#{hash[:context].to_s.upcase}: " : '')
+    }
+  end
+
+  # Reflows a possibly multi-line failure/ignore message so every physical
+  # line stays useful to whichever format is rendering it -- one template
+  # passes plain spaces to align continuation lines under a text header;
+  # another passes a repeated "file:line:test: " prefix so every line
+  # remains its own clickable reference.
+  def reflow_message(message, continuation_prefix)
+    message.each_line(chomp: true).with_index.map { |line, i| i.zero? ? line : continuation_prefix + line }.join("\n")
+  end
+
+  # Color-decorates summary-banner text green/red by overall pass/fail
+  # outcome -- shared so no sibling template can silently omit this the way
+  # one once did.
+  def decorate_summary_banner(text, failed_count)
+    @loginator.decorate(text, failed_count > 0 ? LogLabels::FAIL : LogLabels::PASS)
+  end
+
   ##
   ## Sample Test Results Output File (YAML)
   ## ======================================
@@ -99,7 +126,8 @@ class PluginReportinator
   # silencing routine build chatter still wants to see; ERRORS is the floor
   # for both, not just for a failing run. Centralized here so every plugin
   # printing post-build test results (report_tests_stdout_plugin, gcov,
-  # valgrind) agrees on the same answer instead of each hardcoding its own.
+  # bullseye, valgrind) agrees on the same answer instead of each hardcoding
+  # its own.
   def test_results_floor_verbosity
     Verbosity::ERRORS
   end
@@ -113,10 +141,11 @@ class PluginReportinator
   end
   
   def run_report(template, hash=nil, verbosity=Verbosity::NORMAL)
-    output = ERB.new( template, trim_mode: "%<>" )
+    # binding() is what exposes `hash` and this object's own methods to the template
+    output = @templateinator.render( template, binding() )
 
-    # Run the report template and log result with no log level heading
-    @loginator.log( output.result(binding()), verbosity, LogLabels::NONE )
+    # Log the rendered report with no log level heading
+    @loginator.log( output, verbosity, LogLabels::NONE )
   end
   
   #

data/lib/ceedling/plugins/plugin_reportinator_helper.rb

@@ -15,8 +15,8 @@ class PluginReportinatorHelper
   
   def fetch_results(results_path, options)
     # Create the results filepaths
-    pass_path = results_path.ext( @configurator.extension_testpass )
-    fail_path = results_path.ext( @configurator.extension_testfail )
+    pass_path = results_path.ext( @configurator.extension_testpass.primary )
+    fail_path = results_path.ext( @configurator.extension_testfail.primary )
 
     # Collect whether the results file(s) exists
     pass_exists = ( @file_wrapper.exist?( pass_path ) ? true : false )
@@ -27,7 +27,7 @@ class PluginReportinatorHelper
 
       if options[:boom]
         # Complain loudly
-        error = "Could find no test results for '#{File.basename(results_path).ext(@configurator.extension_source)}'"
+        error = "Could find no test results for '#{File.basename(results_path).ext(@configurator.extension_source.primary)}'"
         raise CeedlingException.new(error)
 
       else

data/lib/ceedling/plugins/report_log_writer_plugin.rb

@@ -0,0 +1,66 @@
+# =========================================================================
+#   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/plugins/plugin'
+require 'ceedling/constants'
+
+# Shared base for plugins that collect string fragments during a build --
+# behind a mutex, since fragments arrive from concurrent build threads --
+# and flush them to one artifact file per collected entry at post_build or
+# post_error. A subclass owns its own collection's shape (what it collects
+# and how it's keyed); this base owns the mutex discipline and the actual
+# file write, so the two responsibilities can't quietly drift apart the way
+# they previously could when each plugin hand-rolled both itself.
+class ReportLogWriterPlugin < Plugin
+
+  # `Plugin` setup()
+  def setup
+    @mutex        = Mutex.new
+    @file_wrapper = @ceedling[:file_wrapper]
+    @loginator    = @ceedling[:loginator]
+    @reportinator = @ceedling[:reportinator]
+  end
+
+  private
+
+  # Ensures <build root>/artifacts/<context>/ exists and returns the full
+  # filepath for `filename` inside it.
+  def artifact_filepath(context, filename)
+    path = File.join(PROJECT_BUILD_ARTIFACTS_ROOT, context.to_s)
+    @file_wrapper.mkdir(path)
+    File.join(path, filename)
+  end
+
+  # Logs a heading, then either reports `empty_message` or runs the
+  # caller's block to write each artifact. Both the emptiness check and the
+  # write pass happen under `@mutex` -- the same guard a subclass's own
+  # collection-time write already holds -- so a build thread still
+  # finishing its own collection can never interleave with this read/write
+  # pass the way an unguarded read previously could.
+  def flush_log(heading:, empty_message:, empty:)
+    @loginator.log(@reportinator.generate_heading(heading))
+
+    is_empty = false
+    @mutex.synchronize { is_empty = empty.call }
+
+    if is_empty
+      @loginator.log("#{empty_message}\n")
+      return
+    end
+
+    @mutex.synchronize { yield }
+
+    # Whitespace at command line after progress messages
+    @loginator.log('')
+  end
+
+  def write_artifact(filepath, contents)
+    @loginator.log(@reportinator.generate_progress("Generating artifact #{filepath}"))
+    @file_wrapper.write(filepath, contents)
+  end
+
+end

data/lib/ceedling/plugins/report_tests_stdout_plugin.rb

@@ -10,7 +10,7 @@ require 'ceedling/defaults'
 
 # Base class for stdout test-results reporting plugins.
 # Subclasses need only override the private `load_template` method to supply
-# a different ERB template string. All hook logic lives here.
+# a different template string. All hook logic lives here.
 class ReportTestsStdoutPlugin < Plugin
 
   # `Plugin` setup()
@@ -35,7 +35,10 @@ class ReportTestsStdoutPlugin < Plugin
     # Thread-safe manipulation since test fixtures can be run in child processes
     # spawned within multiple test execution threads.
     @mutex.synchronize do
-      if (result_file =~ /#{PROJECT_TEST_RESULTS_PATH}/) && !@result_list.include?(result_file)
+      # A plain substring check -- this is containment, not a pattern match,
+      # so a Regexp (even one properly escaped, per #104's own history) was
+      # never the right tool here to begin with.
+      if result_file.include?(PROJECT_TEST_RESULTS_PATH) && !@result_list.include?(result_file)
         @result_list << arg_hash[:result_file]
       end
     end
@@ -78,11 +81,21 @@ class ReportTestsStdoutPlugin < Plugin
 
   private
 
-  # Returns the ERB template string used for test results reports.
-  # Default: reads assets/template.erb from the plugin's own root path.
+  # Returns the template string used for test results reports.
+  # Default: reads assets/test_results.template from the plugin's own root path.
   # Override in a subclass to supply a different template string.
+  #
+  # Falls back to the historical assets/template.erb name so an out-of-tree plugin
+  # subclass shipping only that file keeps working. Ceedling no longer renders with
+  # ERB, so the old name describes neither the contents nor the engine, but breaking
+  # those plugins to correct a filename would be a poor trade.
   def load_template
-    return @ceedling[:file_wrapper].read( File.join( @plugin_root_path, 'assets/template.erb' ) )
+    preferred = File.join( @plugin_root_path, 'assets/test_results.template' )
+    legacy    = File.join( @plugin_root_path, 'assets/template.erb' )
+
+    path = @ceedling[:file_wrapper].exist?( preferred ) ? preferred : legacy
+
+    return @ceedling[:file_wrapper].read( path )
   end
 
 end