ceedling 1.2.0 → 1.2.2

data/spec/units/config/configurator_validator_spec.rb

@@ -11,21 +11,17 @@ require 'ceedling/config/configurator_validator'
 require 'ceedling/config/config_walkinator'
 require 'ceedling/reportinator'
 
-# Unit coverage for ConfiguratorValidator through a doubled file layer. What these
-# validations make of a real project tree is proven in
-# spec/integration/configurator_validation_spec.rb.
+# Unit coverage for ConfiguratorValidator's checks of required entries, tools, and matchers
 describe ConfiguratorValidator do
   include ConfigYamlHelper
 
   before(:each) do
-    @file_wrapper   = double('file_wrapper')
     @loginator      = double('loginator', log: nil)
     @tool_validator = double('tool_validator')
 
     @validator = described_class.new(
       {
         config_walkinator: ConfigWalkinator.new,
-        file_wrapper:      @file_wrapper,
         loginator:         @loginator,
         reportinator:      Reportinator.new,
         tool_validator:    @tool_validator
@@ -33,14 +29,6 @@ describe ConfiguratorValidator do
     )
   end
 
-  def existing(*paths)
-    allow(@file_wrapper).to receive(:exist?) { |path| paths.include?( path ) }
-  end
-
-  def directories(*paths)
-    allow(@file_wrapper).to receive(:directory?) { |path| paths.include?( path ) }
-  end
-
   describe '#exists?' do
     let(:config) { config_from_yaml( ":project:\n  :build_root: build\n  :use_mocks: false\n" ) }
 
@@ -58,165 +46,6 @@ describe ConfiguratorValidator do
     end
   end
 
-  describe '#validate_path_list' do
-    let(:config) { config_from_yaml( ":paths:\n  :test:\n    - +:test/**\n    - -:test/ignore\n    - '**/generated'\n" ) }
-
-    it 'checks each path stripped of its aggregation decorator and glob' do
-      existing('test', 'test/ignore')
-      expect(@validator.validate_path_list( config, :paths, :test )).to be true
-    end
-
-    it 'skips a path that begins with a glob' do
-      existing('test', 'test/ignore')
-      @validator.validate_path_list( config, :paths, :test )
-      expect(@file_wrapper).to_not have_received(:exist?).with('')
-    end
-
-    it 'logs each path that does not exist' do
-      existing('test')
-      expect(@validator.validate_path_list( config, :paths, :test )).to be false
-      expect(@loginator).to have_received(:log).with("Config path :paths ↳ :test => 'test/ignore' does not exist in the filesystem.", Verbosity::ERRORS)
-    end
-
-    it 'fails a missing entry' do
-      expect(@validator.validate_path_list( config, :paths, :source )).to be false
-    end
-  end
-
-  # An entry naming no path, or wrapping its path in quotes, is rejected before any
-  # filesystem check. Both usually come from quoting only the path after a +: or -:
-  # decoration, so each rejection carries a hint about quoting.
-  shared_examples 'an entry that names no usable path' do |walk|
-    {
-      'a bare subtractive decoration' => "    - '-:'\n",
-      'a bare additive decoration'    => "    - '+:'\n",
-      'an empty string'               => "    - ''\n",
-      'whitespace alone'              => "    - '   '\n",
-      'a YAML null'                   => "    -\n",
-    }.each_pair do |label, yaml|
-      it "rejects #{label} as naming no path, with a quoting hint" do
-        expect(validate( yaml )).to be false
-        expect(@loginator).to have_received(:log).with(/#{Regexp.escape(walk)} => '.*' names no path/, Verbosity::ERRORS)
-        expect(@loginator).to have_received(:log).with(/Quote the whole entry/, Verbosity::ERRORS)
-      end
-    end
-
-    # YAML reads an unquoted decoration with nothing after it as a one-key mapping
-    it 'rejects an entry YAML read as something other than a path, with a quoting hint' do
-      expect(validate( "    - -:\n" )).to be false
-      expect(@loginator).to have_received(:log).with(/#{Regexp.escape(walk)} => '.*' is not a path \(YAML read it as a Hash\)/, Verbosity::ERRORS)
-      expect(@loginator).to have_received(:log).with(/Quote the whole entry/, Verbosity::ERRORS)
-    end
-
-    it 'rejects a path wrapped in quotes after its decoration, with a quoting hint' do
-      expect(validate( "    - '-:\"src/a.c\"'\n" )).to be false
-      expect(@loginator).to have_received(:log).with(/#{Regexp.escape(walk)} => '-:"src\/a.c"' wraps its path in quotes/, Verbosity::ERRORS)
-      expect(@loginator).to have_received(:log).with(/Quote the whole entry/, Verbosity::ERRORS)
-    end
-  end
-
-  describe '#validate_paths_entries' do
-    def validate(yaml_list)
-      @validator.validate_paths_entries( config_from_yaml( ":paths:\n  :source:\n#{yaml_list}" ), :source )
-    end
-
-    it 'accepts a glob that yields directories' do
-      existing; directories('src', 'src/a')
-      allow(@file_wrapper).to receive(:directory_listing).with('src/**/**').and_return(['src', 'src/a', 'src/a/x.c'])
-
-      expect(validate( "    - src/**\n" )).to be true
-    end
-
-    it 'warns about and skips a path naming a file' do
-      existing('src/main.c'); directories
-
-      expect(validate( "    - src/main.c\n" )).to be true
-      expect(@loginator).to have_received(:log).with(/'src\/main.c' is a filepath and will be ignored/, Verbosity::COMPLAIN)
-    end
-
-    it 'accepts a subdirectory glob of a directory that has no subdirectories' do
-      existing; directories
-      allow(@file_wrapper).to receive(:directory_listing).and_return([])
-
-      expect(validate( "    - src/*\n" )).to be true
-    end
-
-    it 'logs a path that yields no directories' do
-      existing; directories
-      allow(@file_wrapper).to receive(:directory_listing).and_return([])
-
-      expect(validate( "    - -:src/missing\n" )).to be false
-      expect(@loginator).to have_received(:log).with(/'src\/missing' yielded no directories/, Verbosity::ERRORS)
-    end
-
-    it 'escapes literal brackets before globbing' do
-      existing; directories('src/[legacy]')
-      allow(@file_wrapper).to receive(:directory_listing).with('src/\[legacy\]').and_return(['src/[legacy]'])
-
-      expect(validate( "    - 'src/[legacy]'\n" )).to be true
-    end
-
-    it 'fails a missing entry' do
-      expect(@validator.validate_paths_entries( { paths: {} }, :source )).to be false
-    end
-
-    it_behaves_like 'an entry that names no usable path', ':paths ↳ :source'
-  end
-
-  describe '#validate_files_entries' do
-    def validate(yaml_list)
-      @validator.validate_files_entries( config_from_yaml( ":files:\n  :source:\n#{yaml_list}" ), :source )
-    end
-
-    it 'accepts a glob that yields files' do
-      existing; directories
-      allow(@file_wrapper).to receive(:instantiate_file_list).with('src/*.c').and_return(['src/a.c'])
-
-      expect(validate( "    - +:src/*.c\n" )).to be true
-    end
-
-    it 'warns about and skips a path naming a directory' do
-      existing('src'); directories('src')
-
-      expect(validate( "    - src\n" )).to be true
-      expect(@loginator).to have_received(:log).with(/'src' is a directory path and will be ignored/, Verbosity::COMPLAIN)
-    end
-
-    it 'logs a glob that yields no files' do
-      existing; directories
-      allow(@file_wrapper).to receive(:instantiate_file_list).and_return([])
-
-      expect(validate( "    - src/*.x\n" )).to be false
-      expect(@loginator).to have_received(:log).with(/'src\/\*.x' yielded no files/, Verbosity::ERRORS)
-    end
-
-    it 'escapes literal brackets before globbing' do
-      existing; directories
-      allow(@file_wrapper).to receive(:instantiate_file_list).with('src/\[legacy\]/*.c').and_return(['src/[legacy]/a.c'])
-
-      expect(validate( "    - 'src/[legacy]/*.c'\n" )).to be true
-    end
-
-    it 'fails a missing entry' do
-      expect(@validator.validate_files_entries( { files: {} }, :source )).to be false
-    end
-
-    it_behaves_like 'an entry that names no usable path', ':files ↳ :source'
-  end
-
-  describe '#validate_filepath_simple' do
-    it 'accepts an existing path' do
-      existing('helper.h')
-      expect(@validator.validate_filepath_simple( 'helper.h', :cmock, :unity_helper_path )).to be true
-    end
-
-    it 'logs a missing path with the configuration walk it came from' do
-      existing
-      expect(@validator.validate_filepath_simple( 'helper.h', :cmock, :unity_helper_path )).to be false
-      expect(@loginator).to have_received(:log).with("Config path 'helper.h' associated with :cmock ↳ :unity_helper_path does not exist in the filesystem.", Verbosity::ERRORS)
-    end
-  end
-
   describe '#validate_tool' do
     let(:config) { { tools: { test_compiler: { executable: 'gcc' } }, extension: { executable: '.out' } } }
 

data/spec/units/default_tools_quoting_spec.rb

@@ -0,0 +1,83 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'spec_helper'
+require 'shellwords'
+require 'yaml'
+require 'ceedling/defaults'
+require 'ceedling/tool_executor'
+require 'ceedling/ruby_expandinator'
+
+load File.expand_path( '../../plugins/gcov/config/defaults_gcov.rb', __dir__ )
+load File.expand_path( '../../plugins/bullseye/config/defaults_bullseye.rb', __dir__ )
+load File.expand_path( '../../plugins/cppcheck/config/defaults_cppcheck.rb', __dir__ )
+
+# GH #1373: the default tools that run a test executable named it unquoted, so a path holding
+# an apostrophe or a space broke the shell command. Each command here is split as a POSIX
+# shell splits it, and every path must come back as one word, exactly as given.
+describe 'Default tools' do
+  SPECIAL_PATH = "build/test/out/test/o'neil dir/test_q/test_q.out"
+  OTHER_PATH   = "src/my dir/o'neil.c"
+
+  DEPENDENCIES_TOOLS = YAML.load_file(
+    File.expand_path( '../../plugins/dependencies/config/defaults.yml', __dir__ ), symbolize_names: true
+  )[:tools]
+
+  before(:each) do
+    helper = double('tool_executor_helper').as_null_object
+    allow(helper).to receive(:osify_path_separators) { |path| path }
+    system_wrapper = double('system_wrapper').as_null_object
+    allow(system_wrapper).to receive(:constants_include?).and_return( false )
+
+    @tool_executor = ToolExecutor.new(
+      {
+        :tool_executor_helper => helper,
+        :loginator            => double('loginator').as_null_object,
+        :verbosinator         => double('verbosinator').as_null_object,
+        :system_wrapper       => system_wrapper,
+        :ruby_expandinator    => RubyExpandinator.new
+      }
+    )
+  end
+
+  # Configuration hands Ceedling an unfrozen copy of each default tool
+  def words(tool, *args)
+    Shellwords.split( @tool_executor.build_command_line( Marshal.load( Marshal.dump( tool ) ), [], *args )[:line] )
+  end
+
+  {
+    'test fixture'                   => DEFAULT_TEST_FIXTURE_TOOL,
+    'gcov fixture'                   => DEFAULT_GCOV_FIXTURE_TOOL,
+    'Bullseye fixture'               => DEFAULT_BULLSEYE_FIXTURE_TOOL,
+  }.each do |name, tool|
+    it "names the test executable as one word in the #{name}" do
+      expect( words( tool, SPECIAL_PATH ) ).to eq( [SPECIAL_PATH] )
+    end
+  end
+
+  it 'names the test executable as one word in a simple backtrace rerun' do
+    expect( words( DEFAULT_TEST_FIXTURE_SIMPLE_BACKTRACE_TOOL, SPECIAL_PATH, '-n "test_a"' ) ).to eq( [SPECIAL_PATH, '-n', 'test_a'] )
+  end
+
+  it 'names the test executable as one word in a gdb backtrace' do
+    expect( words( DEFAULT_TEST_BACKTRACE_GDB_TOOL, 'build/gdb.txt', SPECIAL_PATH, '-n "test_a"' ).last( 3 ) ).to eq( [SPECIAL_PATH, '-n', 'test_a'] )
+  end
+
+  it 'names each source file as one word for cppcheck' do
+    expect( words( DEFAULT_CPPCHECK_TOOL, ['src'], [OTHER_PATH, 'src/b.c'] ).last( 2 ) ).to eq( [OTHER_PATH, 'src/b.c'] )
+  end
+
+  it 'names the library and each object as one word for the Dependencies archiver' do
+    expect( words( DEPENDENCIES_TOOLS[:deps_linker], [OTHER_PATH, 'b.o'], 'build/my dir/libx.a' ) ).to eq(
+      ['ar', 'rcs', 'build/my dir/libx.a', OTHER_PATH, 'b.o']
+    )
+  end
+
+  it 'names the archive as one word for the Dependencies zip unarchiver' do
+    expect( words( DEPENDENCIES_TOOLS[:deps_zip], 'vendor/my dir/x.zip' ) ).to eq( ['unzip', '-o', 'vendor/my dir/x.zip'] )
+  end
+end

data/spec/units/dependencies/dependency_cache_store_spec.rb

@@ -7,7 +7,7 @@
 
 require 'spec_helper'
 require 'json'
-require 'ceedling/file_wrapper'
+require 'ceedling/filesystem/file_wrapper'
 require 'ceedling/loginator'
 require 'ceedling/dependencies/dependency_cache_store'
 
@@ -124,6 +124,37 @@ describe DependencyCacheStore do
       expect( @store.load('cache.json')['entries'] ).to eq( {} )
     end
 
+    # GH #1364: version 2 places per-test build output by the test's path from the project root
+    it 'marks the 1.2.2 build layout as schema version 2' do
+      expect( DependencyCacheStore::CACHE_SCHEMA_VERSION ).to eq( 2 )
+    end
+
+    it 'rebuilds once from an older build layout, advising clobber for what that layout left' do
+      payload = JSON.generate(
+        'schema_version' => 1, 'hash_algorithm' => DependencyHasher::HASH_ALGORITHM, 'entries' => { 'foo.o' => valid_entry }
+      )
+      stub_file( 'build/cache/.test.dep_cache.json', payload )
+
+      expect(@loginator).to receive(:log).with(
+        'Dependency cache build/cache/.test.dep_cache.json comes from an earlier Ceedling build layout -- rebuilding ' \
+        'everything once. Run `ceedling clobber` to remove any orphaned build output left in the old layout.',
+        Verbosity::COMPLAIN
+      )
+
+      expect( @store.load('build/cache/.test.dep_cache.json')['entries'] ).to eq( {} )
+    end
+
+    it 'keeps its usual warning for a schema_version it never wrote' do
+      payload = JSON.generate(
+        'schema_version' => DependencyCacheStore::CACHE_SCHEMA_VERSION + 1, 'hash_algorithm' => DependencyHasher::HASH_ALGORITHM, 'entries' => {}
+      )
+      stub_file( 'cache.json', payload )
+
+      expect(@loginator).to receive(:log).with( /cache\.json has an incompatible or missing schema_version/, Verbosity::COMPLAIN )
+
+      @store.load('cache.json')
+    end
+
     it 'treats a mismatched hash_algorithm as an absent cache' do
       payload = JSON.generate(
         'schema_version' => DependencyCacheStore::CACHE_SCHEMA_VERSION,
@@ -153,7 +184,7 @@ describe DependencyCacheStore do
       result = @store.load('cache.json')
 
       expect( result['entries'].keys ).to eq( ['good.o'] )
-      expect( @loginator ).to have_received(:log)
+      expect( @loginator ).to have_received(:log).with( /'bad\.o' in cache\.json is malformed/, Verbosity::COMPLAIN )
     end
 
     it 'drops an entry with a self_hash of the wrong length' do

data/spec/units/dependencies/dependency_debug_tree_spec.rb

@@ -7,7 +7,7 @@
 
 require 'spec_helper'
 require 'yaml'
-require 'ceedling/file_wrapper'
+require 'ceedling/filesystem/file_wrapper'
 require 'ceedling/yaml_wrapper'
 require 'ceedling/dependencies/dependency_debug_tree'
 

data/spec/units/dependencies/dependency_hasher_spec.rb

@@ -7,16 +7,57 @@
 
 require 'spec_helper'
 require 'digest'
-require 'ceedling/file_wrapper'
+require 'ceedling/filesystem/file_wrapper'
 require 'ceedling/dependencies/dependency_hasher'
 
 describe DependencyHasher do
 
   before(:each) do
     @file_wrapper = instance_double('FileWrapper')
+    # No file status by default, so every read below hashes afresh
+    allow( @file_wrapper ).to receive(:stat).and_return( nil )
     @hasher = described_class.new( { :file_wrapper => @file_wrapper } )
   end
 
+  # GH #1368: every test link hashes the libraries it links, so a large library was read
+  # once per test executable on every build
+  describe '#hash_of_file memo' do
+    def status(size, mtime)
+      return double( %q(File::Stat), size: size, mtime: mtime )
+    end
+
+    before(:each) do
+      allow( @file_wrapper ).to receive(:read_binary).with('libx.a').and_return('library')
+    end
+
+    it 'hashes a file left unchanged since before the build began only once' do
+      allow( @file_wrapper ).to receive(:stat).with('libx.a').and_return( status( 7, Time.now - 60 ) )
+
+      2.times { expect( @hasher.hash_of_file('libx.a') ).to eq( Digest::SHA256.hexdigest('library') ) }
+
+      expect( @file_wrapper ).to have_received(:read_binary).once
+    end
+
+    it 'hashes again a file whose size or modification time changed' do
+      allow( @file_wrapper ).to receive(:stat).with('libx.a').and_return(
+        status( 7, Time.now - 60 ), status( 8, Time.now - 60 ), status( 8, Time.now - 50 )
+      )
+
+      3.times { @hasher.hash_of_file('libx.a') }
+
+      expect( @file_wrapper ).to have_received(:read_binary).exactly(3).times
+    end
+
+    # A file the build writes can change within one timestamp tick, unseen by its status
+    it 'hashes afresh, every time, a file modified as the build began or since' do
+      allow( @file_wrapper ).to receive(:stat).with('libx.a').and_return( status( 7, Time.now ) )
+
+      2.times { @hasher.hash_of_file('libx.a') }
+
+      expect( @file_wrapper ).to have_received(:read_binary).twice
+    end
+  end
+
   describe '#hash_of_file' do
     it 'returns the SHA-256 hex digest of the file content read via FileWrapper' do
       allow( @file_wrapper ).to receive(:read_binary).with('foo.c').and_return('int main(void) {}')

data/spec/units/dependencies/dependency_path_normalizer_spec.rb

@@ -6,7 +6,7 @@
 # =========================================================================
 
 require 'spec_helper'
-require 'ceedling/file_wrapper'
+require 'ceedling/filesystem/file_wrapper'
 require 'ceedling/dependencies/dependency_path_normalizer'
 
 describe DependencyPathNormalizer do

data/spec/units/dependencies/dependency_tracker_spec.rb

@@ -7,7 +7,7 @@
 
 require 'spec_helper'
 require 'ceedling/exceptions'
-require 'ceedling/file_wrapper'
+require 'ceedling/filesystem/file_wrapper'
 require 'ceedling/system_wrapper'
 require 'ceedling/loginator'
 require 'ceedling/yaml_wrapper'
@@ -52,6 +52,8 @@ describe DependencyTracker do
     allow( @file_wrapper ).to receive(:mkdir)
     allow( @file_wrapper ).to receive(:write)
     allow( @file_wrapper ).to receive(:mv)
+    # No file status, so every hash reads its file afresh
+    allow( @file_wrapper ).to receive(:stat).and_return(nil)
     allow( @system_wrapper ).to receive(:env_get).with('CEEDLING_DEP_DEBUG').and_return(nil)
 
     hasher = DependencyHasher.new( { :file_wrapper => @file_wrapper } )

data/spec/units/filename_extension_spec.rb

@@ -51,6 +51,17 @@ describe FilenameExtension do
     end
   end
 
+  describe '#pattern' do
+    it 'matches any one of its extensions, escaped, as a group' do
+      pattern = FilenameExtension.new( ['.c', '.c++'] ).pattern
+
+      expect('a.c++').to match( /#{pattern}\z/ )
+      expect('a.c').to match( /#{pattern}\z/ )
+      expect('a.cxx').to_not match( /#{pattern}\z/ )
+      expect('a_c').to_not match( /#{pattern}\z/ )
+    end
+  end
+
   describe '#candidates' do
     it 'produces one candidate filename per configured extension' do
       extension = FilenameExtension.new(['.s', '.S'])

data/spec/units/filesystem/build_subpath_spec.rb

@@ -0,0 +1,122 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'spec_helper'
+require 'tmpdir'
+require 'fileutils'
+require 'ceedling/filesystem/build_subpath'
+
+# GH #1370 and the path handling audit around it: a build file placed by text could land
+# outside the build directory
+describe BuildSubpath do
+  WINDOWS_ONLY_BUILD = { if: Gem.win_platform? }.freeze
+
+  around(:each) do |example|
+    Dir.mktmpdir do |dir|
+      @ws = File.realpath( dir )
+      FileUtils.mkdir_p( File.join( @ws, 'app' ) )
+      Dir.chdir( File.join( @ws, 'app' ) ) { example.run }
+    end
+  end
+
+  # Every other example reads INSTALLATION_ROOT itself, so only this one shows it names the
+  # running installation
+  it 'names the running installation, which holds what Ceedling ships' do
+    expect(File.file?( File.join( BuildSubpath::INSTALLATION_ROOT, 'lib', 'ceedling', 'filesystem', 'build_subpath.rb' ) )).to be( true )
+    BuildSubpath::INSTALLED_DIRS.each { |dir| expect(File.directory?( dir )).to be( true ), dir }
+  end
+
+  describe '.encode and .decode' do
+    {
+      'a file in the project'    => ['src/drv/uart', 'src/drv/uart'],
+      'a sibling of the project' => ['../shared/src', '_up_/shared/src'],
+      'the working directory'    => ['.', '']
+    }.each do |label, (path, encoded)|
+      it "places #{label} by its path from the project root, and reads it back" do
+        expect(BuildSubpath.encode( path )).to eq( encoded )
+        expect(BuildSubpath.decode( encoded )).to eq( path == '.' ? '' : path )
+      end
+    end
+
+    # A project's own directory may carry a marker's name, which must read back as itself
+    it 'places a directory named like a marker apart from the marker, and reads it back' do
+      ['_up_/x', 'src/a/_up_', '_ceedling_/src', '_abs_/C/x', '_unc_/srv', 'src/__up_/x'].each do |path|
+        encoded = BuildSubpath.encode( path )
+
+        expect(BuildSubpath.decode( encoded )).to eq( path ), "#{path} => #{encoded}"
+      end
+      expect(BuildSubpath.encode( '_up_/x' )).to_not eq( BuildSubpath.encode( '../x' ) )
+      # macOS and Windows file systems fold case
+      expect(BuildSubpath.encode( '_UP_/x' ).downcase).to_not eq( BuildSubpath.encode( '../x' ).downcase )
+      expect(BuildSubpath.decode( BuildSubpath.encode( '_UP_/x' ) )).to eq( '_UP_/x' )
+    end
+
+    # Windows has no relative path from one drive to another
+    it 'places a file of the running Ceedling on another drive below `_ceedling_` too' do
+      file = File.join( BuildSubpath::INSTALLATION_ROOT, 'plugins/fff/src' )
+      allow(ProjectPaths).to receive(:relative).and_call_original
+      allow(ProjectPaths).to receive(:relative).with( file ).and_return( file )
+
+      expect(BuildSubpath.encode( file )).to eq( '_ceedling_/plugins/fff/src' )
+    end
+
+    it 'places an absolute path below the project as a relative one' do
+      expect(BuildSubpath.encode( File.join( @ws, 'app/src/x' ) )).to eq( 'src/x' )
+    end
+
+    it 'places a file of the running Ceedling outside the project below `_ceedling_`, and reads it back' do
+      file = File.join( BuildSubpath::INSTALLATION_ROOT, 'plugins/fff/src' )
+
+      expect(BuildSubpath.encode( file )).to eq( '_ceedling_/plugins/fff/src' )
+      expect(File.expand_path( BuildSubpath.decode( '_ceedling_/plugins/fff/src' ) )).to eq( file )
+    end
+
+    # A project may itself sit inside a Ceedling checkout, as the system specs' projects do.
+    # Only what Ceedling ships places below `_ceedling_`.
+    it 'places a directory beside a project inside the installation by its path from the project root' do
+      root = BuildSubpath::INSTALLATION_ROOT
+      allow(ProjectPaths).to receive(:working_dir).and_return( File.join( root, 'specout/proj/app' ) )
+
+      expect(BuildSubpath.encode( File.join( root, 'specout/proj/shared/src' ) )).to eq( '_up_/shared/src' )
+      expect(BuildSubpath.encode( File.join( root, 'plugins/fff/src' ) )).to eq( '_ceedling_/plugins/fff/src' )
+    end
+
+    it 'places a file of the running Ceedling inside the project by its path from the project root' do
+      Dir.chdir( BuildSubpath::INSTALLATION_ROOT ) do
+        expect(BuildSubpath.encode( 'plugins/fff/src' )).to eq( 'plugins/fff/src' )
+      end
+    end
+
+    it 'places a path on another drive below `_abs_`, and reads it back', **WINDOWS_ONLY_BUILD do
+      other = Dir.pwd.start_with?( 'C' ) ? 'D' : 'C'
+
+      expect(BuildSubpath.encode( "#{other}:/x/inc" )).to eq( "_abs_/#{other}/x/inc" )
+      expect(BuildSubpath.decode( "_abs_/#{other}/x/inc" )).to eq( "#{other}:/x/inc" )
+    end
+
+    it 'places a UNC path below `_unc_`, and reads it back', **WINDOWS_ONLY_BUILD do
+      expect(BuildSubpath.encode( '//server/share/inc' )).to eq( '_unc_/server/share/inc' )
+      expect(BuildSubpath.decode( '_unc_/server/share/inc' )).to eq( '//server/share/inc' )
+    end
+
+    it 'never places a file outside the build subpath it names' do
+      ['../../far/x', '/opt/x', '../shared', File.join( @ws, 'app/../../x' )].each do |path|
+        encoded = BuildSubpath.encode( path )
+
+        expect(encoded.split( '/' )).to_not include( '..' ), "#{path}: #{encoded}"
+        expect(encoded).to_not start_with( '/' ), "#{path}: #{encoded}"
+      end
+    end
+  end
+
+  describe '.of_directory' do
+    it 'is the encoding of a directory, with the working directory as empty' do
+      expect(BuildSubpath.of_directory( 'src/drv' )).to eq( 'src/drv' )
+      expect(BuildSubpath.of_directory( '.' )).to eq( '' )
+    end
+  end
+end

data/spec/units/filesystem/destination_collision_spec.rb

@@ -0,0 +1,30 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'spec_helper'
+require 'ceedling/filesystem/destination_collision'
+
+describe DestinationCollision do
+  describe '.find' do
+    it 'gives each output more than one input maps to, with those inputs' do
+      shared = DestinationCollision.find( ['a/x.c', 'b/x.c', 'c/y.c', 'a/x.c'] ) { |input| File.basename( input ) }
+
+      expect(shared).to eq( 'x.c' => ['a/x.c', 'b/x.c'] )
+    end
+
+    it 'gives nothing when every input has an output of its own' do
+      expect(DestinationCollision.find( ['a.c', 'b.c'] ) { |input| input }).to be_empty
+    end
+  end
+
+  describe '.raise_for' do
+    it 'names every input and the output they share, with a fix' do
+      expect { DestinationCollision.raise_for( 'out/x.o', ['a/x.c', 'b/x.c'], 'would build to the same file' ) }
+        .to raise_error( CeedlingException, '`a/x.c` and `b/x.c` would build to the same file `out/x.o`. Rename one, or move it to its own directory.' )
+    end
+  end
+end