@hyperframes/lint 0.8.67 → 0.8.68

package/dist/browser.d.ts

@@ -39,6 +39,7 @@ type HyperframeLinterOptions = {
     externalStyles?: Array<{
         href: string;
         content: string;
+        file?: string;
     }>;
     /**
      * Set to `true` when linting compositions destined for distributed / Lambda

package/dist/browser.js

@@ -3,6 +3,7 @@ import { Parser as Parser2 } from "htmlparser2";
 
 // src/utils.ts
 import { Parser } from "htmlparser2";
+import { parse } from "acorn";
 var COMPOSITION_ID_IN_CSS_PATTERN = /\[data-composition-id=["']([^"']+)["']\]/g;
 var TIMELINE_REGISTRY_INIT_PATTERN = /window\.__timelines\s*=\s*window\.__timelines\s*\|\|\s*\{\}|window\.__timelines\s*=\s*\{\}|window\.__timelines\s*\?\?=\s*\{\}/i;
 var TIMELINE_REGISTRY_OBJECT_LITERAL_PATTERN = /window\.__timelines\s*=\s*\{\s*(?:["'][^"']+["']|[A-Za-z_$][\w$]*)\s*:/i;
@@ -56,6 +57,7 @@ function parseHtmlStructure(source) {
         blocks[name].push({
           attrs: block.attrs,
           content: source.slice(block.contentStart, parser.startIndex),
+          contentStart: block.contentStart,
           raw: source.slice(block.index, parser.endIndex + 1),
           index: block.index
         });
@@ -205,11 +207,17 @@ function readTimelineRegistryTopLevelKeys(source) {
 function getInlineScriptSyntaxError(source) {
   if (!source.trim()) return null;
   try {
-    new Function(source);
+    parse(source, {
+      ecmaVersion: "latest",
+      sourceType: "script",
+      allowReturnOutsideFunction: true
+    });
     return null;
   } catch (error) {
-    if (error instanceof Error) return error.message;
-    return String(error);
+    return {
+      message: error instanceof Error ? error.message : String(error),
+      offset: error instanceof SyntaxError && "pos" in error && typeof error.pos === "number" ? error.pos : void 0
+    };
   }
 }
 function stripStringLiterals(source) {
@@ -528,7 +536,7 @@ function stripCssComments(source) {
   }
   return out;
 }
-function stripHtmlCommentsOnce(source) {
+function stripHtmlCommentsOnce(source, removed) {
   let out = "";
   let i = 0;
   for (; ; ) {
@@ -537,14 +545,17 @@ function stripHtmlCommentsOnce(source) {
     const end = source.indexOf("-->", start + 4);
     if (end < 0) return out + source.slice(i);
     out += source.slice(i, start);
+    removed?.(start, end + 3);
     i = end + 3;
   }
 }
-function stripHtmlComments(source) {
+function stripHtmlComments(source, pass) {
   let out = source;
   for (let prev = ""; prev !== out; ) {
     prev = out;
-    out = stripHtmlCommentsOnce(out);
+    const ranges = [];
+    out = stripHtmlCommentsOnce(out, pass ? (start, end) => ranges.push([start, end]) : void 0);
+    if (ranges.length) pass?.(ranges);
   }
   return out;
 }
@@ -618,10 +629,42 @@ function snippetOffset(source, snippet) {
   return source.offsets[index];
 }
 
+// src/sourceCoordinates.ts
+function mappedHtmlSource(original) {
+  let offsets;
+  const source = stripHtmlComments(original, (ranges) => {
+    const previous = offsets;
+    const length = (previous?.length ?? original.length + 1) - ranges.reduce((n, [a, b]) => n + b - a, 0);
+    offsets = new Uint32Array(length);
+    let target = 0;
+    let start = 0;
+    const spans = [
+      ...ranges,
+      [previous ? previous.length : original.length + 1, 0]
+    ];
+    for (const [a, b] of spans) {
+      for (let i = start; i < a; i++) offsets[target++] = previous ? previous[i] : i;
+      start = b;
+    }
+  });
+  return { source, originalOffset: (index) => offsets ? offsets[index] : index };
+}
+function sourcePosition(source, offset, file) {
+  if (!Number.isInteger(offset) || offset < 0 || offset > source.length) return {};
+  const before = source.slice(0, offset);
+  return {
+    ...file ? { file } : {},
+    line: before.split(/\r\n|\r|\n/).length,
+    column: offset - Math.max(before.lastIndexOf("\n"), before.lastIndexOf("\r"))
+  };
+}
+
 // src/context.ts
 function buildLintContext(html, options = {}) {
   const rawSource = html || "";
-  let source = stripHtmlComments(rawSource);
+  const mapped = mappedHtmlSource(rawSource);
+  let source = mapped.source;
+  let sourceStart = 0;
   const initialStructure = parseHtmlStructure(source);
   const templateTags = initialStructure.tags.filter(
     (tag) => tag.name === "template" && tag.closeIndex != null
@@ -634,7 +677,8 @@ function buildLintContext(html, options = {}) {
   const template = templateTags[0];
   let structure = initialStructure;
   if (template && !findRootTag(sourceWithoutTemplates)) {
-    source = source.slice(template.index + template.raw.length, template.closeIndex);
+    sourceStart = template.index + template.raw.length;
+    source = source.slice(sourceStart, template.closeIndex);
     structure = parseHtmlStructure(source);
   }
   const tags = structure.tags;
@@ -644,14 +688,23 @@ function buildLintContext(html, options = {}) {
       attrs: `href="${style.href}"`,
       content: style.content,
       raw: style.content,
-      index: -1
+      index: -1,
+      file: style.file ?? style.href
     }))
   ];
   const scripts = structure.scripts;
   const compositionIds = collectCompositionIds(tags);
   const rootTag = findRootTag(source, tags);
   const rootCompositionId = readDecodedAttr(rootTag?.raw || "", "data-composition-id");
+  const locate = (block, offset) => {
+    if (offset === void 0 || offset < 0 || offset > block.content.length) return {};
+    if (block.index === -1) return sourcePosition(block.content, offset, block.file);
+    if (block.contentStart === void 0) return {};
+    const originalOffset = mapped.originalOffset(sourceStart + block.contentStart + offset);
+    return originalOffset === void 0 ? {} : sourcePosition(rawSource, originalOffset, options.filePath);
+  };
   return {
+    locate,
     source,
     rawSource,
     tags,
@@ -671,7 +724,7 @@ import {
   HTML_BODY_CSS_WIDTH_FIRST_RE,
   HTML_BODY_CSS_HEIGHT_FIRST_RE,
   VIEWPORT_META_SIZE_RE
-} from "@hyperframes/parsers";
+} from "@hyperframes/parsers/composition";
 function repeatedDescendantId(selector) {
   let repeated = null;
   const requiredPseudoIds = (pseudo) => {
@@ -1049,7 +1102,7 @@ var coreRules = [
     return findings;
   },
   // CSS selector safety
-  ({ styles }) => {
+  ({ styles, locate }) => {
     const findings = [];
     const reportedRepeatedIds = /* @__PURE__ */ new Set();
     const reportedHiddenStyleSelectors = /* @__PURE__ */ new Set();
@@ -1059,6 +1112,10 @@ var coreRules = [
         root = postcss.parse(style.content);
       } catch (error) {
         findings.push({
+          ...locate(
+            style,
+            error instanceof postcss.CssSyntaxError ? cssErrorOffset(style.content, error) : void 0
+          ),
           code: "css_parse_error",
           severity: "error",
           message: `CSS parse error: ${error instanceof Error ? error.message : "unknown"}`
@@ -1124,7 +1181,7 @@ var coreRules = [
     ];
   },
   // invalid_inline_script_syntax (JS parse error)
-  ({ scripts }) => {
+  ({ scripts, locate }) => {
     const findings = [];
     for (const script of scripts) {
       const attrs = script.attrs || "";
@@ -1135,9 +1192,10 @@ var coreRules = [
       const syntaxError = getInlineScriptSyntaxError(script.content);
       if (!syntaxError) continue;
       findings.push({
+        ...locate(script, syntaxError.offset),
         code: "invalid_inline_script_syntax",
         severity: "error",
-        message: `Inline script has invalid syntax: ${syntaxError}`,
+        message: `Inline script has invalid syntax: ${syntaxError.message}`,
         fixHint: "Fix the inline script syntax before render verification.",
         snippet: truncateSnippet(script.content)
       });
@@ -1203,7 +1261,7 @@ var coreRules = [
     return findings;
   },
   // non_deterministic_code
-  ({ scripts }) => {
+  ({ scripts, locate }) => {
     const findings = [];
     const patterns = [
       {
@@ -1254,8 +1312,10 @@ var coreRules = [
       const withoutComments = stripJsComments(script.content);
       const executable = stripStringLiterals(withoutComments);
       for (const { pattern, label, hint, scansStrings } of patterns) {
-        if (pattern.test(scansStrings ? withoutComments : executable)) {
+        const match = pattern.exec(scansStrings ? withoutComments : executable);
+        if (match) {
           findings.push({
+            ...locate(script, match.index),
             code: "non_deterministic_code",
             severity: "error",
             message: `Script contains \`${label}\` which produces non-deterministic output. Renders may differ between frames or runs.`,
@@ -1268,10 +1328,24 @@ var coreRules = [
     return findings;
   }
 ];
+function cssErrorOffset(source, error) {
+  if (error.input && "offset" in error.input && typeof error.input.offset === "number")
+    return error.input.offset;
+  const { line, column } = error;
+  if (line === void 0 || column === void 0) return void 0;
+  let offset = 0;
+  let currentLine = 1;
+  for (const match of source.matchAll(/\n/g)) {
+    if (currentLine >= line) break;
+    offset = match.index + 1;
+    currentLine++;
+  }
+  return currentLine === line ? offset + column - 1 : void 0;
+}
 
 // src/rules/media.ts
 import { validateColorGradingContract } from "@hyperframes/parsers/color-grading-contract";
-import { extractMediaSrcMutations } from "@hyperframes/parsers";
+import { extractMediaSrcMutations } from "@hyperframes/parsers/composition";
 import { parseHTML } from "linkedom";
 function tweensVolumeInSameCall(script, id) {
   const selector = new RegExp(`#${escapeRegExp(id)}(?![\\w-])`, "g");
@@ -2130,6 +2204,45 @@ function findAudioGroupCarveAttrFindings(ctx) {
   return findings;
 }
 
+// src/scriptPositions.ts
+import { parse as parse2 } from "acorn";
+import { simple } from "acorn-walk";
+var callIndexes = /* @__PURE__ */ new WeakMap();
+function callsFor(script) {
+  const cached = callIndexes.get(script);
+  if (cached) return cached;
+  const calls = [];
+  try {
+    const ast = parse2(script.content, {
+      ecmaVersion: "latest",
+      sourceType: "script",
+      allowReturnOutsideFunction: true
+    });
+    simple(ast, {
+      CallExpression: (node) => {
+        calls.push(node);
+      }
+    });
+  } catch {
+  }
+  calls.sort((a, b) => a.start - b.start);
+  callIndexes.set(script, calls);
+  return calls;
+}
+function gsapCallOffset(script, method) {
+  return callsFor(script).find(
+    ({ callee }) => callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier" && callee.object.name === "gsap" && callee.property.type === "Identifier" && callee.property.name === method
+  )?.start;
+}
+function containingCallOffset(script, tokenOffset) {
+  let start;
+  for (const call of callsFor(script)) {
+    if (call.start > tokenOffset) break;
+    if (call.end > tokenOffset) start = call.start;
+  }
+  return start;
+}
+
 // src/rules/composition.ts
 import { COMPOSITION_VARIABLE_TYPES, isSafeMediaUrl } from "@hyperframes/parsers/composition";
 import { COMPOSITION_ATTRIBUTES, readClipTiming } from "@hyperframes/parsers/composition-contract";
@@ -3339,8 +3452,8 @@ function targetedSelectorTokens(selector) {
     const compounds = group.trim().split(/[\s>+~]+/).filter(Boolean);
     const last = compounds[compounds.length - 1];
     if (!last) continue;
-    const simple = last.match(/[#.][A-Za-z0-9_-]+/g);
-    if (simple) for (const token of simple) tokens.add(token);
+    const simple2 = last.match(/[#.][A-Za-z0-9_-]+/g);
+    if (simple2) for (const token of simple2) tokens.add(token);
   }
   return tokens;
 }
@@ -3379,7 +3492,7 @@ function scanScriptsForRegexMatches(scripts, pattern, options) {
         content.length,
         match.index + match[0].length + options.contextAfter
       );
-      hits.push({ match, snippet: content.slice(contextStart, contextEnd) });
+      hits.push({ match, snippet: content.slice(contextStart, contextEnd), script });
     }
   }
   return hits;
@@ -4085,19 +4198,20 @@ ${right.raw}`)
     return findings;
   },
   // gsap_infinite_repeat
-  ({ scripts, rootTag }) => {
+  ({ scripts, rootTag, locate }) => {
     const findings = [];
     const declaredDuration = Number.parseFloat(
       rootTag ? readAttr(rootTag.raw, "data-duration") ?? "" : ""
     );
     const hasFiniteCompositionWindow = Number.isFinite(declaredDuration) && declaredDuration > 0;
     const pattern = /repeat\s*:\s*-1(?!\d)/g;
-    for (const { snippet } of scanScriptsForRegexMatches(scripts, pattern, {
+    for (const { snippet, match, script } of scanScriptsForRegexMatches(scripts, pattern, {
       stripComments: true,
       contextBefore: 60,
       contextAfter: 60
     })) {
       findings.push({
+        ...locate(script, containingCallOffset(script, match.index)),
         code: "gsap_infinite_repeat",
         severity: hasFiniteCompositionWindow ? "warning" : "error",
         message: hasFiniteCompositionWindow ? `GSAP tween uses \`repeat: -1\` (infinite), but the composition declares a finite ${declaredDuration}s window. HyperFrames clips deterministic seeking and export to that explicit duration.` : "GSAP tween uses `repeat: -1` (infinite) without a finite composition `data-duration`. The timeline can report an unbounded duration and make render planning fail.",
@@ -4108,15 +4222,16 @@ ${right.raw}`)
     return findings;
   },
   // gsap_repeat_ceil_overshoot
-  ({ scripts }) => {
+  ({ scripts, locate }) => {
     const findings = [];
     const pattern = /repeat\s*:\s*Math\.ceil\s*\([^)]+\)\s*-\s*1/g;
-    for (const { snippet } of scanScriptsForRegexMatches(scripts, pattern, {
+    for (const { snippet, match, script } of scanScriptsForRegexMatches(scripts, pattern, {
       stripComments: false,
       contextBefore: 40,
       contextAfter: 40
     })) {
       findings.push({
+        ...locate(script, containingCallOffset(script, match.index)),
         code: "gsap_repeat_ceil_overshoot",
         severity: "warning",
         message: "GSAP repeat calculation uses `Math.ceil` which can overshoot the composition duration. For example, Math.ceil(10.5 / 2) - 1 = 5 repeats \u2192 6 cycles \xD7 2s = 12s, exceeding 10.5s.",
@@ -4127,15 +4242,16 @@ ${right.raw}`)
     return findings;
   },
   // gsap_repeat_floor_unclamped
-  ({ scripts }) => {
+  ({ scripts, locate }) => {
     const findings = [];
     const pattern = /repeat\s*:\s*Math\.floor\s*\([^)]+\)\s*-\s*1/g;
-    for (const { snippet } of scanScriptsForRegexMatches(scripts, pattern, {
+    for (const { snippet, match, script } of scanScriptsForRegexMatches(scripts, pattern, {
       stripComments: false,
       contextBefore: 40,
       contextAfter: 40
     })) {
       findings.push({
+        ...locate(script, containingCallOffset(script, match.index)),
         code: "gsap_repeat_floor_unclamped",
         severity: "warning",
         message: "GSAP repeat calculation can evaluate to -1 when the composition is shorter than one cycle, which GSAP interprets as an infinite repeat.",
@@ -4146,7 +4262,7 @@ ${right.raw}`)
     return findings;
   },
   // gsap_timeline_not_registered
-  ({ scripts, rawSource, options }) => {
+  ({ scripts, rawSource, options, locate }) => {
     const findings = [];
     const canInheritFromHost = options.isSubComposition || rawSource.trimStart().toLowerCase().startsWith("<template");
     for (const script of scripts) {
@@ -4155,6 +4271,7 @@ ${right.raw}`)
       const hasRegistration = WINDOW_TIMELINE_ASSIGN_PATTERN.test(content) || TIMELINE_REGISTRY_OBJECT_LITERAL_PATTERN.test(content);
       if (hasRegistration || canInheritFromHost) continue;
       findings.push({
+        ...locate(script, gsapCallOffset(script, "timeline")),
         code: "gsap_timeline_not_registered",
         severity: "error",
         message: "GSAP timeline is created but never registered in window.__timelines. The runtime discovers timelines from this registry \u2014 without registration, animations will not play during preview or render.",
@@ -5197,6 +5314,7 @@ var textureRules = [
 ];
 
 // src/rules/fonts.ts
+import postcss3 from "postcss";
 import { FONT_ALIAS_KEYS, resolveAliasDisplayName } from "@hyperframes/parsers/composition";
 var GENERIC_FAMILIES = /* @__PURE__ */ new Set([
   "serif",
@@ -5343,7 +5461,7 @@ var fontRules = [
     ];
   },
   // font_family_without_font_face
-  ({ styles, source, rawSource, options }) => {
+  ({ styles, source, rawSource, options, locate }) => {
     if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
     const findings = [];
     const declared = extractFontFaceFamilies(styles);
@@ -5354,6 +5472,7 @@ var fontRules = [
     );
     if (undeclared.length === 0) return findings;
     findings.push({
+      ...uniqueFontLocation(styles, undeclared, locate),
       code: "font_family_without_font_face",
       severity: "error",
       message: `Font ${undeclared.length === 1 ? "family" : "families"} used without @font-face declaration: ${undeclared.join(", ")}. These are not in the auto-resolved font list, so the renderer cannot supply them automatically. Text will fall back to a generic font, producing incorrect typography in the video.`,
@@ -5362,6 +5481,26 @@ var fontRules = [
     return findings;
   }
 ];
+function uniqueFontLocation(styles, families, locate) {
+  const locations = [];
+  for (const style of styles) {
+    try {
+      postcss3.parse(style.content).walkDecls(/^font-family$/i, (decl) => {
+        let parent = decl.parent;
+        while (parent) {
+          if (parent.type === "atrule" && parent.name.toLowerCase() === "font-face") return;
+          parent = parent.parent;
+        }
+        if (!decl.value.split(",").some((part) => families.includes(normalizeUsedFontName(part) ?? "")))
+          return;
+        locations.push(locate(style, decl.source?.start?.offset));
+      });
+    } catch {
+      return {};
+    }
+  }
+  return locations.length === 1 ? locations[0] : {};
+}
 
 // src/rules/slideshow.ts
 import {
@@ -5634,7 +5773,7 @@ function collectFindings(produced, seen, filePath, into) {
     const dedupeKey = dedupeKeyFor(finding);
     if (seen.has(dedupeKey)) continue;
     seen.add(dedupeKey);
-    into.push(filePath ? { ...finding, file: filePath } : finding);
+    into.push(filePath ? { ...finding, file: finding.file ?? filePath } : finding);
   }
 }
 async function lintHyperframeHtml(html, options = {}) {
@@ -5643,6 +5782,12 @@ async function lintHyperframeHtml(html, options = {}) {
   const { findings: rawFindings, timings } = await runRules(ctx, options.filePath);
   const locate = createSourceLocator(html);
   const findings = rawFindings.map((finding) => {
+    if (finding.line !== void 0 || finding.code === "invalid_inline_script_syntax" || finding.code === "non_deterministic_code" || [
+      "gsap_infinite_repeat",
+      "gsap_repeat_ceil_overshoot",
+      "gsap_repeat_floor_unclamped"
+    ].includes(finding.code))
+      return finding;
     if (finding.snippet && options.externalStyles?.some(
       (style) => style.content.replace(/\s+/g, " ").includes(finding.snippet.replace(/\.\.\.$/, ""))
     ))