ceedling 1.1.10 → 1.2.0

data/plugins/bullseye/lib/bullseye_constants.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
+# =========================================================================
+
+BULLSEYE_ROOT_NAME           = 'bullseye'.freeze
+BULLSEYE_TASK_ROOT           = BULLSEYE_ROOT_NAME + ':'
+BULLSEYE_SYM                 = BULLSEYE_ROOT_NAME.to_sym
+
+BULLSEYE_REPORT_NAMESPACE_SYM = :report
+
+BULLSEYE_BUILD_PATH          = File.join(PROJECT_BUILD_ROOT, BULLSEYE_ROOT_NAME)
+BULLSEYE_BUILD_OUTPUT_PATH   = File.join(BULLSEYE_BUILD_PATH, BUILD_OUT_DIR)
+BULLSEYE_RESULTS_PATH        = File.join(BULLSEYE_BUILD_PATH, BUILD_RESULTS_DIR)
+BULLSEYE_DEPENDENCIES_PATH   = File.join(BULLSEYE_BUILD_PATH, BUILD_DEPENDENCIES_DIR)
+BULLSEYE_ARTIFACTS_PATH      = File.join(PROJECT_BUILD_ARTIFACTS_ROOT, BULLSEYE_ROOT_NAME)
+BULLSEYE_HTML_ARTIFACTS_PATH = File.join(BULLSEYE_ARTIFACTS_PATH, 'covhtml')
+
+# One filename serves both XML formats. Only one format is ever active per build.
+BULLSEYE_XML_ARTIFACT_PATH   = File.join(BULLSEYE_ARTIFACTS_PATH, 'coverage.xml')
+
+# Bullseye records each source's path in the .cov file relative to the .cov file's own
+# directory, and region-exclusion glob patterns (covselect, and covsrc/covfn/covhtml's
+# automatic honoring of covselect's persisted selections) match against that raw stored
+# path. Bullseye's own docs recommend locating the coverage file at "the parent of all
+# the directories containing source files" for exactly this reason. Ceedling's project
+# root is that common ancestor for every source location a project can have (src/,
+# test/, build/vendor/.../, build/test/runners/, etc.) — anywhere under build/artifacts/
+# is not, since it's a descendant of build/ itself, which forces multi-level ../..
+# prefixes into stored paths and breaks exclusion pattern matching. So, unlike every
+# other Bullseye build artifact, the .cov file itself lives at project root, not under
+# build/.
+BULLSEYE_COVFILE_PATH        = 'test.cov'
+
+# Vendor/framework sources never subject to coverage instrumentation or reporting
+BULLSEYE_IGNORE_SOURCES      = ['unity', 'cmock', 'cexception']
+
+TOOL_COLLECTION_BULLSEYE_TASKS = {
+  :test_compiler  => TOOLS_BULLSEYE_COMPILER,
+  :test_assembler => TOOLS_TEST_ASSEMBLER,
+  :test_linker    => TOOLS_BULLSEYE_LINKER,
+  :test_fixture   => TOOLS_BULLSEYE_FIXTURE
+}
+
+# Untested Sources Processing Modes
+# :ignore  — Skip untested sources entirely (no logging, no compilation).
+# :list    — Log untested source filepaths as a warning; do not compile them.
+# :compile — Compile all untested sources with coverage instrumentation.
+BULLSEYE_UNTESTED_SOURCES_IGNORE  = :ignore
+BULLSEYE_UNTESTED_SOURCES_LIST    = :list
+BULLSEYE_UNTESTED_SOURCES_COMPILE = :compile
+BULLSEYE_UNTESTED_SOURCES_OPTIONS = [
+  BULLSEYE_UNTESTED_SOURCES_IGNORE,
+  BULLSEYE_UNTESTED_SOURCES_LIST,
+  BULLSEYE_UNTESTED_SOURCES_COMPILE
+]
+
+# Branch Coverage Detail Modes
+# Bullseye's covsrc totals report a branch coverage percentage but never say which
+# branches went uncovered. covbr answers that with an annotated source listing.
+# :none      — No annotated listing.
+# :uncovered — Annotate only probes that are not fully covered (covbr --uncover).
+# :all       — Annotate every source line (covbr --all).
+# --uncover and --all are mutually exclusive per Bullseye's own reference.
+BULLSEYE_BRANCH_DETAIL_NONE      = :none
+BULLSEYE_BRANCH_DETAIL_UNCOVERED = :uncovered
+BULLSEYE_BRANCH_DETAIL_ALL       = :all
+BULLSEYE_BRANCH_DETAIL_OPTIONS   = [
+  BULLSEYE_BRANCH_DETAIL_NONE,
+  BULLSEYE_BRANCH_DETAIL_UNCOVERED,
+  BULLSEYE_BRANCH_DETAIL_ALL
+]
+
+# covbr mode flags keyed by configuration value
+BULLSEYE_BRANCH_DETAIL_FLAGS = {
+  BULLSEYE_BRANCH_DETAIL_UNCOVERED => '--uncover',
+  BULLSEYE_BRANCH_DETAIL_ALL       => '--all'
+}
+
+# XML Report Formats
+# :none      — Generate no XML report.
+# :native    — Bullseye's own XML schema (covxml default output).
+# :cobertura — Cobertura format for CI tools that consume it (covxml --cobertura).
+BULLSEYE_XML_REPORT_NONE      = :none
+BULLSEYE_XML_REPORT_NATIVE    = :native
+BULLSEYE_XML_REPORT_COBERTURA = :cobertura
+BULLSEYE_XML_REPORT_OPTIONS   = [
+  BULLSEYE_XML_REPORT_NONE,
+  BULLSEYE_XML_REPORT_NATIVE,
+  BULLSEYE_XML_REPORT_COBERTURA
+]
+
+# covxml format flags keyed by configuration value. Native format is covxml's
+# default and needs no flag, so it maps to an empty argument.
+BULLSEYE_XML_REPORT_FLAGS = {
+  BULLSEYE_XML_REPORT_NATIVE    => '',
+  BULLSEYE_XML_REPORT_COBERTURA => '--cobertura'
+}

