Files
hyperframes/packages/cli/src/utils/checkCache.ts
T
Miguel Ángel 070b964d7b feat(cli): check replays an unchanged project's last pass and takes --no-craft (#7398)
* feat(cli): check returns an unchanged project's last pass in about a second

* fix(cli): the check cache hashes files without a stat race and its tests run before the signal test

* test(cli): the warm check test compares two real runs, not a run and its cached pass

* feat(cli): check --no-craft skips the craft pass for a render preflight

* fix(cli): the check cache keys on timeout, env and large files and never replays a moved tree

* style(cli): format the check cache

* fix(cli): the large-file cache test waits for the clock tick it depends on

* fix(cli): the check cache keys on the browser and on scripts under .hyperframes

* fix(cli): the check cache ignores the video copies the check itself touches
2026-11-08 14:01:58 +00:00

140 lines
4.9 KiB
TypeScript

import { createHash } from "node:crypto";
import {
closeSync,
fstatSync,
mkdirSync,
openSync,
readFileSync,
readdirSync,
writeFileSync,
} from "node:fs";
import { join } from "node:path";
import { CACHE_DIR_NAME as PROXY_CACHE_DIR_NAME } from "@hyperframes/studio-server/proxy-transcoder";
import type { CheckOptions, CheckReport } from "./checkTypes.js";
const PROJECT_STATE_DIR = ".hyperframes";
// What the CLI itself writes under .hyperframes; anything else there (a script the page loads) is project input.
const TOOL_OWNED = new Set([
"artifacts",
"cache",
"history-id",
"video-state.json",
"video-state-lock",
"project.lock",
]);
// Bigger files (video, audio) are not read: size, mtime and ctime (which a tool cannot restore) stand for them.
const HASH_CONTENT_UP_TO = 2 * 1024 * 1024;
// Environment that changes what a check loads or how long it waits, so it is part of the key.
const VERDICT_ENV = /^(HYPERFRAMES?|PRODUCER|HF)_/;
class Uncacheable extends Error {}
function cachePath(projectDir: string): string {
return join(projectDir, ".hyperframes", "cache", "check.json");
}
/** The browser binary a check would launch, by path and file identity; undefined when none is installed. */
export async function browserIdentity(): Promise<string | undefined> {
const { findBrowser } = await import("../browser/manager.js");
const found = await findBrowser();
if (!found) return undefined;
try {
const fd = openSync(found.executablePath, "r");
try {
const { size, mtimeMs, ctimeMs, ino } = fstatSync(fd);
return `${found.executablePath}:${size}:${mtimeMs}:${ctimeMs}:${ino}`;
} finally {
closeSync(fd);
}
} catch {
return undefined;
}
}
function fileFingerprint(path: string): string {
const fd = openSync(path, "r");
try {
const stat = fstatSync(fd);
if (stat.isDirectory()) throw new Uncacheable(`${path} is a linked directory`);
return stat.size <= HASH_CONTENT_UP_TO
? createHash("sha256").update(readFileSync(fd)).digest("hex")
: `${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}:${stat.ino}`;
} finally {
closeSync(fd);
}
}
function hashTree(dir: string, prefix: string, hash: ReturnType<typeof createHash>): void {
const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
a.name < b.name ? -1 : 1,
);
for (const entry of entries) {
if (entry.name === ".git" || entry.name === PROXY_CACHE_DIR_NAME) continue;
if (prefix === `${PROJECT_STATE_DIR}/` && TOOL_OWNED.has(entry.name)) continue;
if (entry.name === "node_modules")
throw new Uncacheable("node_modules can hold code the page runs");
const path = join(dir, entry.name);
const name = `${prefix}${entry.name}`;
if (entry.isDirectory()) hashTree(path, `${name}/`, hash);
else hash.update(`${name}\0${fileFingerprint(path)}\0`);
}
}
/** Everything that can change a check verdict: the project files, the CLI build and the options. */
export function checkCacheKey(
projectDir: string,
options: CheckOptions,
version: string,
browser: string | undefined,
): string | undefined {
if (browser === undefined) return undefined; // no installed browser: the check would download one
const hash = createHash("sha256").update(`${version}\0${browser}\0`);
const { cache: _cache, ...verdictOptions } = options;
const env = Object.entries(process.env)
.filter(([name]) => VERDICT_ENV.test(name))
.sort();
hash.update(`${JSON.stringify([verdictOptions, env])}\0`);
try {
hashTree(projectDir, "", hash);
} catch {
return undefined; // an unreadable or linked tree is not cached; the check itself says what is wrong
}
return hash.digest("hex");
}
/** A budgeted run is partial, and these options need artifacts a replayed report cannot recreate. */
export function checkCacheable(options: CheckOptions): boolean {
return (
options.cache !== false &&
!options.budget &&
!options.snapshots &&
!options.findingFrames &&
!options.inspect
);
}
export function readCachedPass(projectDir: string, key: string): CheckReport | undefined {
try {
const stored = JSON.parse(readFileSync(cachePath(projectDir), "utf8"));
if (stored.key !== key || !stored.report?.ok) return undefined;
return { ...stored.report, cached: { at: stored.at } };
} catch {
return undefined;
}
}
/** Only a clean pass that ran the browser is stored; a failure is always re-run. */
export function storePass(projectDir: string, key: string, report: CheckReport): void {
if (!report.ok || report.browserSkipped) return;
try {
mkdirSync(join(projectDir, ".hyperframes", "cache"), { recursive: true });
const { saved: _saved, ...clean } = report as CheckReport & { saved?: unknown };
writeFileSync(
cachePath(projectDir),
JSON.stringify({ key, at: new Date().toISOString(), report: clean }),
);
} catch {
// A cache that cannot be written only costs the next run its speed-up.
}
}