diff --git a/docs/reference/audio-effects.mdx b/docs/reference/audio-effects.mdx index b1e9ecc2de..05307c2850 100644 --- a/docs/reference/audio-effects.mdx +++ b/docs/reference/audio-effects.mdx @@ -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. diff --git a/docs/reference/lint-rules.mdx b/docs/reference/lint-rules.mdx index 896a217267..4a2506b359 100644 --- a/docs/reference/lint-rules.mdx +++ b/docs/reference/lint-rules.mdx @@ -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 ``, so the list silently rots when clips change. diff --git a/packages/core/src/audioAttributeLintParity.test.ts b/packages/core/src/audioAttributeLintParity.test.ts new file mode 100644 index 0000000000..0bd07a0f9f --- /dev/null +++ b/packages/core/src/audioAttributeLintParity.test.ts @@ -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)); + }); +}); diff --git a/packages/lint/src/index.ts b/packages/lint/src/index.ts index 060cbf1a92..14633b0819 100644 --- a/packages/lint/src/index.ts +++ b/packages/lint/src/index.ts @@ -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"; diff --git a/packages/lint/src/rules/audioAttributes.test.ts b/packages/lint/src/rules/audioAttributes.test.ts new file mode 100644 index 0000000000..ecf9b84c6f --- /dev/null +++ b/packages/lint/src/rules/audioAttributes.test.ts @@ -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 ` + +
+ ${body} +
+ +`; +} + +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(``); + 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(``)).toEqual([]); + expect(await findings(``)).toEqual([]); + expect(await findings(``)).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 = ``; + 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); + }); +}); diff --git a/packages/lint/src/rules/audioAttributes.ts b/packages/lint/src/rules/audioAttributes.ts new file mode 100644 index 0000000000..c799a7df1a --- /dev/null +++ b/packages/lint/src/rules/audioAttributes.ts @@ -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 = { + "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 { + 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; +} + +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; + 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; +} diff --git a/packages/lint/src/rules/media.ts b/packages/lint/src/rules/media.ts index 9869d7ef4b..ecb3c4f44d 100644 --- a/packages/lint/src/rules/media.ts +++ b/packages/lint/src/rules/media.ts @@ -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, ]; /** diff --git a/scripts/package-size-budgets.json b/scripts/package-size-budgets.json index 42c67e9ea9..c11b4c855d 100644 --- a/scripts/package-size-budgets.json +++ b/scripts/package-size-budgets.json @@ -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,