ceedling 1.1.9 → 1.2.0

data/spec/integration/report_build_warnings_log_spec.rb

@@ -0,0 +1,170 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# The Build Warnings Log plugin with real compiler output and real file writing. gcc
+# compiles small C files in a temporary project, the plugin's compile hook receives each
+# compilation's output as a build would hand it over, and the build's end writes the log.
+
+require 'spec_helper'
+require 'spec_integration_helper'
+require 'tmpdir'
+require 'open3'
+require 'json'
+require 'ceedling/constants'
+require 'ceedling/plugins/plugin'
+require 'ceedling/file_wrapper'
+
+$LOAD_PATH.unshift( File.expand_path( '../../plugins/report_build_warnings_log/lib', __dir__ ) )
+
+require 'report_build_warnings_log'
+
+describe 'Build Warnings Log plugin (integration)' do
+  include_context 'requires gcc'
+
+  # A header warning every file including it repeats, and an unused variable
+  BUILD_WARNINGS_FILES = {
+    'shared.h' => "static int unused_helper( void ) { return 1; }\n",
+    'a.c'      => "#include \"shared.h\"\nint a( void ) { int spare; return 0; }\n",
+    'b.c'      => "#include \"shared.h\"\nint b( void ) { return 0; }\n"
+  }.freeze
+
+  let(:logged) { [] }
+
+  def plugin(excludes: [], reports: [])
+    loginator = double( 'loginator' ).tap { |log| allow(log).to receive(:log) { |message, *| logged << message } }
+    objects   = {
+      configurator: double( 'configurator', report_build_warnings_log_filename: 'warnings', report_build_warnings_log_reports: reports,
+                            report_build_warnings_log_patterns: [], report_build_warnings_log_excludes: excludes ),
+      file_wrapper: FileWrapper.new( { loginator: loginator, verbosinator: double( 'verbosinator', should_output?: false ) } ),
+      loginator:    loginator,
+      reportinator: double( 'reportinator', generate_heading: '', generate_progress: '' )
+    }
+    return ReportBuildWarningsLog.new( objects, 'report_build_warnings_log', '/plugins/report_build_warnings_log' )
+  end
+
+  def compile(file)
+    output, = Open3.capture2e( 'gcc', '-Wall', '-c', file, '-o', File.basename( file, '.c' ) + '.o' )
+    return { output: output }
+  end
+
+  def in_project
+    Dir.mktmpdir( 'warnings' ) do |root|
+      Dir.chdir( root ) do
+        BUILD_WARNINGS_FILES.each { |name, text| File.write( name, text ) }
+        stub_const( 'PROJECT_BUILD_ARTIFACTS_ROOT', 'build/artifacts' )
+        yield
+      end
+    end
+  end
+
+  def log_for(context)
+    return File.read( "build/artifacts/#{context}/warnings.log" )
+  end
+
+  it 'writes the warnings of each build context to its own log' do
+    in_project do
+      warnings = plugin
+      warnings.post_compile_execute( context: :test, shell_result: compile( 'a.c' ) )
+      warnings.post_compile_execute( context: :release, shell_result: compile( 'b.c' ) )
+      warnings.post_build( 0 )
+
+      expect(log_for( :test )).to include( 'spare' )
+      expect(log_for( :release )).to include( 'unused_helper' )
+      expect(log_for( :release )).not_to include( 'spare' )
+    end
+  end
+
+  it 'leaves out warnings a configured exclude matches' do
+    in_project do
+      warnings = plugin( excludes: ['unused_helper'] )
+      warnings.post_compile_execute( context: :test, shell_result: compile( 'a.c' ) )
+      warnings.post_build( 0 )
+
+      expect(log_for( :test )).to include( 'spare' )
+      expect(log_for( :test )).not_to include( 'unused_helper' )
+    end
+  end
+
+  it 'writes nothing and says so for a build without warnings' do
+    in_project do
+      warnings = plugin
+      warnings.post_compile_execute( context: :test, shell_result: { output: "Compiling foo.c...\n" } )
+      warnings.post_build( 0 )
+
+      expect(Dir.exist?( 'build/artifacts' )).to be false
+      expect(logged).to include( "Build produced no warnings.\n" )
+    end
+  end
+
+  it 'writes its log when the build ends in error too' do
+    in_project do
+      warnings = plugin
+      warnings.post_link_execute( context: :test, shell_result: { output: "ld: warning: object file built for newer OS\n" } )
+      warnings.post_error( 0 )
+
+      expect(log_for( :test )).to include( 'ld: warning:' )
+    end
+  end
+
+  it 'keeps the source and caret lines that belong to each warning' do
+    in_project do
+      warnings = plugin
+      warnings.post_compile_execute( context: :test, shell_result: compile( 'a.c' ) )
+      warnings.post_build( 0 )
+
+      expect(log_for( :test )).to include( 'int spare;', '^' )
+    end
+  end
+
+  it 'logs a warning from a shared header once' do
+    in_project do
+      warnings = plugin
+      %w[a.c b.c].each { |file| warnings.post_compile_execute( context: :test, shell_result: compile( file ) ) }
+      warnings.post_build( 0 )
+
+      expect(log_for( :test ).scan( /warning: .*unused_helper/ ).size).to eq( 1 )
+    end
+  end
+
+  # Structured reports of the same build agree with its text log
+  it 'writes SARIF and JSON reports of the warnings in the text log' do
+    in_project do
+      warnings = plugin( reports: %i[text sarif json] )
+      %w[a.c b.c].each { |file| warnings.post_compile_execute( context: :test, shell_result: compile( file ) ) }
+      warnings.post_build( 0 )
+
+      json    = JSON.parse( File.read( 'build/artifacts/test/warnings.json' ) )
+      sarif   = JSON.parse( File.read( 'build/artifacts/test/warnings.sarif' ) )
+      results = sarif.dig( 'runs', 0, 'results' )
+
+      expect(json['warnings'].map { |warning| warning['text'] }.join).to eq( log_for( :test ) )
+      expect(json['warnings'].map { |warning| [warning['file'].delete_prefix( './' ), warning['line'], warning['flag']] })
+        .to contain_exactly( ['a.c', 2, '-Wunused-variable'], ['shared.h', 1, '-Wunused-function'] )
+
+      expect(sarif).to include( 'version' => '2.1.0' )
+      expect(sarif.dig( 'runs', 0, 'tool', 'driver', 'name' )).to eq( 'Ceedling' )
+      expect(results.map { |result| result['ruleId'] }).to contain_exactly( '-Wunused-variable', '-Wunused-function' )
+      results.each do |result|
+        expect(result).to include( 'level' => 'warning', 'message' => hash_including( 'text' ) )
+        expect(result.dig( 'locations', 0, 'physicalLocation', 'region', 'startLine' )).to be_a( Integer )
+        expect(result.dig( 'locations', 0, 'physicalLocation', 'artifactLocation', 'uri' )).to eq( 'a.c' ).or eq( 'shared.h' )
+      end
+    end
+  end
+
+  it 'writes empty structured reports, and no text log, for a build without warnings' do
+    in_project do
+      warnings = plugin( reports: %i[text sarif json] )
+      warnings.post_compile_execute( context: :test, shell_result: { output: "Compiling foo.c...\n" } )
+      warnings.post_build( 0 )
+
+      expect(Dir.children( 'build/artifacts/test' )).to contain_exactly( 'warnings.sarif', 'warnings.json' )
+      expect(JSON.parse( File.read( 'build/artifacts/test/warnings.sarif' ) ).dig( 'runs', 0, 'results' )).to eq( [] )
+    end
+  end
+
+end

