ceedling 1.1.9 → 1.2.0

data/lib/ceedling/dependencies/README.md

@@ -0,0 +1,69 @@
+# The Dependency-Tracking Subsystem
+
+This subsystem answers one question for any expensive step in either the test or release pipeline: has anything this target depends on changed since it last built successfully? It answers using content hashes rather than timestamps, so neither pipeline ever duplicates work that doesn't need to be done.
+
+It is not itself a pipeline with sequential stages the way `test_invoker`/`release_invoker` are. It's a service both pipelines call into, over and over, as a pure oracle. It never decides *when* to run a build step or *what order* steps happen in -- that's each pipeline's own stage list -- it only answers, at the moment a step is about to run, whether that build step actually needs to run.
+
+## The subsystem's shape
+
+Two classes matter most, and everything else exists to serve them:
+
+- **`Dependinator`** is the thin, Ceedling-specific facade every pipeline actually talks to. Every method it has except one is a one-line passthrough to `DependencyTracker` below; what it actually owns is the convention for where a given pipeline's cache file lives on disk, keyed by a symbolic identifier (`:test`, `:release`, or a plugin's own symbol), and the vocabulary translation at `flush` time from the tracker's own `prune:` parameter to the pipeline-facing `refresh_dependencies:` (see below). Its whole reason for existing is so pipeline code speaks in build verbs -- register this, ask if that's stale, mark this fresh -- and never has to know anything about cache file paths or tracker internals.
+- **`DependencyTracker`** is the actual engine, and it's deliberately generic and application-agnostic -- nothing in it knows what a "test" or a "release" is. It holds this run's registrations in memory and a loaded cache of the previous run's hashes, and its whole job is answering staleness queries against the two.
+
+`DependencyTracker`, in turn, composes six narrowly-scoped collaborators, each doing exactly one job and nothing else. Four serve every run:
+
+- `DependencyHasher` decides what makes two things count as "the same."
+- `DependencyPathNormalizer` decides what makes two spellings of a path count as "the same target."
+- `DependencyCacheStore` owns the on-disk cache file itself.
+- `GccDependencyParser` turns a compiler's own dependency output into something registerable.
+
+The other two, `DependencyDebugTree` and `DependencyDiffer`, serve only the troubleshooting aid described last. The sections below cover each in turn.
+
+## The `register` → `stale?` → `mark_fresh` idiom
+
+Every call site in both pipelines, regardless of what expensive thing it's guarding -- a preprocessor subprocess, a mock generation, a real compiler or linker invocation -- follows the same three-part shape. `register` tells the tracker what a target depends on: its antecedent files, and a `meta` value carrying anything else that should count toward staleness even though it isn't a file at all -- compile flags, `-D` defines, search paths, a toolchain version string, a coverage-on-or-off flag. An object file's target is the `.o` itself; its files are its source plus whatever headers it actually pulled in; its meta is the flags and defines that, if they change, should force a recompile even though the source file itself didn't change a byte.
+
+`register` is additive on purpose. Calling it more than once for the same target unions the file lists and merges the meta rather than replacing what came before, so a target's dependencies can be built up incrementally across more than one call site without either caller needing full knowledge of what the other already supplied. This is exactly what lets a step register its source file and known flags in one call, then separately register the dependencies its tool discovered, described next.
+
+### Dependencies discovered by the tool
+
+A step can't know every file it depends on until its tool has run, since the headers a C file reaches depend on its `#include`s, its defines, and its search paths. So a step registers the files its *previous* run discovered before asking whether it is stale, then registers what its new run discovered before marking it fresh. A file the previous run read that has since changed makes the step stale. A newly reached file is recorded once the step reruns.
+
+Two sources supply these files:
+
+- **A compile's `.d` file.** `-MMD -MF` writes gcc's own dependency output, in Makefile dialect, and `register_gcc_deps_file` (or `register_gcc_deps_string`, for content already in hand) parses it with `GccDependencyParser` and `register`s each target it describes with that target's dependency list. A single `.d` file can describe more than one target at once; it's a small manifest, not just one file's dependency list.
+- **A preprocessing run's line markers.** Two stages of the test pipeline preprocess each test file. Stage 4 runs it with `-fdirectives-only`, following its `#include`s, including headers a mock stand-in includes. Stage 11 fully expands it, reading every header it reaches. Each output's line markers name every file it entered. The pipeline registers the project files among them (`Preprocessinator#preprocessed_dependencies`), so editing a header the test reaches reruns the step. Such a header's macro can decide which mocks the test needs (stage 4) or which test cases it has (stage 11). System headers are left out. So are generated files below the build root, such as stand-ins and the mocks that replace them, which derive from project files and would only ever look changed.
+
+### Fresh, stale, and invalidated
+
+Once a target's inputs are registered, `stale?` is a pure question with no side effects, and `mark_fresh` is the write that happens after a real (re)build succeeds, recording new hashes for the target itself, its meta, and every currently-existing dependency. A dependency that's gone missing is simply left out of what gets recorded -- `stale?` already treats a missing dependency as stale on its own, so there's nothing to gain by recording anything else about it. `invalidate` is the explicit override: it drops a target's cache entry outright, so its next `stale?` answers true whatever the hashes say, while leaving this run's registrations alone.
+
+Some steps also produce a file beside their target that a later run trusts, such as a test's cached results or a test file's cached build directives. These are a target's `outputs`, registered after the step produces them and before `mark_fresh`, which records their hashes in the target's cache entry. A fresh target vouches for those outputs: `stale?` reads them from the cache entry, not this run's registrations, and treats the target as stale when any one is missing or altered. Damage to a trusted artifact then costs one rerun of the step that wrote it. Throughout, only a regular file counts as present. A directory named as a dependency, as a truncated `.d` file can do, reads as missing rather than being hashed.
+
+## What makes two things "the same"
+
+Two decisions make this whole scheme trustworthy rather than merely convenient, and both trade a little efficiency for a lot of certainty.
+
+`DependencyHasher` hashes a file's exact on-disk bytes, whitespace included, with no format-aware normalization at all. Whitespace isn't reliably cosmetic: it's syntactically meaningful in YAML, and it can even change whether a C macro's line continuation is recognized. The two ways a hash-based staleness check can be wrong aren't equally bad, either. Reporting something stale when it isn't just costs a wasted rebuild. Reporting it fresh when it isn't means shipping a build that silently doesn't reflect its own source -- exactly the failure this whole subsystem exists to prevent. The same hasher also canonicalizes a `meta` value before hashing it. Hash-key order and Symbol-vs-String keys never matter as a result, while array element order is still preserved, since the order of a flags or defines list can itself be meaningful.
+
+`DependencyPathNormalizer` solves a narrower but equally important problem. It resolves a path to its real, on-disk casing before that path is ever used as a cache key. A `#include "Foo.h"` written one way and a file that actually exists on disk as `foo.h` can then never be mistaken for two different targets -- nor can the same real file assembled from project configuration two different ways.
+
+## The on-disk cache
+
+Each pipeline identifier gets exactly one JSON cache file of its own, never shared with any other identifier. Test and release builds each get their own, and a plugin introducing a third pipeline would get a third, just by choosing its own identifier. This isn't incidental. It's what makes the pruning behavior described below safe at all -- a shared cache would mean a full test run's prune could silently evict every cached release entry along with it.
+
+Loading that cache is deliberately forgiving in one direction and strict in another. Any structural surprise in the file as a whole degrades the entire store to empty rather than raising. A missing cache, malformed cache, or incompatible version simply triggers a full rebuild instead of a hard failure. A single malformed *entry* within an otherwise-good file, similarly, only drops that one entry (i.e. requires a rebuild step). On every load, entries whose target has since been deleted from disk are pruned, automatically and unconditionally. This pruning is always safe, even during a partial run that only touches a handful of targets, because it only ever removes an entry once its target is confirmed gone from disk -- never merely unregistered this run. That's exactly what distinguishes it from the opt-in pruning described next. Persisting the cache back out is done via a write-to-temp-file-then-rename, so a reader can never observe a half-written cache.
+
+## `refresh_dependencies`: the special feature
+
+A normal `flush` just persists whatever this run registered and learned. Passing `refresh_dependencies: true` additionally drops every cache entry whose target was *not* registered at some point during this run, before persisting. In effect, this treats this run's registrations as the complete, authoritative set of everything that should still have a cache entry at all. That's exactly correct for a run that's guaranteed to have touched every target that matters, such as a full `test:all` or a full release build. It's exactly wrong for anything less than that. A single test file, `test:pattern`, `test:path`, or the ad hoc single-file `release:compile:`/`release:assemble:` tasks would each, if this were set true, silently wipe out cache entries for every target the partial run simply didn't happen to touch -- forcing an unnecessary full rebuild on the next real run. Both pipelines are careful to set it only when they can actually make that guarantee.
+
+## Debugging a stale/fresh surprise
+
+Separately from anything either pipeline does on a normal run, this subsystem carries an opt-in troubleshooting aid for a human trying to understand *why* something did or didn't rebuild. Setting the `CEEDLING_DEP_DEBUG` developer-only environment variable turns on a tiered snapshot mechanism, off by default. `CEEDLING_DEP_DEBUG=meta` captures just the canonicalized meta a target was judged against. `CEEDLING_DEP_DEBUG=full` additionally captures the actual content of the target and its dependencies at the moment they were last marked fresh. Both tiers write into a human-readable file tree alongside the cache, capped in size per file so one enormous generated header can't silently balloon that tree.
+
+Those snapshots exist to back one thing: `DependencyTracker#diagnose`, an always-available "explain yourself" query that reports which of a target's self-hash, meta-hash, dependency hashes, or output hashes changed. `diagnose` runs regardless of whether `CEEDLING_DEP_DEBUG` is set. Without a snapshot to compare against, it can still report *that* a given hash changed, but not *what* changed. With one available, from a run where the matching tier was active, it produces an actual before/after diff instead.
+
+`DependencyDebugTree` writes and reads those snapshots, and `DependencyDiffer` turns a snapshot and the live content into that diff. The differ uses the `diff-lcs` gem, a development-only dependency that an installed release gem does not require. Without it, the explanation degrades to a plain before/after dump rather than failing.
+

