Initial Open Sourcing of React Native Compatibility Check (#49340)

Summary:
Pull Request resolved: #49340

This tool enables checking the boundary between JavaScript and Native for
backwards incompatible changes to protect against crashes.

This is useful for:

- Local Development
- Over the Air updates on platforms that support it
- Theoretically: Server Components with React Native

Check out the Readme for more information

Changelog: [General][Added] Open Sourcing React Native's Compatibility Check

Reviewed By: panagosg7

Differential Revision: D69476742

fbshipit-source-id: 8af6039839c5475c1258fa82d9750a9320cf0751

Author: elicwhite

packages/react-native-compatibility-check/.gitignore

@@ -0,0 +1 @@
+lib

packages/react-native-compatibility-check/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+This tool is essentially a type checker, and as such it can be difficult to
+understand the data flow. Luckily, there are fairly extensive tests which can
+aid in ramping up.
+
+This tool is made up of 3 primary stages: TypeDiffing, VersionDiffing, and
+ErrorFormatting.
+
+At a high level, the schemas are passed to TypeDiffing which is the pure
+typechecker. It returns all differences between the types. VersionDiffing then
+interprets these results and decides if some of those changes are actually safe
+in the context of React Native’s JS/Native boundary.
+
+For example, if you have a NativeModule method that returns a string union
+`small | medium | large`. Any changes to that union would be flagged by
+TypeDiffing as incompatible. However, adding a value to that union is safe
+because it ensures your JS code handles more cases than native returns. Removing
+a value from that union isn’t safe though because it means your JS no longer
+handles something native might return which could cause an exception.
+
+VersionDiffing encodes the logic of what is safe and what isn’t;
+property/union/enum additions and removals, changing something from optional to
+required and vice versa, etc. VersionDiffing has knowledge of components and
+modules.
+
+VersionDiffing returns a set of incompatible changes, which then gets passed to
+ErrorFormatting. ErrorFormatting does as you’d expect, converting these deep
+objects into nicely formatted strings.
+
+When contributing, some principles:
+
+- Keep TypeDiffing and ErrorFormatting pure. They should only know about
+  JavaScript types, not React Native specific concepts
+- Add tests for every case you can think of. This codebase can be complex and
+  hard to reason about when making changes. The only way to stay sane is to be
+  able to rely on the tests to catch anything bad you’ve done. Do yourself and
+  future contributors a favor.

packages/react-native-compatibility-check/README.md

@@ -0,0 +1,245 @@
+# **React Native compatibility-check**
+
+Status: Experimental (stage 1)
+
+Work In Progress. Documentation is lacking, and intended to be used by power
+users at this point.
+
+This tool enables checking the boundary between JavaScript and Native for
+backwards incompatible changes to protect against crashes.
+
+This is useful for:
+
+- Local Development
+- Over the Air updates on platforms that support it
+- Theoretically: Server Components with React Native
+
+## **Motivating Problems**
+
+Let’s look at some motivating examples for this project.
+
+> [!NOTE] 
+> The examples below are written with Flow, but the compatibility-check
+> tool is agnostic to the types you write. The compatibility-check runs on JSON
+> schema files, most commonly generated by the
+> [@react-native/codegen](https://www.npmjs.com/package/@react-native/codegen)
+> tool which supports both TypeScript and Flow.
+
+### **Adding new methods**
+
+You might have an Analytics Native Module in your app, and you last built the
+native client a couple of days ago:
+
+```javascript
+export interface Spec extends TurboModule {
+  log: (eventName: string, content: string) => void;
+}
+```
+
+And you are working on a change to add a new method to this Native Module:
+
+```javascript
+export interface Spec extends TurboModule {
+  log: (eventName: string, content: string) => void;
+  logError: (message: string) => void;
+}
+```
+
+```
+NativeAnalytics.logError('Oh No! We hit a crash')
+```
+
+Since you are working on this, you’ve built a new native client and tested the
+change on your computer and everything works.
+
+However, when your colleague pulls your latest changes and tries to run it,
+they’ll get a crash `logError is not a function`. They need to rebuild their
+native client\!
+
+Using this tool, you can detect this incompatibility at build time, getting an
+error that looks like:
+
+```
+NativeAnalytics: Object added required properties, which native will not provide
+  -- logError
+```
+
+Errors like this can occur for much more nuanced reasons than adding a method.
+For example:
+
+### **Sending native new union values**
+
+```javascript
+export interface Spec extends TurboModule {
+  // You add 'system' to this union
+  +setColorScheme: (color: 'light' | 'dark') => void;
+}
+```
+
+If you add a new option of `system` and add native support for that option, when
+you call this method with `system` on your commit it would work but on an older
+build not expecting `system` it will crash. This tool will give you the error
+message:
+
+```
+ColorManager.setColorScheme parameter 0: Union added items, but native will not expect/support them
+  -- position 3 system
+```
+
+### **Changing an enum value sent from native**
+
+As another example, say you are getting the color scheme from the system as an
+integer value, used in JavaScript as an enum:
+
+```javascript
+enum TestEnum {
+  LIGHT = 1,
+  DARK = 2,
+  SYSTEM = 3,
+}
+
+export interface Spec extends TurboModule {
+  getColorScheme: () => TestEnum;
+}
+```
+
+And you realize you actually need native to send `-1` for System instead of 3\.
+
+```javascript
+enum TestEnum {
+  LIGHT = 1,
+  DARK = 2,
+  SYSTEM = -1,
+}
+```
+
+If you make this change and run the JavaScript on an old build, it might still
+send JavaScript the value 3, which your JavaScript isn’t handling anymore\!
+
+This tool gives an error:
+
+```javascript
+ColorManager: Object contained a property with a type mismatch
+   -- getColorScheme: has conflicting type changes
+       --new: ()=>Enum<number>
+       --old: ()=>Enum<number>
+       Function return types do not match
+           --new: ()=>Enum<number>
+           --old: ()=>Enum<number>
+           Enum types do not match
+               --new: Enum<number> {LIGHT = 1, DARK = 2, SYSTEM = -1}
+               --old: Enum<number> {LIGHT = 1, DARK = 2, SYSTEM = 3}
+               Enum contained a member with a type mismatch
+                   -- Member SYSTEM: has conflicting changes
+                       --new: -1
+                       --old: 3
+                       Numeric literals are not equal
+                           --new: -1
+                           --old: 3
+
+```
+
+## **Avoiding Breaking Changes**
+
+You can use this tool to either detect changes locally to warn that you need to
+install a new native build, or when doing OTA you might need to guarantee that
+the changes in your PR are compatible with the native client they’ll be running
+in.
+
+### **Example 1**
+
+In example 1, when adding logError, it needs to be optional to be safe:
+
+```javascript
+export interface Spec extends TurboModule {
+  log: (eventName: string, content: string) => void;
+  logError?: (message: string) => void;
+}
+```
+
+That will enforce if you are using TypeScript or Flow that you check if the
+native client supports logError before calling it:
+
+```javascript
+if (NativeAnalytics.logError) {
+  NativeAnalytics.logError('Oh No! We hit a crash');
+}
+```
+
+### **Example 2**
+
+When you want to add '`system'` as a value to the union, modifying the existing
+union is not safe. You would need to add a new optional method that has that
+change. You can clean up the old method when you know that all of the builds you
+ever want to run this JavaScript on have native support.
+
+```javascript
+export interface Spec extends TurboModule {
+  +setColorScheme: (color: 'light' | 'dark') => void
+  +setColorSchemeWithSystem?: (color: 'light' | 'dark' | 'system') => void
+}
+```
+
+### **Example 3**
+
+Changing a union case is similar to Example 2, you would either need a new
+method, or support the existing value and the new `-1`.
+
+```
+enum TestEnum {
+  LIGHT = 1,
+  DARK = 2,
+  SYSTEM = 3,
+  SYSTEM_ALSO = -1,
+}
+```
+
+## **Installation**
+
+```
+yarn add @react-native/compatibility-check
+```
+
+## **Usage**
+
+To use this package, you’ll need a script that works something like this:
+
+This script checks the compatibility of a React Native app's schema between two
+versions. It takes into account the changes made to the schema and determines
+whether they are compatible or not.
+
+```javascript
+import {compareSchemas} from '@react-native/compatibility-check';
+const util = require('util');
+
+async function run(argv: Argv, STDERR: string) {
+  const debug = (log: mixed) => {
+    argv.debug &&
+      console.info(util.inspect(log, {showHidden: false, depth: null}));
+  };
+
+  const currentSchema =
+    JSON.parse(/*you'll read the file generated by codegen wherever it is in your app*/);
+  const previousSchema =
+    JSON.parse(/*you'll read the schema file that you persisted from when your native app was built*/);
+
+  const safetyResult = compareSchemas(currentSchema, previousSchema);
+
+  const summary = safetyResult.getSummary();
+  switch (summary.status) {
+    case 'ok':
+      debug('No changes in boundary');
+      console.log(JSON.stringify(summary));
+      break;
+    case 'patchable':
+      debug('Changes in boundary, but are compatible');
+      debug(result.getDebugInfo());
+      console.log(JSON.stringify(summary));
+      break;
+    default:
+      debug(result.getDebugInfo());
+      console.error(JSON.stringify(result.getErrors()));
+      throw new Error(`Incompatible changes in boundary`);
+  }
+}
+```

packages/react-native-compatibility-check/index.js.flow

@@ -0,0 +1,12 @@
+/**
+ * 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
+ * @format
+ * @oncall react_native
+ */
+
+export * from './src';

packages/react-native-compatibility-check/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@react-native/compatibility-check",
+  "version": "0.0.1",
+  "description": "Check a React Native app's boundary between JS and Native for incompatibilities",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/facebook/react-native.git",
+    "directory": "packages/react-native-compatibility-check"
+  },
+  "homepage": "https://github.com/facebook/react-native/tree/HEAD/packages/react-native-compatibility-check#readme",
+  "keywords": [
+    "boundary",
+    "crashes",
+    "native",
+    "codegen",
+    "tools",
+    "react-native"
+  ],
+  "bugs": "https://github.com/facebook/react-native/issues",
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@react-native/codegen": "0.79.0-main"
+  },
+  "devDependencies": {
+    "flow-remove-types": "^2.237.2",
+    "rimraf": "^3.0.2"
+  }
+}