react-native-boost 0.7.0 → 1.1.0

package/README.md

@@ -4,9 +4,6 @@
 
 A powerful Babel plugin that automatically optimizes React Native apps through static source code analysis. It replaces standard React Native components with their native counterparts where possible, leading to significant performance improvements.
 
-> [!WARNING]
-> The library and its Babel plugin are still experimental. You should expect things to break. Please report any issues you encounter in the issues tab with reproducible examples, and use the library's ignore mechanisms to disable optimizations for problematic files or lines of code.
-
 - ⚡ Automatic performance optimization through source code analysis
 - 🔒 Safe optimizations that don't break your app
 - 🎯 Virtually zero runtime overhead
@@ -23,10 +20,19 @@ The documentation is available at [react-native-boost.oss.kuatsu.de](https://rea
 The app in the `apps/example` directory serves as a benchmark for the performance of the plugin.
 
 <div align="center">
-  <img src="./apps/docs/docs/introduction/img/benchmark-ios.png" width="500" />
+  <img src="./apps/docs/content/docs/information/img/benchmark-ios.png" width="500" />
 </div>
 
-More benchmarks are available in the [docs](https://react-native-boost.oss.kuatsu.de/docs/introduction/benchmarks).
+More benchmarks are available in the [docs](https://react-native-boost.oss.kuatsu.de/docs/information/benchmarks).
+
+## Compatibility
+
+| `react-native-boost` | React Native     |
+| -------------------- | ---------------- |
+| `0.x`                | All versions[^1] |
+| `1.x`                | `>=0.83`         |
+
+[^1]: Starting from React Native `0.80`, `react-native-boost@0` prints import deprecation warnings.
 
 ## Installation
 
@@ -62,11 +68,11 @@ yarn start --clear
 
 That's it! No imports in your code, rebuilding, or anything else is required.
 
-Optionally, you can configure the Babel plugin with a few options described in the [documentation](https://react-native-boost.oss.kuatsu.de/docs/babel-plugin/configure).
+Optionally, you can configure the Babel plugin with a few options described in the [documentation](https://react-native-boost.oss.kuatsu.de/docs/configuration/configure).
 
 ## How it works
 
-A technical rundown of how the plugin works can be found in the [docs](https://react-native-boost.oss.kuatsu.de/docs/introduction/how-it-works).
+A technical rundown of how the plugin works can be found in the [docs](https://react-native-boost.oss.kuatsu.de/docs/information/how-it-works).
 
 ## Contributing
 

package/dist/plugin/esm/index.mjs

@@ -15,6 +15,14 @@ const ensureArray = (value) => {
   if (Array.isArray(value)) return value;
   return [value];
 };
+const getFirstBailoutReason = (checks) => {
+  for (const check of checks) {
+    if (check.shouldBail()) {
+      return check.reason;
+    }
+  }
+  return null;
+};
 
 const isIgnoredFile = (path, ignores) => {
   const hub = path.hub;
@@ -32,17 +40,23 @@ const isIgnoredFile = (path, ignores) => {
   }
   return false;
 };
+const isForcedLine = (path) => {
+  return hasDecoratorComment(path, "@boost-force");
+};
 const isIgnoredLine = (path) => {
+  return hasDecoratorComment(path, "@boost-ignore");
+};
+function hasDecoratorComment(path, decorator) {
   var _a, _b, _c;
-  if ((_a = path.node.leadingComments) == null ? void 0 : _a.some((comment) => comment.value.includes("@boost-ignore"))) {
+  if ((_a = path.node.leadingComments) == null ? void 0 : _a.some((comment) => comment.value.includes(decorator))) {
     return true;
   }
   const jsxElementPath = path.parentPath;
-  if ((_b = jsxElementPath.node.leadingComments) == null ? void 0 : _b.some((comment) => comment.value.includes("@boost-ignore"))) {
+  if ((_b = jsxElementPath.node.leadingComments) == null ? void 0 : _b.some((comment) => comment.value.includes(decorator))) {
     return true;
   }
   const propertyPath = jsxElementPath.parentPath;
-  if (propertyPath && propertyPath.isObjectProperty() && ((_c = propertyPath.node.leadingComments) == null ? void 0 : _c.some((comment) => comment.value.includes("@boost-ignore")))) {
+  if (propertyPath && propertyPath.isObjectProperty() && ((_c = propertyPath.node.leadingComments) == null ? void 0 : _c.some((comment) => comment.value.includes(decorator)))) {
     return true;
   }
   if (!jsxElementPath.parentPath) return false;
@@ -63,18 +77,18 @@ const isIgnoredLine = (path) => {
           ...expression.node.trailingComments || [],
           ...expression.node.innerComments || []
         ].map((comment) => comment.value.trim());
-        if (comments.some((comment) => comment.includes("@boost-ignore"))) {
+        if (comments.some((comment) => comment.includes(decorator))) {
           return true;
         }
       }
     }
-    if (sibling.node.leadingComments && sibling.node.leadingComments.some((comment) => comment.value.includes("@boost-ignore"))) {
+    if (sibling.node.leadingComments && sibling.node.leadingComments.some((comment) => comment.value.includes(decorator))) {
       return true;
     }
     break;
   }
   return false;
-};
+}
 const isValidJSXComponent = (path, componentName) => {
   if (!types.isJSXIdentifier(path.node.name)) return false;
   const parent = path.parent;
@@ -111,11 +125,8 @@ const isReactNativeImport = (path, expectedImportedName) => {
   }
   return false;
 };
-const hasUnsafeViewAncestor = (path, allowUnknownAncestors = false) => {
-  const classification = classifyViewAncestors(path);
-  if (classification === "text") return true;
-  if (classification === "unknown" && !allowUnknownAncestors) return true;
-  return false;
+const getViewAncestorClassification = (path) => {
+  return classifyViewAncestors(path);
 };
 function classifyViewAncestors(path) {
   const context = {
@@ -729,25 +740,53 @@ const textBlacklistedProperties = /* @__PURE__ */ new Set([
   "selectionColor"
   // TODO: we can use react-native's internal `processColor` to process this at runtime
 ]);
-const textOptimizer = (path, log = () => {
-}) => {
-  var _a, _b, _c;
-  if (isIgnoredLine(path)) return;
+const textOptimizer = (path, logger) => {
   if (!isValidJSXComponent(path, "Text")) return;
   if (!isReactNativeImport(path, "Text")) return;
-  if (hasBlacklistedProperty(path, textBlacklistedProperties)) return;
-  if (hasExpoRouterLinkParentWithAsChild(path)) return;
   const parent = path.parent;
-  if (hasInvalidChildren(path, parent)) return;
+  const forced = isForcedLine(path);
+  const overridableChecks = [
+    {
+      reason: "contains blacklisted props",
+      shouldBail: () => hasBlacklistedProperty(path, textBlacklistedProperties)
+    },
+    {
+      reason: "is a direct child of expo-router Link with asChild",
+      shouldBail: () => hasExpoRouterLinkParentWithAsChild(path)
+    },
+    {
+      reason: "contains non-string children",
+      shouldBail: () => hasInvalidChildren(path, parent)
+    }
+  ];
+  if (forced) {
+    const overriddenReason = getFirstBailoutReason(overridableChecks);
+    if (overriddenReason) {
+      logger.forced({ component: "Text", path, reason: overriddenReason });
+    }
+  } else {
+    const skipReason = getFirstBailoutReason([
+      {
+        reason: "line is marked with @boost-ignore",
+        shouldBail: () => isIgnoredLine(path)
+      },
+      ...overridableChecks
+    ]);
+    if (skipReason) {
+      logger.skipped({ component: "Text", path, reason: skipReason });
+      return;
+    }
+  }
   const hub = path.hub;
   const file = typeof hub === "object" && hub !== null && "file" in hub ? hub.file : void 0;
   if (!file) {
     throw new PluginError("No file found in Babel hub");
   }
-  const filename = ((_a = file.opts) == null ? void 0 : _a.filename) || "unknown file";
-  const lineNumber = (_c = (_b = path.node.loc) == null ? void 0 : _b.start.line) != null ? _c : "unknown line";
-  log(`Optimizing Text component in ${filename}:${lineNumber}`);
-  fixNegativeNumberOfLines({ path, log });
+  logger.optimized({
+    component: "Text",
+    path
+  });
+  fixNegativeNumberOfLines({ path, logger });
   addDefaultProperty(path, "allowFontScaling", types.booleanLiteral(true));
   addDefaultProperty(path, "ellipsizeMode", types.stringLiteral("tail"));
   processProps(path, file);
@@ -763,10 +802,7 @@ function hasInvalidChildren(path, parent) {
   }
   return !parent.children.every((child) => isStringNode(path, child));
 }
-function fixNegativeNumberOfLines({
-  path,
-  log
-}) {
+function fixNegativeNumberOfLines({ path, logger }) {
   for (const attribute of path.node.attributes) {
     if (types.isJSXAttribute(attribute) && types.isJSXIdentifier(attribute.name, { name: "numberOfLines" }) && attribute.value && types.isJSXExpressionContainer(attribute.value)) {
       let originalValue;
@@ -776,9 +812,11 @@ function fixNegativeNumberOfLines({
         originalValue = -attribute.value.expression.argument.value;
       }
       if (originalValue !== void 0 && originalValue < 0) {
-        log(
-          `Warning: 'numberOfLines' in <Text> must be a non-negative number, received: ${originalValue}. The value will be set to 0.`
-        );
+        logger.warning({
+          component: "Text",
+          path,
+          message: `'numberOfLines' must be a non-negative number, received: ${originalValue}. The value will be set to 0.`
+        });
         attribute.value.expression = types.numericLiteral(0);
       }
     }
@@ -837,9 +875,101 @@ function processProps(path, file) {
   );
 }
 
-const log = (message) => {
-  console.log(`[react-native-boost] ${message}`);
+const LOG_PREFIX = "[react-native-boost]";
+const ANSI_RESET = "\x1B[0m";
+const ANSI_GREEN = "\x1B[32m";
+const ANSI_YELLOW = "\x1B[33m";
+const ANSI_MAGENTA = "\x1B[35m";
+const ANSI_RED = "\x1B[31m";
+const noopLogger = {
+  optimized() {
+  },
+  skipped() {
+  },
+  forced() {
+  },
+  warning() {
+  }
 };
+const createLogger = ({ verbose, silent }) => {
+  if (silent) return noopLogger;
+  return {
+    optimized(payload) {
+      writeLog("optimized", `Optimized ${payload.component} in ${formatPathLocation(payload.path)}`);
+    },
+    skipped(payload) {
+      if (!verbose) return;
+      writeLog("skipped", `Skipped ${payload.component} in ${formatPathLocation(payload.path)} (${payload.reason})`);
+    },
+    forced(payload) {
+      writeLog(
+        "forced",
+        `Force-optimized ${payload.component} in ${formatPathLocation(payload.path)} (skipped bailout: ${payload.reason})`
+      );
+    },
+    warning(payload) {
+      const context = formatWarningContext(payload);
+      const message = context.length > 0 ? `${context}: ${payload.message}` : payload.message;
+      writeLog("warning", message);
+    }
+  };
+};
+function formatWarningContext(payload) {
+  const location = formatPathLocation(payload.path);
+  if (payload.component && location.length > 0) {
+    return `${payload.component} in ${location}`;
+  }
+  if (payload.component) {
+    return payload.component;
+  }
+  return location;
+}
+function writeLog(level, message) {
+  const levelTag = formatLevel(level);
+  console.log(`${LOG_PREFIX} ${levelTag} ${message}`);
+}
+function formatLevel(level) {
+  if (level === "optimized") {
+    return colorize("[optimized]", ANSI_GREEN);
+  }
+  if (level === "skipped") {
+    return colorize("[skipped]", ANSI_YELLOW);
+  }
+  if (level === "forced") {
+    return colorize("[forced]", ANSI_RED);
+  }
+  return colorize("[warning]", ANSI_MAGENTA);
+}
+function colorize(value, colorCode) {
+  if (!shouldUseColor()) return value;
+  return `${colorCode}${value}${ANSI_RESET}`;
+}
+function shouldUseColor() {
+  var _a, _b;
+  if (process.env.NO_COLOR != null) return false;
+  if (process.env.FORCE_COLOR === "0") return false;
+  if (process.env.FORCE_COLOR != null) return true;
+  if (process.env.CLICOLOR === "0") return false;
+  if (process.env.CLICOLOR_FORCE != null && process.env.CLICOLOR_FORCE !== "0") return true;
+  if (((_a = process.stdout) == null ? void 0 : _a.isTTY) === true || ((_b = process.stderr) == null ? void 0 : _b.isTTY) === true) {
+    return true;
+  }
+  const colorTerm = process.env.COLORTERM;
+  if (colorTerm != null && colorTerm !== "") {
+    return true;
+  }
+  const term = process.env.TERM;
+  return term != null && term !== "" && term.toLowerCase() !== "dumb";
+}
+function formatPathLocation(payloadPath) {
+  var _a, _b, _c, _d;
+  if (!payloadPath) return "unknown file:unknown line";
+  const hub = payloadPath.hub;
+  const file = typeof hub === "object" && hub !== null && "file" in hub ? hub.file : void 0;
+  const filename = (_b = (_a = file == null ? void 0 : file.opts) == null ? void 0 : _a.filename) != null ? _b : "unknown file";
+  const lineNumber = (_d = (_c = payloadPath.node.loc) == null ? void 0 : _c.start.line) != null ? _d : "unknown line";
+  return `${filename}:${lineNumber}`;
+}
 
 const viewBlacklistedProperties = /* @__PURE__ */ new Set([
   // TODO: process a11y props at runtime
@@ -857,22 +987,58 @@ const viewBlacklistedProperties = /* @__PURE__ */ new Set([
   "style"
   // TODO: process style at runtime
 ]);
-const viewOptimizer = (path, log = () => {
-}, options) => {
-  var _a, _b, _c;
-  if (isIgnoredLine(path)) return;
+const viewOptimizer = (path, logger, options) => {
   if (!isValidJSXComponent(path, "View")) return;
   if (!isReactNativeImport(path, "View")) return;
-  if (hasBlacklistedProperty(path, viewBlacklistedProperties)) return;
-  if (hasUnsafeViewAncestor(path, (options == null ? void 0 : options.dangerouslyOptimizeViewWithUnknownAncestors) === true)) return;
+  let ancestorClassification;
+  const getAncestorClassification = () => {
+    if (!ancestorClassification) {
+      ancestorClassification = getViewAncestorClassification(path);
+    }
+    return ancestorClassification;
+  };
+  const forced = isForcedLine(path);
+  const overridableChecks = [
+    {
+      reason: "contains blacklisted props",
+      shouldBail: () => hasBlacklistedProperty(path, viewBlacklistedProperties)
+    },
+    {
+      reason: "has Text ancestor",
+      shouldBail: () => getAncestorClassification() === "text"
+    },
+    {
+      reason: "has unresolved ancestor and dangerous optimization is disabled",
+      shouldBail: () => getAncestorClassification() === "unknown" && (options == null ? void 0 : options.dangerouslyOptimizeViewWithUnknownAncestors) !== true
+    }
+  ];
+  if (forced) {
+    const overriddenReason = getFirstBailoutReason(overridableChecks);
+    if (overriddenReason) {
+      logger.forced({ component: "View", path, reason: overriddenReason });
+    }
+  } else {
+    const skipReason = getFirstBailoutReason([
+      {
+        reason: "line is marked with @boost-ignore",
+        shouldBail: () => isIgnoredLine(path)
+      },
+      ...overridableChecks
+    ]);
+    if (skipReason) {
+      logger.skipped({ component: "View", path, reason: skipReason });
+      return;
+    }
+  }
   const hub = path.hub;
   const file = typeof hub === "object" && hub !== null && "file" in hub ? hub.file : void 0;
   if (!file) {
     throw new PluginError("No file found in Babel hub");
   }
-  const filename = ((_a = file.opts) == null ? void 0 : _a.filename) || "unknown file";
-  const lineNumber = (_c = (_b = path.node.loc) == null ? void 0 : _b.start.line) != null ? _c : "unknown line";
-  log(`Optimizing View component in ${filename}:${lineNumber}`);
+  logger.optimized({
+    component: "View",
+    path
+  });
   const parent = path.parent;
   replaceWithNativeComponent(path, parent, file, "NativeView");
 };
@@ -884,9 +1050,9 @@ var index = declare((api) => {
     visitor: {
       JSXOpeningElement(path, state) {
         var _a, _b, _c, _d;
-        const options = (_a = state.opts) != null ? _a : {};
-        const logger = options.verbose ? log : () => {
-        };
+        const pluginState = state;
+        const options = (_a = pluginState.opts) != null ? _a : {};
+        const logger = getOrCreateLogger(pluginState, options);
         if (isIgnoredFile(path, (_b = options.ignores) != null ? _b : [])) return;
         if (((_c = options.optimizations) == null ? void 0 : _c.text) !== false) textOptimizer(path, logger);
         if (((_d = options.optimizations) == null ? void 0 : _d.view) !== false) viewOptimizer(path, logger, options);
@@ -894,6 +1060,16 @@ var index = declare((api) => {
     }
   };
 });
+function getOrCreateLogger(state, options) {
+  if (state.__reactNativeBoostLogger) {
+    return state.__reactNativeBoostLogger;
+  }
+  state.__reactNativeBoostLogger = createLogger({
+    verbose: options.verbose === true,
+    silent: options.silent === true
+  });
+  return state.__reactNativeBoostLogger;
+}
 
 export { index as default };
 //# sourceMappingURL=index.mjs.map