data/spec/integration/report_tests_log_factory_spec.rb

@@ -0,0 +1,100 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Integration coverage for the Test Suite Report Log Factory's built-in reports.
+#
+# Each report is written to a real file and read back with a real parser, so a report a
+# CI tool would reject is caught here. The results use a project name and a test path
+# full of markup metacharacters, which every format must carry intact. The unit specs
+# for each reporter own their structure through in-memory streams.
+
+require 'spec_helper'
+require 'json'
+require 'tmpdir'
+require 'rexml/document'
+require 'ceedling/file_wrapper'
+require 'ceedling/config/config_walkinator'
+
+$: << File.expand_path('../../../plugins/report_tests_log_factory/lib', __FILE__)
+require 'json_tests_reporter'
+require 'junit_tests_reporter'
+require 'cppunit_tests_reporter'
+require 'html_tests_reporter'
+
+describe 'ReportTestsLogFactory reports (integration)' do
+  let(:name) { 'Q-36 & "<Modulator>"' }
+  let(:test_file) { 'test/T&"x".c' }
+
+  let(:results) do
+    {
+      times:     { test_file => 0.25 },
+      successes: [ { source: { file: test_file }, collection: [ { test: 'test_a', line: 1, message: '', unity_test_time: 0 } ] } ],
+      failures:  [ { source: { file: test_file }, collection: [ { test: 'test_<b>', line: 2, message: 'Expected "<a>" & more', unity_test_time: 0 } ] } ],
+      ignores:   [ { source: { file: test_file }, collection: [ { test: 'test_c', line: 3, message: '', unity_test_time: 0 } ] } ],
+      stdout:    [ { source: { file: test_file }, collection: ['printed <out> & more'] } ],
+      counts:    { total: 3, passed: 1, failed: 1, ignored: 1, stdout: 1 },
+      total_time: 0.25
+    }
+  end
+
+  # Writes one report into `dir` and returns its contents
+  def report(klass, handle, dir)
+    verbosinator = double('verbosinator', should_output?: false)
+    reporter = klass.new( handle: handle )
+    reporter.config            = {}
+    reporter.config_walkinator = ConfigWalkinator.new
+    reporter.file_wrapper      = FileWrapper.new( { loginator: double('loginator', log: nil), verbosinator: verbosinator } )
+    reporter.setup
+
+    filepath = File.join( dir, reporter.filename )
+    reporter.write( name: name, filepath: filepath, results: results, duration_s: 4 )
+    File.read( filepath )
+  end
+
+  it 'writes a JUnit report that parses, carrying names and messages intact' do
+    Dir.mktmpdir do |dir|
+      root = REXML::Document.new( report( JunitTestsReporter, :junit, dir ) ).root
+
+      expect(root.attributes['name']).to eq(name)
+      expect(root.elements['testsuite'].attributes['name']).to eq('test/T&"x"')
+      expect(root.elements['testsuite/testcase/failure'].attributes['message']).to eq('test/T&"x".c:2: Expected "<a>" & more')
+      expect(root.elements['testsuite/testcase'].attributes['file']).to eq('test/T&"x".c')
+      expect(root.elements['testsuite/system-out'].text).to include('printed <out> & more')
+    end
+  end
+
+  it 'writes a CppUnit report that parses, carrying names and messages intact' do
+    Dir.mktmpdir do |dir|
+      root = REXML::Document.new( report( CppunitTestsReporter, :cppunit, dir ) ).root
+
+      expect(root.attributes['name']).to eq(name)
+      expect(root.elements['FailedTests/Test/Name'].text).to eq('test/T&"x".c::test_<b>')
+      expect(root.elements['FailedTests/Test/Message'].text).to eq('Expected "<a>" & more')
+    end
+  end
+
+  it 'writes a JSON report that parses, carrying names and messages intact' do
+    Dir.mktmpdir do |dir|
+      parsed = JSON.parse( report( JsonTestsReporter, :json, dir ) )
+
+      expect(parsed['Name']).to eq(name)
+      expect(parsed['BuildDuration']).to eq(4)
+      expect(parsed['FailedTests'].first).to include('file' => test_file, 'message' => 'Expected "<a>" & more')
+    end
+  end
+
+  it 'writes an HTML report with every name and message escaped' do
+    Dir.mktmpdir do |dir|
+      html = report( HtmlTestsReporter, :html, dir )
+
+      expect(html).to include('<title>Ceedling Test Suite: Q-36 &amp; &quot;&lt;Modulator&gt;&quot;</title>')
+      expect(html).to include('test_&lt;b&gt;')
+      expect(html).to include('Expected &quot;&lt;a&gt;&quot; &amp; more')
+      expect(html).not_to include('<Modulator>')
+    end
+  end
+end

