ceedling 1.2.1 → 1.2.2

data/spec/units/bin/cli_handler_spec.rb

@@ -20,6 +20,7 @@ $: << File.join(here, '../../../lib')
 # real bin/ceedling bootstrap always loads ceedling/constants first, so this load
 # order only ever bites a spec harness requiring cli_handler.rb directly.
 require 'ceedling/constants'
+require 'version' # The launcher's own version, which #version reports for this repository
 require 'cli_handler'
 require 'app_cfg'
 require 'path_validator'
@@ -40,16 +41,22 @@ require 'ceedling/rake_app/rake_task_registry'
 # exercising the real filtering/standardizing behavior it coordinates).
 describe CliHandler do
   before(:each) do
-    @loginator = double('loginator').as_null_object
-    @helper    = double('cli_helper').as_null_object
+    @loginator     = double('loginator').as_null_object
+    @helper        = double('cli_helper').as_null_object
+    @composinator  = double('composinator').as_null_object
+    @projectinator = double('projectinator').as_null_object
+    @path_validator = double('path_validator').as_null_object
+    @actionator    = double('actionator').as_null_object
+    @launchinator  = double('launchinator').as_null_object
 
     @cli_handler = described_class.new({
-      :composinator       => double('composinator').as_null_object,
-      :projectinator      => double('projectinator').as_null_object,
+      :composinator       => @composinator,
+      :projectinator      => @projectinator,
       :cli_helper         => @helper,
-      :path_validator     => double('path_validator').as_null_object,
+      :path_validator     => @path_validator,
       :rake_task_registry => double('rake_task_registry').as_null_object,
-      :actionator         => double('actionator').as_null_object,
+      :actionator         => @actionator,
+      :launchinator       => @launchinator,
       :loginator          => @loginator,
     })
   end
@@ -77,6 +84,9 @@ describe CliHandler do
   describe '#version' do
     before(:each) do
       @app_cfg = CeedlingAppConfig.new
+      # No project file unless an example says otherwise
+      allow(@projectinator).to receive(:config_available?).and_return( false )
+      allow(@path_validator).to receive(:standardize_paths) { |*paths| paths }
     end
 
     def fake_application_version(install_path)
@@ -116,6 +126,271 @@ describe CliHandler do
 
       @cli_handler.version( {}, @app_cfg )
     end
