not-react-native-macos 0.83.0-rc.1 → 0.87.1-rc.2

package/scripts/spm/scaffold-package-swift.js

@@ -0,0 +1,1247 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+'use strict';
+
+/*::
+import type {
+  AutolinkedDep,
+  AutolinkingIosPlatform,
+  PodspecModel,
+  ScaffoldResult,
+  SpmScaffoldSpec,
+} from './spm-types';
+*/
+
+/**
+ * scaffold-package-swift.js — generates a `Package.swift` into
+ * `node_modules/<dep>/` for community RN libraries that don't ship SPM
+ * support. The autolinker's existing `isSelfManagedPackage` check
+ * (generate-spm-autolinking.js, AUTOGEN_MARKER) treats these scaffolded
+ * files as self-managed and references them directly from the aggregator —
+ * no autolinker changes required.
+ *
+ * Three layers:
+ *   - translatePodspecToSpmTarget(model, dep): pure translation
+ *   - emitScaffoldedPackageSwift(spec, ctx): pure Swift emission
+ *   - scaffoldPackageSwiftForDep(dep, ctx): I/O + skip-rule + write
+ *   - scaffoldAll(opts): orchestrator over autolinking.json
+ */
+
+const {
+  SpmNameCollisionError,
+  defaultReadConfig,
+  defaultResolveDep,
+  expandSpmDependencies,
+} = require('./expand-spm-dependencies');
+const {expandSpmSourceGlobs} = require('./generate-spm-autolinking');
+const {readPodspec} = require('./read-podspec');
+const {
+  REACT_CODEGEN_PACKAGE_NAME,
+  REACT_CODEGEN_PRODUCTS,
+  REACT_NATIVE_PACKAGE_NAME,
+  REACT_NATIVE_PRODUCTS,
+  SCAFFOLDER_MARKER,
+  makeLogger,
+  remotePackageConfig,
+  toSwiftName,
+} = require('./spm-utils');
+const fs = require('fs');
+const path = require('path');
+
+const {log} = makeLogger('scaffold-package-swift');
+
+// SCAFFOLDER_MARKER lives in spm-utils.js (shared, no import cycle). It must NOT
+// contain the autolinker's AUTOGEN_MARKER ('// AUTO-GENERATED by
+// scripts/generate-spm-autolinking.js') — that marker is what the autolinker
+// uses to tell self-managed deps from its own synth output. Our marker is
+// recognized by the scaffolder itself (skip-rule), but invisible to the
+// autolinker (treated as self-managed).
+
+// Bump when the emitter's output format changes in a way that requires
+// re-scaffolding existing files (rather than just being a content drift the
+// cache-slot label already handles). v2: swift-tools-version moved to
+// line 1 — pre-v2 scaffolds emit it on a later line, which recent Xcode
+// rejects with "Swift tools version 3.1.0 ... no longer supported". v4: the
+// single `let rnHeaders = appRoot + "/.../ReactHeadersAll"` split into the two
+// `rnCoreHeaders` / `appHeaders` lets (merged tree replaced by two trees), so
+// pre-v4 scaffolds reference a tree that is no longer materialized. v5:
+// header resolution moved to product dependencies (ReactNativeHeaders +
+// ReactAppHeaders binary/headers targets) — the rnCoreHeaders/appHeaders
+// trees no longer exist, so pre-v5 scaffolds carry dead lets and would break
+// if anything still referenced them. v7: the runtime appRoot walker and the
+// siblingPath helper are gone — package paths are plain relative strings
+// computed at scaffold time (the walker anchored on
+// build/xcframeworks/Package.swift, which remote mode no longer writes).
+//
+// Skip-rule contract: when an existing file's version is < this constant,
+// the scaffolder regenerates regardless of --force (the bump implies the
+// existing file is broken under current tooling). A file with the marker
+// but no version line is treated as v1.
+// v8: relative app paths (codegen / xcframeworks) are now computed from the
+// autolinker's libs/<SwiftName> symlink location instead of the real dep.root,
+// fixing a doubled-path resolution failure on fresh SwiftPM resolves.
+// v9: header search paths derived from each subspec's header_mappings_dir
+// (dirname) so namespaced includes (`<reanimated/...>`) resolve. v10:
+// publicHeadersPath derived from the header_mappings_dir namespace root so a
+// package exposes `<namespace/...>` to dependents; pod-style sibling deps
+// (reanimated's `s.dependency "RNWorklets"`) wired to their npm package. v11:
+// sibling .package path uses the libs/<SwiftName> symlink name, not the npm
+// name (fixes "package ... doesn't exist" on resolve). v12: preprocessor
+// defines from pod_target_xcconfig emitted as `.define(...)`. v13: ObjC(++)
+// targets get an ambient-import prefix header (Foundation/UIKit) `-include`d,
+// replacing CocoaPods' generated prefix.pch. v18: React-core deps also get
+// the ReactNativeDependenciesHeaders product (ReactNativeHeaders went
+// pure-RN; folly/glog/boost/... now come from the deps sidecar);
+// publicHeadersPath falls back to "." for root-level-source podspecs
+// (`s.source_files = "*.{h,m,mm}"`) instead of SPM's nonexistent `include/`.
+// v19: scaffolded C++ targets carry DEBUG/NDEBUG config defines so their Fabric
+// ABI matches the prebuilt React.framework (Release strips DebugStringConvertible
+// under NDEBUG). Bumped so existing scaffolds regenerate with the defines.
+const SCAFFOLDER_VERSION = 19;
+const SCAFFOLDER_VERSION_LINE_RE = /^\/\/ AUTO-SCAFFOLDED-VERSION: (\d+)$/m;
+
+const AUTOGEN_MARKER =
+  '// AUTO-GENERATED by scripts/generate-spm-autolinking.js';
+
+// CocoaPods auto-generates a `<Target>-prefix.pch` that imports Foundation +
+// UIKit into every ObjC translation unit, so pod sources can use NSThread /
+// dispatch / UIKit symbols without an explicit import. SPM has no prefix-header
+// mechanism, so we emit this file at the dep root and `-include` it on the
+// target (cSettings + cxxSettings) to reproduce that ambient import. The
+// `__OBJC__` guard makes it inert for plain C/C++ sources, and UIKit is
+// `__has_include`-guarded for platforms that lack it.
+// The config-gated C++ defines the prebuilt React.framework is built with (see
+// packages/react-native/Package.swift). Fabric C++ in autolinked deps must
+// compile with the SAME NDEBUG state or its DebugStringConvertible / ShadowNode
+// ABI diverges from the Release React.framework and the link fails.
+const REACT_CXX_CONFIG_DEFINES = [
+  '.define("DEBUG", .when(configuration: .debug))',
+  '.define("NDEBUG", .when(configuration: .release))',
+];
+
+const SCAFFOLD_PREFIX_HEADER = 'react-native-spm-prefix.h';
+const SCAFFOLD_PREFIX_HEADER_CONTENTS = `// AUTO-SCAFFOLDED by react-native spm scaffold — mirrors CocoaPods' default
+// prefix header so ObjC sources that rely on an implicit Foundation/UIKit
+// import compile under SPM (which has no prefix-header mechanism). Safe to
+// delete + regenerate via \`npx react-native spm scaffold\`.
+#ifdef __OBJC__
+#import <Foundation/Foundation.h>
+#if __has_include(<UIKit/UIKit.h>)
+#import <UIKit/UIKit.h>
+#endif
+#endif
+`;
+
+// Names of deps the scaffolder always refuses to touch — `react-native`
+// itself is handled by the xcframework subpackage, never as an autolinked
+// target.
+const NEVER_SCAFFOLD /*: ReadonlySet<string> */ = new Set(['react-native']);
+
+// React-core / React-Fabric / etc. dependency names collapse to a single
+// invariant React header-product set. The app target links the prebuilt
+// runtime frameworks outside SwiftPM. This
+// list matches what `install_modules_dependencies(s)` materializes plus
+// common podspec hand-rolled additions.
+const REACT_CORE_DEP_PREFIXES = [
+  'React-',
+  'React_',
+  'ReactCommon',
+  'RCT-Folly',
+  'RCT',
+  'glog',
+  'boost',
+  'fmt',
+  'DoubleConversion',
+  'Yoga',
+  'hermes-engine',
+];
+
+function isReactCoreDep(name /*: string */) /*: boolean */ {
+  return REACT_CORE_DEP_PREFIXES.some(p => name.startsWith(p));
+}
+
+// True when the dep ships a `codegenConfig` in package.json — RN's standard
+// marker that the library participates in the New Architecture / codegen. Such
+// a lib's Fabric sources include the app-generated component headers
+// (`<react/renderer/components/<name>/ShadowNodes.h>` etc.), which are vended by
+// the per-app React-GeneratedCode package — so it implicitly depends on React
+// core even when its podspec only wires that via `install_modules_dependencies`
+// (which we strip). Safe/quiet: a missing or unparseable package.json → false.
+function depHasCodegenConfig(depRoot /*: string */) /*: boolean */ {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(depRoot, 'package.json'), 'utf8'),
+    );
+    return pkg != null && pkg.codegenConfig != null;
+  } catch {
+    return false;
+  }
+}
+
+// Every subdirectory (relative to depRoot) under depRoot/base, recursively —
+// used to expand a CocoaPods `path/**` recursive header search path into the
+// concrete dirs SPM needs (SPM has no recursive search-path syntax). Skips
+// VCS / build / dependency noise.
+function collectSubdirs(
+  depRoot /*: string */,
+  base /*: string */,
+) /*: Array<string> */ {
+  const SKIP /*: Set<string> */ = new Set([
+    'node_modules',
+    'Pods',
+    'build',
+    '.git',
+  ]);
+  const out /*: Array<string> */ = [];
+  const walk = (absDir /*: string */, relDir /*: string */) => {
+    let entries /*: Array<{name: string, isDirectory(): boolean}> */ = [];
+    try {
+      // $FlowFixMe[incompatible-type] Dirent typing
+      entries = fs.readdirSync(absDir, {withFileTypes: true});
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      // $FlowFixMe[incompatible-type] Dirent.name is string|Buffer in stubs
+      const name /*: string */ = e.name;
+      if (!e.isDirectory() || name.startsWith('.') || SKIP.has(name)) continue;
+      const rel = relDir === '.' ? name : `${relDir}/${name}`;
+      out.push(rel);
+      walk(path.join(absDir, name), rel);
+    }
+  };
+  walk(path.join(depRoot, base), base === '.' ? '.' : base);
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Translation
+// ---------------------------------------------------------------------------
+
+/**
+ * Pure: turns a flattened PodspecModel into an SpmScaffoldSpec the emitter
+ * can consume. Substitutes Xcode build-setting tokens (`$(PODS_TARGET_SRCROOT)`)
+ * against the dep root, buckets dependencies, drops unknown tokens with a
+ * warning.
+ */
+function translatePodspecToSpmTarget(
+  model /*: PodspecModel */,
+  dep /*: AutolinkedDep */,
+  // Maps a podspec name (e.g. "RNWorklets") to the npm package name of an
+  // autolinked sibling (e.g. "react-native-worklets"). Lets us wire a
+  // `s.dependency "RNWorklets"` — a pod-style name the `react-native-*`
+  // heuristic can't recognize — to the right sibling package. Empty by default.
+  podToNpm /*: Map<string, string> */ = new Map(),
+  // npm name → resolved Swift name for every autolinked dep, so a sibling
+  // reference honors that sibling's `spm.name` instead of re-deriving it.
+  swiftNameByNpm /*: Map<string, string> */ = new Map(),
+) /*: SpmScaffoldSpec */ {
+  const warnings = [...model.warnings];
+
+  // Swift target name: whatever the autolinker resolved for this dep — its
+  // `spm.name` override when set, else toSwiftName(npm-name). The autolinker
+  // registers the dep under that name in its aggregator (and in any sibling
+  // spm.dependencies refs), so the scaffolded Package.swift's product/library
+  // name must match it exactly — otherwise SPM resolution fails with a name
+  // mismatch on `.product(name: "X", package: "X")`.
+  //
+  // The podspec's `header_dir` is captured separately: when it changes the
+  // include surface (e.g. `<reanimated/...>` instead of `<ReactNativeReanimated/...>`),
+  // header resolution already works via the -I flags from headerSearchPaths
+  // (path-style includes like safe-area-context's
+  // `<react/renderer/components/safeareacontext/...>` resolve through
+  // `-I common/cpp/`). Module-style includes that NEED the target name to
+  // match (e.g. reanimated's `<reanimated/X.h>` via SwiftPM's auto-generated
+  // module map) are what `spm.name` is for.
+  const swiftName = dep.swiftName ?? toSwiftName(dep.name);
+
+  // Header search paths — substitute Xcode build-setting tokens against the
+  // dep root. Anything we can't substitute is dropped + warned (avoids
+  // emitting `$(SOMETHING)` literally into the Swift file).
+  const headerSearchPaths /*: Array<string> */ = [];
+  const addSearchPath = (p /*: string */) => {
+    if (p.length > 0 && !headerSearchPaths.includes(p)) {
+      headerSearchPaths.push(p);
+    }
+  };
+  for (const raw of model.headerSearchPaths) {
+    let substituted = raw
+      .replace(/\$\(PODS_TARGET_SRCROOT\)/g, '.')
+      .replace(/\$\{PODS_TARGET_SRCROOT\}/g, '.');
+    if (/\$[({]/.test(substituted)) {
+      warnings.push(
+        `Dropped HEADER_SEARCH_PATHS entry "${raw}" — contains unresolved Xcode token. ` +
+          `Add it manually if needed.`,
+      );
+      continue;
+    }
+    // CocoaPods `path/**` (or `/*`) = recursive search. SPM has no recursive
+    // search-path syntax, so add the base dir + every subdirectory under it.
+    const recursive = /\/\*\*?$/.test(substituted);
+    substituted = substituted
+      .replace(/\/\*\*?$/, '') // strip the glob marker
+      .replace(/\/{2,}/g, '/'); // collapse `cpp//` → `cpp/`
+    // Strip leading "./" (emitter prefixes with the target path) + trailing "/".
+    const base = substituted
+      .replace(/^\.\//, '')
+      .replace(/^\//, '')
+      .replace(/\/$/, '');
+    addSearchPath(base === '' ? '.' : base);
+    if (recursive) {
+      for (const sub of collectSubdirs(dep.root, base === '' ? '.' : base)) {
+        addSearchPath(sub);
+      }
+    }
+  }
+
+  // header_mappings_dir → search path. CocoaPods exposes a subspec's headers
+  // under `<basename(mappings_dir)>/...` by copying them into Pods/Headers
+  // preserving structure relative to the mappings dir. SPM has no such copy
+  // step, so namespaced includes like `<reanimated/apple/sensor/X.h>` (header
+  // physically at `apple/reanimated/apple/sensor/X.h`, mappings dir
+  // `apple/reanimated`) only resolve if the mappings dir's PARENT (`apple`) is
+  // on the search path. Add dirname() of every subspec's mappings dir.
+  for (const mappingsDir of model.headerMappingsDirs) {
+    const parent = path.posix.dirname(mappingsDir.replace(/^\.\//, ''));
+    // dirname of a single-segment dir is "." (root) — already implicitly
+    // searched; skip it and anything that doesn't exist on disk.
+    if (
+      parent.length > 0 &&
+      parent !== '.' &&
+      !headerSearchPaths.includes(parent) &&
+      fs.existsSync(path.join(dep.root, parent))
+    ) {
+      headerSearchPaths.push(parent);
+    }
+  }
+
+  // Bucket dependencies. React-Core / React-jsi / RCT-Folly / glog etc. ALL
+  // collapse to the invariant React header products
+  // reference because they're bundled in the prebuilt React.xcframework.
+  // Sibling RN libs (autolinked or self-managed deps) flow through the
+  // existing spm-deps mechanism. Unknown names are dropped with a warning.
+  let coreReactNative = false;
+  const siblingNames /*: Array<string> */ = [];
+  const selfPodspecName = model.name;
+  for (const depName of model.dependencies) {
+    // Cross-subspec refs like "react-native-safe-area-context/common" are a
+    // CocoaPods construct for one subspec depending on another from the
+    // SAME podspec. After flattenSubspecs has merged everything into one
+    // target the subspec ref is meaningless — drop silently.
+    if (depName.includes('/') && depName.startsWith(`${selfPodspecName}/`)) {
+      continue;
+    }
+    const podSibling = podToNpm.get(depName.split('/')[0]);
+    if (isReactCoreDep(depName)) {
+      coreReactNative = true;
+    } else if (depName.startsWith('react-native-')) {
+      // Generic cross-subspec ref guard for any "package/subspec" form.
+      const baseName = depName.split('/')[0];
+      if (!siblingNames.includes(baseName)) {
+        siblingNames.push(baseName);
+      }
+    } else if (podSibling != null && podSibling !== dep.name) {
+      // A pod-style dependency name (e.g. reanimated's `s.dependency
+      // "RNWorklets"`) that resolves to an autolinked sibling's npm package
+      // (react-native-worklets). Wire it as a sibling .package/.product so
+      // the dep's cross-package includes (`<worklets/...>`) resolve.
+      if (!siblingNames.includes(podSibling)) {
+        siblingNames.push(podSibling);
+      }
+    } else {
+      // Could be a non-RN dep ("MMKV", "AFNetworking"). The scaffolder
+      // doesn't know how to wire those — surface a warning so user can
+      // edit the generated Package.swift.
+      warnings.push(
+        `Unknown dependency "${depName}" — not wired into the scaffolded Package.swift. Edit manually if needed.`,
+      );
+    }
+  }
+
+  // New-Architecture libraries declare their React-core dependency via the
+  // `install_modules_dependencies(s)` podspec helper (which auto-adds
+  // React-Core / React-RCTFabric / React-Codegen), NOT an explicit
+  // `s.dependency "React-Core"`. We strip that helper when evaluating the
+  // podspec, so the React-core dependency never surfaces in model.dependencies
+  // and `coreReactNative` would stay false. The authoritative, RN-standard
+  // marker for "this lib participates in the New Architecture / codegen" is a
+  // `codegenConfig` block in package.json — when present, the app's codegen has
+  // generated `react/renderer/components/<name>/{ShadowNodes,Props,…}.h` that
+  // the lib's Fabric sources include via angle brackets. Those generated
+  // headers live in the per-app React-GeneratedCode package, so the lib must
+  // depend on it (and, transitively, on React core). Treat codegenConfig as
+  // an implicit React-core dependency.
+  // `codegenConfig` only marks Fabric/New-Arch libraries. A plain ObjC module
+  // (e.g. rn-tester's TestLibrary*) that wires React core solely through
+  // `install_modules_dependencies(s)` has no codegenConfig — but the helper's
+  // presence is itself an authoritative "depends on React core" signal, so
+  // treat it the same way.
+  if (
+    !coreReactNative &&
+    (depHasCodegenConfig(dep.root) ||
+      model.usesInstallModulesDependencies === true)
+  ) {
+    coreReactNative = true;
+  }
+
+  // SPM's `sources:` field does NOT accept CocoaPods-style globs — it wants
+  // a list of explicit file paths (relative to the target's `path:`).
+  // Expand the podspec globs against the actual filesystem so the emitted
+  // Package.swift parses cleanly.
+  let expandedSources /*: Array<string> */ = [];
+  try {
+    expandedSources = expandSpmSourceGlobs(dep.root, model.sourceFiles);
+  } catch (e) {
+    warnings.push(
+      `Source glob expansion failed (${e.message}); emitting raw globs — SPM will likely reject them.`,
+    );
+    expandedSources = model.sourceFiles;
+  }
+  // Strip files matching exclude_files (podspec's negation list).
+  if (model.excludeFiles.length > 0) {
+    try {
+      // $FlowFixMe[untyped-import] micromatch has no types
+      const micromatch = require('micromatch');
+      const isExcluded = micromatch.matcher(model.excludeFiles);
+      expandedSources = expandedSources.filter(f => !isExcluded(f));
+    } catch (e) {
+      warnings.push(
+        `exclude_files filtering failed (${e.message}); keeping all sources.`,
+      );
+    }
+  }
+  // Never self-ingest scaffold artifacts: a re-scaffold runs with the
+  // previous run's output on disk, and root-level podspec globs sweep it
+  // into sources — `*.{h,...,swift}` matches Package.swift itself, whose
+  // `.swift` extension then trips the mixed-language gate into DELETING the
+  // manifest it just wrote (alternating scaffold/self-destruct runs); the
+  // prefix header and the include/ shim mirror would similarly feed back.
+  expandedSources = expandedSources.filter(
+    f =>
+      f !== SCAFFOLD_PREFIX_HEADER &&
+      f !== 'Package.swift' &&
+      !f.startsWith('include/'),
+  );
+
+  // Header-map emulation: CocoaPods builds a header map (USE_HEADERMAP=YES by
+  // default) so a source can `#import "Foo.h"` by bare name regardless of which
+  // subdirectory Foo.h lives in. SPM has no header map, so add every directory
+  // that contains a header to the search path. Covers libs (e.g. svg) that
+  // spread flat-named headers across many subdirs.
+  const headerFiles = expandedSources.filter(f => /\.(h|hh|hpp)$/i.test(f));
+  try {
+    for (const f of expandSpmSourceGlobs(dep.root, model.publicHeaderFiles)) {
+      if (/\.(h|hh|hpp)$/i.test(f)) headerFiles.push(f);
+    }
+  } catch {
+    // public_header_files globbing is best-effort — source_files usually
+    // already covers the headers.
+  }
+  for (const f of headerFiles) {
+    const d = path.posix.dirname(f);
+    addSearchPath(d === '' ? '.' : d);
+  }
+
+  // ObjC(++) sources may rely on CocoaPods' implicit prefix-header import of
+  // Foundation/UIKit. When present, emit + `-include` a prefix header (below).
+  // The prefix is `-include`d by bare name, so the dep root (".") must be on
+  // the header search path for clang to find it.
+  const needsObjCPrefix = expandedSources.some(f => /\.mm?$/.test(f));
+  if (needsObjCPrefix && !headerSearchPaths.includes('.')) {
+    headerSearchPaths.push('.');
+  }
+
+  // SPM REQUIRES publicHeadersPath to be a real directory inside the target
+  // when the target compiles C-family sources (default is "include" which
+  // typically doesn't exist in a podspec-shaped dep). Pick the first
+  // existing prefix dir from public_header_files / source_files. The
+  // chosen dir doesn't need to be the include surface — path-style
+  // includes (`<react/renderer/.../X.h>`) resolve via headerSearchPaths
+  // instead. publicHeadersPath just has to point at a real dir containing
+  // some .h files so SPM accepts the target definition.
+  let publicHeadersPath /*: ?string */ = null;
+  // Prefer the namespace root (parent of a header_mappings_dir). SPM propagates
+  // a target's publicHeadersPath to DEPENDENT packages as a search path, so
+  // setting it to e.g. `Common/cpp` (parent of `Common/cpp/worklets`) is what
+  // lets a sibling package resolve `<worklets/...>`. Prefer a cross-platform
+  // (Common) dir — that holds the C++ API siblings consume — over a
+  // platform-specific (apple/) one.
+  const mappingsParents = model.headerMappingsDirs
+    .map(d => path.posix.dirname(d.replace(/^\.\//, '')))
+    .filter(
+      p => p.length > 0 && p !== '.' && fs.existsSync(path.join(dep.root, p)),
+    );
+  if (mappingsParents.length > 0) {
+    publicHeadersPath =
+      mappingsParents.find(p => /(?:^|\/)common(?:\/|$)/i.test(p)) ??
+      mappingsParents[0];
+  }
+  if (publicHeadersPath == null) {
+    for (const glob of [...model.publicHeaderFiles, ...model.sourceFiles]) {
+      const prefix = glob.split('/')[0];
+      if (
+        prefix.length > 0 &&
+        !prefix.includes('*') &&
+        fs.existsSync(path.join(dep.root, prefix))
+      ) {
+        publicHeadersPath = prefix;
+        break;
+      }
+    }
+  }
+  let namespacedShimHeaders /*: Array<string> */ = [];
+  if (publicHeadersPath == null) {
+    // Root-level podspecs (`s.source_files = "*.{h,m,mm}"`) keep their
+    // headers in the package root. CocoaPods exposes them to dependents as
+    // `#import <PodName/Header.h>` via header maps; SPM has no equivalent, so
+    // the scaffold writer mirrors them into a generated include/<SwiftName>/
+    // shim dir and publicHeadersPath points there (also fixing SPM's
+    // rejection over the nonexistent default `include/`).
+    const rootHeaders = expandedSources.filter(
+      f => f.endsWith('.h') && !f.includes('/'),
+    );
+    if (rootHeaders.length > 0) {
+      namespacedShimHeaders = rootHeaders;
+      publicHeadersPath = 'include';
+    }
+  }
+  if (publicHeadersPath == null) {
+    warnings.push(
+      `Could not infer publicHeadersPath from source globs. SPM may reject the target — add a publicHeadersPath manually to the scaffolded Package.swift.`,
+    );
+  }
+
+  const siblingSwiftNames /*: {[npmName: string]: string} */ = {};
+  for (const npmName of siblingNames) {
+    const resolved = swiftNameByNpm.get(npmName);
+    if (resolved != null) {
+      siblingSwiftNames[npmName] = resolved;
+    }
+  }
+
+  return {
+    swiftName,
+    sources: expandedSources,
+    headerSearchPaths,
+    preprocessorDefines: model.preprocessorDefines,
+    needsObjCPrefix,
+    coreReactNative,
+    siblingNames,
+    siblingSwiftNames,
+    extraFrameworks: model.frameworks,
+    weakFrameworks: model.weakFrameworks,
+    compilerFlags: model.compilerFlags,
+    publicHeadersPath,
+    namespacedShimHeaders,
+    resources: model.resources,
+    warnings,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Swift emission
+// ---------------------------------------------------------------------------
+
+/*::
+type EmitContext = {
+  // Identifier embedded as a comment so SPM's manifest hash bumps when the
+  // active xcframework slot changes (otherwise cached evaluations would
+  // keep pointing at the prior slot's headers).
+  cacheSlotLabel: ?string,
+  // Remote SPM package mode (url/version/identity) — see remotePackageConfig.
+  remote?: ?{url: string, version: string, identity: string},
+  // Relative path (posix, from the dep's package dir) to the app's codegen
+  // package (<appRoot>/build/generated/ios). Computed at scaffold time —
+  // safe because the file is re-scaffolded per app/cache slot, and any
+  // node_modules relayout implies a reinstall that drops the file anyway.
+  codegenPackageDir?: ?string,
+  // Relative path to the app's local xcframeworks package
+  // (<appRoot>/build/xcframeworks). Only referenced when remote == null.
+  localXcfwPackageDir?: ?string,
+};
+*/
+
+/**
+ * Renders the SpmScaffoldSpec to a complete Package.swift string suitable
+ * for writing into `node_modules/<dep>/`. Fully declarative: all package
+ * references are plain relative paths computed at scaffold time (no runtime
+ * discovery — the scaffolder knows both the dep dir and the app root, and
+ * re-scaffolds whenever either could have moved).
+ */
+function emitScaffoldedPackageSwift(
+  spec /*: SpmScaffoldSpec */,
+  ctx /*:: ?: EmitContext */ = {cacheSlotLabel: null, remote: null},
+) /*: string */ {
+  const slotComment =
+    ctx.cacheSlotLabel != null ? `\n// Cache slot: ${ctx.cacheSlotLabel}` : '';
+
+  // React headers need NO search paths — they come from the React /
+  // ReactNativeHeaders binaryTargets and the ReactAppHeaders product (see
+  // the dependencies block below). Per-dep HEADER_SEARCH_PATHS from the
+  // podspec are emitted as `.headerSearchPath("<rel>")` so they resolve
+  // relative to `path:` ("." below). Custom podspec compiler flags keep
+  // using unsafeFlags (rare; surfaced verbatim).
+  const customFlagsCxx = spec.compilerFlags.map(f => `"${f}"`);
+
+  const headerSearchPathDirectives = spec.headerSearchPaths
+    .map(p => `.headerSearchPath("${p}")`)
+    .join(', ');
+
+  // Preprocessor defines → `.define("NAME", to: "VALUE", .when(...))`. The
+  // value is escaped as a Swift string literal because it may itself contain
+  // quotes (e.g. a string-literal macro `-DFOO="[A:false]"`).
+  const swiftStr = (s /*: string */) =>
+    `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  const defineDirectives = (spec.preprocessorDefines ?? [])
+    .map(d => {
+      const toPart = d.value != null ? `, to: ${swiftStr(d.value)}` : '';
+      const condPart =
+        d.config === 'debug'
+          ? ', .when(configuration: .debug)'
+          : d.config === 'release'
+            ? ', .when(configuration: .release)'
+            : '';
+      return `.define(${swiftStr(d.name)}${toPart}${condPart})`;
+    })
+    .join(', ');
+
+  const settingsEntries = (extra /*: Array<string> */) => {
+    const parts = [
+      defineDirectives,
+      headerSearchPathDirectives,
+      ...extra,
+    ].filter(e => e.length > 0);
+    return `[${parts.join(', ')}]`;
+  };
+  // Force-include the ambient-import prefix header on ObjC(++) sources (the
+  // `__OBJC__` guard makes it a no-op for plain C/C++). `-include` resolves the
+  // bare name via the dep-root header search path (".", ensured in translate).
+  const prefixFlag = spec.needsObjCPrefix
+    ? `.unsafeFlags(["-include", "${SCAFFOLD_PREFIX_HEADER}"])`
+    : '';
+  const cSettings = settingsEntries([prefixFlag].filter(e => e.length > 0));
+  const cxxSettings = settingsEntries(
+    [
+      prefixFlag,
+      ...(customFlagsCxx.length > 0
+        ? [`.unsafeFlags([${customFlagsCxx.join(', ')}])`]
+        : []),
+      // Match the prebuilt React.framework's config-gated C++ ABI. NDEBUG in
+      // Release strips DebugStringConvertible's vtable (and shifts the
+      // ShadowNode layout that inherits it), so a Fabric C++ target compiled
+      // WITHOUT NDEBUG fails to link against a Release React.framework. Mirrors
+      // packages/react-native/Package.swift's own C++ targets.
+      ...REACT_CXX_CONFIG_DEFINES,
+    ].filter(e => e.length > 0),
+  );
+
+  // Linker frameworks: defaults + podspec-declared extras + weak frameworks.
+  // Dedup on render so the user doesn't see duplicate UIKit lines.
+  const defaults = ['UIKit', 'Foundation', 'CoreGraphics'];
+  const linkedFrameworks = Array.from(
+    new Set([...defaults, ...spec.extraFrameworks]),
+  );
+  const linkerEntries = [
+    ...linkedFrameworks.map(f => `.linkedFramework("${f}")`),
+    ...spec.weakFrameworks.map(
+      f => `.linkedFramework("${f}", .when(platforms: [.iOS]))`,
+    ),
+  ];
+
+  // Dependencies block. Always declares ReactNative if any React-core dep
+  // was in the podspec; sibling RN deps come from autolinking's existing
+  // .package(path: ...) graph — we reference them by toSwiftName(npmName)
+  // since that's what the autolinker registers them under.
+  const packageDeps /*: Array<string> */ = [];
+  const targetDeps /*: Array<string> */ = [];
+  if (spec.coreReactNative) {
+    // Remote mode: React Native comes from the remote package identity (no
+    // app-layout knowledge). The per-app codegen package is generated INTO
+    // the app by definition, so it stays a path reference — relative,
+    // computed at scaffold time.
+    const remote = ctx.remote;
+    const rnLabel =
+      remote != null ? remote.identity : REACT_NATIVE_PACKAGE_NAME;
+    const codegenDir = ctx.codegenPackageDir;
+    if (codegenDir == null) {
+      throw new Error(
+        'emitScaffoldedPackageSwift: codegenPackageDir is required when the dep depends on React core.',
+      );
+    }
+    if (remote != null) {
+      packageDeps.push(
+        `.package(url: "${remote.url}", exact: "${remote.version}")`,
+      );
+    } else {
+      const xcfwDir = ctx.localXcfwPackageDir;
+      if (xcfwDir == null) {
+        throw new Error(
+          'emitScaffoldedPackageSwift: localXcfwPackageDir is required when no remote package is configured.',
+        );
+      }
+      packageDeps.push(
+        `.package(name: "${REACT_NATIVE_PACKAGE_NAME}", path: "${xcfwDir}")`,
+      );
+    }
+    packageDeps.push(
+      `.package(name: "${REACT_CODEGEN_PACKAGE_NAME}", path: "${codegenDir}")`,
+    );
+    for (const product of REACT_NATIVE_PRODUCTS) {
+      targetDeps.push(`.product(name: "${product}", package: "${rnLabel}")`);
+    }
+    for (const product of REACT_CODEGEN_PRODUCTS) {
+      targetDeps.push(
+        `.product(name: "${product}", package: "${REACT_CODEGEN_PACKAGE_NAME}")`,
+      );
+    }
+  }
+  for (const siblingName of spec.siblingNames) {
+    const swiftSibling =
+      spec.siblingSwiftNames?.[siblingName] ?? toSwiftName(siblingName);
+    // The autolinker references each self-managed (scaffolded) dep through a
+    // `libs/<SwiftName>` symlink, and SPM resolves a manifest's relative
+    // package paths against that symlink location — so a sibling lives at
+    // `../<SwiftName>` (NOT `../<npm-name>`, which would be `libs/<npm-name>`
+    // and not exist).
+    packageDeps.push(
+      `.package(name: "${swiftSibling}", path: "../${swiftSibling}")`,
+    );
+    targetDeps.push(
+      `.product(name: "${swiftSibling}", package: "${swiftSibling}")`,
+    );
+  }
+
+  // sources: emit only when the podspec declared them. If empty (regex-fallback
+  // podspec), no `sources:`/`exclude:` is emitted and SPM auto-scans the target
+  // dir — which for `path: "."` is the entire dep root. That is a known
+  // limitation of the regex-fallback path (the pod-ipc parse yields explicit
+  // sources); a future improvement could emit an `exclude:` list for the dep's
+  // example/test/build dirs.
+  const sourcesLine =
+    spec.sources.length > 0
+      ? `\n            sources: [\n${spec.sources.map(s => `                "${s}",`).join('\n')}\n            ],`
+      : '';
+
+  const publicHeadersLine =
+    spec.publicHeadersPath != null
+      ? `\n            publicHeadersPath: "${spec.publicHeadersPath}",`
+      : '';
+
+  const resourcesLine =
+    spec.resources.length > 0
+      ? `\n            resources: [${spec.resources.map(r => `.copy("${r}")`).join(', ')}],`
+      : '';
+
+  const packageDepsBlock =
+    packageDeps.length > 0
+      ? `    dependencies: [\n        ${packageDeps.join(',\n        ')},\n    ],\n`
+      : '';
+
+  const targetDepsLine =
+    targetDeps.length > 0
+      ? `\n            dependencies: [${targetDeps.join(', ')}],`
+      : '';
+
+  return `// swift-tools-version: 6.0
+${SCAFFOLDER_MARKER}
+// AUTO-SCAFFOLDED-VERSION: ${SCAFFOLDER_VERSION}${slotComment}
+// Edit the contents below if needed and re-run \`npx patch-package <dep-name>\`
+// to persist across \`npm install\`. To regenerate from the podspec, remove
+// this file (or just this marker) and re-run \`npx react-native spm scaffold\`.
+//
+// Package references are plain relative paths, computed when this file was
+// scaffolded. They stay correct because the file is re-scaffolded per app
+// and cache slot, and any node_modules relayout reinstalls this package
+// (dropping the file) anyway.
+
+import PackageDescription
+
+let package = Package(
+    name: "${spec.swiftName}",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(name: "${spec.swiftName}", targets: ["${spec.swiftName}"]),
+    ],
+${packageDepsBlock}    targets: [
+        .target(
+            name: "${spec.swiftName}",${targetDepsLine}
+            path: ".",${sourcesLine}${publicHeadersLine}${resourcesLine}
+            cSettings: ${cSettings},
+            cxxSettings: ${cxxSettings},
+            linkerSettings: [${linkerEntries.join(', ')}]
+        ),
+    ],
+    cxxLanguageStandard: .cxx20
+)
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Per-dep orchestrator
+// ---------------------------------------------------------------------------
+
+/*::
+type ScaffoldContext = {
+  appRoot: string,
+  projectRoot: string,
+  reactNativeRoot: string,
+  // Forces overwrite of files carrying the scaffolder marker. Files
+  // WITHOUT the marker (user-edited, upstream-shipped) are never touched.
+  force: boolean,
+  // When true, no file is written — caller gets the would-be content and
+  // can preview.
+  dryRun: boolean,
+  // Slot label (e.g. "0.87.0-nightly-20260513-6e262624f/debug") embedded as
+  // a comment so SPM's manifest hash bumps on slot changes.
+  cacheSlotLabel: ?string,
+  // podspec-name → npm-name index over all autolinked deps, so pod-style
+  // `s.dependency` names (e.g. "RNWorklets") wire to the right sibling.
+  podToNpm?: Map<string, string>,
+  // npm-name → resolved Swift name over all autolinked deps, so sibling
+  // references honor each sibling's `spm.name`.
+  swiftNameByNpm?: Map<string, string>,
+  remote: ?{url: string, version: string, identity: string},
+};
+*/
+
+/**
+ * Decides whether to scaffold one dep, runs the translation + emission,
+ * writes the file (unless dryRun). Pure path/skip logic — all I/O via fs.
+ */
+function scaffoldPackageSwiftForDep(
+  dep /*: AutolinkedDep */,
+  ctx /*: ScaffoldContext */,
+) /*: ScaffoldResult */ {
+  const depName = dep.name;
+
+  if (NEVER_SCAFFOLD.has(depName)) {
+    return {
+      depName,
+      status: 'skipped-is-react-native',
+      reason: 'react-native itself is handled by the xcframework package.',
+    };
+  }
+
+  // ios platform missing → no native code to wrap.
+  if (dep.platforms.ios == null) {
+    return {
+      depName,
+      status: 'skipped-no-ios',
+      reason: 'autolinking.json has no ios platform entry.',
+    };
+  }
+
+  // Dep can opt out via its own react-native.config.js.
+  const cfg = defaultReadConfig(dep.root);
+  // $FlowFixMe[prop-missing] config has dynamic shape
+  if (cfg != null && cfg.spm != null && cfg.spm.scaffold === false) {
+    return {
+      depName,
+      status: 'skipped-opt-out',
+      reason: 'react-native.config.js sets spm.scaffold = false.',
+    };
+  }
+
+  const pkgSwiftPath = path.join(dep.root, 'Package.swift');
+
+  // A self-managed Package.swift may live either at the dep root (legacy
+  // convention) or inside ios/ (preferred for community RN libs that want
+  // their npm-package root free of SPM artifacts). If a nested manifest
+  // exists and is user-authored, skip — writing a stray root manifest would
+  // cause the autolinker to prefer the wrong file.
+  const nestedPkgSwiftPath = path.join(dep.root, 'ios', 'Package.swift');
+  if (!fs.existsSync(pkgSwiftPath) && fs.existsSync(nestedPkgSwiftPath)) {
+    const nested = fs.readFileSync(nestedPkgSwiftPath, 'utf8');
+    if (
+      !nested.includes(AUTOGEN_MARKER) &&
+      !nested.includes(SCAFFOLDER_MARKER)
+    ) {
+      return {
+        depName,
+        status: 'skipped-self-managed',
+        reason:
+          'Existing ios/Package.swift was not produced by this scaffolder. ' +
+          'Leaving it alone.',
+      };
+    }
+  }
+
+  // Skip rules around existing files.
+  if (fs.existsSync(pkgSwiftPath)) {
+    const existing = fs.readFileSync(pkgSwiftPath, 'utf8');
+    if (existing.includes(AUTOGEN_MARKER)) {
+      return {
+        depName,
+        status: 'skipped-autogen',
+        reason:
+          'Existing Package.swift carries the autolinker AUTOGEN marker. ' +
+          'spm update will regenerate the synth wrapper.',
+      };
+    }
+    if (existing.includes(SCAFFOLDER_MARKER)) {
+      // Version bump → unconditional regen. A bumped SCAFFOLDER_VERSION
+      // implies the emitter's output format changed in a way that requires
+      // regenerating existing files; --force is not needed here.
+      const vMatch = existing.match(SCAFFOLDER_VERSION_LINE_RE);
+      const existingVersion = vMatch != null ? parseInt(vMatch[1], 10) : 1;
+      const versionStale = existingVersion < SCAFFOLDER_VERSION;
+      if (!ctx.force && !versionStale) {
+        // Slot label change is the other auto-regen trigger — bumps SPM's
+        // manifest hash so the cache-slot path gets re-resolved.
+        const m = existing.match(/^\/\/ Cache slot: (.+)$/m);
+        const existingSlot = m != null ? m[1] : null;
+        if (ctx.cacheSlotLabel == null || existingSlot === ctx.cacheSlotLabel) {
+          return {
+            depName,
+            status: 'skipped-scaffolder-marker',
+            reason:
+              'Already scaffolded for this cache slot. Pass --force to regenerate.',
+          };
+        }
+      }
+      if (versionStale) {
+        log(
+          `Re-scaffolding ${depName} (format v${existingVersion} → v${SCAFFOLDER_VERSION})`,
+        );
+      }
+      // Fall through: regenerate (force, slot changed, or version bumped).
+    } else {
+      // No marker at all → user-managed or upstream-shipped. Never touch.
+      return {
+        depName,
+        status: 'skipped-self-managed',
+        reason:
+          'Existing Package.swift was not produced by this scaffolder. ' +
+          'Leaving it alone.',
+      };
+    }
+  }
+
+  // Find a podspec to read. autolinking.json may have provided podspecPath;
+  // otherwise glob for *.podspec in dep root.
+  // $FlowFixMe[prop-missing] dynamic shape from autolinking.json
+  let podspecPath /*: ?string */ = dep.platforms.ios.podspecPath ?? null;
+  if (podspecPath == null) {
+    try {
+      const entries = fs.readdirSync(dep.root);
+      // Skip a crashed run's leftover patched copy (read-podspec.js stages it
+      // as `.spm-scaffold-<pid>-<name>.podspec` next to the original).
+      const candidate = entries.find(
+        e => e.endsWith('.podspec') && !e.startsWith('.spm-scaffold-'),
+      );
+      if (candidate != null) {
+        podspecPath = path.join(dep.root, candidate);
+      }
+    } catch {
+      // dep.root may not exist; treat as no-podspec
+    }
+  }
+  if (podspecPath == null || !fs.existsSync(podspecPath)) {
+    return {
+      depName,
+      status: 'skipped-no-podspec',
+      reason: 'No .podspec found in dep root.',
+    };
+  }
+
+  let model;
+  try {
+    model = readPodspec(podspecPath);
+  } catch (e) {
+    return {
+      depName,
+      status: 'error',
+      reason: `Podspec read failed: ${e.message}`,
+    };
+  }
+
+  const spec = translatePodspecToSpmTarget(
+    model,
+    dep,
+    ctx.podToNpm ?? new Map(),
+    ctx.swiftNameByNpm ?? new Map(),
+  );
+
+  // Mixed-language fail-closed: SPM can't compile Swift + C-family in one
+  // target. Don't emit a manifest that would fail with a cryptic "mixed
+  // language source files" resolve error — skip with a clear reason (and remove
+  // any stale scaffolded manifest so the autolinker reports it distinctly and
+  // points the user at opting it out / a binary distribution).
+  const hasSwift = spec.sources.some(f => /\.swift$/i.test(f));
+  const hasClang = spec.sources.some(f => /\.(mm?|c|cc|cpp|cxx)$/i.test(f));
+  if (hasSwift && hasClang) {
+    if (!ctx.dryRun && fs.existsSync(pkgSwiftPath)) {
+      const existing = fs.readFileSync(pkgSwiftPath, 'utf8');
+      if (existing.includes(SCAFFOLDER_MARKER)) {
+        fs.rmSync(pkgSwiftPath, {force: true});
+      }
+    }
+    return {
+      depName,
+      status: 'skipped-mixed-language',
+      reason:
+        'has mixed Swift + Objective-C/C++ sources, which SPM cannot compile ' +
+        'in one target (and the bidirectional ObjC↔Swift interop typical of ' +
+        'such libs cannot be split without a circular dependency). Opt it out ' +
+        'via react-native.config.js (platforms.ios = null) or use a prebuilt ' +
+        'xcframework.',
+    };
+  }
+
+  // Relative paths into the app, embedded in the scaffolded Package.swift.
+  //
+  // The manifest is written to <dep.root>/Package.swift, but the autolinker
+  // references the dep through a symlink at
+  // <appRoot>/build/generated/autolinking/libs/<SwiftName>. On a fresh resolve
+  // SwiftPM interprets a manifest's relative `.package(path:)` entries against
+  // that SYMLINK location (it does not canonicalize the symlink first), so the
+  // paths must be relative to the symlink dir — NOT the real dep.root.
+  // Computing from dep.root produced a doubled path
+  // (…/autolinking/ios/build/generated/ios) → opaque "package manifest cannot
+  // be accessed" resolution failure. posix separators, as SPM expects.
+  const symlinkDir = path.join(
+    ctx.appRoot,
+    'build',
+    'generated',
+    'autolinking',
+    'libs',
+    spec.swiftName,
+  );
+  const relFromManifest = (...segments /*: Array<string> */) =>
+    path
+      .relative(symlinkDir, path.join(ctx.appRoot, ...segments))
+      .split(path.sep)
+      .join('/');
+  const content = emitScaffoldedPackageSwift(spec, {
+    cacheSlotLabel: ctx.cacheSlotLabel,
+    remote: ctx.remote,
+    codegenPackageDir: relFromManifest('build', 'generated', 'ios'),
+    localXcfwPackageDir: relFromManifest('build', 'xcframeworks'),
+  });
+
+  // Distinguish "first-time scaffold" (no file at all) from "regenerate"
+  // (file with the scaffolder marker, e.g. slot changed). Used by the
+  // CLI orchestrator to decide whether to prompt for confirmation:
+  // first-time scaffolds touch a node_modules dir the user may not expect,
+  // regens are silent because we're maintaining a file we already own.
+  const previouslyExisted = fs.existsSync(pkgSwiftPath);
+
+  if (!ctx.dryRun) {
+    fs.writeFileSync(pkgSwiftPath, content, 'utf8');
+    // Emit the ambient-import prefix header next to the manifest when the
+    // target has ObjC(++) sources (the manifest `-include`s it by bare name).
+    if (spec.needsObjCPrefix) {
+      fs.writeFileSync(
+        path.join(dep.root, SCAFFOLD_PREFIX_HEADER),
+        SCAFFOLD_PREFIX_HEADER_CONTENTS,
+        'utf8',
+      );
+    }
+    // Mirror root-level headers into the generated include/<SwiftName>/ shim
+    // dir (publicHeadersPath) so dependents can use the CocoaPods header-map
+    // spelling `#import <SwiftName/Header.h>`.
+    if (spec.namespacedShimHeaders.length > 0) {
+      const shimDir = path.join(dep.root, 'include', spec.swiftName);
+      fs.mkdirSync(shimDir, {recursive: true});
+      for (const header of spec.namespacedShimHeaders) {
+        fs.writeFileSync(
+          path.join(shimDir, header),
+          `// AUTO-SCAFFOLDED by react-native spm scaffold — the namespaced\n` +
+            `// spelling (<${spec.swiftName}/${header}>) of the package-root header,\n` +
+            `// matching how CocoaPods header maps expose it.\n` +
+            `#import "../../${header}"\n`,
+          'utf8',
+        );
+      }
+    }
+  }
+
+  return {
+    depName,
+    status: 'written',
+    packageSwiftPath: pkgSwiftPath,
+    warnings: spec.warnings,
+    previouslyExisted,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Multi-dep orchestrator
+// ---------------------------------------------------------------------------
+
+/*::
+type ScaffoldAllOptions = {
+  appRoot: string,
+  projectRoot: string,
+  reactNativeRoot: string,
+  force?: boolean,
+  dryRun?: boolean,
+  cacheSlotLabel?: ?string,
+  autolinkingJsonPath?: string,
+  // npm dep names to skip entirely — used when the user declined the
+  // confirmation prompt for first-time scaffolds. Skipped deps still
+  // appear in the returned results array with status='skipped-opt-out'.
+  skipDeps?: ReadonlyArray<string>,
+};
+*/
+
+/**
+ * Walks autolinking.json, scaffolds each iOS-native dep, returns one
+ * ScaffoldResult per dep. Caller (setup-apple-spm.js) prints a structured
+ * summary.
+ */
+function scaffoldAll(
+  opts /*: ScaffoldAllOptions */,
+) /*: Array<ScaffoldResult> */ {
+  const {appRoot, projectRoot, reactNativeRoot} = opts;
+  const autolinkingJsonPath =
+    opts.autolinkingJsonPath ??
+    path.join(appRoot, 'build', 'generated', 'autolinking', 'autolinking.json');
+
+  if (!fs.existsSync(autolinkingJsonPath)) {
+    log(
+      `autolinking.json not found at ${path.relative(appRoot, autolinkingJsonPath)}; nothing to scaffold.`,
+    );
+    return [];
+  }
+
+  /*:: type AutolinkingJson = {dependencies?: ?{[string]: {root?: string, platforms?: {ios?: ?{...}, ...}, ...}}, ...}; */
+  // $FlowFixMe[incompatible-type] JSON.parse returns any
+  const data /*: AutolinkingJson */ = JSON.parse(
+    fs.readFileSync(autolinkingJsonPath, 'utf8'),
+  );
+  const deps = data.dependencies;
+  if (deps == null) {
+    return [];
+  }
+
+  // Narrow the direct autolinking.json entries with an iOS platform, then
+  // expand transitive `spm.dependencies` so the scaffolder covers EXACTLY the
+  // set the autolinker considers. Without this, a transitive native dep that
+  // ships no Package.swift would be flagged by the autolinker but never
+  // scaffolded here — leaving `react-native spm scaffold` unable to clear the
+  // autolinker's missing-manifest error.
+  const results /*: Array<ScaffoldResult> */ = [];
+  const directDeps /*: Array<AutolinkedDep> */ = [];
+  for (const name of Object.keys(deps)) {
+    const raw = deps[name];
+    if (raw == null) continue;
+    const root = raw.root;
+    const ios = raw.platforms?.ios;
+    if (typeof root !== 'string' || ios == null) {
+      results.push({
+        depName: name,
+        status: 'skipped-no-ios',
+        reason: 'no iOS platform in autolinking.json',
+      });
+      continue;
+    }
+    // $FlowFixMe[incompatible-type] `ios` shape is runtime-validated above
+    const iosPlatform /*: AutolinkingIosPlatform */ = ios;
+    directDeps.push({name, root, platforms: {ios: iosPlatform}});
+  }
+
+  // Outside the try: a malformed remote config (RemoteVersionError) is a
+  // misconfiguration to surface, not an expansion failure to degrade past.
+  const remote = remotePackageConfig(appRoot);
+
+  let allDeps /*: Array<AutolinkedDep> */ = [];
+  try {
+    allDeps = expandSpmDependencies(directDeps, {
+      readConfig: defaultReadConfig,
+      resolveDep: defaultResolveDep,
+      extraReservedNames: remote != null ? [remote.identity] : undefined,
+      log,
+    });
+  } catch (e) {
+    if (e instanceof SpmNameCollisionError) {
+      throw e;
+    }
+    // A transitive-resolution failure shouldn't abort the whole scaffold pass;
+    // fall back to the direct deps so at least those get manifests.
+    log(`Transitive spm.dependencies expansion failed: ${e.message}`);
+    allDeps = directDeps;
+  }
+
+  // Index every autolinked dep's podspec name → its npm name, so a dep that
+  // depends on a sibling by its pod name (reanimated's `s.dependency
+  // "RNWorklets"`) can be wired to the sibling's package (react-native-worklets).
+  // The podspec file basename is the pod name for RN-ecosystem libs (and is
+  // cheap — no `pod ipc` pre-pass).
+  const podToNpm /*: Map<string, string> */ = new Map();
+  for (const dep of allDeps) {
+    const podspecPath = dep.platforms?.ios?.podspecPath;
+    if (typeof podspecPath === 'string' && podspecPath.length > 0) {
+      podToNpm.set(path.basename(podspecPath, '.podspec'), dep.name);
+    } else {
+      // Transitive entries synthesized by expandSpmDependencies (declared via
+      // `spm.dependencies` in react-native.config.js) carry no podspecPath —
+      // discover the podspec at the dep root so podspec-name sibling deps
+      // (e.g. `s.dependency "TestLibraryCommon"`) still wire to their npm
+      // package.
+      try {
+        for (const f of fs.readdirSync(dep.root)) {
+          if (f.endsWith('.podspec') && !f.startsWith('.spm-scaffold-')) {
+            podToNpm.set(path.basename(f, '.podspec'), dep.name);
+          }
+        }
+      } catch {
+        // unreadable dep root — sibling wiring falls back to the warning path
+      }
+    }
+  }
+
+  const swiftNameByNpm /*: Map<string, string> */ = new Map();
+  for (const dep of allDeps) {
+    if (dep.swiftName != null) {
+      swiftNameByNpm.set(dep.name, dep.swiftName);
+    }
+  }
+
+  const ctx /*: ScaffoldContext */ = {
+    appRoot,
+    projectRoot,
+    reactNativeRoot,
+    force: opts.force === true,
+    dryRun: opts.dryRun === true,
+    cacheSlotLabel: opts.cacheSlotLabel ?? null,
+    podToNpm,
+    swiftNameByNpm,
+    remote,
+  };
+  const skipSet /*: Set<string> */ = new Set(opts.skipDeps ?? []);
+
+  for (const dep of allDeps) {
+    if (skipSet.has(dep.name)) {
+      results.push({
+        depName: dep.name,
+        status: 'skipped-opt-out',
+        reason: 'User declined scaffolding for this dep.',
+      });
+      continue;
+    }
+    try {
+      results.push(scaffoldPackageSwiftForDep(dep, ctx));
+    } catch (e) {
+      results.push({depName: dep.name, status: 'error', reason: e.message});
+    }
+  }
+  return results;
+}
+
+module.exports = {
+  scaffoldAll,
+  scaffoldPackageSwiftForDep,
+  translatePodspecToSpmTarget,
+  emitScaffoldedPackageSwift,
+  SCAFFOLDER_MARKER,
+  SCAFFOLDER_VERSION,
+};