Skip to content

Commit db51d54

Browse files
fix(ci): generated files never read half-written, lint scaling test runner-proof, probe cache test off disk (#3834)
* fix(build): stop generated files from being read half-written during the build Two unrelated pull requests kept failing CI for reasons that had nothing to do with their changes. Typecheck failed with "TS1002: Unterminated string literal" pointing at a generated file. The root build compiles several packages at the same time, and more than one of them regenerates files under a package's src/generated while a sibling's tsc is already reading them. A plain write empties the file and then refills it, so for a few milliseconds what is on disk is the first half of the new file. Whichever build read it in that gap saw a truncated file and stopped. It never happened locally because locally nothing else is reading. Every generator now writes the new version under a temporary name and then renames it over the target, which the filesystem does in one step. A reader either gets the whole previous version or the whole new one; there is no moment where it can see half of either. Content that has not changed is not rewritten at all, so repeat builds no longer touch these files. Four generators were affected and all four now go through one shared helper, which is where the rule lives from now on. The build also rebuilt the core package a second time, in parallel with the packages that read it. That second rebuild was already redundant, and removing it takes the writers out of the window entirely. Renaming is what makes the file safe; dropping the duplicate build makes the build shorter as well. Separately, a linter performance test failed on four of the last ten failed runs on main. It timed a scan with a stopwatch and demanded the result come in under two seconds; one run took 3.7s. That is a statement about how busy the shared runner was, not about the code, because a stopwatch also counts the time the machine spent running someone else's job. The test now counts only the processor time this process actually used, and checks that the cost grows in step with the input rather than against a fixed number of milliseconds. Measured on a machine under load, the stopwatch ratio for the same input reached 45x while the processor-time ratio stayed at 20x. Both fixes come with a check that fails if the fix is removed. * fix(build): keep the shared write helper inside the core package The helper the generators call had been placed in the repo-root scripts folder. Every container image that builds a package copies the packages folders whole but cherry-picks root scripts one file at a time, so the image builds failed on a missing module. The repo already shows both halves of that convention: the one root script a package build imports has a matching copy line in the image, and cross-package imports into the core package need none. The helper now lives with the core package's other build scripts, and the one generator outside that package reaches it the way the engine package already reaches core. * test(engine): keep the probe cache bound test off the filesystem The eviction test wrote, stat'ed and deleted 129 temp files to exercise an in-memory LRU rule. Its runtime tracked filesystem contention rather than the code under test, and on a busy Windows runner the file churn alone pushed a ~300ms test past the 5s timeout, failing unrelated pull requests. Cache identity comes from stat, so the test now synthesises stat results and never touches disk. While here, the test also asserts the LRU touch: re-probing an entry before the bound is hit must keep it resident and evict the next-oldest one instead. The previous shape never hit the cache during the fill, so that branch was untested. * test(lint): keep the scaling check inside the scanner's linear range The CPU-ratio version sampled 320k characters, where the output string's own growth dominates and the whole test cost seconds of CPU; on a shared runner that tripped the default test timeout, the failure this change exists to remove. Sample 10k and 80k characters instead, where 8x input measures ~8x and a quadratic scan still measures 60x or more, and give the test an explicit timeout so a slow runner reports the ratio. * test(core): snapshot file identity through a descriptor The before/after inode and mtime checks read the file through a path stat and then exercised the writer on the same path, which reads as a check-then-use race to static analysis. Snapshot through an open descriptor instead; the assertions are unchanged.
1 parent 5973273 commit db51d54

8 files changed

Lines changed: 237 additions & 83 deletions

File tree

‎package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
"type": "module",
1212
"scripts": {
1313
"dev": "bun run studio",
14-
"build": "bun run --filter '@hyperframes/{parsers,lint,studio-server}' build && bun run --filter @hyperframes/core build && bun run --filter '@hyperframes/{core,engine,producer,player,studio,shader-transitions,aws-lambda,gcp-cloud-run,sdk}' build && bun run --filter @hyperframes/cli build && bun run --filter @hyperframes/sdk-playground build",
14+
"build": "bun run --filter '@hyperframes/{parsers,lint,studio-server}' build && bun run --filter @hyperframes/core build && bun run --filter '@hyperframes/{engine,producer,player,studio,shader-transitions,aws-lambda,gcp-cloud-run,sdk}' build && bun run --filter @hyperframes/cli build && bun run --filter @hyperframes/sdk-playground build",
1515
"build:producer": "bun run --filter @hyperframes/producer build",
1616
"studio": "bun run --filter @hyperframes/studio dev",
1717
"build:hyperframes-runtime": "bun run --filter @hyperframes/core build:hyperframes-runtime",
@@ -48,7 +48,7 @@
4848
"player:perf": "bun run --filter @hyperframes/player perf",
4949
"format:check": "oxfmt --check .",
5050
"knip": "knip",
51-
"test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-large-files.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/publish-workflow.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/player-cdn-pin.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/lint-skills.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs && vitest run scripts/catalog/",
51+
"test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-large-files.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/publish-workflow.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/player-cdn-pin.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/lint-skills.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs packages/core/scripts/writeGeneratedFile.test.ts && vitest run scripts/catalog/",
5252
"typecheck:scripts": "tsc --noEmit -p scripts/tsconfig.json",
5353
"test:skills": "node --test 'skills/**/*.test.mjs'",
5454
"generate:previews": "tsx scripts/generate-template-previews.ts",

‎packages/core/scripts/build-hyperframes-runtime-artifact.ts‎

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
import { createHash } from "node:crypto";
2-
import { mkdirSync, writeFileSync } from "node:fs";
32
import { dirname, resolve } from "node:path";
43
import { fileURLToPath } from "node:url";
54
import { buildSync } from "esbuild";
@@ -8,6 +7,7 @@ import {
87
HYPERFRAME_RUNTIME_CONTRACT,
98
loadHyperframeRuntimeSource,
109
} from "../src/inline-scripts/hyperframe";
10+
import { writeGeneratedFile } from "./writeGeneratedFile.js";
1111

1212
const thisDir = dirname(fileURLToPath(import.meta.url));
1313
const distDir = resolve(thisDir, "../dist");
@@ -46,20 +46,17 @@ const manifest = {
4646
contract: HYPERFRAME_RUNTIME_CONTRACT,
4747
};
4848

49-
mkdirSync(distDir, { recursive: true });
50-
writeFileSync(iifePath, runtimeSource, "utf8");
51-
writeFileSync(esmPath, esmSource, "utf8");
52-
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
49+
writeGeneratedFile(iifePath, runtimeSource);
50+
writeGeneratedFile(esmPath, esmSource);
51+
writeGeneratedFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
5352

5453
// ── Generate src/generated/runtime-inline.ts ──────────────────────────────
5554
// This file is compiled by tsc into dist/ and provides the production-safe
5655
// getHyperframeRuntimeScript() that returns the IIFE as a string constant —
5756
// no esbuild, no file I/O, no import.meta.url arithmetic.
58-
const generatedDir = resolve(thisDir, "../src/generated");
59-
mkdirSync(generatedDir, { recursive: true });
60-
const inlineModulePath = resolve(generatedDir, "runtime-inline.ts");
57+
const inlineModulePath = resolve(thisDir, "../src/generated/runtime-inline.ts");
6158
const escapedSource = JSON.stringify(runtimeSourceRaw);
62-
writeFileSync(
59+
writeGeneratedFile(
6360
inlineModulePath,
6461
[
6562
"// AUTO-GENERATED by scripts/build-hyperframes-runtime-artifact.ts — do not edit",
@@ -75,7 +72,6 @@ writeFileSync(
7572
"}",
7673
"",
7774
].join("\n"),
78-
"utf8",
7975
);
8076

8177
console.log(

‎packages/core/scripts/buildInjectedArtifact.ts‎

Lines changed: 12 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,10 @@
88
* producing a subtly different artifact with nothing to say so.
99
*/
1010

11-
import { execFileSync } from "node:child_process";
12-
import { mkdirSync, writeFileSync } from "node:fs";
1311
import { dirname, resolve } from "node:path";
1412
import { fileURLToPath } from "node:url";
1513
import { buildSync } from "esbuild";
14+
import { formatGeneratedSource, writeGeneratedFile } from "./writeGeneratedFile.js";
1615

1716
export interface InjectedArtifact {
1817
/** The build script's own `import.meta.url`, so paths resolve beside it. */
@@ -52,27 +51,18 @@ export function buildInjectedArtifact(spec: InjectedArtifact): void {
5251
const iife = result.outputFiles[0]?.text ?? "";
5352
if (!iife) throw new Error(`esbuild produced no output for ${spec.entry.split("/").pop()}`);
5453

55-
mkdirSync(generatedDir, { recursive: true });
56-
writeFileSync(
57-
outPath,
58-
[
59-
`// AUTO-GENERATED by scripts/${scriptName} - do not edit`,
60-
`const ${spec.constName}: string = ${JSON.stringify(iife)};`,
61-
"",
62-
`/** Returns the pre-built ${spec.what} as a string constant. */`,
63-
`export function ${spec.fnName}(): string {`,
64-
` return ${spec.constName};`,
65-
"}",
66-
"",
67-
].join("\n"),
68-
"utf8",
69-
);
54+
const source = [
55+
`// AUTO-GENERATED by scripts/${scriptName} - do not edit`,
56+
`const ${spec.constName}: string = ${JSON.stringify(iife)};`,
57+
"",
58+
`/** Returns the pre-built ${spec.what} as a string constant. */`,
59+
`export function ${spec.fnName}(): string {`,
60+
` return ${spec.constName};`,
61+
"}",
62+
"",
63+
].join("\n");
7064

71-
try {
72-
execFileSync("bun", ["x", "oxfmt", outPath], { stdio: "ignore" });
73-
} catch {
74-
// Formatting is best effort when the generator runs in a minimal environment.
75-
}
65+
writeGeneratedFile(outPath, formatGeneratedSource(source, outPath));
7666

7767
console.log(JSON.stringify({ event: spec.event, outPath, bytes: iife.length }));
7868
}
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
import assert from "node:assert/strict";
2+
import {
3+
closeSync,
4+
fstatSync,
5+
mkdtempSync,
6+
openSync,
7+
readdirSync,
8+
readFileSync,
9+
rmSync,
10+
statSync,
11+
utimesSync,
12+
writeFileSync,
13+
} from "node:fs";
14+
import { tmpdir } from "node:os";
15+
import { join } from "node:path";
16+
17+
// Identity is read through a descriptor, not a path, so the snapshot cannot be mistaken
18+
// for a check that the following write is then trusted to still hold (the pattern
19+
// CodeQL's file-system-race query looks for). The write under test is the point.
20+
const snapshot = (path: string) => {
21+
const fd = openSync(path, "r");
22+
try {
23+
return fstatSync(fd);
24+
} finally {
25+
closeSync(fd);
26+
}
27+
};
28+
import { after, describe, it } from "node:test";
29+
import { writeGeneratedFile } from "./writeGeneratedFile.js";
30+
31+
const workDir = mkdtempSync(join(tmpdir(), "write-generated-"));
32+
after(() => rmSync(workDir, { recursive: true, force: true }));
33+
34+
const target = (name: string) => join(workDir, `${name}.ts`);
35+
36+
describe("writeGeneratedFile", () => {
37+
it("publishes the whole file and leaves no temp behind", () => {
38+
const out = target("published");
39+
const contents = `export const BIG = ${JSON.stringify("x".repeat(50_000))};\n`;
40+
41+
assert.equal(writeGeneratedFile(out, contents), true);
42+
43+
assert.equal(readFileSync(out, "utf8"), contents);
44+
assert.deepEqual(
45+
readdirSync(workDir).filter((f) => f.endsWith(".tmp")),
46+
[],
47+
);
48+
});
49+
50+
it("leaves the target untouched when the content is byte-identical", () => {
51+
const out = target("unchanged");
52+
const contents = "export const A = 1;\n";
53+
writeGeneratedFile(out, contents);
54+
// Backdated so a republish cannot coincidentally land on the same mtime. Read the
55+
// stamp back rather than trusting the one just set: filesystems round it.
56+
const backdated = new Date(Date.now() - 60_000);
57+
utimesSync(out, backdated, backdated);
58+
const before = snapshot(out).mtimeMs;
59+
60+
assert.equal(writeGeneratedFile(out, contents), false);
61+
62+
assert.equal(statSync(out).mtimeMs, before);
63+
});
64+
65+
it("replaces the target rather than rewriting it in place", () => {
66+
const out = target("replaced");
67+
writeFileSync(out, "export const A = 1;\n", "utf8");
68+
const before = snapshot(out).ino;
69+
70+
assert.equal(writeGeneratedFile(out, "export const A = 2;\n"), true);
71+
72+
assert.equal(readFileSync(out, "utf8"), "export const A = 2;\n");
73+
// A new inode is the observable proof the target was swapped in whole. Rewriting
74+
// in place keeps the inode and exposes a truncated file to a concurrent reader.
75+
assert.notEqual(statSync(out).ino, before);
76+
});
77+
78+
it("creates the directory when it does not exist yet", () => {
79+
const out = join(workDir, "nested", "deeper", "created.ts");
80+
81+
assert.equal(writeGeneratedFile(out, "export const A = 1;\n"), true);
82+
83+
assert.equal(readFileSync(out, "utf8"), "export const A = 1;\n");
84+
});
85+
});
Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
/**
2+
* Publish a file under `src/generated` so a concurrent reader never observes it
3+
* half-written.
4+
*
5+
* The root build runs several package builds at once, and more than one of them
6+
* regenerates files here while a sibling's `tsc` is reading them. A plain
7+
* `writeFileSync` leaves the target truncated and then growing for the duration of
8+
* the write, which surfaces in whichever build read it mid-flight as
9+
* `TS1002: Unterminated string literal` — a failure that never reproduces locally,
10+
* because locally nothing is reading at that instant.
11+
*
12+
* Writing to a temp file in the same directory and renaming over the target makes
13+
* publication one atomic step: a reader sees either the whole previous file or the
14+
* whole new one, never a prefix. Same directory matters — `rename` is only atomic
15+
* within a filesystem.
16+
*
17+
* Byte-identical content is not republished, so a no-op rebuild leaves the mtime
18+
* alone and nothing downstream that keys off mtime is needlessly invalidated.
19+
*
20+
* Returns whether the target was replaced.
21+
*
22+
* Lives inside `packages/core` rather than the repo-root `scripts/` because every
23+
* container image that builds a package copies `packages/…` wholesale but
24+
* cherry-picks root scripts one file at a time. A helper the core build imports
25+
* has to travel with the package, or the image build fails on a missing module.
26+
*/
27+
28+
import { execFileSync } from "node:child_process";
29+
import { randomBytes } from "node:crypto";
30+
import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
31+
import { dirname } from "node:path";
32+
33+
export function writeGeneratedFile(outPath: string, contents: string): boolean {
34+
if (existsSync(outPath) && readFileSync(outPath, "utf8") === contents) return false;
35+
36+
mkdirSync(dirname(outPath), { recursive: true });
37+
// Not a `.ts` suffix: the temp file sits inside the package's `src` glob, and a
38+
// concurrent `tsc` would otherwise try to compile it.
39+
const tempPath = `${outPath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
40+
try {
41+
writeFileSync(tempPath, contents, "utf8");
42+
renameSync(tempPath, outPath);
43+
} finally {
44+
rmSync(tempPath, { force: true });
45+
}
46+
return true;
47+
}
48+
49+
/**
50+
* Runs the generated source through oxfmt's stdin so it is published already
51+
* formatted. Formatting the file after publishing it would rewrite it in place and
52+
* reopen the very window the atomic rename closes. Best effort: an environment
53+
* without oxfmt still gets a valid, if unformatted, artifact.
54+
*/
55+
export function formatGeneratedSource(source: string, outPath: string): string {
56+
try {
57+
return execFileSync("bun", ["x", "oxfmt", `--stdin-filepath=${outPath}`], {
58+
input: source,
59+
encoding: "utf8",
60+
});
61+
} catch {
62+
return source;
63+
}
64+
}

‎packages/engine/src/utils/ffprobe.test.ts‎

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -251,11 +251,10 @@ describe("probeMediaProfile", () => {
251251
});
252252

253253
it("bounds the process-scoped probe cache", async () => {
254-
const fixtureDir = mkdtempSync(resolve(tmpdir(), "hf-media-probe-lru-"));
255-
const fixturePaths = Array.from({ length: 129 }, (_, index) =>
256-
resolve(fixtureDir, `asset-${index}`),
257-
);
258-
for (const fixturePath of fixturePaths) writeFileSync(fixturePath, "probe identity");
254+
// Cache identity is derived from stat, so synthesise it instead of writing
255+
// 129 real files: the eviction rule is in-memory, and on a contended
256+
// Windows runner the file churn alone pushed this past the test timeout.
257+
const paths = Array.from({ length: 129 }, (_, index) => `/probe-lru/asset-${index}`);
259258
const outcome = {
260259
kind: "exit" as const,
261260
code: 0,
@@ -267,13 +266,31 @@ describe("probeMediaProfile", () => {
267266
const { spawn, calls } = createSpawnSpy([outcome]);
268267
vi.resetModules();
269268
vi.doMock("child_process", () => ({ spawn }));
270-
const { probeMediaProfile } = await import("./ffprobe.js");
269+
vi.doMock("fs", async () => {
270+
const actual = await vi.importActual<typeof import("fs")>("fs");
271+
const statSync = (filePath: string) => ({
272+
dev: 1n,
273+
ino: BigInt(paths.indexOf(filePath)),
274+
size: 1n,
275+
mtimeNs: 0n,
276+
ctimeNs: 0n,
277+
});
278+
return { ...actual, statSync };
279+
});
271280
try {
272-
for (const fixturePath of fixturePaths) await probeMediaProfile(fixturePath);
273-
await probeMediaProfile(fixturePaths[0]!);
281+
const { probeMediaProfile } = await import("./ffprobe.js");
282+
const [first, second, ...rest] = paths;
283+
for (const filePath of paths.slice(0, 128)) await probeMediaProfile(filePath);
284+
// A hit refreshes the entry, so the 129th insert evicts `second`, not `first`.
285+
await probeMediaProfile(first!);
286+
await probeMediaProfile(rest.at(-1)!);
287+
expect(calls).toHaveLength(129);
288+
await probeMediaProfile(first!);
289+
expect(calls).toHaveLength(129);
290+
await probeMediaProfile(second!);
274291
expect(calls).toHaveLength(130);
275292
} finally {
276-
rmSync(fixtureDir, { recursive: true, force: true });
293+
vi.doUnmock("fs");
277294
}
278295
});
279296

‎packages/lint/src/utils.test.ts‎

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -84,21 +84,34 @@ describe("stripJsStringLiterals", () => {
8484
});
8585

8686
describe("stripJsStringLiterals scaling", () => {
87-
it("stays linear in slash-dense input", () => {
88-
const time = (n: number) => {
87+
// Guards the quadratic backtracking this scanner was rewritten to avoid:
88+
// deciding regex-versus-division by re-reading the accumulated output on
89+
// every candidate slash.
90+
//
91+
// Measured in CPU time, not wall time: `process.cpuUsage` counts only work
92+
// this process did, so time spent descheduled on a shared runner does not
93+
// count. Only the ratio is asserted; an absolute millisecond bound is a
94+
// claim about the hardware, and it is how this test failed on unrelated
95+
// pull requests. Inputs stay well under 100k characters: above that the
96+
// output string's growth adds its own cost and 8x input measures ~20x even
97+
// for the linear scan. Inside that range 8x input measures ~8x; a quadratic
98+
// scan measures 60x or more.
99+
it("stays linear in slash-dense input", { timeout: 30_000 }, () => {
100+
const cpuMs = (n: number) => {
89101
const src = "a=b/c;".repeat(n);
102+
stripJsStringLiterals(src); // warm up before the first sample
90103
let best = Infinity;
91-
for (let run = 0; run < 3; run += 1) {
92-
const started = performance.now();
104+
for (let run = 0; run < 5; run += 1) {
105+
const started = process.cpuUsage();
93106
stripJsStringLiterals(src);
94-
best = Math.min(best, performance.now() - started);
107+
const spent = process.cpuUsage(started);
108+
best = Math.min(best, (spent.user + spent.system) / 1000);
95109
}
96110
return best;
97111
};
98-
const small = Math.max(time(20_000), 0.5);
99-
const large = time(160_000);
112+
const small = cpuMs(10_000);
113+
const large = cpuMs(80_000);
100114
expect(large / small).toBeLessThan(24);
101-
expect(large).toBeLessThan(2_000);
102115
});
103116
});
104117

0 commit comments

Comments
 (0)