Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
53 commits
Select commit Hold shift + click to select a range
be44c42
docs: add the alpha.8 fail-early design
WillyAntunez Nov 6, 2026
5fa2fc1
docs: close the alpha.8 design rulings
WillyAntunez Nov 6, 2026
ee4e699
docs: add alpha.8 plan 1, the podspec reader
WillyAntunez Nov 6, 2026
d9f739a
fix: write new-file headers patch-package reads
WillyAntunez Nov 6, 2026
ce361b1
feat: add the podspec reader's Ruby shim
WillyAntunez Nov 6, 2026
8ce7280
test: cover the shim's raised paths
WillyAntunez Nov 6, 2026
c20ca04
feat: model CocoaPods and React Native helpers
WillyAntunez Nov 6, 2026
47a3395
fix: keep the shim's ENV and require honest
WillyAntunez Nov 6, 2026
16d6609
feat: pick the podspec reader and run the shim
WillyAntunez Nov 6, 2026
1b84aea
feat: read podspecs with Ruby, drop pod ipc spec
WillyAntunez Nov 6, 2026
1d3f7b3
fix: punctuate the podspec reader's remedy
WillyAntunez Nov 6, 2026
1297fb9
test: complete the gesture-handler 2.32.0 fixture
WillyAntunez Nov 6, 2026
5eb4e81
feat: merge ios attributes of the shim's model
WillyAntunez Nov 6, 2026
5678eeb
fix: merge ios dependencies and array values
WillyAntunez Nov 6, 2026
371ec7a
fix: stop rn-spm on a podspec reader failure
WillyAntunez Nov 6, 2026
895366b
feat: record the podspec reader, revision 8
WillyAntunez Nov 6, 2026
79fa048
feat: report Ruby in doctor and setup
WillyAntunez Nov 6, 2026
a06fe7b
fix: match setup's Ruby line to the reader
WillyAntunez Nov 6, 2026
8371982
feat: warn when a scaffold's reader differs
WillyAntunez Nov 6, 2026
1ed343d
fix: drop the Ruby advice for a forced reader
WillyAntunez Nov 6, 2026
70ebbcf
feat: say which podspec reader rn-spm used
WillyAntunez Nov 6, 2026
ca3fd91
docs: describe the Ruby podspec reader
WillyAntunez Nov 6, 2026
86e7539
docs: true up library and README notes
WillyAntunez Nov 6, 2026
ff9d986
test: sweep the podspec readers over libraries
WillyAntunez Nov 6, 2026
a52cdfc
test: guard the sweep against silent gaps
WillyAntunez Nov 9, 2026
83b48fe
test: fail loudly when the gap kinds parse empty
WillyAntunez Nov 9, 2026
06c806e
feat: model attributes_hash in the podspec shim
WillyAntunez Nov 9, 2026
9ee0166
chore: cache the test tarballs in CI
WillyAntunez Nov 9, 2026
9d67b91
feat: load the colored2 stub as CocoaPods does
WillyAntunez Nov 9, 2026
3ab5f07
test: key sweep goldens by library and React Native
WillyAntunez Nov 9, 2026
c67d0ed
test: sweep R11's library set in CI
WillyAntunez Nov 9, 2026
3d7c9dd
test: give the sweep's cleanup time to finish
WillyAntunez Nov 9, 2026
bc5d600
test: add an optional heavy tier to the sweep
WillyAntunez Nov 9, 2026
db4988e
test: sweep skia with its prebuilt binaries
WillyAntunez Nov 9, 2026
6d4ee15
feat: refuse bare mentions in markdown
WillyAntunez Nov 9, 2026
d137b88
fix: see fences in CRLF markdown
WillyAntunez Nov 9, 2026
602cab0
test: give heavy sweep entries a longer timeout
WillyAntunez Nov 9, 2026
af940cf
docs: skip backups in the patch recipe
WillyAntunez Nov 9, 2026
b598747
fix: run podspecs with the probed Ruby
WillyAntunez Nov 9, 2026
3071846
fix: give each podspec read 120 s
WillyAntunez Nov 9, 2026
c3694d3
fix: stop rn-spm on reader plumbing errors
WillyAntunez Nov 9, 2026
d1dd4ba
fix: offer the escape on exit and ENV stops
WillyAntunez Nov 9, 2026
c6dd8af
fix: drop stale CocoaPods text in the scaffolder
WillyAntunez Nov 9, 2026
11e66e9
fix: give Ruby install advice only when it helps
WillyAntunez Nov 9, 2026
a7a7411
test: give sweep reads and tar more time
WillyAntunez Nov 9, 2026
fcc97b0
test: sweep gesture-handler with worklets
WillyAntunez Nov 9, 2026
409af79
test: check mentions in tracked markdown only
WillyAntunez Nov 9, 2026
ffdcd12
test: read the scaffold golden from app-golden
WillyAntunez Nov 9, 2026
15f66fe
test: give the fake Ruby a version no host has
WillyAntunez Nov 9, 2026
810d3d5
docs: rewrite the alpha.8 upgrade notes
WillyAntunez Nov 9, 2026
fb7830c
docs: say when podspec ENV appears in a report
WillyAntunez Nov 9, 2026
04cfa4c
docs: record the plan 1 amendments
WillyAntunez Nov 9, 2026
e9f337a
fix: match the patch warning to the Ruby advice
WillyAntunez Nov 9, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 33 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# CI: on every pull request to main and every push to main, install, fetch the pinned upstream tarballs the tests
# read, type-check, scan the tracked files for private identifiers and run the whole test suite.
# read (restored from the cache while tests/tarballs.json is unchanged), type-check, scan the tracked files for private
# identifiers and run the whole test suite.
# A second job runs the podspec reader's Ruby shim tests on the oldest Ruby the shim supports.
#
# Nothing is compiled for iOS and no device is touched: there is no Swift, no Darwin SDK and no iPhone here. Tests that
# need a real app, a toolchain or a device are skipped, and the run summary lists them by name (and, on a red run, the
Expand All @@ -26,6 +28,7 @@ concurrency:
jobs:
test:
runs-on: ubuntu-latest
# At least twice a fetch from an empty cache plus the tests (under 2 minutes measured locally), and never under 15.
# Also bounds the fetch script's npm pack, which has no timeout of its own.
timeout-minutes: 15
steps:
Expand All @@ -39,16 +42,45 @@ jobs:
# npm ci runs the package's prepare script, which builds dist/.
- name: Install and build
run: npm ci
# Keyed on the manifest: a changed pin starts a new cache, and the fetch below checks every integrity anyway.
- name: Cache the test tarballs
uses: actions/cache@v6
with:
path: tests/.cache
key: test-tarballs-${{ hashFiles('tests/tarballs.json') }}
- name: Fetch the test tarballs
run: node scripts/fetch-test-tarballs.mjs
- name: Type-check
run: npm run lint
# Before the tests: a leak is reported even when the suite is red.
- name: Scan for private identifiers
run: npm run scan:private
# The runner image ships Ruby; tests/podspecShim.test.ts fails here without it, instead of skipping.
- name: Ruby (the podspec reader needs it)
run: ruby --version
- name: Test
run: npm test -- --reporter=default --reporter=json --outputFile=test-results.json
# Runs after a failed test step too, so a red run still says what did not run.
- name: List skipped tests
if: ${{ !cancelled() }}
run: node scripts/ci-skipped.mjs test-results.json >> "$GITHUB_STEP_SUMMARY"

