ceedling 1.1.9 → 1.2.0

data/lib/ceedling/test_invoker/test_build_setup.rb

@@ -11,10 +11,15 @@ require 'ceedling/test_context_extractor'
 require 'ceedling/includes/includes'
 require 'ceedling/partials/partials'
 require 'ceedling/test_invoker/test_invoker_types'
+require 'ceedling/test_invoker/test_pipeline_helpers'
+require 'ceedling/test_invoker/test_build_validations'
+require 'ceedling/path_mirror'
 
 class TestBuildSetup
 
   include TestInvokerTypes
+  include TestPipelineHelpers
+  include TestBuildValidations
 
   constructor(
     :configurator,
@@ -23,12 +28,15 @@ class TestBuildSetup
     :batchinator,
     :test_context_extractor,
     :include_pathinator,
-    :preprocessinator,
     :defineinator,
     :flaginator,
     :file_wrapper,
     :file_path_utils,
-    :test_runner_manager
+    :file_finder,
+    :test_runner_manager,
+    :dependinator,
+    :test_search_paths,
+    :mock_locator
   )
 
   def setup()
@@ -38,11 +46,11 @@ class TestBuildSetup
   # Stage 1: Create per-test build/results/mock/partial directory structure
   # and populate the testables hash with initial entries.
   def stage_prepare_build_paths(state)
-    results_path = @file_path_utils.form_test_results_path( context: state.context )
+    clean_test_roots = PathMirror.clean_roots( @configurator.paths_test )
 
     @batchinator.exec(workload: :compile, things: state.tests) do |filepath|
       filepath = filepath.to_s
-      key  = testable_symbolize( filepath )
+      key  = testable_symbolize( filepath, clean_test_roots )
       name = key.to_s
 
       state.lock.synchronize do
@@ -59,8 +67,9 @@ class TestBuildSetup
 
       # Assemble all needed testable build paths
       paths[:build]        = @file_path_utils.form_test_build_path( name, context: state.context )
-      paths[:results]      = results_path
+      paths[:results]      = @file_path_utils.form_test_results_path( name, context: state.context )
       paths[:dependencies] = @file_path_utils.form_test_dependencies_path( name, context: state.context )
+      paths[:runners]      = @file_path_utils.form_test_runners_path( name )
 
       if @configurator.project_use_mocks
         paths[:mocks] = @file_path_utils.form_test_mocks_path( name )
@@ -71,39 +80,56 @@ class TestBuildSetup
       end
 
       if @configurator.project_use_test_preprocessor != :none
-        testable.preprocess[:includes]         = []
-        testable.preprocess[:directives_only]  = { filepath: nil }
+        testable.preprocess[:includes]           = []
+        testable.preprocess[:directives_only]    = { filepath: nil }
+        testable.preprocess[:fallback_expansion] = { filepath: nil }
 
-        paths[:preprocess_incudes]                    = @file_path_utils.form_test_preprocess_includes_path( name )
+        paths[:preprocess_includes]                   = @file_path_utils.form_test_preprocess_includes_path( name )
         paths[:preprocess_files]                      = @file_path_utils.form_test_preprocess_files_path( name )
         paths[:preprocess_files_full_expansion]       = @file_path_utils.form_test_preprocess_files_full_expansion_path( name )
         paths[:preprocess_files_directives_only]      = @file_path_utils.form_test_preprocess_files_directives_only_path( name )
         paths[:preprocess_files_raw_directives_only]  = @file_path_utils.form_test_preprocess_files_raw_directives_only_path( name )
       end
 
+      # A test file's own build directive macros are cached here regardless of whether
+      # preprocessing is enabled, so this path is always present.
+      paths[:preprocess_build_directives] = @file_path_utils.form_test_preprocess_build_directives_path( name )
+
       # Create all testable build paths
       testable.paths.each { |_, path| @file_wrapper.mkdir( path ) }
     end
