diff --git a/packages/cli/src/commands/check.test.ts b/packages/cli/src/commands/check.test.ts index 724f2b5a89..150242db4a 100644 --- a/packages/cli/src/commands/check.test.ts +++ b/packages/cli/src/commands/check.test.ts @@ -1635,6 +1635,28 @@ describe("check pipeline", () => { expect(checkExitCode(report)).toBe(1); }); + it("names the saved report file on stderr after a --json run", async () => { + const { report } = await runScenario(fakeDriver()); + const saved = { + id: "r1", + revision: "rev", + report: "/p/.hyperframes/artifacts/checks/r1.json", + attribution: "recorded-revision" as const, + }; + vi.spyOn(console, "log").mockImplementation(() => undefined); + const err = vi.spyOn(console, "error").mockImplementation(() => undefined); + const command = createCheckCommand({ + resolveProject: () => PROJECT, + runPipeline: vi.fn(async () => ({ ...report, saved })), + prepareMedia: vi.fn(async () => []), + withMeta: (value) => value, + }); + + await runCommand(command, { rawArgs: ["--json"] }); + + expect(err).toHaveBeenCalledWith(`[hyperframes] check: report saved to ${saved.report}`); + }); + it("says in plain words that a lint error left no composition to load", async () => { const lint = lintWith( "error", diff --git a/packages/cli/src/commands/check.ts b/packages/cli/src/commands/check.ts index 0601d01629..edcf385229 100644 --- a/packages/cli/src/commands/check.ts +++ b/packages/cli/src/commands/check.ts @@ -2,7 +2,7 @@ import { captureArtifactRevision } from "../utils/artifactCapture.js"; import { pngDimensions } from "../utils/pngDimensions.js"; import { randomUUID } from "node:crypto"; import { mkdirSync, writeFileSync } from "node:fs"; -import { join, resolve } from "node:path"; +import { dirname, join, resolve } from "node:path"; import { recordArtifacts, type ArtifactCapture, @@ -67,6 +67,10 @@ const DEFAULT_COMMAND_DEPENDENCIES: CheckCommandDependencies = { resolveProject, async runPipeline(project, options) { const capturing = captureArtifactRevision(project.dir).catch(warnNotRecorded); + const id = randomUUID(); + console.error( + `[hyperframes] check: the report is saved to ${checkReportFile(project.dir, id)} when the check ends, unless a warning says it could not be saved`, + ); const report = await runCheckPipeline(project, options); const images = (files: readonly string[]) => files.map((file) => resolve(project.dir, file)); reportArtifacts("check", "frame", images(report.snapshots.files)); @@ -74,7 +78,7 @@ const DEFAULT_COMMAND_DEPENDENCIES: CheckCommandDependencies = { const capture = await capturing; if (!capture) return report; try { - return { ...report, saved: await saveCheckReport(project, options, report, capture) }; + return { ...report, saved: await saveCheckReport(project, options, report, capture, id) }; } catch (error) { warnNotRecorded(error); return report; @@ -93,16 +97,19 @@ function warnNotRecorded(error: unknown): undefined { return undefined; } +export function checkReportFile(projectDir: string, id: string): string { + return join(projectDir, ".hyperframes", "artifacts", "checks", `${id}.json`); +} + async function saveCheckReport( project: ProjectDir, options: CheckOptions, report: CheckReport, capture: ArtifactCapture, + id: string, ): Promise { - const id = randomUUID(); - const directory = join(project.dir, ".hyperframes", "artifacts", "checks"); - mkdirSync(directory, { recursive: true }); - const path = join(directory, `${id}.json`); + const path = checkReportFile(project.dir, id); + mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, JSON.stringify(report, null, 2) + "\n", { flag: "wx" }); const reportScope = "scope" in report && typeof report.scope === "object" && report.scope !== null @@ -311,6 +318,8 @@ export function createCheckCommand( }); if (asJson) { console.log(JSON.stringify(dependencies.withMeta(report), null, 2)); + if (report.saved) + console.error(`[hyperframes] check: report saved to ${report.saved.report}`); } else { printHumanReport(report); if (report.saved) { diff --git a/packages/cli/src/utils/checkDeadline.test.ts b/packages/cli/src/utils/checkDeadline.test.ts index fc5b66714d..8c3ce9ec81 100644 --- a/packages/cli/src/utils/checkDeadline.test.ts +++ b/packages/cli/src/utils/checkDeadline.test.ts @@ -112,6 +112,7 @@ it("an expired check names the phase it was in and the seconds each phase took", await vi.advanceTimersByTimeAsync(2_000); deadline.start(); await vi.advanceTimersByTimeAsync(3_000); + deadline.enter("copies"); deadline.enter("settle"); await vi.advanceTimersByTimeAsync(60_000); deadline.enter("samples"); @@ -216,3 +217,49 @@ it("a check waits as long as the --timeout it was given before it counts as idle await deadline.close(); } }); + +it("names a step once when it is entered again in a loop", () => { + const lines: string[] = []; + const spy = vi + .spyOn(console, "error") + .mockImplementation((line: string) => void lines.push(line)); + const deadline = new CheckDeadline(); + try { + deadline.start(); + for (let i = 0; i < 5; i += 1) deadline.enter("frames", `frame ${i}`); + deadline.enter("crops"); + deadline.enter("frames"); + expect(lines).toEqual([ + "[hyperframes] check: loading the page", + "[hyperframes] check: capturing finding frames", + "[hyperframes] check: capturing finding crops", + "[hyperframes] check: capturing finding frames", + ]); + } finally { + spy.mockRestore(); + } +}); + +it("names each step and repeats it every 30 s on stderr while a step runs long", async () => { + vi.useFakeTimers(); + const lines: string[] = []; + const spy = vi + .spyOn(console, "error") + .mockImplementation((line: string) => void lines.push(line)); + const deadline = new CheckDeadline(); + try { + deadline.start(); + deadline.enter("copies"); + deadline.enter("settle"); + await vi.advanceTimersByTimeAsync(65_000); + expect(lines).toEqual([ + "[hyperframes] check: loading the page", + "[hyperframes] check: waiting for the page to be ready", + "[hyperframes] check: still waiting for the page to be ready (30 s in this step)", + "[hyperframes] check: still waiting for the page to be ready (60 s in this step)", + ]); + } finally { + spy.mockRestore(); + await deadline.close(); + } +}); diff --git a/packages/cli/src/utils/checkDeadline.ts b/packages/cli/src/utils/checkDeadline.ts index b41f8c5a32..ad373b0f3c 100644 --- a/packages/cli/src/utils/checkDeadline.ts +++ b/packages/cli/src/utils/checkDeadline.ts @@ -39,6 +39,7 @@ export class CheckDeadlineError extends Error { } export const COPY_BUDGET_MS = 120_000; +const HEARTBEAT_MS = 30_000; export class CheckCopiesUnfinishedError extends Error { constructor(budgetMs: number, unfinished: readonly string[]) { @@ -79,6 +80,7 @@ export class CheckDeadline { private readonly spent = new Map(); private readonly partials: Array<() => Partial> = []; + private heartbeat: NodeJS.Timeout | undefined; private readonly budgetTimer: NodeJS.Timeout | undefined; private readonly stopAt: number | undefined; @@ -114,12 +116,17 @@ export class CheckDeadline { enter = (phase: CheckPhase, detail?: string): void => { if (this.expired) return; const now = Date.now(); + if (this.work?.phase !== phase) this.announce(phase, PHASE_LABELS[phase]); if (this.work) this.spend(this.work.phase, now - this.work.since); this.work = { phase, since: now, detail }; this.spend(phase, 0); this.rearm(); }; + private announce(phase: CheckPhase, text: string): void { + if (phase !== "copies") console.error(`[hyperframes] check: ${text}`); + } + private spend(phase: CheckPhase, ms: number): void { this.spent.set(phase, (this.spent.get(phase) ?? 0) + ms); } @@ -142,6 +149,14 @@ export class CheckDeadline { start = (): void => { if (this.phase !== "waiting") return; this.phase = "started"; + this.heartbeat = setInterval(() => { + if (this.work) { + const seconds = Math.round((Date.now() - this.work.since) / 1000); + const { phase } = this.work; + this.announce(phase, `still ${PHASE_LABELS[phase]} (${seconds} s in this step)`); + } + }, HEARTBEAT_MS); + this.heartbeat.unref(); this.enter("load"); }; @@ -155,6 +170,7 @@ export class CheckDeadline { } private expire(error: Error): void { + clearInterval(this.heartbeat); clearTimeout(this.timer); clearTimeout(this.budgetTimer); this.expired = error; @@ -204,6 +220,7 @@ export class CheckDeadline { async close(): Promise { this.phase = "closed"; + clearInterval(this.heartbeat); clearTimeout(this.timer); clearTimeout(this.budgetTimer); const closes = await Promise.allSettled([...this.browsers].map(closeManagedBrowser)); diff --git a/skills-manifest.json b/skills-manifest.json index 031864454a..1e0f78fac5 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -10,7 +10,7 @@ "files": 78 }, "hyperframes-cli": { - "hash": "2c977e879386734b", + "hash": "af4aa1c5232591dd", "files": 13 }, "hyperframes-registry": { diff --git a/skills/hyperframes-cli/references/lint-validate-inspect.md b/skills/hyperframes-cli/references/lint-validate-inspect.md index ae8ea179c1..07b4fb6dd8 100644 --- a/skills/hyperframes-cli/references/lint-validate-inspect.md +++ b/skills/hyperframes-cli/references/lint-validate-inspect.md @@ -41,7 +41,7 @@ npx hyperframes check --no-contrast # skip the WCAG audit while iterating npx hyperframes check --strict # exit non-zero on warnings too (default: only errors) ``` -One command, one Chrome boot. `check` runs the linter first. A lint error fails the check, but the browser audits still run and report alongside it, unless the error leaves no composition to load (a root with no `data-composition-id`). When the browser never ran (no composition to load, a linter crash, or a browser launch failure), `browserSkipped` is `true` and the `layout`, `motion` and `contrast` sections are empty, not clean. Otherwise it loads the bundled composition once, wires runtime listeners before navigation, and sweeps one seek grid running every audit per sample: +Run it as `npx hyperframes check`, never through `npm run`: a tool timeout's SIGTERM ends npm at once, while `check` goes on and saves its report to the file it names on stderr (`.hyperframes/artifacts/checks/`). One command, one Chrome boot. `check` runs the linter first. A lint error fails the check, but the browser audits still run and report alongside it, unless the error leaves no composition to load (a root with no `data-composition-id`). When the browser never ran (no composition to load, a linter crash, or a browser launch failure), `browserSkipped` is `true` and the `layout`, `motion` and `contrast` sections are empty, not clean. Otherwise it loads the bundled composition once, wires runtime listeners before navigation, and sweeps one seek grid running every audit per sample: - **Runtime**: JavaScript console errors, unhandled exceptions, failed network requests (media-file `ERR_ABORTED` filtered out), HTTP 4xx/5xx. - **Layout**: text extending outside its container or the canvas, text clipped by its own box, held text overlaps and occlusion (with an approximate covered fraction), an opaque element covering the canvas above every other clip for most of the film (`canvas_covered`, naming it), children escaping clipping containers. Text under a transparent `