ceedling 1.1.9 → 1.2.0

data/lib/ceedling/partials/partializer_config.rb

@@ -19,6 +19,10 @@ class PartializerConfig
   constructor :c_extractor_preprocessing
 
   # Macro names for all partial configuration macros
+  #
+  # Each macro has a directory-qualified `_AT` counterpart taking a leading directory
+  # parameter. Recognition requires an exact name match followed by an open parenthesis,
+  # so a name and its own `_AT` extension stay distinct however they are ordered here.
   MACRO_NAMES = [
     'TEST_PARTIAL_PUBLIC_MODULE',
     'TEST_PARTIAL_PRIVATE_MODULE',
@@ -30,7 +34,20 @@ class PartializerConfig
     'MOCK_PARTIAL_ALL_MODULE',
     'TEST_PARTIAL_CONFIG',
     'MOCK_PARTIAL_CONFIG',
-  ].freeze
+    'TEST_PARTIAL_PUBLIC_MODULE_AT',
+    'TEST_PARTIAL_PRIVATE_MODULE_AT',
+    'MOCK_PARTIAL_PUBLIC_MODULE_AT',
+    'MOCK_PARTIAL_PRIVATE_MODULE_AT',
+    'TEST_PARTIAL_MODULE_AT',
+    'MOCK_PARTIAL_MODULE_AT',
+    'TEST_PARTIAL_ALL_MODULE_AT',
+    'MOCK_PARTIAL_ALL_MODULE_AT',
+    'TEST_PARTIAL_CONFIG_AT',
+    'MOCK_PARTIAL_CONFIG_AT',
+  ].freeze unless const_defined?(:MACRO_NAMES, false)
+
+  # Suffix marking a macro that takes a leading directory parameter.
+  QUALIFIED_SUFFIX = '_AT' unless const_defined?(:QUALIFIED_SUFFIX, false)
 
   # Holds function-level extraction config for tests or mocks within a Partial.
   # type         -- :public, :private, or :accumulate (additions-driven); nil if unset
@@ -54,7 +71,7 @@ class PartializerConfig
       # DEDUCT: starts with all functions; zero subtractions is valid ("include everything")
       return true
     end
-  end
+  end unless const_defined?(:PartialFunctions, false)
 
   # Top-level Partial configuration for a single C module.
   Config = Struct.new(:module, :tests, :mocks, :header, :source, keyword_init: true) do
@@ -65,7 +82,7 @@ class PartializerConfig
                    source: Partials::ConfigFileInfo.new)
       super
     end
-  end
+  end unless const_defined?(:Config, false)
 
   # Extract partial configuration macros from a string.
   # Returns a hash of module_name => Config.
@@ -95,15 +112,20 @@ class PartializerConfig
       macro_name, params = @c_extractor_preprocessing.parse_macro_call(call_str)
       next if macro_name.nil?
 
-      if macro_name.end_with?('_CONFIG')
+      # A directory-qualified macro behaves exactly as its unqualified counterpart
+      # once its leading directory parameter is folded into the module key, so
+      # dispatch and validation below work from the unqualified name.
+      base_macro = _unqualified_name(macro_name)
+
+      if base_macro.end_with?('_CONFIG')
         config_calls << [macro_name, params]
         next
       end
 
-      mod = _strip_quotes(params[0])
+      mod = _module_key(macro_name, params)
       configs[mod] ||= Config.new(module: mod)
 
-      case macro_name
+      case base_macro
       when 'TEST_PARTIAL_PUBLIC_MODULE'
         _check_type_unset!(configs[mod].tests, mod, macro_name)
         configs[mod].tests.type = PUBLIC
@@ -133,7 +155,7 @@ class PartializerConfig
 
     # --- Pass 2: CONFIG macros ---
     config_calls.each do |macro_name, params|