data/lib/ceedling/dependencies/dependency_cache_store.rb

@@ -0,0 +1,160 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'json'
+require 'ceedling/constants'
+require 'ceedling/dependencies/dependency_hasher'
+
+# Loads, validates, and persists DependencyTracker's on-disk cache file.
+#
+# The persisted shape is a single JSON object:
+#   {
+#     "schema_version": 1,
+#     "hash_algorithm": "sha256",
+#     "entries": {
+#       "<target path>": {
+#         "self_hash": "<hex digest>",
+#         "meta_hash": "<hex digest>" | null,
+#         "deps": { "<dep path>": "<hex digest>", ... },
+#         "outputs": { "<output path>": "<hex digest>", ... }   # only when present
+#       },
+#       ...
+#     }
+#   }
+#
+# Loading never raises: a cache file that is missing, unreadable, malformed
+# JSON, structurally wrong, schema-mismatched, or hand-edited into garbage is
+# all treated as "cache absent" (an empty store, i.e. a full rebuild) --
+# reading a stale/foreign/corrupt cache file is a routine, expected outcome
+# (another Ceedling version, an interrupted write, manual editing), not an
+# exceptional one, and misinterpreting an ambiguous cache as valid risks
+# answering `stale?` *incorrectly* rather than merely rebuilding more than
+# strictly necessary.
+#
+# A single corrupt *entry* does not invalidate the whole cache, though: only
+# that one entry is dropped (that one target is simply treated as stale),
+# since a schema mismatch calls every entry's shape into question but one
+# malformed entry very likely reflects isolated damage.
+#
+# Entry pruning: an entry whose target no longer exists on disk (a deleted
+# or renamed source/object file) is dropped silently on load -- this is
+# routine build-tree drift, not corruption, so unlike a malformed entry it
+# is not logged as a warning. This is a conservative, always-safe prune:
+# it only ever removes entries for targets that are provably gone, so it
+# cannot misfire under a partial build (`ceedling test:some_file.c`) the
+# way pruning based on "was this target registered this run" could -- a
+# target simply not touched by a partial build still exists on disk and so
+# is never pruned here. Broader pruning ("no longer part of the build, but
+# still present on disk") is deliberately not attempted at load time, since
+# that requires knowing the current build's full target manifest -- see
+# DependencyTracker#flush's `prune:` option, which the *caller* opts into
+# only when it knows a run's registrations were comprehensive.
+class DependencyCacheStore
+
+  CACHE_SCHEMA_VERSION = 1 unless const_defined?(:CACHE_SCHEMA_VERSION, false)
+
+  constructor :file_wrapper, :loginator
+
+  # Loads and validates `store_path`, returning
+  # `{ 'schema_version', 'hash_algorithm', 'entries', 'pruned' }`. `entries`
+  # is always a Hash of target path => entry Hash, with any invalid or
+  # deleted-target entries dropped. `pruned` is the list of target paths
+  # dropped this load (malformed or deleted) -- callers use it to also clean
+  # up any DependencyDebugTree data for those same targets, so the debug
+  # tree doesn't outlive the cache entries it exists to explain.
+  def load(store_path)
+    return empty_store unless @file_wrapper.exist?( store_path )
+
+    raw = @file_wrapper.read( store_path )
+    parsed = JSON.parse( raw )
+
+    return degrade( store_path, "does not contain a JSON object" ) unless parsed.is_a?( Hash )
+    return degrade( store_path, "has an incompatible or missing schema_version" ) unless parsed['schema_version'] == CACHE_SCHEMA_VERSION
+    return degrade( store_path, "has an incompatible or missing hash_algorithm" ) unless parsed['hash_algorithm'] == DependencyHasher::HASH_ALGORITHM
+    return degrade( store_path, "is missing its entries object" ) unless parsed['entries'].is_a?( Hash )
+
+    valid_entries = {}
+    pruned = []
+    parsed['entries'].each do |target, entry|
+      if !valid_entry?( entry )
+        @loginator.log(
+          "Dependency cache entry for '#{target}' in #{store_path} is malformed -- dropping just that entry.",
+          Verbosity::COMPLAIN, LogLabels::WARNING
+        )
+        pruned << target
+      elsif !@file_wrapper.exist?( target )
+        @loginator.log(
+          "Dependency cache entry for '#{target}' in #{store_path} no longer exists on disk -- pruning it.",
+          Verbosity::OBNOXIOUS, LogLabels::AUTO
+        )
+        pruned << target
+      else
+        valid_entries[target] = entry
+      end
+    end
+
+    {
+      'schema_version' => CACHE_SCHEMA_VERSION,
+      'hash_algorithm' => DependencyHasher::HASH_ALGORITHM,
+      'entries'        => valid_entries,
+      'pruned'         => pruned
+    }
+
+  rescue JSON::ParserError => e
+    degrade( store_path, "is not valid JSON (#{e.message})" )
+  end
+
+  # Persists `entries` (a Hash of target path => entry Hash) to `store_path`.
+  # Writes to a temp file in the same directory and renames into place so a
+  # reader never observes a partially-written cache file, even if two
+  # Ceedling invocations somehow raced on the same project.
+  def persist(store_path, entries)
+    @file_wrapper.mkdir( @file_wrapper.dirname( store_path ) )
+
+    payload = {
+      'schema_version' => CACHE_SCHEMA_VERSION,
+      'hash_algorithm' => DependencyHasher::HASH_ALGORITHM,
+      'entries'        => entries
+    }
+
+    tmp_path = "#{store_path}.tmp.#{Process.pid}"
+    @file_wrapper.write( tmp_path, JSON.pretty_generate( payload ) )
+    @file_wrapper.mv( tmp_path, store_path )
+  end
+
+  ### Private ###
+  private
+
+  def empty_store
+    { 'schema_version' => CACHE_SCHEMA_VERSION, 'hash_algorithm' => DependencyHasher::HASH_ALGORITHM, 'entries' => {}, 'pruned' => [] }
+  end
+
+  def degrade(store_path, reason)
+    @loginator.log(
+      "Dependency cache #{store_path} #{reason} -- treating it as absent (full rebuild for tracked targets).",
+      Verbosity::COMPLAIN, LogLabels::WARNING
+    )
+    empty_store
+  end
+
+  def valid_entry?(entry)
+    return false unless entry.is_a?( Hash )
+    return false unless valid_digest?( entry['self_hash'] )
+    return false unless entry['meta_hash'].nil? || valid_digest?( entry['meta_hash'] )
+    return false unless valid_digest_map?( entry['deps'] )
+    entry['outputs'].nil? || valid_digest_map?( entry['outputs'] )
+  end
+
+  def valid_digest_map?(map)
+    map.is_a?( Hash ) && map.all? { |path, digest| path.is_a?( String ) && valid_digest?( digest ) }
+  end
+
+  def valid_digest?(value)
+    value.is_a?( String ) && value.match?( DependencyHasher::DIGEST_RE )
+  end
+
+end

