ceedling 1.2.0 → 1.2.2

data/spec/integration/test_source_file_checks_spec.rb

@@ -0,0 +1,166 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Checking TEST_SOURCE_FILE() entries against a real project. Real test files are scanned by
+# the real context extractor, and the real resolver looks each entry up through the real
+# file finder in a temporary project configured by the real configuration pipeline.
+#
+# Each test's entries are checked once, under that test's own name, with test preprocessing
+# on or off, so a misspelled entry stops the build naming the test that holds it (GH #1364).
+
+require 'spec_helper'
+require 'configurator_integration_helper'
+require 'ceedling/parsing_parcels'
+require 'ceedling/includes/include_factory'
+require 'ceedling/filesystem/file_finder'
+require 'ceedling/filesystem/file_finder_helper'
+require 'ceedling/filesystem/file_path_utils'
+require 'ceedling/test_context_extractor'
+require 'ceedling/test_invoker/test_source_file_directive_resolver'
+require 'ceedling/test_invoker/test_build_setup'
+require 'ceedling/test_invoker/test_invoker_types'
+
+describe 'TEST_SOURCE_FILE() checks (integration)' do
+  include ConfiguratorIntegrationHelpers
+
+  # Runs each test of a batch in turn, in place of the thread pool
+  class TestSourceFileChecksBatchinator
+    def exec(things:, **_options)
+      things.each { |key, value| yield key, value }
+    end
+  end
+
+  def test_file(entries)
+    lines = entries.map { |entry| "TEST_SOURCE_FILE(\"#{entry}\")\n" }.join
+    return "#include \"unity.h\"\n#{lines}void test_it(void) {}\n"
+  end
+
+  def project_files
+    return {
+      'src/calc.c'        => "int calc(void) { return 1; }\n",
+      'src/calc.h'        => "int calc(void);\n",
+      'src/a/dup.c'       => "int dup(void) { return 1; }\n",
+      'lib/a/dup.c'       => "int dup(void) { return 2; }\n",
+      'lib/extra.c'       => "int extra(void) { return 7; }\n",
+      'test/test_m1.c'    => test_file( ['calc.c'] ),
+      'test/test_m2.c'    => test_file( ['calc.c'] ),
+      'test/unit/test_m3.c' => test_file( ['../../lib/extra.c'] )
+    }
+  end
+
+  def project_yaml(preprocessor: :none)
+    return <<~YAML
+      :project:
+        :build_root: build
+        :use_test_preprocessor: :#{preprocessor}
+      :paths:
+        :test: [test/**]
+        :source: [src/**, lib/**]
+        :include: [src/**]
+    YAML
+  end
+
+  def objects
+    graph        = configure( project_yaml )
+    configurator = graph[:configurator]
+    loginator    = graph[:loginator]
+    file_wrapper = graph[:file_wrapper]
+
+    file_path_utils = FilePathUtils.new( configurator: configurator, file_wrapper: file_wrapper )
+    file_finder     = FileFinder.new(
+      configurator: configurator, file_finder_helper: FileFinderHelper.new( loginator: loginator ),
+      file_path_utils: file_path_utils, file_wrapper: file_wrapper, yaml_wrapper: graph[:yaml_wrapper]
+    )
+    extractor = TestContextExtractor.new(
+      configurator: configurator, parsing_parcels: ParsingParcels.new, include_factory: IncludeFactory.new( configurator: configurator ),
+      partializer_config: double( 'partializer_config' ).as_null_object, file_path_utils: file_path_utils, file_wrapper: file_wrapper,
+      yaml_wrapper: graph[:yaml_wrapper], loginator: loginator
+    )
+    resolver = TestSourceFileDirectiveResolver.new(
+      test_context_extractor: extractor, file_finder: file_finder, configurator: configurator, loginator: loginator
+    )
+
+    return { configurator: configurator, file_path_utils: file_path_utils, file_finder: file_finder, extractor: extractor, resolver: resolver }
+  end
+
+  def scan(extractor, tests)
+    tests.each { |test| extractor.collect_simple_context_from_file( test, nil, TestContextExtractor::Context::BUILD_DIRECTIVE_SOURCE_FILES ) }
+  end
+
+  it "passes a test's real entries, including one reached through .." do
+    in_temp_project( project_files ) do
+      o = objects
+      tests = %w[test/test_m1.c test/test_m2.c test/unit/test_m3.c]
+      scan( o[:extractor], tests )
+
+      tests.each do |test|
+        expect { o[:resolver].validate!( test: test.ext( '' ), test_filepath: test, context: :test ) }.to_not raise_error
+      end
+    end
+  end
+
+  it 'names the test that holds a missing entry' do
+    in_temp_project( project_files.merge( 'test/test_m2.c' => test_file( ['calc_typo.c'] ) ) ) do
+      o = objects
+      scan( o[:extractor], %w[test/test_m1.c test/test_m2.c] )
+
+      expect { o[:resolver].validate!( test: 'test/test_m1', test_filepath: 'test/test_m1.c', context: :test ) }.to_not raise_error
+      expect { o[:resolver].validate!( test: 'test/test_m2', test_filepath: 'test/test_m2.c', context: :test ) }.to raise_error(
+        CeedlingException, %r{'calc_typo\.c' specified with TEST_SOURCE_FILE\(\) in test/test_m2 cannot be found}
+      )
+    end
+  end
+
+  it 'stops for a misspelled removal entry, which otherwise leaves its file in the build' do
+    in_temp_project( project_files.merge( 'test/test_m1.c' => test_file( ['-:clac.c'] ) ) ) do
+      o = objects
+      scan( o[:extractor], %w[test/test_m1.c] )
+
+      expect { o[:resolver].validate!( test: 'test/test_m1', test_filepath: 'test/test_m1.c', context: :test ) }.to raise_error(
+        CeedlingException, /'clac\.c'.*cannot be found/
+      )
+    end
+  end
+
+  it 'notes an entry matching several files once, however many tests name it' do
+    files = project_files.merge( %w[test/test_m1.c test/test_m2.c test/unit/test_m3.c].to_h { |test| [test, test_file( ['a/dup.c'] )] } )
+
+    in_temp_project( files ) do
+      o = objects
+      tests = %w[test/test_m1.c test/test_m2.c test/unit/test_m3.c]
+      scan( o[:extractor], tests )
+
+      tests.each do |test|
+        o[:resolver].validate!( test: test.ext( '' ), test_filepath: test, context: :test )
+        o[:resolver].resolve( test, :test )
+      end
+
+      expect( logged.grep( /Multiple files matched 'a\/dup\.c'/ ).size ).to eq( 1 )
+    end
+  end
+
+  # Without test preprocessing, stage 2 scans the entries and checks them
+  it 'checks each test under its own name in stage 2 without test preprocessing' do
+    in_temp_project( project_files.merge( 'test/unit/test_m3.c' => test_file( ['nowhere.c'] ) ) ) do
+      o = objects
+      setup = TestBuildSetup.new( TestBuildSetup.constructor_keys.to_h { |key| [key, double( key.to_s ).as_null_object] }.merge(
+        configurator: o[:configurator], batchinator: TestSourceFileChecksBatchinator.new, test_context_extractor: o[:extractor],
+        file_path_utils: o[:file_path_utils], file_finder: o[:file_finder], test_source_file_directive_resolver: o[:resolver],
+        file_wrapper: FileWrapper.new( loginator: double( 'loginator', log: nil ), verbosinator: double( 'verbosinator', should_output?: false ) ),
+        dependinator: double( 'dependinator', register: nil, stale?: true, mark_fresh: nil ),
+        reportinator: double( 'reportinator', generate_progress: '', generate_skip_summary: nil )
+      ) )
+      tests = %w[test/test_m1.c test/test_m2.c test/unit/test_m3.c]
+      state = TestInvokerTypes::PipelineState.new( tests: tests, testables: {}, context: :test, options: [], lock: Mutex.new )
+      setup.stage_prepare_build_paths( state )
+
+      expect { setup.stage_collect_test_context( state ) }.to raise_error(
+        CeedlingException, %r{'nowhere\.c' specified with TEST_SOURCE_FILE\(\) in test/unit/test_m3 cannot be found}
+      )
+    end
+  end
+end

data/spec/integration/tool_validator_spec.rb

@@ -17,7 +17,7 @@ require 'spec_helper'
 require 'spec_integration_helper'
 require 'fileutils'
 require 'ceedling/tool_validator'
-require 'ceedling/file_wrapper'
+require 'ceedling/filesystem/file_wrapper'
 require 'ceedling/system_wrapper'
 require 'ceedling/ruby_expandinator'
 require 'ceedling/filename_extension'

data/spec/integration/upgrade_docs_spec.rb

@@ -0,0 +1,84 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# GH #1371: `upgrade` never refreshed documentation that `new --docs` exported, because it
+# looked for a file exports stopped writing in 1.1.0. For a 1.0.x export, which it did
+# find, it removed all of docs/, the project's own files included.
+#
+# These run the real launcher against real projects. Nothing compiles, so no toolchain is
+# needed.
+
+require 'spec_helper'
+require 'tmpdir'
+require 'fileutils'
+require 'open3'
+require 'rbconfig'
+
+describe '`upgrade` and exported documentation' do
+  REPO = File.expand_path( '../..', __dir__ )
+  UNITY_PAGE = File.join( 'unity', 'UnityGettingStartedGuide.md' )
+
+  def ceedling(*args)
+    stdout, stderr, status = Open3.capture3(
+      {'CEEDLING_DECORATORS' => 'false'}, RbConfig.ruby, File.join( REPO, 'bin', 'ceedling' ), *args, chdir: @tmp
+    )
+    raise "`ceedling #{args.join( ' ' )}` failed:\n#{stdout}#{stderr}" unless status.success?
+  end
+
+  def docs(*entry)
+    return File.join( @tmp, 'proj', 'docs', *entry )
+  end
+
+  def write(entry, text='')
+    FileUtils.mkdir_p( File.dirname( docs( entry ) ) )
+    File.write( docs( entry ), text )
+  end
+
+  around(:each) do |example|
+    Dir.mktmpdir( 'upgrade_docs' ) { |dir| @tmp = dir; example.run }
+  end
+
+  it 'refreshes an export of 1.1.0 or later and keeps the project\'s own files' do
+    ceedling( 'new', '--local', '--docs', 'proj' )
+    write( 'notes.md', 'mine' )
+    write( File.join( 'unity', 'stale.md' ) )
+    write( UNITY_PAGE, 'edited' )
+
+    ceedling( 'upgrade', 'proj' )
+
+    expect(File.exist?( docs( 'unity', 'stale.md' ) )).to be( false )
+    expect(File.read( docs( UNITY_PAGE ) )).to eq( File.read( File.join( REPO, 'vendor', 'unity', 'docs', 'UnityGettingStartedGuide.md' ) ) )
+    expect(File.read( docs( 'notes.md' ) )).to eq( 'mine' )
+  end
+
+  it 'replaces a 1.0.x export with the current layout and keeps the project\'s own files' do
+    ceedling( 'new', '--local', 'proj' )
+    write( 'CeedlingPacket.md' )
+    write( 'Changelog.md' )
+    write( File.join( 'plugins', 'gcov.md' ) )
+    write( File.join( 'unity', 'stale.md' ) )
+    write( 'license.txt' )
+    write( 'notes.md', 'mine' )
+
+    ceedling( 'upgrade', 'proj' )
+
+    ['CeedlingPacket.md', 'Changelog.md', 'plugins', File.join( 'unity', 'stale.md' )].each do |entry|
+      expect(File.exist?( docs( entry ) )).to be( false ), entry
+    end
+    expect(File.exist?( docs( UNITY_PAGE ) )).to be( true )
+    expect(File.read( docs( 'notes.md' ) )).to eq( 'mine' )
+  end
+
+  it 'leaves a docs/ holding only the project\'s own files alone' do
+    ceedling( 'new', '--local', 'proj' )
+    write( 'notes.md', 'mine' )
+
+    ceedling( 'upgrade', 'proj' )
+
+    expect(Dir.children( docs )).to eq( ['notes.md'] )
+  end
+end

data/spec/integration/vendor_copy_transient_io_retry_spec.rb

@@ -5,126 +5,243 @@
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
-# Integration coverage for Issue #1292: a vendor destination (build/vendor/unity/src,
-# etc.) occasionally turns up as the wrong file/directory type mid-copy, crashing with
-# Errno::ENOTDIR/EISDIR. Does FileWrapper#cp_r_with_retry actually let
-# ConfiguratorSetup#vendor_frameworks_and_support_files ride out a transient fault of
-# that shape, end to end against a real filesystem -- and does a fault that never
-# clears still surface as a clear, path-naming CeedlingException rather than a raw Errno?
+# ConfiguratorSetup#vendor_frameworks_and_support_files with a real FileWrapper on a real
+# filesystem. A build brings build/vendor up to date with the gem's frameworks. It writes only
+# a file that differs from its source, and replaces it whole by renaming a temporary copy over
+# it, so a concurrent build never reads a half-written header (GH #1361). An entry of the
+# wrong type, such as a directory where a file belongs, is replaced (GH #1292, #1376). A
+# transient copy fault, such as a scanner holding a file open, is retried, and one that never
+# clears names the destination.
 #
-# Modeled directly on spec/integration/preprocessing_transient_io_retry_spec.rb: a real
-# ConfiguratorSetup + real FileWrapper subclass that controls exactly one #cp_r call
-# (matched by destination path) so the fault is deterministic. Faulting at #cp_r rather
-# than #cp_r_with_retry itself matters here -- cp_r_with_retry's own retry loop (already
-# proven exhaustively in file_wrapper_spec.rb) is exactly the mechanism this spec needs
-# to actually run.
+# Faults are injected at FileWrapper#replace_file, the one write of each file, so the retry
+# loop in FileTree is what runs.
 
 require 'spec_helper'
 require 'spec_integration_helper'
+require 'file_tree_helper'
 require 'ceedling/config/configurator_setup'
 require 'ceedling/constants'
 
-describe 'Vendor-copy transient I/O retry (integration)' do
+describe 'Vendor copy into build/vendor (integration)' do
   include IntegrationSpecHelpers
+  include FileTreeHelper
 
-  # A real FileWrapper whose #cp_r raises for `fault_dest` the first `raises_left`
-  # times it's called, then behaves normally -- every other destination is untouched.
-  # Real FileWrapper#cp_r_with_retry (inherited, not overridden) is what actually retries.
-  # Named distinctly from preprocessing_transient_io_retry_spec.rb's own FaultingFileWrapper
-  # -- both are top-level classes loaded into the same RSpec process, and Ruby's open
-  # classes would otherwise let the second file's definition silently clobber the first's.
-  class CpRFaultingFileWrapper < FileWrapper
-    def initialize(fault_dest:, raises_left: 1, error: Errno::EISDIR, **kwargs)
+  # A real FileWrapper whose #replace_file raises for files beneath `fault_dir` the first
+  # `raises_left` times. Named apart from other specs' faulting wrappers, since top-level
+  # classes share one RSpec process.
+  class ReplaceFaultingFileWrapper < FileWrapper
+    def initialize(fault_dir:, raises_left: 1, error: Errno::EACCES, **kwargs)
       super(**kwargs)
-      @fault_dest = fault_dest
+      @fault_dir = fault_dir
       @raises_left = raises_left
       @error = error
     end
 
-    def cp_r(source, destination, options={})
-      if destination == @fault_dest && @raises_left > 0
+    def replace_file(source, destination)
+      if destination.start_with?( @fault_dir ) && @raises_left > 0
         @raises_left -= 1
-        raise @error, "simulated transient type-mismatch on #{destination}"
+        raise @error, "simulated fault on #{destination}"
       end
       super
     end
   end
 
-  # Real ConfiguratorSetup wired to `file_wrapper`; every other collaborator is
-  # untouched by #vendor_frameworks_and_support_files, so NULL stands in for them.
+  def file_wrapper(**fault)
+    options = { loginator: IntegrationSpecHelpers::NULL, verbosinator: IntegrationSpecHelpers::NULL }
+    return fault.empty? ? FileWrapper.new( options ) : ReplaceFaultingFileWrapper.new( **fault, **options )
+  end
+
   def build_configurator_setup(file_wrapper)
     ConfiguratorSetup.new(
       configurator_builder:   IntegrationSpecHelpers::NULL,
       configurator_validator: IntegrationSpecHelpers::NULL,
-      loginator:               IntegrationSpecHelpers::NULL,
-      reportinator:            IntegrationSpecHelpers::NULL,
-      file_wrapper:            file_wrapper,
-      system_wrapper:          IntegrationSpecHelpers::NULL,
-      tool_executor:           IntegrationSpecHelpers::NULL
+      configurator_paths_validator: IntegrationSpecHelpers::NULL,
+      loginator:              IntegrationSpecHelpers::NULL,
+      reportinator:           IntegrationSpecHelpers::NULL,
+      file_wrapper:           file_wrapper,
+      system_wrapper:         IntegrationSpecHelpers::NULL,
+      tool_executor:          IntegrationSpecHelpers::NULL
     )
   end
 
-  # A minimal but real fixture standing in for the gem's own vendor/unity/src -- one
-  # real file, so a real FileUtils.cp_r has real directory-tree content to walk.
+  # A stand-in for the gem's vendor/unity/src, with a nested file to show subdirectories copy
   def flattened_config(dir)
-    unity_src = File.join(dir, 'gem_vendor', 'unity', 'src')
-    FileUtils.mkdir_p(unity_src)
-    File.write(File.join(unity_src, 'unity.c'), "// stand-in for the real unity.c\n")
+    unity_src = File.join( dir, 'gem_vendor', 'unity', 'src' )
+    FileUtils.mkdir_p( File.join( unity_src, 'internal' ) )
+    File.write( File.join( unity_src, 'unity.c' ), "// stand-in for unity.c\n" )
+    File.write( File.join( unity_src, 'unity.h' ), "// stand-in for unity.h\n" )
+    File.write( File.join( unity_src, 'internal', 'unity_internals.h' ), "// stand-in\n" )
 
     {
-      # UNITY_LIB_PATH ('unity/src') is joined onto this root -- it must be the
-      # vendor root, not 'unity' itself, matching CEEDLING_VENDOR's real shape.
-      unity_vendor_path:                     File.join(dir, 'gem_vendor'),
-      project_build_vendor_unity_path:       File.join(dir, 'build', 'vendor', 'unity', 'src'),
-      project_use_mocks:                     false,
-      project_use_exceptions:                false,
-      project_use_backtrace:                 false,
-      project_use_partials:                  false,
+      # UNITY_LIB_PATH ('unity/src') joins this vendor root
+      unity_vendor_path:               File.join( dir, 'gem_vendor' ),
+      project_build_vendor_unity_path: File.join( dir, 'build', 'vendor', 'unity', 'src' ),
+      project_use_mocks:               false,
+      project_use_exceptions:          false,
+      project_use_backtrace:           :none,
+      project_use_partials:            false,
     }
   end
 
-  it "recovers from a transient copy failure on its own vendor destination instead of crashing the build" do
+  def vendor(file_wrapper, dir, config)
+    build_configurator_setup( file_wrapper ).vendor_frameworks_and_support_files( dir, config, test_build: true, release_build: false )
+  end
+
+  def snapshot(dest)
+    return Dir.glob( File.join( dest, '**', '*' ) ).select { |path| File.file?( path ) }.to_h do |path|
+      stat = File.stat( path )
+      [path, [stat.ino, stat.mtime]]
+    end
+  end
+
+  def leftovers(dest)
+    return Dir.glob( File.join( dest, '**', '*' ), File::FNM_DOTMATCH ).select { |path| File.basename( path ).include?( '.tmp' ) }
+  end
+
+  it "copies every file, including those in subdirectories, into a fresh destination" do
     with_source_tree({}) do |dir|
-      config = flattened_config(dir)
+      config = flattened_config( dir )
       dest = config[:project_build_vendor_unity_path]
-      # Real usage always runs build_directory_structure (which mkdir_p's every
-      # vendor destination) before this copy -- match that precondition here so the
-      # only fault in play is the one this spec injects, not a missing parent dir.
-      FileUtils.mkdir_p(dest)
-
-      # Exactly one raise, well within cp_r_with_retry's own retry budget -- the
-      # source is otherwise 100% fine, the real copy proceeds either way.
-      faulting_fw = CpRFaultingFileWrapper.new(
-        fault_dest: dest, raises_left: 1,
-        loginator: IntegrationSpecHelpers::NULL, verbosinator: IntegrationSpecHelpers::NULL
-      )
-      setup = build_configurator_setup(faulting_fw)
 
-      expect {
-        setup.vendor_frameworks_and_support_files(dir, config)
-      }.not_to raise_error
+      vendor( file_wrapper, dir, config )
+
+      expect( File.read( File.join( dest, 'unity.h' ) ) ).to eq( "// stand-in for unity.h\n" )
+      expect( File.exist?( File.join( dest, 'internal', 'unity_internals.h' ) ) ).to be(true)
+      expect( leftovers( dest ) ).to be_empty
+    end
+  end
+
+  it "rewrites nothing when the destination already matches" do
+    with_source_tree({}) do |dir|
+      config = flattened_config( dir )
+      dest = config[:project_build_vendor_unity_path]
+      vendor( file_wrapper, dir, config )
+      before = snapshot( dest )
+      sleep( 1.1 ) # Past the coarsest file modification time resolution
 
-      expect(File.exist?(File.join(dest, 'unity.c'))).to be true
+      vendor( file_wrapper, dir, config )
+
+      expect( snapshot( dest ) ).to eq( before )
+    end
+  end
+
+  it "restores an edited file by replacing it whole, and leaves matching files alone" do
+    with_source_tree({}) do |dir|
+      config = flattened_config( dir )
+      dest = config[:project_build_vendor_unity_path]
+      vendor( file_wrapper, dir, config )
+      edited = File.join( dest, 'unity.h' )
+      File.write( edited, "// an errant edit\n" )
+      before = snapshot( dest )
+
+      vendor( file_wrapper, dir, config )
+
+      expect( File.read( edited ) ).to eq( "// stand-in for unity.h\n" )
+      expect( File.stat( edited ).ino ).not_to eq( before[edited].first ) unless SystemWrapper.windows?
+      untouched = File.join( dest, 'unity.c' )
+      expect( snapshot( dest )[untouched] ).to eq( before[untouched] )
+      expect( leftovers( dest ) ).to be_empty
     end
   end
 
-  it "still raises a clear, path-naming CeedlingException when the fault never clears" do
+  it "restores a missing file" do
     with_source_tree({}) do |dir|
-      config = flattened_config(dir)
+      config = flattened_config( dir )
       dest = config[:project_build_vendor_unity_path]
-      FileUtils.mkdir_p(dest)
+      vendor( file_wrapper, dir, config )
+      FileUtils.rm( File.join( dest, 'internal', 'unity_internals.h' ) )
+
+      vendor( file_wrapper, dir, config )
+
+      expect( File.exist?( File.join( dest, 'internal', 'unity_internals.h' ) ) ).to be(true)
+    end
+  end
+
+  it "recovers from a transient copy failure instead of crashing the build" do
+    with_source_tree({}) do |dir|
+      config = flattened_config( dir )
+      dest = config[:project_build_vendor_unity_path]
+
+      expect { vendor( file_wrapper( fault_dir: dest, raises_left: 1 ), dir, config ) }.not_to raise_error
 
-      # More raises than cp_r_with_retry's own retry budget (initial attempt + 4
-      # retries) -- every attempt fails, so the fault genuinely never clears.
-      permanently_faulting_fw = CpRFaultingFileWrapper.new(
-        fault_dest: dest, raises_left: 999,
-        loginator: IntegrationSpecHelpers::NULL, verbosinator: IntegrationSpecHelpers::NULL
-      )
-      setup = build_configurator_setup(permanently_faulting_fw)
+      expect( File.exist?( File.join( dest, 'unity.c' ) ) ).to be(true)
+      expect( leftovers( dest ) ).to be_empty
+    end
+  end
+
+  it "raises a clear, path-naming CeedlingException when the fault never clears" do
+    with_source_tree({}) do |dir|
+      config = flattened_config( dir )
+      dest = config[:project_build_vendor_unity_path]
 
       expect {
-        setup.vendor_frameworks_and_support_files(dir, config)
-      }.to raise_error(CeedlingException, /#{Regexp.escape(dest)}/)
+        vendor( file_wrapper( fault_dir: dest, raises_left: 999 ), dir, config )
+      }.to raise_error( CeedlingException, /#{Regexp.escape( dest )}/ )
+    end
+  end
+  # GH #1376: a deduplicated file the reporter's lstat called a directory left one where any
+  # vendored file belongs, not only the framework's own .c file
+  it "replaces a directory where any vendored file belongs" do
+    with_source_tree({}) do |dir|
+      config = flattened_config( dir )
+      dest = config[:project_build_vendor_unity_path]
+      FileUtils.mkdir_p( File.join( dest, 'unity.h' ) )
+      write( File.join( dest, 'internal', 'unity_internals.h', 'junk' ) )
+
+      vendor( file_wrapper, dir, config )
+
+      expect( File.read( File.join( dest, 'unity.h' ) ) ).to eq( "// stand-in for unity.h\n" )
+      expect( File.file?( File.join( dest, 'internal', 'unity_internals.h' ) ) ).to be(true)
+    end
+  end
+
+  it "vendors every file as a file when lstat reports files as directories" do
+    with_source_tree({}) do |dir|
+      config = flattened_config( dir )
+      dest = config[:project_build_vendor_unity_path]
+      lie_about_lstat( %r{gem_vendor/} )
+
+      begin
+        vendor( file_wrapper, dir, config )
+      ensure
+        # The temporary directory is removed by an lstat-based remover
+        allow(File).to receive(:lstat).and_call_original
+      end
+
+      expect( File.file?( File.join( dest, 'unity.c' ) ) ).to be(true)
+      expect( File.file?( File.join( dest, 'internal', 'unity_internals.h' ) ) ).to be(true)
+    end
+  end
+
+  # A read-only gem install would otherwise vendor read-only files, which Windows will not
+  # let a later rename replace
+  it "vendors owner-writable files from a read-only source, and replaces a read-only destination" do
+    with_source_tree({}) do |dir|
+      config = flattened_config( dir )
+      dest = config[:project_build_vendor_unity_path]
+      source = File.join( config[:unity_vendor_path], 'unity', 'src', 'unity.h' )
+      File.chmod( 0o444, source )
+      vendor( file_wrapper, dir, config )
+      expect( File.stat( File.join( dest, 'unity.h' ) ).mode & 0o200 ).to eq( 0o200 )
+
+      File.chmod( 0o644, source )
+      File.write( source, "// a newer unity.h\n" )
+      File.chmod( 0o444, File.join( dest, 'unity.h' ) )
+      vendor( file_wrapper, dir, config )
+
+      expect( File.read( File.join( dest, 'unity.h' ) ) ).to eq( "// a newer unity.h\n" )
+    end
+  end
+
+  it "fails at once on an error retrying cannot clear" do
+    with_source_tree({}) do |dir|
+      config = flattened_config( dir )
+      dest = config[:project_build_vendor_unity_path]
+      faulting = file_wrapper( fault_dir: dest, raises_left: 999, error: Errno::ENOSPC )
+      allow(faulting).to receive(:sleep)
+
+      expect { vendor( faulting, dir, config ) }.to raise_error( Errno::ENOSPC )
+      expect(faulting).not_to have_received(:sleep)
     end
   end
 end

data/spec/support/file_tree_helper.rb

@@ -0,0 +1,88 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'delegate'
+require 'fileutils'
+require 'tmpdir'
+
+# Support for specs that copy real file trees (`filesystem: true`).
+#
+# CEEDLING_TEST_FS_ROOT names a directory on another filesystem, such as a tmpfs, a vfat
+# image, a UNC share, or a VHD volume. These specs then build their trees there instead of
+# the system temp directory, so CI can run one suite on several filesystems.
+module FileTreeHelper
+  ROOT_ENV = 'CEEDLING_TEST_FS_ROOT'
+
+  # A stat result that claims a directory. Reproduces a filesystem whose `lstat` reports a
+  # regular file as a directory.
+  class LyingStat < SimpleDelegator
+    def directory?
+      true
+    end
+
+    def file?
+      false
+    end
+
+    def symlink?
+      false
+    end
+
+    def ftype
+      'directory'
+    end
+
+    def mode
+      (__getobj__.mode & ~0o170000) | 0o040000
+    end
+  end
+
+  # A temporary directory on the filesystem under test, removed afterwards
+  def with_tree_root
+    root = ENV[ROOT_ENV].to_s
+    dir = root.empty? ? Dir.mktmpdir( 'tree' ) : Dir.mktmpdir( 'tree', root )
+    yield File.realpath( dir )
+  ensure
+    FileUtils.rm_rf( dir ) if dir
+  end
+
+  def write(path, content = File.basename( path ))
+    FileUtils.mkdir_p( File.dirname( path ) )
+    File.binwrite( path, content )
+  end
+
+  def symlink_or_skip(target, link)
+    File.symlink( target, link )
+  rescue NotImplementedError, SystemCallError => e
+    skip "symlinks are unavailable here (#{e.class})"
+  end
+
+  # Every entry below `dir`, dotfiles included, as sorted relative paths
+  def tree_of(dir)
+    Dir.glob( '**/*', File::FNM_DOTMATCH, base: dir ).reject { |path| path == '.' || path.end_with?( '/.' ) }.sort
+  end
+
+  # Makes `File.lstat` lie, claiming a directory, for each path matching `pattern`
+  def lie_about_lstat(pattern)
+    allow(File).to receive(:lstat).and_wrap_original do |original, path, *rest|
+      status = original.call( path, *rest )
+      path.to_s.match?( pattern ) ? LyingStat.new( status ) : status
+    end
+  end
+
+  # Fails any `File.lstat` call, proving code under test never classifies by it
+  def forbid_lstat
+    allow(File).to receive(:lstat).and_raise( RuntimeError, 'File.lstat must not be called' )
+  end
+
+  # The publish step FileWrapper#replace_file performs: a whole copy renamed into place
+  PUBLISH = lambda do |source, destination|
+    temp = "#{destination}.publishing"
+    FileUtils.cp( source, temp )
+    File.rename( temp, destination )
+  end
+end