ceedling 1.1.2 → 1.1.4

data/lib/ceedling/generators/generator_test_results_backtrace.rb

@@ -7,13 +7,17 @@
 
 class GeneratorTestResultsBacktrace
 
-  constructor :configurator, :tool_executor, :generator_test_results, :file_path_utils, :file_wrapper
+  constructor :configurator, :tool_executor, :generator_test_results, :generator_helper,
+              :file_path_utils, :file_wrapper, :loginator
 
   def setup()
     @RESULTS_COLLECTOR = Struct.new( :passed, :failed, :ignored, :output, keyword_init:true )
+    # Alias, matching Generator's own convention for the same dependency.
+    @helper = @generator_helper
   end
 
-  # Re-runs each test case under gdb to identify which ones crashed and why.
+  # Re-runs each test case (or, for a parameterized test, each group of parameterized
+  # cases -- see `group_test_cases`) under gdb to identify which one(s) crashed and why.
   # Writes the full gdb transcript to a per-test-case log file and assembles a
   # terse crash label (signal + description, optional source line in backticks)
   # for each failing test case. Returns a modified shell_result with regenerated output.
@@ -28,98 +32,174 @@ class GeneratorTestResultsBacktrace
 
     test_name = File.basename( filename, '.*' )
 
-    # Iterate on test cases
-    test_cases.each do |test_case|
-      # Per-test-case log file: <log_path>/<context>/<test_name>/<test_case>.gdb.log
-      log_path = @file_path_utils.form_test_gdb_log( test_name, context: context, name: test_case[:test] )
-      @file_wrapper.mkdir( File.dirname( log_path ) )
+    # True once some retry group has actually shown crash evidence of its own -- an
+    # unresolved member, or (below) a group whose real status contradicts a fully clean
+    # set of matches. If this stays false across every group, the whole diagnostic never
+    # reproduced or attributed the crash the main run already detected, and none of it
+    # can be trusted -- see the fallback after the loop.
+    any_group_crashed = false
 
-      # Build the test fixture to run with our test case of interest
+    # Iterate on test cases, one sub-process run per group (see `group_test_cases`)
+    group_test_cases( test_cases ).each do |group|
+      # Build the test fixture to run with our test case (or parameterized group) of interest
       command = @tool_executor.build_command_line(
         @configurator.tools_test_backtrace_gdb, [],
         gdb_script_filepath,
         executable,
-        test_case[:test]
+        unity_filter_arg( group )
       )
       # Things are gonna go boom, so ignore booms to get output
       command[:options][:boom] = false
 
       crash_result = @tool_executor.exec( command )
 
-      # Sum execution time for each test case
+      # Sum execution time for each sub-process run
       # Note: Running tests separately increases total execution time
       shell_result[:time] += crash_result[:time].to_f()
 
