ceedling 1.0.1 → 1.1.0

data/lib/ceedling/partials/partializer_helper.rb

@@ -0,0 +1,344 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'set'
+require 'ceedling/exceptions'
+require 'ceedling/array_patches' # Redundant `require` to ensure patching in test cases
+require 'ceedling/partials/partials'
+require 'ceedling/c_extractor/c_extractor_declarations'
+require 'ceedling/c_extractor/c_extractor_constants'
+require 'strscan'
+
+class PartializerHelper
+
+  include Partials
+
+  constructor(
+    :partializer_utils,
+    :c_extractor,
+    :c_extractor_declarations,
+    :file_path_utils,
+    :loginator
+  )
+
+  def setup()
+    # Aliases
+    @utils = @partializer_utils
+    @declaration_extractor = @c_extractor_declarations
+  end
+
+  # 1. Filter functions by visibility (:private | :public | :deduct) or seed an empty list (:accumulate)
+  # 2. Transform functions to appropriate container (:impl | :interface) → `FunctionDefinition[]` or `FunctionDeclaration[]`
+  def filter_and_transform_funcs(funcs, visibility, output_type)
+    # DEDUCT starts with all functions regardless of visibility; subtractions are applied later by the caller
+    if visibility == DEDUCT
+      return funcs.filter_map { |func| @utils.transform_function(func, func.signature_stripped, output_type) }
+    end
+
+    # ACCUMULATE starts with an empty list; the caller then injects explicitly named additions
+    return [] unless [PRIVATE, PUBLIC].include?(visibility)
+
+    # PUBLIC or PRIVATE: filter to matching visibility, then transform
+    funcs.filter_map do |func|
+      next unless @utils.matches_visibility?(func.decorators, visibility)
+
+      @utils.transform_function(func, func.signature_stripped, output_type)
+    end
+  end
+
+  # Find a function by name, searching primary_funcs first then secondary_funcs.
+  # Returns the first match transformed for the given output_type, or nil if not found.
+  # For :impl output_type, pass secondary_funcs: [] — declarations have no code_block.
+  def find_and_transform_func(name:, primary_funcs:, secondary_funcs:, output_type:)
+    func = primary_funcs.find { |f| f.name == name }
+    return @utils.transform_function(func, func.signature_stripped, output_type) if func
+
+    func = secondary_funcs.find { |f| f.name == name }
+    return @utils.transform_function(func, func.signature_stripped, output_type) if func
+
+    nil
+  end
+
+  # Return funcs with any function whose name is in names removed.
+  def subtract_funcs(funcs:, names:)
+    return funcs if names.empty?
+    name_set = Set.new(names)
+    funcs.reject { |f| name_set.include?(f.name) }
+  end
+
+  # Associate each FunctionDefinition with its line number in the original source file.
+  #
+  # C source files are run through the GCC preprocessor before extraction. The
+  # resulting fully expanded output file retains GCC line markers of the form:
+  #   # <linenum> "<filename>" [flags]
+  # These markers preserve the correspondence between preprocessed text and the
+  # original source lines, even after macro expansion has altered the content.
+  #
+  # For each function in funcs, this method searches the preprocessor expansion
+  # for an exact match of the function's `code_block`` text. When a match is
+  # found, the GCC line marker immediately preceding the match is used to
+  # calculate the 1-indexed source line number. This line number is then written 
+  # back into the `FunctionDefinition` struct alongside the originating filepath.
+  #
+  # `FunctionDefinition` entries whose `code_block` cannot be located in the
+  # preprocessor output are skipped -- `line_num` fields remain unset.
+  # 
+  # `source_filepath` is always updated.
+  #
+  # @param name [String]Name of the containing test, used to construct the path to 
+  # the preprocessor expansion file for that test context.
+  # @param funcs [Array<FunctionDefinition>] Function definitions whose source 
+  # locations are to be resolved. Matched entries are mutated in place.
+  # @param filepath [String] Path to the original C source file that was 
+  # preprocessed, written into each matched FunctionDefinition as source_filepath.
+  # @param fallback [bool] Whether to immediately use simple source file scanning
+  # instead of preprocessed output (because preprocessed output is not available)
+  def associate_function_line_numbers(name:, funcs:, filepath:, fallback:)
+    # File path of directives-only preprocessor output
+    preprocessed_filepath = @file_path_utils.form_preprocessed_file_raw_directives_only_filepath( filepath, name )
+
+    @utils.stamp_source_filepaths( funcs, filepath )
+
+    if fallback
+      msg = "Using fallback C function location search for #{filepath}"
+      @loginator.log( msg, Verbosity::OBNOXIOUS, LogLabels::WARNING )
+
+      funcs.each do |func|
+        func.line_num = @utils.locate_function_in_source(
+          code_block:  func.code_block,
+          filepath:    filepath
+        )
+      end
+
+    else
+      funcs.each do |func|
+        # Uses `locate_function_in_source` as an automatic fallback
+        func.line_num = @utils.locate_function_via_preprocessed(
+          code_block:            func.code_block,
+          filepath:              filepath,
+          preprocessed_filepath: preprocessed_filepath
+        )
+      end
+    end
+
+    funcs.each do |func|
+      if func.line_num.nil?
+        msg = "Could not locate function #{func.name}() in #{filepath} ➡️ Any test coverage reporting will be incomplete."
+        @loginator.log( msg, Verbosity::COMPLAIN )
+      end
+    end
+
+    header = "Found functions at line numbers in #{filepath}:"
+    @loginator.log_list( @utils.format_line_number_list( funcs ), header, Verbosity::DEBUG )
+  end
+
+  # Excise function-scoped static variable declarations from function bodies (to be
+  # promoted to module-scope).
+  #
+  # C functions may contain local `static` variable declarations. These variables have
+  # file-level storage duration but function-level scope. When generating partials, they
+  # must be lifted out of function bodies and treated as module-level variables so that
+  # linker and coverage tooling see them correctly.
+  #
+  # For each function in `funcs`, this method:
+  #   1. Scans the function body for variable declarations bearing a private keyword
+  #      (i.e. any keyword in `CExtractorConstants::PRIVATE_KEYWORDS`, e.g. `static`).
+  #   2. Replaces each such declaration in the function's `code_block` and `body` with a
+  #      no-op expression of the form `(void)0; /* <original text> */` so that coverage
+  #      line mappings remain valid without re-declaring the variable inside the body.
+  #   3. Renames each private function-scoped declaration to be prepended with the 
+  #      containing function name to prevent name collisions at module-scope.
+  #   4. Collects all promoted declarations and returns them for inclusion at module scope.
+  #
+  # @param funcs       [Array<CFunctionDefinition>] Function definitions to scan. Each matched
+  #   function's `code_block` and `body` fields are mutated in place.
+  # @param name        [String] Test name, used in log messages.
+  # @param module_name [String] Module name, used in log messages.
+  # @param file_type   [String] "source" or "header", used in log messages.
+  #
+  # @return [Array<CVariableDeclaration>] All function-scoped static variable declarations
+  #   found across all supplied functions, suitable for emission at module scope.
+  def extract_function_scope_static_vars(funcs, name:, module_name:, file_type:)
+    decls = []
+
+    # Process each function definition looking for function-scoped static variables.
+    # If found, collect them and remove from function `body` and `code_block`.
+    funcs.each do |func|
+      # Remove containing brackets of function body
+      func_body = func.body.dup
+      func_body.delete_prefix!( '{' )
+      func_body.delete_suffix!( '}' )
+
+      scanner = StringScanner.new( func_body )
+      _decls = []
+
+      loop do
+        # `try_extract_variable` returns an array of declarations.
+        # A compound declaration (e.g. int x, y) yields multiple declaration Structs
+        success, var_decls = @declaration_extractor.try_extract_variable( scanner )
+        break unless success
+        var_decls.each do |var|
+          if var.decorators.any? { |d| CExtractorConstants::PRIVATE_KEYWORDS.include?(d) }
+            _decls << var
+          end
+        end
+      end
+
+      # Group declarations by original statement.
+      # Simple declarations (one var per unique original) and 
+      # compound declarations (multiple vars sharing the same original, e.g. `static int a, b;`)
+      # require different strategies to prevent the restored comment text from being found and
+      # corrupted by a subsequent replace call.
+      groups = _decls.group_by { |var| var.original.strip }
+
+      groups.each do |_original, vars|
+        # Pre-compute old/new names before any mutation of var.name
+        old_names   = vars.map(&:name)
+        new_names   = old_names.map { |n| "partial_#{func.name}_#{n}" }
+
+        # Single placeholder per group — keyed on the first variable's name
+        placeholder = "__CEEDLING_NOOP_#{func.name.upcase}_#{old_names.first.upcase}__"
+
+        # Replace original declaration: one no-op per variable, single comment with placeholder.
+        # Defer placeholder restoration until after ALL renames are complete so that
+        # restored comment text cannot be found and re-processed by a subsequent replace.
+        if vars.size > 1
+          func.code_block = @utils.replace_compound_declaration_with_noops( func.code_block, _original, placeholder, vars.size )
+          func.body       = @utils.replace_compound_declaration_with_noops( func.body,       _original, placeholder, vars.size )
+        else
+          func.code_block = @utils.replace_declaration_with_noop( func.code_block, _original, placeholder )
+          func.body       = @utils.replace_declaration_with_noop( func.body,       _original, placeholder )
+        end
+
+        # Rename all variables' token-bounded references (shared logic for both cases)
+        vars.zip( old_names, new_names ).each do |var, old_name, new_name|
+          var.text        = @utils.rename_c_identifier( var.text,        old_name, new_name )
+          var.name        = new_name
+          func.code_block = @utils.rename_c_identifier( func.code_block, old_name, new_name )
+          func.body       = @utils.rename_c_identifier( func.body,       old_name, new_name )
+        end
+
+        # Restore original declaration text in the single placeholder comment
+        func.code_block = func.code_block.sub(placeholder) { _original }
+        func.body       = func.body.sub(placeholder)       { _original }
+      end
+
+      _decls_log = _decls.map { |d| "`#{d.original.strip}`" }
+      @loginator.log_list(
+        _decls_log,
+        "Function-scope static variables in #{func.name}() in #{file_type} to be promoted for Partial #{name}::#{module_name}:",
+        Verbosity::OBNOXIOUS
+      ) unless _decls_log.empty?
+
+      decls += _decls
+    end
+
+    return decls
+  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
+  # macro-expanded equivalents. All other fields — especially code_block — are preserved
+  # from the directives-only extraction so that line number mapping stays valid.
+  #
+  # @param funcs [Array<CFunctionDefinition>] Definitions to update in place.
+  # @param full_expansion_filepath [String] Path to the assembled full expansion file
+  #   produced by preprocess_partial_{header,source}_expand_macros().
+  # @param name [String] Test name, used in log messages.
+  # @param module_name [String] Partial module name, used in log messages.
+  # @param file_type [String] "source" or "header", used in log messages.
+  def update_signatures_from_full_expansion(funcs:, full_expansion_filepath:, name:, module_name:, file_type:)
+    expanded_module  = @c_extractor.from_file( full_expansion_filepath )
+    expanded_by_name = expanded_module.function_definitions.each_with_object({}) { |f, h| h[f.name] = f }
+
+    updated = []
+    funcs.each do |func|
+      expanded = expanded_by_name[func.name]
+      next unless expanded
+
+      func.signature          = expanded.signature
+      func.decorators         = expanded.decorators
+      func.signature_stripped = expanded.signature_stripped
+      updated << func.name
+    end
+
+    @loginator.log_list(
+      updated.map { |n| "`#{n}`" },
+      "Updated signatures from full expansion for Partial #{name}::#{module_name} #{file_type}:",
+      Verbosity::DEBUG
+    ) unless updated.empty?
+  end
+
+  # Validate that every function name in additions and subtractions exists in c_module.
+  # Case-sensitive match; if a name matches case-insensitively but not exactly, raise
+  # a specific case-mismatch exception.
+  def validate_function_names_exist(c_module, config, name)
+    known_exact = Set.new( c_module.function_definitions.map(&:name) )
+    known_lower = Set.new( c_module.function_definitions.map { |f| f.name.downcase } )
+    mod         = config.module
+
+    {TEST: config.tests, MOCK: config.mocks}.each do |label, pf|
+      (pf.additions + pf.subtractions).each do |func_name|
+        next if known_exact.include?(func_name)
+
+        if known_lower.include?(func_name.downcase)
+          raise CeedlingException.new(
+            "#{name}: #{label} Partial configuration for module '#{mod}' references function '#{func_name}' " \
+            "which differs only by case from a real function name"
+          )
+        else
+          raise CeedlingException.new(
+            "#{name}: #{label} Partial configuration for module '#{mod}' references function '#{func_name}' which does not exist"
+          )
+        end
+      end
+    end
+  end
+
+  # Validate that no function name appears in both additions and subtractions of the
+  # same tests or mocks entry.
+  def validate_no_additions_subtractions_overlap(config, name)
+    mod = config.module
+
+    {TEST: config.tests, MOCK: config.mocks}.each do |label, pf|
+      overlap = Set.new(pf.additions) & Set.new(pf.subtractions)
+      overlap.each do |func_name|
+        raise CeedlingException.new(
+          "#{name}: #{label} Partial configuration for module '#{mod}' ⏩️ Function '#{func_name}' should not be both added and subtracted"
+        )
+      end
+    end
+  end
+
+  # Validate that subtractions match their type's own visibility classification.
+  # For PUBLIC type: subtractions must be public functions.
+  # For PRIVATE type: subtractions must be private functions.
+  # Additions are not validated (same-visibility additions are redundant but harmless).
+  # ACCUMULATE is skipped (no subtractions allowed, already enforced by extract_configs).
+  def validate_additions_subtractions_visibility(c_module, config, name)
+    func_map = c_module.function_definitions.each_with_object({}) { |f, h| h[f.name] = f }
+    mod      = config.module
+
+    {tests: config.tests, mocks: config.mocks}.each do |label, pf|
+      next unless pf.type == PUBLIC || pf.type == PRIVATE
+
+      subtraction_required_visibility = pf.type
+
+      pf.subtractions.each do |func_name|
+        func = func_map[func_name]
+        unless @utils.matches_visibility?(func.decorators, subtraction_required_visibility)
+          raise CeedlingException.new(
+            "#{name}: Partial configuration for module '#{mod}': #{label} type is #{pf.type}, " \
+            "so subtractions must be #{subtraction_required_visibility} functions, " \
+            "but '#{func_name}' is not #{subtraction_required_visibility}"
+          )
+        end
+      end
+    end
+  end
+
+end