data/lib/ceedling/dependencies/dependency_debug_tree.rb

@@ -0,0 +1,129 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'yaml'
+require 'time'
+require 'ceedling/exceptions'
+
+# Manages DependencyTracker's on-disk debug tree -- a directory, separate
+# from the single hash-only JSON cache file, that exists only when a debug
+# tier is active (or has been at some point) and mirrors every monitored
+# real path (targets and dependencies alike) as its own nested directory,
+# keyed purely by that path:
+#
+#   <debug_root>/Users/mkarlesky/project/build/test/out/foo.o/
+#     snapshot.yml    -- captured at mark_fresh time (see #write_snapshot)
+#     diagnosis.yml   -- written by DependencyTracker#diagnose, target paths only
+#
+# A path is mirrored by stripping any leading slash and any Windows drive
+# letter's colon, so it reconstructs as a relative directory tree under
+# `debug_root` without colliding with `debug_root`'s own path syntax.
+#
+# YAML (not JSON) specifically because this tree exists for a human to
+# directly browse and read, not for the tracker to parse back at speed --
+# block scalars make multi-line diffs and captured content vastly more
+# readable than escaped JSON strings would.
+class DependencyDebugTree
+
+  SNAPSHOT_FILENAME  = 'snapshot.yml'  unless const_defined?(:SNAPSHOT_FILENAME, false)
+  DIAGNOSIS_FILENAME = 'diagnosis.yml' unless const_defined?(:DIAGNOSIS_FILENAME, false)
+
+  constructor :file_wrapper, :yaml_wrapper
+
+  # Writes a snapshot for `path` (a target or a dependency) under
+  # `debug_root`. `hash` is always recorded; `meta` (target-only; a
+  # dependency has no meta of its own) and content-capture keywords
+  # (`content:`, or `truncated:`/`size:` when content exceeded the capture
+  # size cap -- see DependencyTracker::DEBUG_FULL_CAPTURE_SIZE_CAP) are
+  # included only when the caller supplies them, so a :meta-tier snapshot
+  # simply omits content entirely rather than recording it as empty/nil.
+  def write_snapshot(debug_root, path, hash:, meta: nil, content: nil, truncated: false, size: nil)
+    snapshot = { 'path' => path, 'captured_at' => timestamp(), 'hash' => hash }
+    snapshot['meta'] = meta unless meta.nil?
+    snapshot['content'] = content unless content.nil?
+    if truncated
+      snapshot['truncated'] = true
+      snapshot['size'] = size
+    end
+
+    write_yaml( File.join( path_dir( debug_root, path ), SNAPSHOT_FILENAME ), snapshot )
+  end
+
+  # Reads back a previously-written snapshot for `path`, or nil if none
+  # exists, is unreadable, or fails to parse -- callers treat a nil
+  # snapshot as "no baseline available to diff against," never as an error.
+  def read_snapshot(debug_root, path)
+    read_yaml( File.join( path_dir( debug_root, path ), SNAPSHOT_FILENAME ) )
+  end
+
+  # Writes a target's diagnosis (see DependencyTracker#diagnose) under
+  # `debug_root`.
+  def write_diagnosis(debug_root, target, diagnosis)
+    write_yaml( File.join( path_dir( debug_root, target ), DIAGNOSIS_FILENAME ), diagnosis )
+  end
+
+  # Removes `path`'s entire debug directory (snapshot, diagnosis, everything
+  # under it), if any exists. Called when the corresponding cache entry is
+  # pruned (either DependencyCacheStore's load-time existence pruning, or
+  # DependencyTracker#flush(prune: true)), so the debug tree doesn't outlive
+  # the cache data it exists to explain. Safe to call for a path that was
+  # never captured at all.
+  def prune(debug_root, path)
+    dir = path_dir( debug_root, path )
+    @file_wrapper.rm_rf( dir ) if @file_wrapper.exist?( dir )
+  end
+
+  # The exact file path `write_snapshot`/`read_snapshot` use for `path`, and
+  # likewise for `write_diagnosis`. Public so callers that need to point a
+  # human at the right file (or verify one exists, e.g. in specs) use the
+  # same path-mirroring logic this class does internally, rather than an
+  # independent reimplementation that can silently drift out of sync with
+  # it -- notably around the Windows drive-letter handling in `mirror`.
+  def snapshot_file(debug_root, path)
+    File.join( path_dir( debug_root, path ), SNAPSHOT_FILENAME )
+  end
+
+  def diagnosis_file(debug_root, target)
+    File.join( path_dir( debug_root, target ), DIAGNOSIS_FILENAME )
+  end
+
+  ### Private ###
+  private
+
+  def path_dir(debug_root, path)
+    File.join( debug_root, mirror( path ) )
+  end
+
+  def mirror(path)
+    normalized = path.to_s.tr( '\\', '/' )
+    normalized = normalized.sub( /\A([A-Za-z]):/, '\1' ) # C:/foo -> C/foo (Windows drive letter)
+    normalized.sub( /\A\/+/, '' )                         # /foo/bar -> foo/bar (relative under debug_root)
+  end
+
+  def timestamp
+    Time.now.utc.iso8601
+  end
+
+  def write_yaml(filepath, structure)
+    @file_wrapper.mkdir( @file_wrapper.dirname( filepath ) )
+    @file_wrapper.write( filepath, YAML.dump( structure ) )
+  end
+
+  # Reads and parses `filepath` via the injected FileWrapper (all disk I/O
+  # stays mockable) and YamlWrapper#load_string (the same Psych-version-safe
+  # parsing used for the main config/cache YAML elsewhere in Ceedling) --
+  # but degrades to nil rather than raising, since a missing, unreadable, or
+  # corrupt debug artifact is exactly the kind of "nothing to work with"
+  # condition callers already handle gracefully (no snapshot captured yet).
+  def read_yaml(filepath)
+    return nil unless @file_wrapper.exist?( filepath )
+    @yaml_wrapper.load_string( @file_wrapper.read( filepath ), source_label: filepath )
+  rescue YamlLoadException
+    nil
+  end
+
+end