+
+    # GH #1365: `version` reported the launcher for a project selecting another installation
+    context 'with a project' do
+      before(:each) do
+        allow(@helper).to receive(:manufacture_app_version).and_return( fake_application_version( '/elsewhere' ) )
+        allow(@helper).to receive(:process_mixin_filepaths) { |mixins| mixins }
+      end
+
+      it 'resolves which Ceedling from an explicit --project and its mixins, loading silently' do
+        config = {:project => {:which_ceedling => '/elsewhere'}}
+        expect(@composinator).to receive(:loadinate).with(
+          hash_including( filepath: 'other/project.yml', mixins: ['ci.yml'], silent: true )
+        ).and_return( ['other/project.yml', config] )
+        expect(@launchinator).to receive(:resolve).with( env: {}, app_cfg: @app_cfg, config: config )
+
+        @cli_handler.version( {}, @app_cfg, {:project => 'other/project.yml', :mixin => ['ci.yml']} )
+      end
+
+      it 'raises when an explicit --project cannot be loaded' do
+        allow(@composinator).to receive(:loadinate).and_raise( 'Could not find project filepath' )
+
+        expect {
+          @cli_handler.version( {}, @app_cfg, {:project => 'missing.yml', :mixin => []} )
+        }.to raise_error( /Could not find project filepath/ )
+      end
+
+      it 'raises when an explicit --mixin cannot be loaded with the default project file' do
+        allow(@composinator).to receive(:loadinate).and_raise( 'Command line failed validation' )
+
+        expect {
+          @cli_handler.version( {}, @app_cfg, {:project => nil, :mixin => ['missing.yml']} )
+        }.to raise_error( /Command line failed validation/ )
+      end
+
+      it 'reads the default project file when one is available' do
+        config = {:project => {:which_ceedling => 'vendor/ceedling'}}
+        allow(@projectinator).to receive(:config_available?).and_return( true )
+        allow(@composinator).to receive(:loadinate).and_return( ['project.yml', config] )
+        expect(@launchinator).to receive(:resolve).with( env: {}, app_cfg: @app_cfg, config: config )
+
+        @cli_handler.version( {}, @app_cfg )
+      end
+
+      it 'falls back to resolving without a project when the default project file cannot be loaded' do
+        allow(@projectinator).to receive(:config_available?).and_return( true )
+        allow(@composinator).to receive(:loadinate).and_raise( 'Project configuration file section :mixins failed validation' )
+        expect(@launchinator).to receive(:resolve).with( env: {}, app_cfg: @app_cfg, config: {} )
+
+        expect { @cli_handler.version( {}, @app_cfg ) }.to_not raise_error
+      end
+
+      it 'resolves without a project when no project file is available' do
+        expect(@composinator).to_not receive(:loadinate)
+        expect(@launchinator).to receive(:resolve).with( env: {}, app_cfg: @app_cfg, config: {} )
+
+        @cli_handler.version( {}, @app_cfg )
+      end
+
+      it 'never hands off, since it reports on both installations' do
+        @cli_handler.version( {}, @app_cfg )
+
+        expect(@launchinator).to_not have_received(:launch)
+      end
+
+      it 'reports the launcher from where it runs, even after resolution moves the application paths' do
+        allow(@launchinator).to receive(:resolve) { |app_cfg:, **| app_cfg.set_paths( '/elsewhere' ) }
+
+        expect(@loginator).to receive(:console) do |message, _label|
+          expect(message).to include( "Ceedling Launcher => #{Ceedling::Version::GEM}" )
+          expect(message).to include( "#{@app_cfg[:launcher_root_path]}/" )
+        end
+
+        @cli_handler.version( {}, @app_cfg )
+      end
+    end
+  end
+
+  # GH #1365: every command but `version` runs in the installation it selects. An exec
+  # never returns, so a raise stands in for it: nothing after the hand-off may run.
+  describe 'hand-off' do
+    HandedOff = Class.new( StandardError )
+
+    before(:each) do
+      @app_cfg = CeedlingAppConfig.new
+      @config  = {:project => {:which_ceedling => 'vendor/ceedling'}}
+      allow(@path_validator).to receive(:standardize_paths) { |*paths| paths }
+      allow(@helper).to receive(:process_mixin_filepaths) { |mixins| mixins }
+      allow(@composinator).to receive(:loadinate).and_return( ['project.yml', @config] )
+    end
+
+    def expect_no_work_done
+      [:log_project_name, :console_project_name, :load_ceedling, :run_rake_tasks, :dump_yaml,
+       :project_exists?, :vendor_tools, :copy_docs, :lookup_example_projects, :help_footer].each do |work|
+        expect(@helper).to_not have_received( work )
+      end
+      expect(@actionator).to_not have_received(:make_directory)
+      expect(@actionator).to_not have_received(:remove_directory)
+      expect(@loginator).to_not have_received(:console)
+    end
+
+    {
+      'build'                    => ->(h, cfg) { h.build( env: {}, app_cfg: cfg, options: {:project => nil, :mixin => []}, tasks: ['test:all'] ) },
+      'check'                    => ->(h, cfg) { h.check( {}, cfg, {:project => nil, :mixin => []} ) },
+      'environment'              => ->(h, cfg) { h.environment( {}, cfg, {:project => nil, :mixin => []} ) },
+      'dumpconfig'               => ->(h, cfg) { h.dumpconfig( {}, cfg, {:project => nil, :mixin => [], :app => true}, 'out.yml', [] ) },
+      'dumpconfig --no-app'      => ->(h, cfg) { h.dumpconfig( {}, cfg, {:project => nil, :mixin => [], :app => false}, 'out.yml', [] ) },
+      '-T'                       => ->(h, cfg) { h.rake_help( env: {}, app_cfg: cfg ) },
+    }.each do |name, command|
+      it "#{name} hands off with the project's configuration before doing anything else" do
+        expect(@launchinator).to receive(:launch).with( env: {}, app_cfg: @app_cfg, config: @config ).and_raise( HandedOff )
+
+        expect { command.call( @cli_handler, @app_cfg ) }.to raise_error( HandedOff )
+        expect_no_work_done()
+      end
+    end
+
+    it 'help hands off with the project\'s configuration before printing any help' do
+      allow(@projectinator).to receive(:config_available?).and_return( true )
+      expect(@launchinator).to receive(:launch).with( env: {}, app_cfg: @app_cfg, config: @config ).and_raise( HandedOff )
+      printed = false
+
+      expect { @cli_handler.app_help( {}, @app_cfg, {:project => nil, :mixin => []}, nil ) { printed = true } }.to raise_error( HandedOff )
+      expect(printed).to be( false )
+      expect_no_work_done()
+    end
+
+    it 'help for one command hands off without the project when the project fails to load' do
+      allow(@projectinator).to receive(:config_available?).and_return( true )
+      allow(@composinator).to receive(:loadinate).and_raise( 'Project configuration file section :mixins failed validation' )
+      expect(@launchinator).to receive(:launch).with( env: {}, app_cfg: @app_cfg, config: {} ).and_raise( HandedOff )
+
+      expect { @cli_handler.app_help( {}, @app_cfg, {:project => nil, :mixin => []}, 'build' ) { } }.to raise_error( HandedOff )
+    end
+
+    it 'help for every command still fails when the project fails to load' do
+      allow(@projectinator).to receive(:config_available?).and_return( true )
+      allow(@composinator).to receive(:loadinate).and_raise( 'Project configuration file section :mixins failed validation' )
+
+      expect {
+        @cli_handler.app_help( {}, @app_cfg, {:project => nil, :mixin => []}, nil ) { }
+      }.to raise_error( /failed validation/ )
+      expect(@launchinator).to_not have_received(:launch)
+    end
+
+    it 'help without a project hands off by environment and vendor detection alone' do
+      allow(@projectinator).to receive(:config_available?).and_return( false )
+      expect(@launchinator).to receive(:launch).with( env: {}, app_cfg: @app_cfg, config: {} ).and_raise( HandedOff )
+
+      expect { @cli_handler.app_help( {}, @app_cfg, {:project => nil, :mixin => []}, 'build' ) { } }.to raise_error( HandedOff )
+      expect(@composinator).to_not have_received(:loadinate)
+    end
+
+    {
+      'new'      => ->(h, cfg) { h.new_project( {}, cfg, '1.2.2', {:local => true, :configs => true}, 'proj' ) },
+      'examples' => ->(h, cfg) { h.list_examples( {}, cfg, {} ) },
+      'example'  => ->(h, cfg) { h.create_example( {}, cfg, {:local => true}, 'temp_sensor', nil ) },
+    }.each do |name, command|
+      it "#{name} hands off by environment and vendor detection before doing anything else" do
+        expect(@launchinator).to receive(:launch).with( env: {}, app_cfg: @app_cfg ).and_raise( HandedOff )
+
+        expect { command.call( @cli_handler, @app_cfg ) }.to raise_error( HandedOff )
+        expect_no_work_done()
+      end
+    end
+
+    # GH #1365: a `--local` copy carries no documentation bundle, so it would export only licenses
+    describe 'docs' do
+      before(:each) do
+        @launcher = Installation.new( @app_cfg[:launcher_root_path] )
+        @copy = Installation.new( 'vendor/ceedling' )
+        allow(@launchinator).to receive(:resolve) { |app_cfg:, **| app_cfg.set_paths( @copy.root ); @copy }
+      end
+
+      it 'hands off to the selected installation when it holds a documentation bundle' do
+        allow(@helper).to receive(:docs_bundle?).with( @copy.root ).and_return( true )
+        expect(@launchinator).to receive(:proceed).with( target: @copy, app_cfg: @app_cfg ).and_raise( HandedOff )
+
+        expect { @cli_handler.docs( {}, @app_cfg, 'out' ) }.to raise_error( HandedOff )
+        expect_no_work_done()
+      end
+
+      it 'exports the launcher\'s documentation, saying so, when the selected installation has none' do
+        allow(@helper).to receive(:docs_bundle?).with( @copy.root ).and_return( false )
+
+        expect(@loginator).to receive(:console).with(
+          "#{@copy.describe} holds no documentation bundle to export. " +
+          "Exporting the documentation of #{@launcher.describe( 'Ceedling launcher' )} instead.",
+          LogLabels::NOTICE
+        ).ordered
+        expect(@helper).to receive(:copy_docs).with( @launcher.root, 'out' ).ordered
+
+        @cli_handler.docs( {}, @app_cfg, 'out' )
+
+        expect(@launchinator).to_not have_received(:proceed)
+        expect(@app_cfg[:ceedling_root_path]).to eq( @launcher.root )
+      end
+
+      it 'exports the launcher\'s own documentation with no notice when it is selected' do
+        allow(@launchinator).to receive(:resolve).and_return( @launcher )
+
+        expect(@helper).to receive(:copy_docs).with( @launcher.root, 'out' )
+
+        @cli_handler.docs( {}, @app_cfg, 'out' )
+
+        expect(@loginator).to_not have_received(:console)
+      end
+    end
+
+  it 'upgrade hands off by environment alone, never to a vendor/ceedling it detects' do
+    source = Installation.new( 'elsewhere/ceedling' )
+    expect(@launchinator).to receive(:resolve).with( env: {}, app_cfg: @app_cfg, detect_vendor: false ).and_return( source )
+    expect(@launchinator).to receive(:proceed).with( target: source, app_cfg: @app_cfg ).and_raise( HandedOff )
+
+    expect { @cli_handler.upgrade_project( {}, @app_cfg, {:project => 'project.yml'}, 'proj' ) }.to raise_error( HandedOff )
+    expect_no_work_done()
+  end
+
+  # GH #1365: WHICH_CEEDLING naming the project's own copy would hand off to it, and a copy
+  # before 1.2.2 deletes itself as its own source
+  it 'upgrade refuses to re-vendor a project from its own vendored copy, before handing off to it' do
+    allow(@launchinator).to receive(:resolve) { |app_cfg:, **| app_cfg.set_paths( 'proj/vendor/ceedling' ); Installation.new( 'proj/vendor/ceedling' ) }
+
+    expect {
+      @cli_handler.upgrade_project( {'WHICH_CEEDLING' => 'proj/vendor/ceedling'}, @app_cfg, {:project => 'project.yml'}, 'proj' )
+    }.to raise_error( CeedlingException, /Cannot upgrade #{Regexp.escape( File.expand_path( 'proj/vendor/ceedling' ) )}\/ from itself/ )
+    expect(@launchinator).to_not have_received(:proceed)
+    expect_no_work_done()
+  end
+end
+
+  # GH #1371: exported documentation was never refreshed, and refreshing it removed all of docs/
+  describe '#upgrade_project documentation' do
+    before(:each) do
+      @app_cfg = CeedlingAppConfig.new
+      @source = Installation.new( 'elsewhere/ceedling' )
+      @docs = File.join( 'proj', 'docs' )
+      allow(@path_validator).to receive(:standardize_paths) { |*paths| paths }
+      allow(@launchinator).to receive(:resolve) { |app_cfg:, **| app_cfg.set_paths( @source.root ); @source }
+      allow(@helper).to receive(:project_exists?).and_return( true )
+    end
+
+    def upgrade
+      @cli_handler.upgrade_project( {}, @app_cfg, {:project => 'project.yml'}, 'proj' )
+    end
+
+    it 'replaces what an export wrote, keeping the bundle when the source has none, then exports again' do
+      allow(@helper).to receive(:exported_docs?).with( @docs ).and_return( true )
+      allow(@helper).to receive(:docs_bundle?).with( @source.root ).and_return( false )
+
+      expect(@helper).to receive(:remove_exported_docs).with( @docs, keep_bundle: true ).ordered
+      expect(@helper).to receive(:copy_docs).with( @source.root, @docs ).ordered
+
+      upgrade()
+
+      expect(@actionator).to_not have_received(:remove_directory).with( @docs )
+    end
+
+    it 'leaves docs/ alone when it holds no export' do
+      allow(@helper).to receive(:exported_docs?).with( @docs ).and_return( false )
+
+      upgrade()
+
+      expect(@helper).to_not have_received(:remove_exported_docs)
+      expect(@helper).to_not have_received(:copy_docs)
+    end
   end
 
   describe '#list_examples' do
@@ -168,6 +443,7 @@ describe CliHandler do
         :path_validator     => real_path_validator,
         :rake_task_registry => double('rake_task_registry').as_null_object,
         :actionator         => double('actionator').as_null_object,
+        :launchinator       => double('launchinator').as_null_object,
         :loginator          => double('loginator').as_null_object,
       })
     end

