Skip to content

Commit cd7b738

Browse files
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 <[email protected]> * fix(lint): an empty data-automation or data-fx-chain is ignored, as the mixer does Co-Authored-By: Claude Opus 5.5 <[email protected]> * 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 <[email protected]> * style(lint): format the split audio attribute checks Co-Authored-By: Claude Opus 5.5 <[email protected]> * 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 <[email protected]> --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 0bbc9b2 commit cd7b738

8 files changed

Lines changed: 217 additions & 8 deletions

File tree

‎docs/reference/audio-effects.mdx‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -244,9 +244,10 @@ only one group, so this is the way to put one effect across everything.
244244
chain, group or automation of its own stays on native output.
245245
- An unreadable master chain **fails the whole mix**: the render stops with an
246246
`audio_processing_failed` error under every strictness setting, and exports
247-
nothing. Preview plays dry with no message, and no lint rule checks a chain's
248-
contents, so one typo on the root blocks every export of that composition.
249-
Check a master chain in preview before rendering.
247+
nothing. Preview plays dry with no message. `audio_attribute_unreadable` catches
248+
a chain that is not JSON, has no `"version": 1` or no `nodes` array; an unknown
249+
effect type still only shows up at render. Check a master chain in preview
250+
before rendering.
250251

251252
## Effect registry
252253

@@ -543,13 +544,14 @@ ends exactly at its `data-duration`. That is expected.
543544

544545
## What the linter checks
545546

546-
Almost no static gate covers a mix. Three rules exist:
547+
Almost no static gate covers a mix. Four rules exist:
547548

