ceedling 1.1.9 → 1.2.0

data/lib/ceedling/partials/partializer.rb

@@ -14,32 +14,50 @@ require 'ceedling/c_extractor/c_extractor'
 require 'ceedling/c_extractor/c_extractor_constants'
 require 'ceedling/c_extractor/c_extractor_types'
 require 'ceedling/constants'
+require 'ceedling/path_mirror'
+require 'ceedling/encodinator'
 
 class Partializer
 
+  # Enough of a header to reach its include guard. The guard pair sits at the top of a header by
+  # construction, so a bounded read beats loading a large file to find it.
+  GUARD_SCAN_BYTES = 2048
+
   include Partials
 
-  constructor :partializer_helper, :file_finder, :c_extractor, :file_path_utils, :reportinator, :loginator
+  constructor :configurator, :partializer_helper, :file_finder, :c_extractor, :file_path_utils,
+              :preprocessinator_reconstructor, :file_wrapper, :reportinator, :loginator
 
   def setup()
     # Alias
     @helper = @partializer_helper
   end
 
-  def validate_config(c_module:, config:, name:)
+  def validate_config(c_module:, config:, name:, fallback:)
     msg = @reportinator.generate_progress("Validating Partial config for '#{name}'")
     @loginator.log(msg, Verbosity::DEBUG)
     @helper.validate_function_names_exist(c_module, config, name)
     @helper.validate_no_additions_subtractions_overlap(config, name)
     @helper.validate_additions_subtractions_visibility(c_module, config, name)
+
+    # Fallback preprocessing resolves strictly less than the accurate pass, and two module
+    # shapes are knowably beyond it. Reading the original text happens here, at the I/O edge,
+    # so the check itself stays pure.
+    return unless fallback
+
+    @helper.validate_fallback_sufficiency(
+      name: name,
+      module_name: config.module,
+      files: _module_file_texts(config)
+    )
   end
 
   def sanitize(c_module)
-    # Remove macro definitions that contain the CEEDLING_GENERATED sentinel string.
-    # These are include-guard and boilerplate macros injected into Ceedling-generated header files.
-    removed = c_module.macro_definitions.select { |m| m.text.include?(CEEDLING_GENERATED) }
+    # Remove macro definitions carrying a generated include guard. Ceedling writes these into
+    # the headers it generates, and they belong to those headers, not the module.
+    removed = c_module.macro_definitions.select { |m| m.text.match?(GENERATED_INCLUDE_GUARD_PATTERN) }
     # Remove from both the macro_definitions list and the element_sequence that references it
-    c_module.macro_definitions.reject! { |m| m.text.include?(CEEDLING_GENERATED) }
+    c_module.macro_definitions.reject! { |m| removed.include?(m) }
     c_module.element_sequence.reject!  { |e| removed.include?(e) }
   end
 
@@ -60,155 +78,187 @@ class Partializer
     )
     @loginator.log(msg, Verbosity::DEBUG)
 
+    # Report the first overlap and abort. An `each` here would read as though
+    # every offending function gets reported, which it cannot -- the raise ends
+    # the build on the first one.
     overlap = impl_names & interface_names
-    overlap.each do |func_name|
+    unless overlap.empty?
       raise CeedlingException.new(
-        "#{name}: Partial '#{partial}' ⏩️ Function '#{func_name}' cannot be both testable and mockable"
+        "#{name}: Partial '#{partial}' ⏩️ Function '#{overlap.first}' cannot be both testable and mockable"
       )
     end
   end
 
-  def populate_filepaths(configs)
+  # A Partial module is resolved the way every other file reference in a test is, by
+  # matching trailing path segments. Two things make that correct here.
+  #
+  # `collection` is the ordered header list this one test would search, so a
+  # TEST_INCLUDE_PATH() in that test decides which module it gets. Resolving against
+  # one project-wide collection instead lets two modules sharing a basename collapse
+  # to whichever appears first, no matter which test asked.
+  #
+  # The source is then found by way of the resolved header, so a bare module name
+  # cannot pair one module's header with another module's source.
+  def populate_filepaths(configs, collection: nil, test_filepath: nil)
     configs.each do |_module, config|
       # Every partial involves processing header files
