ceedling 1.1.10 → 1.2.1

data/lib/ceedling/preprocess/preprocessinator_includes_handler.rb

@@ -6,6 +6,7 @@
 # =========================================================================
 
 require 'ceedling/includes/includes'
+require 'ceedling/path_matcher'
 require 'ceedling/preprocess/preprocessinator_bare_includes_extractor'
 require 'ceedling/preprocess/preprocessinator_line_marker_includes_extractor'
 require 'ceedling/preprocess/c_preprocessor_conditionals'
@@ -22,6 +23,7 @@ class PreprocessinatorIncludesHandler
     :file_path_utils,
     :yaml_wrapper,
     :parsing_parcels,
+    :quote_include_isolator,
     :loginator,
     :reportinator
   )
@@ -31,87 +33,19 @@ class PreprocessinatorIncludesHandler
     @line_marker_includes_extractor = @preprocessinator_line_marker_includes_extractor
   end
 
+  # GCC's make rule (-M -MG -MP) for an isolated copy of `filepath`, listing every header
+  # the file names. Only Ceedling's vendor paths are searched, which serves a Partials
+  # directive macro, and a header not found is taken as one to be generated. A macro
+  # another header defines is invisible here, so an #include it guards can drop out; the
+  # text scan and computed #includes make up for that. Nil when the run gives no rule at
+  # all: errors in the file's own code still give one, so the tool itself failed.
   def extract_bare_includes(test:, filepath:, search_paths:, flags:, defines:)
-    filename = File.basename(filepath)
-
-    msg = @reportinator.generate_module_progress(
-      operation: "Extracting bare #includes via preprocessing from",
-      module_name: test,
-      filename: filename
-    )
-    @loginator.log( msg, Verbosity::OBNOXIOUS )
-
-    # Creation:
-    #  - This output is created with the -MM -MG -MP command line options.
-    #  - Limited search paths are used towards shallow extracting of only the user #include statements of the file.
-    #    This preprocessor mode assumes any includes discovered outside of a search path will be generated.
-    #
-    # Notes:
-    #  - This approach can have gaps with advacnced user-level macros like `#include <MACRO>`.
-    #    By including Ceedling's vendor search path, we support Partials macros of this sort.
-    #  - Gaps can be minimized with proper defines in the project file. However, needed, complex macros
-    #    located in other header files could still gum up the works.
-    #  - Many errors can occur but may not necessarily prevent usable results.
-    #
-    # GCC's quoted #include resolution always checks the directory of the file it's currently
-    # processing, independent of search paths -- a real sibling header on disk is opened and
-    # recursed into regardless of the restricted search paths above. Staging an isolated,
-    # sibling-free copy of the file being scanned keeps this pass's output limited to genuine
-    # top-level #include statements only. The isolation directory is minted directly inside the
-    # test's own preprocess-files build directory (already created in an earlier build stage) --
-    # no dedicated subdirectory or filename-based naming, to keep the resulting path as short as
-    # possible for platforms with tight path length limits.
-    isolation_parent = @file_path_utils.form_test_preprocess_files_path( test )
-    isolation_dir = @file_wrapper.mkdir_tmp( nil, isolation_parent )
-    isolated_filepath = File.join( isolation_dir, filename )
-
-    begin
-      @file_wrapper.cp( filepath, isolated_filepath )
-
-      msg = @reportinator.generate_module_progress(
-        operation: "Isolating a sibling-free copy for bare-includes extraction at",
-        module_name: test,
-        filename: isolated_filepath
-      )
-      @loginator.log( msg, Verbosity::OBNOXIOUS )
-
-      command =
-        @tool_executor.build_command_line(
-          @configurator.tools_test_bare_includes_preprocessor,
-          # No additional arguments
-          [],
-          # Argument replacement
-          isolated_filepath,
-          defines,
-          flags,
-          search_paths
-        )
-
-      # Assume possible errors so we have best shot at extracting results from preprocessing.
-      # Full code compilation will catch any breaking code errors
-      command[:options][:boom] = false
-      shell_result = @tool_executor.exec( command )
-    ensure
-      @file_wrapper.rm_rf( isolation_dir )
-    end
-
-    make_rules = shell_result[:output]
-
-    # Do not check exit code for success. In some error conditions we still get usable output.
-    # Look for the first line of the make rule output.
-    if not make_rules =~ PreprocessinatorBareIncludesExtractor::MAKE_RULE_MATCHER
-      @loginator.lazy( Verbosity::DEBUG ) do
-        "Preprocessor bare #include extraction failed: #{shell_result[:output]}"
-      end
-      return []
-    end
-
-    includes = PreprocessinatorBareIncludesExtractor.extract_includes( make_rules )
-    includes = clean_self_reference(filepath, includes)
-
-    header = "Extracted bare #includes from #{filepath}:"
-    @loginator.log_list( includes, header, Verbosity::DEBUG )
+    _log_extraction_progress( 'Extracting bare #includes via preprocessing from', test, filepath )
+    output = run_bare_includes_preprocessor( test, filepath, [defines, flags, search_paths] )
+    return log_bare_failure( filepath, output ) unless output.to_s.match?( PreprocessinatorBareIncludesExtractor::MAKE_RULE_MATCHER )
 
