@hyperframes/lint 0.8.143 → 0.8.145

package/dist/index.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/index.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;
     }
@@ -712,7 +714,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;
@@ -1110,7 +1113,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({
@@ -1122,7 +1125,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",
@@ -2605,6 +2608,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, "");
@@ -2918,42 +2939,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();
@@ -2966,8 +2976,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.`
       }
     ];
   },
@@ -6749,7 +6759,7 @@ function collectExternalStyles(projectDir, html, compSrcPath) {
     document,
     compSrcPath
   )) {
-    styles.push({ href, content, file: join2(projectDir, rootRelativePath) });
+    styles.push({ href, content, file: join2(projectDir, rootRelativePath), rootRelativePath });
   }
   return styles;
 }
@@ -6801,6 +6811,7 @@ async function lintProject(projectDir, entryFile, hostOptions = {}) {
   const rootResult = await lintHyperframeHtml(rootHtml, {
     ...hostOptions,
     filePath: indexPath,
+    compSrcPath: rootFile,
     externalStyles: collectExternalStyles(projectDir, rootHtml, rootCompSrcPath)
   });
   results.push({ file: rootFile, result: rootResult, contentHash: contentDigest(rootHtml) });
@@ -6834,6 +6845,7 @@ async function lintProject(projectDir, entryFile, hostOptions = {}) {
         ...hostOptions,
         filePath,
         isSubComposition: true,
+        compSrcPath,
         externalStyles: collectExternalStyles(projectDir, html, compSrcPath)
       });
       results.push({