-      mod = _strip_quotes(params[0])
+      mod = _module_key(macro_name, params)
       unless configs.key?(mod)
         raise CeedlingException.new(
           "#{macro_name} references module '#{mod}' but no corresponding MODULE Partial macro directive for that module was found"
@@ -142,7 +164,7 @@ class PartializerConfig
 
       target = macro_name.start_with?('TEST_') ? configs[mod].tests : configs[mod].mocks
 
-      params[1..].each do |raw|
+      _function_params(macro_name, params).each do |raw|
         name = _strip_quotes(raw)
         if name.start_with?('-')
           target.subtractions << name[1..]
@@ -214,4 +236,115 @@ class PartializerConfig
     str[1..-2]
   end
 
+  # True for a directory-qualified macro, which carries a leading directory parameter.
+  def _qualified?(macro_name)
+    macro_name.end_with?( QUALIFIED_SUFFIX )
+  end
+
+  def _unqualified_name(macro_name)
+    macro_name.delete_suffix( QUALIFIED_SUFFIX )
+  end
+
+  # One module identity, however the module was named. A qualified macro's directory
+  # and module parameters join here, so a module declared by one macro family pairs
+  # with a config macro from either, and two modules sharing a basename stay distinct.
+  def _module_key(macro_name, params)
+    unless _qualified?( macro_name )
+      _validate_module!( params[0], macro_name )
+      return params[0]
+    end
+
+    dir = params[0].nil? ? nil : params[0].strip
+
+    _validate_qualifier!( dir, macro_name )
+    _validate_module!( params[1], macro_name, dir: dir )
+
+    File.join( dir, params[1] )
+  end
+
+  # The module argument names one file's stem and nothing more. The preprocessor emits it
+  # verbatim into the generated filename, so anything Ceedling cannot reproduce in the
+  # filename it actually writes names a file that is never written -- surfacing much later
+  # as a missing include for a filename the author never typed.
+  def _validate_module!(mod, macro_name, dir: nil)
+    if mod.nil? || mod.empty?
+      requires = dir.nil? ? 'a module name' : 'a directory and a module name'
+      example  = dir.nil? ? 'module' : 'path/to/module, module'
+
+      raise CeedlingException.new(
+        "#{macro_name}() requires #{requires}, as in #{macro_name}(#{example})."
+      )
+    end
+
+    if mod.include?('"')
+      raise CeedlingException.new(
+        "#{macro_name}() module '#{mod}' must not be quoted. " \
+        "Write the module name as bare text, as in #{macro_name}(#{dir.nil? ? '' : dir + ', '}module)."
+      )
+    end
+
+    return unless mod.match?( %r{[\\/]} )
+
+    raise CeedlingException.new(
+      "#{macro_name}() module '#{mod}' must not contain a path. " \
+      "A module's directory belongs in its own argument, as in #{_qualified_example( macro_name, mod, dir )}. " \
+      "A path in the module argument lands the Partials prefix on the first directory " \
+      "instead of the filename, naming a file Ceedling never writes."
+    )
+  end
+
+  # The call that replaces one carrying a path in its module argument. Whatever directory
+  # the author wrote folds into the directory argument, leaving the module's own stem.
+  def _qualified_example(macro_name, mod, dir)
+    normalized = mod.tr( '\\', '/' )
+    qualifier  = File.dirname( normalized )
+    qualifier  = dir.nil? ? qualifier : File.join( dir, qualifier )
+
+    return "#{_qualified?( macro_name ) ? macro_name : macro_name + QUALIFIED_SUFFIX}" \
+           "(#{qualifier}, #{File.basename( normalized )})"
+  end
+
+  # Function names follow every leading parameter the macro declares.
+  def _function_params(macro_name, params)
+    _qualified?( macro_name ) ? params[2..] : params[1..]
+  end
+
+  # The preprocessor emits the directory verbatim into the generated #include, so a
+  # spelling Ceedling cannot reproduce as a real relative path names a file that is
+  # never written. Both rejections below are that mismatch, caught where the author
+  # can act on it rather than as a missing include much later.
+  def _validate_qualifier!(dir, macro_name)
+    if dir.nil? || dir.empty?
+      raise CeedlingException.new(
+        "#{macro_name}() requires a directory as its first argument, " \
+        "as in #{macro_name}(path/to/module, module)."
+      )
+    end
+
+    # A Partial is written below its test's own generated directory, while the emitted
+    # #include resolves against the including file. A climbing segment makes those two
+    # different places.
+    if dir.split( %r{[\\/]} ).include?( '..' )
+      raise CeedlingException.new(
+        "#{macro_name}() directory '#{dir}' must not contain '..'. " \
+        "A Partial is generated relative to the project root, so its directory cannot " \
+        "climb above it."
+      )
+    end
+
+    if dir.start_with?('"') || dir.end_with?('"')
+      raise CeedlingException.new(
+        "#{macro_name}() directory '#{dir}' must not be quoted. " \
+        "Write the path as bare text, as in #{macro_name}(path/to/module, module)."
+      )
+    end
+
+    if dir.start_with?('/', '\\') || dir.match?(/\A[A-Za-z]:[\/\\]/)
+      raise CeedlingException.new(
+        "#{macro_name}() directory '#{dir}' must be a relative path, not an absolute path. " \
+        "A Partial is generated relative to the project root."
+      )
+    end
+  end
+
 end

data/lib/ceedling/partials/partializer_helper.rb

@@ -12,9 +12,31 @@ require 'ceedling/partials/partials'
 require 'ceedling/c_extractor/c_extractor_declarations'
 require 'ceedling/c_extractor/c_extractor_constants'
 require 'strscan'
+require 'ceedling/constants'
+require 'ceedling/parsing_parcels'
+require 'ceedling/preprocess/c_preprocessor_conditionals'
 
 class PartializerHelper
 
+  # Content Partials relocates out of a module, so a conditional deciding whether it exists has
+  # to be decided rather than assumed.
+  #
+  # Deliberately narrow: a leading type-definition keyword, which is how a file-scope type
+  # definition opens. It does not reach an aggregate written directly on a variable
+  # (`static struct { int a; } slot;`) nor a declaration behind a storage class. Widening it far
+  # enough to catch those would also match an ordinary local declaration inside a function body,
+  # turning a resolvable module into a refused one -- and telling the two apart needs brace
+  # tracking this check does not do. Under-reaching leaves a shape unrefused; over-reaching
+  # breaks a working build.
+  RELOCATED_CONTENT = /^\s*(?:typedef|struct|union|enum)\b/ unless const_defined?(:RELOCATED_CONTENT, false)
+
+  # Any #include, however its target is spelled. Paired with the two PATTERNS filename forms, it
+  # isolates the computed case: a directive whose target matches neither a quoted nor an angled
+  # filename is naming a macro. PreprocessinatorIncludesHandler draws the same distinction for
+  # the same reason, against its own copy of this pattern.
+  ANY_INCLUDE_DIRECTIVE = /^\s*#\s*include\s+\S/ unless const_defined?(:ANY_INCLUDE_DIRECTIVE, false)
+
+
   include Partials
 
   constructor(
@@ -22,6 +44,7 @@ class PartializerHelper
     :c_extractor,
     :c_extractor_declarations,
     :file_path_utils,
+    :parsing_parcels,
     :loginator
   )
 
@@ -239,6 +262,67 @@ class PartializerHelper
 
     return decls
   end
+  # Refuses a module whose shape fallback preprocessing cannot resolve.
+  #
+  # Fallback never runs a compiler. It scans text and tracks a handful of conditional shapes
+  # against a defines list, so two shapes are knowably beyond it, and generating from either
+  # leaves a compiler or a linker to report something arcane several stages later. Refusing
+  # here -- before anything is written -- trades a confusing failure for a specific one.
+  #
+  # `files` maps a filepath to that file's text, so this method reads nothing itself and a spec
+  # can exercise every branch without a filesystem.
+  def validate_fallback_sufficiency(name:, module_name:, files:)
+    files.each do |filepath, text|
+      # One tracker per file, walked alongside the lines so every line is judged in the
+      # conditional state that actually encloses it.
+      tracker = CPreprocessorConditionals.new( [] )
+
+      @parsing_parcels.code_lines_with_num( text ) do |line, _line_num, end_line_num|
+        tracker.process_directive( line )
+
+        reason = _fallback_blocker( line, tracker )
+        next if reason.nil?
+
+        raise CeedlingException.new(
+          "Partial #{name}::#{module_name} \u23e9\ufe0f #{filepath}:#{end_line_num} #{reason} " \
+          "Partials for this module require directives-only preprocessing."
+        )
+      end
+    end
+  end
+
+  # What puts this line beyond fallback preprocessing, or nil when fallback resolves it.
+  #
+  # Only an active line can matter. A directive or definition that fallback already drops with
+  # the rest of an inactive block is no reason to refuse -- a real preprocessor drops it too.
+  def _fallback_blocker(line, tracker)
+    return nil unless tracker.active?
+
+    # An #include naming a macro needs real expansion to resolve. Fallback has none, so the
+    # include is lost outright and whatever it declared is missing from every list built from it,
+    # the dependencies the shared types header carries included.
+    if _computed_include?( line )
+      'computes an #include target that fallback preprocessing cannot resolve.'
+
+    # Content chosen by a condition the tracker kept without evaluating. Keeping such a block is
+    # the safe default for text the Partial ignores and the wrong answer for content it
+    # relocates: the types header would carry a type the build should not have, and no later
+    # stage can tell it was a guess.
+    elsif tracker.unevaluated? && _relocated_content?( line )
+      'sits behind a conditional expression that fallback preprocessing cannot evaluate.'
+    end
+  end
+
+  def _computed_include?(line)
+    line.match?( ANY_INCLUDE_DIRECTIVE ) &&
+      !line.match?( PATTERNS::USER_INCLUDE_DIRECTIVE_FILENAME ) &&
+      !line.match?( PATTERNS::SYSTEM_INCLUDE_DIRECTIVE_FILENAME )
+  end
+
+  def _relocated_content?(line)
+    line.match?( RELOCATED_CONTENT ) || line.match?( ANY_INCLUDE_DIRECTIVE )
+  end
+
 
   # For each function definition in funcs, find the matching function by name in the fully
   # preprocessed expansion file and replace the three signature-related fields with their
@@ -305,10 +389,12 @@ class PartializerHelper
     mod = config.module
 
     {TEST: config.tests, MOCK: config.mocks}.each do |label, pf|
+      # Report the first overlap and abort, as above -- an `each` would imply
+      # every offending function gets reported.
       overlap = Set.new(pf.additions) & Set.new(pf.subtractions)
-      overlap.each do |func_name|
+      unless overlap.empty?
         raise CeedlingException.new(
-          "#{name}: #{label} Partial configuration for module '#{mod}' ⏩️ Function '#{func_name}' should not be both added and subtracted"
+          "#{name}: #{label} Partial configuration for module '#{mod}' ⏩️ Function '#{overlap.first}' should not be both added and subtracted"
         )
       end
     end

data/lib/ceedling/partials/partializer_utils.rb

@@ -162,7 +162,7 @@ class PartializerUtils
   # @param preprocessed_filepath [String] Path to the preprocessed directives-only file
   # @return [Integer, nil] 1-indexed source line number, or nil if not found
   def locate_function_via_preprocessed(code_block:, filepath:, preprocessed_filepath:)
-    line_num = @code_finder.find_in_preprpocessed_file(preprocessed_filepath, code_block)
+    line_num = @code_finder.find_in_preprocessed_file(preprocessed_filepath, code_block)
     return line_num unless line_num.nil?
 
     msg = "Using fallback C function location search for #{filepath}"

data/lib/ceedling/partials/partials.rb

@@ -22,14 +22,14 @@ module Partials
     def initialize(filepath: nil, directives_only_filepath: nil, full_expansion_filepath: nil, includes: [])
       super
     end
-  end
+  end unless const_defined?(:ConfigFileInfo, false)
 
   # Data class representing a C partial to be generated
   Config = Struct.new(:module, :types, :header, :source, keyword_init: true) do
     def initialize(module:, types: [], header: ConfigFileInfo.new, source: ConfigFileInfo.new)
       super
     end
-  end
+  end unless const_defined?(:Config, false)
 
   # Data class representing a C function signature
   FunctionDeclaration = Struct.new(
@@ -44,7 +44,7 @@ module Partials
     def initialize(name: nil, signature: nil, source_filepath: nil, line_num: nil)
       super
     end
-  end
+  end unless const_defined?(:FunctionDeclaration, false)
 
   # Data class representing a C function with intentionally duplicated fields
   FunctionDefinition = Struct.new(
@@ -59,7 +59,7 @@ module Partials
     def initialize(name: nil, signature: nil, code_block: nil, source_filepath: nil, line_num: nil)
       super
     end
-  end
+  end unless const_defined?(:FunctionDefinition, false)
 
   def self.manufacture_function_declaration(line_num: nil, source_filepath: nil, name:, signature:)
     return FunctionDeclaration.new(

data/lib/ceedling/path_matcher.rb

@@ -0,0 +1,163 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'ceedling/exceptions'
+
+# Resolves a query -- a bare filename, a partial relative path, or a full/absolute
+# path -- against a collection of full filepaths, treating however much path the
+# query supplies as the thing to match, not merely a hint. A project may legitimately
+# contain two files with the same name in different directories; this class is the
+# one place that decides whether a given query is specific enough to mean exactly one
+# of them, so no caller has to fall back on guessing.
+class PathMatcher
+
+  # The single file `query` identifies in `collection`, or nil if none does.
+  # Raises a CeedlingException if `query` is insufficiently specific and more than
+  # one file in `collection` matches it -- a query is never allowed to silently pick
+  # a winner among genuinely ambiguous candidates.
+  def self.match(query, collection)
+    found = candidates(query, collection)
+
+    case found.length
+    when 0
+      nil
+    when 1
+      found.first
+    else
+      raise CeedlingException.new(ambiguous_message(query, found))
+    end
+  end
+
+  # As `.match`, but never raises. When more than one candidate matches, the winner
+  # is simply the first entry in `collection`'s own order -- callers hand this method
+  # a collection whose order already reflects real priority (e.g. a project's own
+  # `:paths` configuration order, which mirrors the order a compiler's own search
+  # paths would consult), so the earliest-listed candidate is the one a real build
+  # would actually find first.
+  #
+  # Returns [winner, others] -- `winner` is the resolved file or nil; `others` is
+  # every remaining candidate passed over, empty unless genuinely ambiguous, so a
+  # caller can decide whether anything is worth telling the user about.
+  def self.resolve(query, collection)
+    found = candidates(query, collection)
+    winner = found.first
+    others = found[1..] || []
+    return [winner, others]
+  end
+
+  # Every entry in `collection` that `query` could refer to.
+  def self.candidates(query, collection)
+    if absolute?(query)
+      target = File.expand_path(query)
+      return collection.select { |candidate| File.expand_path(candidate) == target }
+    end
+
+    query_segments = segments(query)
+    collection.select { |candidate| tail_matches?(query_segments, segments(candidate)) }
+  end
+
+  # Collapses a `..` segment in `query` against `anchor`, a directory path in the
+  # same representation as every other path this class handles (e.g. a test file's
+  # own `File.dirname`) -- one anchor segment is popped per leading `..`, so the
+  # result is an ordinary query ready for `.match`/`.resolve`/`.candidates` exactly as
+  # if it had been written that way to begin with. Only the leading `..` segments that
+  # climb above a relative anchor remain, naming a path outside it. A query with no `..` at
+  # all is returned completely untouched, so this is a no-op for the overwhelming
+  # majority of callers.
+  #
+  # `anchor: nil` means no file context exists to resolve against (e.g. a bare CLI
+  # task name, which names no file of its own) -- a `..` there can't mean anything,
+  # so it raises rather than silently mismatching or falling through to a confusing
+  # "not found" further down. `anchor: ''` is different: it means the query is
+  # already a complete, self-contained path that merely needs its own internal `..`
+  # collapsed, not prefixed onto anything else -- the shape GCC itself produces for a
+  # directory-relative quoted include, which is a full project-root-relative path
+  # left uncanonicalized.
+  #
+  # An absolute query (including a Windows drive letter) is returned unchanged --
+  # `candidates()`'s own `File.expand_path` comparison above already resolves `..`
+  # correctly for those, so reprocessing one here as anchor-relative would be wrong,
+  # not merely redundant.
+  def self.resolve_relative(query, anchor: nil)
+    return query if absolute?(query)
+
+    query_segments = segments(query)
+    return query unless query_segments.include?('..')
+
+    if anchor.nil?
+      raise CeedlingException.new(
+        "Relative path reference '..' in '#{query}' has no file context to resolve against here."
+      )
+    end
+
+    # segments() strips the empty string a leading "/" splits off, so a Unix
+    # absolute anchor's own "/"-ness has to be remembered separately here and
+    # reapplied below -- otherwise the result quietly turns into a relative-looking
+    # path carrying the same text minus its leading "/".
+    anchor_was_absolute = anchor.start_with?('/')
+    resolved = segments(anchor)
+
+    # A `..` beyond a relative anchor's own segments names a directory above it, as a
+    # project's paths outside its own root do (`../shared`), so it stays in the result.
+    # Nothing lies above an absolute anchor's root.
+    query_segments.each do |segment|
+      if segment != '..'
+        resolved << segment
+      elsif !resolved.empty? and resolved.last != '..'
+        resolved.pop
+      elsif anchor_was_absolute
+        raise CeedlingException.new("Relative path reference '..' in '#{query}' climbs above the filesystem root.")
+      else
+        resolved << '..'
+      end
+    end
+
+    joined = resolved.join('/')
+    anchor_was_absolute ? "/#{joined}" : joined
+  end
+
+  # Two filepaths correspond if the shorter one's path segments equal the longer
+  # one's own trailing segments, exactly, in order -- checked without regard for
+  # which side is shorter, since a query and a candidate can each be the more
+  # specific one depending on how each was discovered.
+  def self.correspond?(a, b)
+    segments_a = segments(a)
+    segments_b = segments(b)
+    shorter, longer = segments_a.length <= segments_b.length ? [segments_a, segments_b] : [segments_b, segments_a]
+    tail_matches?(shorter, longer)
+  end
+
+  # A Unix absolute path or one beginning with a Windows drive letter
+  def self.absolute?(path)
+    path.start_with?('/') || path.match?( /\A[A-Za-z]:[\\\/]/ )
+  end
+
+  ### Private ###
+
+  def self.segments(path)
+    path.split(/[\\\/]/).reject(&:empty?)
+  end
+  private_class_method :segments
+
+  # `query_segments` matches `candidate_segments` if the query's segments equal the
+  # candidate's own trailing segments exactly, in order -- a bare filename (one
+  # segment) matches any candidate ending in that filename; a deeper query only
+  # matches a candidate whose path actually ends the same way, not merely contains
+  # those segments somewhere.
+  def self.tail_matches?(query_segments, candidate_segments)
+    return false if query_segments.length > candidate_segments.length
+    candidate_segments.last(query_segments.length) == query_segments
+  end
+  private_class_method :tail_matches?
+
+  def self.ambiguous_message(query, candidates)
+    "Ambiguous file reference '#{query}' found. " \
+    "Include more trailing path to distinguish among: #{candidates.join(', ')}"
+  end
+  private_class_method :ambiguous_message
+
+end

data/lib/ceedling/path_mirror.rb

@@ -0,0 +1,73 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'ceedling/file_path_utils'
+
+# Answers the question build output asks when it wants to avoid same-basename
+# collisions: given a resolved file and the raw (still possibly glob/decorator-laden)
+# `:paths` entries a project configured for that file's category, what subdirectory
+# should this file's build artifact live in so its place in the source tree survives
+# into the build tree? A file directly inside a configured root needs no
+# subdirectory at all; a file nested beneath one carries that nesting forward.
+class PathMirror
+
+  # The directory portion of `filepath` below whichever `roots` entry is its
+  # longest (most specific) matching ancestor, or '' if no root contains it at all
+  # -- the safe fallback that leaves such a file's build placement flat.
+  def self.relative_subdir(filepath, roots)
+    relative_subdir_from_clean_roots(filepath, clean_roots(roots))
+  end
+
+  # Strips decorators and glob specifiers from each entry in `roots`, dropping any that
+  # end up empty. A caller mirroring many files against the same `roots` list -- a whole
+  # build's worth of sources against one project's configured paths, say -- can compute
+  # this once and feed the result to `relative_subdir_from_clean_roots` for every file,
+  # rather than every file's own call re-parsing the same still-decorated list from scratch.
+  def self.clean_roots(roots)
+    roots
+      .map { |root| FilePathUtils.no_decorators(root) }
+      .reject(&:empty?)
+  end
+
+  # As `relative_subdir`, but distinguishes a file no root contains (nil) from one sitting
+  # directly in a root (''). `relative_subdir` answers '' for both, which is the right
+  # fallback for placing build output but hides the difference from a caller deciding
+  # whether a path belongs to a configured tree at all.
+  def self.relative_subdir_if_rooted(filepath, roots)
+    clean    = clean_roots( roots )
+    file_dir = File.dirname( filepath )
+
+    return nil unless clean.any? { |root| file_dir == root || file_dir.start_with?( root + '/' ) }
+
+    return relative_subdir_from_clean_roots( filepath, clean )
+  end
+
+  # A path as lowercased segments, split on either separator. One spelling for every caller
+  # that matches trailing path segments rather than whole paths, so all of them agree on
+  # what a segment is and on case folding.
+  def self.path_segments(path)
+    path.downcase.split( %r{[\\/]} ).reject(&:empty?)
+  end
+
+  # As `relative_subdir`, but takes roots already reduced by `clean_roots` instead of
+  # raw, possibly glob/decorator-laden `:paths` entries.
+  def self.relative_subdir_from_clean_roots(filepath, clean_roots)
+    file_dir = File.dirname(filepath)
+
+    matching_roots = clean_roots.select do |root|
+      file_dir == root || file_dir.start_with?(root + '/')
+    end
+
+    return '' if matching_roots.empty?
+
+    best_root = matching_roots.max_by(&:length)
+    return '' if file_dir == best_root
+
+    file_dir[(best_root.length + 1)..]
+  end
+
+end

data/lib/ceedling/plugins/plugin.rb

@@ -20,7 +20,7 @@ class Plugin
   # Override to prevent exception handling from walking & stringifying the object variables.
   # Plugin's object variables are gigantic and produce a flood of output.
   def inspect
-    return this.class.name
+    return self.class.name
   end
 
   def setup; end