data/lib/ceedling/dependencies/dependency_differ.rb

@@ -0,0 +1,127 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Builds human-readable explanations of *why* a hash comparison failed --
+# the content half for `DependencyTracker#diagnose`. Pure: works entirely on
+# strings and Hashes handed to it, no filesystem access of its own.
+#
+# `diff-lcs` is a soft dependency, declared in the Gemfile for development
+# but deliberately not in ceedling.gemspec (see the Gemfile comment) -- so
+# it is not a hard requirement for an installed release gem. When it is not
+# available, content diffing degrades to a plain before/after dump rather
+# than raising or silently producing nothing.
+class DependencyDiffer
+
+  unless const_defined?(:DIFF_LCS_AVAILABLE, false)
+    begin
+      require 'diff/lcs'
+      DIFF_LCS_AVAILABLE = true
+    rescue LoadError
+      DIFF_LCS_AVAILABLE = false
+    end
+  end
+
+  # First N bytes sniffed for a null byte to decide whether content is text
+  # or binary -- a line-oriented diff on binary content is not "readable."
+  BINARY_SNIFF_BYTES = 8_000 unless const_defined?(:BINARY_SNIFF_BYTES, false)
+
+  # Explains why a piece of content changed, given `old_snapshot` (the Hash
+  # loaded from a previously-written DependencyDebugTree snapshot, or nil if
+  # none exists) and `new_content` (the live content read from disk right
+  # now, or nil if the file no longer exists). Returns a Hash with one of:
+  # - `{ 'reason' => ... }` when no diff can be produced (no snapshot ever
+  #   captured, snapshot was truncated, snapshot didn't include content
+  #   because the debug tier at capture time was only :meta, or the file is
+  #   now missing).
+  # - `{ 'summary' => ... }` for binary content -- byte sizes, not a diff.
+  # - `{ 'diff' => ... }` for text content -- a readable line-level diff.
+  def diff_content(old_snapshot, new_content)
+    return { 'reason' => 'no prior snapshot was captured for this path (enable CEEDLING_DEP_DEBUG=full and rebuild once to establish a baseline)' } if old_snapshot.nil?
+    return { 'reason' => "prior snapshot's content was truncated (file exceeded the capture size cap; see 'size' in its snapshot.yml)" } if old_snapshot['truncated']
+    return { 'reason' => "prior snapshot did not include content (captured at debug tier :meta, not :full)" } if old_snapshot['content'].nil?
+    return { 'reason' => 'file no longer exists' } if new_content.nil?
+
+    old_content = old_snapshot['content']
+
+    if binary?( old_content ) || binary?( new_content )
+      return { 'summary' => "binary content differs (previously #{old_content.bytesize} bytes, now #{new_content.bytesize} bytes)" }
+    end
+
+    { 'diff' => text_diff( old_content, new_content ) }
+  end
+
+  # Explains why canonicalized meta changed, given `old_meta` (Hash loaded
+  # from a snapshot, or nil) and `new_meta` (the live, currently-registered,
+  # canonicalized meta). Returns added/removed/changed_keys breakdowns, or a
+  # `'reason'` Hash if no prior meta snapshot exists to compare against.
+  #
+  # Note the result key is `changed_keys`, not `changed` -- callers (see
+  # DependencyTracker#diagnose_meta) wrap this in their own `'changed'`
+  # boolean flag, and a flat merge of the two would otherwise silently
+  # clobber that boolean with this Hash.
+  def diff_meta(old_meta, new_meta)
+    return { 'reason' => 'no prior meta snapshot was captured for this target (enable CEEDLING_DEP_DEBUG=meta or :full and rebuild once to establish a baseline)' } if old_meta.nil?
+
+    old_meta ||= {}
+    new_meta ||= {}
+
+    added   = new_meta.keys - old_meta.keys
+    removed = old_meta.keys - new_meta.keys
+    changed = (old_meta.keys & new_meta.keys).select { |key| old_meta[key] != new_meta[key] }
+
+    {
+      'added'        => added.each_with_object( {} )   { |key, h| h[key] = new_meta[key] },
+      'removed'      => removed.each_with_object( {} ) { |key, h| h[key] = old_meta[key] },
+      'changed_keys' => changed.each_with_object( {} ) { |key, h| h[key] = { 'old' => old_meta[key], 'new' => new_meta[key] } }
+    }
+  end
+
+  ### Private ###
+  private
+
+  def binary?(content)
+    return false if content.nil?
+    content.byteslice( 0, BINARY_SNIFF_BYTES ).include?( "\0" )
+  end
+
+  def text_diff(old_content, new_content)
+    old_lines = old_content.lines
+    new_lines = new_content.lines
+
+    return diff_lcs_text( old_lines, new_lines ) if DIFF_LCS_AVAILABLE
+    fallback_text( old_lines, new_lines )
+  end
+
+  # Readable, line-numbered diff via diff-lcs. Not a byte-for-byte unified
+  # diff -- a terser, more directly readable "what actually changed" list,
+  # which is what this is for (troubleshooting, not patch generation).
+  def diff_lcs_text(old_lines, new_lines)
+    lines = []
+
+    Diff::LCS.sdiff( old_lines, new_lines ).each do |change|
+      case change.action
+      when '-'
+        lines << "- [#{change.old_position + 1}] #{change.old_element.chomp}"
+      when '+'
+        lines << "+ [#{change.new_position + 1}] #{change.new_element.chomp}"
+      when '!'
+        lines << "- [#{change.old_position + 1}] #{change.old_element.chomp}"
+        lines << "+ [#{change.new_position + 1}] #{change.new_element.chomp}"
+      end
+      # '=' (unchanged) lines are omitted -- only what actually changed matters here.
+    end
+
+    lines.empty? ? '(content hash differs, but no line-level difference found -- likely a line-ending or encoding change)' : lines.join( "\n" )
+  end
+
+  def fallback_text(old_lines, new_lines)
+    "diff-lcs is not installed -- showing full before/after content instead of a line diff\n" \
+    "--- before ---\n#{old_lines.join}\n" \
+    "--- after ---\n#{new_lines.join}"
+  end
+
+end

