feat(ios-prebuild): generator-time headers gate + drift hardening (R11, verify, ratchet)

Hardens the header layout against new/changed headers so consumer-facing
regressions fail the PREBUILD instead of a downstream (rn-tester/Expo/
community) build:

- headers-verify.js (new; runs in the prebuild compose CI job): include-health
  ratchet against a committed baseline (notShipped/unresolved/quoted-
  unresolvable includes in shipped headers — 27 baselined today); structural
  byte-compare of the composed module maps/umbrellas against the spec render;
  compile smokes — an ObjC TU precompiling the React module (every umbrella
  header) + all 14 R5 namespace modules + the R10 umbrella + __has_include
  asserts, an Expo-shaped ObjC++ TU (the R9 textual Fabric surface), and a
  Swift TU (import React + RCTBridge.moduleRegistry).
- R11: one source, one content location. 116 sources ship under multiple
  spellings (React/X.h + CoreModules/RCTImage/RCTAnimation/... forms, bare
  React_RCTAppDelegate aliases). The flattened layout duplicated their
  declarations, so any -fmodules consumer touching two spellings (even
  transitively via a legacy spelling) hit redefinition errors — found by the
  gate's first run. The module-owned spelling keeps the content; every other
  spelling is emitted as a one-line redirect shim.
- Single source of truth for third-party namespaces: the inventory's include
  classifier now derives from DEPS_NAMESPACES, and compose enforces
  set-equality with the deps artifact in BOTH directions (missing OR
  undeclared namespace fails). The undeclared direction immediately surfaced
  SocketRocket, which the deps artifact ships but was never relocated.
- R5 exemption assert: an invalid-module-identifier namespace gaining a
  modular-candidate header now fails the plan instead of silently shipping a
  non-modular header.
- Inventory records quoted includes that don't resolve to a shipped header
  (quotedNotShipped) instead of dropping them.

Docs: __docs__/headers-rules.md documents rules R1-R11, the emission pipeline,
and the resilience model.

Author: chrfalch

.github/workflows/prebuild-ios-core.yml

@@ -189,6 +189,16 @@ jobs:
         run: |
           cd packages/react-native
           node scripts/ios-prebuild -c -f "${{ matrix.flavor }}" -i "React Org"
+      - name: Verify composed headers
+        if: steps.restore-ios-xcframework.outputs.cache-hit != 'true'
+        run: |
+          # Generator-time header gate: include-health ratchet, structural
+          # byte-compare of module maps/umbrellas against the spec render, and
+          # compile smokes (React module + every namespace module + the
+          # privileged-consumer/Expo fixtures). Catches consumer-facing header
+          # regressions here instead of in downstream builds.
+          cd packages/react-native
+          node scripts/ios-prebuild/headers-verify.js --flavor "${{ matrix.flavor }}"
       - name: Compress and Rename XCFramework
         if: steps.restore-ios-xcframework.outputs.cache-hit != 'true'
         run: |

packages/react-native/scripts/ios-prebuild/__docs__/headers-rules.md

@@ -22,11 +22,15 @@ const fs = require('fs');
 // (and thus land in namespaceModules), making these tests deterministic.
 jest.spyOn(fs, 'readFileSync').mockReturnValue('');
 
-const entry = (naturalPath /*: string */, bucket /*: string */) => ({
+const entry = (
+  naturalPath /*: string */,
+  bucket /*: string */,
+  source /*:: ?: string */,
+) => ({
   naturalPath,
   bucket,
   lang: 'objc',
-  identities: [{source: `does/not/exist/${naturalPath}`}],
+  identities: [{source: source ?? `does/not/exist/${naturalPath}`}],
 });
 
 // A manifest satisfying both the R9 private-header allowlist and the R10
@@ -140,3 +144,113 @@ describe('R10 per-namespace umbrella (React_RCTAppDelegate)', () => {
     );
   });
 });
