@keepsnappy/react-native 0.1.0-alpha.15 → 0.1.0-alpha.17

package/README.md

@@ -19,6 +19,18 @@ const { withKeepSnappy } = require('@keepsnappy/react-native/metro');
 module.exports = withKeepSnappy(config);
 ```
 
+Shared client packages can opt into component keys:
+
+```js
+module.exports = withKeepSnappy(config, { clientPackages: ['@my-app/ui'] });
+```
+
+With the flag on, `.js/.jsx/.ts/.tsx` files inside the real project root, outside `node_modules`, and owned by the root package count as client code. Another package (including a workspace sibling or linked SDK) counts only when its name is in `clientPackages` (default `[]`). Package keys use `<package>/<path inside it>`, never a parent-relative path.
+
+A plugin in the client's own Babel pipeline stamps only module-scope named functions, React component classes, function-valued constants and outer `memo`/`forwardRef` bindings. Nested declarations and anonymous default exports remain unstamped. An unsupported instrumentation path falls back to the client's transform. The key is `Name@file`; the file part uses `encodeURIComponent`, keeps `/` and `@` readable, and additionally encodes `~`. Names support uppercase/titlecase Unicode identifiers. Parsing accepts only the exact canonical encoding. `@keepsnappy/facts` owns the grammar and fragment schema. The SDK's small build-time encoder is pinned by a round-trip test through facts, without adding a private workspace dependency to the shipped SDK.
+
+Workers write atomic, content-addressed fragments under `.keepsnappy/components/`, with source paths relative to the project root. Metro excludes that directory from its resolver. `keepsnappy sourcemaps upload` sends source maps first, then prepares sorted `.keepsnappy/components.json`; component-map errors only print a warning. Use `--project-root PATH` for a moved checkout. Each configuration has its own `.config.json`; when several exist, select its directory name with `--components-config ID`. Keep this build-output directory out of version control. The map's upload awaits API support.
+
 `app.config.js` / `app.json`:
 
 ```js

package/js/babel-transformer.js

@@ -1,5 +1,5 @@
-// Wraps the app's Babel transformer (set by withKeepSnappy) and adds one import to
-// the entry module: the keepsnappy boot module. That import is what puts the SDK
+// Wraps the app's Babel transformer (set by withKeepSnappy), stamps client
+// declarations and imports the keepsnappy boot module in the entry. That import puts the SDK
 // in the graph; getModulesRunBeforeMainModule then runs it before the entry.
 //
 // babel-preset-expo inlines EXPO_PUBLIC_* only outside node_modules, and the
@@ -12,6 +12,9 @@ const upstreamPath = (process.env.KEEPSNAPPY_UPSTREAM_BABEL_TRANSFORMER);
 const entryFile = (process.env.KEEPSNAPPY_ENTRY_FILE);
 const bootFile = (process.env.KEEPSNAPPY_BOOT_FILE);
 const sdkVersion = process.env.KEEPSNAPPY_SDK_VERSION;