data/spec/integration/sanitizer_exclusions_spec.rb

@@ -0,0 +1,126 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Guards the `nosanitize` naming convention that keeps deliberately-faulty C
+# fixtures out of ASan+UBSan instrumentation.
+#
+# The convention is enforceable only by a test, because every way it can break
+# breaks silently. Renaming a crashing fixture without the segment instruments
+# it, and the suite then reports a sanitizer "finding" that is really the fault
+# the fixture exists to provoke. Breaking the matcher regex the other way
+# instruments nothing at all, and the whole leg goes green while testing none of
+# what it claims to.
+#
+# Integration tier rather than unit: this reads real files from
+# assets/fixtures/, and unit specs in this repo touch neither filesystem nor
+# shell. The matcher *logic* is pinned separately and purely in
+# spec/units/config_matchinator_spec.rb.
+#
+# The one thing this cannot catch, stated plainly: a newly-added crashing
+# fixture that carries neither the filename segment nor the convention comment
+# is invisible to every check below. This guards drift in what is marked, not
+# the absence of marking.
+
+require 'spec_helper'
+require 'yaml'
+
+describe 'Sanitizer exclusion convention (integration)' do
+
+  REPO_ROOT_FOR_SANITIZERS = File.expand_path( '../..', __dir__ )
+  FIXTURES_DIR = File.join( REPO_ROOT_FOR_SANITIZERS, 'assets', 'fixtures' )
+  FLAVORS_DIR  = File.join( REPO_ROOT_FOR_SANITIZERS, 'spec', 'support', 'system', 'sanitizers' )
+
+  # Every fixture the convention must cover, by the name it carries today.
+  # Listed explicitly, not globbed: a glob would quietly shrink to nothing if
+  # these files were deleted or renamed, which is precisely the drift being
+  # guarded against.
+  EXCLUDED_FIXTURES = [
+    'test_nosanitize_crash_sigsegv.c',
+    'test_nosanitize_crash_sigsegv_with_param.c',
+    'test_nosanitize_crash_assert.c',
+    'test_nosanitize_ub_shift_overflow.c',
+    'test_nosanitize_boom.c',
+    'test_nosanitize_heap_buffer_overflow.c',
+    'test_nosanitize_leak.c',
+    'test_nosanitize_two_findings.c'
+  ].freeze
+
+  # The sentence each excluded fixture carries in a header comment. Short enough
+  # to survive rewording of the surrounding prose, specific enough that no other
+  # file would contain it by accident.
+  CONVENTION_COMMENT = 'The `nosanitize` filename segment is read by a build-time matcher'
+
+  # Read out of the flavor YAML rather than restated here, so this spec and the
+  # mixins cannot drift apart -- a spec carrying its own copy of the regex would
+  # keep passing after the mixin's copy was broken.
+  def exclusion_regexes
+    Dir[File.join( FLAVORS_DIR, '*.yml' )].sort.to_h do |path|
+      hash = YAML.load_file( path )
+      keys = [
+        hash.dig( :flags, :test, :compile ),
+        hash.dig( :flags, :test, :link ),
+        hash.dig( :defines, :test )
+      ].compact.flat_map( &:keys ).uniq
+
+      expect( keys.size ).to eq(1), "#{File.basename(path)} must use one matcher throughout, found #{keys.inspect}"
+
+      expr = keys.first.to_s
+      expect( expr ).to start_with('/'), "#{File.basename(path)} matcher #{expr} is not in /regex/ form"
+      expect( expr ).to end_with('/')
+
+      [File.basename( path ), Regexp.new( expr[1..-2] )]
+    end
+  end
+
+  it 'finds at least one sanitizer flavor to guard' do
+    # Without this, every example below would vacuously pass if the flavor
+    # directory were emptied or moved
+    expect( exclusion_regexes ).not_to be_empty
+  end
+
+  it 'keeps every listed fixture present under its conventional name' do
+    EXCLUDED_FIXTURES.each do |basename|
+      expect( File.exist?( File.join( FIXTURES_DIR, basename ) ) ).to be(true),
+        "#{basename} is missing. Deliberately-faulty fixtures must keep a `nosanitize` filename " \
+        "segment -- it is what excludes them from sanitizer instrumentation. If this file was " \
+        "renamed, update this list and the comment in the file itself; if it was deleted, remove " \
+        "it from this list."
+    end
+  end
+
+  it "excludes every listed fixture from every flavor's instrumentation" do
+    exclusion_regexes.each do |flavor, regex|
+      EXCLUDED_FIXTURES.each do |basename|
+        expect( regex.match?( "test/#{basename}" ) ).to be(false),
+          "#{flavor} would instrument #{basename}"
+      end
+    end
+  end
+
+  it 'still instruments ordinary test files' do
+    # The other half of the regex's job. A pattern that excluded everything
+    # would satisfy every example above while instrumenting nothing, and a green
+    # suite would be indistinguishable from a working one.
+    exclusion_regexes.each do |flavor, regex|
+      ['test/test_example_file.c', 'build/test/runners/test_example_file_runner.c'].each do |filepath|
+        expect( regex.match?( filepath ) ).to be(true), "#{flavor} would not instrument #{filepath}"
+      end
+    end
+  end
+
+  it 'keeps filename segment and convention comment in agreement, both directions' do
+    named    = Dir[File.join( FIXTURES_DIR, '**', '*nosanitize*' )].sort
+    commented = Dir[File.join( FIXTURES_DIR, '**', '*.c' )].sort.select do |path|
+      File.read( path ).include?( CONVENTION_COMMENT )
+    end
+
+    # Either direction failing means a reader of one signal is being misled by
+    # the absence of the other
+    expect( named.sort ).to eq(commented.sort)
+  end
+
+end