data/plugins/command_hooks/lib/command_hooks.rb

@@ -13,228 +13,146 @@ require 'ceedling/tool_executor'
 COMMAND_HOOKS_ROOT_NAME = 'command_hooks'.freeze
 COMMAND_HOOKS_SYM       = COMMAND_HOOKS_ROOT_NAME.to_sym
 
-COMMAND_HOOKS_LIST = [
-  :pre_mock_preprocess,
-  :post_mock_preprocess,
-  :pre_test_preprocess,
-  :post_test_preprocess,
-  :pre_mock_generate,
-  :post_mock_generate,
-  :pre_runner_generate,
-  :post_runner_generate,
-  :pre_compile_execute,
-  :post_compile_execute,
-  :pre_link_execute,
-  :post_link_execute,
-  :pre_test_fixture_execute,
-  :post_test_fixture_execute,
-  :pre_test,
-  :post_test,
-  :pre_test_build,
-  :post_test_build,
-  :pre_release_build,
-  :post_release_build,
-  :pre_build,
-  :post_build,
-  :post_error,
-].freeze
-
+# Hooks whose build step hands over an argument hash, and the hash entries its tools
+# receive as ${1}, ${2}, ... The keys are those Ceedling's core builds for each step.
+COMMAND_HOOKS_ARGUMENTS = {
+  pre_mock_preprocess:       [:header_file],
+  post_mock_preprocess:      [:header_file],
+  pre_test_preprocess:       [:test_file],
+  post_test_preprocess:      [:test_file],
+  pre_mock_generate:         [:header_file],
+  post_mock_generate:        [:header_file],
+  pre_runner_generate:       [:test_file],
+  post_runner_generate:      [:runner_file],
+  pre_compile_execute:       [:source, :object],
+  post_compile_execute:      [:source, :object],
+  pre_link_execute:          [:executable],
+  post_link_execute:         [:executable],
+  pre_test_fixture_execute:  [:executable],
+  post_test_fixture_execute: [:executable]
+}.freeze
+
+# Hooks whose build step hands over plain values, which their tools receive in order
+COMMAND_HOOKS_VALUES = %i[pre_test post_test pre_test_build post_test_build pre_release_build post_release_build
+                          pre_build post_build post_error].freeze
+
+COMMAND_HOOKS_LIST = (COMMAND_HOOKS_ARGUMENTS.keys + COMMAND_HOOKS_VALUES).freeze
+
+# Runs the tools a project configures under :command_hooks at Ceedling's build steps.
+#
+# Each hook takes one tool or a list of tools, every one validated as Ceedling validates
+# any tool. A tool receives its hook's arguments as ${1}, ${2}, and so on, and logs its
+# output when its :logging is set.
 class CommandHooks < Plugin
 
   def setup