+    includes = clean_self_reference( filepath, PreprocessinatorBareIncludesExtractor.extract_includes( output ) )
+    @loginator.log_list( includes, "Extracted bare #includes from #{filepath}:", Verbosity::DEBUG )
     return includes
   end
 
@@ -135,8 +69,9 @@ class PreprocessinatorIncludesHandler
   def extract_bare_includes_from_text(filepath:)
     includes = []
 
-    # Open in binary mode: code_lines applies clean_encoding per-line, but each_line
-    # itself can raise on invalid byte sequences before clean_encoding is reached.
+    # Open in binary mode: code_lines cleans the whole buffer via clean_encoding
+    # before ever splitting into lines, but a text-mode read could itself raise
+    # on invalid byte sequences before clean_encoding gets the chance.
     @file_wrapper.open(filepath, 'rb') do |input|
       @parsing_parcels.code_lines( input ) do |line|
         _include = @include_factory.user_include_from_directive( line ) ||
@@ -148,104 +83,82 @@ class PreprocessinatorIncludesHandler
     return clean_self_reference( filepath, includes )
   end
 
-  def extract_user_includes_preprocess(name:, filepath:, preprocessed_filepath:)
-    includes = []
-
-    filename = File.basename(filepath)
+  # User and system extraction are the same shape twice over -- once against the
+  # accurate directives-only line-marker stream, once against the original file's own
+  # text as a fallback. The public methods below stay as the four call sites callers
+  # and specs know; the two private helpers hold the body each pair shares.
 