data/spec/units/bin/cli_helper_spec.rb

@@ -7,6 +7,7 @@
 
 require 'spec_helper'
 require 'tmpdir'
+require 'fileutils'
 require 'rake'
 
 # bin/versionator.rb (pulled in transitively by cli_helper.rb) uses bare `require`
@@ -22,6 +23,8 @@ $: << File.join(here, '../../../lib')
 require 'cli_helper'
 require 'app_cfg'
 require 'ceedling/ruby_expandinator'
+require 'ceedling/config/config_walkinator'
+require 'ceedling/filesystem/file_wrapper'
 # CliHelper#test_task? references RakeTaskRegistry::TAG_TEST, but only
 # bin/cli_handler.rb requires this file in the real bootstrap (loaded before
 # cli_helper.rb's methods are ever called) -- required directly here since this
@@ -121,70 +124,107 @@ describe CliHelper do
     end
   end
 
-  describe '#which_ceedling?' do
-    before(:each) do
-      @app_cfg = CeedlingAppConfig.new
-      # Baseline: no :project ↳ :which_ceedling entry found. Tests exercising that
-      # config path override this with a more specific `.with(...)` stub below.
-      allow(@config_walkinator).to receive(:fetch_value).and_return( [nil, nil] )
+  describe '#docs_bundle?' do
+    it 'is true when the installation holds an HTML documentation bundle' do
+      allow(@file_wrapper).to receive(:directory?).with( File.join( '/ceedling', DOCS_SITE_LOCAL_PATH ) ).and_return( true )
+
+      expect(@cli_helper.docs_bundle?( '/ceedling' )).to be( true )
     end
 