data/lib/ceedling/partials/partializer_runtime.rb

@@ -0,0 +1,29 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+module PartializerRuntime
+
+  # Format a mistaken configuration parameter for error messages
+  # @param option [Object] The mistaken value to format
+  # @return [String] Formatted string representation
+  def self.raise_on_option(option)
+    str = ''
+
+    case option
+    when Symbol
+      str = " :#{option}"
+    when NilClass, nil
+      str = ': nil'
+    when String
+      str = ": \"#{option}\""
+    else
+      str = ": #{option}"
+    end
+
+    raise ArgumentError, "Invalid internal option#{str}"
+  end
+end

data/lib/ceedling/partials/partializer_utils.rb

@@ -0,0 +1,222 @@
+# =========================================================================
+#   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/partials/partials'
+require 'ceedling/partials/partializer_runtime'
+require 'ceedling/c_extractor/c_extractor_constants'
+
+class PartializerUtils
+
+  include Partials
+
+  constructor :preprocessinator_code_finder, :loginator
+
+  def setup()
+    # Aliases
+    @code_finder = @preprocessinator_code_finder
+  end
+
+  # Check if function decorators match the desired visibility
+  def matches_visibility?(decorators, visibility)
+    case visibility
+    when PUBLIC
+      return !is_function_private?(decorators)
+    when PRIVATE
+      return is_function_private?(decorators)
+    else
+      PartializerRuntime.raise_on_option(visibility)
+    end
+  end
+
+  # Transform function to appropriate output format `FunctionDefinition` or `FunctionDeclaration`
+  def transform_function(func, signature, output_type)
+    case output_type
+    when :impl
+      # Strip decorators from the front of code_block and count how many newlines were removed.
+      # Adjust line_num upward so that emitted #line directives remain accurate.
+      new_code_block, stripped_newlines = extract_code_block(func.code_block, func.decorators)
+      Partials.manufacture_function_definition(
+        name:            func.name,
+        signature:       signature,
+        source_filepath: func.source_filepath,
+        line_num:        adjust_line_num(func.line_num, stripped_newlines),
+        code_block:      new_code_block
+      )
+    when :interface
+      Partials.manufacture_function_declaration(
+        name: func.name,
+        signature: signature
+      )
+    else
+      PartializerRuntime.raise_on_option(output_type)
+    end
+  end
+
+  # Replace a C variable declaration in a text block with a no-op expression.
+  #
+  # Substitutes the first occurrence of `original_decl` in `text` with:
+  #   (void)0; /* <placeholder> */
+  # The caller supplies a unique `placeholder` token for the comment slot. This
+  # allows subsequent rename operations (which use simple token-bounded substitution
+  # with no comment awareness) to run without touching the comment. After all renames
+  # are complete, the caller restores `original_decl` by replacing the placeholder.
+  #
+  # Block form of `sub` is used so that `\` and `&` in the declaration are not
+  # interpreted as regex replacement backreferences.
+  #
+  # @param text          [String] Code text to modify (e.g., a function code_block or body)
+  # @param original_decl [String] Declaration text to replace (should be stripped of surrounding whitespace)
+  # @param placeholder   [String] Opaque token to embed in the comment (caller replaces it afterwards)
+  # @return [String] Modified text with declaration replaced by a no-op expression
+  def replace_declaration_with_noop(text, original_decl, placeholder)
+    replace_compound_declaration_with_noops(text, original_decl, placeholder, 1)
+  end
+
+  # Replace a C compound variable declaration with N no-op expressions and a single comment.
+  #
+  # Generates `count` `(void)0;` expressions where the final one carries a comment
+  # containing `placeholder`. The result replaces the first occurrence of `original_decl`
+  # in `text`. The caller supplies `count` = number of variables in the compound statement
+  # and a single unique `placeholder` token. After all variable renames are complete, the
+  # caller restores `original_decl` by replacing the placeholder with the original text.
+  #
+  # Block form of `sub` is used so that `\` and `&` in the declaration are not interpreted
+  # as regex replacement backreferences.
+  #
+  # @param text          [String] Code text to modify (e.g., a function code_block or body)
+  # @param original_decl [String] Declaration text to replace (should be stripped of surrounding whitespace)
+  # @param placeholder   [String] Opaque token to embed in the single trailing comment
+  # @param count         [Integer] Number of no-op expressions to insert (one per variable)
+  # @return [String] Modified text
+  def replace_compound_declaration_with_noops(text, original_decl, placeholder, count)
+    noops   = "(void)0; " * (count - 1)
+    comment = "(void)0; /* `#{placeholder}` replaced with no-op plus variable renamed & promoted to module-scope */"
+    text.sub(original_decl) { noops + comment }
+  end
+
+  # Rename a C identifier throughout a text block with token-bounded substitution.
+  #
+  # Replaces all occurrences of `old_name` that are bounded by C identifier boundaries
+  # with `new_name`. Token boundaries use Ruby `\b` (word boundary between
+  # `\w` = `[a-zA-Z0-9_]` and `\W`), which exactly matches C identifier boundaries.
+  # For example, renaming `count`:
+  #   - Matches:     `count = 0`, `(count)`, `count==5`, `*count`, `count[0]`
+  #   - No match:    `count_down`, `up_count`, `recount`
+  #
+  # Note: This method has no comment-awareness. Callers that need comment content
+  # preserved verbatim (e.g., no-op placeholders) should use `replace_declaration_with_noop`
+  # with an opaque placeholder and restore the original text after renaming.
+  #
+  # @param text     [String] Code text to process
+  # @param old_name [String] Identifier to replace
+  # @param new_name [String] Replacement identifier
+  # @return [String] Modified text with all token-bounded occurrences renamed
+  def rename_c_identifier(text, old_name, new_name)
+    text.gsub(/\b#{Regexp.escape(old_name)}\b/, new_name)
+  end
+
+  # Stamp the originating source filepath onto each function in a collection.
+  #
+  # Mutates each element of `funcs` in place by assigning `filepath` to its
+  # `source_filepath` field. Called before any line-number search so the field
+  # is always populated regardless of whether a line number is ultimately found.
+  #
+  # @param funcs    [Array<CFunctionDefinition>] Functions to annotate
+  # @param filepath [String] Path to the originating C source file
+  def stamp_source_filepaths(funcs, filepath)
+    funcs.each { |func| func.source_filepath = filepath }
+  end
+
+  # Locate a function's line number by searching the original C source file.
+  #
+  # Used when the global fallback mode is active — i.e., preprocessed output is
+  # unavailable for all functions in the current context. Delegates directly to
+  # `code_finder.find_in_c_file`.
+  #
+  # @param code_block  [String] Function definition text to search for
+  # @param filepath    [String] Path to the C source file to search
+  # @return [Integer, nil] 1-indexed source line number, or nil if not found
+  def locate_function_in_source(code_block:, filepath:)
+    @code_finder.find_in_c_file(filepath, code_block)
+  end
+
+  # Locate a function's line number using preprocessed output with C source fallback.
+  #
+  # Two-strategy lookup for a single function:
+  #   1. Try the GCC-preprocessed directives-only file — exact match preserving line markers.
+  #   2. If that yields nil, fall back to the original C source file.
+  #
+  # Returns line number or nil if neither approach succeeds.
+  #
+  # @param code_block            [String] Function definition text to search for
+  # @param filepath              [String] Path to the original C source file (fallback target)
+  # @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)
+    return line_num unless line_num.nil?
+
+    msg = "Using fallback C function location search for #{filepath}"
+    @loginator.log( msg, Verbosity::OBNOXIOUS, LogLabels::WARNING )
+
+    return @code_finder.find_in_c_file(filepath, code_block)
+  end
+
+  # Format per-function line-number results as a list of human-readable strings.
+  #
+  # Produces one entry per function in the form `"name(): <line_num>"`.
+  # Functions with no resolved line number are rendered with `'N/A'`.
+  # The returned array is passed directly to `@loginator.log_list` for debug output.
+  #
+  # @param funcs [Array<CFunctionDefinition>] Functions with `name` and `line_num` fields
+  # @return [Array<String>]
+  def format_line_number_list(funcs)
+    funcs.map do |func|
+      "#{func.name}(): #{func.line_num.nil? ? 'N/A' : func.line_num.to_s()}"
+    end
+  end
+
+  private
+
+  # Does any decorator in a list matche any private keyword (case-insensitive)
+  def is_function_private?(decorators)
+    return decorators.any? do |decorator|
+      CExtractorConstants::PRIVATE_KEYWORDS.any? { |keyword| decorator.downcase == keyword.downcase }
+    end
+  end
+
+  # Strip decorator keywords from the front of code_block and count leading newlines removed.
+  #
+  # Removes the first occurrence of each decorator string, then strips any leading whitespace
+  # (including newlines). Returns the trimmed code block and a count of the newlines removed
+  # from the leading portion — used by the caller to adjust line_num so that emitted #line
+  # directives in generated source remain accurate.
+  #
+  # @param code_block  [String]        Raw function source text (decorators + signature + body)
+  # @param decorators  [Array<String>] Decorator keywords from CFunctionDefinition#decorators
+  # @return [Array(String, Integer)]   [trimmed_code_block, leading_newline_count]
+  def extract_code_block(code_block, decorators)
+    stripped = code_block.dup
+    decorators.each { |d| stripped.sub!(d, '') }
+    leading = stripped[/\A\s*/]
+    stripped.lstrip!
+    return stripped, leading.count("\n")
+  end
+
+  # Offset a source line number by the count of newlines stripped from the front of a code block.
+  #
+  # When decorator keywords occupy one or more lines before the function's return type, those
+  # lines are removed from the emitted code_block. The #line directive must be bumped forward
+  # by the same count so it still points at the return type in the original source file.
+  #
+  # Returns nil unchanged when line_num was not resolved.
+  def adjust_line_num(line_num, stripped_newlines)
+    return line_num if line_num.nil?
+    line_num + stripped_newlines
+  end
+
+end

data/lib/ceedling/partials/partials.rb

@@ -0,0 +1,82 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+module Partials
+  # Constants
+  PUBLIC     = :public     unless const_defined?(:PUBLIC)
+  PRIVATE    = :private    unless const_defined?(:PRIVATE)
+  ACCUMULATE = :accumulate unless const_defined?(:ACCUMULATE)
+  DEDUCT     = :deduct     unless const_defined?(:DEDUCT)
+
+  TEST_PUBLIC  = :test_public   unless const_defined?(:TEST_PUBLIC)
+  TEST_PRIVATE = :test_private  unless const_defined?(:TEST_PRIVATE)
+  MOCK_PUBLIC  = :mock_public   unless const_defined?(:MOCK_PUBLIC)
+  MOCK_PRIVATE = :mock_private  unless const_defined?(:MOCK_PRIVATE)
+
+  # Data class representing a source or header file to be partialized
+  ConfigFileInfo = Struct.new(:filepath, :directives_only_filepath, :full_expansion_filepath, :includes, keyword_init: true) do
+    def initialize(filepath: nil, directives_only_filepath: nil, full_expansion_filepath: nil, includes: [])
+      super
+    end
+  end
+
+  # 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
+
+  # Data class representing a C function signature
+  FunctionDeclaration = Struct.new(
+    :name,            # Function name (e.g., "foo")
+    :return_type,     # Return type (e.g., "int")
+    :signature,       # FunctionDefinition signature (e.g., "int foo(void)")
+    :source_filepath, # Path to source file
+    :line_num,        # Line number in source file
+    keyword_init: true
+  ) do
+    # Constructor to set unassigned fields to nil for convenience
+    def initialize(name: nil, signature: nil, source_filepath: nil, line_num: nil)
+      super
+    end
+  end
+
+  # Data class representing a C function with intentionally duplicated fields
+  FunctionDefinition = Struct.new(
+    :name,            # Function name (e.g., "foo")
+    :signature,       # FunctionDefinition signature (e.g., "int foo(void)")
+    :code_block,      # Complete function text (signature + body)
+    :source_filepath, # Path to source file
+    :line_num,        # Line number in source file
+    keyword_init: true
+  ) do
+    # Constructor to set unassigned fields to nil for convenience
+    def initialize(name: nil, signature: nil, code_block: nil, source_filepath: nil, line_num: nil)
+      super
+    end
+  end
+
+  def self.manufacture_function_declaration(line_num: nil, source_filepath: nil, name:, signature:)
+    return FunctionDeclaration.new(
+      name: name,
+      signature: signature,
+      source_filepath: source_filepath,
+      line_num: line_num
+    )
+  end
+
+  def self.manufacture_function_definition(line_num: nil, source_filepath: nil, name:, signature:, code_block:)
+    return FunctionDefinition.new(
+      name: name,
+      signature: signature,
+      code_block: code_block,
+      source_filepath: source_filepath,
+      line_num: line_num
+    )
+  end
+end

data/lib/ceedling/{plugin.rb → plugins/plugin.rb}

@@ -1,7 +1,7 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================