@hyperframes/lint 0.8.49 → 0.8.51

package/dist/index.d.ts

@@ -45,6 +45,8 @@ type HyperframeLinterOptions = {
      * render time — the font will silently fall back to whatever the OS provides.
      */
     distributed?: boolean;
+    /** Who is running the lint: Studio raises the structure rules to errors, the CLI keeps them warnings. */
+    host?: "studio" | "cli";
 };
 
 /**
@@ -90,6 +92,6 @@ interface ProjectLintResult {
     totalWarnings: number;
     totalInfos: number;
 }
-declare function lintProject(projectDir: string, entryFile?: string): Promise<ProjectLintResult>;
+declare function lintProject(projectDir: string, entryFile?: string, hostOptions?: Pick<HyperframeLinterOptions, "host">): Promise<ProjectLintResult>;
 
 export { type HyperframeLintFinding, type HyperframeLintResult, type HyperframeLintSeverity, type HyperframeLinterOptions, LINT_RULE_COUNT, LINT_RULE_GROUP_COUNTS, type LintTimings, type ProjectLintResult, lintHyperframeHtml, lintMediaUrls, lintProject, shouldBlockRender };

package/dist/index.js

@@ -1541,6 +1541,7 @@ function findRuntimeMediaSrcMutationFindings(ctx) {
 }
 var mediaRules = [
   findNestedMediaStartBasisFindings,
+  findSpeedRampOnNonMediaFindings,
   // duplicate_media_id + duplicate_media_discovery_risk
   ({ tags }) => {
     const findings = [];
@@ -1962,6 +1963,18 @@ function findVolumeDoubleAutomationFindings(ctx) {
   }
   return findings;
 }
+function findSpeedRampOnNonMediaFindings(ctx) {
+  return ctx.tags.filter((tag) => tag.name !== "video" && tag.name !== "audio").filter(
+    (tag) => /"target"\s*:\s*"rate"/.test(readDecodedAttr(tag.raw, "data-automation") ?? "")
+  ).map((tag) => ({
+    code: "speed_ramp_on_non_media",
+    severity: "warning",
+    message: `<${tag.name}> has a speed-ramp lane, but only <video> and <audio> clips can be retimed. The lane does nothing here.`,
+    elementId: readAttr(tag.raw, "id") || void 0,
+    fixHint: "Move the rate lane onto the <video> or <audio> clip, or retime an animation with a GSAP timeline instead.",
+    snippet: truncateSnippet(tag.raw)
+  }));
+}
 function findCarveUngroupedSourcesFindings(ctx) {
   const groupIds = new Set(
     ctx.tags.filter((tag) => tag.name === "hf-audio-group").map((tag) => readAttr(tag.raw, "id"))
@@ -2068,6 +2081,11 @@ function findAudioGroupCarveAttrFindings(ctx) {
 // src/rules/composition.ts
 import { COMPOSITION_VARIABLE_TYPES, isSafeMediaUrl } from "@hyperframes/parsers/composition";
 import { COMPOSITION_ATTRIBUTES, readClipTiming } from "@hyperframes/parsers/composition-contract";
+import { resolveCompositionDuration } from "@hyperframes/parsers/composition-duration";
+import {
+  readAuthoredDurationSeconds,
+  resolveMediaDuration
+} from "@hyperframes/parsers/media-duration";
 var MAX_COMPOSITION_LINES = 300;
 var MAX_TIMED_ELEMENTS_PER_TRACK = 3;
 var TRACK_DENSITY_EXEMPT_TAGS = /* @__PURE__ */ new Set(["audio", "script", "style", "video"]);