548549
| Rule | Reports |
549550
| --- | --- |
551+
| `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 |
550552
| `audio_carve_ungrouped_sources` | A carve naming two or more plain clip ids instead of a group |
551553
| `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 |
552554
| `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 |
553555

554-
Nothing validates the chain or the effect lanes at all. What enforces those is
555-
the render. Beyond that, a mix is verified by rendering and listening.
556+
Nothing checks a lane's target or an effect's type and parameters. What enforces
557+
those is the render. Beyond that, a mix is verified by rendering and listening.

‎docs/reference/lint-rules.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -532,6 +532,12 @@ Or keep the element `visibility: hidden` until its draw tween starts.
532532

533533
Source: `packages/lint/src/rules/media.ts`.
534534

535+
### `audio_attribute_unreadable`
536+
537+
**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.
538+
539+
**Fix:** Write it as `{"version": 1, "lanes": [...]}` (automation) or `{"version": 1, "nodes": [...]}` (effect chain), or remove the attribute.
540+
535541
### `audio_carve_ungrouped_sources`
536542

537543
**Warning.** A voiceover carve names its member clips directly instead of carving an `<hf-audio-group>`, so the list silently rots when clips change.
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import { describe, expect, it } from "vitest";
2+
import { audioAttributeShapeError } from "@hyperframes/lint";
3+
import { parseAutomation } from "./audioAutomation";
4+
import { parseAudioFxChain } from "./audioFx";
5+
6+
const PARSERS = { "data-automation": parseAutomation, "data-fx-chain": parseAudioFxChain } as const;
7+
8+
const accepts = (attr: keyof typeof PARSERS, json: string) => {
9+
try {
10+
PARSERS[attr](json);
11+
return true;
12+
} catch {
13+
return false;
14+
}
15+
};
16+
17+
describe("lint's audio attribute envelope matches the renderer's parsers", () => {
18+
it.each([
19+
[
20+
"data-automation",
21+
'{"version": 1, "lanes": [{"target": "volume", "points": [{"t": 0, "v": 1}]}]}',
22+
],
23+
["data-automation", '{"version": 1, "lanes": []}'],
24+
["data-automation", '{"lanes": []}'],
25+
["data-automation", '{"version": 2, "lanes": []}'],
26+
["data-automation", '{"version": "1", "lanes": []}'],
27+
["data-automation", "{version: 1}"],
28+
["data-automation", "null"],
29+
["data-automation", '{"version": 1}'],
30+
["data-automation", '{"version": 1, "lanes": [null]}'],
31+
["data-automation", '{"version": 1, "lanes": [{"target": "volume"}]}'],
32+
["data-automation", '{"version": 1, "lanes": [{"points": []}]}'],
33+
["data-fx-chain", '{"version": 1, "nodes": [{"type": "highpass", "params": {}}]}'],
34+
["data-fx-chain", '{"version": 1, "nodes": []}'],
35+
["data-fx-chain", '{"nodes": []}'],
36+
["data-fx-chain", '{"version": 1}'],
37+
["data-fx-chain", '{"version": 1, "nodes": ["x"]}'],
38+
["data-fx-chain", '{"version": 1, "nodes": [{"id": "n1"}]}'],
39+
] as const)("%s %s: lint flags it exactly when the render refuses it", (attr, json) => {
40+
expect(audioAttributeShapeError(attr, json) === null).toBe(accepts(attr, json));
41+
});
42+
});

‎packages/lint/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ export {
1313
} from "./hyperframeLinter.js";
1414
export { collectExternalStyles, lintProject, shouldBlockRender } from "./project.js";
1515
export type { ProjectLintResult } from "./project.js";
16+
export { audioAttributeShapeError, type AudioAttribute } from "./rules/audioAttributes.js";
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
import { describe, expect, it } from "vitest";
2+
import { lintHyperframeHtml } from "../hyperframeLinter.js";
3+
import { audioAttributeShapeError } from "./audioAttributes.js";
4+
5+
function composition(body: string, rootAttrs = ""): string {
6+
return `
7+
<html><body>
8+
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080"${rootAttrs}>
9+
${body}
10+
</div>
11+
<script>window.__timelines = {};</script>
12+
</body></html>`;
13+
}
14+
15+
async function findings(body: string, rootAttrs = "") {
16+
const result = await lintHyperframeHtml(composition(body, rootAttrs));
17+
return result.findings.filter((f) => f.code === "audio_attribute_unreadable");
18+
}
19+
20+
const LANE = `{"target": "volume", "points": [{"t": 0, "v": 0}, {"t": 1, "v": 0.3}]}`;
21+
const CUE = `id="bed" src="bed.mp3" data-start="0" data-duration="4" data-track-index="2"`;
22+
23+
describe("audio_attribute_unreadable", () => {
24+
it("flags a volume lane written without a version, which the render refuses", async () => {
25+
const found = await findings(`<audio ${CUE} data-automation='{"lanes": [${LANE}]}'></audio>`);
26+
expect(found).toHaveLength(1);
27+
expect(found[0]).toMatchObject({ severity: "error", elementId: "bed" });
28+
expect(found[0]!.message).toContain("unsupported automation version: undefined");
29+
expect(found[0]!.fixHint).toContain('{"version": 1, "lanes": [...]}');
30+
});
31+
32+
it("ignores an empty or valueless attribute, as the mixer does, but not a blank one it would parse", async () => {
33+
for (const attr of ["data-automation", "data-fx-chain"]) {
34+
expect(await findings(`<audio ${CUE} ${attr}=""></audio>`)).toEqual([]);
35+
expect(await findings(`<audio ${CUE} ${attr}></audio>`)).toEqual([]);
36+
expect(await findings(`<audio ${CUE} ${attr}=" "></audio>`)).toHaveLength(1);
37+
}
38+
});
39+
40+
it("passes a well-formed lane and chain", async () => {
41+
const chain = `{"version": 1, "nodes": [{"type": "highpass", "id": "n1", "params": {"frequency": 70}}]}`;
42+
const body = `<audio ${CUE} data-automation='{"version": 1, "lanes": [${LANE}]}' data-fx-chain='${chain}'></audio>`;
43+
expect(await findings(body)).toEqual([]);
44+
});
45+
46+
it("reads an entity-encoded chain and names the master bus when the root carries it", async () => {
47+
const found = await findings(
48+
"",
49+
' data-fx-chain="{&quot;version&quot;: 2, &quot;nodes&quot;: []}"',
50+
);
51+
expect(found).toHaveLength(1);
52+
expect(found[0]!.message).toBe(
53+
"#root has a `data-fx-chain` the render cannot read: unsupported chain version: 2. The render fails on it, locally and in the cloud.",
54+
);
55+
});
56+
57+
it.each([
58+
["data-automation", "{version: 1}", /^it is not valid JSON/],
59+
["data-automation", "[]", /^it is not a JSON object$/],
60+
["data-automation", '{"version": 1}', /^it is missing a `lanes` array$/],
61+
[
62+
"data-automation",
63+
'{"version": 1, "lanes": [{"target": "volume"}]}',
64+
/^Lane 0 is missing a `points` array$/,
65+
],
66+
["data-automation", '{"version": 1, "lanes": [{"points": []}]}', /^Lane 0 has no `target`$/],
67+
["data-fx-chain", '{"version": 1, "nodes": [7]}', /^Node 0 is not an object$/],
68+
["data-fx-chain", '{"version": 1, "nodes": [{"id": "n1"}]}', /^Node 0 has no effect `type`$/],
69+
] as const)("%s %s is refused", (attr, json, reason) => {
70+
expect(audioAttributeShapeError(attr, json)).toMatch(reason);
71+
});
72+
});
Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
import type { LintContext, HyperframeLintFinding } from "../context";
2+
import { readAttr, readDecodedAttr, truncateSnippet } from "../utils";
3+
4+
export type AudioAttribute = "data-automation" | "data-fx-chain";
5+
6+
// The renderer parses these in @hyperframes/core, which depends on this package, so the envelope is restated
7+
// here; core's audioAttributeLintParity test fails if the two drift apart.
8+
const AUDIO_ATTRIBUTES: Record<AudioAttribute, { list: string; noun: string; item: string }> = {
9+
"data-automation": { list: "lanes", noun: "automation", item: "Lane" },
10+
"data-fx-chain": { list: "nodes", noun: "chain", item: "Node" },
11+
};
12+
const AUDIO_ATTRIBUTE_VERSION = 1;
13+
14+
/**
15+
* Why the renderer would refuse an audio attribute's value before reading any lane or effect, or null when the
16+
* envelope reads. Lane targets and effect types are left to the render: they need core's effect registry.
17+
*/
18+
export function audioAttributeShapeError(attr: AudioAttribute, json: string): string | null {
19+
const { list, noun, item } = AUDIO_ATTRIBUTES[attr];
20+
const parsed = parseEnvelope(json);
21+
if (typeof parsed === "string") return parsed;
22+
if (parsed.version !== AUDIO_ATTRIBUTE_VERSION) {
23+
return `unsupported ${noun} version: ${String(parsed.version)}`;
24+
}
25+
const entries = parsed[list];
26+
if (!Array.isArray(entries)) return `it is missing a \`${list}\` array`;
27+
for (const [i, entry] of entries.entries()) {
28+
const reason = entryShapeError(attr, item, i, entry);
29+
if (reason) return reason;
30+
}
31+
return null;
32+
}
33+
34+
function parseEnvelope(json: string): ({ version?: unknown } & Record<string, unknown>) | string {
35+
let raw: unknown;
36+
try {
37+
raw = JSON.parse(json);
38+
} catch (err) {
39+
return `it is not valid JSON (${(err as Error).message})`;
40+
}
41+
if (typeof raw !== "object" || raw === null || Array.isArray(raw))
42+
return "it is not a JSON object";
43+
return raw as { version?: unknown } & Record<string, unknown>;
44+
}
45+
46+
function entryShapeError(
47+
attr: AudioAttribute,
48+
item: string,
49+
i: number,
50+
entry: unknown,
51+
): string | null {
52+
if (typeof entry !== "object" || entry === null) return `${item} ${i} is not an object`;
53+
const fields = entry as Record<string, unknown>;
54+
if (attr === "data-fx-chain") {
55+
return typeof fields.type === "string" ? null : `Node ${i} has no effect \`type\``;
56+
}
57+
if (typeof fields.target !== "string") return `Lane ${i} has no \`target\``;
58+
if (!Array.isArray(fields.points)) return `Lane ${i} is missing a \`points\` array`;
59+
return null;
60+
}
61+
62+
/** An audio attribute the renderer cannot parse fails the whole mix, locally and in the cloud. */
63+
export function findUnreadableAudioAttributeFindings(ctx: LintContext): HyperframeLintFinding[] {
64+
const findings: HyperframeLintFinding[] = [];
65+
for (const tag of ctx.tags) {
66+
for (const attr of Object.keys(AUDIO_ATTRIBUTES) as AudioAttribute[]) {
67+
const value = readDecodedAttr(tag.raw, attr);
68+
if (value === null || value === "") continue;
69+
const reason = audioAttributeShapeError(attr, value);
70+
if (!reason) continue;
71+
const id = readAttr(tag.raw, "id");
72+
const { list } = AUDIO_ATTRIBUTES[attr];
73+
findings.push({
74+
code: "audio_attribute_unreadable",
75+
severity: "error",
76+
message: `${id ? `#${id}` : `<${tag.name}>`} has a \`${attr}\` the render cannot read: ${reason}. The render fails on it, locally and in the cloud.`,
77+
elementId: id || undefined,
78+
fixHint: `Write it as {"version": ${AUDIO_ATTRIBUTE_VERSION}, "${list}": [...]}, or remove the attribute.`,
79+
snippet: truncateSnippet(tag.raw),
80+
});
81+
}
82+
}
83+
return findings;
84+
}

‎packages/lint/src/rules/media.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import {
1919
import { extractMediaSrcMutations } from "@hyperframes/parsers/composition";
2020
import { parseHTML } from "linkedom";
2121
import { findLinkedClipFindings } from "./linkedClips";
22+
import { findUnreadableAudioAttributeFindings } from "./audioAttributes";
2223

2324
/**
2425
* 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[]> =
886887
// audio_group_holds_elements
887888
findAudioGroupHoldsElementsFindings,
888889
findLinkedClipFindings,
890+
findUnreadableAudioAttributeFindings,
889891
];
890892

891893
/**

‎scripts/package-size-budgets.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
},
66
"@hyperframes/cli": {
77
"packed": 7902966,
8-
"unpacked": 23722874
8+
"unpacked": 25159107
99
},
1010
"@hyperframes/core": {
1111
"packed": 1762752,
@@ -25,7 +25,7 @@
2525
},
2626
"@hyperframes/lint": {
2727
"packed": 179338,
28-
"unpacked": 695173
28+
"unpacked": 737342
2929
},
3030
"@hyperframes/parsers": {
3131
"packed": 203731,

0 commit comments

Comments
 (0)