-    it 'uses the WHICH_CEEDLING environment variable at highest priority' do
-      which, path = @cli_helper.which_ceedling?( env: {'WHICH_CEEDLING' => 'gem'}, app_cfg: @app_cfg )
+    it 'is false when it does not, as for any --local copy' do
+      allow(@file_wrapper).to receive(:directory?).with( File.join( '/ceedling', DOCS_SITE_LOCAL_PATH ) ).and_return( false )
 
-      expect(which).to eq( :gem )
-      expect(path).to eq( @app_cfg[:ceedling_rakefile_filepath] )
+      expect(@cli_helper.docs_bundle?( '/ceedling' )).to be( false )
     end
+  end
 
-    it 'falls back to config :project ↳ :which_ceedling when no environment variable is set' do
-      config = {:project => {:which_ceedling => 'gem'}}
-      allow(@config_walkinator).to receive(:fetch_value).with( :project, :which_ceedling, hash: config ).and_return( ['gem', nil] )
+  # GH #1371: `upgrade` detected exported documentation by a file exports stopped writing in
+  # 1.1.0, and refreshed it by deleting all of docs/, the project's own files included
+  describe 'exported documentation' do
+    LEGACY_PAGES = %w[BreakingChanges.md CODE_OF_CONDUCT.md CONTRIBUTING.md CeedlingPacket.md CeedlingUpgrade.md
+                      Changelog.md PluginDevelopmentGuide.md ReleaseNotes.md ThrowTheSwitchCodingStandard.md]
 
