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:
WaterrrForever
2026-11-04 16:59:04 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 0bbc9b2943
commit cd7b7383cb
8 changed files with 217 additions and 8 deletions
+8 -6
View File
@@ -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.
+6
View File
@@ -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));
});
});
+1
View File
@@ -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="{&quot;version&quot;: 2, &quot;nodes&quot;: []}"',
);
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;
}
+2
View File
@@ -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,
];
/**
+2 -2
View File
@@ -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,