@react-native-harness/cache 1.4.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Callstack
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+![harness-banner](https://react-native-harness.dev/harness-banner.jpg)
+
+### Cache Management for React Native Harness
+
+[![mit licence][license-badge]][license]
+[![npm downloads][npm-downloads-badge]][npm-downloads]
+[![Chat][chat-badge]][chat]
+[![PRs Welcome][prs-welcome-badge]][prs-welcome]
+
+Owns the layout of `.harness/cache/` and exposes a narrow API for checking and preparing cache directories, so no other package needs to construct cache paths or hold cache-key logic.
+
+## Made with ❤️ at Callstack
+
+`@react-native-harness/cache` is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. [Callstack][callstack-readme-with-love] is a group of React and React Native geeks, contact us at [hello@callstack.com](mailto:hello@callstack.com) if you need any help with these or just want to say hi!
+
+Like the project? ⚛️ [Join the team](https://callstack.com/careers/?utm_campaign=Senior_RN&utm_source=github&utm_medium=readme) who does amazing stuff for clients and drives React Native Open Source! 🔥
+
+[callstack-readme-with-love]: https://callstack.com/?utm_source=github.com&utm_medium=referral&utm_campaign=react-native-harness&utm_term=readme-with-love
+[license-badge]: https://img.shields.io/npm/l/@react-native-harness/cache?style=for-the-badge
+[license]: https://github.com/callstackincubator/react-native-harness/blob/main/LICENSE
+[npm-downloads-badge]: https://img.shields.io/npm/dm/@react-native-harness/cache?style=for-the-badge
+[npm-downloads]: https://www.npmjs.com/package/@react-native-harness/cache
+[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge
+[prs-welcome]: ../../CONTRIBUTING.md
+[chat-badge]: https://img.shields.io/discord/426714625279524876.svg?style=for-the-badge
+[chat]: https://discord.gg/xgGt7KAjxv

package/dist/__tests__/boundary.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=boundary.test.d.ts.map

package/dist/__tests__/boundary.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/boundary.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/boundary.test.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+// All `.harness/cache` layout knowledge must live in this package; other
+// packages consume `HarnessCache.paths` instead of constructing cache paths
+// themselves. This test scans the other packages' sources for violations.
+//
+// Allowlisted until phase 2 migrates them onto this package:
+// - packages/tools/src/harness-artifacts.ts: getHarnessCacheRootPath, used by
+//   platform-ios for the XCTest agent cache.
+const ALLOWLIST = new Set(['tools/src/harness-artifacts.ts']);
+const findRepoRoot = (start) => {
+    let dir = start;
+    while (!fs.existsSync(path.join(dir, 'pnpm-workspace.yaml'))) {
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            throw new Error('Could not find the repository root');
+        }
+        dir = parent;
+    }
+    return dir;
+};
+const collectSourceFiles = (dir, files = []) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            if (entry.name === 'node_modules' ||
+                entry.name === 'dist' ||
+                entry.name === '__tests__') {
+                continue;
+            }
+            collectSourceFiles(path.join(dir, entry.name), files);
+        }
+        else if (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx')) {
+            files.push(path.join(dir, entry.name));
+        }
+    }
+    return files;
+};
+const constructsHarnessCachePath = (content) => {
+    if (content.includes('.harness/cache')) {
+        return true;
+    }
+    const hasHarnessDirLiteral = content.includes("'.harness'") || content.includes('".harness"');
+    // A quoted 'cache' followed by `,`, `)`, or `]` is a path segment being
+    // joined, as opposed to e.g. a property name in a type.
+    const hasCacheSegmentLiteral = /['"]cache['"]\s*[,)\]]/.test(content);
+    return hasHarnessDirLiteral && hasCacheSegmentLiteral;
+};
+describe('cache path boundary', () => {
+    it('no package outside @react-native-harness/cache constructs .harness cache paths', () => {
+        const repoRoot = findRepoRoot(path.dirname(fileURLToPath(import.meta.url)));
+        const packagesRoot = path.join(repoRoot, 'packages');
+        const violations = [];
+        for (const entry of fs.readdirSync(packagesRoot, {
+            withFileTypes: true,
+        })) {
+            if (!entry.isDirectory() || entry.name === 'cache') {
+                continue;
+            }
+            const srcDir = path.join(packagesRoot, entry.name, 'src');
+            if (!fs.existsSync(srcDir)) {
+                continue;
+            }
+            for (const file of collectSourceFiles(srcDir)) {
+                const relativePath = path.relative(packagesRoot, file);
+                if (ALLOWLIST.has(relativePath)) {
+                    continue;
+                }
+                if (constructsHarnessCachePath(fs.readFileSync(file, 'utf8'))) {
+                    violations.push(relativePath);
+                }
+            }
+        }
+        expect(violations).toEqual([]);
+    });
+});

package/dist/__tests__/domains/metro.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=metro.test.d.ts.map

package/dist/__tests__/domains/metro.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metro.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/domains/metro.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/domains/metro.test.js

@@ -0,0 +1,234 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { computeMetroStaticInputs } from '../../domains/metro.js';
+describe('computeMetroStaticInputs', () => {
+    let repoRoot;
+    let projectRoot;
+    beforeEach(() => {
+        repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-cache-metro-'));
+        projectRoot = path.join(repoRoot, 'apps', 'mobile');
+        fs.mkdirSync(projectRoot, { recursive: true });
+    });
+    afterEach(() => {
+        fs.rmSync(repoRoot, { recursive: true, force: true });
+    });
+    it('includes a lockfile at an ancestor directory between projectRoot and repoRoot', () => {
+        fs.writeFileSync(path.join(repoRoot, 'pnpm-lock.yaml'), 'lockfile-a');
+        const before = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        fs.writeFileSync(path.join(repoRoot, 'pnpm-lock.yaml'), 'lockfile-b');
+        const after = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        expect(before.lockfileHash).not.toBe(after.lockfileHash);
+    });
+    it('ignores a config file in a sibling directory not on the ancestor chain', () => {
+        const siblingDir = path.join(repoRoot, 'apps', 'other');
+        fs.mkdirSync(siblingDir, { recursive: true });
+        fs.writeFileSync(path.join(siblingDir, 'metro.config.js'), 'config-a');
+        const before = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        fs.writeFileSync(path.join(siblingDir, 'metro.config.js'), 'config-b');
+        const after = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        expect(before.lockfileHash).toBe(after.lockfileHash);
+    });
+    it('excludes a vendored lockfile under node_modules (regression pin)', () => {
+        // Pin for the old bug where a downward `hashFiles('**/pnpm-lock.yaml',
+        // ...)`-style glob would match a dependency's own lockfile under
+        // node_modules. Trivially true now that node_modules is never on the
+        // upward ancestor chain, but kept as an explicit regression test.
+        fs.writeFileSync(path.join(repoRoot, 'pnpm-lock.yaml'), 'lockfile-a');
+        const vendoredDir = path.join(projectRoot, 'node_modules', 'some-pkg');
+        fs.mkdirSync(vendoredDir, { recursive: true });
+        fs.writeFileSync(path.join(vendoredDir, 'package-lock.json'), 'vendored-lockfile');
+        const withVendored = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        fs.rmSync(path.join(projectRoot, 'node_modules'), {
+            recursive: true,
+            force: true,
+        });
+        const withoutVendored = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        expect(withVendored.lockfileHash).toBe(withoutVendored.lockfileHash);
+    });
+    it('is deterministic across independent calls given the same fixture tree', () => {
+        fs.writeFileSync(path.join(repoRoot, 'pnpm-lock.yaml'), 'lockfile-a');
+        fs.writeFileSync(path.join(projectRoot, 'metro.config.js'), 'config-a');
+        const first = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        const second = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        expect(first.lockfileHash).toBe(second.lockfileHash);
+    });
+    it('changes the hash when a matched file changes content', () => {
+        fs.writeFileSync(path.join(repoRoot, 'pnpm-lock.yaml'), 'lockfile-a');
+        const before = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        fs.writeFileSync(path.join(repoRoot, 'pnpm-lock.yaml'), 'lockfile-b');
+        const after = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        expect(before.lockfileHash).not.toBe(after.lockfileHash);
+    });
+    it('does not change the hash when an unrelated file changes content', () => {
+        fs.writeFileSync(path.join(repoRoot, 'pnpm-lock.yaml'), 'lockfile-a');
+        fs.writeFileSync(path.join(projectRoot, 'notes.txt'), 'v1');
+        const before = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        fs.writeFileSync(path.join(projectRoot, 'notes.txt'), 'v2');
+        const after = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        expect(before.lockfileHash).toBe(after.lockfileHash);
+    });
+    it.each([
+        ['metro.config.mts', 'metro-mts-a', 'metro-mts-b'],
+        ['metro.config.cts', 'metro-cts-a', 'metro-cts-b'],
+        ['metro.config.json', 'metro-json-a', 'metro-json-b'],
+        ['babel.config.cts', 'babel-cts-a', 'babel-cts-b'],
+    ])('picks up %s as a candidate at projectRoot', (filename, before, after) => {
+        fs.writeFileSync(path.join(projectRoot, filename), before);
+        const beforeInputs = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        fs.writeFileSync(path.join(projectRoot, filename), after);
+        const afterInputs = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        expect(beforeInputs.lockfileHash).not.toBe(afterInputs.lockfileHash);
+    });
+    it('picks up .config/metro.js as a candidate at projectRoot', () => {
+        const configDir = path.join(projectRoot, '.config');
+        fs.mkdirSync(configDir, { recursive: true });
+        fs.writeFileSync(path.join(configDir, 'metro.js'), 'config-a');
+        const before = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        fs.writeFileSync(path.join(configDir, 'metro.js'), 'config-b');
+        const after = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        expect(before.lockfileHash).not.toBe(after.lockfileHash);
+    });
+    it('no longer treats babel.config.ts as a candidate', () => {
+        const before = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        fs.writeFileSync(path.join(projectRoot, 'babel.config.ts'), 'babel-ts-a');
+        const afterCreate = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        fs.writeFileSync(path.join(projectRoot, 'babel.config.ts'), 'babel-ts-b');
+        const afterChange = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        expect(afterCreate.lockfileHash).toBe(before.lockfileHash);
+        expect(afterChange.lockfileHash).toBe(before.lockfileHash);
+    });
+    it('passes bundlerMetroVersion and salt through into the returned object', () => {
+        fs.writeFileSync(path.join(repoRoot, 'pnpm-lock.yaml'), 'lockfile-a');
+        const withoutSalt = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '2.3.4',
+        });
+        expect(withoutSalt.bundlerMetroVersion).toBe('2.3.4');
+        expect(withoutSalt.salt).toBeUndefined();
+        const withSalt = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot,
+            bundlerMetroVersion: '2.3.4',
+            salt: 'v2',
+        });
+        expect(withSalt.salt).toBe('v2');
+    });
+    it('returns a stable fallback instead of throwing when projectRoot does not exist', () => {
+        const missingProjectRoot = path.join(repoRoot, 'does-not-exist');
+        const result = computeMetroStaticInputs({
+            projectRoot: missingProjectRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        expect(result).toEqual({
+            lockfileHash: 'unavailable',
+            bundlerMetroVersion: '1.0.0',
+        });
+    });
+    it('returns a stable fallback instead of throwing when repoRoot does not exist', () => {
+        const missingRepoRoot = path.join(repoRoot, 'does-not-exist');
+        const result = computeMetroStaticInputs({
+            projectRoot,
+            repoRoot: missingRepoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        expect(result).toEqual({
+            lockfileHash: 'unavailable',
+            bundlerMetroVersion: '1.0.0',
+        });
+    });
+    it('works when projectRoot === repoRoot (single directory examined)', () => {
+        fs.writeFileSync(path.join(repoRoot, 'pnpm-lock.yaml'), 'lockfile-a');
+        const before = computeMetroStaticInputs({
+            projectRoot: repoRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        fs.writeFileSync(path.join(repoRoot, 'pnpm-lock.yaml'), 'lockfile-b');
+        const after = computeMetroStaticInputs({
+            projectRoot: repoRoot,
+            repoRoot,
+            bundlerMetroVersion: '1.0.0',
+        });
+        expect(before.lockfileHash).not.toBe(after.lockfileHash);
+    });
+});

package/dist/__tests__/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/__tests__/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/index.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/index.test.js

@@ -0,0 +1,40 @@
+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;
+    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/dist/__tests__/paths.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=paths.test.d.ts.map

package/dist/__tests__/paths.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/paths.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/paths.test.js

@@ -0,0 +1,12 @@
+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/dist/__tests__/plan.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plan.test.d.ts.map

package/dist/__tests__/plan.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/plan.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/plan.test.js

@@ -0,0 +1,197 @@
+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, } from '../plan.js';
+describe('planRestore', () => {
+    let projectRoot;
+    beforeEach(() => {
+        projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-cache-'));
+    });
+    afterEach(() => {
+        fs.rmSync(projectRoot, { recursive: true, force: true });
+    });
+    const inputs = (staticInputs) => ({
+        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;
+    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;
+    beforeEach(() => {
+        projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-cache-'));
+    });
+    afterEach(() => {
+        fs.rmSync(projectRoot, { recursive: true, force: true });
+    });
+    const inputs = (staticInputs = { a: '1' }) => ({
+        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 = {};
+        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;
+    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/dist/__tests__/warmth.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=warmth.test.d.ts.map

package/dist/__tests__/warmth.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warmth.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/warmth.test.ts"],"names":[],"mappings":""}