-    # Get a copy of the project configuration
     project_config = @ceedling[:setupinator].config_hash
 
-    # Convenience object references
-    @loginator = @ceedling[:loginator]
-    @reportinator = @ceedling[:reportinator]
-    @walkinator = @ceedling[:config_walkinator]
-    @tool_validator = @ceedling[:tool_validator]
-    @tool_executor = @ceedling[:tool_executor]
-    @verbosinator = @ceedling[:verbosinator]
-    @configurator_validator = @ceedling[:configurator_validator]
-    
-    # Look up if the accompanying `:command_hooks` configuration block exists
-    config_exists = @configurator_validator.exists?(
-      project_config,
-      COMMAND_HOOKS_SYM
-    )
-
-    # Go boom if the required configuration block does not exist
-    unless config_exists
-      name = @reportinator.generate_config_walk([COMMAND_HOOKS_SYM])
-      error = "Command Hooks plugin is enabled but is missing a required configuration block `#{name}`"
-      raise CeedlingException.new(error)
-    end
-    
-    @config = project_config[COMMAND_HOOKS_SYM]
-    
-    # Validate the command hook keys (look out for typos)
-    validate_config( @config )
-    
-    # Validate the tools beneath the keys
-    @config.each do |hook, tool|
-      if tool.is_a?(Array)
-        tool.each_index {|index| validate_hook( project_config, hook, index )}
-      else
-        validate_hook( project_config, hook )
-      end
+    @loginator     = @ceedling[:loginator]
+    @reportinator  = @ceedling[:reportinator]
+    @verbosinator  = @ceedling[:verbosinator]
+
+    unless @ceedling[:configurator_validator].exists?( project_config, COMMAND_HOOKS_SYM )
+      name = @reportinator.generate_config_walk( [COMMAND_HOOKS_SYM] )
+      raise CeedlingException.new( "Command Hooks plugin is enabled but is missing a required configuration block `#{name}`" )
     end
+
+    config = project_config[COMMAND_HOOKS_SYM]
+    validate_config( config )
+
+    # Every hook as a list of its validated tools
+    @hooks = config.to_h { |hook, tools| [hook, validate_tools( hook, tools )] }
+  end
+
+  COMMAND_HOOKS_ARGUMENTS.each do |hook, keys|
+    define_method( hook ) { |arg_hash| run_hook( hook, *arg_hash.values_at( *keys ) ) }
   end
 