# The podspec reader's Ruby shim on the oldest Ruby it supports: the floor its --probe reports is what this job runs.
shim-ruby-floor:
runs-on: ubuntu-22.04
timeout-minutes: 15
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- uses: ruby/setup-ruby@v1
with:
ruby-version: "2.7"
- name: Install and build
run: npm ci
- name: Test the shim on Ruby 2.7
run: npx vitest run tests/podspecShim.test.ts
33 changes: 33 additions & 0 deletions .github/workflows/mentions.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Mentions: on every pull request that is opened, edited, reopened or pushed to, check its description for bare GitHub
# mentions (`@name` outside a code span), which notify that user. The Markdown files in the repo are checked by
# tests/mentions.test.ts in CI.
#
# The description reaches the shell through an environment variable and is written to a file, never put into the
# script text: an expression inside run text would let a description run commands.

name: Mentions

on:
pull_request:
types: [opened, edited, reopened, synchronize]

permissions:
contents: read

jobs:
description:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: actions/setup-node@v7
with:
node-version: 22
- name: Write the description to a file
env:
BODY: ${{ github.event.pull_request.body }}
run: printf '%s' "$BODY" > "$RUNNER_TEMP/body.md"
- name: Check the description for bare mentions
run: node scripts/check-mentions.mjs "$RUNNER_TEMP/body.md"
62 changes: 61 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,66 @@ versions follow [Semantic Versioning](https://semver.org/) with `alpha` prerelea

## [Unreleased]

### Upgrading from 0.1.0-alpha.7
- Install Ruby 2.7 or newer (`sudo apt install ruby`) before your first build with this release, so rn-xtool reads
podspecs as CocoaPods does; `rn-xtool doctor` shows the reader this machine uses. Without Ruby, `rn-spm` reads them
with the reduced reader and says so in a `⚠` line.
- On React Native 0.88 (bare, and Expo SDK 58), the first build after the upgrade stops at `patches` with "rn-xtool
could not apply its patch to react-native@0.88.1 (patch file: react-native+0.88.1.patch): node_modules/react-native
is the version the patch is for, but its files match neither the original package nor the patched one.": this
release changes the bundled react-native patch (a new file, `scripts/spm/read-podspec-shim.rb`, and a rewritten
`scripts/spm/read-podspec.js`), and `node_modules/react-native` still holds 0.1.0-alpha.7's. Run
`rm -rf node_modules/react-native && npm install`, then build again.
- The scaffolder is now revision 8, so every scaffold patch rn-xtool persisted in your `patches/` before this release
gets a warning at each `build`: "⚠ patches/<name> was written by an older rn-xtool scaffolder (revision 7, now 8);
delete it so rn-xtool regenerates it (also remove node_modules/<package> and reinstall: that copy still has the old
Package.swift)". With Ruby installed, delete each such patch, remove the library from `node_modules` and reinstall
it, then build: rn-xtool scaffolds it again and persists the new patch.

### Changed
- The scaffolder reads every podspec with the system `ruby` (2.7 or later) through a shim of CocoaPods' DSL and React
Native's podspec helpers, the way CocoaPods runs it on a Mac: `install_modules_dependencies`, `defined?` and
`respond_to?` answer as under React Native's Podfile, and a library's own Ruby and `node` scripts run. So
react-native-gesture-handler 3.3.0 gets `RNGH_USE_WORKLETS=1` beside react-native-worklets 0.8 or later, and
react-native-webview 14.0.1 takes its `install_modules_dependencies` branch. Every podspec runs with the
interpreter of the first `ruby` on `PATH`, by its absolute path, so a version manager's `ruby` shim cannot pick
another one per folder, for at most 120 s. Without a usable Ruby, the reduced reader of earlier releases reads them, and
`rn-spm` prints one `⚠` line saying why. See [how-it-works.md](docs/how-it-works.md#cocoapods-only-libraries).
- `pod ipc spec` is no longer run, so a machine with CocoaPods reads a podspec exactly as any machine with Ruby, instead
of with React Native's helpers stripped (react-native-webview, `@react-native-async-storage/async-storage`,
react-native-keychain and react-native-video took their old-architecture branch there).
- A podspec's `ios` attributes (`s.ios.exclude_files`, `ss.ios.dependency`, …) are merged over the spec and each
subspec the scaffold uses, as CocoaPods merges them for an iOS target; `osx`, `tvos`, `visionos` and `watchos` ones
are never read.
- A podspec Ruby cannot read, or one that does not finish in 120 s, stops `rn-spm` with the podspec (and its line,
when Ruby keeps one) and the reason, also when autolinking reads it for header search paths, on React Native 0.88
and in the copy used for 0.85–0.87 and Expo SDK 57, instead of leaving that library without them. A gap of the
reader, a timeout, a Ruby that ends without a result and a `key not found` from `ENV.fetch` end with "Set
RN_XTOOL_PODSPEC_READER=reduced to read it with the reduced reader for one run, and report it with rn-xtool doctor
--report." See [troubleshooting.md](docs/troubleshooting.md#podspec-reader).
- A podspec that calls React Native's `spm_dependency` is refused by name, "<podspec>: uses spm_dependency(url: <url>,
products: <a, b>), which rn-xtool does not map yet", instead of scaffolding a target that would not link.
- A podspec that sets `script_phases`, `prepare_command`, `info_plist` or `module_map` gets a line at `rn-spm`,
"! <library>: The podspec sets <key>, which a CocoaPods build applies and rn-xtool's scaffold does not.", instead
of leaving it out silently.