-      which, path = @cli_helper.which_ceedling?( env: {}, config: config, app_cfg: @app_cfg )
+    around(:each) do |example|
+      Dir.mktmpdir { |dir| @docs = dir; example.run }
+    end
 
-      expect(which).to eq( :gem )
-      expect(path).to eq( @app_cfg[:ceedling_rakefile_filepath] )
+    before(:each) do
+      @actions = double('actionator')
+      @removed = []
+      allow(@actions).to receive(:remove_directory) { |path| @removed << path }
+      @helper = described_class.new({
+        :file_wrapper       => FileWrapper.new( {:loginator => @loginator, :verbosinator => double('verbosinator').as_null_object} ),
+        :actionator         => @actions,
+        :config_walkinator  => @config_walkinator,
+        :path_validator     => @path_validator,
+        :rake_task_registry => @rake_task_registry,
+        :loginator          => @loginator,
+        :reportinator       => double('reportinator').as_null_object,
+        :system_wrapper     => double('system_wrapper').as_null_object,
+        :ruby_expandinator  => @ruby_expandinator,
+      })
+    end
+
+    def make(*entries)
+      entries.each do |entry|
+        path = File.join( @docs, entry )
+        entry.end_with?( '/' ) ? FileUtils.mkdir_p( path ) : (FileUtils.mkdir_p( File.dirname( path ) ); File.write( path, '' ))
+      end
     end
 