+const clientPackages = JSON.parse(process.env.KEEPSNAPPY_CLIENT_PACKAGES ?? '[]');
+const projectRoot = process.env.KEEPSNAPPY_PROJECT_ROOT;
+const componentCacheKey = process.env.KEEPSNAPPY_COMPONENT_CACHE_KEY ?? '';
 
 if (!upstreamPath || !entryFile || !bootFile || !sdkVersion) {
   throw new Error(
@@ -53,23 +56,45 @@ const absolute = (filename, options) =>
 module.exports = {
   ...upstream,
   transform(args) {
+    if (process.env.EXPO_PUBLIC_KEEPSNAPPY !== '1') return upstream.transform(args);
     const file = absolute(args.filename, args.options);
+    const original = args;
     if (file === entryFile) {
-      return upstream.transform({ ...args, src: bootImport() + args.src });
+      args = { ...args, src: bootImport() + args.src };
     }
     if (file.startsWith(packageRoot)) {
       const src = file === path.join(packageRoot, 'js', 'sdk', 'push-install.ts')
         ? args.src.replace("require('../../package.json')", JSON.stringify({ version: sdkVersion }))
         : args.src;
-      return upstream.transform({ ...args, src: inlineEnv(src) });
+      args = { ...args, src: inlineEnv(src) };
     }
-    return upstream.transform(args);
+    const root = args.options?.projectRoot ?? projectRoot ?? process.cwd();
+    // A client file built without its stamps keys its components to an ancestor's: never silently.
+    const skipped = error => console.warn(`KeepSnappy: component stamps skipped for ${path.relative(root, file)}: ${String(error)}`);
+    let stamps;
+    try {
+      stamps = require('./component-stamps.js').instrumentation(
+        original.src, file, root, clientPackages, file === entryFile ? 1 : 0,
+      );
+    } catch (error) { skipped(error); return upstream.transform(args); }
+    if (!stamps) return upstream.transform(args);
+    const complete = result => { stamps.complete(); return result; };
+    const passthrough = error => {
+      skipped(error);
+      stamps.complete(true);
+      return upstream.transform(args);
+    };
+    try {
+      const result = upstream.transform({ ...args, plugins: [stamps.plugin, ...(args.plugins ?? [])] });
+      return result && typeof result.then === 'function'
+        ? result.then(complete, passthrough) : complete(result);
+    } catch (error) { return passthrough(error); }
   },
   getCacheKey(...args) {
     const base =
       typeof upstream.getCacheKey === 'function'
         ? upstream.getCacheKey(...args)
         : '';
-    return `${base}$keepsnappy:${entryFile}:${bootFile}:${sdkVersion}:${envSignature()}`;
+    return `${base}$keepsnappy:${entryFile}:${bootFile}:${sdkVersion}:${envSignature()}:components-v2:${JSON.stringify(clientPackages)}:${componentCacheKey}`;
   },
 };

package/js/component-contract.cjs

@@ -0,0 +1,14 @@
+// Build-time copy of @keepsnappy/facts. The SDK ships without the
+// private facts workspace; Metro's round-trip test pins this encoder to it.
+const FRAGMENT_VERSION = 2;
+const isComponentName = name => typeof name === 'string' && /^[\p{Lu}\p{Lt}][\p{ID_Continue}$\u200C\u200D]*$/u.test(name);
+function componentKey(name, file) {
+  if ((name !== 'default' && !isComponentName(name)) || typeof file !== 'string' || !file
+    || /^(?:\/|[A-Za-z]:)/.test(file) || file.includes('\\')
+    || file.split('/').some(part => part === '..' || part === '.' || part === '')) {
+    throw new Error('invalid client component name or file');
+  }
+  const encoded = encodeURIComponent(file).replace(/%2F/g, '/').replace(/%40/g, '@').replace(/~/g, '%7E');
+  return `${name}@${encoded}`;
+}
+module.exports = { FRAGMENT_VERSION, componentKey, isComponentName };

package/js/component-stamps.js

@@ -0,0 +1,207 @@
+const fs = require('fs');
+const path = require('path');
+const { createHash, randomUUID } = require('crypto');
+const { FRAGMENT_VERSION, componentKey, isComponentName } = require('./component-contract.cjs');
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const posix = value => value.replace(/\\/g, '/');
+const realPath = file => {
+  try { return fs.realpathSync(file); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return path.resolve(file);
+  }
+};
+
+function atomicJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(value));
+    fs.renameSync(temporary, file);
+  } finally { fs.rmSync(temporary, { force: true }); }
+}
+
+const configuration = clientPackages => hash(JSON.stringify([FRAGMENT_VERSION, clientPackages]));
+const contexts = new Map();
+function context(projectRoot) {
+  const absolute = path.resolve(projectRoot);
+  if (contexts.has(absolute)) return contexts.get(absolute);
+  const root = realPath(absolute);
+  const owners = new Map();
+  const owningPackage = directory => {
+    if (owners.has(directory)) return owners.get(directory);
+    let owner;
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(directory, 'package.json'), 'utf8'));
+      if (typeof pkg.name === 'string') owner = { name: pkg.name, directory };
+    } catch (error) {
+      if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
+    }
+    if (!owner) {
+      const parent = path.dirname(directory);
+      owner = parent === directory ? null : owningPackage(parent);
+    }
+    owners.set(directory, owner);
+    return owner;
+  };
+  const value = { root, owningPackage, projectPackage: owningPackage(root)?.name };
+  contexts.set(absolute, value);
+  return value;
+}
+
+function configure(projectRoot, clientPackages) {
+  context(projectRoot);
+  const directory = configuration(clientPackages);
+  const selected = path.join(projectRoot, '.keepsnappy', 'components', directory);
+  fs.mkdirSync(selected, { recursive: true });
+  const cacheFile = path.join(selected, '.cache-key');
+  try { fs.writeFileSync(cacheFile, randomUUID(), { flag: 'wx' }); }
+  catch (error) { if (error.code !== 'EEXIST') throw error; }
+  atomicJson(path.join(selected, '.config.json'), { version: FRAGMENT_VERSION, directory });
+  return fs.readFileSync(cacheFile, 'utf8');
+}
+
+function clientFile(filename, projectRoot, clientPackages) {
+  if (!/\.[jt]sx?$/.test(filename)) return null;
+  const source = realPath(filename);
+  if (source.split(path.sep).includes('node_modules') && clientPackages.length === 0) return null;
+  const { root, owningPackage, projectPackage } = context(projectRoot);
+  const pkg = owningPackage(path.dirname(source));
+  const relative = posix(path.relative(root, source));
+  if (pkg && clientPackages.includes(pkg.name)) {
+    return { source: relative, file: `${pkg.name}/${posix(path.relative(pkg.directory, source))}` };
+  }
+  if (relative.startsWith('../') || path.isAbsolute(relative) || source.split(path.sep).includes('node_modules')) return null;
+  if (pkg && pkg.name !== projectPackage) return null;
+  return { source: relative, file: relative };
+}
+
+const reactMember = (node, names) => node?.type === 'Identifier'
+  ? names.includes(node.name)
+  : node?.type === 'MemberExpression' && !node.computed && node.object.type === 'Identifier'
+    && node.object.name === 'React' && names.includes(node.property.name);
+const unwrap = node => {
+  while (['TSAsExpression', 'TSSatisfiesExpression', 'TSNonNullExpression', 'TypeCastExpression', 'ParenthesizedExpression'].includes(node?.type)) node = node.expression;
+  return node;
+};
+const componentValue = node => {
+  node = unwrap(node);
+  return node?.type === 'ArrowFunctionExpression' || node?.type === 'FunctionExpression'
+    || (node?.type === 'CallExpression' && reactMember(node.callee, ['memo', 'forwardRef']));
+};
+
+const jsxResult = node => {
+  node = unwrap(node);
+  if (!node) return false;
+  if (['JSXElement', 'JSXFragment'].includes(node.type)) return true;
+  if (node.type === 'ConditionalExpression') return jsxResult(node.consequent) || jsxResult(node.alternate);
+  if (node.type === 'LogicalExpression') return jsxResult(node.right) || (node.operator !== '&&' && jsxResult(node.left));
+  if (node.type === 'SequenceExpression') return jsxResult(node.expressions.at(-1));
+  return false;
+};
+const returnsJSX = (body, t) => {
+  if (body.type !== 'BlockStatement') return jsxResult(body);
+  const visit = node => {
+    if (!node || t.isFunction(node) || t.isClass(node)) return false;
+    if (node.type === 'ReturnStatement') return jsxResult(node.argument);
+    return (t.VISITOR_KEYS[node.type] ?? []).some(key => {
+      const child = node[key];
+      return Array.isArray(child) ? child.some(visit) : visit(child);
+    });
+  };
+  return visit(body);
+};
+const anonymousRender = (node, t) => {
+  node = unwrap(node);
+  if (node?.type === 'CallExpression' && reactMember(node.callee, ['memo', 'forwardRef'])) return anonymousRender(node.arguments[0], t);
+  return ['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression'].includes(node?.type)
+    && !node.id && !node.async && !node.generator && returnsJSX(node.body, t);
+};
+
+// A plugin that ran first (React Compiler listed in the app's babel.config.js) may put back regenerated nodes without
+// `loc`; the line then comes from the declaration in the source.
+const declarationLine = (src, id, statement, lineOffset) => {
+  const line = id.loc?.start?.line ?? statement.loc?.start?.line;
+  if (typeof line === 'number') return Math.max(1, line - lineOffset);
+  const match = new RegExp(`^[ \\t]*(?:export[ \\t]+(?:default[ \\t]+)?)?(?:async[ \\t]+)?(?:function\\*?|class|const)[ \\t]+${id.name}\\b`, 'm').exec(src);
+  return match ? src.slice(0, match.index).split('\n').length : 1;
+};
+
+function instrumentation(src, filename, projectRoot, clientPackages, lineOffset = 0) {
+  const client = clientFile(filename, projectRoot, clientPackages);
+  if (!client) return null;
+  const components = [];
+  const contentHash = hash(src);
+  const target = path.join(projectRoot, '.keepsnappy', 'components', configuration(clientPackages), `${hash(client.source)}-${contentHash}.json`);
+  const plugin = ({ types: t }) => ({
+    name: 'keepsnappy-components',
+    visitor: {
+      Program(program) {
+        // Inspect the original module body once, before preset visitors lower declarations.
+        for (const statement of program.get('body')) {
+          const node = statement.node;
+          const declaration = ['ExportNamedDeclaration', 'ExportDefaultDeclaration'].includes(node.type) ? node.declaration : node;
+          if (!declaration || declaration.declare) continue;
+          const found = [];
+          if (declaration.type === 'FunctionDeclaration' && isComponentName(declaration.id?.name)) found.push(declaration.id);
+          else if (declaration.type === 'ClassDeclaration' && isComponentName(declaration.id?.name)
+            && reactMember(declaration.superClass, ['Component', 'PureComponent'])) found.push(declaration.id);
+          else if (declaration.type === 'VariableDeclaration' && declaration.kind === 'const') {
+            for (const binding of declaration.declarations) {
+              if (binding.id.type === 'Identifier' && isComponentName(binding.id.name) && componentValue(binding.init)) found.push(binding.id);
+            }
+          }
+          let defaultId;
+          if (node.type === 'ExportDefaultDeclaration' && (
+            anonymousRender(declaration, t) || (declaration.type === 'ClassDeclaration' && !declaration.id
+              && reactMember(declaration.superClass, ['Component', 'PureComponent']))
+          )) {
+            // Only real component defaults gain an uppercase binding.
+            let name = 'KeepSnappyDefault';
+            while (program.scope.hasBinding(name) || program.scope.hasGlobal(name) || program.scope.hasReference(name)) name += '_';
+            defaultId = t.identifier(name);
+            defaultId.loc = declaration.loc;
+            if (['FunctionDeclaration', 'ClassDeclaration'].includes(declaration.type)) {
+              // Keep declarations in place, including function hoisting through circular imports.
+              declaration.id = defaultId;
+            } else {
+              statement.insertBefore(t.variableDeclaration('const', [t.variableDeclarator(defaultId, declaration)]));
+              statement.get('declaration').replaceWith(t.cloneNode(defaultId));
+            }
+            found.push(defaultId);
+            program.scope.crawl();
+          }
+          const stamps = [];
+          for (const id of found) {
+            const componentName = id === defaultId ? 'default' : id.name;
+            // One declaration that cannot be stamped must not cost the file its other stamps.
+            try {
+              const key = componentKey(componentName, client.file);
+              const line = declarationLine(src, id, statement.node, lineOffset);
+              const name = () => t.identifier(id.name);
+              const typeIs = value => t.binaryExpression('===', t.unaryExpression('typeof', name()), t.stringLiteral(value));
+              stamps.push(t.ifStatement(t.logicalExpression('||', typeIs('function'), t.logicalExpression('&&',
+                t.binaryExpression('!==', name(), t.nullLiteral()), typeIs('object'))),
+              t.expressionStatement(t.assignmentExpression('=', t.memberExpression(name(), t.identifier('__ks')), t.stringLiteral(key)))));
+              components.push({ key, name: componentName, file: client.file, line });
+            } catch (error) {
+              console.warn(`KeepSnappy: could not stamp ${componentName} in ${client.file}: ${String(error)}`);
+            }
+          }
+          if (stamps.length) statement.insertAfter(stamps);
+        }
+      },
+    },
+  });
+  return {
+    plugin,
+    complete(skipped = false) {
+      // Inventory output is optional; source compilation must remain usable on write failures.
+      try { atomicJson(target, { version: FRAGMENT_VERSION, source: client.source, hash: contentHash, components: skipped ? [] : components }); }
+      catch { /* The CLI reports an unavailable inventory without blocking source maps. */ }
+    },
+  };
+}
+
+module.exports = { configure, instrumentation };

package/js/sdk/bytes.ts

@@ -0,0 +1,20 @@
+// The push queue drops a window line over this many bytes (push.ts enqueue). The window summary budgets against half of it.
+export const MAX_BATCH_BYTES = 256 * 1024;
+
+export const utf8Length = (text: string) => {
+  let n = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (c < 0x80) {
+      n += 1;
+    } else if (c < 0x800) {
+      n += 2;
+    } else if (c >= 0xd800 && c <= 0xdbff) {
+      n += 4;
+      i++;
+    } else {
+      n += 3;
+    }
+  }
+  return n;
+};