+
+describe('R5 invalid-identifier exemption assert (H5)', () => {
+  test('throws when an invalid-identifier namespace gains a modular candidate', () => {
+    const m = validManifest();
+    m.headers.push(entry('bad-namespace/Foo.h', 'objc-modular-candidate'));
+    expect(() => planFromInventory(m)).toThrow(
+      /namespace 'bad-namespace' is not a valid module identifier/,
+    );
+  });
+
+  test('invalid-identifier namespaces with only non-modular headers stay exempt', () => {
+    const m = validManifest();
+    m.headers.push(entry('jsinspector-modern/Foo.h', 'objcxx'));
+    expect(() => planFromInventory(m)).not.toThrow();
+  });
+});
+
+describe('R11 redirect shims for dual-identity headers', () => {
+  test('RNH spelling of a source that also ships as React/ becomes a shim', () => {
+    const m = validManifest();
+    m.headers.push(
+      entry('React/RCTClipboard.h', 'objc-modular-candidate', 'src/clip.h'),
+      entry(
+        'CoreModules/RCTClipboard.h',
+        'objc-modular-candidate',
+        'src/clip.h',
+      ),
+    );
+    const plan = planFromInventory(m);
+    const shim = plan.reactNativeHeaders.find(
+      e => e.naturalPath === 'CoreModules/RCTClipboard.h',
+    );
+    expect(shim?.redirectTo).toBe('React/RCTClipboard.h');
+    // The React/ owner keeps its content.
+    const owner = plan.react.find(
+      e => e.naturalPath === 'React/RCTClipboard.h',
+    );
+    expect(owner?.redirectTo).toBeUndefined();
+    // The shim stays a namespace-module member (imports the owning module).
+    expect(plan.namespaceModules.CoreModules).toContain(
+      'CoreModules/RCTClipboard.h',
+    );
+  });
+
+  test('bare root alias shims to its RNH namespaced owner', () => {
+    const m = validManifest();
+    m.headers.push(
+      entry('RCTAppDelegate.h', 'objc-modular-candidate', 'src/appdelegate.h'),
+    );
+    // Same source as the namespaced form.
+    const ns = m.headers.find(
+      x => x.naturalPath === 'React_RCTAppDelegate/RCTAppDelegate.h',
+    );
+    if (ns == null) {
+      throw new Error('fixture missing namespaced RCTAppDelegate.h');
+    }
+    ns.identities[0].source = 'src/appdelegate.h';
+    const plan = planFromInventory(m);
+    const bare = plan.react.find(e => e.naturalPath === 'RCTAppDelegate.h');
+    expect(bare?.redirectTo).toBe('React_RCTAppDelegate/RCTAppDelegate.h');
+    const owner = plan.reactNativeHeaders.find(
+      e => e.naturalPath === 'React_RCTAppDelegate/RCTAppDelegate.h',
+    );
+    expect(owner?.redirectTo).toBeUndefined();
+  });
+
+  test('single-identity headers get no redirect', () => {
+    const plan = planFromInventory(validManifest());
+    for (const e of [...plan.react, ...plan.reactNativeHeaders]) {
+      expect(e.redirectTo).toBeUndefined();
+    }
+  });
+});
+
+describe('headers-verify gate pieces', () => {
+  const {
+    diffAgainstBaseline,
+    renderObjcFixture,
+    renderPrivilegedFixture,
+  } = require('../headers-verify');
+
+  test('diffAgainstBaseline ratchets: new offenders fail, resolved reported', () => {
+    const {newOffenders, resolved} = diffAgainstBaseline(
+      ['a', 'c'],
+      ['a', 'b'],
+    );
+    expect(newOffenders).toEqual(['c']);
+    expect(resolved).toEqual(['b']);
+  });
+
+  test('ObjC fixture asserts and imports the R9/R10 + module surfaces', () => {
+    const plan = planFromInventory(validManifest());
+    const tu = renderObjcFixture(plan);
+    expect(tu).toContain('__has_include(<React/RCTBridge+Private.h>)');
+    expect(tu).toContain(
+      '__has_include(<React_RCTAppDelegate/React_RCTAppDelegate-umbrella.h>)',
+    );
+    expect(tu).toContain('#import <React/RCTBridge.h>');
+    expect(tu).toContain('#import <React/RCTBridge+Private.h>');
+    // One import per namespace module (fixture has React_RCTAppDelegate).
+    expect(tu).toMatch(/#import <React_RCTAppDelegate\//);
+  });
+
+  test('privileged fixture imports every R9 textual header', () => {
+    const plan = planFromInventory(validManifest());
+    const tu = renderPrivilegedFixture(plan);
+    expect(tu).toContain('#import <React/RCTMountingManager.h>');
+    expect(tu).toContain('#import <React/RCTViewComponentView.h>');
+  });
+});

packages/react-native/scripts/ios-prebuild/__tests__/headers-spec-test.js

@@ -58,7 +58,19 @@ function stageEntries(
   for (const e of entries) {
     const dest = path.join(stage, e.relPath);
     fs.mkdirSync(path.dirname(dest), {recursive: true});
-    fs.copyFileSync(path.join(rnRoot, e.source), dest);
+    if (e.redirectTo != null) {
+      // R11: duplicate spelling of a source that lives elsewhere — emit a
+      // redirect shim so the declarations exist in exactly one file (module
+      // ownership and #import-once stay coherent across spellings).
+      fs.writeFileSync(
+        dest,
+        `// @generated by headers-compose (R11): this spelling redirects to\n` +
+          `// the content's single home so clang modules stay coherent.\n` +
+          `#import <${e.redirectTo}>\n`,
+      );
+    } else {
+      fs.copyFileSync(path.join(rnRoot, e.source), dest);
+    }
   }
 }
 
@@ -176,6 +188,25 @@ function buildReactNativeHeadersXcframework(
     }
     execSync(`/bin/cp -Rc "${src}" "${path.join(stage, ns)}"`);
   }