-    it 'falls back to a vendor/ceedling directory when neither environment nor config specify anything' do
-      allow(@file_wrapper).to receive(:directory?).with( 'vendor/ceedling' ).and_return( true )
-      allow(@file_wrapper).to receive(:exist?).and_return( true )
+    def removed
+      return @removed.map { |path| path.delete_prefix( File.join( @docs, '' ) ) }.sort
+    end
 
-      which, path = @cli_helper.which_ceedling?( env: {}, app_cfg: @app_cfg )
+    describe '#exported_docs?' do
+      it 'finds an export of 1.1.0 or later by its framework or bundle directories' do
+        %w[ceedling/ unity/ cmock/ c_exception/].each do |entry|
+          Dir.mktmpdir do |dir|
+            FileUtils.mkdir_p( File.join( dir, entry ) )
+            expect(@helper.exported_docs?( dir )).to be( true ), entry
+          end
+        end
+      end
 
-      expect(which).to eq( :path )
-      expect(path).to eq( @app_cfg[:ceedling_rakefile_filepath] )
-      expect(@app_cfg[:ceedling_root_path]).to eq( File.expand_path('vendor/ceedling') )
-    end
+      it 'finds a 1.0.x export by its CeedlingPacket.md' do
+        make( 'CeedlingPacket.md' )
 
-    it 'defaults to :gem when nothing is set and no vendor/ceedling directory exists' do
-      allow(@file_wrapper).to receive(:directory?).with( 'vendor/ceedling' ).and_return( false )
+        expect(@helper.exported_docs?( @docs )).to be( true )
+      end
 
-      which, path = @cli_helper.which_ceedling?( env: {}, app_cfg: @app_cfg )
+      it 'finds nothing in a docs/ holding only the project\'s own files, or in no docs/ at all' do
+        make( 'notes.md', 'design/' )
 
-      expect(which).to eq( :gem )
-      expect(path).to eq( @app_cfg[:ceedling_rakefile_filepath] )
+        expect(@helper.exported_docs?( @docs )).to be( false )
+        expect(@helper.exported_docs?( File.join( @docs, 'absent' ) )).to be( false )
+      end
     end
 
-    it 'raises when a configured launch path does not exist as a directory' do
-      config = {:project => {:which_ceedling => 'nonexistent/path'}}
-      allow(@config_walkinator).to receive(:fetch_value).with( :project, :which_ceedling, hash: config ).and_return( ['nonexistent/path', nil] )
-      allow(@file_wrapper).to receive(:directory?).and_return( false )
+    describe '#remove_exported_docs' do
+      it 'removes what an export of 1.1.0 or later wrote, and leaves the project\'s own files' do
+        make( 'ceedling/', 'unity/', 'cmock/', 'c_exception/', 'license.txt', 'LICENSE.md', 'notes.md', 'design/' )
 
-      expect {
-        @cli_helper.which_ceedling?( env: {}, config: config, app_cfg: @app_cfg )
-      }.to raise_error( /does not exist/ )
-    end
+        @helper.remove_exported_docs( @docs, keep_bundle: false )
+
+        # The export overwrites its own license, so a license file in docs/ may be the project's
+        expect(removed).to eq( %w[c_exception ceedling cmock unity] )
+      end
 
-    it 'raises when a configured launch path exists but contains no Ceedling installation' do
-      config = {:project => {:which_ceedling => 'empty/path'}}
-      allow(@config_walkinator).to receive(:fetch_value).with( :project, :which_ceedling, hash: config ).and_return( ['empty/path', nil] )
-      allow(@file_wrapper).to receive(:directory?).and_return( true )
-      allow(@file_wrapper).to receive(:exist?).and_return( false )
+      it 'removes what a 1.0.x export wrote, and leaves the project\'s own files' do
+        make( *LEGACY_PAGES, 'plugins/', 'unity/', 'LICENSE.txt', 'notes.md' )
 
