@react-native-harness/cache 1.4.0

package/src/__tests__/index.test.ts

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createHarnessCache } from '../index.js';
+
+describe('createHarnessCache', () => {
+  let projectRoot: string;
+
+  beforeEach(() => {
+    projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-cache-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it('exposes paths rooted at <projectRoot>/.harness/cache', () => {
+    const cache = createHarnessCache({ projectRoot });
+
+    expect(cache.paths.root).toBe(path.join(projectRoot, '.harness', 'cache'));
+  });
+
+  it('reports metro as cold before directories exist', () => {
+    const cache = createHarnessCache({ projectRoot });
+
+    expect(cache.isWarm('metro')).toBe(false);
+  });
+
+  it('creates domain directories and reports warm once populated', () => {
+    const cache = createHarnessCache({ projectRoot });
+
+    cache.ensureDomainDirectories('metro');
+
+    expect(fs.existsSync(cache.paths.metroTransform)).toBe(true);
+    expect(fs.existsSync(cache.paths.metroFileMap)).toBe(true);
+    expect(cache.isWarm('metro')).toBe(false);
+
+    fs.writeFileSync(path.join(cache.paths.metroTransform, 'entry'), 'data');
+    expect(cache.isWarm('metro')).toBe(true);
+  });
+
+  it('swallows and logs errors instead of throwing when directories cannot be created', () => {
+    // Point the project root at a path that cannot be created (its parent is a file).
+    const blockedRoot = path.join(projectRoot, 'blocked-file', 'nested');
+    fs.writeFileSync(path.join(projectRoot, 'blocked-file'), 'not a directory');
+
+    const cache = createHarnessCache({ projectRoot: blockedRoot });
+
+    expect(() => cache.ensureDomainDirectories('metro')).not.toThrow();
+    expect(cache.isWarm('metro')).toBe(false);
+  });
+});

package/src/__tests__/paths.test.ts

@@ -0,0 +1,18 @@
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { createHarnessCachePaths } from '../paths.js';
+
+describe('createHarnessCachePaths', () => {
+  it('nests cache paths under <projectRoot>/.harness/cache', () => {
+    const projectRoot = '/tmp/some-project';
+    const paths = createHarnessCachePaths(projectRoot);
+
+    expect(paths.root).toBe(path.join(projectRoot, '.harness', 'cache'));
+    expect(paths.metroTransform).toBe(
+      path.join(projectRoot, '.harness', 'cache', 'metro')
+    );
+    expect(paths.metroFileMap).toBe(
+      path.join(projectRoot, '.harness', 'cache', 'metro-file-map')
+    );
+  });
+});

package/src/__tests__/plan.test.ts

@@ -0,0 +1,330 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createHarnessCachePaths } from '../paths.js';
+import {
+  planRestore,
+  planSave,
+  snapshot,
+  writeKeysFile,
+  type CacheKeyInputs,
+  type CacheSnapshot,
+} from '../plan.js';
+
+describe('planRestore', () => {
+  let projectRoot: string;
+
+  beforeEach(() => {
+    projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-cache-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  const inputs = (
+    staticInputs: Record<string, string>
+  ): Record<'metro', CacheKeyInputs> => ({
+    metro: { os: 'linux', staticInputs },
+  });
+
+  it('produces the same restoreKey across independent calls given the same staticInputs', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+
+    const first = planRestore(paths, inputs({ a: '1', b: '2' }));
+    const second = planRestore(paths, inputs({ a: '1', b: '2' }));
+
+    expect(first.domains.metro?.restoreKey).toBe(
+      second.domains.metro?.restoreKey
+    );
+  });
+
+  it('produces the same restoreKey regardless of staticInputs key order', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+
+    const first = planRestore(paths, inputs({ a: '1', b: '2' }));
+    const second = planRestore(paths, inputs({ b: '2', a: '1' }));
+
+    expect(first.domains.metro?.restoreKey).toBe(
+      second.domains.metro?.restoreKey
+    );
+  });
+
+  it('produces a different restoreKey for different staticInputs', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+
+    const first = planRestore(paths, inputs({ a: '1' }));
+    const second = planRestore(paths, inputs({ a: '2' }));
+
+    expect(first.domains.metro?.restoreKey).not.toBe(
+      second.domains.metro?.restoreKey
+    );
+  });
+
+  it('shapes restorePrefixes for the accretive metro domain as a single trailing-dash prefix', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    const plan = planRestore(paths, inputs({ a: '1' }));
+    const domain = plan.domains.metro;
+
+    expect(domain?.accretive).toBe(true);
+    expect(domain?.restorePrefixes).toEqual([`${domain?.restoreKey}-`]);
+  });
+
+  it('only includes domains present in the inputs', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    const plan = planRestore(paths, {});
+
+    expect(plan.domains).toEqual({});
+  });
+
+  it('reports the domain cache directories as paths', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    const plan = planRestore(paths, inputs({ a: '1' }));
+
+    expect(plan.domains.metro?.paths).toEqual([
+      paths.metroTransform,
+      paths.metroFileMap,
+    ]);
+  });
+});
+
+describe('snapshot', () => {
+  let projectRoot: string;
+
+  beforeEach(() => {
+    projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-cache-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  it('is empty for a domain whose directories do not exist', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+
+    expect(() => snapshot(paths)).not.toThrow();
+    expect(snapshot(paths).metro).toEqual([]);
+  });
+
+  it('collects entries for files under the domain directories', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    fs.mkdirSync(path.join(paths.metroTransform, 'nested'), {
+      recursive: true,
+    });
+    fs.writeFileSync(path.join(paths.metroTransform, 'a.txt'), 'aaa');
+    fs.writeFileSync(
+      path.join(paths.metroTransform, 'nested', 'b.txt'),
+      'bb'
+    );
+
+    const result = snapshot(paths);
+    const entries = result.metro ?? [];
+
+    expect(entries).toHaveLength(2);
+    const aEntry = entries.find((entry) =>
+      entry.path.endsWith(path.join('metro', 'a.txt'))
+    );
+    const bEntry = entries.find((entry) =>
+      entry.path.endsWith(path.join('metro', 'nested', 'b.txt'))
+    );
+    expect(aEntry?.sizeBytes).toBe(3);
+    expect(bEntry?.sizeBytes).toBe(2);
+    expect(typeof aEntry?.mtimeMs).toBe('number');
+  });
+});
+
+describe('planSave', () => {
+  let projectRoot: string;
+
+  beforeEach(() => {
+    projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-cache-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  const inputs = (
+    staticInputs: Record<string, string> = { a: '1' }
+  ): Record<'metro', CacheKeyInputs> => ({
+    metro: { os: 'linux', staticInputs },
+  });
+
+  it('does not save when there is no change, regardless of policy', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    fs.mkdirSync(paths.metroTransform, { recursive: true });
+    fs.writeFileSync(path.join(paths.metroTransform, 'a.txt'), 'aaa');
+
+    const before = snapshot(paths);
+    const plan = planSave(
+      paths,
+      before,
+      { mode: 'always', isDefaultBranch: true },
+      inputs()
+    );
+
+    expect(plan.domains.metro?.shouldSave).toBe(false);
+    expect(plan.domains.metro?.delta).toEqual({
+      addedEntries: 0,
+      removedEntries: 0,
+      addedBytes: 0,
+    });
+  });
+
+  it('saves an added file only when policy allows it', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    fs.mkdirSync(paths.metroTransform, { recursive: true });
+    const before = snapshot(paths);
+
+    fs.writeFileSync(path.join(paths.metroTransform, 'a.txt'), 'aaa');
+
+    const disallowed = planSave(
+      paths,
+      before,
+      { mode: 'default-branch', isDefaultBranch: false },
+      inputs()
+    );
+    expect(disallowed.domains.metro?.shouldSave).toBe(false);
+    expect(disallowed.domains.metro?.delta.addedEntries).toBe(1);
+    expect(disallowed.domains.metro?.delta.addedBytes).toBe(3);
+
+    const allowed = planSave(
+      paths,
+      before,
+      { mode: 'default-branch', isDefaultBranch: true },
+      inputs()
+    );
+    expect(allowed.domains.metro?.shouldSave).toBe(true);
+  });
+
+  it('never saves when policy mode is "never"', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    fs.mkdirSync(paths.metroTransform, { recursive: true });
+    const before = snapshot(paths);
+    fs.writeFileSync(path.join(paths.metroTransform, 'a.txt'), 'aaa');
+
+    const plan = planSave(
+      paths,
+      before,
+      { mode: 'never', isDefaultBranch: true },
+      inputs()
+    );
+
+    expect(plan.domains.metro?.shouldSave).toBe(false);
+  });
+
+  it('counts a removed file in the delta', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    fs.mkdirSync(paths.metroTransform, { recursive: true });
+    fs.writeFileSync(path.join(paths.metroTransform, 'a.txt'), 'aaa');
+    const before = snapshot(paths);
+
+    fs.rmSync(path.join(paths.metroTransform, 'a.txt'));
+
+    const plan = planSave(
+      paths,
+      before,
+      { mode: 'always', isDefaultBranch: true },
+      inputs()
+    );
+
+    expect(plan.domains.metro?.delta.removedEntries).toBe(1);
+    expect(plan.domains.metro?.shouldSave).toBe(true);
+  });
+
+  it('does not treat an mtime-only change as an added entry or change the content hash', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    fs.mkdirSync(paths.metroTransform, { recursive: true });
+    const filePath = path.join(paths.metroTransform, 'a.txt');
+    fs.writeFileSync(filePath, 'aaa');
+    const before = snapshot(paths);
+
+    const beforeSave = planSave(
+      paths,
+      before,
+      { mode: 'always', isDefaultBranch: true },
+      inputs()
+    );
+
+    // Touch the file's mtime without changing its size/content.
+    const future = new Date(Date.now() + 10_000);
+    fs.utimesSync(filePath, future, future);
+
+    const afterSave = planSave(
+      paths,
+      before,
+      { mode: 'always', isDefaultBranch: true },
+      inputs()
+    );
+
+    expect(afterSave.domains.metro?.delta.addedEntries).toBe(0);
+    expect(afterSave.domains.metro?.shouldSave).toBe(false);
+    expect(afterSave.domains.metro?.saveKey).toBe(
+      beforeSave.domains.metro?.saveKey
+    );
+  });
+
+  it('produces a deterministic saveKey across independent planSave calls given the same on-disk state', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    fs.mkdirSync(paths.metroTransform, { recursive: true });
+    fs.writeFileSync(path.join(paths.metroTransform, 'a.txt'), 'aaa');
+    const before: CacheSnapshot = {};
+
+    const first = planSave(
+      paths,
+      before,
+      { mode: 'always', isDefaultBranch: true },
+      inputs()
+    );
+    const second = planSave(
+      paths,
+      before,
+      { mode: 'always', isDefaultBranch: true },
+      inputs()
+    );
+
+    expect(first.domains.metro?.saveKey).toBe(second.domains.metro?.saveKey);
+  });
+});
+
+describe('writeKeysFile', () => {
+  let projectRoot: string;
+
+  beforeEach(() => {
+    projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-cache-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  it('writes keys.json under the cache root, outside domain subdirectories', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    const plan = planRestore(paths, {
+      metro: { os: 'linux', staticInputs: { a: '1' } },
+    });
+
+    writeKeysFile(paths, plan);
+
+    const filePath = path.join(paths.root, 'keys.json');
+    expect(fs.existsSync(filePath)).toBe(true);
+    expect(filePath.startsWith(paths.metroTransform)).toBe(false);
+    expect(filePath.startsWith(paths.metroFileMap)).toBe(false);
+
+    const written = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    expect(written.version).toBe(1);
+  });
+
+  it('swallows errors instead of throwing when the cache root cannot be created', () => {
+    const blockedRoot = path.join(projectRoot, 'blocked-file', 'nested');
+    fs.writeFileSync(path.join(projectRoot, 'blocked-file'), 'not a directory');
+    const paths = createHarnessCachePaths(blockedRoot);
+    const plan = planRestore(paths, {
+      metro: { os: 'linux', staticInputs: { a: '1' } },
+    });
+
+    expect(() => writeKeysFile(paths, plan)).not.toThrow();
+    expect(fs.existsSync(path.join(paths.root, 'keys.json'))).toBe(false);
+  });
+});

package/src/__tests__/warmth.test.ts

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createHarnessCachePaths } from '../paths.js';
+import { isDomainWarm } from '../warmth.js';
+
+describe('isDomainWarm', () => {
+  let projectRoot: string;
+
+  beforeEach(() => {
+    projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-cache-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  it('is false when the domain directory does not exist', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+
+    expect(isDomainWarm('metro', paths)).toBe(false);
+  });
+
+  it('is false when the domain directory exists but is empty', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    fs.mkdirSync(paths.metroTransform, { recursive: true });
+
+    expect(isDomainWarm('metro', paths)).toBe(false);
+  });
+
+  it('is true when the domain directory exists and has entries', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    fs.mkdirSync(paths.metroTransform, { recursive: true });
+    fs.writeFileSync(path.join(paths.metroTransform, 'entry'), 'data');
+
+    expect(isDomainWarm('metro', paths)).toBe(true);
+  });
+
+  it('is false when the path exists but is a file, not a directory', () => {
+    const paths = createHarnessCachePaths(projectRoot);
+    fs.mkdirSync(path.dirname(paths.metroTransform), { recursive: true });
+    fs.writeFileSync(paths.metroTransform, 'not a directory');
+
+    expect(isDomainWarm('metro', paths)).toBe(false);
+  });
+});