-
-    clean_test_results( results_path, state.testables.map { |_, t| t.name } )
   end
 
   # Stage 2: Collect includes, build directives, and test case context from each test file.
+  #
+  # A test file's #includes and Partials configuration are read fresh every run, since
+  # they carry richer information than a simple cache can hold. Its build directive
+  # macros -- TEST_INCLUDE_PATH() always, and (when preprocessing is off)
+  # TEST_SOURCE_FILE() -- are plain lists of strings, so those are recalled from a small
+  # cache instead of being scanned again when nothing about the file itself has changed.
   def stage_collect_test_context(state)
+    skipped = 0
+
     @batchinator.exec(workload: :compile, things: state.testables) do |_, testable|
       filepath = testable.filepath
       filename = File.basename( filepath )
 
+      cache_target = @file_path_utils.form_test_build_directives_cache_filepath( filepath, testable.name )
+      @dependinator.register( cache_target, files: [filepath] )
+      directives_stale = @dependinator.stale?( cache_target )
+
       contexts = [TestContextExtractor::Context::INCLUDES]
 
       if @configurator.project_use_test_preprocessor_tests
         msg = @reportinator.generate_progress( "Parsing #{filename} for user & system #includes (fallback for preprocessing failures)" )
         @loginator.log( msg )
 
-        contexts << TestContextExtractor::Context::BUILD_DIRECTIVE_INCLUDE_PATHS
+        if directives_stale
+          contexts << TestContextExtractor::Context::BUILD_DIRECTIVE_INCLUDE_PATHS
 
-        msg = @reportinator.generate_progress( "Parsing #{filename} for include path build directive macros" )
-        @loginator.log( msg )
+          msg = @reportinator.generate_progress( "Parsing #{filename} for include path build directive macros" )
+          @loginator.log( msg )
+        end
 
         msg = @reportinator.generate_progress( "Parsing #{filename} for Partials directive macros" )
         @loginator.log( msg )
@@ -112,16 +138,35 @@ class TestBuildSetup
         msg = @reportinator.generate_progress( "Parsing #{filename} for user & system #includes" )
         @loginator.log( msg )
 
-        contexts << TestContextExtractor::Context::BUILD_DIRECTIVE_INCLUDE_PATHS
-        contexts << TestContextExtractor::Context::BUILD_DIRECTIVE_SOURCE_FILES
+        if directives_stale
+          contexts << TestContextExtractor::Context::BUILD_DIRECTIVE_INCLUDE_PATHS
+          contexts << TestContextExtractor::Context::BUILD_DIRECTIVE_SOURCE_FILES
+
+          msg = @reportinator.generate_progress( "Parsing #{filename} for build directive macros" )
+          @loginator.log( msg )
+        end
+
         contexts << TestContextExtractor::Context::TEST_RUNNER_DETAILS
 
-        msg = @reportinator.generate_progress( "Parsing #{filename} for build directive macros and test case names" )
+        msg = @reportinator.generate_progress( "Parsing #{filename} for test case names" )
         @loginator.log( msg )
       end
 
+      unless directives_stale
+        msg = @reportinator.generate_progress( "Recalling cached build directive macros for #{filename}" )
+        @loginator.log( msg, Verbosity::OBNOXIOUS )
+      end
+
       @context_extractor.collect_simple_context_from_file( filepath, nil, *contexts )
 
+      if directives_stale
+        @context_extractor.store_build_directives_cache( filepath: filepath, cache_filepath: cache_target )
+        @dependinator.mark_fresh( cache_target )
+      else
+        @context_extractor.load_build_directives_cache( filepath: filepath, cache_filepath: cache_target )
+        state.lock.synchronize { skipped += 1 }
+      end
+
       validate_mocks_in_use(
         filename: filename,
         mocks:    @context_extractor.lookup_mock_header_includes_list( filepath )
@@ -132,8 +177,12 @@ class TestBuildSetup
         partials_in_use: !(@context_extractor.lookup_partials_config( filepath )).empty?,
         includes:        @context_extractor.lookup_all_header_includes_list( filepath )
       )