-      expect {
-        @cli_helper.which_ceedling?( env: {}, config: config, app_cfg: @app_cfg )
-      }.to raise_error( /contains no Ceedling installation/ )
+        @helper.remove_exported_docs( @docs, keep_bundle: false )
+
+        expect(removed).to eq( (LEGACY_PAGES + %w[plugins unity]).sort )
+      end
+
+      it 'keeps the HTML bundle when the source has none to replace it with' do
+        make( 'ceedling/', 'unity/' )
+
+        @helper.remove_exported_docs( @docs, keep_bundle: true )
+
+        expect(removed).to eq( %w[unity] )
+      end
     end
   end
 
@@ -232,6 +272,37 @@ describe CliHelper do
     end
   end
 
+  # The path handling audit around GH #1370: every other build path reads the build root
+  # after Ruby expansion
+  describe 'G17: #process_logging_path' do
+    it 'places the log directory below the build root as expanded' do
+      helper = described_class.new({
+        :file_wrapper => @file_wrapper, :actionator => double('actionator').as_null_object, :config_walkinator => ConfigWalkinator.new,
+        :path_validator => @path_validator, :rake_task_registry => @rake_task_registry, :loginator => @loginator,
+        :reportinator => double('reportinator').as_null_object, :system_wrapper => double('system_wrapper').as_null_object,
+        :ruby_expandinator => @ruby_expandinator
+      })
+      helper.set_ruby_replacement( true )
+
+      expect(helper.process_logging_path( { project: { build_root: "\#{'out'}/build" } } )).to eq( 'out/build/logs' )
+    end
+
+    # An unset environment variable expands to nothing, which would place the logs at the
+    # filesystem root before configuration could refuse the build root
+    it 'refuses a build root that expands to nothing, as configuration does' do
+      helper = described_class.new({
+        :file_wrapper => @file_wrapper, :actionator => double('actionator').as_null_object, :config_walkinator => ConfigWalkinator.new,
+        :path_validator => @path_validator, :rake_task_registry => @rake_task_registry, :loginator => @loginator,
+        :reportinator => double('reportinator').as_null_object, :system_wrapper => double('system_wrapper').as_null_object,
+        :ruby_expandinator => @ruby_expandinator
+      })
+      helper.set_ruby_replacement( true )
+
+      expect { helper.process_logging_path( { project: { build_root: "\#{''}" } } ) }
+        .to raise_error( CeedlingException, ":project ↳ :build_root => '' names no directory. Give the build its own directory, such as 'build'." )
+    end
+  end
+
   describe '#process_log_filepath' do
     around(:each) do |example|
       Dir.mktmpdir do |dir|

data/spec/units/bin/installation_selector_spec.rb