-  def pre_mock_preprocess(arg_hash);           run_hook( :pre_mock_preprocess,       arg_hash[:header_file] ); end
-  def post_mock_preprocess(arg_hash);          run_hook( :post_mock_preprocess,      arg_hash[:header_file] ); end
-  def pre_test_preprocess(arg_hash);           run_hook( :pre_test_preprocess,       arg_hash[:test_file]   ); end
-  def post_test_preprocess(arg_hash);          run_hook( :post_test_preprocess,      arg_hash[:test_file]   ); end
-  def pre_mock_generate(arg_hash);             run_hook( :pre_mock_generate,         arg_hash[:header_file] ); end
-  def post_mock_generate(arg_hash);            run_hook( :post_mock_generate,        arg_hash[:header_file] ); end
-  def pre_runner_generate(arg_hash);           run_hook( :pre_runner_generate,       arg_hash[:source]      ); end
-  def post_runner_generate(arg_hash);          run_hook( :post_runner_generate,      arg_hash[:runner_file] ); end
-  def pre_compile_execute(arg_hash);           run_hook( :pre_compile_execute,       arg_hash[:source_file] ); end
-  def post_compile_execute(arg_hash);          run_hook( :post_compile_execute,      arg_hash[:object_file] ); end
-  def pre_link_execute(arg_hash);              run_hook( :pre_link_execute,          arg_hash[:executable]  ); end
-  def post_link_execute(arg_hash);             run_hook( :post_link_execute,         arg_hash[:executable]  ); end
-  def pre_test_fixture_execute(arg_hash);      run_hook( :pre_test_fixture_execute,  arg_hash[:executable]  ); end
-  def post_test_fixture_execute(arg_hash);     run_hook( :post_test_fixture_execute, arg_hash[:executable]  ); end
-  def pre_test(test);                          run_hook( :pre_test,                  test ); end
-  def post_test(test);                         run_hook( :post_test,                 test ); end
-  def pre_test_build(context, timestamp_s);    run_hook( :pre_test_build,            context.to_s, timestamp_s.to_s ); end
-  def post_test_build(context, timestamp_s);   run_hook( :post_test_build,           context.to_s, timestamp_s.to_s ); end
-  def pre_release_build(timestamp_s);          run_hook( :pre_release_build,         timestamp_s.to_s ); end
-  def post_release_build(timestamp_s);         run_hook( :post_release_build,        timestamp_s.to_s ); end
-  def pre_build(timestamp_s);                  run_hook( :pre_build,                 timestamp_s.to_s ); end
-  def post_build(timestamp_s);                 run_hook( :post_build,                timestamp_s.to_s ); end
-  def post_error(timestamp_s);                 run_hook( :post_error,                timestamp_s.to_s ); end
+  def pre_test(test);                        run_hook( :pre_test,           test ); end
+  def post_test(test);                       run_hook( :post_test,          test ); end
+  def pre_test_build(context, timestamp_s);  run_hook( :pre_test_build,     context.to_s, seconds( timestamp_s ) ); end
+  def post_test_build(context, timestamp_s); run_hook( :post_test_build,    context.to_s, seconds( timestamp_s ) ); end
+  def pre_release_build(timestamp_s);        run_hook( :pre_release_build,  seconds( timestamp_s ) ); end
+  def post_release_build(timestamp_s);       run_hook( :post_release_build, seconds( timestamp_s ) ); end
+  def pre_build(timestamp_s);                run_hook( :pre_build,          seconds( timestamp_s ) ); end
+  def post_build(timestamp_s);               run_hook( :post_build,         seconds( timestamp_s ) ); end
+  def post_error(timestamp_s);               run_hook( :post_error,         seconds( timestamp_s ) ); end
 
   ### Private
 
   private
-  
-  ##
-  # Validate plugin configuration.
-  #
-  # :args:
-  #   - config: :command_hooks section from project config hash
-  #
+
+  # A stopwatch value as seconds. Ceedling's stopwatch is a Float count of seconds on most
+  # platforms but the wall clock, a Time, on Windows. Converting through the exact
+  # Rational keeps a Time's fraction from picking up rounding noise.
+  def seconds(timestamp)
+    return timestamp.to_r.to_f.to_s
+  end
+
+  # The :command_hooks section must be a hash of recognized hooks, so a misspelled hook
+  # stops the build rather than silently never running
   def validate_config(config)
-    unless config.is_a?(Hash)
-      name = @reportinator.generate_config_walk([COMMAND_HOOKS_SYM])
-      error = "Expected configuration #{name} to be a Hash but found #{config.class}"
-      raise CeedlingException.new(error)
+    unless config.is_a?( Hash )
+      name = @reportinator.generate_config_walk( [COMMAND_HOOKS_SYM] )
+      raise CeedlingException.new( "Expected configuration #{name} to be a Hash but found #{config.class}" )
     end
-    
-    unrecognized_hooks = config.keys - COMMAND_HOOKS_LIST
-    
-    unrecognized_hooks.each do |not_a_hook|
-      name = @reportinator.generate_config_walk( [COMMAND_HOOKS_SYM, not_a_hook] )
-      error = "Unrecognized Command Hook: #{name}"
-      @loginator.log( error, Verbosity::ERRORS )
-    end
-    
-    unless unrecognized_hooks.empty?
-      error = "Unrecognized hooks found in Command Hooks plugin configuration"
-      raise CeedlingException.new(error)
+
+    unrecognized = config.keys - COMMAND_HOOKS_LIST
+    return if unrecognized.empty?
+
+    unrecognized.each do |hook|
+      @loginator.log( "Unrecognized Command Hook: #{@reportinator.generate_config_walk( [COMMAND_HOOKS_SYM, hook] )}", Verbosity::ERRORS )
     end
