trickle-observe 0.2.61 → 0.2.62

package/dist/metro-transformer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * trickle/metro-transformer — Metro bundler transform for React Native observability.
+ *
+ * Drop-in Metro transformer that instruments React Native components with
+ * trickle's render tracking, useState change tracking, and hook observability —
+ * the same tracking trickle's Vite plugin provides for web React apps.
+ *
+ * Setup in metro.config.js:
+ *
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   // or: const { getDefaultConfig } = require('@react-native/metro-config');
+ *
+ *   const config = getDefaultConfig(__dirname);
+ *   config.transformer.babelTransformerPath = require.resolve('trickle-observe/metro-transformer');
+ *   module.exports = config;
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL   — URL of your trickle backend (default: http://localhost:4888)
+ *                           For real device: use your machine's LAN IP, e.g. http://192.168.1.5:4888
+ *   TRICKLE_DEBUG         — Set to "1" for debug logging
+ */
+interface MetroTransformArgs {
+    src: string;
+    filename: string;
+    options: Record<string, unknown>;
+}
+export declare function transform({ src, filename, options }: MetroTransformArgs): Promise<any>;
+export {};

package/dist/metro-transformer.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * trickle/metro-transformer — Metro bundler transform for React Native observability.
+ *
+ * Drop-in Metro transformer that instruments React Native components with
+ * trickle's render tracking, useState change tracking, and hook observability —
+ * the same tracking trickle's Vite plugin provides for web React apps.
+ *
+ * Setup in metro.config.js:
+ *
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   // or: const { getDefaultConfig } = require('@react-native/metro-config');
+ *
+ *   const config = getDefaultConfig(__dirname);
+ *   config.transformer.babelTransformerPath = require.resolve('trickle-observe/metro-transformer');
+ *   module.exports = config;
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL   — URL of your trickle backend (default: http://localhost:4888)
+ *                           For real device: use your machine's LAN IP, e.g. http://192.168.1.5:4888
+ *   TRICKLE_DEBUG         — Set to "1" for debug logging
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transform = transform;
+const path_1 = __importDefault(require("path"));
+const vite_plugin_1 = require("./vite-plugin");
+// The upstream Babel transformer — try Expo first, fall back to bare RN
+function getUpstreamTransformer() {
+    const candidates = [
+        '@expo/metro-config/babel-transformer',
+        'metro-react-native-babel-transformer',
+    ];
+    for (const candidate of candidates) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            return require(candidate);
+        }
+        catch {
+            // not installed, try next
+        }
+    }
+    throw new Error('[trickle/metro-transformer] Could not find a Metro Babel transformer. ' +
+        'Install either @expo/metro-config or metro-react-native-babel-transformer.');
+}
+const backendUrl = process.env.TRICKLE_BACKEND_URL ?? 'http://localhost:4888';
+const debug = process.env.TRICKLE_DEBUG === '1';
+async function transform({ src, filename, options }) {
+    const upstreamTransformer = getUpstreamTransformer();
+    // Only instrument React Native component files
+    const ext = path_1.default.extname(filename).toLowerCase();
+    const isReactFile = ext === '.tsx' || ext === '.jsx';
+    const isJsFile = ext === '.ts' || ext === '.js';
+    if ((isReactFile || isJsFile) && !filename.includes('node_modules') && !filename.includes('trickle-observe')) {
+        const moduleName = path_1.default.basename(filename).replace(/\.[jt]sx?$/, '');
+        const transformed = (0, vite_plugin_1.transformEsmSource)(src, filename, moduleName, backendUrl, debug, false);
+        if (transformed !== src) {
+            if (debug) {
+                console.log(`[trickle/metro] Instrumented ${filename}`);
+            }
+            return upstreamTransformer.transform({ src: transformed, filename, options });
+        }
+    }
+    return upstreamTransformer.transform({ src, filename, options });
+}

package/dist/vite-plugin.d.ts

@@ -37,4 +37,5 @@ export declare function tricklePlugin(options?: TricklePluginOptions): {
         map: null;
     } | null;
 };
