Add .. (parent-directory) support to relative path resolution

#include directives, TEST_SOURCE_FILE(), and CLI `test:` task names got
proper relative-path handling and duplicate-filename disambiguation in a
recent refactor, but none of it accounted for `..`. A `..`-containing query
was silently treated as an ordinary path segment that could never match any
real project file, degrading to a plain not-found rather than naming `..`
as the actual problem.

PathMatcher gains `resolve_relative(query, anchor:)`, collapsing a query's
own `..` against an anchor directory (or raising a clear, specific error
when no anchor exists, or when traversal would go outside the project).
Six call sites needed it, not the three originally expected -- three
distinct #include extraction pipelines (GCC's own directives-only output,
the text-scan fallback, and TestContextExtractor's always-on scan) each
independently construct Include objects from literal, unresolved directive
text and needed their own anchoring. That repeated reconstruction logic is
now consolidated into one `Include#anchored(anchor)` on the base class.

CLI test: task names have no file of their own to anchor a `..` against,
so one is deliberately left unsupported there, with a named error instead
of a generic not-found.

Also folds `Includes.paths_correspond?`'s own segment-tail-matching into
`PathMatcher.correspond?`, removing a second, independent reimplementation
of the same comparison PathMatcher already provided.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: mkarlesky

assets/fixtures/parent_directory_references/alpha/extra.c

@@ -0,0 +1,4 @@
+int extra_value(void)
+{
+  return 222;
+}

assets/fixtures/parent_directory_references/common/helper.c

@@ -0,0 +1,6 @@
+#include "helper.h"
+
+int helper_value(void)
+{
+  return 111;
+}

assets/fixtures/parent_directory_references/common/helper.h

@@ -0,0 +1,6 @@
+#ifndef HELPER_H
+#define HELPER_H
+
+int helper_value(void);
+
+#endif // HELPER_H

assets/fixtures/parent_directory_references/unit/test_dotdot_include.c

@@ -0,0 +1,10 @@
+#include "unity.h"
+#include "../common/helper.h"
+
+void setUp(void) {}
+void tearDown(void) {}
+
+void test_helper_value_via_parent_directory_include(void)
+{
+  TEST_ASSERT_EQUAL(111, helper_value());
+}

assets/fixtures/parent_directory_references/unit/test_dotdot_source.c

@@ -0,0 +1,16 @@
+#include "unity.h"
+
+// extra.c has no corresponding header; this test file lives one directory
+// away from it, so resolving this directive exercises TEST_SOURCE_FILE()'s
+// own anchor-relative .. resolution rather than the #include machinery.
+TEST_SOURCE_FILE("../alpha/extra.c")
+
+extern int extra_value(void);
+
+void setUp(void) {}
+void tearDown(void) {}
+
+void test_extra_value_via_parent_directory_test_source_file(void)
+{
+  TEST_ASSERT_EQUAL(222, extra_value());
+}

lib/ceedling/file_finder.rb

@@ -65,7 +65,12 @@ def resolve_mock(mock, collection: nil)
   # ambiguous, not have Ceedling silently guess which test they meant -- there's no
   # compilation step downstream to catch a wrong guess the way there is for a header
   # or source file resolved during a build.
+  #
+  # A task name has no file of its own to anchor a `..` against, unlike an #include or
+  # TEST_SOURCE_FILE() entry -- resolving with no anchor surfaces that as a specific,
+  # named error rather than falling through to a generic file-not-found further down.
   def find_test_file_from_name(name)
+    name = PathMatcher.resolve_relative(name)
     return find_first_candidate(name, @configurator.extension_source, @configurator.collection_all_tests, :error, strict: true)
   end
 

lib/ceedling/includes/includes.rb

@@ -7,6 +7,7 @@
 
 require 'set'
 require 'ceedling/exceptions'
+require 'ceedling/path_matcher'
 
 class Includes
   # Class method to convert mixed list of Include objects into an order-preserving list of hashes
@@ -209,9 +210,12 @@ def self.sanitize!(includes, &block)
   # includes are never resolved against a real file under `-nostdinc`, so its bare text
   # is always exactly what was written.
   #
-  # `test_filepath` plays no part in matching -- it's carried only so a caller's own
-  # `on_ambiguous` block can name the one test file whose #include statement is worth a
-  # closer look, since nothing further up the call stack adds that context on its own.
+  # `test_filepath` is the anchor a bare entry's own `..` resolves against -- a bare
+  # scan sees a directory-relative #include exactly as written, `..` and all, so it's
+  # resolved here against the one file any such directive could possibly belong to:
+  # the test file itself. It's also carried so a caller's own `on_ambiguous` block can
+  # name the one test file whose #include statement is worth a closer look, since
+  # nothing further up the call stack adds that context on its own.
   def self.reconcile(bare:, user:, system:, test_filepath: nil, &on_ambiguous)
     # Validate input types
 
@@ -249,13 +253,20 @@ def self.reconcile(bare:, user:, system:, test_filepath: nil, &on_ambiguous)
     seen = Set.new
 
     bare.each do |bare_include|
