feat(spm): scaffold header search paths from header_mappings_dir

Community libs that lay headers out under a namespaced subdir and consume them
via that namespace — reanimated/worklets ship `apple/reanimated/...` and
`Common/cpp/reanimated/...` and `#import <reanimated/...>` — declare it with a
per-subspec `header_mappings_dir`. CocoaPods makes those includes resolve by
copying the headers into `Pods/Headers` preserving structure relative to the
mappings dir; SPM has no equivalent copy step, so `<reanimated/apple/sensor/X.h>`
(physically at `apple/reanimated/apple/sensor/X.h`) was unresolved and the
scaffolded target failed with "file not found".

Fix: for every subspec's `header_mappings_dir`, add `dirname(mappings_dir)` as a
header search path on the scaffolded target. That exposes the
`<basename(mappings_dir)>/...` namespace from the physical source tree (e.g.
`-I apple` makes `<reanimated/apple/sensor/X.h>` resolve). The podspec's literal
HEADER_SEARCH_PATHS never list these because CocoaPods relies on the copy step.

- read-podspec.js: collect ALL subspecs' header_mappings_dir into
  `headerMappingsDirs` (the existing singular `headerMappingsDir` is the merged
  value; the array is the union).
- scaffold-package-swift.js: add `dirname()` of each (skipping "." and
  non-existent dirs); bump SCAFFOLDER_VERSION 8 → 9 so already-scaffolded deps
  regenerate with the new search paths.
- spm-types.js: `headerMappingsDirs: Array<string>` on PodspecModel.
- Tests for the reanimated/worklets pattern, the non-existent-dir skip, and the
  single-segment ("." → skip) case.

Verified: re-scaffolding react-native-reanimated now auto-emits
`.headerSearchPath("Common/cpp")` + `.headerSearchPath("apple")`, and its own
`<reanimated/...>` headers resolve (build advances past them). 323 spm tests
pass. NOTE: a full reanimated build still needs the reanimated→worklets
cross-package dep and Hermes public headers in the artifacts (separate work).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: chrfalch

packages/react-native/scripts/spm/__tests__/scaffold-package-swift-test.js