### Added
- `rn-xtool doctor` (also with `--project`) and `rn-xtool setup` report Ruby: `✔ ruby — 3.3.8`, or `⚠ ruby — not
found — podspecs are read with the reduced reader; sudo apt install ruby`. The install command is named when Ruby is
missing or older than 2.7; for another reason (no `json`, a Ruby that cannot run the reader) the line names it and
links the troubleshooting page. `setup` never installs Ruby.
- `RN_XTOOL_PODSPEC_READER=reduced` reads every podspec with the reduced reader for one run, the escape when Ruby
cannot read one; `rn-spm` says so in a `⚠` line. Another value is named in a warning and ignored.
- Each scaffolded `Package.swift` names its podspec reader on its marker (`// rn-xtool-podspec-reader: ruby` or
`reduced`), and the `patches` step warns about a persisted scaffold patch the other reader wrote: delete one the
reduced reader wrote where Ruby is available, keep one Ruby wrote on a machine that reads with the reduced reader.
- `rn-xtool doctor --report` has `ruby:`, `podspec reader:` (the reader of the last `rn-spm` and how many podspecs it
read) and `podspec ENV:` (the environment variables each podspec read) lines, from
`ios/build/rn-xtool-podspec-reads.jsonl`, which `rn-spm` writes.
- CI runs the podspec reader sweep, which reads the podspecs of a pinned set of libraries with both readers and
compares them with recorded goldens, the shim's tests on Ruby 2.7, and a check that no Markdown file holds a bare
`@` mention, which would notify a GitHub user.

