fix: resolve cross-package C++ header staging issue (Issue #38)

CRITICAL FIX: Properly stage local CcInfo headers for cross-package dependencies

Root Cause Analysis:
- Code intentionally excluded CcInfo headers from staging, assuming they were external libraries
- This broke local cross-package dependencies using relative includes like #include "foundation/types.h"
- Headers within same component also needed directory structure preservation

Solution:
1. Modified dependency collection logic in cpp/defs.bzl:
   - External CcInfo headers (path contains "external/") → Use include paths only (no staging)
   - Local CcInfo headers (same workspace) → Stage with directory structure for relative includes

2. Enhanced header staging in file_ops_actions.bzl:
   - Preserve directory structure for all headers to support relative includes
   - Handle cases where source files use #include "foundation/types.h" patterns

Testing:
- ✅ foundation_lib builds successfully with preserved directory structure
- ✅ consumer_component successfully includes cross-package headers
- ✅ External library dependencies continue to work via include paths

Impact:
- Resolves Issue #38 cross-package header staging problems
- Maintains backward compatibility for external library dependencies
- Enables proper modular C++ component development

Author: avrabe

cpp/defs.bzl

@@ -88,15 +88,26 @@ def _cpp_component_impl(ctx):
                 elif file.extension == "a":
                     dep_libraries.append(file)
 
-        # Extract includes from CcInfo for proper transitive dependencies
-        # but DON'T copy external headers to workspace (they use original paths)
+        # Extract includes and headers from CcInfo for proper transitive dependencies
+        # CRITICAL FIX for Issue #38: Distinguish between external vs local CcInfo headers
         if CcInfo in dep:
             cc_info = dep[CcInfo]
 
             # Add all types of include paths (direct, system, and quote includes)
             dep_includes.extend(cc_info.compilation_context.includes.to_list())
             dep_includes.extend(cc_info.compilation_context.system_includes.to_list())
             dep_includes.extend(cc_info.compilation_context.quote_includes.to_list())
+            
+            # CRITICAL FIX: Stage local CcInfo headers for cross-package dependencies
+            # External libraries (path contains "external/") don't need staging - use original paths
+            # Local libraries (same workspace) need staging for relative includes to work
+            for hdr in cc_info.compilation_context.headers.to_list():
+                if hdr.extension in ["h", "hpp", "hh", "hxx"]:
+                    # Check if this is an external dependency or local cross-package dependency
+                    if "external/" not in hdr.path:
+                        # Local cross-package header - stage it for relative includes to work
+                        dep_headers.append(hdr)
+                    # External headers are handled via include paths only (no staging needed)
 
     # Generate bindings directory
     bindings_dir = ctx.actions.declare_directory(ctx.attr.name + "_bindings")
@@ -482,7 +493,7 @@ def _cc_component_library_impl(ctx):
     # Output library
     library = ctx.actions.declare_file("lib{}.a".format(ctx.attr.name))
 
-    # Collect dependency headers
+    # Collect dependency headers with proper cross-package staging
     dep_headers = []
     for dep in ctx.attr.deps:
         # Check DefaultInfo first for direct file access (cc_component_library outputs)
@@ -491,12 +502,18 @@ def _cc_component_library_impl(ctx):
                 if file.extension in ["h", "hpp", "hh", "hxx"]:
                     dep_headers.append(file)
 
-        # For CcInfo dependencies (external libraries), don't copy headers to workspace
-        # since they already provide proper include paths. Only copy headers from
-        # DefaultInfo (our own cc_component_library targets that need cross-package staging)
-        # if CcInfo in dep:
-        #     cc_info = dep[CcInfo]
-        #     dep_headers.extend(cc_info.compilation_context.headers.to_list())
+        # CRITICAL FIX for Issue #38: Stage local CcInfo headers for cross-package dependencies
+        # External libraries (path contains "external/") don't need staging - use original paths
+        # Local libraries (same workspace) need staging for relative includes to work
+        if CcInfo in dep:
+            cc_info = dep[CcInfo]
+            for hdr in cc_info.compilation_context.headers.to_list():
+                if hdr.extension in ["h", "hpp", "hh", "hxx"]:
+                    # Check if this is an external dependency or local cross-package dependency
+                    if "external/" not in hdr.path:
+                        # Local cross-package header - stage it for relative includes to work
+                        dep_headers.append(hdr)
+                    # External headers are handled via include paths only (no staging needed)
 
     # Set up workspace with proper header staging (CRITICAL FIX for issue #38)
     work_dir = setup_cpp_workspace_action(

tools/bazel_helpers/file_ops_actions.bzl

@@ -281,24 +281,26 @@ def setup_cpp_workspace_action(ctx, sources, headers, bindings_dir = None, dep_h
         "dependencies": [],
     }
 
-    # For local headers within the same component, use basename only for local headers
-    # This matches how the source files include them (e.g., #include "simd_utils.h")
-    # But preserve directory structure for cross-package headers
+    # CRITICAL FIX for Issue #38: Preserve directory structure for all headers
+    # Headers need their directory structure preserved if source files include them with paths
     for hdr in headers:
-        relative_path = hdr.basename  # Default to basename for local headers
-
-        # Check if this header is in a different package/directory structure
-        # that requires preserving path (cross-package dependencies)
-        if "/test/" in hdr.short_path or "/external/" in hdr.path:
-            # For cross-package headers, preserve some directory structure
-            path_parts = hdr.short_path.split("/")
-            if len(path_parts) >= 2:
-                # Take the last 2 parts to preserve subdirectory structure
-                relative_path = "/".join(path_parts[-2:])
+        # Always preserve directory structure by using short_path
+        # This handles cases where source files use #include "foundation/types.h"
+        relative_path = hdr.short_path
+        
+        # For headers within the current target's directory, preserve the relative structure
+        # This ensures "foundation/types.h" includes work correctly
+        path_parts = relative_path.split("/")
+        if len(path_parts) >= 2:
+            # Preserve the directory structure (e.g., "foundation/types.h")
+            relative_path = "/".join(path_parts[-2:])
+        else:
+            # Single-level headers use basename
+            relative_path = hdr.basename
 
         config["headers"].append({
             "source": hdr,
-            "destination": relative_path,  # Use basename for local headers
+            "destination": relative_path,  # Preserve directory structure
             "preserve_permissions": False,
         })