+
+      testable.mock_search_paths = collect_mock_search_paths( testable )
     end
 
+    log_skip_summary( task: "build directive macro scanning", count: skipped, noun: "test files" )
+
     process_project_include_paths()
   end
 
@@ -145,7 +194,7 @@ class TestBuildSetup
     @batchinator.exec(workload: :compile, things: state.testables) do |_, testable|
       filepath = testable.filepath
 
-      srch_paths     = search_paths( filepath, testable.paths )
+      srch_paths     = @test_search_paths.compose( filepath, testable.paths, testable.mock_search_paths )
       cmp_flags      = flags( context: state.context, operation: OPERATION_COMPILE_SYM,    filepath: filepath )
       pre_flags      = preprocess_flags( context: state.context, compile_flags: cmp_flags, filepath: filepath )
       asm_flags      = flags( context: state.context, operation: OPERATION_ASSEMBLE_SYM,   filepath: filepath )
@@ -172,143 +221,6 @@ class TestBuildSetup
     end
   end
 
-  # Stage 4 (conditional on preprocessing): Extract includes using the preprocessor.
-  def stage_collect_preprocessor_context(state)
-    # First pass: extract bare includes; create stand-in files for mocks and partials
-    @batchinator.exec(workload: :compile, things: state.testables) do |_, testable|
-      name     = testable.name
-      filepath = testable.filepath
-
-      if @preprocessinator.cached_includes_list?( test: name, filepath: filepath )
-        msg = @reportinator.generate_module_progress(
-          operation:   'Skipping preprocessing for #includes in favor of cached #includes for',
-          module_name: name,
-          filename:    File.basename( filepath )
-        )
-        @loginator.log( msg )
-        next
-      end
-
-      arg_hash = {
-        test:         name,
-        filepath:     filepath,
-        search_paths: [@configurator.project_build_vendor_ceedling_path],
-        flags:        testable.preprocess_flags,
-        defines:      testable.preprocess_defines
-      }
-
-      msg = @reportinator.generate_module_progress(
-        operation:   'Extracting #includes from',
-        module_name: name,
-        filename:    File.basename( filepath )
-      )
-      @loginator.log( msg )
-
-      includes = @preprocessinator.preprocess_bare_includes( **arg_hash )
-
-      testable.preprocess[:includes] = includes
-
-      generate_test_includes_standins( name, includes )
-    end
-
-    # Second pass: generate directives-only preprocessor output after stand-ins exist
-    directives_only = @configurator.test_build_preprocess_directives_only_available
-    @batchinator.exec(workload: :compile, things: state.testables) do |_, testable|
-      next unless directives_only
-
-      name     = testable.name
-      filepath = testable.filepath
-
-      arg_hash = {
-        filepath:      filepath,
-        test:          name,
-        flags:         testable.preprocess_flags,
-        include_paths: testable.search_paths,
-        vendor_paths:  [@configurator.project_build_vendor_ceedling_path],
-        defines:       testable.preprocess_defines
-      }
-
-      msg = @reportinator.generate_module_progress(
-        operation:   'Preprocessing test files for follow-on details extraction steps',
-        module_name: name,
-        filename:    File.basename( filepath )
-      )
-      @loginator.log( msg, Verbosity::OBNOXIOUS )
-
-      testable.preprocess[:directives_only][:filepath] =
-        @preprocessinator.generate_directives_only_output( **arg_hash )
-    end
-
-    # Third pass: reconcile includes from all extraction sources and ingest
-    directives_only = @configurator.test_build_preprocess_directives_only_available
-    @batchinator.exec(workload: :compile, things: state.testables) do |_, testable|
-      filepath = testable.filepath
-      filename = File.basename( filepath )
-      name     = testable.name
-
-      cached, includes = @preprocessinator.load_includes_list( test: name, filepath: filepath )
-      if cached
-        @context_extractor.ingest_includes( filepath, includes )
-        next
-      end
-
-      unless directives_only
-        msg = @reportinator.generate_module_progress(
-          operation:   'Using fallback text-only includes extracted for',
-          module_name: name,
-          filename:    filename
-        )
-        @loginator.log( msg, Verbosity::OBNOXIOUS, LogLabels::WARNING )
-        next
-      end
-
-      directive_only_filepath = testable.preprocess[:directives_only][:filepath]
-      system_includes = []
-      user_includes   = []
-
-      unless directive_only_filepath.nil?
-        arg_hash = {
-          name:                     name,
-          filepath:                 filepath,
-          directives_only_filepath: directive_only_filepath
-        }
-
-        user_includes   = @preprocessinator.preprocess_user_includes( **arg_hash )
-        system_includes = @preprocessinator.preprocess_system_includes( **arg_hash )
-      else
-        msg = @reportinator.generate_module_progress(
-          operation:   'Using fallback text-only includes extracted for',
-          module_name: name,
-          filename:    filename
-        )
-        @loginator.log( msg, Verbosity::OBNOXIOUS, LogLabels::WARNING )
-
-        all_includes    = @context_extractor.lookup_all_header_includes_list( filepath )
-        user_includes   = Includes.user( all_includes )
-        system_includes = Includes.system( all_includes )
-      end
-
-      bare_includes = testable.preprocess[:includes]
-
-      all_includes = Includes.reconcile(
-        bare:   bare_includes,
-        user:   user_includes,
-        system: system_includes
-      )
-
-      header = "Extracted reconciled #include list from #{filepath}:"
-      @loginator.log_list( all_includes, header, Verbosity::OBNOXIOUS )
-
-      @context_extractor.ingest_includes( filepath, all_includes )
-
-      @preprocessinator.store_includes_list(
-        test:     name,
-        filepath: filepath,
-        includes: all_includes
-      )
-    end
-  end
-
   # -----------------------------------------------------------------------
   # Helper methods
   # -----------------------------------------------------------------------