-    msg = @reportinator.generate_module_progress(
-      operation: "Extracting user #includes from preprocessed output",
-      module_name: name,
-      filename: filename
+  def extract_user_includes_preprocess(name:, filepath:, preprocessed_filepath:)
+    _log_extraction_progress( 'Extracting user #includes from preprocessed output', name, filepath )
+
+    # No depth limit: a user include matters however deeply it nests. `test:` lets the
+    # extractor strip this test's own mock subdirectory off a resolved mock include.
+    includes = @line_marker_includes_extractor.extract_includes_from_file(
+      preprocessed_filepath,
+      PreprocessinatorLineMarkerIncludesExtractor::USER,
+      test: name
     )
-    @loginator.log(msg, Verbosity::OBNOXIOUS)
 
-    includes = 
-      @line_marker_includes_extractor.extract_includes_from_file(
-        preprocessed_filepath,
-        PreprocessinatorLineMarkerIncludesExtractor::USER
-        # Note: No limit to max depth to search for user includes
-      )
-
-    return clean_self_reference( filepath, includes )
+    clean_self_reference( filepath, includes )
   end
 
-  def extract_user_includes_from_text(name:, filepath:, defines: [])
-    includes = []
-
-    filename = File.basename(filepath)
-
-    msg = @reportinator.generate_module_progress(
-      operation: "Extracting user #includes from original file using fallback method",
-      module_name: name,
-      filename: filename
+  def extract_system_includes_preprocess(name:, filepath:, preprocessed_filepath:)
+    _log_extraction_progress( 'Extracting system #includes from preprocessed output', name, filepath )
+
+    # A practical ceiling: system headers nest deeply through their own wrappers and
+    # everything past a handful of levels is noise, not a project dependency.
+    includes = @line_marker_includes_extractor.extract_includes_from_file(
+      preprocessed_filepath,
+      PreprocessinatorLineMarkerIncludesExtractor::SYSTEM,
+      SYSTEM_INCLUDE_MAX_DEPTH
     )
-    @loginator.log( msg, Verbosity::OBNOXIOUS, LogLabels::WARNING )
-
-    cond_tracker = CPreprocessorConditionals.new( defines )
-
-    # Open in binary mode: code_lines applies clean_encoding per-line, but each_line
-    # itself can raise on invalid byte sequences before clean_encoding is reached.
-    @file_wrapper.open(filepath, 'rb') do |input|
-      @parsing_parcels.code_lines( input ) do |line|
-        cond_tracker.process_directive( line )
-        next unless cond_tracker.active?
-        _include = @include_factory.user_include_from_directive( line )
-        includes << _include if !_include.nil?
-      end
-    end
 
-    return clean_self_reference( filepath, includes )
+    clean_self_reference( filepath, includes )
   end
 
-  def extract_system_includes_preprocess(name:, filepath:, preprocessed_filepath:)
-    includes = []
-
-    filename = File.basename(filepath)
+  # The user files a preprocessor's output entered, from its line markers. Any output
+  # that keeps them serves: directives-only output, or a full -E expansion.
+  def extract_preprocessed_dependencies(preprocessed_filepath:)
+    return @line_marker_includes_extractor.extract_entered_files_from_file( preprocessed_filepath )
+  end
 
-    msg = @reportinator.generate_module_progress(
-      operation: "Extracting system #includes from preprocessed output",
-      module_name: name,
-      filename: filename
+  # Resolve every `#include` in the original file whose target is a macro invocation
+  # rather than a literal `"..."` / `<...>` filename. Neither bare pass above can see
+  # such a directive: the gcc dep pass runs against an isolated copy and can't evaluate
+  # a sibling-header guard around it, and the text scan has no literal filename to
+  # match. A real preprocessor pass DID resolve it -- it opened the header and emitted
+  # an ordinary entering line marker. That pass is directives-only output, or for a test
+  # file in fallback, a plain expansion read as a best effort. This method finds each
+  # non-literal `#include`'s source line, then asks the line-marker extractor which
+  # header the preprocessor entered at that line, and returns those as base `Include`
+  # objects to union into `bare` (see Preprocessinator#preprocess_file_includes_common).
+  # Meaningful only with line-marker output to read; a nil `directives_only_filepath`
+  # (a header in fallback, or a per-file failure) yields an empty list -- a documented
+  # limitation.
+  #
+  # @return [Array<Include>] base Include objects, one per resolved computed #include
+  def extract_computed_includes(filepath:, directives_only_filepath:)
+    return [] if directives_only_filepath.nil?
+
+    computed_lines = computed_include_source_lines( filepath )
+    return [] if computed_lines.empty?
+
+    resolved = @line_marker_includes_extractor.resolve_computed_includes(
+      preprocessed_filepath: directives_only_filepath,
+      source_basename:       File.basename( filepath ),
+      source_lines:          computed_lines
     )
-    @loginator.log(msg, Verbosity::OBNOXIOUS)
 
-    includes = 
-      @line_marker_includes_extractor.extract_includes_from_file(
-        preprocessed_filepath,
-        PreprocessinatorLineMarkerIncludesExtractor::SYSTEM,
-        5 # Practical max depth limit for system headers (to avoid noisy length)
-      )
+    includes = resolved.values.map { |path| Include.new( path ) }
+    clean_self_reference( filepath, includes )
+  end
 
-    return clean_self_reference( filepath, includes )
+  def extract_user_includes_from_text(name:, filepath:, defines: [])
+    _extract_includes_from_text( :user_include_from_directive, 'user', name: name, filepath: filepath, defines: defines )
   end
 
   def extract_system_includes_from_text(name:, filepath:, defines: [])
-    includes = []
-
-    filename = File.basename(filepath)
-
-    msg = @reportinator.generate_module_progress(
-      operation: "Extracting system #includes from original file using fallback method",
-      module_name: name,
-      filename: filename
-    )
-    @loginator.log( msg, Verbosity::OBNOXIOUS, LogLabels::WARNING )
-
-    cond_tracker = CPreprocessorConditionals.new( defines )
-
-    # Open in binary mode: code_lines applies clean_encoding per-line, but each_line
-    # itself can raise on invalid byte sequences before clean_encoding is reached.
-    @file_wrapper.open(filepath, 'rb') do |input|
-      @parsing_parcels.code_lines( input ) do |line|
-        cond_tracker.process_directive( line )
-        next unless cond_tracker.active?
-        _include = @include_factory.system_include_from_directive( line )
-        includes << _include if !_include.nil?
-      end
-    end
-
-    return clean_self_reference( filepath, includes )
+    _extract_includes_from_text( :system_include_from_directive, 'system', name: name, filepath: filepath, defines: defines )
   end
 
   # Write to disk a yaml representation of a list of includes
@@ -270,6 +183,112 @@ class PreprocessinatorIncludesHandler
   ### Private ###
   private
 
+  # GCC's quoted #include resolution always checks the directory of the file it is
+  # processing, whatever the search paths say, so a real sibling header would be opened and
+  # followed. An isolated, sibling-free copy keeps the rule to the file's own #includes.
+  # The copy sits directly in the test's preprocess directory, with no name drawn from the
+  # file, to keep paths short where their length is limited.
+  def run_bare_includes_preprocessor(test, filepath, tool_args)
+    output = nil
+    @quote_include_isolator.within( parent: @file_path_utils.form_test_preprocess_files_path( test ), files: [filepath] ) do |isolation|
+      output = exec_bare_includes_tool( test, isolation.copy_of( filepath ), tool_args )
+    end
+    return output
+  end
+
+  # Errors in the file's own code still leave a usable rule, so a failing run's output is
+  # read all the same
+  def exec_bare_includes_tool(test, isolated_filepath, tool_args)
+    operation = 'Isolating a sibling-free copy for bare-includes extraction at'
+    @loginator.log( @reportinator.generate_module_progress( operation: operation, module_name: test, filename: isolated_filepath ), Verbosity::OBNOXIOUS )
+
+    command = @tool_executor.build_command_line( @configurator.tools_test_bare_includes_preprocessor, [], isolated_filepath, *tool_args )
+    command[:options][:boom] = false
+    return @tool_executor.exec( command )[:output]
+  end
+
+  # The tool's own output, since the command line alone wouldn't say why it failed
+  def log_bare_failure(filepath, output)
+    @loginator.log( "Failed to extract bare #includes (text-scan #includes will stand in) for #{filepath}:\n#{output.to_s.strip}", Verbosity::OBNOXIOUS, LogLabels::ERROR )
+    return nil
+  end
+
+  # Practical max depth for the system-header line-marker walk (see
+  # extract_system_includes_preprocess).
+  SYSTEM_INCLUDE_MAX_DEPTH = 5 unless const_defined?(:SYSTEM_INCLUDE_MAX_DEPTH, false)
+
+  # Fallback text scan for user or system includes -- identical but for which directive
+  # form IncludeFactory recognizes. `#if`/`#ifdef` state is tracked so a guarded include
+  # is only kept when its guard is actually true given `defines`.
+  def _extract_includes_from_text(directive_method, noun, name:, filepath:, defines:)
+    _log_extraction_progress(
+      "Extracting #{noun} #includes from original file using fallback method",
+      name, filepath, label: LogLabels::WARNING
+    )
+
+    includes = active_includes_in_text( directive_method, filepath, CPreprocessorConditionals.new( defines ) )
+    clean_self_reference( filepath, includes )
+  end
+
+  # Binary read: code_lines runs clean_encoding over the whole buffer, but a text-mode
+  # read can raise on an invalid byte sequence before that ever happens.
+  def active_includes_in_text(directive_method, filepath, conditionals)
+    includes = []
+    @file_wrapper.open( filepath, 'rb' ) do |input|
+      @parsing_parcels.code_lines( input ) do |line|
+        conditionals.process_directive( line )
+        next unless conditionals.active?
+        include = @include_factory.public_send( directive_method, line )
+        includes << include.anchored( File.dirname( filepath ) ) unless include.nil?
+      end
+    end
+    return includes
+  end
+
+  # An `#include` directive with an argument of some kind. `\S` after the whitespace
+  # rejects a malformed `#include` with nothing after it.
+  INCLUDE_DIRECTIVE = /^\s*#\s*include\s+\S/ unless const_defined?(:INCLUDE_DIRECTIVE, false)
+
+  # 1-indexed source line numbers of every `#include` in `filepath` whose argument is
+  # a bare token rather than a literal `"..."` or `<...>` -- i.e. a macro the
+  # preprocessor must expand before any filename exists. `code_lines_with_num` has
+  # already stripped comments and folded backslash continuations, so a commented-out
+  # or string-embedded `#include` never reaches here.
+  #
+  # The line reported is the directive's ENDING physical line, not its first --
+  # `-fdirectives-only` attributes a consumed multi-line directive's own entering
+  # marker to the last physical line it spans (the marker literally replaces that
+  # line in the output stream; see PreprocessinatorLineMarkerIncludesExtractor's own
+  # correlation walk and preprocess/README.md), so this must name the same line or
+  # resolve_computed_includes never finds a match. For an ordinary, single-line
+  # directive the start and end line are identical, so this is a no-op there.
+  def computed_include_source_lines(filepath)
+    lines = []
+
+    # Binary read for the same reason the sibling text scans use it: a text-mode read
+    # can raise on an invalid byte sequence before code_lines' encoding cleanup runs.
+    @file_wrapper.open( filepath, 'rb' ) do |input|
+      @parsing_parcels.code_lines_with_num( input ) do |line, _line_num, end_line_num|
+        next unless line.match?( INCLUDE_DIRECTIVE )
+        next if line.match?( PATTERNS::USER_INCLUDE_DIRECTIVE_FILENAME )
+        next if line.match?( PATTERNS::SYSTEM_INCLUDE_DIRECTIVE_FILENAME )
+        lines << end_line_num
+      end
+    end
+
+    lines
+  end
+
+  # Shared progress line for the four extraction methods above.
+  def _log_extraction_progress(operation, name, filepath, label: nil)
+    msg = @reportinator.generate_module_progress(
+      operation: operation, module_name: name, filename: File.basename( filepath )
+    )
+    args = [msg, Verbosity::OBNOXIOUS]
+    args << label unless label.nil?
+    @loginator.log( *args )
+  end
+
   # Remove any filepath in the includes list that is identical to the filepath being processed.
   # We want to prevent an includes list containing an unnecessary self-reference.
   # Use normalized paths for comparison to handle variations (relative vs absolute, different separators, etc.)

data/lib/ceedling/preprocess/preprocessinator_line_marker_includes_extractor.rb

@@ -6,7 +6,9 @@
 # =========================================================================
 
 require 'ceedling/exceptions'
+require 'ceedling/path_matcher'
 require 'set'
+require 'stringio'
 
 ##
 ## System Includes Directives-only Preprocessor Output Parsing
@@ -92,12 +94,14 @@ class PreprocessinatorLineMarkerIncludesExtractor
   SYSTEM = :system  unless const_defined?(:SYSTEM)
   USER   = :user    unless const_defined?(:USER)
 
-  constructor :include_factory
+  constructor :include_factory, :file_wrapper
 
   # Parse preprocessor output from a file (production use)
   # @param filepath [String] Path to the preprocessor output file
+  # @param test [String, nil] Current test's identity, needed to correctly strip its
+  #   own mock subdirectory from a resolved mock include's filepath
   # @return [Array<UserInclude, SystemInclude>]
-  def extract_includes_from_file(filepath, type, max_depth=nil)
+  def extract_includes_from_file(filepath, type, max_depth=nil, test: nil)
     validate_type_argument( type )
     includes = []
     begin
@@ -110,8 +114,10 @@ class PreprocessinatorLineMarkerIncludesExtractor
       # their first byte is 0x3C — ASCII '<' — regardless of the surrounding encoding.
       # NOTE: binary mode means \r\n line endings are NOT translated on Windows; the
       # extract_includes method calls line.chomp! before regex matching to handle this.
-      File.open(filepath, 'rb') do |file|
-        includes = extract_includes(io: file, filepath: filepath, type: type, max_depth: max_depth)
+      # `filepath` is this same build's own gcc output -- open_with_retry rides out
+      # the file briefly not yet being visible right after the shell-out exits.
+      @file_wrapper.open_with_retry(filepath, 'rb') do |file|
+        includes = extract_includes(io: file, filepath: filepath, type: type, max_depth: max_depth, test: test)
       end
     rescue StandardError => e
       raise CeedlingException.new("Failed to extract #{type} includes from preprocessor output file '#{filepath}' ⏩️ #{e.message}")
@@ -119,18 +125,171 @@ class PreprocessinatorLineMarkerIncludesExtractor
     return includes
   end
 
+  # Every user file the preprocessor entered, once each, in the order entered: the files
+  # its output depends on. System headers (marker flag 3) and the preprocessor's own
+  # markers, such as "<built-in>", are left out.
+  def extract_entered_files_from_string(content)
+    return extract_entered_files( StringIO.new( content ) )
+  end
+
+  # As extract_entered_files_from_string, reading this build's own preprocessor output
+  def extract_entered_files_from_file(filepath)
+    files = []
+    @file_wrapper.open_with_retry( filepath, 'rb' ) { |file| files = extract_entered_files( file ) }
+    return files
+  end
+
   # Parse preprocessor output from a string (testing use)
   # @param content [String] Preprocessor output as a string
   # @return [Array<UserInclude, SystemInclude>]
-  def extract_includes_from_string(content, filepath, type, max_depth=nil)
+  def extract_includes_from_string(content, filepath, type, max_depth=nil, test: nil)
     validate_type_argument( type )
     require 'stringio'
     io = StringIO.new(content)
-    return extract_includes(io: io, filepath: filepath, type: type, max_depth: max_depth)
+    return extract_includes(io: io, filepath: filepath, type: type, max_depth: max_depth, test: test)
+  end
+
+  # Correlate `-fdirectives-only` entering line markers back to the raw source lines
+  # that produced them, for a set of lines of interest. Used to recover GCC's own
+  # resolution of an `#include` whose target is a macro invocation: the directive
+  # carries no literal filename to scan for, but the accurate directives-only pass
+  # still resolves it and emits an ordinary entering marker for the header.
+  #
+  # @param preprocessed_filepath [String] raw directives-only output (line markers
+  #   intact, comments stripped or not -- physical line count is 1:1 with the source
+  #   either way, which is all this walk needs), or a test file's plain fallback
+  #   expansion, read as a best effort (see correlate_computed_includes)
+  # @param source_basename [String] basename of the original source file, used to
+  #   recognize its own line markers in the stream
+  # @param source_lines [Enumerable<Integer>] 1-indexed source line numbers to report
+  #   a resolution for (the lines carrying a non-literal `#include`)
+  # @return [Hash{Integer => String}] source line number => path GCC resolved that
+  #   line's `#include` to; only lines that actually produced an entering marker appear
+  def resolve_computed_includes(preprocessed_filepath:, source_basename:, source_lines:)
+    wanted = source_lines.to_a
+    return {} if wanted.empty?
+
+    begin
+      # Binary mode for the same reason extract_includes_from_file uses it: GCC output
+      # under a non-C locale carries non-ASCII bytes, and \r\n must survive untranslated
+      # for the per-line chomp! below to normalize.
+      # `preprocessed_filepath` is this same build's own gcc output -- open_with_retry
+      # rides out the file briefly not yet being visible right after the shell-out exits.
+      @file_wrapper.open_with_retry( preprocessed_filepath, 'rb' ) do |file|
+        return correlate_computed_includes( io: file, source_basename: source_basename, wanted: Set.new( wanted ) )
+      end
+    rescue StandardError => e
+      raise CeedlingException.new("Failed to correlate computed #includes from preprocessor output file '#{preprocessed_filepath}' ⏩️ #{e.message}")
+    end
   end
 
   private
 
+  # Walk the directives-only stream tracking which source line of the file of interest
+  # the current physical line maps to, and report the resolved path for every entering
+  # marker attributed to a `wanted` source line.
+  #
+  # `src_line` names the source line the NEXT non-marker physical line will be. A
+  # `# n "<file of interest>"` marker sets it to `n`; each subsequent body line of that
+  # file bumps it by one. The macro-target `#include` directive is REPLACED by the
+  # entering marker for the header it pulled in, so it never shows up as a body line --
+  # `src_line` therefore still reads that directive's own line number when its entering
+  # marker appears. Body lines and markers of any OTHER file are skipped entirely, so
+  # a header's own nesting can't drift the count.
+  #
+  # A plain expansion, fallback's stand-in for directives-only output, drops runs of lines
+  # it has no use for, but it ends each such gap with a `# n` marker for the file, which
+  # resets the count. Fallback reads it as a best effort.
+  def correlate_computed_includes(io:, source_basename:, wanted:)
+    resolved = {}
+    in_file_of_interest = false
+    src_line = 0
+
+    io.each_line do |line|
+      line.chomp!
+
+      match = LINE_MARKER_REGEX.match(line)
+
+      # A non-marker line advances the counter only while inside the file of interest.
+      unless match
+        src_line += 1 if in_file_of_interest
+        next
+      end
+
+      marker_path = match[2]
+      next if marker_path.start_with?('<')  # <built-in>, <command-line>
+
+      marker_path = canonicalize_marker_path( marker_path )
+      flags = match[3] ? match[3].split.map(&:to_i) : []
+
+      if File.basename(marker_path) == source_basename
+        # Entering or resuming the file of interest: its own markers carry the
+        # authoritative line number for whatever comes next.
+        src_line = match[1].to_i
+        in_file_of_interest = true
+      elsif in_file_of_interest && flags.include?(1)
+        # An entering marker for another file, standing in for a directive on the
+        # file-of-interest line the counter currently names.
+        resolved[src_line] = marker_path if wanted.include?(src_line)
+        in_file_of_interest = false
+      else
+        # Any other marker (returning to an intermediate header, a nested entry):
+        # we're no longer tracking file-of-interest body lines until its own marker
+        # brings us back.
+        in_file_of_interest = false
+      end
+    end
+
+    resolved
+  end
+
+  # GCC's own marker text is real and complete but sometimes left uncanonicalized:
+  # PathMatcher.resolve_relative deliberately leaves an ABSOLUTE query's own `..`
+  # untouched (its own documented contract defers that case to a File.expand_path-
+  # based comparison elsewhere) -- reachable whenever the file actually being
+  # preprocessed has an absolute path of its own, which makes GCC's marker for a
+  # directory-relative include absolute too. Collapsed here with a plain segment
+  # walk rather than File.expand_path, which is CWD- and drive-dependent on Windows
+  # and would silently inject the current process's own drive letter into an
+  # already-absolute Unix-style path instead of leaving it alone. Only reached when
+  # the result is still absolute AND still carries a literal `..` segment -- a no-op
+  # for the ordinary, already-clean case.
+  def canonicalize_marker_path(path)
+    resolved = PathMatcher.resolve_relative( path, anchor: '' )
+    segments = resolved.split(%r{[\\/]}).reject(&:empty?)
+
+    # A relative result keeps only the leading .. segments naming a path above the
+    # project root, which are already as collapsed as they can be
+    return resolved unless segments.include?('..') and PathMatcher.absolute?( resolved )
+
+    # Absolute forms this can see: a leading "/" (Unix), or a drive letter
+    # ("C:\..." / "C:/..."). Either way, remember the prefix so the collapsed
+    # result stays just as absolute as it started -- neither form's own marker is
+    # ever a bare relative path once resolve_relative has already left it untouched.
+    drive_match = resolved.match(/\A([A-Za-z]:)[\\\/]/)
+    prefix = drive_match ? "#{drive_match[1]}/" : '/'
+    segments.shift if drive_match
+
+    collapsed = []
+    segments.each { |segment| segment == '..' ? collapsed.pop : collapsed << segment }
+
+    "#{prefix}#{collapsed.join('/')}"
+  end
+
+  def extract_entered_files(io)
+    return io.each_line.filter_map { |line| entered_user_file( LINE_MARKER_REGEX.match( line.chomp ) ) }.uniq
+  end
+
+  # The user file a line marker enters (flag 1), or nil for any other line or marker
+  def entered_user_file(match)
+    return nil if match.nil? or match[2].start_with?( '<' )
+
+    flags = match[3] ? match[3].split.map( &:to_i ) : []
+    return nil if !flags.include?( 1 ) or flags.include?( 3 )
+
+    return canonicalize_marker_path( match[2] )
+  end
+
   def validate_type_argument(type)
     unless [SYSTEM, USER].include?(type)
       raise CeedlingException.new("Invalid type argument: #{type.inspect}. Must be :#{SYSTEM} or :#{USER}")
@@ -139,7 +298,7 @@ class PreprocessinatorLineMarkerIncludesExtractor
 
   # Extracts includes from directives-only preprocessor output
   # Returns an array of Include-derived objects
-  def extract_includes(io:, filepath:, type:, max_depth:)
+  def extract_includes(io:, filepath:, type:, max_depth:, test: nil)
     includes = []
     seen_paths = Set.new
     initial_file_seen = false
@@ -167,6 +326,13 @@ class PreprocessinatorLineMarkerIncludesExtractor
         # Skip special markers like "<built-in>" and "<command-line>"
         next if filepath.start_with?('<')
 
+        # GCC forms a directory-relative quoted include's own line marker by
+        # concatenating the including file's directory onto the literal include
+        # text -- real and complete, but left uncanonicalized. Collapsing any ..
+        # here, once, means this path can correspond to the project's own real,
+        # ..-free file list the same way any other candidate already does.
+        filepath = canonicalize_marker_path( filepath )
+
         # Integer line number
         line_number = match[1].to_i
         
@@ -204,7 +370,7 @@ class PreprocessinatorLineMarkerIncludesExtractor
           # Extract user includes
           elsif type == USER
             unless flags.include?(3)
-              includes << @include_factory.user_include_from_filepath( filepath )
+              includes << @include_factory.user_include_from_filepath( filepath, test: test )
             end
           end
         # Flag 2 means returning to a previous file