data/spec/integration/system_harness_sanitizers_spec.rb

@@ -0,0 +1,104 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Coverage for how the system test harness translates CEEDLING_TEST_SANITIZERS
+# into what Ceedling actually consumes: a CEEDLING_MIXIN_* slot holding an
+# absolute path, plus the sanitizer's own runtime options in the environment the
+# test executable inherits.
+#
+# Integration tier: these examples load the real flavor files from
+# spec/support/system/sanitizers/ and exercise SystemContext's real environment
+# manipulation, but spawn no subprocess and build nothing. The system suite
+# itself would prove the same translation only as a side effect of a full build,
+# at minutes per example instead of milliseconds, and would not be able to show
+# the negative cases at all.
+#
+# `with_context` is reached directly rather than through a deployed project
+# because its environment block is the unit under test here -- it yields with
+# ENV already assembled, so the block can simply read back what it set.
+
+require 'spec_helper'
+require 'system_context'
+
+describe 'System harness sanitizer wiring (integration)' do
+
+  # with_context chdir's into this and restores on exit; nothing is written to it
+  let(:context) { SystemContext.new }
+
+  after do
+    context.done!
+    SystemContext.sanitizers_disabled = false
+  end
+
+  # Returns the ENV values with_context assembles, for just the keys this spec
+  # cares about. Captured inside the block because with_constrained_env restores
+  # the surrounding environment the moment it returns.
+  def captured_env(flavor)
+    original = ENV['CEEDLING_TEST_SANITIZERS']
+    ENV['CEEDLING_TEST_SANITIZERS'] = flavor
+    captured = nil
+    context.with_context do
+      captured = { mixin: ENV['CEEDLING_MIXIN_9'], asan: ENV['ASAN_OPTIONS'] }
+    end
+    captured
+  ensure
+    ENV['CEEDLING_TEST_SANITIZERS'] = original
+  end
+
+  context 'when CEEDLING_TEST_SANITIZERS names a flavor' do
+    it 'exports the flavor mixin as an absolute path' do
+      env = captured_env('asan_ubsan')
+
+      # Absolute, not relative: each spec chdir's into its own ephemeral project
+      # directory, so a relative path would resolve against that project and the
+      # mixin would silently fail to be found
+      expect( env[:mixin] ).to eq(File.absolute_path( env[:mixin] ))
+      expect( env[:mixin] ).to end_with(File.join('sanitizers', 'asan_ubsan.yml'))
+      expect( File.exist?( env[:mixin] ) ).to be(true)
+    end
+
+    it "exports the flavor's own runtime options" do
+      expect( captured_env('asan_ubsan')[:asan] ).to eq('detect_leaks=0')
+    end
+
+    it 'exports the leaks flavor with leak detection on' do
+      # The two flavors differ in exactly this value, which is why the flavor
+      # file owns it rather than the harness
+      expect( captured_env('asan_ubsan_leaks')[:asan] ).to include('detect_leaks=1')
+    end
+  end
+
+  context 'when CEEDLING_TEST_SANITIZERS is unset or empty' do
+    it 'exports nothing, leaving every other matrix leg untouched' do
+      [nil, '', '   '].each do |value|
+        env = captured_env(value)
+        expect( env[:mixin] ).to be_nil
+        expect( env[:asan] ).to be_nil
+      end
+    end
+  end
+
+  context 'when CEEDLING_TEST_SANITIZERS names no existing flavor' do
+    it 'raises rather than running uninstrumented' do
+      # A typo in a CI workflow must fail the job, not quietly reduce it to an
+      # ordinary run that reports success while testing none of what it claims
+      expect { captured_env('asan_ubsan_typo') }.to raise_error(
+        SystemContext::VerificationFailed, /asan_ubsan_typo/
+      )
+    end
+  end
+
+  context 'when a spec opts out' do
+    it 'exports nothing even with a valid flavor selected' do
+      SystemContext.sanitizers_disabled = true
+      env = captured_env('asan_ubsan')
+      expect( env[:mixin] ).to be_nil
+      expect( env[:asan] ).to be_nil
+    end
+  end
+
+end