+    raise CeedlingException.new( 'Unrecognized hooks found in Command Hooks plugin configuration' )
   end
-  
-  ##
-  # Validate given hook
-  #
-  # :args:
-  #   - config: Project configuration hash
-  #   - keys: Key and index of hook inside :command_hooks configuration
-  #
-  def validate_hook(config, *keys)
-    walk = [COMMAND_HOOKS_SYM, *keys]
-    name = @reportinator.generate_config_walk( walk )
-    entry, _ = @walkinator.fetch_value( *walk, hash:config )
-
-    if entry.nil?
-      raise CeedlingException.new( "Missing Command Hook plugin configuration for #{name}" )
-    end
-        
-    unless entry.is_a?(Hash)
-      error = "Expected configuration #{name} for Command Hooks plugin to be a Hash but found #{entry.class}"
-      raise CeedlingException.new( error )
+
+  # A hook's tools as a list, each validated. A single tool may stand alone or be the only
+  # entry in a list.
+  def validate_tools(hook, tools)
+    return [validate_tool( tools, [hook] )] unless tools.is_a?( Array )
+
+    return tools.each_with_index.map { |tool, index| validate_tool( tool, [hook, index] ) }
+  end
+
+  def validate_tool(tool, keys)
+    name = @reportinator.generate_config_walk( [COMMAND_HOOKS_SYM, *keys] )
+
+    raise CeedlingException.new( "Missing Command Hook plugin configuration for #{name}" ) if tool.nil?
+    unless tool.is_a?( Hash )
+      raise CeedlingException.new( "Expected configuration #{name} for Command Hooks plugin to be a Hash but found #{tool.class}" )
     end
 
-    # Populate name if not given
-    ToolExecutor.default_name!( entry, keys.join('_') )
+    ToolExecutor.default_name!( tool, keys.join( '_' ) )
+    @ceedling[:tool_validator].validate( tool: tool, name: name, boom: true )
+    tool[:logging] = false if tool[:logging].nil?
 
-    # Validate the Ceedling tool components of the hook entry config
-    @tool_validator.validate( tool: entry, name: name, boom: true )
+    return tool
+  end
 
-    # Default logging configuration
-    config[:logging] = false if config[:logging].nil?
+  # Runs each of a hook's tools in order, handing each the hook's arguments
+  def run_hook(hook, *args)
+    tools = @hooks[hook]
+    return if tools.nil?
+
+    @loginator.log( @reportinator.generate_progress( "Running Command Hook :#{hook}" ) )
+    tools.each { |tool| run_tool( hook, tool, *args ) }
   end
-  
-  ##
-  # Run a hook if its available.
-  #
-  # If __which_hook__ is an array, run each of them sequentially.
-  #
-  # :args:
-  #   - which_hook: Name of the hook to run
-  #   - args: Zero or more substitution values available as ${1}, ${2}, ... in tool argument lists
-  #
-  def run_hook(which_hook, *args)
-    if (@config[which_hook])
-      msg = "Running Command Hook :#{which_hook}"
-      msg = @reportinator.generate_progress( msg )
-      @loginator.log( msg )
-
-      # Single tool config
-      if (@config[which_hook].is_a? Hash)
-        run_hook_step( which_hook, @config[which_hook], *args )
-
-      # Multiple tool configs
-      elsif (@config[which_hook].is_a? Array)
-        @config[which_hook].each do |hook|
-          run_hook_step( which_hook, hook, *args )
-        end
-
-      # Tool config is bad
-      else
-        msg = "The tool config for Command Hook #{which_hook} was poorly formed and not run"
-        @loginator.log( msg, Verbosity::COMPLAIN )
-      end
-    end
+
+  def run_tool(hook, tool, *args)
+    command      = @ceedling[:tool_executor].build_command_line( tool, [], *args )
+    shell_result = @ceedling[:tool_executor].exec( command )
+    log_output( hook, shell_result[:output] ) if tool[:logging]
   end
 
