@jay-framework/seo-validator 0.19.0

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { JayHtmlValidatorFn } from '@jay-framework/compiler-shared';
+
+declare const validate: JayHtmlValidatorFn;
+
+export { validate };

package/dist/index.js

@@ -0,0 +1,103 @@
+import { walkElements } from "@jay-framework/compiler-shared";
+const validate = (ctx) => {
+  const findings = [];
+  let hasH1 = false;
+  let h1Count = 0;
+  let lastHeadingLevel = 0;
+  walkElements(ctx.body, ctx, (el) => {
+    const tag = el.rawTagName?.toLowerCase();
+    if (!tag)
+      return;
+    if (tag === "img") {
+      const alt = el.getAttribute?.("alt");
+      if (alt === void 0 || alt === null) {
+        findings.push({
+          severity: "warning",
+          message: "Image missing alt attribute — hurts SEO and accessibility",
+          suggestion: 'Add an alt attribute with descriptive text. For decorative images use alt="".',
+          element: "<img>",
+          attribute: "alt"
+        });
+      }
+      const width = el.getAttribute?.("width");
+      const height = el.getAttribute?.("height");
+      const srcset = el.getAttribute?.("srcset");
+      if (!width || !height) {
+        const style = el.getAttribute?.("style") || "";
+        const hasInlineWidth = /width\s*:/.test(style);
+        const hasInlineHeight = /height\s*:/.test(style);
+        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.',
+            element: "<img>",
+            attribute: "width"
+          });
+        }
+      }
+      const loading = el.getAttribute?.("loading");
+      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.',
+          element: "<img>",
+          attribute: "loading"
+        });
+      }
+    }
+    if (tag === "a") {
+      const href = el.getAttribute?.("href");
+      const text = el.textContent?.trim();
+      if (href && (!text || text.length === 0) && !el.querySelector?.("img")) {
+        const ariaLabel = el.getAttribute?.("aria-label");
+        if (!ariaLabel) {
+          findings.push({
+            severity: "warning",
+            message: "Anchor element has no visible text or aria-label — bad for SEO link signals",
+            suggestion: "Add descriptive text content inside the <a> tag, or add an aria-label attribute.",
+            element: "<a>",
+            attribute: "href"
+          });
+        }
+      }
+    }
+    const headingMatch = tag.match(/^h([1-6])$/);
+    if (headingMatch) {
+      const level = parseInt(headingMatch[1], 10);
+      if (level === 1) {
+        hasH1 = true;
+        h1Count++;
+      }
+      if (lastHeadingLevel > 0 && level > lastHeadingLevel + 1) {
+        findings.push({
+          severity: "warning",
+          message: `Heading level skipped: <h${lastHeadingLevel}> followed by <h${level}>`,
+          suggestion: `Use <h${lastHeadingLevel + 1}> instead of <h${level}> to maintain heading hierarchy. Search engines use heading structure to understand content organization.`,
+          element: `<h${level}>`
+        });
+      }
+      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>"
+    });
+  }
+  return findings;
+};
+export {
+  validate
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@jay-framework/seo-validator",
+  "version": "0.19.0",
+  "type": "module",
+  "description": "SEO validation plugin for Jay Framework — checks jay-html templates for SEO best practices",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "plugin.yaml"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./plugin.yaml": "./plugin.yaml"
+  },
+  "scripts": {
+    "build": "npm run clean && npm run build:server && npm run build:types && npm run validate",
+    "validate": "jay-stack-cli validate-plugin",
+    "build:server": "vite build --ssr",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run test",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@jay-framework/compiler-shared": "^0.19.0"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "^0.19.0",
+    "@jay-framework/jay-stack-cli": "^0.19.0",
+    "@types/node": "^22.15.21",
+    "node-html-parser": "^6.1.0",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}

package/plugin.yaml

@@ -0,0 +1,6 @@
+name: seo-validator
+
+validators:
+  - name: seo
+    handler: validate
+    description: Validates jay-html templates for SEO best practices