-      test_output = ''
-
-      # Process single test case stats
-      case crash_result[:output]
-      # Success test case
-      when /(^#{filename}.+:PASS\s*$)/
-        test_case_results[:passed]  += 1
-        test_output = $1 # Grab regex match
-
-      # Ignored test case
-      when /(^#{filename}.+:IGNORE\s*$)/
-        test_case_results[:ignored] += 1
-        test_output = $1 # Grab regex match
-
-      when /(^#{filename}.+:FAIL(:.+)?\s*$)/
-        test_case_results[:failed]  += 1
-        test_output = $1 # Grab regex match
-
-      else # Crash failure case
-        test_case_results[:failed]  += 1
-
-        # Append full gdb output for this test case to the log
-        @file_wrapper.write( log_path, "=== #{test_case[:test]} ===\n#{crash_result[:output]}\n", 'a' )
-
-        # Collect file_name and line in which crash occurred
-        matched = crash_result[:output].match( /#{test_case[:test]}\s*\(\)\sat.+#{filename}:(\d+)\n/ )
-
-        # If we found an error report line containing `test_case() at filename.c:###` in `gdb` output
-        if matched
-          # Line number
-          line_number = matched[1]
-
-          # Build terse signal label: "[SIGNAL] Description"
-          signal_label = format_signal_label( crash_result[:output] )
+      # Buffered separately from test_case_results and only merged in afterward, since
+      # the status check below can still discard every match here in favor of a crash
+      # attribution, once the whole group has been seen.
+      group_results = @RESULTS_COLLECTOR.new( passed:0, failed:0, ignored:0, output:[] )
+      unresolved = []
+
+      # Attribute each group member its own real result line, if Unity printed one
+      group.each do |test_case|
+        case crash_result[:output]
+        # Success test case
+        when /(^#{Regexp.escape(filename)}:\d+:#{Regexp.escape(test_case[:test])}:PASS\s*$)/
+          group_results[:passed]  += 1
+          group_results[:output] << $1
+
+        # Ignored test case
+        when /(^#{Regexp.escape(filename)}:\d+:#{Regexp.escape(test_case[:test])}:IGNORE\s*$)/
+          group_results[:ignored] += 1
+          group_results[:output] << $1
+
+        when /(^#{Regexp.escape(filename)}:\d+:#{Regexp.escape(test_case[:test])}:FAIL(:.+)?\s*$)/
+          group_results[:failed]  += 1
+          group_results[:output] << $1
+
+        # No result line for this member -- either it crashed, or it never got to run
+        # because an earlier member in this same group crashed. Resolved below.
+        else
+          unresolved << test_case
+        end
+      end
 
-          # Extract the offending source line (nil for assertion crashes or when unavailable)
-          source_line = extract_source_line( crash_result[:output], test_case[:test], filename )
+      if !unresolved.empty?
+        # Prefer whichever unresolved member's own C symbol is actually named in the gdb
+        # backtrace (works regardless of position in the group); fall back to the first
+        # unresolved member if no member's symbol can be found in the transcript (e.g. a
+        # brief crash report with no frame information at all).
+        crashed_case = unresolved.find do |tc|
+          crash_result[:output].match?( /#{Regexp.escape(tc[:symbol])}\s*\(\)\sat/ )
+        end
+        crashed_case ||= unresolved.first
 
-          # Unity's test executable output is line oriented.
-          # Multi-line output is not possible (it looks like random `printf()` statements to the results parser).
-          # "Encode" newlines in multiline string to be handled by the test results parser.
-          crash_detail = source_line ? "#{NEWLINE_TOKEN}`#{source_line}`" : ''
+        # Per-test-case log file: <log_path>/<context>/<test_name>/<test_case>.gdb.log
+        log_path = @file_path_utils.form_test_gdb_log( test_name, context: context, name: crashed_case[:test] )
+        @file_wrapper.mkdir( File.dirname( log_path ) )
+        @file_wrapper.write( log_path, "=== #{crashed_case[:test]} ===\n#{crash_result[:output]}\n", 'a' )
 
-          # Log path appears on its own encoded line so the results parser treats it separately
-          test_output =
-            "#{filename}:#{line_number}:#{test_case[:test]}:FAIL: Test case crashed" \
-            " >> #{signal_label}" \
-            "#{crash_detail}" \
-            "#{NEWLINE_TOKEN}(#{log_path})"
+        unresolved.each do |test_case|
+          group_results[:failed] += 1
 
-        # Try to extract a useful label even when no crash location frame was found.
-        # A brief Windows assertion failure may report only the assertion text without frames.
-        else
-          label = format_signal_label( crash_result[:output] )
+          if !test_case.equal?( crashed_case )
+            # An earlier case in this same parameterized group already crashed the
+            # process -- this member never got a chance to run.
+            group_results[:output] <<
+              "#{filename}:#{test_case[:line_number]}:#{test_case[:test]}:FAIL: " \
+              "Test case not run -- an earlier case in this parameterized test group crashed"
+            next
+          end
 
-          if !label.empty?
-            test_output =
-              "#{filename}:#{test_case[:line_number]}:#{test_case[:test]}:FAIL: Test case crashed" \
-              " >> #{label}" \
+          # Collect file_name and line in which crash occurred.
+          # Match against the actual C symbol (`:symbol`), not the human-facing test name
+          # (`:test`): a parameterized test case crashes inside a generated wrapper function
+          # (`runner_args<N>_<test>`), not a function literally named `<test>(<args>)`.
+          matched = crash_result[:output].match( /#{Regexp.escape(test_case[:symbol])}\s*\(\)\sat.+#{filename}:(\d+)\n/ )
+
+          # If we found an error report line containing `test_case() at filename.c:###` in `gdb` output
+          if matched
+            # Line number
+            line_number = matched[1]
+
+            # Build terse signal label: "[SIGNAL] Description"
+            signal_label = format_signal_label( crash_result[:output] )
+
+            # Extract the offending source line (nil for assertion crashes or when unavailable)
+            source_line = extract_source_line( crash_result[:output], test_case[:symbol], filename )
+
+            # Unity's test executable output is line oriented.
+            # Multi-line output is not possible (it looks like random `printf()` statements to the results parser).
+            # "Encode" newlines in multiline string to be handled by the test results parser.
+            crash_detail = source_line ? "#{NEWLINE_TOKEN}`#{source_line}`" : ''
+
+            # Log path appears on its own encoded line so the results parser treats it separately
+            group_results[:output] <<
+              "#{filename}:#{line_number}:#{test_case[:test]}:FAIL: Test case crashed" \
+              " >> #{signal_label}" \
+              "#{crash_detail}" \
               "#{NEWLINE_TOKEN}(#{log_path})"
+
+          # Try to extract a useful label even when no crash location frame was found.
+          # A brief Windows assertion failure may report only the assertion text without frames.
           else
-            test_output =
-              "#{filename}:#{test_case[:line_number]}:#{test_case[:test]}:FAIL: " \
-              "Test case crashed (failed to extract `gdb` report)" \
-              "#{NEWLINE_TOKEN}(#{log_path})"
+            label = format_signal_label( crash_result[:output] )
+
+            if !label.empty?
+              group_results[:output] <<
+                "#{filename}:#{test_case[:line_number]}:#{test_case[:test]}:FAIL: Test case crashed" \
+                " >> #{label}" \
+                "#{NEWLINE_TOKEN}(#{log_path})"
+            else
+              group_results[:output] <<
+                "#{filename}:#{test_case[:line_number]}:#{test_case[:test]}:FAIL: " \
+                "Test case crashed (failed to extract `gdb` report)" \
+                "#{NEWLINE_TOKEN}(#{log_path})"
+            end
           end
         end
       end
 
-      test_case_results[:output] << test_output
+      # Every member in this group resolved via a matched result line -- but gdb
+      # normally exits successfully after handling a crash regardless of what happened
+      # to the debuggee, so a clean-looking group here is a weaker signal than it is for
+      # `do_simple`. Still checked for the same reason: a diagnostic retry's own real
+      # status contradicting a fully clean set of matches is never trustworthy, whatever
+      # tool produced it.
+      if unresolved.empty? && @helper.test_crash?( filename, executable, crash_result )
+        group_results = @RESULTS_COLLECTOR.new(
+          passed: 0, ignored: 0, failed: group.size,
+          output: group.map { |test_case|
+            "#{filename}:#{test_case[:line_number]}:#{test_case[:test]}:FAIL: Test case crashed" \
+            " >> diagnostic retry's own exit status contradicts its reported clean result"
+          }
+        )
+        unresolved = group # non-empty now, marks this group as having shown crash evidence
+      end
+
+      any_group_crashed ||= !unresolved.empty?
+
+      test_case_results[:passed]  += group_results[:passed]
+      test_case_results[:ignored] += group_results[:ignored]
+      test_case_results[:failed]  += group_results[:failed]
+      test_case_results[:output].concat( group_results[:output] )
+    end
+
+    # No retry group, across the entire file, ever showed real crash evidence, yet this
+    # method only runs because the main run was already established as a crash. An
+    # all-clean diagnostic must never be allowed to overrule that -- fall back to the
+    # same whole-file crash-as-failure construction the :none backtrace setting uses.
+    unless any_group_crashed
+      @loginator.log(
+        "Diagnostic retry for `#{File.basename(executable)}` could not reproduce the crash " \
+        "already detected on the main run -- reporting the original crash rather than trusting " \
+        "an all-clear diagnostic that contradicts it.",
+        Verbosity::ERRORS, LogLabels::CRASH
+      )
+      return @generator_test_results.create_crash_failure( filename, shell_result, test_cases )
     end
 
     # Reset shell result exit code and output
@@ -135,7 +215,8 @@ class GeneratorTestResultsBacktrace
     return shell_result
   end
 
-  # Re-runs each test case individually to determine which ones crashed.
+  # Re-runs each test case (or, for a parameterized test, each group of parameterized
+  # cases -- see `group_test_cases`) individually to determine which one(s) crashed.
   # For crash cases, captures any extra output from the test binary (e.g.
   # assertion messages on stderr) and includes it in the failure report.
   # Returns a modified shell_result with regenerated output.
@@ -146,50 +227,109 @@ class GeneratorTestResultsBacktrace
     # Reset time
     shell_result[:time] = 0
 
-    # Iterate on test cases
-    test_cases.each do |test_case|
-      # Build the test fixture to run with our test case of interest
+    # True once some retry group has actually shown crash evidence of its own -- a
+    # member with no result line, or (below) a group whose real status contradicts a
+    # fully clean set of matches. If this stays false across every group, the whole
+    # diagnostic never reproduced or attributed the crash the main run already
+    # detected, and none of it can be trusted -- see the fallback after the loop.
+    any_group_crashed = false
+
+    # Iterate on test cases, one sub-process run per group (see `group_test_cases`)
+    group_test_cases( test_cases ).each do |group|
+      # Build the test fixture to run with our test case (or parameterized group) of interest
       command = @tool_executor.build_command_line(
         @configurator.tools_test_fixture_simple_backtrace, [],
         executable,
-        test_case[:test]
+        unity_filter_arg( group )
       )
       # Things are gonna go boom, so ignore booms to get output
       command[:options][:boom] = false
 
       crash_result = @tool_executor.exec( command )
 
-      # Sum execution time for each test case
+      # Sum execution time for each sub-process run
       # Note: Running tests separately increases total execution time
       shell_result[:time] += crash_result[:time].to_f()
 
-      # Process single test case stats
-      case crash_result[:output]
-      # Success test case
-      when /(^#{filename}.+:PASS\s*$)/
-        test_case_results[:passed]  += 1
-        test_output = $1 # Grab regex match
-
-      # Ignored test case
-      when /(^#{filename}.+:IGNORE\s*$)/
-        test_case_results[:ignored] += 1
-        test_output = $1 # Grab regex match
-
-      when /(^#{filename}.+:FAIL(:.+)?\s*$)/
-        test_case_results[:failed]  += 1
-        test_output = $1 # Grab regex match
-
-      else # Crash failure case
-        test_case_results[:failed]  += 1
-
-        # Collect any non-result, non-blank lines (e.g. assertion messages on stderr)
-        extra = extract_simple_crash_output( crash_result[:output], filename )
-        test_output = "#{filename}:#{test_case[:line_number]}:#{test_case[:test]}:FAIL: Test case crashed"
-        test_output += " >> #{extra.join(NEWLINE_TOKEN)}" unless extra.empty?
+      # Buffered separately from test_case_results and only merged in afterward, since
+      # the status check below can still discard every match here in favor of a crash
+      # attribution, once the whole group has been seen.
+      group_results = @RESULTS_COLLECTOR.new( passed:0, failed:0, ignored:0, output:[] )
+      crashed = false # Has the actual crash in this group already been attributed?
+
+      # Attribute each group member its own real result line, if Unity printed one
+      group.each do |test_case|
+        case crash_result[:output]
+        # Success test case
+        when /(^#{Regexp.escape(filename)}:\d+:#{Regexp.escape(test_case[:test])}:PASS\s*$)/
+          group_results[:passed]  += 1
+          group_results[:output] << $1
+
+        # Ignored test case
+        when /(^#{Regexp.escape(filename)}:\d+:#{Regexp.escape(test_case[:test])}:IGNORE\s*$)/
+          group_results[:ignored] += 1
+          group_results[:output] << $1
+
+        when /(^#{Regexp.escape(filename)}:\d+:#{Regexp.escape(test_case[:test])}:FAIL(:.+)?\s*$)/
+          group_results[:failed]  += 1
+          group_results[:output] << $1
+
+        # No result line for this member -- either it crashed, or it never got to run
+        # because an earlier member in this same group crashed.
+        else
+          group_results[:failed] += 1
+
+          if crashed
+            group_results[:output] <<
+              "#{filename}:#{test_case[:line_number]}:#{test_case[:test]}:FAIL: " \
+              "Test case not run -- an earlier case in this parameterized test group crashed"
+          else
+            crashed = true
+            # Collect any non-result, non-blank lines (e.g. assertion messages on stderr)
+            extra = extract_simple_crash_output( crash_result[:output], filename )
+            test_output = "#{filename}:#{test_case[:line_number]}:#{test_case[:test]}:FAIL: Test case crashed"
+            test_output += " >> #{extra.join(NEWLINE_TOKEN)}" unless extra.empty?
+            group_results[:output] << test_output
+          end
+        end
       end
 
-      # Collect up real and stand-in test results output
-      test_case_results[:output] << test_output
+      # Every member in this group resolved via a matched result line -- but a diagnostic
+      # retry running through its own, separately-configured tool (e.g. without the main
+      # :test_fixture's sanitizer options) can complete cleanly and print a legitimate-
+      # looking PASS even when it isn't a trustworthy stand-in for what actually happened.
+      # The same real-status check the main run itself relies on applies here too.
+      if !crashed && @helper.test_crash?( filename, executable, crash_result )
+        crashed = true
+        group_results = @RESULTS_COLLECTOR.new(
+          passed: 0, ignored: 0, failed: group.size,
+          output: group.map { |test_case|
+            "#{filename}:#{test_case[:line_number]}:#{test_case[:test]}:FAIL: Test case crashed" \
+            " >> diagnostic retry's own exit status contradicts its reported clean result"
+          }
+        )
+      end
+
+      any_group_crashed ||= crashed
+
+      test_case_results[:passed]  += group_results[:passed]
+      test_case_results[:ignored] += group_results[:ignored]
+      test_case_results[:failed]  += group_results[:failed]
+      test_case_results[:output].concat( group_results[:output] )
+    end
+
+    # No retry group, across the entire file, ever showed real crash evidence, yet this
+    # method only runs because the main run was already established as a crash. An
+    # all-clean diagnostic must never be allowed to overrule that -- fall back to the
+    # same whole-file crash-as-failure construction the :none backtrace setting uses.
+    unless any_group_crashed
+      @loginator.log(
+        "Diagnostic retry for `#{File.basename(executable)}` could not reproduce the crash " \
+        "already detected on the main run -- reporting the original crash rather than trusting " \
+        "an all-clear diagnostic that contradicts it.",
+        Verbosity::ERRORS, LogLabels::CRASH
+      )
+      return @generator_test_results.create_crash_failure( filename, shell_result, test_cases )
     end
 
     # Reset shell result exit code and output
@@ -208,6 +348,34 @@ class GeneratorTestResultsBacktrace
   ### Private ###
   private
 
+  # Groups test cases so each parameterized test's cases are isolated together as one
+  # sub-process run instead of one run per case. Unity's `-n`/`-f` command-line filter
+  # parser treats a comma as a separator between multiple OR'd filter clauses, so an
+  # exact filter can never match a parameterized case's runtime name once it has more
+  # than one argument (e.g. `name(5, 3, 2)`). Grouping by base name and matching each
+  # member's own result line out of the group's single shared sub-run output sidesteps
+  # that limitation entirely. Non-parameterized test cases are unaffected: each forms
+  # its own single-member group, isolated exactly as before.
+  def group_test_cases(test_cases)
+    test_cases.group_by { |test_case| test_case[:test].sub(/\(.*\)\z/, '') }.values
+  end
+
+  # Builds the Unity command-line filter argument for isolating one group (see
+  # `group_test_cases`). A non-parameterized (single-member, no-args) group is isolated
+  # with an exact-match filter as before. A parameterized group is isolated with a
+  # non-strict prefix filter on its shared base name -- the only reliable way to select
+  # such a group, since its members' runtime names contain commas.
+  def unity_filter_arg(group)
+    test_name = group.first[:test]
+
+    if test_name.include?('(')
+      base_name = test_name.sub(/\(.*\)\z/, '')
+      %(-f "#{base_name}")
+    else
+      %(-n "#{test_name}")
+    end
+  end
+
   # Builds a terse crash label from gdb output.
   # Rules:
   #   - Named signal explicitly in output → "[SIGNAL] Description"

data/lib/ceedling/generators/generator_test_runner.rb

@@ -62,8 +62,26 @@ class GeneratorTestRunner
     # Unity's runner generator `find_tests()` produces an array of hashes with the following keys...
     # { test:, args:, call:, params:, line_number: }
 
-    # For external use of test case names and line numbers, keep only those pieces of info
-    @test_cases = @test_cases_internal.map {|hash| hash.slice( :test, :line_number )}
+    # For external use, reduce down to test name, runtime C symbol, and line number.
+    # A parameterized test (`:args` populated) is expanded into one entry per TEST_CASE /
+    # TEST_RANGE / TEST_MATRIX row, since Unity's generated runner registers each invocation
+    # under its own name (matching `generate_test_runner.rb`'s `"#{test}(#{args})"` naming) and
+    # runs it through its own wrapper function (`runner_args<N>_<test>`). Collapsing these to a
+    # single bare-name entry breaks exact-match test case isolation (crash handling) for
+    # parameterized tests.
+    @test_cases = @test_cases_internal.flat_map do |hash|
+      if hash[:args].nil? || hash[:args].empty?
+        [ { test: hash[:test], symbol: hash[:test], line_number: hash[:line_number] } ]
+      else
+        hash[:args].each_with_index.map do |args, idx|
+          {
+            test:        "#{hash[:test]}(#{args})",
+            symbol:      "runner_args#{idx + 1}_#{hash[:test]}",
+            line_number: hash[:line_number]
+          }
+        end
+      end
+    end
   end
 
   def extract_test_cases(source_contents)

data/lib/ceedling/includes/includes.rb

@@ -32,10 +32,15 @@ class Includes
         else raise ArgumentError, "Unknown Include type: #{include.class}"
         end
 
-      {
+      hash = {
         'type' => type,
         'filepath' => include.filepath,
       }
+      # `include_path` is only ever meaningful on a reconciled SystemInclude, so it's
+      # written only when actually set -- a cached build's YAML stays uncluttered for
+      # the common, plain case.
+      hash['include_path'] = include.include_path if include.include_path
+      hash
     end
   end
 
@@ -63,11 +68,11 @@ class Includes
       
       case hash['type']
       when 'user'
-        UserInclude.new(hash['filepath'])
+        UserInclude.new(hash['filepath'], include_path: hash['include_path'])
       when 'mock'
         MockInclude.new(hash['filepath'])
       when 'system'
-        SystemInclude.new(hash['filepath'])
+        SystemInclude.new(hash['filepath'], include_path: hash['include_path'])
       else
         raise ArgumentError, "Invalid include type: #{hash['type']}. Must be 'user' or 'system'"
       end
@@ -153,6 +158,16 @@ class Includes
   # Compares bare includes against user and system includes and applies the following rules:
   # 1. Intersection of bare includes and system includes.
   # 2. Intersection of bare includes and user includes.
+  #
+  # A matched system include's `filepath` is its real, resolved location (possibly
+  # absolute), which is what identity and deduplication need but is wrong to render
+  # verbatim into a generated file. Each matched system include is therefore rebuilt
+  # carrying `include_path:` recovered from `bare` -- the original, as-written directive
+  # text -- via `best_bare_match`, so `<sys/stat.h>` renders as written instead of
+  # collapsing to `<stat.h>`. User includes are left untouched; unlike a system header's
+  # `<...>` text, a quoted include's own bare-includes pass can be resolved by GCC's
+  # directory-relative search before reconciliation ever sees it, so `bare` isn't a
+  # reliable source of "the literal, as-written spelling" for a user include.
   def self.reconcile(bare:, user:, system:)
     # Validate input types
 
@@ -179,10 +194,15 @@ class Includes
     # Create set of bare include filenames for O(1) lookup
     bare_filenames = Set.new(bare.map(&:filename))
 
-    # Intersect system includes with bare includes based on filename.
-    # Keep system includes that have matching filenames in bare list.
+    # Intersect system includes with bare includes based on filename, then rebuild each
+    # matched system include carrying the original, as-written directive spelling
+    # recovered from bare via best_bare_match, since filepath alone (the real, resolved
+    # location) is wrong to render verbatim.
     system_includes = system.select do |include|
       bare_filenames.include?(include.filename)
+    end.map do |include|
+      original = best_bare_match(bare, include.filepath)
+      SystemInclude.new(include.filepath, include_path: original.filepath)
     end
 
     # Intersect user includes with bare includes based on filename.
@@ -196,6 +216,36 @@ class Includes
     return (system_includes + user_includes)
   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 either a bare entry or its candidate may be the one carrying less path.
+  def self.paths_correspond?(a, b)
+    segments_a = a.split(/[\\\/]/).reject(&:empty?)
+    segments_b = b.split(/[\\\/]/).reject(&:empty?)
+    shorter, longer = segments_a.length <= segments_b.length ? [segments_a, segments_b] : [segments_b, segments_a]
+    return longer.last(shorter.length) == shorter
+  end
+  private_class_method :paths_correspond?
+
+  # Finds the bare entry that best identifies a resolved system include's original,
+  # as-written spelling. A bare entry carries no information about whether its own
+  # #include was quoted or bracketed, so a project's own same-named quoted include
+  # (`#include "stat.h"`) can sit in `bare` right alongside a system one
+  # (`#include <sys/stat.h>`). Preferring the *longest* path correspondence, rather than
+  # merely the first one found, keeps a short, unrelated bare entry -- which trivially
+  # "corresponds" to any longer resolved path ending in the same filename -- from
+  # shadowing the correct, more specific entry. Falls back to the longest same-filename
+  # candidate, even without path correspondence, only when the compiler's real
+  # search-path structure doesn't literally match the directive's own spelling (a
+  # symlinked or vendored include root, for instance).
+  def self.best_bare_match(bare, filepath)
+    candidates = bare.select { |bare_include| bare_include.filename == File.basename(filepath) }
+    corresponding = candidates.select { |bare_include| paths_correspond?(bare_include.filepath, filepath) }
+    pool = corresponding.empty? ? candidates : corresponding
+    return pool.max_by { |bare_include| bare_include.filepath.split(/[\\\/]/).reject(&:empty?).length }
+  end
+  private_class_method :best_bare_match
+
   # Sort list so system includes are at the beginning
   # (Best practice)
   def self.sort(includes)
@@ -216,6 +266,7 @@ class Include
   attr_reader :filepath
   attr_reader :filename
   attr_reader :path
+  attr_reader :include_path
 
   # Initialize an Include object from a C include statement or simple filepath.
   #
@@ -224,18 +275,21 @@ class Include
   #  - #include <stdio.h>
   #  - A quoted/bracketed filepath (e.g., '"header.h"' or <stdio.h>')
   #  - A plain filepath (e.g., 'path/to/header.h')
-  # @param use_path [Boolean] (default: false)
-  #  - If true, use the full filepath in the include directive
-  #  - If false, use only the filename
+  # @param include_path [String, nil] (default: nil)
+  #  - When set, this exact spelling is used in the include directive, taking
+  #    precedence over `filepath`/`filename`. This exists for a reconciled
+  #    SystemInclude, whose `filepath` is deliberately the header's real, resolved
+  #    location (needed elsewhere for identity -- see `Includes.sanitize!`) rather than
+  #    the original, as-written directive text a reconciled render needs.
   # @raise [ArgumentError] If the statement is empty or becomes empty after cleaning
-  def initialize(statement, use_path: false)
+  def initialize(statement, include_path: nil)
     @filepath = clean(statement)
 
     raise ArgumentError, "Empty include statement" if @filepath.empty?
 
     @filename = File.basename(@filepath)
     @path = File.dirname(@filepath)
-    @use_path = use_path
+    @include_path = clean(include_path) if include_path
   end
 
   # Method specialized by subclasses
@@ -294,7 +348,8 @@ class Include
 
   # Returns the configured entry to use in the include directive
   def include()
-    @use_path ? @filepath : @filename
+    return @include_path if @include_path
+    @filename
   end
 
   private

data/lib/ceedling/objects.yml

@@ -249,8 +249,10 @@ generator_test_results_backtrace:
      - configurator
      - tool_executor
      - generator_test_results
+     - generator_helper
      - file_path_utils
      - file_wrapper
+     - loginator
 
 generator_test_results_sanity_checker:
   compose:
@@ -312,6 +314,7 @@ preprocessinator_includes_handler:
     - tool_executor
     - parsing_parcels
     - file_wrapper
+    - file_path_utils
     - yaml_wrapper
     - loginator
     - reportinator
@@ -354,6 +357,8 @@ c_extractor:
     - c_extractor_functions
     - c_extractor_preprocessing
     - c_extractor_definitions
+    - configurator
+    - loginator
 
 partializer_config:
   compose: