ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-03 04:38:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix: validate CLI smoke paths and warn on oversized compositions

Browse Source
This commit is contained in:
Miguel Ángel
2026-04-28 10:57:50 -04:00
parent 8e5593b6ba
commit 9c7983211a
5 changed files with 248 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/cli/scripts/build-copy.mjs
+5
View File
@@ -82,6 +82,11 @@ async function main() {
cpSync(layoutAuditScript, join(DIST, "commands", "layout-audit.browser.js"));
}
const contrastAuditScript = join(CLI_ROOT, "src", "commands", "contrast-audit.browser.js");
if (existsSync(contrastAuditScript)) {
cpSync(contrastAuditScript, join(DIST, "commands", "contrast-audit.browser.js"));
}
copyMdFiles(join(CLI_ROOT, "src", "docs"), join(DIST, "docs"));
console.log("[build-copy] done");
packages/cli/src/commands/validate.ts
+14 -5
View File
@@ -27,10 +27,6 @@ interface ContrastEntry {
bg: string;
}
// esbuild's text loader inlines this at build time — no runtime file read.
// @ts-expect-error — .browser.js files use esbuild text loader, not TS module resolution
import CONTRAST_AUDIT_SCRIPT from "./contrast-audit.browser.js";
const CONTRAST_SAMPLES = 5;
const SEEK_SETTLE_MS = 150;
@@ -64,7 +60,7 @@ async function runContrastAudit(page: import("puppeteer-core").Page): Promise<Co
const duration = await getCompositionDuration(page);
if (duration <= 0) return [];
await page.addScriptTag({ content: CONTRAST_AUDIT_SCRIPT });
await page.addScriptTag({ content: loadContrastAuditScript() });
const results: ContrastEntry[] = [];
for (let i = 0; i < CONTRAST_SAMPLES; i++) {
@@ -86,6 +82,19 @@ async function runContrastAudit(page: import("puppeteer-core").Page): Promise<Co
return results;
}
function loadContrastAuditScript(): string {
const candidates = [
join(__dirname, "contrast-audit.browser.js"),
join(__dirname, "commands", "contrast-audit.browser.js"),
];
for (const candidate of candidates) {
if (existsSync(candidate)) return readFileSync(candidate, "utf-8");
}
throw new Error("Missing contrast audit browser script");
}
async function validateInBrowser(
projectDir: string,
opts: { timeout?: number; contrast?: boolean },
packages/core/src/lint/rules/composition.test.ts
+103
View File
@@ -2,6 +2,109 @@ import { describe, it, expect } from "vitest";
import { lintHyperframeHtml } from "../hyperframeLinter.js";
describe("composition rules", () => {
describe("subcomposition guidance", () => {
it("warns when a composition file is over 300 lines", () => {
const html = Array.from({ length: 301 }, (_, i) =>
i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
).join("\n");
const result = lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "composition_file_too_large");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("warning");
});
it("does not warn when a composition file is exactly 300 lines", () => {
const html = Array.from({ length: 300 }, (_, i) =>
i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
).join("\n");
const result = lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "composition_file_too_large");
expect(finding).toBeUndefined();
});
it("warns when more than 3 timed elements share the same track", () => {
const html = `<!DOCTYPE html>
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0">
<div class="clip" data-start="0" data-duration="1" data-track-index="0">A</div>
<div class="clip" data-start="1" data-duration="1" data-track-index="0">B</div>
<div class="clip" data-start="2" data-duration="1" data-track-index="0">C</div>
<div class="clip" data-start="3" data-duration="1" data-track-index="0">D</div>
</div>
<script>
window.__timelines = window.__timelines || {};
window.__timelines["c1"] = gsap.timeline({ paused: true });
</script>
</body></html>`;
const result = lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("warning");
expect(finding?.message).toContain("Track 0 has 4 timed elements");
});
it("does not warn when 3 timed elements share the same track", () => {
const html = `<!DOCTYPE html>
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0">
<div class="clip" data-start="0" data-duration="1" data-track-index="0">A</div>
<div class="clip" data-start="1" data-duration="1" data-track-index="0">B</div>
<div class="clip" data-start="2" data-duration="1" data-track-index="0">C</div>
</div>
<script>
window.__timelines = window.__timelines || {};
window.__timelines["c1"] = gsap.timeline({ paused: true });
</script>
</body></html>`;
const result = lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
expect(finding).toBeUndefined();
});
it("does not warn when timed elements are split across tracks", () => {
const html = `<!DOCTYPE html>
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0">
<div class="clip" data-start="0" data-duration="1" data-track-index="0">A</div>
<div class="clip" data-start="1" data-duration="1" data-track-index="0">B</div>
<div class="clip" data-start="2" data-duration="1" data-track-index="1">C</div>
<div class="clip" data-start="3" data-duration="1" data-track-index="1">D</div>
</div>
<script>
window.__timelines = window.__timelines || {};
window.__timelines["c1"] = gsap.timeline({ paused: true });
</script>
</body></html>`;
const result = lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
expect(finding).toBeUndefined();
});
it("does not count the root composition element as a timed track element", () => {
const html = `<!DOCTYPE html>
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0" data-track-index="0">
<div class="clip" data-start="0" data-duration="1" data-track-index="0">A</div>
<div class="clip" data-start="1" data-duration="1" data-track-index="0">B</div>
<div class="clip" data-start="2" data-duration="1" data-track-index="0">C</div>
</div>
<script>
window.__timelines = window.__timelines || {};
window.__timelines["c1"] = gsap.timeline({ paused: true });
</script>
</body></html>`;
const result = lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
expect(finding).toBeUndefined();
});
});
it("reports info for composition with external CDN script dependency", () => {
const html = `<template id="rockets-template">
<div data-composition-id="rockets" data-width="1920" data-height="1080">
packages/core/src/lint/rules/composition.ts
+47
View File
@@ -1,7 +1,54 @@
import type { LintContext, HyperframeLintFinding } from "../context";
import { readAttr, truncateSnippet } from "../utils";
const MAX_COMPOSITION_LINES = 300;
const MAX_TIMED_ELEMENTS_PER_TRACK = 3;
export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
// composition_file_too_large
({ rawSource }) => {
const lineCount = rawSource.split(/\r\n|\r|\n/).length;
if (lineCount <= MAX_COMPOSITION_LINES) return [];
return [
{
code: "composition_file_too_large",
severity: "warning",
message: `This composition file has ${lineCount} lines. Large single-file compositions are hard for agents to inspect and revise reliably.`,
fixHint:
"Split coherent scenes or layers into smaller .html files under compositions/, then mount them from the parent with data-composition-src so each piece can be validated independently.",
},
];
},
// timeline_track_too_dense
({ tags }) => {
const trackCounts = new Map<string, number>();
for (const tag of tags) {
if (readAttr(tag.raw, "data-composition-id")) continue;
const startStr = readAttr(tag.raw, "data-start");
const trackStr = readAttr(tag.raw, "data-track-index");
if (!startStr || !trackStr) continue;
trackCounts.set(trackStr, (trackCounts.get(trackStr) ?? 0) + 1);
}
const findings: HyperframeLintFinding[] = [];
for (const [track, count] of trackCounts) {
if (count <= MAX_TIMED_ELEMENTS_PER_TRACK) continue;
findings.push({
code: "timeline_track_too_dense",
severity: "warning",
message: `Track ${track} has ${count} timed elements in this file. Dense tracks usually mean too much scene structure is packed into one composition.`,
fixHint:
"Move coherent scene groups into separate .html files under compositions/ and mount them from the parent with data-composition-src so the timeline stays easier to inspect, revise, and validate.",
});
}
return findings;
},
// timed_element_missing_visibility_hidden
({ tags }) => {
const findings: HyperframeLintFinding[] = [];