@jay-framework/seo-validator 0.22.2 → 0.23.1

package/dist/index.js

@@ -1,28 +1,38 @@
 import { walkElements } from "@jay-framework/compiler-shared";
 import * as fs from "node:fs";
 import * as path from "node:path";
+function isComponent(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  return normalized.includes("/components/");
+}
 const validate = (ctx) => {
   const findings = [];
+  const isComp = isComponent(ctx.filePath);
   let hasH1 = false;
   let h1Count = 0;
   let lastHeadingLevel = 0;
   let hasMain = false;
-  let hasImage = false;
+  const LARGE_IMAGE_THRESHOLD = 200;
+  let hasLargeImage = false;
   let hasFetchPriorityHigh = false;
   walkElements(ctx.body, ctx, (el) => {
     const tag = el.rawTagName?.toLowerCase();
-    if (!tag)
-      return;
+    if (!tag) return;
     if (tag === "img") {
-      hasImage = true;
+      const w = parseInt(el.getAttribute?.("width") || "", 10);
+      const h = parseInt(el.getAttribute?.("height") || "", 10);
+      const hasExplicitSize = !isNaN(w) && !isNaN(h);
+      const isLarge = !hasExplicitSize || w >= LARGE_IMAGE_THRESHOLD || h >= LARGE_IMAGE_THRESHOLD;
+      if (isLarge) hasLargeImage = true;
       if (el.getAttribute?.("fetchpriority") === "high") {
         hasFetchPriorityHigh = true;
       }
       const alt = el.getAttribute?.("alt");
+      const imgTag = el.outerHTML?.split(">")[0] + ">" || "<img>";
       if (alt === void 0 || alt === null) {
         findings.push({
           severity: "warning",
-          message: "Image missing alt attribute — hurts SEO and accessibility",
+          message: `Image missing alt attribute: ${imgTag}`,
           suggestion: 'Add an alt attribute with descriptive text. For decorative images use alt="".',
           element: "<img>",
           attribute: "alt"
@@ -38,8 +48,8 @@ const validate = (ctx) => {
         if ((!hasInlineWidth || !hasInlineHeight) && !srcset) {
           findings.push({
             severity: "warning",
-            message: "Image missing explicit dimensions — causes layout shift (CLS)",
-            suggestion: 'Add width and height attributes to prevent Cumulative Layout Shift. Example: <img width="800" height="600" ... />. For responsive images, use srcset with sizes. CLS is a Core Web Vital that affects search ranking.',
+            message: `Image missing explicit dimensions — causes layout shift (CLS): ${imgTag}`,
+            suggestion: 'Add width and height attributes to prevent Cumulative Layout Shift. Example: <img width="800" height="600" ... />. For small icons, add the actual size (e.g., width="20" height="20"). For responsive images, use srcset with sizes. CLS is a Core Web Vital that affects search ranking.',
             element: "<img>",
             attribute: "width"
           });
@@ -49,8 +59,8 @@ const validate = (ctx) => {
       if (!loading) {
         findings.push({
           severity: "warning",
-          message: "Image without loading attribute — consider lazy loading for performance",
-          suggestion: 'Add loading="lazy" to defer off-screen images. Use loading="eager" only for above-the-fold images.',
+          message: `Image without loading attribute: ${imgTag}`,
+          suggestion: 'Add loading="lazy" for off-screen images, or loading="eager" for above-the-fold images. Either value suppresses this warning.',
           element: "<img>",
           attribute: "loading"
         });
@@ -93,44 +103,45 @@ const validate = (ctx) => {
       lastHeadingLevel = level;
     }
   });
-  if (!hasH1) {
-    findings.push({
-      severity: "warning",
-      message: "Page has no <h1> element — the primary heading is important for SEO",
-      suggestion: "Add an <h1> element with the main page title or topic. Each page should have exactly one <h1>.",
-      element: "<h1>"
-    });
-  } else if (h1Count > 1) {
-    findings.push({
-      severity: "warning",
-      message: `Page has ${h1Count} <h1> elements — should have exactly one`,
-      suggestion: "Keep only one <h1> for the primary page heading. Use <h2> or lower for secondary headings.",
-      element: "<h1>"
-    });
-  }
-  if (!hasMain) {
-    findings.push({
-      severity: "warning",
-      message: "Page has no <main> landmark — helps search engines identify primary content",
-      suggestion: "Wrap the primary page content in a <main> element. Each page should have one <main> landmark.",
-      element: "<main>"
-    });
-  }
-  if (hasImage && !hasFetchPriorityHigh) {
-    findings.push({
-      severity: "warning",
-      message: 'No image has fetchpriority="high" — the LCP image should be prioritized',
-      suggestion: 'Add fetchpriority="high" to the largest above-the-fold image (the LCP candidate). This tells the browser to download it first, improving Largest Contentful Paint.',
-      element: "<img>",
-      attribute: "fetchpriority"
-    });
+  if (!isComp) {
+    if (!hasH1) {
+      findings.push({
+        severity: "warning",
+        message: "Page has no <h1> element — the primary heading is important for SEO",
+        suggestion: "Add an <h1> element with the main page title or topic. Each page should have exactly one <h1>.",
+        element: "<h1>"
+      });
+    } else if (h1Count > 1) {
+      findings.push({
+        severity: "warning",
+        message: `Page has ${h1Count} <h1> elements — should have exactly one`,
+        suggestion: "Keep only one <h1> for the primary page heading. Use <h2> or lower for secondary headings.",
+        element: "<h1>"
+      });
+    }
+    if (!hasMain) {
+      findings.push({
+        severity: "warning",
+        message: "Page has no <main> landmark — helps search engines identify primary content",
+        suggestion: "Wrap the primary page content in a <main> element. Each page should have one <main> landmark.",
+        element: "<main>"
+      });
+    }
+    if (hasLargeImage && !hasFetchPriorityHigh) {
+      findings.push({
+        severity: "warning",
+        message: 'No image has fetchpriority="high" — the LCP image should be prioritized',
+        suggestion: 'Add fetchpriority="high" to the largest above-the-fold image (the LCP candidate). This tells the browser to download it first, improving Largest Contentful Paint.',
+        element: "<img>",
+        attribute: "fetchpriority"
+      });
+    }
   }
   const cssSources = [];
   const styleBlocks = ctx.body.querySelectorAll?.("style") ?? [];
   for (const styleEl of styleBlocks) {
     const cssText = styleEl.textContent || "";
-    if (cssText)
-      cssSources.push({ css: cssText, source: "<style>" });
+    if (cssText) cssSources.push({ css: cssText, source: "<style>" });
   }
   const linkedFiles = ctx.body.querySelectorAll?.('link[rel="stylesheet"]') ?? [];
   for (const link of linkedFiles) {
@@ -160,6 +171,7 @@ const validate = (ctx) => {
       }
     }
   }
+  if (isComp) return findings;
   const componentHeadTags = new Set(
     ctx.headlessImports.flatMap((imp) => imp.providedHeadTags ?? [])
   );
@@ -207,6 +219,50 @@ const validate = (ctx) => {
         attribute: "content"
       });
     }
+    const preconnectOrigins = new Set(
+      ctx.head.links.filter((l) => l.rel === "preconnect").map((l) => {
+        try {
+          return new URL(l.href.map((p) => p.value).join("")).origin;
+        } catch {
+          return "";
+        }
+      }).filter(Boolean)
+    );
+    const FONT_SERVICE_DOMAINS = ["fonts.googleapis.com", "use.typekit.net"];
+    for (const link of ctx.head.links) {
+      if (link.rel !== "stylesheet") continue;
+      const href = link.href.map((p) => p.value).join("");
+      if (!href.startsWith("http://") && !href.startsWith("https://")) continue;
+      let origin;
+      let hostname;
+      try {
+        const parsed = new URL(href);
+        origin = parsed.origin;
+        hostname = parsed.hostname;
+      } catch {
+        continue;
+      }
+      if (!preconnectOrigins.has(origin)) {
+        findings.push({
+          severity: "warning",
+          message: `External stylesheet from ${hostname} without <link rel="preconnect"> — delays resource discovery`,
+          suggestion: `Add <link rel="preconnect" href="${origin}"> before the stylesheet in <head>. Preconnect establishes the connection early, reducing load time.`,
+          element: "<link>",
+          attribute: "href"
+        });
+      }
+      if (FONT_SERVICE_DOMAINS.some((d) => hostname === d || hostname.endsWith("." + d))) {
+        if (!href.includes("display=swap")) {
+          findings.push({
+            severity: "warning",
+            message: `Font stylesheet from ${hostname} missing display=swap — blocks text rendering`,
+            suggestion: "Add &display=swap to the font URL to avoid invisible text while fonts load. Example: https://fonts.googleapis.com/css2?family=Inter&display=swap",
+            element: "<link>",
+            attribute: "href"
+          });
+        }
+      }
+    }
   }
   return findings;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/seo-validator",
-  "version": "0.22.2",
+  "version": "0.23.1",
   "type": "module",
   "description": "SEO validation plugin for Jay Framework — checks jay-html templates for SEO best practices",
   "license": "Apache-2.0",
@@ -24,11 +24,11 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@jay-framework/compiler-shared": "^0.22.2"
+    "@jay-framework/compiler-shared": "^0.23.1"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.22.2",
-    "@jay-framework/jay-stack-cli": "^0.22.2",
+    "@jay-framework/dev-environment": "^0.23.1",
+    "@jay-framework/jay-stack-cli": "^0.23.1",
     "@types/node": "^22.15.21",
     "node-html-parser": "^6.1.0",
     "rimraf": "^5.0.5",