-  ##
-  # Run a hook step (single tool execution).
-  #
-  # :args:
-  #   - which_hook: Name of the hook to run
-  #   - hook: Tool configuration hash for this step
-  #   - args: Zero or more substitution values available as ${1}, ${2}, ... in tool argument lists
-  #
-  # :return:
-  #    shell_result.
-  #
-  def run_hook_step(which_hook, hook, *args)
-    if (hook[:executable])
-      # Handle argument replacement (${1}, ${2}, ...) and get commandline
-      cmd = @ceedling[:tool_executor].build_command_line( hook, [], *args )
-      shell_result = @ceedling[:tool_executor].exec( cmd )
-
-      # If hook logging is enabled
-      if hook[:logging]
-        # Skip debug logging -- allow normal tool debug logging to do its thing
-        return if @verbosinator.should_output?( Verbosity::DEBUG )
-
-        output = shell_result[:output].strip
-
-        # Set empty output to empty string if we're in OBNOXIOUS logging mode
-        output = '<empty>' if output.empty? and @verbosinator.should_output?( Verbosity::OBNOXIOUS )
-
-        # Don't add to logging output if there's nothing to output
-        return if output.empty?
-
-        # NORMAL and OBNOXIOUS logging
-        @loginator.log( "Command Hook :#{which_hook} output >> #{output}" )
-      end
-    end
+  # Debug verbosity already logs every tool's output, so a hook's own logging stands aside
+  def log_output(hook, output)
+    return if @verbosinator.should_output?( Verbosity::DEBUG )
+
+    output = output.to_s.strip
+    output = '<empty>' if output.empty? and @verbosinator.should_output?( Verbosity::OBNOXIOUS )
+    return if output.empty?
+
+    @loginator.log( "Command Hook :#{hook} output >> #{output}" )
   end
 
 end

data/plugins/compile_commands_json_db/lib/compile_commands_json_db.rb

@@ -9,43 +9,88 @@ require 'ceedling/plugins/plugin'
 require 'ceedling/constants'
 require 'json'
 
+# Maintains a JSON compilation database so tools like clangd can see how a build compiles.
+#
+# The database accumulates across builds. A delta build compiles only what changed, so
+# entries from earlier builds carry over. It holds one entry per source file, and the
+# latest compile of a file replaces any earlier one. Entries collect as compiles finish and
+# are written once, when the build ends or fails.
 class CompileCommandsJsonDb < Plugin
-  
+
   # `Plugin` setup()
   def setup
-    @fullpath = File.join(PROJECT_BUILD_ARTIFACTS_ROOT, "compile_commands.json")
-    
-    @database = []
-    
-    if (File.exist?(@fullpath) && File.size(@fullpath) > 0)
-      @database = JSON.parse( File.read(@fullpath) )
-    end
-
-    @mutex = Mutex.new()
+    @file_wrapper = @ceedling[:file_wrapper]
+    @loginator    = @ceedling[:loginator]
+    @fullpath     = File.join( PROJECT_BUILD_ARTIFACTS_ROOT, 'compile_commands.json' )
+    # Hash: source filepath => entry, in the order sources were first compiled
+    @database     = load_database()
+    @changed      = false
+    @mutex        = Mutex.new
   end
 
   # `Plugin` build step hook
   def post_compile_execute(arg_hash)
+    entry = CompileCommandsJsonDb.entry_from( arg_hash )
+
+    @mutex.synchronize do
+      @database[entry['file']] = entry
+      @changed = true
+    end
+  end
+
+  # `Plugin` build step hooks -- a failed build still records what it compiled
+  def post_build(_timestamp_s)
+    write_database()
+  end
 
-    # Create new Entry from compilation
-    value = {
-      "directory" => Dir.pwd, # TODO: Replace with Ceedling project root when it exists
-      "file" => arg_hash[:source],
-      "command" => arg_hash[:shell_command],
-      "output" => arg_hash[:object]
-    }
+  def post_error(_timestamp_s)
+    write_database()
+  end
+
+  # The database entry for one compile.
+  #
+  # Commands use paths relative to Ceedling's working directory, so that is the entry's
+  # directory. A source compiled from an isolated copy names that throwaway copy in its
+  # command, so the command is rewritten to name the original source it stands for.
+  def self.entry_from(arg_hash)
+    source  = arg_hash[:source]
+    command = arg_hash[:shell_command]
+    copy    = arg_hash[:compile_source]
+    command = command.gsub( copy ) { source } if copy
 
