@depup/react-native 0.86.2-depup.0 → 0.87.0-depup.0

package/scripts/spm/__doc__/spm-autolinking-plugins.md

@@ -0,0 +1,244 @@
+# SwiftPM Autolinking Plugins (Preview)
+
+> **Preview / unstable contract.** The discovery mechanism and the plugin
+> function's context/return shape may change while the first consumers (Expo)
+> validate it. Pin to a React Native version if you depend on it.
+
+How a framework with its own module system — Expo is the first consumer —
+contributes to the SwiftPM autolinking graph that `npx react-native spm`
+generates. See [spm-scripts.md](./spm-scripts.md) for the base tool.
+
+## Why a plugin (not a static list or a post-process)
+
+The documented extension points don't cover a framework:
+
+- `spm.modules` in `react-native.config.js` is a **static** list of simple
+  source modules. A framework discovers its modules **dynamically** (scanning
+  `node_modules`), generates a **module registry**, and ships mixed
+  Swift/ObjC/C++ modules (e.g. `ExpoModulesCore`) that `spm scaffold` can't
+  handle.
+- A one-shot **post-process** of the generated `Package.swift` is **clobbered
+  on the next sync**: the Xcode [auto-sync build phase](./spm-scripts.md#auto-sync-build-phase)
+  re-runs autolinking on every dependency change. A framework's contribution
+  must run *whenever autolinking runs*.
+
+A plugin is exactly that. It is invoked from `generate-spm-autolinking.js`'s
+`main()` — the single function that both `add` / `update` **and** the
+build-time `sync` call — so the contribution is regenerated on every build and
+never goes stale.
+
+(This is the SwiftPM analog of the seams CocoaPods gave Expo: the Podfile,
+`use_expo_modules!`, and `react_native_post_install` hooks.)
+
+## Discovery — transitive, zero app config
+
+A dependency opts in from its **own** `react-native.config.js`, so installing
+the framework is enough (mirrors how CocoaPods pulls in `use_expo_modules!`
+transitively):
+
+```js
+// node_modules/expo/react-native.config.js
+module.exports = {
+  spm: {autolinkingPlugin: './spm/autolinking-plugin.js'},
+};
+```
+
+The autolinker already walks every dependency's `react-native.config.js`; any
+that declares `spm.autolinkingPlugin` is `require`d and invoked. No app-level
+registration or allowlist is required.
+
+**Opt-out escape hatch.** An app can exclude a plugin from its own
+`react-native.config.js`:
+
+```js
+module.exports = {
+  spm: {denyPlugins: ['some-framework']}, // npm names to skip
+};
+```
+
+## The contract
+
+A plugin is a function exported from the module named above
+(`module.exports = fn`, or `default` / `plugin` named exports also work):
+
+```js
+module.exports = function plugin(context) {
+  return {
+    packageDependencies: [
+      // Local package (e.g. a scanned module dir) …
+      {name: 'ExpoModulesCore', path: '../../../node_modules/expo-modules-core/ios'},
+      // … or a remote/published package:
+      // {name: 'SomePkg', url: 'https://…/SomePkg.git', version: '1.2.3'},
+    ],
+    productDependencies: [
+      // Linked by the app's AutolinkedAggregate target:
+      {name: 'ExpoModulesCore', package: 'ExpoModulesCore'},
+    ],
+    generatedSources: [
+      // e.g. the generated module registry, registered with codegen:
+      {path: 'build/generated/expo/ExpoModulesProvider.swift'},
+    ],
+    flavoredFrameworks: [
+      // Precompiled dynamic XCFrameworks that come in mandatory Debug/Release
+      // pairs. RN validates and stages both outside the SwiftPM graph.
+      {
+        id: 'expo-modules-core',
+        frameworkName: 'ExpoModulesCore',
+        linkage: 'dynamic',
+        flavors: {
+          debug: '/…/output/debug/xcframeworks/ExpoModulesCore.xcframework',
+          release: '/…/output/release/xcframeworks/ExpoModulesCore.xcframework',
+        },
+      },
+    ],
+    watchPaths: [
+      // Inputs whose edits must re-trigger the auto-sync — the plugin's own
+      // manifest and per-module config (absolute paths, dirs or files):
+      '/…/node_modules/expo/Package.swift',
+      '/…/node_modules/expo/expo-module.config.json',
+    ],
+  };
+};
+```
+
+#### `flavoredFrameworks` — per-configuration precompiled frameworks
+
+Each entry is
+`{id, frameworkName, linkage: 'dynamic', flavors: {debug, release}}`.
+Both flavor paths must be absolute and present when `spm add` or `spm update`
+runs. The framework and executable names, public headers, and platform slices
+must agree across flavors. Static binaries, nested frameworks, duplicate IDs,
+and duplicate embedded framework names are fatal.
+
+The declarations are recorded to
+`<outputDir>/.spm-plugin-flavored-frameworks.json`, normalized into the same
+immutable app-local slots as React Native, and added to Xcode's exact linker and
+embed settings. They are not emitted as SwiftPM product dependencies. Adding or
+removing one requires `spm update`; the build-time `spm sync` intentionally does
+not mutate runtime framework settings.
+
+#### `watchPaths` — plugin staleness inputs
+
+`watchPaths` is an array of **absolute** paths (dirs **or** files) the Xcode
+auto-sync build phase watches to decide whether it must re-sync. RN already
+watches each module's source dir plus every npm dep's checked-in `Package.swift`
+and `.react-native/` dir; a plugin adds the inputs only it knows about — e.g.
+`packages/expo/Package.swift`, `expo-module.config.json`, and per-module
+manifests. On the next build the phase re-syncs when a watched **file** is newer
+than the last sync, a watched **dir** has a newer child, or a watched path has
+**vanished** (a rename forces a re-sync so the config error surfaces).
+
+Unlike `flavoredFrameworks`, watch paths are best-effort: a non-array is ignored with a warning
+(never fatal), and each non-string / empty / **relative** entry is dropped with a
+warning. Absolute-only, because the generated phase tests these paths with no cwd
+context. The kept paths are folded into `<outputDir>/.spm-sync-watch-paths`
+alongside RN's own, then deduped and sorted.
+
+### Context (input)
+
+| Field | Meaning |
+|---|---|
+| `appRoot` | The Xcode project directory (`<app>/ios`) being injected — **not** the app package root. Deriving package-root-relative paths from it (e.g. `path.join(appRoot, 'node_modules')`) silently breaks; use `projectRoot` for that. |
+| `projectRoot` | The JS root (nearest `package.json`) — where the framework scans `node_modules`. |
+| `reactNativeRoot` | Resolved `react-native` package root. |
+| `autolinking` | Parsed `autolinking.json` — RN's already-discovered deps, so the plugin can react to them. |
+| `outputDir` | `build/generated/autolinking` — where generated artifacts land. |
+| `react` | How to depend on React (see below). `null` when there is no resolvable React dependency. |
+
+#### `context.react` — depending on React
+
+A plugin that emits its own `Package.swift` must declare React as a dependency.
+Rather than re-deriving React Native's package path, identity, and product
+names — which differ between local and remote mode and **move as RN
+repackages** — take them from `context.react`:
+
+```js
+react: {
+  packageRef:
+    {name: 'ReactNative', path: '<absolute>', relPath: '<relative-to-outputDir>'} // local
+    | {name: '<identity>', url: '<url>', version: '<version>'},                   // remote (SPM-resolved)
+  products: [
+    {name: 'ReactHeaders', package: 'ReactNative'},
+    {name: 'ReactNativeHeaders', package: 'ReactNative'},
+    {name: 'ReactNativeDependenciesHeaders', package: 'ReactNative'},
+    {name: 'ReactAppHeaders', package: 'React-GeneratedCode'}, // ← separate, per-app package
+  ],
+}
+```
+
+Local vs remote is signalled by which `packageRef` keys are present (`path` xor
+`url`+`version`). `packageRef.path` is **absolute** — always correct no matter
+which subdirectory of `outputDir` the plugin writes its own manifest into (the
+generated manifests are gitignored and regenerated every sync, so there's no
+portability cost); `relPath` (relative to `outputDir`) is provided as a
+convenience. `products` is the set React Native wires into **its own** autolinked
+targets (so a plugin's target compiles against exactly RN's React surface),
+filtered to those resolvable this run — every listed product is safe to
+reference without guarding. Note the fourth entry: `ReactAppHeaders` lives in
+the separate `React-GeneratedCode` package (per-app codegen), which a
+hand-rolled plugin would miss, and which is omitted when that package is absent.
+Because RN derives this list from one source of truth alongside its own product
+wiring, it stays correct across repackaging.
+
+### Return (contributions, all optional)
+
+| Field | Merged into |
+|---|---|
+| `packageDependencies` | The aggregator's `.package(…)` list (`path`, or `url` + `version`). |
+| `productDependencies` | The `AutolinkedAggregate` target's `dependencies:` (`.product(name:package:)`). |
+| `generatedSources` | Recorded for the codegen step to register (e.g. a module-registry `.swift`). |
+| `flavoredFrameworks` | Mandatory Debug/Release dynamic XCFramework pairs normalized outside SwiftPM. Malformed or incomplete entries are fatal. |
+
+The plugin returns **data** — it never writes into React Native's generated
+tree. RN owns the merge, so a re-sync reproduces the same `Package.swift`
+byte-for-byte (idempotent). Package and product contributions are **deduped by
+name** across plugins.
+
+## Lifecycle
+
+```
+react-native spm add / update ─┐
+                               ├─► generate-spm-autolinking main()
+Xcode "Sync SPM Autolinking" ──┘        │
+(build phase, every build)              ├─ 1. discover plugins (dep configs)
+                                        ├─ 2. RN builds its own dep graph
+                                        ├─ 3. invoke plugins (context in)
+                                        └─ 4. merge results → aggregator Package.swift
+```
+
+Because steps 1–4 run in the one `main()`, everything above shares the same
+seam — there is no separate hook to wire for the build-time path.
+
+## Failure behavior
+
+Fail-closed and **named**: a plugin that fails to load, doesn't export a
+function, throws, or returns a malformed contribution aborts the run with a
+message identifying the framework. A framework silently dropping its modules
+(a green build missing native code) is worse than a loud stop.
+
+## Status & open items (Preview)
+
+- **Implemented & tested:** discovery (transitive + deny-list), invocation,
+  package + product merge, fail-closed validation, and dual-flavor framework
+  normalization/link/embed outside SwiftPM.
+- **Implemented & tested:** `generatedSources` **app-target wiring**. The
+  merge writes `.spm-plugin-generated-sources.json`; the `spm add`/`update`
+  xcodeproj injector (generate-spm-xcodeproj.js) reads it and wires each source
+  **into the app target** — a `PBXFileReference` + `PBXBuildFile` + a
+  Sources-build-phase entry, parented under one "SPM Generated Sources"
+  navigator group. This is what makes an `@objc` class (e.g. Expo's
+  `ExpoModulesProvider`) reach the ObjC classlist: a class inside the static
+  Autolinked aggregate never does, so `NSClassFromString` discovery would fail.
+  Paths are stored SRCROOT-relative when under the app root (the usual
+  `build/generated/…` case), else absolute (`sourceTree = "<absolute>"`). All
+  UUIDs are namespaced on the normalized path (deterministic/idempotent) and
+  recorded in the `.spm-injected.json` marker's `generatedSources` map, so
+  `deinit` reverts them and `update` reconciles entries that left the manifest.
+  A target without a Sources phase logs loudly and skips the wiring (injection
+  otherwise succeeds). v1 targets only the injected app target and assumes
+  `.swift` in practice (`.m`/`.mm` are mapped as future-proofing).
+- **Co-design with Expo (not final):** codegen **provider ordering** — codegen
+  must consume the same discovered module set the plugin contributes — is
+  intentionally left for the first real plugin to drive to a stable shape.
+- Contract to be ratified via RFC once Expo's plugin proves it (framed as a
+  generic hook, not Expo-specific code in RN).

