Files
hyperframes/packages/cli/src/utils/workspaceBuildCheck.ts
T
Miguel Ángel de9206e0f8 fix(cli): detect a missing or stale studio build before it crashes (#4076)
* fix(cli): name the missing or stale workspace package before preview crashes

Running hyperframes preview from source with an unbuilt or stale
package previously crashed deep inside that package's own import
graph with a raw resolver error naming neither the package nor the
fix. Add a preflight that runs before the preview command's own
module import, so it also catches the crash that happens at CLI load
time before the studio dev server ever spawns.

* test(cli): cover the preview workspace-build gate wiring

Adds a test that exercises the real CLI dispatch path (mocked module
loaders, not source-text matching) to prove the preview command's
build-check runs before its module loads and that a failure exits
non-zero without double-printing. Also guards the exports-map reader
against a malformed package.json instead of crashing raw.

* fix(cli): correct why the audio-fx generated file is checked

The comment claimed core/src/index.ts imports both generated files
directly. Only runtime-inline.ts is; audio-fx-runtime-inline.ts is
reachable solely via core's own audio-fx-runtime export subpath,
which the engine package imports. The check itself was already
correct to require both, only the stated reason was wrong.
2026-09-18 09:27:39 -04:00

167 lines
6.1 KiB
TypeScript

// Detects a missing or stale workspace build before anything else imports it.
// Zero `@hyperframes/*` imports: must stay importable when nothing is built.
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { join } from "node:path";
/** Build-dependency order: each package only depends on ones before it. */
export const STUDIO_WORKSPACE_BUILD_ORDER = [
"parsers",
"lint",
"studio-server",
"core",
"player",
] as const;
// Gitignored, produced only by `core`'s own build script. `runtime-inline.ts`
// is imported by `core/src/index.ts` directly; `audio-fx-runtime-inline.ts` is
// only reached via core's own `./audio-fx-runtime` subpath, which engine imports.
const CORE_REQUIRED_GENERATED_FILES = [
"src/generated/runtime-inline.ts",
"src/generated/audio-fx-runtime-inline.ts",
];
export const SKIP_STALE_CHECK_ENV = "HYPERFRAMES_SKIP_BUILD_STALE_CHECK";
export interface WorkspaceBuildProblem {
package: string;
kind: "missing" | "stale";
detail: string;
fix: string;
}
function buildCommand(pkg: string): string {
return `bun run --filter @hyperframes/${pkg} build`;
}
function isTestFile(name: string): boolean {
return /\.test\.[tj]sx?$/.test(name);
}
/** Newest mtime among files under `dir` (recursive; skips node_modules). */
function newestMtimeMs(dir: string, { skipTests }: { skipTests: boolean }): number {
if (!existsSync(dir)) return 0;
const mtimes = readdirSync(dir, { recursive: true, withFileTypes: true })
.filter((entry) => entry.isFile() && !entry.parentPath.includes("node_modules"))
.filter((entry) => !skipTests || !isTestFile(entry.name))
.map((entry) => statSync(join(entry.parentPath, entry.name)).mtimeMs);
return mtimes.length > 0 ? Math.max(...mtimes) : 0;
}
/** The `./dist/...` targets named in every condition of a package's own `exports`
* map (not `publishConfig.exports`, which describes the published tarball). */
function distExportEntries(packageDir: string): Array<{ subpath: string; target: string }> {
const pkgJsonPath = join(packageDir, "package.json");
if (!existsSync(pkgJsonPath)) return [];
const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8")) as {
exports?: Record<string, unknown>;
};
return Object.entries(pkg.exports ?? {}).flatMap(([subpath, conditions]) =>
distTargetsOf(conditions).map((target) => ({ subpath, target })),
);
}
function distTargetsOf(conditions: unknown): string[] {
if (typeof conditions !== "object" || conditions === null) return [];
return Object.values(conditions as Record<string, unknown>).filter(
(value): value is string => typeof value === "string" && value.startsWith("./dist/"),
);
}
// Declared exports whose target file is missing — the gap a merge that adds
// a subpath without a rebuild leaves, which a stale-mtime check alone misses.
function missingDistExportTargets(packageDir: string): string[] {
return distExportEntries(packageDir)
.filter((entry) => !existsSync(join(packageDir, entry.target)))
.map((entry) => `${entry.subpath} (${entry.target})`);
}
// A malformed package.json must produce the same friendly message as any
// other build problem, not an uncaught SyntaxError.
function exportProblemsFor(packageDir: string, pkg: string, fix: string): WorkspaceBuildProblem[] {
let missingExports: string[];
try {
missingExports = missingDistExportTargets(packageDir);
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
return [{ package: pkg, kind: "missing", detail: `package.json is invalid: ${message}`, fix }];
}
if (missingExports.length === 0) return [];
return [
{
package: pkg,
kind: "missing",
detail: `dist is missing exported file(s): ${missingExports.join(", ")}`,
fix,
},
];
}
// Checks parsers/lint/studio-server/core/player in build order. Missing
// files always report; a stale src skips via HYPERFRAMES_SKIP_BUILD_STALE_CHECK=1.
export function checkStudioWorkspaceBuild(repoRoot: string): WorkspaceBuildProblem[] {
const problems: WorkspaceBuildProblem[] = [];
for (const pkg of STUDIO_WORKSPACE_BUILD_ORDER) {
const packageDir = join(repoRoot, "packages", pkg);
const distDir = join(packageDir, "dist");
const fix = buildCommand(pkg);
if (!existsSync(distDir) || readdirSync(distDir).length === 0) {
problems.push({ package: pkg, kind: "missing", detail: "dist/ is missing or empty", fix });
continue;
}
if (pkg === "core") {
const missingGenerated = CORE_REQUIRED_GENERATED_FILES.filter(
(rel) => !existsSync(join(packageDir, rel)),
);
if (missingGenerated.length > 0) {
problems.push({
package: pkg,
kind: "missing",
detail: `generated file(s) missing: ${missingGenerated.join(", ")}`,
fix,
});
continue;
}
}
const exportProblems = exportProblemsFor(packageDir, pkg, fix);
if (exportProblems.length > 0) {
problems.push(...exportProblems);
continue;
}
if (process.env[SKIP_STALE_CHECK_ENV]) continue;
const newestSrc = newestMtimeMs(join(packageDir, "src"), { skipTests: true });
const newestDist = newestMtimeMs(distDir, { skipTests: false });
if (newestSrc > newestDist) {
problems.push({
package: pkg,
kind: "stale",
detail: `src changed after the last build (set ${SKIP_STALE_CHECK_ENV}=1 to skip this check)`,
fix,
});
}
}
return problems;
}
export function formatWorkspaceBuildProblems(problems: WorkspaceBuildProblem[]): string {
const lines = ["Studio workspace build check failed", ""];
for (const problem of problems) {
lines.push(` - ${problem.package}: ${problem.detail}`);
lines.push(` fix: ${problem.fix}`);
}
lines.push("");
lines.push(
" Or build every package in order (core depends on the first three, player on core):",
);
lines.push(" bun run --filter '@hyperframes/{parsers,lint,studio-server}' build \\");
lines.push(" && bun run --filter @hyperframes/core build \\");
lines.push(" && bun run --filter @hyperframes/player build");
return lines.join("\n");
}