@hyperframes/lint 0.9.12 → 0.9.13

package/dist/browser.js

@@ -1824,6 +1824,71 @@ function findLinkedClipFindings(ctx) {
   return findings;
 }
 
+// src/rules/audioAttributes.ts
+var AUDIO_ATTRIBUTES = {
+  "data-automation": { list: "lanes", noun: "automation", item: "Lane" },
+  "data-fx-chain": { list: "nodes", noun: "chain", item: "Node" }
+};
+var AUDIO_ATTRIBUTE_VERSION = 1;
+function audioAttributeShapeError(attr, json) {
+  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) {
+  let raw;
+  try {
+    raw = JSON.parse(json);
+  } catch (err) {
+    return `it is not valid JSON (${err.message})`;
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+    return "it is not a JSON object";
+  return raw;
+}
+function entryShapeError(attr, item, i, entry) {
+  if (typeof entry !== "object" || entry === null) return `${item} ${i} is not an object`;
+  const fields = entry;
+  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;
+}
+function findUnreadableAudioAttributeFindings(ctx) {
+  const findings = [];
+  for (const tag of ctx.tags) {
+    for (const attr of Object.keys(AUDIO_ATTRIBUTES)) {
+      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 || void 0,
+        fixHint: `Write it as {"version": ${AUDIO_ATTRIBUTE_VERSION}, "${list}": [...]}, or remove the attribute.`,
+        snippet: truncateSnippet(tag.raw)
+      });
+    }
+  }
+  return findings;
+}
+
 // src/rules/media.ts
 function tweensVolumeInSameCall(script, id) {
   const selector = new RegExp(`#${escapeRegExp(id)}(?![\\w-])`, "g");
@@ -2556,7 +2621,8 @@ var mediaRules = [
   findAudioGroupCarveAttrFindings,
   // audio_group_holds_elements
   findAudioGroupHoldsElementsFindings,
-  findLinkedClipFindings
+  findLinkedClipFindings,
+  findUnreadableAudioAttributeFindings
 ];
 function findVolumeTweenOverridesGainFindings(ctx) {
   const boosted = ctx.tags.filter((tag) => isMediaTag(tag.name)).map((tag) => ({ tag, volume: Number(readAttr(tag.raw, "data-volume") ?? "1") })).filter((entry) => Number.isFinite(entry.volume) && entry.volume !== 1).filter((entry) => !readDecodedAttr(entry.tag.raw, "data-automation")).map((entry) => ({ ...entry, id: readAttr(entry.tag.raw, "id") })).filter((entry) => Boolean(entry.id));

package/dist/index.d.ts

@@ -109,4 +109,11 @@ interface ProjectLintResult {
 declare function collectExternalStyles(projectDir: string, html: string, compSrcPath?: string): NonNullable<HyperframeLinterOptions["externalStyles"]>;
 declare function lintProject(projectDir: string, entryFile?: string, hostOptions?: Pick<HyperframeLinterOptions, "host" | "isSubComposition">): Promise<ProjectLintResult>;
 
-export { type HyperframeLintFinding, type HyperframeLintResult, type HyperframeLintSeverity, type HyperframeLinterOptions, LINT_RULE_COUNT, LINT_RULE_GROUP_COUNTS, type LintTimings, type ProjectLintResult, collectExternalStyles, lintHyperframeHtml, lintMediaUrls, lintProject, shouldBlockRender };
+type AudioAttribute = "data-automation" | "data-fx-chain";
+/**
+ * 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.
+ */
+declare function audioAttributeShapeError(attr: AudioAttribute, json: string): string | null;
+
+export { type AudioAttribute, type HyperframeLintFinding, type HyperframeLintResult, type HyperframeLintSeverity, type HyperframeLinterOptions, LINT_RULE_COUNT, LINT_RULE_GROUP_COUNTS, type LintTimings, type ProjectLintResult, audioAttributeShapeError, collectExternalStyles, lintHyperframeHtml, lintMediaUrls, lintProject, shouldBlockRender };

package/dist/index.js

@@ -1830,6 +1830,71 @@ function findLinkedClipFindings(ctx) {
   return findings;
 }
 
+// src/rules/audioAttributes.ts
+var AUDIO_ATTRIBUTES = {
+  "data-automation": { list: "lanes", noun: "automation", item: "Lane" },
+  "data-fx-chain": { list: "nodes", noun: "chain", item: "Node" }
+};
+var AUDIO_ATTRIBUTE_VERSION = 1;
+function audioAttributeShapeError(attr, json) {
+  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) {
+  let raw;
+  try {
+    raw = JSON.parse(json);
+  } catch (err) {
+    return `it is not valid JSON (${err.message})`;
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+    return "it is not a JSON object";
+  return raw;
+}
+function entryShapeError(attr, item, i, entry) {
+  if (typeof entry !== "object" || entry === null) return `${item} ${i} is not an object`;
+  const fields = entry;
+  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;
+}
+function findUnreadableAudioAttributeFindings(ctx) {
+  const findings = [];
+  for (const tag of ctx.tags) {
+    for (const attr of Object.keys(AUDIO_ATTRIBUTES)) {
+      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 || void 0,
+        fixHint: `Write it as {"version": ${AUDIO_ATTRIBUTE_VERSION}, "${list}": [...]}, or remove the attribute.`,
+        snippet: truncateSnippet(tag.raw)
+      });
+    }
+  }
+  return findings;
+}
+
 // src/rules/media.ts
 function tweensVolumeInSameCall(script, id) {
   const selector = new RegExp(`#${escapeRegExp(id)}(?![\\w-])`, "g");
@@ -2562,7 +2627,8 @@ var mediaRules = [
   findAudioGroupCarveAttrFindings,
   // audio_group_holds_elements
   findAudioGroupHoldsElementsFindings,
-  findLinkedClipFindings
+  findLinkedClipFindings,
+  findUnreadableAudioAttributeFindings
 ];
 function findVolumeTweenOverridesGainFindings(ctx) {
   const boosted = ctx.tags.filter((tag) => isMediaTag(tag.name)).map((tag) => ({ tag, volume: Number(readAttr(tag.raw, "data-volume") ?? "1") })).filter((entry) => Number.isFinite(entry.volume) && entry.volume !== 1).filter((entry) => !readDecodedAttr(entry.tag.raw, "data-automation")).map((entry) => ({ ...entry, id: readAttr(entry.tag.raw, "id") })).filter((entry) => Boolean(entry.id));
@@ -8134,6 +8200,7 @@ function isSnippetFragment(html) {
 export {
   LINT_RULE_COUNT,
   LINT_RULE_GROUP_COUNTS,
+  audioAttributeShapeError,
   collectExternalStyles,
   lintHyperframeHtml,
   lintMediaUrls,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/lint",
-  "version": "0.9.12",
+  "version": "0.9.13",
   "repository": {
     "type": "git",
     "url": "https://github.com/heygen-com/hyperframes",
@@ -35,7 +35,7 @@
     "linkedom": "^0.18.12",
     "postcss": "^8.5.8",
     "postcss-selector-parser": "^7.1.4",
-    "@hyperframes/parsers": "0.9.12"
+    "@hyperframes/parsers": "0.9.13"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",