@react-native/compatibility-check 0.0.0 → 0.0.1

package/README.md

@@ -1 +1,245 @@
-Placeholder
+# **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`);
+  }
+}
+```

package/dist/ComparisonResult.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ *
+ *
+ * @format
+ */
+
+import type {
+  CompleteTypeAnnotation,
+  NamedShape,
+  NativeModuleEnumMember,
+} from "@react-native/codegen/src/CodegenSchema";
+type TypeAnnotationComparisonError = {
+  type: "TypeAnnotationComparisonError";
+  message: string;
+  newerAnnotation: CompleteTypeAnnotation;
+  olderAnnotation: CompleteTypeAnnotation;
+  previousError?: TypeComparisonError;
+};
+type TypeInformationComparisonError = {
+  type: "TypeInformationComparisonError";
+  message: string;
+  newerType: CompleteTypeAnnotation;
+  olderType: CompleteTypeAnnotation;
+  previousError?: TypeComparisonError;
+};
+type PropertyComparisonError = {
+  type: "PropertyComparisonError";
+  message: string;
+  mismatchedProperties: Array<{
+    property: string;
+    fault?: TypeComparisonError;
+  }>;
+  previousError?: TypeComparisonError;
+};
+type PositionalComparisonError = {
+  type: "PositionalComparisonError";
+  message: string;
+  erroneousItems: Array<[number, CompleteTypeAnnotation]>;
+  previousError?: TypeComparisonError;
+};
+type MemberComparisonError = {
+  type: "MemberComparisonError";
+  message: string;
+  mismatchedMembers: Array<{ member: string; fault?: TypeComparisonError }>;
+  previousError?: TypeComparisonError;
+};
+export type TypeComparisonError =
+  | TypeAnnotationComparisonError
+  | TypeInformationComparisonError
+  | PropertyComparisonError
+  | PositionalComparisonError
+  | MemberComparisonError;
+export type PositionalComparisonResult = {
+  typeKind: "stringUnion" | "union" | "intersection" | "parameter" | "tuple";
+  nestedChanges: Array<[number, number, ComparisonResult]>;
+  addedElements?: Array<[number, CompleteTypeAnnotation]>;
+  removedElements?: Array<[number, CompleteTypeAnnotation]>;
+};
+export type FunctionComparisonResult = {
+  returnType?: ComparisonResult;
+  parameterTypes?: PositionalComparisonResult;
+};
+export type PropertiesComparisonResult = {
+  addedProperties?: ReadonlyArray<NamedShape<CompleteTypeAnnotation>>;
+  missingProperties?: ReadonlyArray<NamedShape<CompleteTypeAnnotation>>;
+  errorProperties?: Array<{ property: string; fault?: TypeComparisonError }>;
+  madeStrict?: Array<{ property: string; furtherChanges?: ComparisonResult }>;
+  madeOptional?: Array<{ property: string; furtherChanges?: ComparisonResult }>;
+  nestedPropertyChanges?: Array<[string, ComparisonResult]>;
+};
+export type MembersComparisonResult = {
+  addedMembers?: Array<NativeModuleEnumMember>;
+  missingMembers?: Array<NativeModuleEnumMember>;
+  errorMembers?: Array<{ member: string; fault?: TypeComparisonError }>;
+};
+export type NullableComparisonResult = {
+  typeRefined: boolean;
+  optionsReduced: boolean;
+  interiorLog: null | undefined | ComparisonResult;
+  newType: null | undefined | CompleteTypeAnnotation;
+  oldType: null | undefined | CompleteTypeAnnotation;
+};
+export type ComparisonResult =
+  | { status: "matching" }
+  | { status: "skipped" }
+  | { status: "nullableChange"; nullableLog: NullableComparisonResult }
+  | { status: "properties"; propertyLog: PropertiesComparisonResult }
+  | { status: "members"; memberLog: MembersComparisonResult }
+  | { status: "functionChange"; functionChangeLog: FunctionComparisonResult }
+  | { status: "positionalTypeChange"; changeLog: PositionalComparisonResult }
+  | { status: "error"; errorLog: TypeComparisonError };
+export declare function isPropertyLogEmpty(
+  result: PropertiesComparisonResult
+): boolean;
+export declare function isMemberLogEmpty(
+  result: MembersComparisonResult
+): boolean;
+export declare function isFunctionLogEmpty(
+  result: FunctionComparisonResult
+): boolean;
+export declare function makeError(error: TypeComparisonError): ComparisonResult;
+export declare function typeInformationComparisonError(
+  message: string,
+  newerType: CompleteTypeAnnotation,
+  olderType: CompleteTypeAnnotation,
+  previousError?: TypeComparisonError
+): TypeComparisonError;
+export declare function typeAnnotationComparisonError(
+  message: string,
+  newerAnnotation: CompleteTypeAnnotation,
+  olderAnnotation: CompleteTypeAnnotation,
+  previousError?: TypeComparisonError
+): TypeComparisonError;
+export declare function propertyComparisonError(
+  message: string,
+  mismatchedProperties: Array<{
+    property: string;
+    fault?: TypeComparisonError;
+  }>,
+  previousError?: TypeComparisonError
+): TypeComparisonError;
+export declare function memberComparisonError(
+  message: string,
+  mismatchedMembers: Array<{ member: string; fault?: TypeComparisonError }>,
+  previousError?: TypeComparisonError
+): TypeComparisonError;
+export declare function positionalComparisonError(
+  message: string,
+  erroneousItems: Array<[number, CompleteTypeAnnotation]>,
+  previousError?: TypeComparisonError
+): TypeComparisonError;

package/dist/ComparisonResult.js

@@ -0,0 +1,88 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true,
+});
+exports.isFunctionLogEmpty = isFunctionLogEmpty;
+exports.isMemberLogEmpty = isMemberLogEmpty;
+exports.isPropertyLogEmpty = isPropertyLogEmpty;
+exports.makeError = makeError;
+exports.memberComparisonError = memberComparisonError;
+exports.positionalComparisonError = positionalComparisonError;
+exports.propertyComparisonError = propertyComparisonError;
+exports.typeAnnotationComparisonError = typeAnnotationComparisonError;
+exports.typeInformationComparisonError = typeInformationComparisonError;
+function isPropertyLogEmpty(result) {
+  return !(
+    result.addedProperties ||
+    result.missingProperties ||
+    result.nestedPropertyChanges ||
+    result.madeStrict ||
+    result.madeOptional ||
+    result.errorProperties
+  );
+}
+function isMemberLogEmpty(result) {
+  return !(result.addedMembers || result.missingMembers || result.errorMembers);
+}
+function isFunctionLogEmpty(result) {
+  return !(result.returnType || result.parameterTypes);
+}
+function makeError(error) {
+  return {
+    status: "error",
+    errorLog: error,
+  };
+}
+function typeInformationComparisonError(
+  message,
+  newerType,
+  olderType,
+  previousError
+) {
+  return {
+    type: "TypeInformationComparisonError",
+    message,
+    newerType,
+    olderType,
+    previousError,
+  };
+}
+function typeAnnotationComparisonError(
+  message,
+  newerAnnotation,
+  olderAnnotation,
+  previousError
+) {
+  return {
+    type: "TypeAnnotationComparisonError",
+    message,
+    newerAnnotation,
+    olderAnnotation,
+    previousError,
+  };
+}
+function propertyComparisonError(message, mismatchedProperties, previousError) {
+  return {
+    type: "PropertyComparisonError",
+    message,
+    mismatchedProperties,
+    previousError,
+  };
+}
+function memberComparisonError(message, mismatchedMembers, previousError) {
+  return {
+    type: "MemberComparisonError",
+    message,
+    mismatchedMembers,
+    previousError,
+  };
+}
+function positionalComparisonError(message, erroneousItems, previousError) {
+  return {
+    type: "PositionalComparisonError",
+    message,
+    erroneousItems,
+    previousError,
+  };
+}

package/dist/ComparisonResult.js.flow

@@ -0,0 +1,188 @@
+/**
+ * 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
+ * @format
+ */
+
+import type {
+  CompleteTypeAnnotation,
+  NamedShape,
+  NativeModuleEnumMember,
+} from "@react-native/codegen/src/CodegenSchema";
+
+type TypeAnnotationComparisonError = {
+  type: "TypeAnnotationComparisonError",
+  message: string,
+  newerAnnotation: CompleteTypeAnnotation,
+  olderAnnotation: CompleteTypeAnnotation,
+  previousError?: TypeComparisonError,
+};
+type TypeInformationComparisonError = {
+  type: "TypeInformationComparisonError",
+  message: string,
+  newerType: CompleteTypeAnnotation,
+  olderType: CompleteTypeAnnotation,
+  previousError?: TypeComparisonError,
+};
+type PropertyComparisonError = {
+  type: "PropertyComparisonError",
+  message: string,
+  mismatchedProperties: Array<{
+    property: string,
+    fault?: TypeComparisonError,
+    ...
+  }>,
+  previousError?: TypeComparisonError,
+};
+type PositionalComparisonError = {
+  type: "PositionalComparisonError",
+  message: string,
+  erroneousItems: Array<[number, CompleteTypeAnnotation]>,
+  previousError?: TypeComparisonError,
+};
+type MemberComparisonError = {
+  type: "MemberComparisonError",
+  message: string,
+  mismatchedMembers: Array<{
+    member: string,
+    fault?: TypeComparisonError,
+  }>,
+  previousError?: TypeComparisonError,
+};
+export type TypeComparisonError =
+  | TypeAnnotationComparisonError
+  | TypeInformationComparisonError
+  | PropertyComparisonError
+  | PositionalComparisonError
+  | MemberComparisonError;
+
+// Collects changes that may be type safe within parameters, unions, intersections, and tuples
+export type PositionalComparisonResult = {
+  typeKind: "stringUnion" | "union" | "intersection" | "parameter" | "tuple",
+  // Nested changes stores the position of the old type followed by new
+  // Except for union and intersection, new position === old position
+  nestedChanges: Array<[number, number, ComparisonResult]>,
+  // These properties should never occur for a tuple
+  addedElements?: Array<[number, CompleteTypeAnnotation]>,
+  removedElements?: Array<[number, CompleteTypeAnnotation]>,
+  ...
+};
+export type FunctionComparisonResult = {
+  returnType?: ComparisonResult,
+  // The following should always have typeKind 'parameter'
+  parameterTypes?: PositionalComparisonResult,
+  ...
+};
+
+// Array<NamedShape<Nullable<NativeModuleBaseTypeAnnotation>>>
+
+export type PropertiesComparisonResult = {
+  addedProperties?: $ReadOnlyArray<NamedShape<CompleteTypeAnnotation>>,
+  missingProperties?: $ReadOnlyArray<NamedShape<CompleteTypeAnnotation>>,
+  errorProperties?: Array<{
+    property: string,
+    fault?: TypeComparisonError,
+    ...
+  }>,
+  madeStrict?: Array<{
+    property: string,
+    furtherChanges?: ComparisonResult,
+    ...
+  }>,
+  madeOptional?: Array<{
+    property: string,
+    furtherChanges?: ComparisonResult,
+    ...
+  }>,
+  nestedPropertyChanges?: Array<[string, ComparisonResult]>,
+  ...
+};
+export type MembersComparisonResult = {
+  addedMembers?: Array<NativeModuleEnumMember>,
+  missingMembers?: Array<NativeModuleEnumMember>,
+  errorMembers?: Array<{
+    member: string,
+    fault?: TypeComparisonError,
+  }>,
+};
+export type NullableComparisonResult = {
+  /* Four possible cases of change:
+     void goes to T?   :: typeRefined !optionsReduced
+     T?   goes to void :: typeRefined optionsReduced
+     T    goes to T?   :: !typeRefined !optionsReduced
+     T?   goes to T    :: !typeRefined optionsReduced
+  */
+  typeRefined: boolean,
+  optionsReduced: boolean,
+  // interiorLog not available if either type is void
+  interiorLog: ?ComparisonResult,
+  newType: ?CompleteTypeAnnotation,
+  oldType: ?CompleteTypeAnnotation,
+  ...
+};
+export type ComparisonResult =
+  | { status: "matching" }
+  | { status: "skipped" }
+  | { status: "nullableChange", nullableLog: NullableComparisonResult }
+  | { status: "properties", propertyLog: PropertiesComparisonResult }
+  | { status: "members", memberLog: MembersComparisonResult }
+  | { status: "functionChange", functionChangeLog: FunctionComparisonResult }
+  | { status: "positionalTypeChange", changeLog: PositionalComparisonResult }
+  | { status: "error", errorLog: TypeComparisonError };
+
+declare export function isPropertyLogEmpty(
+  result: PropertiesComparisonResult
+): boolean;
+
+declare export function isMemberLogEmpty(
+  result: MembersComparisonResult
+): boolean;
+
+declare export function isFunctionLogEmpty(
+  result: FunctionComparisonResult
+): boolean;
+
+declare export function makeError(error: TypeComparisonError): ComparisonResult;
+
+declare export function typeInformationComparisonError(
+  message: string,
+  newerType: CompleteTypeAnnotation,
+  olderType: CompleteTypeAnnotation,
+  previousError?: TypeComparisonError
+): TypeComparisonError;
+
+declare export function typeAnnotationComparisonError(
+  message: string,
+  newerAnnotation: CompleteTypeAnnotation,
+  olderAnnotation: CompleteTypeAnnotation,
+  previousError?: TypeComparisonError
+): TypeComparisonError;
+
+declare export function propertyComparisonError(
+  message: string,
+  mismatchedProperties: Array<{
+    property: string,
+    fault?: TypeComparisonError,
+    ...
+  }>,
+  previousError?: TypeComparisonError
+): TypeComparisonError;
+
+declare export function memberComparisonError(
+  message: string,
+  mismatchedMembers: Array<{
+    member: string,
+    fault?: TypeComparisonError,
+  }>,
+  previousError?: TypeComparisonError
+): TypeComparisonError;
+
+declare export function positionalComparisonError(
+  message: string,
+  erroneousItems: Array<[number, CompleteTypeAnnotation]>,
+  previousError?: TypeComparisonError
+): TypeComparisonError;