+export declare function transformEsmSource(source: string, filename: string, moduleName: string, backendUrl: string, debug: boolean, traceVars: boolean, originalSource?: string | null): string;
 export default tricklePlugin;

package/dist/vite-plugin.js

@@ -23,6 +23,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.tricklePlugin = tricklePlugin;
+exports.transformEsmSource = transformEsmSource;
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 function tricklePlugin(options = {}) {
@@ -496,8 +497,8 @@ function escapeRegexStr(str) {
 function transformEsmSource(source, filename, moduleName, backendUrl, debug, traceVars, originalSource) {
     // Detect React files for component render tracking
     const isReactFile = /\.(tsx|jsx)$/.test(filename);
-    // Match top-level and nested function declarations (including async, export)
-    const funcRegex = /^[ \t]*(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
+    // Match top-level and nested function declarations (including async, export, export default)
+    const funcRegex = /^[ \t]*(?:export\s+(?:default\s+)?)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
     const funcInsertions = [];
     // Body insertions: insert at start of function body (for React render tracking)
     // propsExpr: JS expression to evaluate as the props object at render time

package/dist-esm/vite-plugin.js

@@ -487,11 +487,11 @@ function findOriginalLineDestructured(origLines, varNames, transformedLine) {
 function escapeRegexStr(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-function transformEsmSource(source, filename, moduleName, backendUrl, debug, traceVars, originalSource) {
+export function transformEsmSource(source, filename, moduleName, backendUrl, debug, traceVars, originalSource) {
     // Detect React files for component render tracking
     const isReactFile = /\.(tsx|jsx)$/.test(filename);
-    // Match top-level and nested function declarations (including async, export)
-    const funcRegex = /^[ \t]*(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
+    // Match top-level and nested function declarations (including async, export, export default)
+    const funcRegex = /^[ \t]*(?:export\s+(?:default\s+)?)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
     const funcInsertions = [];
     // Body insertions: insert at start of function body (for React render tracking)
     // propsExpr: JS expression to evaluate as the props object at render time

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trickle-observe",
-  "version": "0.2.61",
+  "version": "0.2.62",
   "description": "Runtime type observability for JavaScript applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,11 +17,12 @@
       "require": "./dist/vite-plugin.js"
     },
     "./trace-var": "./dist/trace-var.js",
-    "./lambda": "./dist/lambda.js"
+    "./lambda": "./dist/lambda.js",
+    "./metro-transformer": "./dist/metro-transformer.js"
   },
   "scripts": {
     "build": "tsc && tsc -p tsconfig.esm.json",
-    "test": "npm run build && node --experimental-strip-types --test src/vite-plugin.test.ts src/lambda.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test src/vite-plugin.test.ts src/lambda.test.ts src/metro-transformer.test.ts",
     "prepublishOnly": "npm run build"
   },
   "optionalDependencies": {

package/src/metro-transformer.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Unit tests for the Metro transformer (React Native observability).
+ *
+ * Tests the transformation logic independently — without needing a real Metro
+ * bundler or Babel pipeline. We test that transformEsmSource is applied correctly
+ * to React Native component source files.
+ *
+ * Run with: node --experimental-strip-types --test src/metro-transformer.test.ts
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { transformEsmSource } from '../dist/vite-plugin.js';
+
+const BACKEND_URL = 'http://localhost:4888';
+
+// Helper: transform as if coming from a .tsx React Native file
+function transformRNTsx(code: string, filename = '/app/components/MyComponent.tsx'): string {
+  return transformEsmSource(code, filename, 'MyComponent', BACKEND_URL, false, false);
+}
+
+// Helper: transform as if coming from a .ts utility file
+function transformRNTs(code: string, filename = '/app/utils/helper.ts'): string {
+  return transformEsmSource(code, filename, 'helper', BACKEND_URL, false, false);
+}
+
+// ── Metro transformer: React component detection ──────────────────────────────
+
+describe('Metro transformer: React component detection', () => {
+  it('instruments uppercase components in .tsx files', () => {
+    const code = `function OrderCard({ order }) { return null; }`;
+    const out = transformRNTsx(code);
+    assert.notEqual(out, code, 'should transform');
+    assert.ok(out.includes('__trickle_rc'), 'should inject render tracker');
+  });
+
+  it('does not inject render tracker for .ts utility files', () => {
+    const code = `function formatPrice(amount) { return '$' + amount; }`;
+    const out = transformRNTs(code);
+    assert.ok(!out.includes('__trickle_rc'), 'should not inject render tracker in .ts files');
+  });
+
+  it('instruments export default function components (common React Native screen pattern)', () => {
+    const code = `export default function HomeScreen() { return null; }`;
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_rc'), 'should inject render tracker for export default function');
+  });
+
+  it('does not instrument lowercase utility functions as components', () => {
+    const code = `function formatOrder(order) { return order.id; }`;
+    const out = transformRNTsx(code);
+    if (out !== code) {
+      assert.ok(!out.includes('__trickle_rc'), 'lowercase function should not be tracked as component');
+    }
+  });
+});
+
+// ── Metro transformer: useState tracking ─────────────────────────────────────
+
+describe('Metro transformer: useState tracking in React Native', () => {
+  it('tracks useState in a React Native functional component', () => {
+    const code = [
+      `import React, { useState } from 'react';`,
+      `function Counter() {`,
+      `  const [count, setCount] = useState(0);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_ss'), 'should inject state setter wrapper');
+    assert.ok(out.includes('__trickle_s_setCount'), 'should rename original setter');
+    assert.ok(out.includes('"count"'), 'should include state variable name');
+  });
+
+  it('tracks multiple useState calls in a React Native screen', () => {
+    const code = [
+      `function CheckoutScreen() {`,
+      `  const [items, setItems] = useState([]);`,
+      `  const [total, setTotal] = useState(0);`,
+      `  const [loading, setLoading] = useState(false);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    const count = (out.match(/const \w+=__trickle_ss/g) || []).length;
+    assert.equal(count, 3, 'should wrap all 3 useState setters');
+  });
+
+  it('handles TypeScript typed useState in React Native', () => {
+    const code = [
+      `function ProfileScreen() {`,
+      `  const [user, setUser] = useState<User | null>(null);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_ss'), 'should track typed useState');
+    assert.ok(out.includes('"user"'), 'should include state name');
+  });
+});
+
+// ── Metro transformer: hook observability ────────────────────────────────────
+
+describe('Metro transformer: hook observability in React Native', () => {
+  it('wraps useEffect in a React Native component', () => {
+    const code = [
+      `function DataScreen() {`,
+      `  useEffect(() => {`,
+      `    fetchData();`,
+      `  }, []);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_hw'), 'should inject hook wrapper for useEffect');
+    assert.ok(out.includes('"useEffect"'), 'should record hook name');
+  });
+
+  it('wraps useCallback in a React Native component', () => {
+    const code = [
+      `function ListScreen() {`,
+      `  const handlePress = useCallback(() => {`,
+      `    navigate('Detail');`,
+      `  }, []);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_hw'), 'should inject hook wrapper for useCallback');
+    assert.ok(out.includes('"useCallback"'), 'should record hook name');
+  });
+});
+
+// ── Metro transformer: source unchanged for non-RN files ─────────────────────
+
+describe('Metro transformer: passthrough for non-component files', () => {
+  it('does not modify a plain TypeScript utility file', () => {
+    const code = `export function add(a: number, b: number): number { return a + b; }`;
+    const out = transformRNTs(code);
+    // .ts files should not get __trickle_rc (no React components)
+    assert.ok(!out.includes('__trickle_rc'), 'should not inject React tracking in .ts files');
+  });
+
+  it('does not inject useState tracking in .ts files', () => {
+    const code = `function helper() {\n  const [x, setX] = useState(0);\n  return x;\n}`;
+    const out = transformRNTs(code);
+    assert.ok(!out.includes('__trickle_ss'), 'should not track useState in .ts files');
+  });
+});

package/src/metro-transformer.ts

@@ -0,0 +1,75 @@
+/**
+ * trickle/metro-transformer — Metro bundler transform for React Native observability.
+ *
+ * Drop-in Metro transformer that instruments React Native components with
+ * trickle's render tracking, useState change tracking, and hook observability —
+ * the same tracking trickle's Vite plugin provides for web React apps.
+ *
+ * Setup in metro.config.js:
+ *
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   // or: const { getDefaultConfig } = require('@react-native/metro-config');
+ *
+ *   const config = getDefaultConfig(__dirname);
+ *   config.transformer.babelTransformerPath = require.resolve('trickle-observe/metro-transformer');
+ *   module.exports = config;
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL   — URL of your trickle backend (default: http://localhost:4888)
+ *                           For real device: use your machine's LAN IP, e.g. http://192.168.1.5:4888
+ *   TRICKLE_DEBUG         — Set to "1" for debug logging
+ */
+
+import path from 'path';
+import { transformEsmSource } from './vite-plugin';
+
+// The upstream Babel transformer — try Expo first, fall back to bare RN
+function getUpstreamTransformer() {
+  const candidates = [
+    '@expo/metro-config/babel-transformer',
+    'metro-react-native-babel-transformer',
+  ];
+  for (const candidate of candidates) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      return require(candidate);
+    } catch {
+      // not installed, try next
+    }
+  }
+  throw new Error(
+    '[trickle/metro-transformer] Could not find a Metro Babel transformer. ' +
+    'Install either @expo/metro-config or metro-react-native-babel-transformer.',
+  );
+}
+
+interface MetroTransformArgs {
+  src: string;
+  filename: string;
+  options: Record<string, unknown>;
+}
+
+const backendUrl = process.env.TRICKLE_BACKEND_URL ?? 'http://localhost:4888';
+const debug = process.env.TRICKLE_DEBUG === '1';
+
+export async function transform({ src, filename, options }: MetroTransformArgs) {
+  const upstreamTransformer = getUpstreamTransformer();
+
+  // Only instrument React Native component files
+  const ext = path.extname(filename).toLowerCase();
+  const isReactFile = ext === '.tsx' || ext === '.jsx';
+  const isJsFile = ext === '.ts' || ext === '.js';
+
+  if ((isReactFile || isJsFile) && !filename.includes('node_modules') && !filename.includes('trickle-observe')) {
+    const moduleName = path.basename(filename).replace(/\.[jt]sx?$/, '');
+    const transformed = transformEsmSource(src, filename, moduleName, backendUrl, debug, false);
+    if (transformed !== src) {
+      if (debug) {
+        console.log(`[trickle/metro] Instrumented ${filename}`);
+      }
+      return upstreamTransformer.transform({ src: transformed, filename, options });
+    }
+  }
+
+  return upstreamTransformer.transform({ src, filename, options });
+}

package/src/vite-plugin.test.ts

@@ -40,6 +40,13 @@ describe('React file detection', () => {
     }
   });
 
+  it('tracks export default function components', () => {
+    const code = `export default function HomeScreen() { return null; }`;
+    const out = transformTsx(code);
+    assert.ok(out, 'should transform');
+    assert.ok(out!.includes('__trickle_rc'), 'export default function should be tracked as component');
+  });
+
   it('does not track lowercase functions as components', () => {
     const code = `function helper(x) { return x + 1; }`;
     const out = transformTsx(code);

package/src/vite-plugin.ts

@@ -481,7 +481,7 @@ function escapeRegexStr(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-function transformEsmSource(
+export function transformEsmSource(
   source: string,
   filename: string,
   moduleName: string,
@@ -493,8 +493,8 @@ function transformEsmSource(
   // Detect React files for component render tracking
   const isReactFile = /\.(tsx|jsx)$/.test(filename);
 
-  // Match top-level and nested function declarations (including async, export)
-  const funcRegex = /^[ \t]*(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
+  // Match top-level and nested function declarations (including async, export, export default)
+  const funcRegex = /^[ \t]*(?:export\s+(?:default\s+)?)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
   const funcInsertions: Array<{ position: number; name: string; paramNames: string[] }> = [];
   // Body insertions: insert at start of function body (for React render tracking)
   // propsExpr: JS expression to evaluate as the props object at render time