@hyperframes/lint 0.8.106 → 0.8.108

package/dist/index.js

@@ -113,6 +113,28 @@ function readAttr(tagSource, attr) {
   const match = tagSource.match(new RegExp(`(?<![\\w-])${escaped}\\s*=\\s*["']([^"']+)["']`, "i"));
   return match?.[1] || null;
 }
+function hasAttrName(tagSource, attr) {
+  const escaped = attr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const attrs = tagSource.replace(/^<\s*[a-z][\w:-]*/i, "");
+  return new RegExp(`(?:^|\\s)${escaped}(?:\\s*=|\\s|/?>)`, "i").test(attrs);
+}
+function isAudibleVideoTag(tagSource) {
+  if (hasAttrName(tagSource, "muted")) return false;
+  if (!hasAttrName(tagSource, "data-has-audio")) return true;
+  const declared = readAttr(tagSource, "data-has-audio");
+  return declared === "true";
+}
+function mediaTimeWindow(tagSource) {
+  const start = Number(readAttr(tagSource, "data-start"));
+  const duration = Number(readAttr(tagSource, "data-duration"));
+  if (!readAttr(tagSource, "data-start") || !readAttr(tagSource, "data-duration")) return null;
+  if (!Number.isFinite(start) || !Number.isFinite(duration)) return null;
+  return { start, end: start + duration };
+}
+function mediaWindowsOverlap(a, b) {
+  if (!a || !b) return true;
+  return a.start < b.end && b.start < a.end;
+}
 function readDecodedAttr(tagSource, attr) {
   if (!tagSource) return null;
   let value = null;
@@ -1370,11 +1392,6 @@ function tweensVolumeInSameCall(script, id) {
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function hasAttrName(tagSource, attr) {
-  const escaped = escapeRegExp(attr);
-  const attrs = tagSource.replace(/^<\s*[a-z][\w:-]*/i, "");
-  return new RegExp(`(?:^|\\s)${escaped}(?:\\s*=|\\s|/?>)`, "i").test(attrs);
-}
 var IMAGE_SRC_EXT = /* @__PURE__ */ new Set([
   "jpg",
   "jpeg",
@@ -1775,14 +1792,15 @@ var mediaRules = [
       if (tag.name !== "video") continue;
       const hasMuted = hasAttrName(tag.raw, "muted");
       const hasDeclaredAudio = readAttr(tag.raw, "data-has-audio") === "true";
-      if (!hasMuted && !hasDeclaredAudio && readAttr(tag.raw, "data-start")) {
+      const declaresAudioState = hasAttrName(tag.raw, "data-has-audio");
+      if (!hasMuted && !declaresAudioState && readAttr(tag.raw, "data-start")) {
         const elementId = readAttr(tag.raw, "id") || void 0;
         findings.push({
           code: "video_missing_muted",
           severity: "error",
-          message: `<video${elementId ? ` id="${elementId}"` : ""}> has data-start but is not muted. Mark audible videos with data-has-audio="true"; otherwise keep video muted and use a separate <audio> element for sound.`,
+          message: `<video${elementId ? ` id="${elementId}"` : ""}> has data-start but declares neither muted nor data-has-audio. If the file has sound, add data-has-audio="true" (the sound stays on this clip). If it is silent, add muted.`,
           elementId,
-          fixHint: 'Add the `muted` attribute for silent video, or add data-has-audio="true" when the video track should contribute audio.',
+          fixHint: 'Add data-has-audio="true" when the file has sound (recommended \u2014 keeps picture and sound on one clip), or add `muted` for silent footage.',
           snippet: truncateSnippet(tag.raw)
         });
       }
@@ -2008,31 +2026,31 @@ var mediaRules = [
   // <audio> pointing to the same file, which causes double playback at runtime
   ({ tags }) => {
     const findings = [];
-    const videoSources = /* @__PURE__ */ new Map();
-    const audioSources = /* @__PURE__ */ new Map();
+    const videos = [];
+    const audios = [];
     for (const tag of tags) {
       if (!readAttr(tag.raw, "data-start")) continue;
       const src = readAttr(tag.raw, "src");
       if (!src) continue;
-      const elementId = readAttr(tag.raw, "id") || void 0;
+      const source = { id: readAttr(tag.raw, "id") || void 0, raw: tag.raw };
       if (tag.name === "video") {
-        const isMuted = hasAttrName(tag.raw, "muted");
-        if (!isMuted) {
-          videoSources.set(src, { id: elementId, raw: tag.raw });
-        }
+        if (isAudibleVideoTag(tag.raw)) videos.push([src, source]);
       } else if (tag.name === "audio") {
-        audioSources.set(src, { id: elementId, raw: tag.raw });
+        audios.push([src, source]);
       }
     }
-    for (const [src, audioInfo] of audioSources) {
-      const videoInfo = videoSources.get(src);
-      if (!videoInfo) continue;
+    for (const [src, audioInfo] of audios) {
+      const match = videos.find(
+        ([videoSrc, video]) => videoSrc === src && mediaWindowsOverlap(mediaTimeWindow(video.raw), mediaTimeWindow(audioInfo.raw))
+      );
+      if (!match) continue;
+      const videoInfo = match[1];
       findings.push({
         code: "video_audio_double_source",
         severity: "error",
-        message: `<audio${audioInfo.id ? ` id="${audioInfo.id}"` : ""}> and <video${videoInfo.id ? ` id="${videoInfo.id}"` : ""}> both point to the same source. The unmuted video already provides audio \u2014 the duplicate <audio> will cause double playback and echo.`,
+        message: `<audio${audioInfo.id ? ` id="${audioInfo.id}"` : ""}> and <video${videoInfo.id ? ` id="${videoInfo.id}"` : ""}> both point to the same source at the same time. The unmuted video already provides audio \u2014 the duplicate <audio> will cause double playback and echo.`,
         elementId: audioInfo.id,
-        fixHint: "Either mute the video (add `muted` attribute) and keep the separate <audio>, or remove the <audio> element and let the video provide its own audio track.",
+        fixHint: "Remove the <audio> element and let the video carry its own sound (recommended), or mute the video (add `muted`) and keep the separate <audio> when picture and sound must be cut independently.",
         snippet: truncateSnippet(audioInfo.raw)
       });
     }
@@ -2141,7 +2159,7 @@ function findCarveUngroupedSourcesFindings(ctx) {
 var AUDIO_GROUP_TIMING_ATTRS = ["data-start", "data-duration", "data-track-index"];
 function findAudioGroupNoMembersFindings(ctx) {
   const memberGroupIds = new Set(
-    ctx.tags.filter((tag) => tag.name === "audio").map((tag) => readAttr(tag.raw, "data-audio-group")).filter((id) => Boolean(id))
+    ctx.tags.filter((tag) => tag.name === "audio" || tag.name === "video" && isAudibleVideoTag(tag.raw)).map((tag) => readAttr(tag.raw, "data-audio-group")).filter((id) => Boolean(id))
   );
   if (memberGroupIds.size === 0) return [];
   const mayHaveCrossFileMembers = ctx.tags.some(
@@ -6616,7 +6634,10 @@ function lintProjectAudioFiles(projectDir, htmlSources) {
   }
   if (audioFiles.length === 0) return findings;
   const hasAudioElement = htmlSources.some(({ html }) => /<audio\b/i.test(html));
-  if (!hasAudioElement) {
+  const hasAudibleVideo = htmlSources.some(
+    ({ html }) => (html.match(/<video\b[^>]*>/gi) ?? []).some(isAudibleVideoTag)
+  );
+  if (!hasAudioElement && !hasAudibleVideo) {
     findings.push({
       code: "audio_file_without_element",
       severity: "warning",
@@ -6766,10 +6787,11 @@ function lintDuplicateAudioTracks(htmlSources) {
   const tracks = [];
   const seen = /* @__PURE__ */ new Set();
   for (const { html } of htmlSources) {
-    const audioTagRe = /<audio\b[^>]*>/gi;
+    const soundTagRe = /<(?:audio|video)\b[^>]*>/gi;
     let match;
-    while ((match = audioTagRe.exec(html)) !== null) {
+    while ((match = soundTagRe.exec(html)) !== null) {
       const tag = match[0];
+      if (/^<video/i.test(tag) && !isAudibleVideoTag(tag)) continue;
       const trackStr = extractAttr(tag, "data-track-index");
       const startStr = extractAttr(tag, "data-start");
       const durStr = extractAttr(tag, "data-duration");
@@ -6793,7 +6815,7 @@ function lintDuplicateAudioTracks(htmlSources) {
         findings.push({
           code: "duplicate_audio_track",
           severity: "warning",
-          message: `Multiple <audio> elements on track ${a.trackIndex} overlap (${a.src} at ${a.start}-${Number.isFinite(a.end) ? a.end.toFixed(1) : "end"}s, ${b.src} at ${b.start}-${Number.isFinite(b.end) ? b.end.toFixed(1) : "end"}s). This causes layered audio playback.`,
+          message: `Multiple audible <audio>/<video> elements on track ${a.trackIndex} overlap (${a.src} at ${a.start}-${Number.isFinite(a.end) ? a.end.toFixed(1) : "end"}s, ${b.src} at ${b.start}-${Number.isFinite(b.end) ? b.end.toFixed(1) : "end"}s). This causes layered audio playback.`,
           fixHint: "Use non-overlapping time windows or different track indices."
         });
       }