package/scripts/spm/__doc__/spm-header-paths-contract.md

@@ -0,0 +1,97 @@
+# SPM headers & package references — how they resolve
+
+React Native's SPM consumption is **zero-I**: no `-I` / `-F` header search
+paths and no `unsafeFlags` in any generated manifest. Headers are served by
+SPM products/binary targets, and every generated `Package.swift` references
+the React Native + codegen packages with plain, fixed-relative paths computed
+at generation time (no runtime discovery). This document is the single source
+of truth for how that resolves.
+
+> History: earlier iterations materialized two header trees and fed them to
+> consumers as `-I` flags read from `spm-paths.json` / `.react-native/paths.json`
+> via an inlined Swift loader. That whole mechanism (the loader
+> `renderRNPathsLoader`, the `writeAppPathsJson` / `writeSharedPathsJson`
+> writers, and both JSON files) has been **deleted** — manifests are now
+> declarative. If you find a reference to those files, it is stale.
+
+## How headers resolve (no search paths)
+
+| Namespace | Served by | Mechanism |
+|-----------|-----------|-----------|
+| Objective-C `<React/...>` / Swift `import React` | `ReactHeaders` Clang source target | Canonical Debug/Release-identical React headers staged under `ReactHeadersTarget/include/React`, with a plain `module React` module map. |
+| Lowercase C++ `<react/...>` and everything else: `<ReactCommon/...>`, `<jsi/...>`, `<react/renderer/...>`, `<yoga/...>`, folly/glog/boost/fmt/double-conversion | `ReactNativeHeaders.xcframework` plus `ReactNativeDependenciesHeaders.xcframework` | Header-only invariant binary targets keep lowercase `react` separate from Objective-C `React` and propagate their search paths through product dependencies. |
+| `<ReactCodegen/...>`, `ReactAppDependencyProvider`, this app's generated specs | `ReactAppHeaders` SPM target in the codegen package | SPM `publicHeadersPath` propagation — a real target dependency, not a flag. |
+
+The one remaining materialized header tree is the per-app farm at
+`<appRoot>/build/generated/ios/ReactAppHeaders` (built by
+`buildPerAppHeaderTree` in `spm-utils.js`, called from the orchestrators). It
+is vended as the `ReactAppHeaders` SPM target — consumers reach it through a
+product dependency, never through `-I`.
+
+`autolinking.json` (the `@react-native-community/cli config` output) is an
+INPUT used to generate the manifests; it is never read by a manifest.
+
+## How each manifest references the React + codegen packages
+
+Every generated manifest sits at a known depth inside the app and is
+regenerated on every `react-native spm` run, so package references are plain
+fixed-relative paths — no walk-up, no JSON, no `import Foundation`.
+
+| Manifest | Location | How it references the React + codegen packages |
+|----------|----------|-------------------------------------------------|
+| Autolinked aggregator | `build/generated/autolinking/Package.swift` | `.package(path: "../../xcframeworks")` + `"../ios"` (only when it has inline `spmModule` targets) |
+| Per-dep synth wrapper | `build/generated/autolinking/packages/<Name>/` | `.package(path: "../../../../xcframeworks")` + `"../../../ios"` |
+| Codegen template | `build/generated/ios/Package.swift` | `.package(path: "../../xcframeworks")` (or the remote url) |
+| App target (pbxproj) | `<App>.xcodeproj` | local `XCLocalSwiftPackageReference` (or `XCRemoteSwiftPackageReference` in remote mode) |
+| Scaffolded community lib | `node_modules/<dep>/Package.swift` | scaffold-time relative paths to the app's xcframeworks + codegen packages (or `.package(url:exact:)` in remote mode) |
+
+## Remote-package mode
+
+Remote mode is gated by a **URL alone** — `RN_SPM_REMOTE_URL` (or the persisted
+`url`). When set, the whole app graph flips to a single remote React Native
+package identity: `.package(path: build/xcframeworks)` becomes
+`.package(url:exact:)` everywhere (aggregator/synth/codegen template/pbxproj),
+and the local artifact download + compose is skipped. SPM's
+one-version-per-package rule then unifies app + every library on one resolved
+React Native. The package identity is derived from the URL tail (swift-tools 6
+dropped `.package(name:url:)`) — nothing hardcodes a repo name.
+
+**Version is derived from npm, not pinned by hand.** The SPM-pinned RN version
+is not a free parameter: the SPM graph must compile against the same React
+Native the JS/native code uses, so the app (graph root) pins EXACT to the
+*installed* RN version, read from `node_modules/react-native/package.json`.
+`RN_SPM_REMOTE_VERSION` and the persisted `versionOverride` are **overrides**,
+not the source of truth — they're only needed when the installed version isn't
+publishable (e.g. the monorepo `1000.0.0` dev placeholder, which has no remote
+tag). A *derived* version is never persisted, so an `npm install` that upgrades
+RN auto-re-pins the SPM graph on the next `spm` run; an *override* is persisted
+as `versionOverride` so it survives Xcode-phase re-syncs without the env.
+
+Persisted schema is `{url, versionOverride?}`. Legacy `{url, version}` is still
+read, with `version` honored as an override (back-compat). If remote mode is on
+but no usable version can be resolved — react-native isn't installed, or it's a
+non-publishable dev placeholder and no override is set — the tooling errors
+(exit 2, a hard Xcode build error) directing you to set `RN_SPM_REMOTE_VERSION`
+or install a released react-native, rather than silently pinning an unpublished
+tag.
+
+## Hand-authored community library contract
+
+A library that ships its own `Package.swift` (no scaffolder/autolinker marker)
+is left untouched by the tooling. It needs only two things, and **no discovery
+code**:
+
+1. Depend on the React Native SPM package and its products — in remote mode
+   `.package(url: "<repo>", exact: "<version>")` + `.product(name: "ReactNative", …)`
+   and `.product(name: "ReactNativeHeaders", …)`. (Libraries should declare a
+   version RANGE in production; the consuming app pins EXACT.)
+2. Ship its own generated code: set `codegenConfig.includesGeneratedCode: true`
+   and generate with `generate-codegen-artifacts.js --path . --targetPlatform
+   ios --source library`. Output lands at
+   `<outputDir>/build/generated/ios/ReactCodegen/`, reachable from the manifest
+   with one safe `.headerSearchPath(...)` into the library's own tree. The
+   app-side codegen then skips the lib's spec (no duplicate symbols).
+
+This makes the library self-contained — it carries no app-layout knowledge and
+needs no per-app codegen headers from the consuming app. Proven with
+`@chrfalch/react-native-calculator` (a hand-authored Fabric/TurboModule lib).