package/src/domains/metro.ts

@@ -0,0 +1,202 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '@react-native-harness/tools';
+
+const cacheLogger = logger.child('cache');
+
+// Metro resolves its own config by walking UP from the project root (see
+// Metro's loadConfig docs), never by scanning the tree downward. Lockfiles in
+// a monorepo live at the repo root, i.e. somewhere on projectRoot's ancestor
+// chain. So instead of a downward `hashFiles('**/…')`-style walk (which also
+// has to dodge node_modules/.git/dist/build to avoid vendored copies), we
+// walk upward from projectRoot to repoRoot (inclusive) and hash every
+// candidate key file that exists along that chain. Sibling workspace
+// packages are never on this chain, so their configs can't spuriously
+// invalidate this project's cache key.
+const LOCKFILE_NAMES: readonly string[] = [
+  'bun.lock',
+  'bun.lockb',
+  'package-lock.json',
+  'npm-shrinkwrap.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+];
+
+// Metro config candidates: `metro.config.*` at the directory root, plus the
+// `.config/metro.*` directory convention Metro also resolves.
+const METRO_CONFIG_EXTENSIONS: readonly string[] = [
+  'js',
+  'cjs',
+  'mjs',
+  'ts',
+  'cts',
+  'mts',
+  'json',
+];
+const METRO_CONFIG_NAMES: readonly string[] = METRO_CONFIG_EXTENSIONS.map(
+  (extension) => `metro.config.${extension}`
+);
+const METRO_CONFIG_DIR_NAMES: readonly string[] = METRO_CONFIG_EXTENSIONS.map(
+  (extension) => `.config/metro.${extension}`
+);
+
+// Babel only resolves root configs named `babel.config.*` (note: no `.ts` —
+// Babel does not resolve `babel.config.ts`). File-relative `.babelrc` and the
+// `package.json` `babel`/`metro` fields are intentionally out of scope.
+const BABEL_CONFIG_NAMES: readonly string[] = [
+  'babel.config.json',
+  'babel.config.js',
+  'babel.config.cjs',
+  'babel.config.mjs',
+  'babel.config.cts',
+];
+
+// Relative-to-examined-directory paths checked at every directory on the
+// ancestor chain. All candidates that exist are hashed (rather than
+// emulating Metro/Babel's own first-match-wins resolution), which is
+// deterministic and strictly more conservative.
+export const METRO_KEY_FILENAMES: readonly string[] = [
+  ...LOCKFILE_NAMES,
+  ...METRO_CONFIG_NAMES,
+  ...METRO_CONFIG_DIR_NAMES,
+  ...BABEL_CONFIG_NAMES,
+];
+
+interface KeyFileMatch {
+  relativePath: string;
+  content: Buffer;
+}
+
+/**
+ * Directories to examine: projectRoot and every ancestor directory up to and
+ * including repoRoot. Defensive: if projectRoot isn't inside repoRoot (or
+ * repoRoot can't be related to it), fall back to examining projectRoot alone
+ * rather than guessing.
+ */
+const collectAncestorDirectories = (
+  projectRoot: string,
+  repoRoot: string
+): string[] => {
+  const resolvedProjectRoot = path.resolve(projectRoot);
+  const resolvedRepoRoot = path.resolve(repoRoot);
+
+  if (resolvedProjectRoot === resolvedRepoRoot) {
+    return [resolvedProjectRoot];
+  }
+
+  const relative = path.relative(resolvedRepoRoot, resolvedProjectRoot);
+  const isProjectRootInsideRepoRoot =
+    relative !== '' &&
+    !relative.startsWith(`..${path.sep}`) &&
+    relative !== '..' &&
+    !path.isAbsolute(relative);
+
+  if (!isProjectRootInsideRepoRoot) {
+    return [resolvedProjectRoot];
+  }
+
+  const directories: string[] = [];
+  let current = resolvedProjectRoot;
+  for (;;) {
+    directories.push(current);
+    if (current === resolvedRepoRoot) {
+      break;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      // Reached the filesystem root without hitting repoRoot; defensive
+      // guard against an infinite loop.
+      break;
+    }
+    current = parent;
+  }
+
+  return directories;
+};
+
+const collectKeyFiles = (
+  directories: readonly string[],
+  repoRoot: string
+): KeyFileMatch[] => {
+  const matches: KeyFileMatch[] = [];
+
+  for (const directory of directories) {
+    for (const candidate of METRO_KEY_FILENAMES) {
+      const fullPath = path.join(directory, candidate);
+
+      if (!fs.existsSync(fullPath) || !fs.statSync(fullPath).isFile()) {
+        continue;
+      }
+
+      matches.push({
+        relativePath: path
+          .relative(repoRoot, fullPath)
+          .split(path.sep)
+          .join('/'),
+        content: fs.readFileSync(fullPath),
+      });
+    }
+  }
+
+  return matches;
+};
+
+const hashKeyFiles = (matches: KeyFileMatch[]): string => {
+  const hash = createHash('sha256');
+
+  for (const match of matches
+    .slice()
+    .sort((a, b) => (a.relativePath < b.relativePath ? -1 : 1))) {
+    hash.update(match.relativePath);
+    hash.update('\0');
+    hash.update(match.content);
+    hash.update('\0');
+  }
+
+  return hash.digest('hex');
+};
+
+export const computeMetroStaticInputs = (options: {
+  projectRoot: string;
+  repoRoot: string;
+  bundlerMetroVersion: string;
+  salt?: string;
+}): Record<string, string> => {
+  try {
+    const resolvedProjectRoot = path.resolve(options.projectRoot);
+    const resolvedRepoRoot = path.resolve(options.repoRoot);
+
+    // Validate both roots exist so a missing directory degrades to the
+    // always-miss fallback below instead of silently hashing zero files.
+    if (!fs.statSync(resolvedProjectRoot).isDirectory()) {
+      throw new Error(
+        `projectRoot "${resolvedProjectRoot}" is not a directory`
+      );
+    }
+    if (!fs.statSync(resolvedRepoRoot).isDirectory()) {
+      throw new Error(`repoRoot "${resolvedRepoRoot}" is not a directory`);
+    }
+
+    const directories = collectAncestorDirectories(
+      resolvedProjectRoot,
+      resolvedRepoRoot
+    );
+    const matches = collectKeyFiles(directories, resolvedRepoRoot);
+
+    return {
+      lockfileHash: hashKeyFiles(matches),
+      bundlerMetroVersion: options.bundlerMetroVersion,
+      ...(options.salt ? { salt: options.salt } : {}),
+    };
+  } catch (error) {
+    cacheLogger.warn(
+      `Failed to compute Metro cache key inputs for "${options.projectRoot}". Falling back to an always-miss key.`,
+      error
+    );
+    return {
+      lockfileHash: 'unavailable',
+      bundlerMetroVersion: options.bundlerMetroVersion,
+    };
+  }
+};