-      config.header.filepath = @file_finder.find_header_file(_module, :ignore)
+      config.header.filepath = @file_finder.find_header_file(_module, :ignore, collection: collection)
+
+      _validate_named_directory_resolved!(_module, config.header.filepath, test_filepath)
 
       # Source file not needed only when mocking public functions exclusively
       unless !config.tests.present? && config.mocks.type == PUBLIC
-        config.source.filepath = @file_finder.find_source_file(_module, :ignore)
+        config.source.filepath = _find_module_source(_module, config.header.filepath)
       end
     end
 
     return configs
   end
 
-  # When `test:` is provided, logs the resulting includes at OBNOXIOUS.
-  def remap_implementation_header_includes(name:, includes:, partials:, types_header: nil, test: nil)
-    _includes = includes.clone()
+  # A module named by directory was spelled out by its author, so it is looked up
+  # verbatim with no fallback. A bare name is narrowed by its resolved header's own
+  # directory, which is what keeps one module's header from pairing with another
+  # module's source. The fallback after that serves a project whose source and include
+  # trees do not mirror one another, where a header sits under a directory its source
+  # does not.
+  def _find_module_source(_module, header_filepath)
+    return @file_finder.find_source_file(_module, :ignore) if _names_directory?(_module)
 
-    # This module's own header include is spliced out in favor of the shared types
-    # header at its exact original list position -- see #splice_in_replacement.
-    _includes = splice_in_replacement(includes: _includes, name: name, replacement: types_header)
+    subdir = header_filepath.nil? ? '' : PathMirror.relative_subdir(header_filepath, _header_roots)
 
-    # Remove includes for every other partialized module (this module's own name was
-    # already handled above)
-    _includes = remove_matching_includes(
-      includes: _includes,
-      modules: (partials.keys - [name])
-    )
-
-    # Remove any duplicates
-    Includes.sanitize!(_includes)
-
-    @loginator.log_list(
-      _includes,
-      "Header includes to inject for testable Partial #{test}::#{name}:",
-      Verbosity::OBNOXIOUS
-    ) if test
+    unless subdir.empty?
+      found = @file_finder.find_source_file(File.join(subdir, _module), :ignore)
+      return found unless found.nil?
+    end
 
-    return _includes
+    return @file_finder.find_source_file(_module, :ignore)
   end
 
-  # When `test:` is provided, logs the resulting includes at OBNOXIOUS.
-  def remap_implementation_source_includes(name:, includes:, partials:, test: nil)
-    _includes = includes.clone()
+  # Roots a header can sit beneath, which is what its mirrored directory is measured
+  # against. The same three the project-wide header collection is built from.
+  def _header_roots
+    @configurator.paths_test + @configurator.paths_support + @configurator.paths_include
+  end
 
-    # Splice the implementation header in at this module's own header's original list
-    # position, same rationale as #splice_in_replacement -- the generated
-    # implementation header carries the shared types header in correctly-ordered
-    # position internally, but that alone doesn't help if THIS file's own separate
-    # include list still reaches an unrelated header that transitively re-includes the
-    # real module header before the implementation header (and everything it carries)
-    # is ever reached. Appending it at the very end (after this file's own copy of every
-    # other real include) would put it after exactly that kind of transitive
-    # re-inclusion instead of before it.
-    _includes = splice_in_replacement(
-      includes: _includes,
-      name: name,
-      replacement: @file_path_utils.form_partial_implementation_header_filename(name)
-    )
+  # Either separator counts. The qualifier validation already rejects a backslash-rooted
+  # absolute path, so a backslash reaching here is a relative directory like any other.
+  def _names_directory?(_module)
+    _module.match?( %r{[\\/]} )
+  end
 
-    mockable_modules = []
+  # A bare module name that matches nothing keeps its older behavior, generating a
+  # degenerate Partial. A directory that matches nothing is a typo worth saying so,
+  # since naming the directory was a deliberate act and no older behavior is at stake.
+  def _validate_named_directory_resolved!(_module, header_filepath, test_filepath)
+    return unless _names_directory?(_module)
+    return unless header_filepath.nil?
 