+      # A directory-relative #include's own literal text is anchored to the one file
+      # a bare scan could have found it in -- the test file itself, never a header,
+      # since bare extraction never recurses into one. Resolving here, once, means
+      # every candidate below is compared against an ordinary, ..-free path exactly
+      # as if it had been written that way to begin with.
+      bare_filepath = PathMatcher.resolve_relative(bare_include.filepath, anchor: test_filepath && File.dirname(test_filepath))
+
       # Matching is deliberately bidirectional: a bare entry can carry either more path
       # than its candidate (literal, unresolved #include text against a bare-scanned
       # candidate from fallback preprocessing) or less (a pathless bare entry against a
       # candidate directives-only preprocessing resolved to a fuller real location) --
       # either side may be the more specific one, so whichever is shorter sets how many
       # of the longer one's trailing segments must match.
-      matched = user_filepaths.select { |filepath| paths_correspond?(bare_include.filepath, filepath) }
+      matched = user_filepaths.select { |filepath| paths_correspond?(bare_filepath, filepath) }
 
       next if matched.empty?
 
@@ -280,11 +291,10 @@ def self.reconcile(bare:, user:, system:, test_filepath: nil, &on_ambiguous)
   # 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 either a bare entry or its candidate may be the one carrying less path.
+  # Delegates to PathMatcher's own version of this same comparison rather than
+  # reimplementing segment-splitting a second time.
   def self.paths_correspond?(a, b)
-    segments_a = a.split(/[\\\/]/).reject(&:empty?)
-    segments_b = b.split(/[\\\/]/).reject(&:empty?)
-    shorter, longer = segments_a.length <= segments_b.length ? [segments_a, segments_b] : [segments_b, segments_a]
-    return longer.last(shorter.length) == shorter
+    PathMatcher.correspond?(a, b)
   end
   private_class_method :paths_correspond?
 
@@ -360,6 +370,18 @@ def initialize(statement, include_path: nil)
     @include_path = clean(include_path) if include_path
   end
 
+  # Resolves any `..` in this include's own filepath against `anchor` (a directory
+  # path in the same representation `filepath` itself uses), returning a new instance
+  # of this same class if resolution actually changed anything, or this instance
+  # unchanged otherwise. A raw text scan -- unlike a real compiler, which resolves a
+  # directory-relative #include on its own while opening it -- has no way to know
+  # which real file its own literal directive text reaches until this runs.
+  def anchored(anchor)
+    resolved = PathMatcher.resolve_relative( @filepath, anchor: anchor )
+    return self if resolved == @filepath
+    return self.class.new( resolved, include_path: @include_path )
+  end
+
   # Method specialized by subclasses
   def to_s()
     # Simple string representation of class contents with no additional formatting or #include decoration

lib/ceedling/path_matcher.rb

@@ -60,6 +60,66 @@ def self.candidates(query, collection)
     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, `..`-free query ready for `.match`/`.resolve`/`.candidates`
+  # exactly as if it had been written that way to begin with. 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
+
+    resolved = segments(anchor)
+
+    query_segments.each do |segment|
+      if segment == '..'
+        if resolved.empty?
+          raise CeedlingException.new("Relative path reference '..' in '#{query}' goes outside the project.")
+        end
+        resolved.pop
+      else
+        resolved << segment
+      end
+    end
+
+    resolved.join('/')
+  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
+
   ### Private ###
 
   def self.absolute?(path)

lib/ceedling/preprocess/preprocessinator_includes_handler.rb

@@ -6,6 +6,7 @@
 # =========================================================================
 
 require 'ceedling/includes/includes'
+require 'ceedling/path_matcher'
 require 'ceedling/preprocess/preprocessinator_bare_includes_extractor'
 require 'ceedling/preprocess/preprocessinator_line_marker_includes_extractor'
 require 'ceedling/preprocess/c_preprocessor_conditionals'
@@ -192,7 +193,7 @@ def extract_user_includes_from_text(name:, filepath:, defines: [])
         cond_tracker.process_directive( line )
         next unless cond_tracker.active?
         _include = @include_factory.user_include_from_directive( line )
-        includes << _include if !_include.nil?
+        includes << _include.anchored( File.dirname( filepath ) ) if !_include.nil?
       end
     end
 
@@ -243,7 +244,7 @@ def extract_system_includes_from_text(name:, filepath:, defines: [])
         cond_tracker.process_directive( line )
         next unless cond_tracker.active?
         _include = @include_factory.system_include_from_directive( line )
-        includes << _include if !_include.nil?
+        includes << _include.anchored( File.dirname( filepath ) ) if !_include.nil?
       end
     end
 

lib/ceedling/preprocess/preprocessinator_line_marker_includes_extractor.rb

@@ -6,6 +6,7 @@
 # =========================================================================
 
 require 'ceedling/exceptions'
+require 'ceedling/path_matcher'
 require 'set'
 
 ##
@@ -164,6 +165,13 @@ def extract_includes(io:, filepath:, type:, max_depth:, test: nil)
         # Skip special markers like "<built-in>" and "<command-line>"
         next if filepath.start_with?('<')
 
+        # GCC forms a directory-relative quoted include's own line marker by
+        # concatenating the including file's directory onto the literal include
+        # text -- real and complete, but left uncanonicalized. Collapsing any ..
+        # here, once, means this path can correspond to the project's own real,
+        # ..-free file list the same way any other candidate already does.
+        filepath = PathMatcher.resolve_relative( filepath, anchor: '' )
+
         # Integer line number
         line_number = match[1].to_i