+  // Set equality with the deps artifact: a namespace dir present in the
+  // artifact but NOT declared in DEPS_NAMESPACES means a new third-party dep
+  // was added upstream and would silently not be relocated — consumers'
+  // `<newdep/...>` includes would break. Declare it once in headers-spec.js
+  // (the include classifier derives from the same list).
+  const foundDepsDirs = fs
+    .readdirSync(depsHeaders, {withFileTypes: true})
+    .filter(e => e.isDirectory())
+    .map(e => String(e.name));
+  const undeclared = foundDepsDirs.filter(
+    d => !plan.depsNamespaces.includes(d),
+  );
+  if (undeclared.length > 0) {
+    throw new Error(
+      `headers-compose: deps artifact ships undeclared namespace(s): ` +
+        `${undeclared.join(', ')}. Add them to DEPS_NAMESPACES in ` +
+        `headers-spec.js so they are relocated into ReactNativeHeaders.`,
+    );
+  }
   // Hermes public headers (separate source from the deps namespaces — they
   // come from the hermes-ios tarball, not ReactNativeDependencies). Vend only
   // the `hermes/` namespace; `jsi/` is already provided elsewhere, so copying

packages/react-native/scripts/ios-prebuild/headers-compose.js

@@ -0,0 +1,29 @@
+[
+  "notShipped react/nativemodule/intersectionobserver/NativeIntersectionObserver.h -> react/renderer/observers/intersection/IntersectionObserverManager.h",
+  "notShipped react/nativemodule/mutationobserver/NativeMutationObserver.h -> react/renderer/observers/mutation/MutationObserverManager.h",
+  "notShipped react/renderer/animated/InterpolationAnimatedNode.h -> react/renderer/animated/internal/primitives.h",
+  "notShipped react/renderer/animated/NativeAnimatedNodesManager.h -> react/renderer/animated/event_drivers/EventAnimationDriver.h",
+  "notShipped react/renderer/animated/PropsAnimatedNode.h -> react/renderer/animated/internal/primitives.h",
+  "notShipped react/renderer/mounting/MountingCoordinator.h -> react/renderer/mounting/stubs/stubs.h",
+  "notShipped react/renderer/mounting/StubViewTree.h -> react/renderer/mounting/stubs/StubView.h",
+  "notShipped react/renderer/mounting/stubs.h -> react/renderer/mounting/stubs/StubView.h",
+  "notShipped react/renderer/mounting/stubs.h -> react/renderer/mounting/stubs/StubViewTree.h",
+  "quotedNotShipped RCTAnimation/RCTEventAnimation.h -> \"RCTValueAnimatedNode.h\"",
+  "quotedNotShipped RCTAnimation/RCTNativeAnimatedModule.h -> \"RCTValueAnimatedNode.h\"",
+  "quotedNotShipped RCTAnimation/RCTNativeAnimatedTurboModule.h -> \"RCTValueAnimatedNode.h\"",
+  "quotedNotShipped React/RCTEventAnimation.h -> \"RCTValueAnimatedNode.h\"",
+  "quotedNotShipped React/RCTNativeAnimatedModule.h -> \"RCTValueAnimatedNode.h\"",
+  "quotedNotShipped React/RCTNativeAnimatedTurboModule.h -> \"RCTValueAnimatedNode.h\"",
+  "quotedNotShipped react/nativemodule/dom/NativeDOM.h -> \"FBReactNativeSpecJSI.h\"",
+  "quotedNotShipped react/nativemodule/featureflags/NativeReactNativeFeatureFlags.h -> \"FBReactNativeSpecJSI.h\"",
+  "quotedNotShipped react/nativemodule/idlecallbacks/NativeIdleCallbacks.h -> \"FBReactNativeSpecJSI.h\"",
+  "quotedNotShipped react/nativemodule/intersectionobserver/NativeIntersectionObserver.h -> \"FBReactNativeSpecJSI.h\"",
+  "quotedNotShipped react/nativemodule/microtasks/NativeMicrotasks.h -> \"FBReactNativeSpecJSI.h\"",
+  "quotedNotShipped react/nativemodule/mutationobserver/NativeMutationObserver.h -> \"FBReactNativeSpecJSI.h\"",
+  "quotedNotShipped react/nativemodule/viewtransition/NativeViewTransition.h -> \"FBReactNativeSpecJSI.h\"",
+  "quotedNotShipped react/nativemodule/webperformance/NativePerformance.h -> \"FBReactNativeSpecJSI.h\"",
+  "quotedNotShipped react/nativemodule/webperformance/NativePerformance.h -> \"rncoreJSI.h\"",
+  "quotedNotShipped react/renderer/animated/AnimatedModule.h -> \"FBReactNativeSpecJSI.h\"",
+  "quotedNotShipped react/renderer/animated/NativeAnimatedNodesManager.h -> \"FBReactNativeSpecJSI.h\"",
+  "quotedNotShipped reactperflogger/FuseboxTracer.h -> \"folly/json/dynamic.h\""
+]