@@ -0,0 +1,114 @@
+# =========================================================================
+#   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/constants'
+require 'installation_selector'
+require 'path_validator'
+require 'app_cfg'
+
+describe InstallationSelector do
+  before(:each) do
+    @file_wrapper      = double('file_wrapper').as_null_object
+    @config_walkinator = double('config_walkinator').as_null_object
+    @loginator         = double('loginator').as_null_object
+    @app_cfg           = CeedlingAppConfig.new
+
+    @selector = described_class.new({
+      :file_wrapper      => @file_wrapper,
+      :config_walkinator => @config_walkinator,
+      # Real, so path standardization is exercised rather than assumed
+      :path_validator    => PathValidator.new( {:file_wrapper => @file_wrapper, :loginator => @loginator} ),
+      :loginator         => @loginator,
+    })
+
+    # Baseline: no :project ↳ :which_ceedling entry found. Examples exercising that
+    # config path override this with a more specific `.with(...)` stub.
+    allow(@config_walkinator).to receive(:fetch_value).and_return( [nil, nil] )
+  end
+
+  it 'uses the WHICH_CEEDLING environment variable at highest priority' do
+    installation = @selector.select( env: {'WHICH_CEEDLING' => 'gem'}, app_cfg: @app_cfg )
+
+    expect(installation).to eq( Installation.new( @app_cfg[:launcher_root_path] ) )
+  end
+
+# A console line would print at every verbosity, into `dumpconfig --stdout` YAML among others
+it 'logs its use of WHICH_CEEDLING at obnoxious verbosity, as for every other source' do
+  @selector.select( env: {'WHICH_CEEDLING' => 'gem'}, app_cfg: @app_cfg )
+
+  expect(@loginator).to have_received(:log).with( " > Set which Ceedling using environment variable WHICH_CEEDLING", Verbosity::OBNOXIOUS )
+  expect(@loginator).to_not have_received(:console)
+end
+
+  it 'falls back to config :project ↳ :which_ceedling when no environment variable is set' do
+    config = {:project => {:which_ceedling => 'gem'}}
+    allow(@config_walkinator).to receive(:fetch_value).with( :project, :which_ceedling, hash: config ).and_return( ['gem', nil] )
+
+    installation = @selector.select( env: {}, config: config, app_cfg: @app_cfg )
+
+    expect(installation).to eq( Installation.new( @app_cfg[:launcher_root_path] ) )
+  end
+
+  it 'falls back to a vendor/ceedling directory when neither environment nor config specify anything' do
+    allow(@file_wrapper).to receive(:directory?).with( 'vendor/ceedling' ).and_return( true )
+    allow(@file_wrapper).to receive(:exist?).and_return( true )
+
+    installation = @selector.select( env: {}, app_cfg: @app_cfg )
+
+    expect(installation.root).to eq( File.expand_path( 'vendor/ceedling' ) )
+    expect(@app_cfg[:ceedling_root_path]).to eq( File.expand_path( 'vendor/ceedling' ) )
+  end
+
+  # GH #1365: `upgrade` run inside a project took the project's own copy as its source
+  it 'ignores a vendor/ceedling directory when vendor detection is off' do
+    allow(@file_wrapper).to receive(:directory?).with( 'vendor/ceedling' ).and_return( true )
+
+    installation = @selector.select( env: {}, app_cfg: @app_cfg, detect_vendor: false )
+
+    expect(installation).to eq( Installation.new( @app_cfg[:launcher_root_path] ) )
+  end
+
+  it 'defaults to the gem when nothing is set and no vendor/ceedling directory exists' do
+    allow(@file_wrapper).to receive(:directory?).with( 'vendor/ceedling' ).and_return( false )
+
+    installation = @selector.select( env: {}, app_cfg: @app_cfg )
+
+    expect(installation).to eq( Installation.new( @app_cfg[:launcher_root_path] ) )
+  end
+
+  it 'standardizes backslashes in a selected path' do
+    allow(@file_wrapper).to receive(:directory?).and_return( true )
+    allow(@file_wrapper).to receive(:exist?).and_return( true )
+
+    installation = @selector.select( env: {'WHICH_CEEDLING' => 'tools\\ceedling'}, app_cfg: @app_cfg )
+
+    expect(installation.root).to eq( File.expand_path( 'tools/ceedling' ) )
+    expect(@file_wrapper).to have_received(:directory?).with( 'tools/ceedling' )
+  end
+
+  it 'raises when a configured launch path does not exist as a directory' do
+    config = {:project => {:which_ceedling => 'nonexistent/path'}}
+    allow(@config_walkinator).to receive(:fetch_value).with( :project, :which_ceedling, hash: config ).and_return( ['nonexistent/path', nil] )
+    allow(@file_wrapper).to receive(:directory?).and_return( false )
+
+    expect {
+      @selector.select( env: {}, config: config, app_cfg: @app_cfg )
+    }.to raise_error( /does not exist/ )
+  end
+
+  it 'raises when a configured launch path exists but contains no Ceedling installation' do
+    config = {:project => {:which_ceedling => 'empty/path'}}
+    allow(@config_walkinator).to receive(:fetch_value).with( :project, :which_ceedling, hash: config ).and_return( ['empty/path', nil] )
+    allow(@file_wrapper).to receive(:directory?).and_return( true )
+    allow(@file_wrapper).to receive(:exist?).and_return( false )
+
+    expect {
+      @selector.select( env: {}, config: config, app_cfg: @app_cfg )
+    }.to raise_error( /contains no Ceedling installation/ )
+  end
+end