feat(spm): nightly cache freshness, spm.name override, scanner hardening

* Cache slot is keyed on the resolved nightly hash for 1000.0.0 / nightly
  versions, so each published nightly is its own slot. Stable versions
  pass through unchanged. resolveCacheSlotVersion() is shared between
  setup-apple-spm and sync-spm-autolinking; sync now also re-points the
  symlinks to the expected slot on every run.

* SPM manifests carry the resolved slot path as a string literal in
  xcfwHeaders / depsHeaders (synth Package.swift + codegen template), so
  SPM's manifest hash bumps on every slot change — Xcode re-resolves and
  re-copies React.framework instead of sticking on a stale BUILT_PRODUCTS
  copy. xcframeworks/Package.swift carries a slot-identifier comment as
  a belt-and-braces invalidator (binary target paths stay relative per
  SPM's rules). Codegen template now goes through a render step with
  __SPM_XCFW_HEADERS_EXPR__ / __SPM_DEPS_HEADERS_EXPR__ placeholders.

* Library authors can override the auto-derived Swift target name via
  `spm.name` in react-native.config.js (e.g. 'worklets' instead of
  'ReactNativeWorklets'). expand-spm-dependencies validates the value
  and throws on collisions across deps. Symmetric with the existing
  `name` field on spmModules.

* scanProjectFiles skips files named Package.swift, plus `build/`,
  `node_modules/`, `Pods/`, `*.xcodeproj`, `*.xcworkspace`, and Xcode
  test-target dirs matching /(?:UI)?Tests?$/i — so the generated
  xcodeproj doesn't pull SPM manifests or XCTest sources into the app
  target when run from an RN project root.

Author: chrfalch

packages/react-native/scripts/codegen/templates/Package.swift.spm-template

@@ -20,11 +20,16 @@
 import PackageDescription
 import Foundation
 
-// Derive all paths from this file's location – no machine-specific absolute paths.
+// Derive all paths from this file's location.
 let packageDir = URL(fileURLWithPath: #filePath).deletingLastPathComponent().path
 let appRoot = URL(fileURLWithPath: packageDir + "/../../..").standardized.path
-let xcfwHeaders = URL(fileURLWithPath: appRoot + "/build/xcframeworks/React.xcframework").resolvingSymlinksInPath().path + "/Headers"
-let depsHeaders = URL(fileURLWithPath: appRoot + "/build/xcframeworks/ReactNativeDependencies.xcframework").resolvingSymlinksInPath().path + "/Headers"
+// xcfwHeaders / depsHeaders: when the install step resolves the current
+// cache-slot symlinks, the placeholders below are replaced with absolute
+// string literals so SPM's manifest hash bumps on every slot change
+// (otherwise the cached `.resolvingSymlinksInPath()` value would stick on
+// the prior slot). Unsubstituted, falls back to the runtime expression.
+let xcfwHeaders = __SPM_XCFW_HEADERS_EXPR__
+let depsHeaders = __SPM_DEPS_HEADERS_EXPR__
 let vfsOverlay = appRoot + "/build/xcframeworks/React-VFS.yaml"
 
 let package = Package(

packages/react-native/scripts/setup-apple-spm.js

@@ -60,7 +60,10 @@
  * After running: open <AppName>-SPM.xcodeproj in Xcode.
  */
 
-const {main: downloadArtifacts} = require('./spm/download-spm-artifacts');
+const {
+  main: downloadArtifacts,
+  resolveCacheSlotVersion,
+} = require('./spm/download-spm-artifacts');
 const {main: generateAutolinking} = require('./spm/generate-spm-autolinking');
 const {
   generateAutolinkingConfig,
@@ -75,6 +78,7 @@ const {
   findProjectRoot,
   makeLogger,
   readPackageJson,
+  renderCodegenTemplate,
   resolveAndWriteVFSOverlay,
 } = require('./spm/spm-utils');
 const {execSync} = require('child_process');
@@ -373,7 +377,11 @@ function runCodegenStep(
     'Package.swift.spm-template',
   );
   if (codegenSucceeded && fs.existsSync(path.dirname(codegenPkgSwift))) {
-    fs.copyFileSync(spmTemplate, codegenPkgSwift);
+    const rendered = renderCodegenTemplate(
+      fs.readFileSync(spmTemplate, 'utf8'),
+      appRoot,
+    );
+    fs.writeFileSync(codegenPkgSwift, rendered, 'utf8');
     log('Installed SPM codegen template → build/generated/ios/Package.swift');
   }
 }
@@ -446,10 +454,16 @@ async function ensureArtifacts(
   version /*: string */,
   artifactsDir /*: string | null */,
 ) /*: Promise<string | null> */ {
+  // Resolve the cache-slot version before computing the cache dir. For dev /
+  // nightly labels this is the actual nightly hash, so each nightly gets its
+  // own slot and a new nightly invalidates the old slot automatically. Stable
+  // versions pass through unchanged.
+  const rawVersion = args.version ?? version;
+  const slotVersion = await resolveCacheSlotVersion(rawVersion);
   const resolvedArtifactsDir =
     artifactsDir != null
       ? path.resolve(artifactsDir)
-      : defaultCacheDir(args.version ?? version, args.flavor);
+      : defaultCacheDir(slotVersion, args.flavor);
 
   if (args.forceDownload && resolvedArtifactsDir != null) {
     log('Clearing cached artifacts (--force-download)...');
@@ -467,10 +481,10 @@ async function ensureArtifacts(
     !fs.existsSync(artifactsJsonPath);
 
   if (needsDownload === true && resolvedArtifactsDir != null) {
-    log('Downloading xcframework artifacts...');
+    log(`Downloading xcframework artifacts (slot: ${slotVersion})...`);
     await downloadArtifacts([
       '--version',
-      args.version ?? version,
+      rawVersion,
       '--flavor',
       args.flavor,
       '--output',
@@ -634,11 +648,10 @@ async function main(argv /*:: ?: Array<string> */) /*: Promise<void> */ {
   const scriptsDir = path.join(reactNativeRoot, 'scripts');
   const version = determineVersion(args, reactNativeRoot);
   log(`React Native version: ${version}`);
-  if (args.localXcframework == null) {
-    log(
-      `Artifact cache:       ${displayPath(defaultCacheDir(args.version ?? version, args.flavor))}`,
-    );
-  }
+  // The artifact cache directory is resolved later in ensureArtifacts so the
+  // nightly hash can be folded in for dev / nightly labels. That branch logs
+  // either "Downloading xcframework artifacts (slot: ...)" or
+  // "Artifacts already present in ...".
 
   if (action === 'codegen') {
     runCodegenStep(projectRoot, appRoot, scriptsDir, false);

packages/react-native/scripts/spm/__tests__/expand-spm-dependencies-test.js

@@ -33,7 +33,11 @@
  * I/O is injected (readConfig, resolveDep) so the tests stay pure.
  */
 
-const {expandSpmDependencies} = require('../expand-spm-dependencies');
+const {
+  expandSpmDependencies,
+  resolveSwiftName,
+} = require('../expand-spm-dependencies');
+const {toSwiftName} = require('../spm-utils');
 
 function makeReadConfig(configs /*: {[string]: ?Object} */) {
   return (root /*: string */) =>
@@ -52,13 +56,15 @@ function makeResolveDep(resolutions /*: {[string]: ?string} */) {
 // ---------------------------------------------------------------------------
 
 describe('expandSpmDependencies', () => {
-  it('returns direct deps unchanged when none declare spm.dependencies', () => {
+  it('returns direct deps with auto-derived swiftName when none declare spm.dependencies', () => {
     const direct = [{name: 'a', root: '/a', platforms: {ios: {}}}];
     const result = expandSpmDependencies(direct, {
       readConfig: makeReadConfig({'/a': {}}),
       resolveDep: makeResolveDep({}),
     });
-    expect(result).toEqual([{...direct[0], spmDependencies: []}]);
+    expect(result).toEqual([
+      {...direct[0], swiftName: toSwiftName('a'), spmDependencies: []},
+    ]);
   });
 
   it('pulls in one transitive dep declared by a direct dep', () => {
@@ -247,4 +253,123 @@ describe('expandSpmDependencies', () => {
     });
     expect(receivedFromRoot).toBe('/apple');
   });
+
+  // -------------------------------------------------------------------------
+  // swiftName resolution: each dep gets a Swift target name on the way out.
+  // Default is toSwiftName(npmName); the dep's react-native.config.js
+  // `spm.name` overrides it. Required for libraries whose import prefix
+  // differs from the auto-derived name (e.g. `react-native-worklets`
+  // publishes headers under `<worklets/...>`).
+  // -------------------------------------------------------------------------
+
+  it('populates swiftName via toSwiftName when no spm.name override is set', () => {
+    const direct = [
+      {name: 'react-native-foo', root: '/foo', platforms: {ios: {}}},
+    ];
+    const [foo] = expandSpmDependencies(direct, {
+      readConfig: makeReadConfig({'/foo': {}}),
+      resolveDep: makeResolveDep({}),
+    });
+    expect(foo.swiftName).toBe(toSwiftName('react-native-foo'));
+    expect(foo.swiftName).toBe('ReactNativeFoo');
+  });
+
+  it('uses spm.name as swiftName when the direct dep declares one', () => {
+    const direct = [
+      {name: 'react-native-worklets', root: '/w', platforms: {ios: {}}},
+    ];
+    const [w] = expandSpmDependencies(direct, {
+      readConfig: makeReadConfig({'/w': {spm: {name: 'worklets'}}}),
+      resolveDep: makeResolveDep({}),
+    });
+    expect(w.swiftName).toBe('worklets');
+  });
+
+  it('applies spm.name override to transitive deps too', () => {
+    const direct = [
+      {name: 'react-native-reanimated', root: '/r', platforms: {ios: {}}},
+    ];
+    const result = expandSpmDependencies(direct, {
+      readConfig: makeReadConfig({
+        '/r': {
+          dependency: {platforms: {ios: {}}},
+          spm: {name: 'reanimated', dependencies: ['react-native-worklets']},
+        },
+        '/w': {
+          dependency: {platforms: {ios: {}}},
+          spm: {name: 'worklets'},
+        },
+      }),
+      resolveDep: makeResolveDep({'react-native-worklets': '/w'}),
+    });
+    const reanimated = result.find(d => d.name === 'react-native-reanimated');
+    const worklets = result.find(d => d.name === 'react-native-worklets');
+    expect(reanimated.swiftName).toBe('reanimated');
+    expect(worklets.swiftName).toBe('worklets');
+  });
+
+  it('throws on swiftName collision between two deps (override vs auto-derived)', () => {
+    // 'react-native-worklets' would auto-derive to 'ReactNativeWorklets', but
+    // here a second dep overrides its spm.name to that same value.
+    const direct = [
+      {name: 'react-native-worklets', root: '/w', platforms: {ios: {}}},
+      {name: 'other-package', root: '/o', platforms: {ios: {}}},
+    ];
+    expect(() =>
+      expandSpmDependencies(direct, {
+        readConfig: makeReadConfig({
+          '/w': {},
+          '/o': {spm: {name: 'ReactNativeWorklets'}},
+        }),
+        resolveDep: makeResolveDep({}),
+      }),
+    ).toThrow(/ReactNativeWorklets/);
+  });
+
+  it('rejects empty-string spm.name with a clear error citing the npm name', () => {
+    const direct = [{name: 'a', root: '/a', platforms: {ios: {}}}];
+    expect(() =>
+      expandSpmDependencies(direct, {
+        readConfig: makeReadConfig({'/a': {spm: {name: ''}}}),
+        resolveDep: makeResolveDep({}),
+      }),
+    ).toThrow(/'a' has an invalid 'spm.name'/);
+  });
+
+  it('rejects non-string spm.name (e.g. number, object) with a clear error', () => {
+    const direct = [{name: 'a', root: '/a', platforms: {ios: {}}}];
+    expect(() =>
+      expandSpmDependencies(direct, {
+        readConfig: makeReadConfig({'/a': {spm: {name: 42}}}),
+        resolveDep: makeResolveDep({}),
+      }),
+    ).toThrow(/invalid 'spm.name'/);
+  });
+
+  it('rejects spm.name with disallowed characters (spaces, slashes, dots)', () => {
+    expect(() =>
+      resolveSwiftName('a', {spm: {name: 'foo bar'}}),
+    ).toThrow(/invalid 'spm.name'/);
+    expect(() => resolveSwiftName('a', {spm: {name: 'foo/bar'}})).toThrow(
+      /invalid 'spm.name'/,
+    );
+    expect(() => resolveSwiftName('a', {spm: {name: 'foo.bar'}})).toThrow(
+      /invalid 'spm.name'/,
+    );
+  });
+
+  it('accepts lowercase-with-hyphen and CamelCase spm.name values', () => {
+    expect(resolveSwiftName('a', {spm: {name: 'reanimated'}})).toBe(
+      'reanimated',
+    );
+    expect(resolveSwiftName('a', {spm: {name: 'hermes-engine'}})).toBe(
+      'hermes-engine',
+    );
+    expect(resolveSwiftName('a', {spm: {name: 'RNWorklets'}})).toBe(
+      'RNWorklets',
+    );
+    expect(resolveSwiftName('a', {spm: {name: 'react_native_foo'}})).toBe(
+      'react_native_foo',
+    );
+  });
 });

packages/react-native/scripts/spm/__tests__/generate-spm-autolinking-test.js

@@ -610,3 +610,52 @@ describe('generateSynthPackageSwift (sources: allowlist)', () => {
     expect(b).not.toContain('sources: [');
   });
 });
+
+// ---------------------------------------------------------------------------
+// spm.name override — verifies that a non-default Swift name (set by a
+// library author via react-native.config.js `spm.name`) flows verbatim into
+// the synth Package.swift: target name, library name, product references,
+// and sibling package paths all use the override.
+// ---------------------------------------------------------------------------
+
+describe('generateSynthPackageSwift (spm.name override)', () => {
+  it('uses the override Swift name for the target, library, and product', () => {
+    const result = generateSynthPackageSwift({
+      swiftName: 'worklets', // override from spm.name (default would be "ReactNativeWorklets")
+      hasReactDep: true,
+      hasXcfwHeaders: true,
+      targetPath: 'root',
+      appRootAbsolute: '/abs/app',
+      autogenHeadersAbsolute: '/abs/app/headers',
+    });
+    expect(result).toContain('name: "worklets"');
+    expect(result).toContain('.library(name: "worklets"');
+    expect(result).toContain('targets: ["worklets"]');
+    // The auto-derived name must not appear anywhere.
+    expect(result).not.toContain('ReactNativeWorklets');
+  });
+
+  it('emits the override name in sibling .package(...) and .product(...) refs when a transitive dep was overridden', () => {
+    // Simulates the case where reanimated declares spm.dependencies on
+    // react-native-worklets, and worklets has set spm.name: "worklets".
+    // The autolinker's swiftNameByNpm map resolves the transitive to
+    // "worklets" before passing it to generateSynthPackageSwift.
+    const result = generateSynthPackageSwift({
+      swiftName: 'reanimated',
+      hasReactDep: true,
+      hasXcfwHeaders: true,
+      targetPath: 'root',
+      appRootAbsolute: '/abs/app',
+      autogenHeadersAbsolute: '/abs/app/headers',
+      spmDependencies: [{swiftName: 'worklets'}],
+      siblingSynthAbsolutePaths: {worklets: '/abs/app/packages/worklets'},
+    });
+    expect(result).toContain(
+      '.package(name: "worklets", path: "/abs/app/packages/worklets")',
+    );
+    expect(result).toContain(
+      '.product(name: "worklets", package: "worklets")',
+    );
+    expect(result).not.toContain('ReactNativeWorklets');
+  });
+});

packages/react-native/scripts/spm/__tests__/spm-pbxproj-test.js

@@ -126,6 +126,69 @@ describe('scanProjectFiles', () => {
       plists: [],
     });
   });
+
+  // -------------------------------------------------------------------------
+  // SPM-collision guards — files named Package.swift are SPM manifests, never
+  // app target sources. swiftc refuses to compile two files with the same
+  // basename in one target, so the legacy bug here was: scanning an appRoot
+  // like ios/ recursively pulled in Package.swift from build/xcframeworks/,
+  // build/generated/ios/, and the app's own Package.swift sibling — breaking
+  // every build with "Filename Package.swift used twice".
+  // -------------------------------------------------------------------------
+
+  it('excludes files named Package.swift even at the source root', () => {
+    fs.writeFileSync(path.join(tempDir, 'AppDelegate.swift'), '');
+    fs.writeFileSync(path.join(tempDir, 'Package.swift'), '');
+    const result = scanProjectFiles(tempDir);
+    expect(result.sources).toEqual(['AppDelegate.swift']);
+  });
+
+  it('skips the build/ directory so nested Package.swift / generated artifacts never enter the source list', () => {
+    fs.writeFileSync(path.join(tempDir, 'AppDelegate.swift'), '');
+    fs.mkdirSync(path.join(tempDir, 'build', 'xcframeworks'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tempDir, 'build', 'xcframeworks', 'Package.swift'),
+      '',
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'build', 'xcframeworks', 'Generated.swift'),
+      '',
+    );
+    const result = scanProjectFiles(tempDir);
+    expect(result.sources).toEqual(['AppDelegate.swift']);
+  });
+
+  it('skips node_modules/, Pods/, and *.xcodeproj subdirectories', () => {
+    fs.writeFileSync(path.join(tempDir, 'Real.m'), '');
+    for (const skip of ['node_modules', 'Pods']) {
+      fs.mkdirSync(path.join(tempDir, skip));
+      fs.writeFileSync(path.join(tempDir, skip, 'Hidden.m'), '');
+    }
+    fs.mkdirSync(path.join(tempDir, 'Helloworld.xcodeproj'));
+    fs.writeFileSync(
+      path.join(tempDir, 'Helloworld.xcodeproj', 'embedded.swift'),
+      '',
+    );
+    const result = scanProjectFiles(tempDir);
+    expect(result.sources).toEqual(['Real.m']);
+  });
+
+  it('skips Xcode test target dirs (*Tests, *UITests) so XCTest-only files do not enter the app target', () => {
+    fs.writeFileSync(path.join(tempDir, 'AppDelegate.swift'), '');
+    for (const dir of ['HelloWorldTests', 'HelloWorldUITests', 'AppTest']) {
+      fs.mkdirSync(path.join(tempDir, dir));
+      fs.writeFileSync(path.join(tempDir, dir, 'Suite.m'), '');
+    }
+    // Directories whose names CONTAIN "test" but don't end with Test(s)/UITests
+    // are legitimate sources — don't over-exclude.
+    fs.mkdirSync(path.join(tempDir, 'TestUtils'));
+    fs.writeFileSync(path.join(tempDir, 'TestUtils', 'Helper.m'), '');
+    const result = scanProjectFiles(tempDir);
+    expect(result.sources.sort()).toEqual([
+      'AppDelegate.swift',
+      'TestUtils/Helper.m',
+    ]);
+  });
 });
 
 // ---------------------------------------------------------------------------