data/lib/ceedling/dependencies/dependency_hasher.rb

@@ -0,0 +1,94 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'digest'
+# `Digest::SHA256` is lazily autoloaded from `digest/sha2` on first reference.
+# Every call site below runs inside parallel worker threads (DependencyTracker
+# is exercised from Batchinator-driven thread pools throughout the pipeline);
+# if two threads race to be the first to touch `Digest::SHA256`, Ruby's C
+# extension init for the digest classes can raise "Digest::Base cannot be
+# directly inherited in Ruby". Loading it here, once, single-threaded, at
+# require time settles the class before any worker thread can race on it.
+require 'digest/sha2'
+require 'json'
+
+# Computes the two kinds of hashes DependencyTracker persists per target:
+# - A content hash for a single file (the target itself, or one of its
+#   dependencies), read via the injected FileWrapper so this class never
+#   touches the filesystem directly and is fully mockable in specs.
+# - A hash of an arbitrary, caller-supplied `meta` value (compilation flags,
+#   defines, include paths, toolchain version, status booleans, etc.) after
+#   canonicalizing it to a stable, order-independent representation so that
+#   two logically-identical meta hashes (built in a different key/element
+#   order) always hash the same.
+class DependencyHasher
+
+  HASH_ALGORITHM = 'sha256'.freeze unless const_defined?(:HASH_ALGORITHM, false)
+  DIGEST_RE = /\A[0-9a-f]{64}\z/.freeze unless const_defined?(:DIGEST_RE, false)
+
+  constructor :file_wrapper
+
+  # SHA-256 hex digest of a file's exact on-disk bytes.
+  #
+  # Read via `read_binary` rather than `read`: Ruby's default text-mode read
+  # silently translates CRLF to LF on Windows but leaves it untouched on
+  # Unix-like platforms, so the same file's bytes -- text or binary -- would
+  # otherwise hash differently purely depending on which OS is running
+  # Ceedling. Reading raw bytes on every platform keeps the hash a function of
+  # the file's actual content alone.
+  #
+  # This intentionally hashes every file byte-for-byte, whitespace included,
+  # rather than attempting any whitespace- or format-insensitive normalization
+  # (e.g. collapsing indentation, trimming trailing spaces). That's a
+  # deliberate choice, not an oversight:
+  # - Whitespace is not reliably cosmetic. In C, the exact whitespace inside a
+  #   string or character literal is program content, not formatting -- and
+  #   trailing whitespace after a macro's line-continuing backslash can change
+  #   whether the continuation is even recognized. In YAML, indentation *is*
+  #   the syntax -- two documents differing only in whitespace can parse to
+  #   different data entirely.
+  # - Deciding which whitespace differences are safe to ignore requires
+  #   understanding the semantics of the specific file's language -- i.e. a
+  #   real parser for every format this hasher might ever see -- not a text
+  #   transform. A byte hash can't be fooled by a parsing bug; a "smart"
+  #   normalization can silently mask a real change.
+  # - The two ways this hash can be wrong aren't equally bad: reporting a
+  #   target stale when it isn't just costs a wasted rebuild, but reporting it
+  #   fresh when it isn't means shipping against a build that silently doesn't
+  #   reflect the source -- exactly the failure this class exists to prevent.
+  #   Any normalization narrows the margin between those two outcomes in
+  #   exchange for skipping some rebuilds; that trade isn't worth it here.
+  def hash_of_file(path)
+    Digest::SHA256.hexdigest( @file_wrapper.read_binary( path ) )
+  end
+
+  # SHA-256 hex digest of a canonicalized `meta` value, or nil for nil/empty
+  # meta -- distinguishing "no meta was supplied" from "meta hashed to some
+  # value" matters to callers deciding whether to store a `meta_hash` at all.
+  def hash_of_meta(meta)
+    return nil if meta.nil? || (meta.respond_to?(:empty?) && meta.empty?)
+    Digest::SHA256.hexdigest( JSON.generate( canonicalize( meta ) ) )
+  end
+
+  # Recursively normalizes a value for stable hashing:
+  # - Hash keys are stringified and sorted, so key order and Symbol-vs-String
+  #   keys never change the resulting hash.
+  # - Arrays are canonicalized element-wise, preserving order (element order
+  #   in a flags/defines/paths list is meaningful, unlike hash key order).
+  # - Everything else (String, Integer, true/false/nil, ...) passes through.
+  def canonicalize(obj)
+    case obj
+    when Hash
+      obj.map { |k, v| [k.to_s, canonicalize( v )] }.sort_by { |k, _v| k }.to_h
+    when Array
+      obj.map { |v| canonicalize( v ) }
+    else
+      obj
+    end
+  end
+
+end