data/spec/integration/test_build_parallel_barrier_spec.rb

@@ -0,0 +1,89 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Integration coverage for Fix 5 (Stage 2 of the concurrency/file-presence work,
+# Finding 4): TestBuildExecutor#apply_sibling_isolation's unguarded writes to
+# testable.search_paths/isolated_headers_path are safe only because
+# stage_build_objects's two-pass split is a real barrier -- every test's own file
+# compiles in one Batchinator batch, fully drained, before any other object in
+# that same test's build starts in a second batch. This is a canary, not a
+# behavior test: today's design should pass every time, and it should keep
+# passing after any future change -- if it ever starts failing, that's this spec
+# doing its job, catching a barrier that's been merged away or reordered.
+#
+# This is the committed, right-sized version of the fact-finding phase's
+# Experiment D. It belongs at the integration tier, not unit: it exercises a real
+# Batchinator driving real Parallel.map worker threads, not a mocked stand-in for
+# one -- exactly the real-threads-and-timing distinction this codebase's own test
+# tiers already draw (see spec/support/integration/spec_integration_helper.rb's
+# own header comment for that distinction as applied to the includes path).
+
+require 'spec_helper'
+require 'constructor'
+require 'ceedling/constants'
+require 'ceedling/batchinator'
+
+describe 'TestBuildExecutor two-pass compile barrier (integration)' do
+  # Absorbs whatever Batchinator's own logging/reporting calls -- this spec cares
+  # about thread scheduling, not log output.
+  class NullObject
+    def method_missing(*_args, **_kwargs); self; end
+    def respond_to_missing?(*); true; end
+  end
+  PARALLEL_BARRIER_NULL = NullObject.new
+
+  class StubConfigurator
+    def initialize(threads); @threads = threads; end
+    def project_compile_threads; @threads; end
+    def project_test_threads; @threads; end
+  end
+
+  # Stands in for a Testable: the one field apply_sibling_isolation actually
+  # writes unguarded (search_paths), read many times per test across the second
+  # batch.
+  Testable = Struct.new(:name, :search_paths, keyword_init: true)
+
+  THREADS         = 12
+  TESTABLE_COUNT  = 40
+  ITERATIONS      = 40 # sized for CI runtime, not exhaustive reproduction -- see below
+
+  let(:batchinator) { Batchinator.new(configurator: StubConfigurator.new(THREADS), loginator: PARALLEL_BARRIER_NULL, reportinator: PARALLEL_BARRIER_NULL) }
+
+  # Mirrors stage_build_objects's own two sequential compile_pass.call invocations:
+  # every testable's "own file" batch (the only place search_paths is corrected)
+  # runs to completion before the "other objects" batch, which must see every
+  # correction, starts.
+  def run_two_pass(testables)
+    violations = 0
+
+    batchinator.exec(workload: :compile, things: testables) do |t|
+      sleep(rand * 0.001) # widen the scheduling window a little
+      t.search_paths = ["ISOLATED:#{t.name}"] + t.search_paths
+    end
+
+    batchinator.exec(workload: :compile, things: testables) do |t|
+      violations += 1 unless t.search_paths.first == "ISOLATED:#{t.name}"
+    end
+
+    violations
+  end
+
+  it 'never lets an "other object" read an uncorrected search_paths, across many iterations' do
+    total_violations = 0
+
+    ITERATIONS.times do
+      testables = Array.new(TESTABLE_COUNT) { |i| Testable.new(name: "test#{i}", search_paths: ["orig#{i}"]) }
+      total_violations += run_two_pass(testables)
+    end
+
+    # Stage 1's fact-finding run (200 iterations, both host and Docker) saw exactly
+    # 0/8,000 violations here and 97%+ once the barrier was removed -- a real,
+    # reliably-reproducing gap this size is enough to reliably catch a regression
+    # at this smaller, CI-sized iteration count too.
+    expect(total_violations).to eq(0)
+  end
+end