## [0.1.0-alpha.7] - 2026-11-06

### Upgrading from 0.1.0-alpha.6
Expand Down Expand Up @@ -44,7 +104,7 @@ versions follow [Semantic Versioning](https://semver.org/) with `alpha` prerelea
the project's `CLANG_CXX_LANGUAGE_STANDARD` (C++20 when unset), instead of clang's default, which stopped on React
Native's C++20 headers with "unknown type name 'Hashable'" in `react/utils/hash_combine.h`.
- An Objective-C++ file that imports a pod table forward (a bare app's `AppDelegate.mm` with
`#import <AppAuth/AppAuth.h>`) compiles, instead of stopping with "use of '@import' when modules are disabled": the
`#import <AppAuth/AppAuth.h>`) compiles, instead of stopping with "use of '`@import`' when modules are disabled": the
scaffold's forwarder `#import`s the pod's public headers instead of `@import`ing its modules.
- A library that was also built for Android gets its scaffold persisted, instead of "⚠ Did not persist <library>'s
scaffold: the patch would contain a binary file (node_modules/<library>/android/build/…/BuildConfig.dex)" and a new
Expand Down
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,9 @@ does not work yet (a library's own vendored binaries, Xcode-only tools).
- FUSE 2 for the xtool AppImage (`sudo apt install libfuse2t64` on Ubuntu 24.04 and newer, `sudo apt install libfuse2`
on older releases), `python3`, `iproute2`. `setup` installs Swift and prints the exact `apt-get` line for any missing
Swift system packages ([list](docs/how-it-works.md#what-setup-installs)).
- Ruby 2.7+ (`sudo apt install ruby`), which reads podspecs as CocoaPods does. Without it, rn-xtool reads them with a
reduced reader that evaluates a subset of Ruby, and `rn-spm` says so in a `⚠` line
([details](docs/troubleshooting.md#podspec-reader)).
- npm or Yarn classic. patch-package needs a flat `node_modules`; pnpm and Yarn PnP are not supported, and `build`
stops on them early ([details](docs/troubleshooting.md#pnpm-and-yarn-pnp)).

Expand Down
32 changes: 27 additions & 5 deletions docs/RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,13 +41,29 @@ git push --follow-tags
```

Then create a GitHub release from the tag with the notes (what changed, known limits, tested xtool/Swift/Expo
versions). Check the result: `npm view react-native-xtool dist-tags` and `npx react-native-xtool@alpha doctor`.
versions), from a checked file as below. Check the result: `npm view react-native-xtool dist-tags` and
`npx react-native-xtool@alpha doctor`.

**Pull requests and release notes.** A bare `@name` outside a code span notifies that GitHub user, and in release
notes lists them as a contributor. Write the text of a pull request and the release notes into files, check each one,
and give GitHub the checked file:

```sh
npm run check:mentions -- <file> # names each bare mention and fails; put it in a code span or drop the @
gh pr create --body-file <file>
gh release create <tag> --notes-file <file>
```

Publish release notes from the checked file only, never typed or pasted into GitHub's release page. CI checks the
Markdown files in the repo (`tests/mentions.test.ts`), and the Mentions workflow
(`.github/workflows/mentions.yml`) checks a pull request's description again each time it is opened, edited or
pushed to.

## Scaffolder changes

React Native's scaffolder ships twice: as `patches/react-native+0.88.0.patch` and its byte-identical copy
`react-native+0.88.1.patch`, applied to an installed 0.88.x, and as `vendor/rn-spm/`, pristine 0.88.0 with that patch
and `vendor/rn-spm/rn-xtool-edits.patch` (E1–E5) applied, for 0.85–0.87 and Expo SDK 57. A change to the scaffolder:
and `vendor/rn-spm/rn-xtool-edits.patch` (E1–E6) applied, for 0.85–0.87 and Expo SDK 57. A change to the scaffolder:

1. Edits the vendored copy (`vendor/rn-spm/spm/*.js`), and documents the fix in
[upstream/react-native-scaffolder.md](upstream/react-native-scaffolder.md) and the count in
Expand All @@ -61,12 +77,17 @@ and `vendor/rn-spm/rn-xtool-edits.patch` (E1–E5) applied, for 0.85–0.87 and
cp -a "$T/x/package/scripts" "$T/a/node_modules/react-native/scripts"
cp -a vendor/rn-spm/setup-apple-spm.js vendor/rn-spm/spm vendor/rn-spm/codegen \
"$T/b/node_modules/react-native/scripts/"
patch -R -p1 -F0 -d "$T/b/node_modules/react-native/scripts" -i "$PWD/vendor/rn-spm/rn-xtool-edits.patch"
patch -R -p1 -F0 --no-backup-if-mismatch -d "$T/b/node_modules/react-native/scripts" \
-i "$PWD/vendor/rn-spm/rn-xtool-edits.patch"
(cd "$T" && git diff --no-index --no-color --src-prefix= --dst-prefix= \
a/node_modules/react-native/scripts b/node_modules/react-native/scripts) > "$T/rn.patch"
a/node_modules/react-native/scripts b/node_modules/react-native/scripts) \
| sed -E 's#^diff --git [ab]/([^ ]+) [ab]/#diff --git a/\1 b/#' > "$T/rn.patch"
cp "$T/rn.patch" patches/react-native+0.88.0.patch && cp "$T/rn.patch" patches/react-native+0.88.1.patch
```

The `sed` gives a new file's header the `a/` side patch-package reads (`git diff --no-index` names both sides
`b/`, and patch-package then refuses the whole patch).

When the reverse `patch` fails, the change moved the context of an E-edit. That `b/` is half-reversed and holds
`.rej` files, so a diff from it would drop the E-edit from `rn-xtool-edits.patch` and move it into the 0.88 patch.
Copy the vendored files into a new `b/`, rerun the reverse without `-F0` (`patch -R -p1 --no-backup-if-mismatch`),
Expand All @@ -80,7 +101,8 @@ and `vendor/rn-spm/rn-xtool-edits.patch` (E1–E5) applied, for 0.85–0.87 and
warning for each persisted scaffold patch, so the CHANGELOG's "Upgrading" section says so. A change that alters no
scaffold output keeps the revision.
4. Regenerates the goldens in `tests/fixtures/scaffold-golden/` when the reference app's manifests change (the golden
test reads `RN_XTOOL_REF_APP`, else `../app`).
test reads `RN_XTOOL_REF_APP`, else `../app-golden`, a reference app beside the repo that holds exactly the eight
golden libraries at the golden's versions; `RN_XTOOL_WRITE_GOLDEN=1` writes the goldens instead of comparing).

The byte tests need the pinned tarballs in `tests/.cache` (`node scripts/fetch-test-tarballs.mjs`); without them they
skip, and the vitest summary says so. Before committing a scaffolder change, run `npx vitest run
Expand Down
Loading
Loading