packages/react-native/scripts/ios-prebuild/headers-include-baseline.json

@@ -62,20 +62,23 @@ type HeaderEntry = {
     otherPlatform: Array<string>,
     notShipped: Array<string>,
     unresolved: Array<string>,
+    // Quoted includes that do not resolve to a shipped header. Fine inside the
+    // framework binary's own compilation, but a consumer compiling the shipped
+    // header hits "file not found" (source builds mask this via pod header
+    // maps). Gated by the include-health ratchet (headers-verify.js).
+    quotedNotShipped: Array<string>,
   },
 };
 */
 
 // Third-party C++ libraries that RN's public headers re-expose (Tier 3 of the
-// modularization doc). Keyed by the first include-path segment.
-const THIRD_PARTY_LIBS /*: Set<string> */ = new Set([
-  'folly',
-  'boost',
-  'fmt',
-  'glog',
-  'double-conversion',
-  'fast_float',
-]);
+// modularization doc). Keyed by the first include-path segment. Single source
+// of truth: the spec's DEPS_NAMESPACES (the namespaces relocated into
+// ReactNativeHeaders) — a new third-party dep is declared ONCE and both the
+// include classifier and the compose step follow. (headers-spec.js requires
+// only fs/path, so this cannot cycle.)
+const {DEPS_NAMESPACES} = require('./headers-spec');
+const THIRD_PARTY_LIBS /*: Set<string> */ = new Set(DEPS_NAMESPACES);
 
 // Apple SDK / platform include roots (first path segment). Includes resolving
 // here are "system": always modular or always available, never our problem.
@@ -295,6 +298,7 @@ function buildInventory(rootFolder /*: string */) /*: {
           otherPlatform: [],
           notShipped: [],
           unresolved: [],
+          quotedNotShipped: [],
         },
       };
       entries.set(naturalPath, entry);
@@ -424,9 +428,14 @@ function classifyEntries(
             naturalPath: naturals[0],
             cxxGuarded: inc.cxxGuarded,
           });
+        } else {
+          // A quoted include in a SHIPPED header that doesn't land on another
+          // shipped header: works in source builds (pod header maps / sibling
+          // files) but has no resolution target in the packaged layout when a
+          // consumer compiles this header. Recorded for the include-health
+          // ratchet rather than silently dropped.
+          entry.includes.quotedNotShipped.push(token);
         }
-        // Quoted includes that don't land on a shipped header are
-        // pod-internal/private — not part of the public surface contract.
         continue;
       }
       if (entries.has(token)) {