@@ -2843,6 +2861,18 @@ ${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
     const hasInfiniteCssAnimation = /\banimation(?:-iteration-count)?\s*:[^;{}]*(?<![\w-])infinite(?![\w-])/.test(combinedCss);
     const hasAnyNonGsapSignal = usesLottie || usesThree || usesWaapi || hasCssAnimationName;
     if (!hasAnyNonGsapSignal) {
+      const derived = deriveDurationFromClips(tags, rootTag);
+      if (derived.source === "derived") {
+        return [
+          {
+            code: "root_composition_duration_derived",
+            severity: "warning",
+            message: `Root composition has no data-duration and no GSAP timeline, so its length is taken from its clips: at least ${derived.seconds}s` + (derived.pendingClips > 0 ? `, and ${derived.pendingClips} clip(s) whose length is only known at runtime` : "") + ".",
+            fixHint: 'Add data-duration="<seconds>" to the root element to set the length yourself.',
+            snippet: truncateSnippet(rootTag.raw)
+          }
+        ];
+      }
       return [
         {
           code: "root_composition_missing_duration_source",
@@ -2927,6 +2957,35 @@ ${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
     ];
   }
 ];
+var CLIP_MEDIA_TAGS = /* @__PURE__ */ new Set(["img", "video", "audio"]);
+function deriveDurationFromClips(tags, rootTag) {
+  const clipEnds = [];
+  for (const tag of tags) {
+    if (tag === rootTag) continue;
+    const startRaw = readAttr(tag.raw, "data-start");
+    if (startRaw === null) continue;
+    const start = Number(startRaw);
+    if (!Number.isFinite(start)) {
+      clipEnds.push(null);
+      continue;
+    }
+    const getAttr = (name) => readAttr(tag.raw, name);
+    const authored = readAuthoredDurationSeconds(getAttr, start);
+    if (CLIP_MEDIA_TAGS.has(tag.name)) {
+      const { seconds } = resolveMediaDuration({
+        tag: tag.name,
+        authoredDurationSeconds: authored,
+        sourceDurationSeconds: null,
+        mediaStartSeconds: 0,
+        playbackRate: 1
+      });
+      clipEnds.push(seconds === null ? null : start + seconds);
+    } else if (authored !== null && authored > 0) {
+      clipEnds.push(start + authored);
+    }
+  }
+  return resolveCompositionDuration({ authoredDurationSeconds: null, clipEndsSeconds: clipEnds });
+}
 
 // src/rules/gsap.ts
 async function loadParseGsapScript() {
@@ -5322,6 +5381,155 @@ var slideshowRules = [
   }
 ];
 
+// src/rules/structure.ts
+import {
+  isSubCompositionHost,
+  topLevelElements,
+  trackKindOf
+} from "@hyperframes/parsers/top-level-elements";
+var INLINE_TEXT_TAGS = /* @__PURE__ */ new Set([
+  "br",
+  "wbr",
+  "b",
+  "i",
+  "u",
+  "s",
+  "em",
+  "strong",
+  "small",
+  "sub",
+  "sup",
+  "mark",
+  "span",
+  "a",
+  "code",
+  "abbr"
+]);
+var OPAQUE_TAGS = /* @__PURE__ */ new Set([
+  "svg",
+  "canvas",
+  "picture",
+  "video",
+  "audio",
+  "select",
+  "textarea",
+  "iframe",
+  "object"
+]);
+var NON_LAYOUT_TAGS = /* @__PURE__ */ new Set(["style", "script", "template", "noscript"]);
+var MEDIA_TAGS = /* @__PURE__ */ new Set(["video", "audio", "img"]);
+var NODE_ATTRS = [
+  "id",
+  "class",
+  "data-start",
+  "data-duration",
+  "data-end",
+  "data-track",
+  "data-track-index",
+  "data-track-kind",
+  "data-composition-id",
+  "data-composition-src"
+];
+function toNode(open) {
+  const attrs = {};
+  for (const name of NODE_ATTRS) attrs[name] = readDecodedAttr(open.raw, name) ?? void 0;
+  return { tag: open.name, attrs, children: [], open };
+}
+function enclosing(stack, root, index) {
+  let top = stack.at(-1);
+  while (top && stack.length > 1 && index >= top.end) {
+    stack.pop();
+    top = stack.at(-1);
+  }
+  return top?.node ?? root;
+}
+function buildTree(ctx) {
+  const { rootTag } = ctx;
+  const rootEnd = rootTag?.closeIndex;
+  if (!rootTag || rootEnd == null) return null;
+  const root = toNode(rootTag);
+  const stack = [{ node: root, end: rootEnd }];
+  for (const tag of ctx.tags.filter((t) => t.index > rootTag.index && t.index < rootEnd)) {
+    const node = toNode(tag);
+    enclosing(stack, root, tag.index).children.push(node);
+    if (tag.closeIndex != null) stack.push({ node, end: tag.closeIndex });
+  }
+  return root;
+}
+function hasNestedStructure(node) {
+  if (OPAQUE_TAGS.has(node.tag)) return null;
+  for (const child of node.children) {
+    if (NON_LAYOUT_TAGS.has(child.tag)) continue;
+    if (!INLINE_TEXT_TAGS.has(child.tag)) return child;
+    const deeper = hasNestedStructure(child);
+    if (deeper) return deeper;
+  }
+  return null;
+}
+var describe = (node) => `<${node.tag}${node.attrs.id ? ` id="${node.attrs.id}"` : ""}>`;
+function nestedStructureFindings(rows, severity) {
+  return rows.flatMap((row) => {
+    const nested = isSubCompositionHost(row) ? null : hasNestedStructure(row);
+    if (!nested) return [];
+    return [
+      {
+        code: "nested_structure_needs_subcomposition",
+        severity,
+        message: `${describe(row)} is a timeline element that contains nested ${describe(nested)}. The timeline shows one row per top-level element, and the root composition is built only from sub-compositions.`,
+        elementId: row.attrs.id,
+        fixHint: `Move ${describe(row)} and its contents into a sub-composition file and mount it with data-composition-src.`
+      }
+    ];
+  });
+}
+function missingDurationFindings(rows, severity) {
+  return rows.filter(
+    (row) => !MEDIA_TAGS.has(row.tag) && row.attrs["data-duration"] === void 0 && row.attrs["data-end"] === void 0 && !isSubCompositionHost(row)
+  ).map((row) => ({
+    code: "timeline_element_missing_timing",
+    severity,
+    message: `${describe(row)} is a timeline element without data-duration, so the timeline cannot draw where it ends.`,
+    elementId: row.attrs.id,
+    fixHint: `Add data-duration (in seconds) to ${describe(row)}.`
+  }));
+}
+function captionFindings(rows, severity) {
+  const captionRows = rows.filter((row) => trackKindOf(row).kind === "captions");
+  const findings = captionRows.filter((row) => trackKindOf(row).source === "legacy-captions").map((row) => ({
+    code: "caption_track_kind_missing",
+    severity,
+    message: `${describe(row)} looks like captions but is not marked as such, so the timeline cannot group it on the caption track.`,
+    elementId: row.attrs.id,
+    fixHint: `Add data-track-kind="captions" to ${describe(row)}.`
+  }));
+  const lanes = new Set(
+    captionRows.flatMap((row) => row.attrs["data-track-index"] ?? row.attrs["data-track"] ?? [])
+  );
+  if (lanes.size > 1) {
+    findings.push({
+      code: "multiple_caption_tracks",
+      severity,
+      message: `Captions are spread across ${lanes.size} timeline tracks. Keep all captions on one track.`,
+      fixHint: "Give every caption element the same data-track-index."
+    });
+  }
+  return findings;
+}
+var structureRules = [
+  (ctx) => {
+    if (ctx.options.isSubComposition) return [];
+    const root = buildTree(ctx);
+    if (!root) return [];
+    const severity = ctx.options.host === "studio" ? "error" : "warning";
+    const rows = topLevelElements(root);
+    return [
+      ...nestedStructureFindings(rows, severity),
+      ...missingDurationFindings(rows, severity),
+      ...captionFindings(rows, severity)
+    ];
+  }
+];
+
 // src/hyperframeLinter.ts
 var RULE_GROUPS = [
   { group: "core", rules: coreRules },
@@ -5332,7 +5540,8 @@ var RULE_GROUPS = [
   { group: "adapters", rules: adapterRules },
   { group: "textures", rules: textureRules },
   { group: "fonts", rules: fontRules },
-  { group: "slideshow", rules: slideshowRules }
+  { group: "slideshow", rules: slideshowRules },
+  { group: "structure", rules: structureRules }
 ];
 var LINT_RULE_COUNT = RULE_GROUPS.reduce((n, g) => n + g.rules.length, 0);
 var LINT_RULE_GROUP_COUNTS = Object.fromEntries(
@@ -5476,7 +5685,8 @@ import {
   isWithinProjectRoot,
   maskNonScannableRanges as maskNonScannableRanges2,
   resolveExistingLocalAsset as resolveExistingLocalAsset2,
-  resolveLocalAssetCandidates
+  resolveLocalAssetCandidates,
+  resolveProjectRelativeSrc
 } from "@hyperframes/parsers/asset-resolution";
 
 // src/hevcPreviewLint.ts
@@ -5794,7 +6004,7 @@ function resolveCssAssetCandidates(projectDir, url, htmlCompSrcPath, cssRootRela
   }
   return resolveLocalAssetCandidates(projectDir, url);
 }
-async function lintProject(projectDir, entryFile) {
+async function lintProject(projectDir, entryFile, hostOptions = {}) {
   const indexPath = entryFile ? resolve(entryFile) : resolve(projectDir, "index.html");
   if (entryFile && !isWithinProjectRoot(projectDir, indexPath)) {
     throw new Error(`Explicit lint entry is outside the project directory: ${entryFile}`);
@@ -5807,6 +6017,7 @@ async function lintProject(projectDir, entryFile) {
   let totalInfos = 0;
   const rootHtml = readFileSync(indexPath, "utf-8");
   const rootResult = await lintHyperframeHtml(rootHtml, {
+    ...hostOptions,
     filePath: indexPath,
     externalStyles: collectExternalStyles(projectDir, rootHtml, rootCompSrcPath)
   });
@@ -5838,6 +6049,7 @@ async function lintProject(projectDir, entryFile) {
       allHtmlSources.push({ html, compSrcPath });
       if (isSnippetFragment(html)) continue;
       const result = await lintHyperframeHtml(html, {
+        ...hostOptions,
         filePath,
         isSubComposition: true,
         externalStyles: collectExternalStyles(projectDir, html, compSrcPath)
@@ -5945,7 +6157,7 @@ function lintAudioSrcNotFound(projectDir, htmlSources) {
       if (/^(https?:|data:|blob:)/i.test(src)) continue;
       if (isUnresolvedAssetPlaceholder2(src)) continue;
       const rootRelative = compSrcPath ? rewriteAssetPath2(compSrcPath, src, (path) => existsSync2(join2(projectDir, path))) : src;
-      if (!resolveLocalAssetCandidates(projectDir, rootRelative).some(existsSync2)) {
+      if (!existsSync2(resolveProjectRelativeSrc(rootRelative, projectDir))) {
         missingSrcs.push(src);
       }
     }