-    partials.each do |_module, config|
-      # Remap mockable interface headers that will be injected into generated partial implementation
-      #
-      # Any real (non-nil) mock mode means this module has a generated mock interface header
-      # to redirect to -- PUBLIC/PRIVATE alone once covered every mode that existed, but DEDUCT
-      # (MOCK_PARTIAL_ALL_MODULE) and ACCUMULATE (MOCK_PARTIAL_MODULE) were added later without
-      # updating this check, so a module mocked via either of those was silently never
-      # redirected: its real header (and any static inline/static function bodies in it) stayed
-      # #include'd verbatim, compiling straight past the mock instead of being replaced by it.
-      if includes.any? { |include| include.filename.ext().downcase() == _module.downcase() }
-        if !config.mocks.type.nil?
-          # Insert mockable interface header from remapping of module name
-          _includes << UserInclude.new(
-            @file_path_utils.form_partial_interface_header_filename(_module)
-          )
-          # Remember the module for later removal of original header
-          mockable_modules << _module
-        end
-      end
-    end
+    location = test_filepath.nil? ? '' : " referenced in #{test_filepath}"
 
-    # Remove the original headers of any OTHER modules now remapped to mockable
-    # interfaces above -- this module's own original header was already handled by
-    # the splice above.
-    _includes = remove_matching_includes(
-      includes: _includes,
-      modules: mockable_modules
+    raise CeedlingException.new(
+      "Partial module '#{_module}'#{location} matches no files. " \
+      "A Partial's directory is matched against the trailing end of a module's path, " \
+      "so check the spelling of both the directory and the module."
     )
+  end
 
-    # Remove any duplicates
-    Includes.sanitize!(_includes)
-
-    @loginator.log_list(
-      _includes,
-      "Source includes to inject for testable Partial #{test}::#{name}:",
-      Verbosity::OBNOXIOUS
-    ) if test
-
-    return _includes
+  # Includes for the generated implementation header. This module's own header is replaced by
+  # the shared types header at its original list position; every other partialized module's
+  # include is dropped.
+  #
+  # When `test:` is provided, logs the resulting includes at OBNOXIOUS.
+  def remap_implementation_header_includes(name:, includes:, partials:, types_header: nil, test: nil)
+    _remap_includes(
+      name:        name,
+      includes:    includes,
+      partials:    partials,
+      replacement: types_header,
+      others:      :drop,
+      noun:        'Header includes to inject for testable Partial',
+      test:        test
+    )
   end
 
+  # Includes for the generated mockable interface header. Same treatment as the implementation
+  # header: both files carry the shared types header, which is how a module tested and mocked
+  # in one test file still gets exactly one definition of each of its types.
+  #
   # When `test:` is provided, logs the resulting includes at OBNOXIOUS.
   def remap_interface_header_includes(name:, includes:, partials:, types_header: nil, test: nil)
-    _includes = includes.clone()
-
-    # This module's own header include is spliced out in favor of the shared types
-    # header at its exact original list position -- see #splice_in_replacement.
-    _includes = splice_in_replacement(includes: _includes, name: name, replacement: types_header)
-
-    # Remove includes for every other partialized module (this module's own name was
-    # already handled above)
-    _includes = remove_matching_includes(
-      includes: _includes,
-      modules: (partials.keys - [name])
+    _remap_includes(
+      name:        name,
+      includes:    includes,
+      partials:    partials,
+      replacement: types_header,
+      others:      :drop,
+      noun:        'Header includes to inject for mockable Partial',
+      test:        test
     )
+  end
 
-    # Remove any duplicates
-    Includes.sanitize!(_includes)
+  # Includes for the generated implementation source. This module's own header is replaced by
+  # the generated implementation header, which carries the types header internally. Another
+  # partialized module that is mocked is redirected to its generated interface header; one that
+  # is not mocked keeps its real header, which the generated code still needs.
+  #
+  # When `test:` is provided, logs the resulting includes at OBNOXIOUS.
+  def remap_implementation_source_includes(name:, includes:, partials:, test: nil)
+    _remap_includes(
+      name:        name,
+      includes:    includes,
+      partials:    partials,
+      replacement: @file_path_utils.form_partial_implementation_header_filename(name),
+      others:      :mock_or_keep,
+      noun:        'Source includes to inject for testable Partial',
+      test:        test
+    )
+  end
 
-    @loginator.log_list(
-      _includes,
-      "Header includes to inject for mockable Partial #{test}::#{name}:",
-      Verbosity::OBNOXIOUS
-    ) if test
+  # Includes the shared types header carries so the extracted types resolve wherever that file
+  # lands. Nothing replaces this module's own header here -- the types header cannot include
+  # itself -- so it is simply dropped. Another partialized module is redirected to its generated
+  # interface header when mocked and dropped otherwise: its real header would reintroduce the
+  # very content that module's own Partial replaced.
+  #
+  # When `test:` is provided, logs the resulting includes at OBNOXIOUS.
+  def remap_types_header_includes(name:, includes:, partials:, test: nil)
+    _remap_includes(
+      name:        name,
+      includes:    includes,
+      partials:    partials,
+      replacement: nil,
+      others:      :mock_or_drop,
+      noun:        'Dependency includes to carry into the shared types header for Partial',
+      test:        test
+    )
+  end
 
-    return _includes
+  # The include guard macro the module's real header defines, or nil when it has none.
+  #
+  # Read from the original header rather than from the reconstituted copy or from extracted
+  # macros. The reconstituted copy carries a synthetic guard that #sanitize strips, and the
+  # fallback preprocessing path deliberately excludes a guard from the macros it recovers, so
+  # neither is a dependable source. A nil return means the header guards itself some other way
+  # -- `#pragma once` -- and offers no macro for a generated file to spoof.
+  def extract_module_include_guard(filepath)
+    return nil if filepath.nil?
+
+    text = @file_wrapper.read( filepath, GUARD_SCAN_BYTES ).clean_encoding
+    @preprocessinator_reconstructor.extract_include_guard( text )
   end
 
-  # Extracts and combines C code contents from header and source files
+  # Extracts and combines C code contents from a Partial config's header and source files
   #
   # This method uses CExtractor to parse C files and extract their contents including
   # function definitions, function declarations, and variable declarations. If both
   # header and source files are provided, their contents are merged into a single
   # CModule structure.
   #
-  # @param header_filepath [String, nil] Path to the header file to extract from.
-  #   If nil, no header content is extracted.
-  # @param source_filepath [String, nil] Path to the source file to extract from.
-  #   If nil, no source content is extracted.
+  # @param name [String] The test this extraction is running for (log/error context).
+  # @param config [Partials::ModuleConfig] The Partial's own config, carrying `header`/
+  #   `source` (each a ConfigFileInfo) and `module`, the module name.
+  # @param fallback [Boolean] Passed through to `associate_function_line_numbers` --
+  #   whether to fall back to plain (non-directives-only) line-number association.
   #
   # @return [CExtractorTypes::CModule] A merged CModule containing all extracted contents
   #   from both files. The structure includes:
@@ -218,7 +268,7 @@ class Partializer
   #
   # @note The method always starts with an empty CModule and merges in contents
   #   from any provided files using the CModule's + operator for combining structures.
-  def extract_module_contents(name, config, fallback)
+  def extract_module_contents(name, config, fallback:)
     # Array for CModule structs
     contents = [CExtractorTypes::CModule.new()]
 
@@ -457,6 +507,104 @@ class Partializer
     )
   end
 
+  # The module's own header and source text, keyed by filepath. A declaration-only Partial has
+  # no paired source, which leaves that filepath legitimately nil.
+  def _module_file_texts(config)
+    [config.header, config.source].filter_map do |file_info|
+      next if file_info.nil? || file_info.filepath.nil?
+
+      [file_info.filepath, @file_wrapper.read( file_info.filepath ).clean_encoding]
+    end.to_h
+  end
+
+  # One body behind all four public remaps. Each differs only in what replaces this module's
+  # own header, what becomes of other partialized modules, and the noun it logs under -- the
+  # splice, the sanitize, and the logging are identical in every case.
+  #
+  # `others` selects the treatment of every OTHER partialized module in the same test file:
+  #   :drop         -- remove its include outright, with no substitute
+  #   :mock_or_keep -- redirect to its interface header when mocked, else leave its real header
+  #   :mock_or_drop -- redirect to its interface header when mocked, else drop it
+  def _remap_includes(name:, includes:, partials:, replacement:, others:, noun:, test: nil)
+    _includes = includes.clone()
+
+    # A nil replacement strips this module's own header and substitutes nothing.
+    _includes = splice_in_replacement( includes: _includes, name: name, replacement: replacement )
+
+    _includes =
+      case others
+      when :drop
+        remove_matching_includes( includes: _includes, modules: (partials.keys - [name]) )
+      when :mock_or_keep, :mock_or_drop
+        # The types header differs from the generated source in two ways at once, which is why
+        # both flags below read from one condition.
+        #
+        # It skips this module: the interface header includes the types header, so carrying the
+        # interface back in would fold that file's declarations into this one. The generated
+        # source needs the opposite -- a module tested and mocked in one test file keeps its
+        # public bodies in the implementation and the private declarations they call in the
+        # interface, so it needs both.
+        #
+        # And it drops an unmocked partialized dependency rather than keeping its real header,
+        # which would reintroduce content that module's own Partial replaced.
+        shared_types_header = ( others == :mock_or_drop )
+
+        _redirect_mocked_partials(
+          includes: _includes,
+          original: includes,
+          name: name,
+          partials: partials,
+          drop_unmocked: shared_types_header,
+          skip_self: shared_types_header
+        )
+      else
+        PartializerRuntime.raise_on_option( others )
+      end
+
+    # Remove any duplicates
+    Includes.sanitize!(_includes)
+
+    @loginator.log_list(
+      _includes,
+      "#{noun} #{test}::#{name}:",
+      Verbosity::OBNOXIOUS
+    ) if test
+
+    return _includes
+  end
+
+  # Appends the generated interface header for each mocked partialized module the original list
+  # named, then removes the real headers those replaced. `skip_self` decides whether the module
+  # being generated counts as one of them, which it does everywhere except the types header --
+  # see the call site.
+  #
+  # Mutates `includes`, which always arrives fresh from splice_in_replacement.
+  #
+  # Any real (non-nil) mock mode counts. PUBLIC/PRIVATE alone once covered every mode that
+  # existed, but DEDUCT (MOCK_PARTIAL_ALL_MODULE) and ACCUMULATE (MOCK_PARTIAL_MODULE) were
+  # added later without updating the check, so a module mocked via either was silently never
+  # redirected: its real header, and any static inline or static function bodies in it, stayed
+  # #include'd verbatim and compiled straight past the mock.
+  def _redirect_mocked_partials(includes:, original:, name:, partials:, drop_unmocked:, skip_self:)
+    retired = []
+
+    partials.each do |_module, config|
+      next if skip_self && _module == name
+      next unless original.any? { |include| include.filename.ext().downcase() == _module.downcase() }
+
+      if config.mocks.type.nil?
+        retired << _module if drop_unmocked
+      else
+        includes << UserInclude.new(
+          @file_path_utils.form_partial_interface_header_filename(_module)
+        )
+        retired << _module
+      end
+    end
+
+    remove_matching_includes( includes: includes, modules: retired )
+  end
+
   # Swaps `name`'s own header include for `replacement` at that same list position,
   # instead of stripping it out and appending the replacement at the very end.
   #
@@ -479,7 +627,7 @@ class Partializer
 
     replaced = false
     spliced = includes.map do |include|
-      if !replaced && include.filename.ext().downcase() == name.downcase()
+      if !replaced && module_basename( name ) == include.filename.ext().downcase()
         replaced = true
         UserInclude.new(replacement)
       else
@@ -500,12 +648,19 @@ class Partializer
   # Remove includes that match the given module names (case-insensitive)
   # Returns a new array with matching includes removed
   def remove_matching_includes(includes:, modules:)
-    # Normalize module names to lowercase for comparison
-    normalized_modules = modules.map(&:downcase)
-    
+    normalized_modules = modules.map { |_module| module_basename( _module ) }
+
     # Filter out includes (minus extension) that match any module name
     return includes.reject do |include|
       normalized_modules.include?(include.filename.ext().downcase())
     end
-  end  
+  end
+
+  # A module name reduced to what an #include actually carries. An #include names a
+  # file, not a module, so a module named by directory still has to be recognized by
+  # the basename its own header include spells out.
+  def module_basename(_module)
+    File.basename( _module ).ext().downcase()
+  end
+
 end