fix(spm): alias self-managed lib refs via libs/<Name> to avoid SPM identity collision

A community library that ships its `Package.swift` inside an `ios/` subdir
(common convention — e.g. @chrfalch/react-native-calculator/ios/Package.swift)
collides with our codegen package at build/generated/ios/Package.swift:
both have path basename "ios", which is what SPM uses to derive package
identity. SPM rejects with "Conflicting identity for ios". Worse, two libs
that both ship Package.swift in ios/ collide with each other regardless of
where our codegen lives.

The fix routes every self-managed dep through a uniquely-named symlink:

  build/generated/autolinking/
    Package.swift
    libs/                              # NEW
      Calculator                  → <abs>/node_modules/@chrfalch/.../ios
      ReactNativeSafeAreaContext  → <abs>/node_modules/react-native-safe-area-context
    packages/                          # unchanged (wrapper synths, already unique)

The aggregator emits `.package(name: ..., path: "libs/<SwiftName>")` instead
of an absolute path. SPM derives identity from the symlink basename — the
Swift module name — which is guaranteed unique per autolinker construction.

`libs/` is wiped + repopulated on every autolinker run, so stale entries
for uninstalled deps don't linger.

Also reverts an aborted exploration that moved the codegen Package.swift to
build/generated/codegen/ — the lib-aliases approach is the better answer
because it solves lib-vs-lib collisions, not just codegen-vs-lib.

Author: chrfalch

packages/react-native/scripts/spm/__doc__/rfc-spm-xcframework.md

@@ -117,7 +117,11 @@ needed.
 │      │   ├── autolinking/       (generated)      │
 │      │   │   ├── Package.swift                   │
 │      │   │   ├── autolinking.json                │
-│      │   │   └── packages/      (synth wrappers) │
+│      │   │   ├── packages/      (synth wrappers) │
+│      │   │   └── libs/          (alias symlinks  │
+│      │   │                       for self-managed│
+│      │   │                       deps; basename  │
+│      │   │                       = SwiftName)    │
 │      │   └── ios/               (codegen)        │
 │      └── xcframeworks/          (symlinks)       │
 │          ├── Package.swift                       │
@@ -310,6 +314,28 @@ Each entry becomes a target in `autolinked/Package.swift`. Sources outside the
 autolinked directory are mirrored with **file-level symlinks** (SPM rejects
 directory symlinks that resolve outside the package root).
 
+### Self-managed deps and package identity
+
+A community library that ships its own `Package.swift` (instead of being
+wrapped by the autolinker) is referenced directly. SPM derives the package
+identity for a `.package(path:)` dependency from the path's basename — and
+a common convention is to ship the manifest inside an `ios/` subdir
+(`<dep>/ios/Package.swift`). Two libs following that convention would both
+have identity `"ios"`, and SPM rejects with `Conflicting identity for ios`.
+
+To make every reference globally unique by construction, the autolinker
+materializes each self-managed dep as a symlink at
+`build/generated/autolinking/libs/<SwiftName>/` pointing at the dep's real
+manifest dir. The aggregator `Package.swift` then references the symlink
+(`path: "libs/<SwiftName>"`), and SPM uses the symlink basename — the
+library's Swift module name — as the package identity. Swift module names
+are already unique per dep (deriving from the npm package name), so this
+sidesteps the collision in all cases, including against the codegen
+package at `build/generated/ios/`.
+
+The `libs/` directory is wiped and recreated on every autolinker run, so
+stale aliases for uninstalled deps disappear automatically.
+
 ### Third-party library support
 
 The current implementation handles React Native's own frameworks and app-local

packages/react-native/scripts/spm/__doc__/spm-scripts.md

@@ -76,7 +76,10 @@ my-app/ios/
       autolinking/                 <-- gitignored (regenerated at build time)
         Package.swift
         autolinking.json
-        packages/                  <-- package wrappers for native modules
+        packages/                  <-- synth wrappers for autolinker-managed deps
+        libs/                      <-- symlinks to self-managed deps' Package.swift
+                                       dirs, named by Swift module so SPM
+                                       package identity stays unique
         headers/                   <-- generated header symlinks
       ios/                         <-- gitignored, codegen output
     xcframeworks/                  <-- gitignored, symlinks to cached artifacts
@@ -177,6 +180,21 @@ Each entry becomes a target in `build/generated/autolinking/Package.swift`.
 Sources outside `build/generated/autolinking/` are automatically mirrored with
 file-level symlinks.
 
+## Self-managed community packages
+
+A community library that ships its own `Package.swift` is referenced
+directly by the autolinker instead of being wrapped. To keep SPM's
+package identity (which it derives from the path basename) unique across
+deps — even when several libs put their manifest inside an `ios/` subdir
+— each self-managed dep is exposed through a uniquely-named symlink at
+`build/generated/autolinking/libs/<SwiftName>/`. The aggregator
+`Package.swift` references that path, so two libs both shipping
+`<dep>/ios/Package.swift` never collide on identity `"ios"`.
+
+The `libs/` directory is wiped and recreated on every autolinker run,
+so deleting a dep via `npm uninstall` cleans up the alias automatically
+on the next build.
+
 ## Header Resolution
 
 React Native uses CocoaPods-style imports (`#import <React/RCTBridge.h>`) that

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

@@ -1180,8 +1180,16 @@ function main(argv /*:: ?: Array<string> */) /*: void */ {
 
   const packagesDir = path.join(outputDir, 'packages');
   const headersDir = path.join(outputDir, 'headers');
+  // libs/<SwiftName>/ symlinks for self-managed deps. The symlink basename
+  // is the Swift module name (guaranteed unique per dep), so SPM's
+  // path-basename-based package identity never collides — even when two
+  // libs ship their own Package.swift inside `ios/` (a common convention).
+  // Wiped on every run; populated below as self-managed deps are visited.
+  const libsDir = path.join(outputDir, 'libs');
   fs.mkdirSync(packagesDir, {recursive: true});
   fs.mkdirSync(headersDir, {recursive: true});
+  fs.rmSync(libsDir, {recursive: true, force: true});
+  fs.mkdirSync(libsDir, {recursive: true});
 
   const wrapperDirs /*: Map<string, string> */ = new Map();
   const selfManagedDirs /*: Map<string, string> */ = new Map();
@@ -1254,11 +1262,16 @@ function main(argv /*:: ?: Array<string> */) /*: void */ {
       // outside of ios/), and cross-package consumers should still resolve
       // them via the centralized -I path.
       linkHeaderTree(absSource, path.join(headersDir, target.name));
-      // packagePath is the directory containing Package.swift — for the
-      // nested layout this is <dep>/ios, not the dep root.
+      // Route the manifest reference through a uniquely-named symlink at
+      // libs/<SwiftName>/ so SPM derives the package identity from the
+      // alias basename. Two libs that both ship Package.swift inside their
+      // own `ios/` subdir would otherwise collide with identity "ios".
+      const realPackageDir = selfManagedDirs.get(target.name) ?? absSource;
+      const aliasPath = path.join(libsDir, target.name);
+      ensureSymlink(aliasPath, realPackageDir);
       aggregatorPackageDeps.push({
         swiftName: target.name,
-        packagePath: selfManagedDirs.get(target.name) ?? absSource,
+        packagePath: `libs/${target.name}`,
       });
       continue;
     }