@hyperframes/lint 0.8.142 → 0.8.144

package/dist/browser.d.ts

@@ -36,10 +36,12 @@ type HyperframeLintResult = {
 type HyperframeLinterOptions = {
     filePath?: string;
     isSubComposition?: boolean;
+    compSrcPath?: string;
     externalStyles?: Array<{
         href: string;
         content: string;
         file?: string;
+        rootRelativePath?: string;
     }>;
     /**
      * Set to `true` when linting compositions destined for distributed / Lambda

package/dist/browser.js

@@ -71,12 +71,13 @@ function parseHtmlStructure(source) {
 function findHtmlTag(tags) {
   return tags.find((tag) => tag.name === "html") ?? null;
 }
+var hasCompositionMarker = (tag) => Boolean(
+  readDecodedAttr(tag.raw, "data-composition-id") || readAttr(tag.raw, "data-width") || readAttr(tag.raw, "data-height")
+);
 function findRootTag(source, parsedTags) {
   const tags = parsedTags ?? parseHtmlStructure(source).tags;
   const bodyTag = tags.find((tag) => tag.name === "body");
-  if (bodyTag && (readDecodedAttr(bodyTag.raw, "data-composition-id") || readAttr(bodyTag.raw, "data-width") || readAttr(bodyTag.raw, "data-height"))) {
-    return bodyTag;
-  }
+  if (bodyTag && hasCompositionMarker(bodyTag)) return bodyTag;
   const bodyStart = bodyTag ? bodyTag.index + bodyTag.raw.length : 0;
   const bodyEnd = bodyTag?.closeIndex ?? source.length;
   const bodyTags = tags.filter((tag) => tag.index >= bodyStart && tag.index < bodyEnd);
@@ -84,7 +85,8 @@ function findRootTag(source, parsedTags) {
   for (const tag of bodyTags) {
     if (tag.index < skipBefore) continue;
     if (["script", "style", "meta", "link", "title"].includes(tag.name)) continue;
-    if (tag.name === "svg" && !readDecodedAttr(tag.raw, "data-composition-id") && !readAttr(tag.raw, "data-width") && !readAttr(tag.raw, "data-height")) {
+    if ((tag.name === "html" || tag.name === "head") && !hasCompositionMarker(tag)) continue;
+    if (tag.name === "svg" && !hasCompositionMarker(tag)) {
       skipBefore = tag.endIndex ?? Infinity;
       continue;
     }
@@ -108,10 +110,7 @@ function hasUnquotedLessThan(attrs) {
   return false;
 }
 function readAttr(tagSource, attr) {
-  if (!tagSource) return null;
-  const escaped = attr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const match = tagSource.match(new RegExp(`(?<![\\w-])${escaped}\\s*=\\s*["']([^"']+)["']`, "i"));
-  return match?.[1] || null;
+  return readAttributeValue(tagSource, attr, false) || null;
 }
 function hasAttrName(tagSource, attr) {
   return readDecodedAttr(tagSource, attr) !== null;
@@ -134,15 +133,18 @@ function mediaWindowsOverlap(a, b) {
   return a.start < b.end && b.start < a.end;
 }
 function readDecodedAttr(tagSource, attr) {
+  return readAttributeValue(tagSource, attr, true);
+}
+function readAttributeValue(tagSource, attr, decodeEntities) {
   if (!tagSource) return null;
   let value = null;
   const parser = new Parser(
     {
-      onattribute(name, decodedValue) {
-        if (value === null && name.toLowerCase() === attr.toLowerCase()) value = decodedValue;
+      onattribute(name, attributeValue) {
+        if (value === null && name.toLowerCase() === attr.toLowerCase()) value = attributeValue;
       }
     },
-    { decodeEntities: true, lowerCaseAttributeNames: false, lowerCaseTags: true }
+    { decodeEntities, lowerCaseAttributeNames: false, lowerCaseTags: true }
   );
   parser.end(tagSource);
   return value;
@@ -709,7 +711,8 @@ function buildLintContext(html, options = {}) {
       content: style.content,
       raw: style.content,
       index: -1,
-      file: style.file ?? style.href
+      file: style.file ?? style.href,
+      rootRelativePath: style.rootRelativePath
     }))
   ];
   const scripts = structure.scripts;
@@ -745,6 +748,12 @@ import {
   HTML_BODY_CSS_HEIGHT_FIRST_RE,
   VIEWPORT_META_SIZE_RE
 } from "@hyperframes/parsers/composition";
+var SCRIPT_SYNTAX_EXEMPT_TYPES = /* @__PURE__ */ new Set([
+  "application/json",
+  "application/hyperframes-slideshow+json",
+  "importmap",
+  "module"
+]);
 function repeatedDescendantId(selector) {
   let repeated = null;
   const requiredPseudoIds = (pseudo) => {
@@ -1101,7 +1110,7 @@ var coreRules = [
   },
   // root_missing_composition_id + root_missing_dimensions
   // fallow-ignore-next-line complexity
-  ({ rootTag }) => {
+  ({ rootTag, options }) => {
     const findings = [];
     if (!rootTag || !readDecodedAttr(rootTag.raw, "data-composition-id")) {
       findings.push({
@@ -1113,7 +1122,7 @@ var coreRules = [
         snippet: truncateSnippet(rootTag?.raw || "")
       });
     }
-    if (!rootTag || !readAttr(rootTag.raw, "data-width") || !readAttr(rootTag.raw, "data-height")) {
+    if (!options.isSubComposition && (!rootTag || !readAttr(rootTag.raw, "data-width") || !readAttr(rootTag.raw, "data-height"))) {
       findings.push({
         code: "root_missing_dimensions",
         severity: "error",
@@ -1363,10 +1372,8 @@ var coreRules = [
   ({ scripts, locate }) => {
     const findings = [];
     for (const script of scripts) {
-      const attrs = script.attrs || "";
-      if (/\bsrc\s*=/.test(attrs) || /\btype\s*=\s*["'](?:application\/json|application\/hyperframes-slideshow\+json|importmap|module)["']/.test(
-        attrs
-      ))
+      const type = readDecodedAttr(script.raw, "type")?.trim().toLowerCase() ?? "";
+      if (readDecodedAttr(script.raw, "src") !== null || SCRIPT_SYNTAX_EXEMPT_TYPES.has(type))
         continue;
       const syntaxError = getInlineScriptSyntaxError(script.content);
       if (!syntaxError) continue;
@@ -1783,6 +1790,7 @@ function findImperativeMediaControlFindings(ctx) {
   };
   if (mediaTags.length === 0 || ctx.scripts.length === 0) return findings;
   for (const script of ctx.scripts) {
+    const code = stripJsCode(script.content);
     const mediaVars = /* @__PURE__ */ new Map();
     const assignmentPatterns = [
       {
@@ -1799,6 +1807,7 @@ function findImperativeMediaControlFindings(ctx) {
     for (const { pattern, variableIndex, targetIndex } of assignmentPatterns) {
       let match;
       while ((match = pattern.exec(script.content)) !== null) {
+        if (code[match.index] !== script.content[match.index]) continue;
         const variableName = match[variableIndex];
         const target = match[targetIndex];
         if (!variableName || !target) continue;
@@ -1809,12 +1818,12 @@ function findImperativeMediaControlFindings(ctx) {
     }
     const directIdPatterns = [
       {
-        pattern: /\b(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)\.play\s*\(/g,
+        pattern: /\b(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)\s*(?:\?\.|\.)\s*play\s*(?:\?\.\s*)?\(/g,
         kind: "play()",
         targetIndex: 1
       },
       {
-        pattern: /\b(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)\.pause\s*\(/g,
+        pattern: /\b(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)\s*(?:\?\.|\.)\s*pause\s*(?:\?\.\s*)?\(/g,
         kind: "pause()",
         targetIndex: 1
       },
@@ -1829,12 +1838,12 @@ function findImperativeMediaControlFindings(ctx) {
         targetIndex: 1
       },
       {
-        pattern: /\b(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\1\s*\)\.play\s*\(/g,
+        pattern: /\b(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\1\s*\)\s*(?:\?\.|\.)\s*play\s*(?:\?\.\s*)?\(/g,
         kind: "play()",
         targetIndex: 2
       },
       {
-        pattern: /\b(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\1\s*\)\.pause\s*\(/g,
+        pattern: /\b(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\1\s*\)\s*(?:\?\.|\.)\s*pause\s*(?:\?\.\s*)?\(/g,
         kind: "pause()",
         targetIndex: 2
       },
@@ -1852,6 +1861,7 @@ function findImperativeMediaControlFindings(ctx) {
     for (const { pattern, kind, targetIndex } of directIdPatterns) {
       let match;
       while ((match = pattern.exec(script.content)) !== null) {
+        if (code[match.index] !== script.content[match.index]) continue;
         const target = match[targetIndex];
         if (!target) continue;
         const elementId = mediaIndex.ids.has(target) ? target : selectorTargetsManagedMedia(target, mediaIndex) ? void 0 : null;
@@ -1869,8 +1879,20 @@ function findImperativeMediaControlFindings(ctx) {
     for (const [variableName, elementId] of mediaVars) {
       const escapedVar = escapeRegExp(variableName);
       const variablePatterns = [
-        { pattern: new RegExp(`\\b${escapedVar}\\.play\\s*\\(`, "g"), kind: "play()" },
-        { pattern: new RegExp(`\\b${escapedVar}\\.pause\\s*\\(`, "g"), kind: "pause()" },
+        {
+          pattern: new RegExp(
+            `\\b${escapedVar}\\s*(?:\\?\\.|\\.)\\s*play\\s*(?:\\?\\.\\s*)?\\(`,
+            "g"
+          ),
+          kind: "play()"
+        },
+        {
+          pattern: new RegExp(
+            `\\b${escapedVar}\\s*(?:\\?\\.|\\.)\\s*pause\\s*(?:\\?\\.\\s*)?\\(`,
+            "g"
+          ),
+          kind: "pause()"
+        },
         { pattern: new RegExp(`\\b${escapedVar}\\.currentTime\\s*=`, "g"), kind: "currentTime" },
         {
           pattern: new RegExp(`\\b${escapedVar}\\.muted\\s*=`, "g"),
@@ -1880,6 +1902,7 @@ function findImperativeMediaControlFindings(ctx) {
       for (const { pattern, kind } of variablePatterns) {
         let match;
         while ((match = pattern.exec(script.content)) !== null) {
+          if (code[match.index] !== script.content[match.index]) continue;
           findings.push({
             code: "imperative_media_control",
             severity: "error",
@@ -2582,6 +2605,24 @@ function extractCssUrlReferences(css) {
   }
   return out;
 }
+function folderDepth(filePath) {
+  if (/^(?:[a-z]:)?[\\/]/i.test(filePath)) return 0;
+  let depth = 0;
+  for (const segment of filePath.split(/[\\/]/).slice(0, -1)) {
+    if (segment === "..") depth = Math.max(0, depth - 1);
+    else if (segment && segment !== ".") depth += 1;
+  }
+  return depth;
+}
+function climbsAboveRoot(fileDepth, path) {
+  let depth = fileDepth;
+  for (const segment of path.split("/")) {
+    if (segment === "..") depth -= 1;
+    else if (segment && segment !== ".") depth += 1;
+    if (depth < 0) return true;
+  }
+  return false;
+}
 function extractCssSelectors(css) {
   const out = [];
   const noComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
@@ -2895,42 +2936,31 @@ var compositionRules = [
     }
     return findings;
   },
-  // invalid_parent_traversal_in_asset_path — catches `../` traversal in src,
-  // href, inline-style url(), and <style> url() asset references on
-  // compositions. Sub-compositions live under compositions/ but are served
-  // with the project root as their base URL, so any `../`-traversing path
-  // climbs above the project root and 404s in Studio preview. Renders
-  // tolerate it because the server-side bundler rewrites `../foo` against
-  // each sub-composition's source path; the runtime now mirrors that fallback
-  // (see rewriteSubCompositionAssetPaths in runtime/compositionLoader.ts), but
-  // the authoring-time signal is still wrong — flag it at lint time so the
-  // baked path is plain root-relative and matches what the bundler emits.
-  //
-  // Mirrors the runtime fallback's surface: `[src]` / `[href]` attribute
-  // values, `[style]` inline url(), and `<style>` block url() references.
-  // Skips absolute URLs (http(s)://, //, data:, /-prefixed root-relative),
-  // hash anchors, and plain relative paths (`assets/x.mp4`) — only `../`
-  // traversal is flagged. Subsumes the older `../capture/`-specific rule.
+  // invalid_parent_traversal_in_asset_path — a `../` path in src, href or a CSS url() that leaves
+  // the project once resolved from the file's own folder, as the bundler, producer and runtime
+  // resolve it. "../assets/x" from compositions/ stays inside and passes.
   // fallow-ignore-next-line complexity
   ({ tags, styles, rawSource, options }) => {
     if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
     const offenders = [];
-    const collect = (value) => {
-      if (!value) return;
-      const trimmed = value.trim();
-      if (!trimmed.startsWith("../") && trimmed !== "..") return;
-      offenders.push(trimmed);
+    const fileDepth = folderDepth(options.compSrcPath ?? "index.html");
+    const collect = (value, depth = fileDepth) => {
+      const trimmed = value?.trim() ?? "";
+      if (/^(?:[a-z][a-z0-9+.-]*:|[\\/#])/i.test(trimmed)) return;
+      const path = (trimmed.split(/[?#]/, 1)[0] ?? "").replace(/\\|%2f/gi, "/").replace(/%2e/gi, ".");
+      if (climbsAboveRoot(depth, path)) offenders.push(trimmed);
     };
     for (const tag of tags) {
-      collect(readAttr(tag.raw, "src"));
-      collect(readAttr(tag.raw, "href"));
+      collect(readDecodedAttr(tag.raw, "src"));
+      collect(readDecodedAttr(tag.raw, "href"));
       const styleAttr = readJsonAttr(tag.raw, "style");
       if (styleAttr) {
         for (const url of extractCssUrlReferences(styleAttr)) collect(url);
       }
     }
     for (const style of styles) {
-      for (const url of extractCssUrlReferences(style.content)) collect(url);
+      const depth = style.rootRelativePath ? folderDepth(style.rootRelativePath) : fileDepth;
+      for (const url of extractCssUrlReferences(style.content)) collect(url, depth);
     }
     if (offenders.length === 0) return [];
     const prefixCounts = /* @__PURE__ */ new Map();
@@ -2943,8 +2973,8 @@ var compositionRules = [
       {
         code: "invalid_parent_traversal_in_asset_path",
         severity: "error",
-        message: `Found ${offenders.length} asset path(s) traversing above the project root with "../" (${prefixSummary}). Renders rewrite this against each sub-composition's source path, but Studio preview and other live consumers resolve against the project root and 404.`,
-        fixHint: 'Use plain root-relative paths (e.g. "assets/...", "capture/...", "fonts/...") \u2014 compositions are served with the project root as their base URL, so paths must be root-relative, not relative to the compositions/ directory.'
+        message: `Found ${offenders.length} asset path(s) traversing above the project root with "../" (${prefixSummary}), resolved from the folder of the file that holds them. Render and preview clamp them to the project root or resolve them outside it, so they load a different file than written, or none.`,
+        fixHint: `Point the path at a file inside the project: from compositions/scene.html, "../assets/x.png" and "assets/x.png" both reach the project's assets folder.`
       }
     ];
   },