@@ -319,75 +231,30 @@ class TestBuildSetup
     @include_pathinator.augment_environment_header_files( headers )
   end
 
-  def generate_test_includes_standins(test, includes)
-    mocks    = Includes.filter( includes, /^#{@configurator.cmock_mock_prefix}/ )
-    partials = Includes.filter( includes, /^#{PARTIAL_FILENAME_PREFIX}/ )
-
-    mocks.each do |include|
-      filepath = @file_path_utils.form_mock_header_filepath( test, include.filepath )
-      msg = @reportinator.generate_module_progress(
-        operation:   'Generating stand-in header for',
-        module_name: test,
-        filename:    include.filename
-      )
-      @loginator.log( msg, Verbosity::DEBUG )
-      @file_wrapper.mkdir( File.dirname( filepath ) )
-      @file_wrapper.write_blank_file( filepath )
-    end
-
-    partials.each do |include|
-      filepath = @file_path_utils.form_partial_header_filepath( test, include.filename )
-      msg = @reportinator.generate_module_progress(
-        operation:   'Generating stand-in header for',
-        module_name: test,
-        filename:    include.filename
-      )
-      @loginator.log( msg, Verbosity::DEBUG )
-      @file_wrapper.write_blank_file( filepath )
-    end
-  end
-
-  def validate_mocks_in_use(filename:, mocks:)
-    if !@configurator.project_use_mocks and !mocks.empty?
-      _mocks = mocks.map { |include| include.filename }
-
-      if _mocks.length > 1
-        _mocks = "[#{_mocks.join(', ')}]"
-      else
-        _mocks = _mocks[0]
-      end
-
-      msg = "Your project is not configured for mocking, but #{filename} #includes #{_mocks}"
-      raise CeedlingException.new( msg )
-    end
-  end
-
-  def validate_partials_in_use(filename:, partials_in_use:, includes:)
-    partials_header_in_use = Includes.contains?( includes, CEEDLING_HEADER_FILENAME )
-
-    if partials_in_use && !@configurator.project_use_partials
-      msg = "Your project is not configured for Partials, but #{filename} is attempting to use Partial features"
-      raise CeedlingException.new( msg )
-    end
-
-    if partials_in_use && !partials_header_in_use
-      msg = "Your test file #{filename} is attempting to use Partial features without #including #{CEEDLING_HEADER_FILENAME}"
-      raise CeedlingException.new( msg )
-    end
-  end
-
-  def search_paths(filepath, paths)
-    _paths = []
-    _paths << paths[:mocks]    if paths[:mocks]
-    _paths << paths[:partials] if paths[:partials]
-    _paths += @include_pathinator.lookup_test_directive_include_paths( filepath )
-    _paths += @include_pathinator.collect_test_include_paths()
-    _paths += @configurator.collection_paths_support
-    _paths += @configurator.collection_paths_include
-    _paths += @configurator.collection_paths_libraries
-    _paths += @configurator.collection_paths_vendor
-    _paths += @configurator.collection_paths_test_toolchain_include
-    return _paths.uniq
+  # Every mocked header's own mirrored directory below this test's mock root -- a mock is
+  # only ever findable by the compiler via a search path pointing directly at wherever it
+  # actually lives, since C's own #include resolution has no notion of a recursive search
+  # path, so this feeds directly into this test's own search paths (TestSearchPaths).
+  #
+  # These come from the text-scanned #includes, which ignore #if. With test preprocessing
+  # on, stage 4 settles which mocks the build uses, and where it reconciles it sets these
+  # paths again from the preprocessor's list. A scanned mock without a header, or with one
+  # matching only in letter case, may be one the preprocessor discards, so it is skipped
+  # here silently. With preprocessing off, the scanned list is the build's own, and a
+  # missing or mis-cased header stops the build.
+  def collect_mock_search_paths(testable)
+    return [] unless testable.paths[:mocks]
+
+    complain = @configurator.project_use_test_preprocessor_tests ? :silent : :error
+
+    # This test's search paths don't exist until stage 3, so they are composed here
+    # without mock directories, the same collection later stages resolve against
+    collection = @mock_locator.header_collection( @test_search_paths.compose( testable.filepath, testable.paths ) )
+
+    return @mock_locator.directories(
+      @context_extractor.lookup_mock_header_includes_list( testable.filepath ),
+      mocks_root: testable.paths[:mocks], collection: collection, complain: complain
+    )
   end
 
   def framework_defines()
@@ -395,6 +262,14 @@ class TestBuildSetup
     defines += @defineinator.defines( topkey: UNITY_SYM,     subkey: :defines )
     defines += @defineinator.defines( topkey: CMOCK_SYM,     subkey: :defines )
     defines += @defineinator.defines( topkey: CEXCEPTION_SYM, subkey: :defines )
+
+    # Partials' own macro-based #includes require this symbol to be defined
+    # for every file, both at compile time and preprocess time. It's added
+    # here unconditionally, alongside Unity/CMock/CException's own framework
+    # defines above, so its presence never depends on whether a file happens
+    # to match any entry in a project's own :defines: matcher configuration.
+    defines << "CEEDLING_PARTIALS_PREFIX=#{PARTIAL_FILENAME_PREFIX}" if @configurator.project_use_partials
+
     return defines.uniq
   end
 
@@ -402,40 +277,56 @@ class TestBuildSetup
     return @test_runner_manager.collect_defines()
   end
 
-  def compile_defines(context:, filepath:)
+  # A build context without defines of its own takes those of :test. Matchers resolve
+  # against `filepath`.
+  def context_defines(context:, filepath:)
     context = TEST_SYM unless @defineinator.defines_defined?( context: context )
+    return @defineinator.defines( subkey: context, filepath: filepath )
+  end
+
+  def compile_defines(context:, filepath:)
     defines  = @defineinator.generate_test_definition( filepath: filepath )
-    defines += @defineinator.defines( subkey: context, filepath: filepath )
+    defines += context_defines( context: context, filepath: filepath )
     return defines.uniq
   end
 
+  # A file matching nothing in a Hash-shaped `:preprocess:` section falls back
+  # to `test_defines`, its compile-time defines, exactly as if the section
+  # didn't apply to it at all -- see ConfigMatchinator#matches?'s
+  # `no_match_default`. This keeps a file's preprocess-defines meta entirely
+  # explained by its own configuration, so a `:preprocess:` matcher targeting
+  # one file has no bearing on any other file's dependency-tracker meta.
   def preprocess_defines(test_defines:, filepath:)
-    preprocessing_defines = @defineinator.defines( subkey: PREPROCESS_SYM, filepath: filepath, default: nil )
-    return test_defines if preprocessing_defines.nil?
-    return preprocessing_defines
+    return @defineinator.defines(
+      subkey: PREPROCESS_SYM, filepath: filepath, default: test_defines, no_match_default: test_defines
+    )
   end
 
-  def flags(context:, operation:, filepath:, default:[])
+  def flags(context:, operation:, filepath:, default:[], no_match_default: nil)
     context = TEST_SYM unless @flaginator.flags_defined?( context: context, operation: operation )
-    return @flaginator.flag_down( context: context, operation: operation, filepath: filepath, default: default )
+    return @flaginator.flag_down(
+      context: context, operation: operation, filepath: filepath, default: default, no_match_default: no_match_default
+    )
   end
 
+  # Mirrors #preprocess_defines: a file matching nothing in a Hash-shaped
+  # `:preprocess:` flags section falls back to `compile_flags`, its
+  # compile-time flags, exactly as if the section didn't apply to it at all.
   def preprocess_flags(context:, compile_flags:, filepath:)
-    preprocessing_flags = flags( context: context, operation: OPERATION_PREPROCESS_SYM, filepath: filepath, default: nil )
-    return compile_flags if preprocessing_flags.nil?
-    return preprocessing_flags
-  end
-
-  def clean_test_results(path, tests)
-    tests.each do |test|
-      @file_wrapper.rm_f( Dir.glob( File.join( path, test + '.*' ) ) )
-    end
+    return flags(
+      context: context, operation: OPERATION_PREPROCESS_SYM, filepath: filepath,
+      default: compile_flags, no_match_default: compile_flags
+    )
   end
 
   private
 
-  def testable_symbolize(filepath)
-    return (File.basename( filepath ).ext( '' )).to_sym
+  def testable_symbolize(filepath, clean_roots)
+    basename = File.basename( filepath ).ext( '' )
+    subdir   = PathMirror.relative_subdir_from_clean_roots( filepath, clean_roots )
+    name     = subdir.empty? ? basename : File.join( subdir, basename )
+
+    return name.to_sym
   end
 
 end

data/lib/ceedling/test_invoker/test_build_validations.rb

@@ -0,0 +1,102 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Test-build configuration validators shared by more than one test pipeline stage
+# class -- each raises CeedlingException on a real, user-facing mistake it's
+# positioned to catch (a project using mocking, Partials, or a build-directive
+# source without configuring for it, or a header that doesn't actually resolve).
+# Relies on whichever including class's own constructor DI already provides the
+# collaborators a given validator needs, the same way TestPipelineHelpers is
+# mixed in without any DI wiring of its own.
+module TestBuildValidations
+
+  def validate_mocks_in_use(filename:, mocks:)
+    if !@configurator.project_use_mocks and !mocks.empty?
+      _mocks = mocks.map { |include| include.filename }
+
+      if _mocks.length > 1
+        _mocks = "[#{_mocks.join(', ')}]"
+      else
+        _mocks = _mocks[0]
+      end
+
+      msg = "Your project is not configured for mocking, but #{filename} #includes #{_mocks}"
+      raise CeedlingException.new( msg )
+    end
+  end
+
+  def validate_partials_in_use(filename:, partials_in_use:, includes:)
+    partials_header_in_use = Includes.contains?( includes, CEEDLING_HEADER_FILENAME )
+
+    if partials_in_use && !@configurator.project_use_partials
+      msg = "Your project is not configured for Partials, but #{filename} is attempting to use Partial features"
+      raise CeedlingException.new( msg )
+    end
+
+    if partials_in_use && !partials_header_in_use
+      msg = "Your test file #{filename} is attempting to use Partial features without #including #{CEEDLING_HEADER_FILENAME}"
+      raise CeedlingException.new( msg )
+    end
+  end
+
+  # Every #include naming a real project header -- other than a mock (validated separately,
+  # as part of resolving it via FileFinder#resolve_mock), a system header, Unity's or
+  # Ceedling's own header, or a Partial (Ceedling's own generated content, not a project file
+  # to validate) -- must resolve to exactly one file, existence-wise, among this test's own
+  # search_paths (the same directory priority the compiler itself consults): ambiguity among
+  # same-named candidates resolves quietly to the first by that order, exactly as the real
+  # compile would find it; only a genuinely unresolvable name still halts the build here. A
+  # bogus or merely-unmatched path is otherwise never actually checked against real project
+  # headers -- only its potential corresponding source file is, tolerantly, elsewhere. Unity's
+  # and Ceedling's own headers live in the build's vendor directories, outside every configured
+  # :test/:source/:support/:include root a test's search_paths is built from, so neither could
+  # ever resolve there.
+  def validate_header_includes(test_filepath:, testable:)
+    includes = @context_extractor.lookup_nonmock_header_includes_list( test_filepath )
+
+    collection = @include_pathinator.ordered_header_files( testable.search_paths )
+
+    includes.each do |include|
+      next if include.is_a?( SystemInclude )
+      next if include.filename == UNITY_H_FILE
+      next if include.filename == CEEDLING_HEADER_FILENAME
+      next if include.filename.start_with?( PARTIAL_FILENAME_PREFIX )
+
+      @file_finder.find_header_file( include.filepath, :error, collection: collection )
+    end
+  end
+
+  # A TEST_SOURCE_FILE() entry must name a real, recognized file whether it
+  # adds or removes -- a typo or a nonexistent path is worth failing loudly
+  # on either side of the +:/-: convention, the same way a missing file has
+  # always been treated for a plain, additive entry.
+  def validate!(test:, filepath:)
+    sources = @test_context_extractor.lookup_build_directive_sources_list( filepath )
+
+    ext_message = @configurator.extension_source.to_s
+    ext_message += " or #{@configurator.extension_assembly}" if @configurator.test_build_use_assembly
+
+    sources.each do |raw_source|
+      source = FilePathUtils.no_aggregation_decorators( raw_source )
+      valid_extension =
+        if @configurator.test_build_use_assembly
+          @configurator.extension_assembly.match?( source ) || @configurator.extension_source.match?( source )
+        else
+          @configurator.extension_source.match?( source )
+        end
+
+      unless valid_extension
+        raise CeedlingException.new( "File '#{source}' specified with TEST_SOURCE_FILE() in #{test} is not a #{ext_message} source file" )
+      end
+
+      if @file_finder.find_build_input_file( filepath: source, complain: :ignore, context: TEST_SYM ).nil?
+        raise CeedlingException.new( "File '#{source}' specified with TEST_SOURCE_FILE() in #{test} cannot be found in the source file collection" )
+      end
+    end
+  end
+
+end