mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
fix(lint): flag a data-automation or data-fx-chain the render cannot read (#7169)
* fix(lint): flag a data-automation or data-fx-chain the render cannot read A cue whose automation lane has no "version": 1 passed `hyperframes check` and only failed at render: locally with "Unsupported automation version: undefined", in the cloud with no cause at all. The new error `audio_attribute_unreadable` reads each data-automation and data-fx-chain envelope (JSON object, version 1, a lanes or nodes array, a target and points per lane, a type per node) and names the element. Lint cannot import the renderer's parsers from @hyperframes/core, which depends on it, so core gains a parity test that fails if the two disagree on any envelope case. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(lint): an empty data-automation or data-fx-chain is ignored, as the mixer does Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(lint): split the audio attribute shape check and raise the CLI size budget audioAttributeShapeError splits its envelope and per-entry checks to stay under the cognitive-complexity gate, and media.ts drops the added rule label comment. The CLI's unpacked size was already 0.99% over its budget on main (23,958,7xx of 23,722,874); this rule adds about 2.4 KB of bundled code, which crosses the 1% tolerance. The budget moves to 5% above the measured 23,961,054, as the budget file's own headroom rule sets it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * style(lint): format the split audio attribute checks Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(ci): raise the lint package's unpacked size budget for the audio attribute rule The rule and its envelope checks take @hyperframes/lint's unpacked size to 702,230, just over 1% past its 695,173 budget. The budget moves to 5% above the measured size, as the budget file's headroom rule sets it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
0bbc9b2943
commit
cd7b7383cb
@@ -244,9 +244,10 @@ only one group, so this is the way to put one effect across everything.
|
||||
chain, group or automation of its own stays on native output.
|
||||
- An unreadable master chain **fails the whole mix**: the render stops with an
|
||||
`audio_processing_failed` error under every strictness setting, and exports
|
||||
nothing. Preview plays dry with no message, and no lint rule checks a chain's
|
||||
contents, so one typo on the root blocks every export of that composition.
|
||||
Check a master chain in preview before rendering.
|
||||
nothing. Preview plays dry with no message. `audio_attribute_unreadable` catches
|
||||
a chain that is not JSON, has no `"version": 1` or no `nodes` array; an unknown
|
||||
effect type still only shows up at render. Check a master chain in preview
|
||||
before rendering.
|
||||
|
||||
## Effect registry
|
||||
|
||||
@@ -543,13 +544,14 @@ ends exactly at its `data-duration`. That is expected.
|
||||
|
||||
## What the linter checks
|
||||
|
||||
Almost no static gate covers a mix. Three rules exist:
|
||||
Almost no static gate covers a mix. Four rules exist:
|
||||
|
||||
| Rule | Reports |
|
||||
| --- | --- |
|
||||
| `audio_attribute_unreadable` | A `data-automation` or `data-fx-chain` the render cannot parse: not JSON, no `"version": 1`, no `lanes` / `nodes` array, a lane without `target` or `points`, a node without `type`. The render fails on it, locally and in the cloud |
|
||||
| `audio_carve_ungrouped_sources` | A carve naming two or more plain clip ids instead of a group |
|
||||
| `audio_volume_double_automation` | A `volume` lane on a track that also has a GSAP tween on `volume` — the lane wins, the tween is ignored |
|
||||
| `audio_volume_tween_overrides_gain` | An authored `data-volume` on a track whose `volume` is tweened — the tween's values are absolute and replace that gain rather than scaling it |
|
||||
|
||||
Nothing validates the chain or the effect lanes at all. What enforces those is
|
||||
the render. Beyond that, a mix is verified by rendering and listening.
|
||||
Nothing checks a lane's target or an effect's type and parameters. What enforces
|
||||
those is the render. Beyond that, a mix is verified by rendering and listening.
|
||||
|
||||
@@ -532,6 +532,12 @@ Or keep the element `visibility: hidden` until its draw tween starts.
|
||||
|
||||
Source: `packages/lint/src/rules/media.ts`.
|
||||
|
||||
### `audio_attribute_unreadable`
|
||||
|
||||
**Error.** A `data-automation` or `data-fx-chain` is not one the render can parse: not JSON, no `"version": 1`, no `lanes` / `nodes` array, a lane without `target` or `points`, or a node without `type`. The audio mix fails on it, locally and in the cloud.
|
||||
|
||||
**Fix:** Write it as `{"version": 1, "lanes": [...]}` (automation) or `{"version": 1, "nodes": [...]}` (effect chain), or remove the attribute.
|
||||
|
||||
### `audio_carve_ungrouped_sources`
|
||||
|
||||
**Warning.** A voiceover carve names its member clips directly instead of carving an `<hf-audio-group>`, so the list silently rots when clips change.
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { audioAttributeShapeError } from "@hyperframes/lint";
|
||||
import { parseAutomation } from "./audioAutomation";
|
||||
import { parseAudioFxChain } from "./audioFx";
|
||||
|
||||
const PARSERS = { "data-automation": parseAutomation, "data-fx-chain": parseAudioFxChain } as const;
|
||||
|
||||
const accepts = (attr: keyof typeof PARSERS, json: string) => {
|
||||
try {
|
||||
PARSERS[attr](json);
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
};
|
||||
|
||||
describe("lint's audio attribute envelope matches the renderer's parsers", () => {
|
||||
it.each([
|
||||
[
|
||||
"data-automation",
|
||||
'{"version": 1, "lanes": [{"target": "volume", "points": [{"t": 0, "v": 1}]}]}',
|
||||
],
|
||||
["data-automation", '{"version": 1, "lanes": []}'],
|
||||
["data-automation", '{"lanes": []}'],
|
||||
["data-automation", '{"version": 2, "lanes": []}'],
|
||||
["data-automation", '{"version": "1", "lanes": []}'],
|
||||
["data-automation", "{version: 1}"],
|
||||
["data-automation", "null"],
|
||||
["data-automation", '{"version": 1}'],
|
||||
["data-automation", '{"version": 1, "lanes": [null]}'],
|
||||
["data-automation", '{"version": 1, "lanes": [{"target": "volume"}]}'],
|
||||
["data-automation", '{"version": 1, "lanes": [{"points": []}]}'],
|
||||
["data-fx-chain", '{"version": 1, "nodes": [{"type": "highpass", "params": {}}]}'],
|
||||
["data-fx-chain", '{"version": 1, "nodes": []}'],
|
||||
["data-fx-chain", '{"nodes": []}'],
|
||||
["data-fx-chain", '{"version": 1}'],
|
||||
["data-fx-chain", '{"version": 1, "nodes": ["x"]}'],
|
||||
["data-fx-chain", '{"version": 1, "nodes": [{"id": "n1"}]}'],
|
||||
] as const)("%s %s: lint flags it exactly when the render refuses it", (attr, json) => {
|
||||
expect(audioAttributeShapeError(attr, json) === null).toBe(accepts(attr, json));
|
||||
});
|
||||
});
|
||||
@@ -13,3 +13,4 @@ export {
|
||||
} from "./hyperframeLinter.js";
|
||||
export { collectExternalStyles, lintProject, shouldBlockRender } from "./project.js";
|
||||
export type { ProjectLintResult } from "./project.js";
|
||||
export { audioAttributeShapeError, type AudioAttribute } from "./rules/audioAttributes.js";
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { lintHyperframeHtml } from "../hyperframeLinter.js";
|
||||
import { audioAttributeShapeError } from "./audioAttributes.js";
|
||||
|
||||
function composition(body: string, rootAttrs = ""): string {
|
||||
return `
|
||||
<html><body>
|
||||
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080"${rootAttrs}>
|
||||
${body}
|
||||
</div>
|
||||
<script>window.__timelines = {};</script>
|
||||
</body></html>`;
|
||||
}
|
||||
|
||||
async function findings(body: string, rootAttrs = "") {
|
||||
const result = await lintHyperframeHtml(composition(body, rootAttrs));
|
||||
return result.findings.filter((f) => f.code === "audio_attribute_unreadable");
|
||||
}
|
||||
|
||||
const LANE = `{"target": "volume", "points": [{"t": 0, "v": 0}, {"t": 1, "v": 0.3}]}`;
|
||||
const CUE = `id="bed" src="bed.mp3" data-start="0" data-duration="4" data-track-index="2"`;
|
||||
|
||||
describe("audio_attribute_unreadable", () => {
|
||||
it("flags a volume lane written without a version, which the render refuses", async () => {
|
||||
const found = await findings(`<audio ${CUE} data-automation='{"lanes": [${LANE}]}'></audio>`);
|
||||
expect(found).toHaveLength(1);
|
||||
expect(found[0]).toMatchObject({ severity: "error", elementId: "bed" });
|
||||
expect(found[0]!.message).toContain("unsupported automation version: undefined");
|
||||
expect(found[0]!.fixHint).toContain('{"version": 1, "lanes": [...]}');
|
||||
});
|
||||
|
||||
it("ignores an empty or valueless attribute, as the mixer does, but not a blank one it would parse", async () => {
|
||||
for (const attr of ["data-automation", "data-fx-chain"]) {
|
||||
expect(await findings(`<audio ${CUE} ${attr}=""></audio>`)).toEqual([]);
|
||||
expect(await findings(`<audio ${CUE} ${attr}></audio>`)).toEqual([]);
|
||||
expect(await findings(`<audio ${CUE} ${attr}=" "></audio>`)).toHaveLength(1);
|
||||
}
|
||||
});
|
||||
|
||||
it("passes a well-formed lane and chain", async () => {
|
||||
const chain = `{"version": 1, "nodes": [{"type": "highpass", "id": "n1", "params": {"frequency": 70}}]}`;
|
||||
const body = `<audio ${CUE} data-automation='{"version": 1, "lanes": [${LANE}]}' data-fx-chain='${chain}'></audio>`;
|
||||
expect(await findings(body)).toEqual([]);
|
||||
});
|
||||
|
||||
it("reads an entity-encoded chain and names the master bus when the root carries it", async () => {
|
||||
const found = await findings(
|
||||
"",
|
||||
' data-fx-chain="{"version": 2, "nodes": []}"',
|
||||
);
|
||||
expect(found).toHaveLength(1);
|
||||
expect(found[0]!.message).toBe(
|
||||
"#root has a `data-fx-chain` the render cannot read: unsupported chain version: 2. The render fails on it, locally and in the cloud.",
|
||||
);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["data-automation", "{version: 1}", /^it is not valid JSON/],
|
||||
["data-automation", "[]", /^it is not a JSON object$/],
|
||||
["data-automation", '{"version": 1}', /^it is missing a `lanes` array$/],
|
||||
[
|
||||
"data-automation",
|
||||
'{"version": 1, "lanes": [{"target": "volume"}]}',
|
||||
/^Lane 0 is missing a `points` array$/,
|
||||
],
|
||||
["data-automation", '{"version": 1, "lanes": [{"points": []}]}', /^Lane 0 has no `target`$/],
|
||||
["data-fx-chain", '{"version": 1, "nodes": [7]}', /^Node 0 is not an object$/],
|
||||
["data-fx-chain", '{"version": 1, "nodes": [{"id": "n1"}]}', /^Node 0 has no effect `type`$/],
|
||||
] as const)("%s %s is refused", (attr, json, reason) => {
|
||||
expect(audioAttributeShapeError(attr, json)).toMatch(reason);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,84 @@
|
||||
import type { LintContext, HyperframeLintFinding } from "../context";
|
||||
import { readAttr, readDecodedAttr, truncateSnippet } from "../utils";
|
||||
|
||||
export type AudioAttribute = "data-automation" | "data-fx-chain";
|
||||
|
||||
// The renderer parses these in @hyperframes/core, which depends on this package, so the envelope is restated
|
||||
// here; core's audioAttributeLintParity test fails if the two drift apart.
|
||||
const AUDIO_ATTRIBUTES: Record<AudioAttribute, { list: string; noun: string; item: string }> = {
|
||||
"data-automation": { list: "lanes", noun: "automation", item: "Lane" },
|
||||
"data-fx-chain": { list: "nodes", noun: "chain", item: "Node" },
|
||||
};
|
||||
const AUDIO_ATTRIBUTE_VERSION = 1;
|
||||
|
||||
/**
|
||||
* Why the renderer would refuse an audio attribute's value before reading any lane or effect, or null when the
|
||||
* envelope reads. Lane targets and effect types are left to the render: they need core's effect registry.
|
||||
*/
|
||||
export function audioAttributeShapeError(attr: AudioAttribute, json: string): string | null {
|
||||
const { list, noun, item } = AUDIO_ATTRIBUTES[attr];
|
||||
const parsed = parseEnvelope(json);
|
||||
if (typeof parsed === "string") return parsed;
|
||||
if (parsed.version !== AUDIO_ATTRIBUTE_VERSION) {
|
||||
return `unsupported ${noun} version: ${String(parsed.version)}`;
|
||||
}
|
||||
const entries = parsed[list];
|
||||
if (!Array.isArray(entries)) return `it is missing a \`${list}\` array`;
|
||||
for (const [i, entry] of entries.entries()) {
|
||||
const reason = entryShapeError(attr, item, i, entry);
|
||||
if (reason) return reason;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function parseEnvelope(json: string): ({ version?: unknown } & Record<string, unknown>) | string {
|
||||
let raw: unknown;
|
||||
try {
|
||||
raw = JSON.parse(json);
|
||||
} catch (err) {
|
||||
return `it is not valid JSON (${(err as Error).message})`;
|
||||
}
|
||||
if (typeof raw !== "object" || raw === null || Array.isArray(raw))
|
||||
return "it is not a JSON object";
|
||||
return raw as { version?: unknown } & Record<string, unknown>;
|
||||
}
|
||||
|
||||
function entryShapeError(
|
||||
attr: AudioAttribute,
|
||||
item: string,
|
||||
i: number,
|
||||
entry: unknown,
|
||||
): string | null {
|
||||
if (typeof entry !== "object" || entry === null) return `${item} ${i} is not an object`;
|
||||
const fields = entry as Record<string, unknown>;
|
||||
if (attr === "data-fx-chain") {
|
||||
return typeof fields.type === "string" ? null : `Node ${i} has no effect \`type\``;
|
||||
}
|
||||
if (typeof fields.target !== "string") return `Lane ${i} has no \`target\``;
|
||||
if (!Array.isArray(fields.points)) return `Lane ${i} is missing a \`points\` array`;
|
||||
return null;
|
||||
}
|
||||
|
||||
/** An audio attribute the renderer cannot parse fails the whole mix, locally and in the cloud. */
|
||||
export function findUnreadableAudioAttributeFindings(ctx: LintContext): HyperframeLintFinding[] {
|
||||
const findings: HyperframeLintFinding[] = [];
|
||||
for (const tag of ctx.tags) {
|
||||
for (const attr of Object.keys(AUDIO_ATTRIBUTES) as AudioAttribute[]) {
|
||||
const value = readDecodedAttr(tag.raw, attr);
|
||||
if (value === null || value === "") continue;
|
||||
const reason = audioAttributeShapeError(attr, value);
|
||||
if (!reason) continue;
|
||||
const id = readAttr(tag.raw, "id");
|
||||
const { list } = AUDIO_ATTRIBUTES[attr];
|
||||
findings.push({
|
||||
code: "audio_attribute_unreadable",
|
||||
severity: "error",
|
||||
message: `${id ? `#${id}` : `<${tag.name}>`} has a \`${attr}\` the render cannot read: ${reason}. The render fails on it, locally and in the cloud.`,
|
||||
elementId: id || undefined,
|
||||
fixHint: `Write it as {"version": ${AUDIO_ATTRIBUTE_VERSION}, "${list}": [...]}, or remove the attribute.`,
|
||||
snippet: truncateSnippet(tag.raw),
|
||||
});
|
||||
}
|
||||
}
|
||||
return findings;
|
||||
}
|
||||
@@ -19,6 +19,7 @@ import {
|
||||
import { extractMediaSrcMutations } from "@hyperframes/parsers/composition";
|
||||
import { parseHTML } from "linkedom";
|
||||
import { findLinkedClipFindings } from "./linkedClips";
|
||||
import { findUnreadableAudioAttributeFindings } from "./audioAttributes";
|
||||
|
||||
/**
|
||||
* Does the GSAP call that names `#id` also set `volume` in the same call?
|
||||
@@ -886,6 +887,7 @@ export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> =
|
||||
// audio_group_holds_elements
|
||||
findAudioGroupHoldsElementsFindings,
|
||||
findLinkedClipFindings,
|
||||
findUnreadableAudioAttributeFindings,
|
||||
];
|
||||
|
||||
/**
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
},
|
||||
"@hyperframes/cli": {
|
||||
"packed": 7902966,
|
||||
"unpacked": 23722874
|
||||
"unpacked": 25159107
|
||||
},
|
||||
"@hyperframes/core": {
|
||||
"packed": 1762752,
|
||||
@@ -25,7 +25,7 @@
|
||||
},
|
||||
"@hyperframes/lint": {
|
||||
"packed": 179338,
|
||||
"unpacked": 695173
|
||||
"unpacked": 737342
|
||||
},
|
||||
"@hyperframes/parsers": {
|
||||
"packed": 203731,
|
||||
|
||||
Reference in New Issue
Block a user