@hyperframes/lint 0.8.49 → 0.8.50

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

@@ -5322,6 +5322,159 @@ 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(["img", "video", "audio"]);
+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) {
+  const intendedClip = (row) => !MEDIA_TAGS.has(row.tag) || row.attrs["data-start"] !== void 0 || row.attrs["data-track-index"] !== void 0;
+  return rows.filter(
+    (row) => row.attrs["data-duration"] === void 0 && row.attrs["data-end"] === void 0 && !isSubCompositionHost(row) && intendedClip(row)
+  ).map((row) => {
+    const isMedia = MEDIA_TAGS.has(row.tag);
+    return {
+      code: isMedia ? "media_missing_duration" : "timeline_element_missing_timing",
+      severity,
+      message: isMedia ? `${describe(row)} is media on the timeline without data-duration, so its clip has no length.` : `${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 +5485,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(
@@ -5794,7 +5948,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 +5961,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 +5993,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)