+    return { 'directory' => Dir.pwd, 'file' => source, 'command' => command, 'output' => arg_hash[:object] }
+  end
+
+  ### Private
+
+  private
+
+  # A damaged database would otherwise fail every later build. Anything other than a list
+  # is discarded and the database starts fresh. A list keeps only its entry objects.
+  def load_database()
+    return {} unless @file_wrapper.exist?( @fullpath )
+
+    database = JSON.parse( @file_wrapper.read( @fullpath ) )
+    return discard_database( 'is not a list of compile entries' ) unless database.is_a?( Array )
+
+    return database.grep( Hash ).to_h { |entry| [entry['file'], entry] }
+  rescue JSON::ParserError
+    discard_database( 'is not valid JSON' )
+  end
+
+  def discard_database(reason)
+    @loginator.log( "#{@fullpath} #{reason} ➡️ Starting a new compile_commands.json.", Verbosity::COMPLAIN, LogLabels::NOTICE )
+    return {}
+  end
+
+  # Nothing is written when nothing compiled, which leaves an earlier build's file as it was
+  def write_database()
     @mutex.synchronize do
-      # Determine if we're updating an existing file description or adding a new one
-      index = @database.index {|h| h["file"] == arg_hash[:source]}
-      if index
-        @database[index] = value
-      else
-        @database << value
-      end
-
-      # Rewrite the compile_commands.json file
-      File.open(@fullpath,'w') {|f| f << JSON.pretty_generate(@database)}
+      return unless @changed
+
+      @file_wrapper.write( @fullpath, JSON.pretty_generate( @database.values ) )
+      @changed = false
     end
   end
+
 end

data/plugins/cppcheck/config/defaults.yml

@@ -8,10 +8,15 @@
 ---
 :cppcheck:
   :reports: []
+  # Register a build failure when findings match :fail_build_severities (implies an XML report)
+  :fail_build: false
+  :fail_build_severities:
+    - error
   :sarif_artifact_filename: null
   :text_artifact_filename: null
   :xml_artifact_filename: null
-  :xml_report_version: 3
+  # Version 2 is accepted by every Cppcheck. Version 3 requires a newer Cppcheck.
+  :xml_report_version: 2
   :template: null
   :html_title: null
   :platform: null

data/plugins/cppcheck/config/defaults_cppcheck.rb

@@ -5,11 +5,15 @@
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
+# `:optional => true` keeps Ceedling's project-wide tool validation from failing a
+# build merely because this plugin is enabled. Cppcheck is an external tool, so an
+# enabled plugin is not evidence the executable exists. The plugin validates it for
+# real at `cppcheck:` task time instead. See the :cppcheck_deps Rake task.
 DEFAULT_CPPCHECK_TOOL = {
   :executable => (ENV['CPPCHECK'].nil? ? FilePathUtils.os_executable_ext('cppcheck') : ENV['CPPCHECK'].split[0]).freeze,
   :name => 'default_cppcheck'.freeze,
   :stderr_redirect => StdErrRedirect::AUTO.freeze,
-  :optional => false.freeze,
+  :optional => true.freeze,
   :arguments => [
     '-I"${1}"'.freeze,
     '${2}'.freeze

data/plugins/cppcheck/cppcheck.rake

@@ -13,7 +13,13 @@ CLEAN.include(File.join(CPPCHECK_ARTIFACTS_PATH, '*'))
 
 CLOBBER.include(File.join(CPPCHECK_BUILD_PATH, '**/*'))
 
-task :cppcheck_deps => [:directories, CPPCHECK_BUILD_PATH, CPPCHECK_ARTIFACTS_PATH]
+# Every cppcheck: task depends on this. It is the one place the Cppcheck executable
+# is checked, so a build that never runs a cppcheck: task never requires Cppcheck to
+# be installed. `files:cppcheck` deliberately does not depend on it, since listing
+# suppression files needs no executable. See Cppcheck#validate_environment!.
+task :cppcheck_deps => [:directories, CPPCHECK_BUILD_PATH, CPPCHECK_ARTIFACTS_PATH] do
+  @ceedling[CPPCHECK_SYM].validate_environment!
+end
 task :cppcheck => ['cppcheck:all']
 
 namespace CPPCHECK_SYM do