@@ -33,6 +33,7 @@ function podspec(overrides /*: Object */ = {}) {
     privateHeaderFiles: [],
     excludeFiles: [],
     headerMappingsDir: null,
+    headerMappingsDirs: [],
     headerDir: null,
     frameworks: [],
     weakFrameworks: [],
@@ -83,6 +84,60 @@ describe('translatePodspecToSpmTarget', () => {
     expect(spec.swiftName).toBe('ReactNativeSafeAreaContext');
   });
 
+  it('adds dirname(header_mappings_dir) as a header search path so namespaced includes resolve (reanimated/worklets pattern)', () => {
+    // reanimated/worklets ship headers at `apple/reanimated/...` and
+    // `Common/cpp/reanimated/...` with per-subspec header_mappings_dir, and
+    // include them as `<reanimated/...>`. SPM has no header_mappings_dir copy
+    // step, so the parent of each mappings dir must be on the search path.
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rea-scaffold-'));
+    try {
+      fs.mkdirSync(path.join(root, 'apple', 'reanimated'), {recursive: true});
+      fs.mkdirSync(path.join(root, 'Common', 'cpp', 'reanimated'), {
+        recursive: true,
+      });
+      const model = podspec({
+        headerMappingsDirs: ['Common/cpp/reanimated', 'apple/reanimated'],
+      });
+      const spec = translatePodspecToSpmTarget(
+        model,
+        autolinkedDep({name: 'react-native-reanimated', root}),
+      );
+      expect(spec.headerSearchPaths).toContain('apple');
+      expect(spec.headerSearchPaths).toContain('Common/cpp');
+    } finally {
+      fs.rmSync(root, {recursive: true, force: true});
+    }
+  });
+
+  it('skips a header_mappings_dir whose parent dir does not exist on disk', () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rea-scaffold-'));
+    try {
+      const model = podspec({headerMappingsDirs: ['nope/reanimated']});
+      const spec = translatePodspecToSpmTarget(
+        model,
+        autolinkedDep({name: 'react-native-foo', root}),
+      );
+      expect(spec.headerSearchPaths).not.toContain('nope');
+    } finally {
+      fs.rmSync(root, {recursive: true, force: true});
+    }
+  });
+
+  it('does not add "." for a single-segment header_mappings_dir', () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rea-scaffold-'));
+    try {
+      fs.mkdirSync(path.join(root, 'ios'), {recursive: true});
+      const model = podspec({headerMappingsDirs: ['ios']});
+      const spec = translatePodspecToSpmTarget(
+        model,
+        autolinkedDep({name: 'react-native-foo', root}),
+      );
+      expect(spec.headerSearchPaths).not.toContain('.');
+    } finally {
+      fs.rmSync(root, {recursive: true, force: true});
+    }
+  });
+
   it('still uses toSwiftName(npm-name) even when header_dir is a plain identifier (matches autolinker registration)', () => {
     const model = podspec({headerDir: 'reanimated'});
     const spec = translatePodspecToSpmTarget(

packages/react-native/scripts/spm/read-podspec.js

@@ -471,6 +471,13 @@ function flattenSubspecs(rawSpec /*: RawSpec */) /*: PodspecModel */ {
     privateHeaderFiles: mergeArrayField('private_header_files'),
     excludeFiles: mergeArrayField('exclude_files'),
     headerMappingsDir: mergeStringField('header_mappings_dir'),
+    // ALL subspecs' header_mappings_dir values (not just the merged one). Each
+    // implies a header search path of its parent dir so namespaced includes
+    // (`<reanimated/apple/sensor/X.h>` for a header physically at
+    // `apple/reanimated/apple/sensor/X.h` with mappings dir `apple/reanimated`)
+    // resolve from the physical tree — CocoaPods does this via the
+    // header_mappings_dir copy step, which SPM has no equivalent for.
+    headerMappingsDirs: mergeArrayField('header_mappings_dir'),
     headerDir: mergeStringField('header_dir'),
     frameworks: mergeArrayField('frameworks'),
     weakFrameworks: mergeArrayField('weak_frameworks'),

packages/react-native/scripts/spm/scaffold-package-swift.js

@@ -83,7 +83,7 @@ const {log} = makeLogger('scaffold-package-swift');
 // v8: relative app paths (codegen / xcframeworks) are now computed from the
 // autolinker's libs/<SwiftName> symlink location instead of the real dep.root,
 // fixing a doubled-path resolution failure on fresh SwiftPM resolves.
-const SCAFFOLDER_VERSION = 8;
+const SCAFFOLDER_VERSION = 9;
 const SCAFFOLDER_VERSION_LINE_RE = /^\/\/ AUTO-SCAFFOLDED-VERSION: (\d+)$/m;
 
 const AUTOGEN_MARKER =
@@ -173,6 +173,27 @@ function translatePodspecToSpmTarget(
     }
   }
 
+  // header_mappings_dir → search path. CocoaPods exposes a subspec's headers
+  // under `<basename(mappings_dir)>/...` by copying them into Pods/Headers
+  // preserving structure relative to the mappings dir. SPM has no such copy
+  // step, so namespaced includes like `<reanimated/apple/sensor/X.h>` (header
+  // physically at `apple/reanimated/apple/sensor/X.h`, mappings dir
+  // `apple/reanimated`) only resolve if the mappings dir's PARENT (`apple`) is
+  // on the search path. Add dirname() of every subspec's mappings dir.
+  for (const mappingsDir of model.headerMappingsDirs) {
+    const parent = path.posix.dirname(mappingsDir.replace(/^\.\//, ''));
+    // dirname of a single-segment dir is "." (root) — already implicitly
+    // searched; skip it and anything that doesn't exist on disk.
+    if (
+      parent.length > 0 &&
+      parent !== '.' &&
+      !headerSearchPaths.includes(parent) &&
+      fs.existsSync(path.join(dep.root, parent))
+    ) {
+      headerSearchPaths.push(parent);
+    }
+  }
+
   // Bucket dependencies. React-Core / React-jsi / RCT-Folly / glog etc. ALL
   // collapse to a single `.product(name: "ReactNative", package: "ReactNative")`
   // reference because they're bundled in the prebuilt React.xcframework.

packages/react-native/scripts/spm/spm-types.js

@@ -346,6 +346,10 @@ export type PodspecModel = {
   privateHeaderFiles: Array<string>,
   excludeFiles: Array<string>,
   headerMappingsDir: ?string,
+  // Every subspec's header_mappings_dir (union). dirname() of each is added as
+  // a header search path so `<namespace/...>` includes resolve from the
+  // physical source tree (SPM has no header_mappings_dir copy step).
+  headerMappingsDirs: Array<string>,
   headerDir: ?string,
   frameworks: Array<string>,
   weakFrameworks: Array<string>,