package/scripts/spm/__doc__/spm-plugins-assessment.md

@@ -0,0 +1,128 @@
+# SPM Build Plugins Assessment
+
+An evaluation of whether Swift Package Manager plugins can replace the Xcode build
+phase scripts currently injected by `generate-spm-xcodeproj.js`.
+
+## Current Build Phases (6 total)
+
+| # | Phase | Timing | SPM Plugin Feasible? |
+|---|-------|--------|----------------------|
+| 1 | Sync SPM Autolinking | Pre-build | Partially |
+| 2 | Prepare VFS Overlay | Pre-build | Partially |
+| 3 | Sources (compile) | Build | N/A (standard) |
+| 4 | Frameworks (link) | Build | N/A (standard) |
+| 5 | Resources (copy) | Build | N/A (standard) |
+| 6 | Build JS Bundle | **Post-build** | **See below** |
+
+> **Removed:** The "Copy Hermes Framework" phase was removed — it was a no-op.
+> The underlying `copy-hermes-xcode.sh` script has been empty since Dec 2022.
+> Hermes is already properly linked as an xcframework SPM dependency.
+
+## SPM Plugin Types
+
+SPM offers two plugin types:
+
+1. **Build Tool Plugins** (`BuildToolPlugin`) — run pre-build, can generate source
+   files/resources via `prebuildCommands` or per-file `buildCommands`.
+2. **Command Plugins** (`CommandPlugin`) — run on-demand via
+   `swift package <command>`.
+
+## Key Constraints
+
+### Sandbox restrictions
+
+SPM plugins run sandboxed by default — no network access, limited filesystem access.
+The current scripts need to:
+
+- Run `node` (not on the sandbox-allowed path)
+- Write to the source tree (`autolinked/`, `build/`)
+- Access `node_modules/`
+- Read git state
+
+Command plugins can request `--allow-writing-to-package-directory`, but build tool
+plugins can only write to a designated plugin work directory, not the source tree.
+
+### No Xcode build settings
+
+SPM plugins do not receive Xcode build settings such as `CONFIGURATION`,
+`PLATFORM_NAME`, `BUILT_PRODUCTS_DIR`, or `DERIVED_FILE_DIR`. The JS bundling script
+relies heavily on these to decide debug-vs-release behavior and output paths.
+
+## JS Bundle Phase — Could Move to Pre-build
+
+The JS bundle has no dependency on native compilation. It only needs JS source files,
+Metro, and knowledge of debug vs release. The current post-build placement is
+historical — the script writes directly into `BUILT_PRODUCTS_DIR`.
+
+A potential restructuring:
+
+1. **Generate the bundle pre-build** into a known location (e.g. `build/jsbundle/`)
+2. **Declare it as an SPM resource** so it gets copied into the app automatically
+
+Challenges:
+- **Debug builds skip bundling** (app loads from Metro dev server). The script checks
+  `CONFIGURATION == Debug`, which is unavailable to SPM plugins.
+- **Hermes bytecode compilation** also happens in this phase for release builds.
+- Making it a command plugin (`swift package bundle-js --configuration release`) would
+  lose the automatic behavior — developers would need to run it explicitly.
+
+## What Could Theoretically Work
+
+### Codegen as a Command Plugin
+
+A Swift command plugin could shell out to `node` to run codegen:
+
+```swift
+@main struct CodegenPlugin: CommandPlugin {
+    func performCommand(context: PluginContext, arguments: [String]) throws {
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+        process.arguments = ["node", "scripts/codegen/generate-codegen-artifacts.js"]
+        try process.run()
+        process.waitUntilExit()
+    }
+}
+```
+
+Invoked as `swift package codegen`. This is essentially wrapping a shell script in
+Swift with no real benefit over the current approach.
+
+### Autolinking sync as a Prebuild Command
+
+A `prebuildCommand` runs before every build, similar to Phase 1. But:
+
+- Output can only go to the plugin work directory (not `autolinked/`)
+- Would need to restructure the package graph to consume generated files from the
+  plugin work directory
+- Still needs to shell out to `node`
+
+This is a significant architectural rework for marginal benefit.
+
+## Recommendation
+
+**Do not invest in SPM plugins for this use case.** Reasons:
+
+1. **Pre-build phases already work well** as Xcode build phase scripts. Moving them
+   to SPM plugins adds Swift boilerplate around `Process()` calls to `node`, while
+   losing access to Xcode build settings.
+
+2. **The ROI is poor** — a hybrid (some SPM plugins + some Xcode build phases) is
+   harder to reason about than the current uniform approach of all Xcode build phases.
+
+3. **SPM plugins shine for pure Swift source generation** (SwiftGen, SwiftProtobuf)
+   where the plugin generates `.swift` files that feed into compilation. React
+   Native's build steps are fundamentally different — they orchestrate a JS toolchain
+   and copy runtime artifacts.
+
+4. **The JS bundle phase could move pre-build** but would lose automatic
+   debug/release detection without Xcode build settings. Worth revisiting if SPM
+   gains access to build configuration in a future Swift version.
+
+## Alternatives Worth Exploring
+
+- **Xcode Build Tool Plug-ins** (the Xcode-specific variant, not SPM) have access to
+  build settings and can run post-build, but require a different packaging model.
+- **Move auto-sync to a `prepare` script** in `package.json` so it runs at
+  `yarn install` time instead of every build, reducing build-time overhead.
+- **Pre-build JS bundling** with the bundle declared as an SPM resource, removing the
+  need for a post-build phase entirely (release builds only).