@dukebot/astro-html-validator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dukebot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# astro-html-validator
+
+Validate Astro-generated HTML output (`dist`) to catch common technical SEO issues:
+
+- broken internal links,
+- missing or invalid JSON-LD blocks,
+- missing SEO metadata (`title`, `description`, `og:*`, etc.).
+
+You can use it as:
+
+1. a **CLI** (great for CI/CD),
+2. a **reusable Node library** shared across projects.
+
+---
+
+## Installation
+
+```bash
+npm install -D @dukebot/astro-html-validator
+```
+
+---
+
+## CLI usage
+
+### Default command
+
+```bash
+npx astro-html-validator
+```
+
+By default it validates `./dist` and runs all validators.
+
+### Run specific validators
+
+```bash
+npx astro-html-validator meta
+npx astro-html-validator links
+npx astro-html-validator jsonld,meta
+```
+
+### CLI options
+
+```bash
+astro-html-validator [selector] [options]
+
+Options:
+  --dir <path>      Path to the dist directory (default: <cwd>/dist)
+  --quiet           Disable summary output
+  --help            Show help
+```
+
+---
+
+## Programmatic usage (Node)
+
+```js
+import path from 'node:path';
+import { Validator } from '@dukebot/astro-html-validator';
+
+const validator = new Validator({
+  dirPath: path.resolve(process.cwd(), 'dist'),
+  config: {
+    jsonld: {},
+    links: {},
+    meta: {
+      metaTitleMinLength: 30,
+      metaTitleMaxLength: 60,
+      metaDescriptionMinLength: 70,
+      metaDescriptionMaxLength: 140,
+    },
+  },
+  print: true,
+});
+
+const results = await validator.run({ selector: 'all' });
+console.log(results);
+```
+
+---
+
+## Suggested scripts for your Astro project
+
+```json
+{
+  "scripts": {
+    "build": "astro build",
+    "validate:dist": "astro-html-validator",
+    "ci:seo": "npm run build && npm run validate:dist"
+  }
+}
+```
+
+---
+
+## Publish to npm
+
+Quick steps:
+
+1. Update `name`, `author`, and `version` in `package.json`.
+2. Sign in:
+
+   ```bash
+   npm login
+   ```
+
+3. Publish:
+
+   ```bash
+   npm publish --access public
+   ```
+
+
+
+
+

package/bin/cli.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { Validator } from '../src/index.mjs';
+
+/**
+ * Prints CLI usage information.
+ */
+function printHelp() {
+  console.log(`
+astro-html-validator
+
+Usage:
+  astro-html-validator [selector] [options]
+
+Selector:
+  all | jsonld | links | meta | jsonld,links,meta
+
+Options:
+  --dir <path>      Path to the dist directory (default: ./dist)
+  --quiet           Disable printed summary output
+  --help            Show help
+
+Examples:
+  astro-html-validator
+  astro-html-validator meta
+  astro-html-validator links --dir ./dist
+  astro-html-validator jsonld,meta
+`);
+}
+
+/**
+ * Parses CLI arguments into validator runtime options.
+ */
+function parseArgs(argv = process.argv.slice(2)) {
+  const options = {
+    selector: 'all',
+    dirPath: path.resolve(process.cwd(), 'dist'),
+    print: true,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg) continue;
+
+    if (!arg.startsWith('-') && options.selector === 'all') {
+      options.selector = arg;
+      continue;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === '--quiet') {
+      options.print = false;
+      continue;
+    }
+
+    if (arg === '--dir') {
+      const next = argv[index + 1];
+      if (!next) throw new Error('Missing value for --dir');
+      options.dirPath = path.resolve(process.cwd(), next);
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return options;
+}
+
+/**
+ * CLI entry point.
+ */
+async function main() {
+  const parsed = parseArgs();
+
+  if (parsed.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  console.log('\n=== Dist validation started ===');
+
+  const validator = new Validator({
+    dirPath: parsed.dirPath,
+    config: {},
+    print: parsed.print,
+  });
+
+  await validator.run({ selector: parsed.selector });
+
+  console.log('\n=== Dist validation completed ===');
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error('[ERROR] Dist validation failed:', error.message ?? error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dukebot/astro-html-validator",
+  "version": "1.0.0",
+  "description": "Validate Astro-generated HTML output for SEO metadata, JSON-LD, and internal links.",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./validator": "./src/validator.mjs"
+  },
+  "bin": {
+    "astro-html-validator": "bin/cli.mjs"
+  },
+  "files": [
+    "src/**/*.mjs",
+    "bin/cli.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "node ./bin/cli.mjs --help",
+    "validate:dist": "node ./bin/cli.mjs"
+  },
+  "keywords": [
+    "astro",
+    "seo",
+    "validator",
+    "html",
+    "jsonld"
+  ],
+  "author": "Dukebot",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.mjs

@@ -0,0 +1,4 @@
+import { Validator } from './validator.mjs';
+
+export { Validator };
+export default Validator;

package/src/utils.mjs

@@ -0,0 +1,92 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Throws if the given directory cannot be accessed.
+ */
+export async function ensureDirExists(dirPath) {
+  try {
+    await fs.access(dirPath);
+  } catch {
+    throw new Error(`Directory does not exist: ${dirPath}`);
+  }
+}
+
+/**
+ * Returns whether a file or directory exists.
+ */
+export async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Converts an HTML file path into a route-like URL.
+ */
+export function toRoute(filePath, rootDir) {
+  const rel = path.relative(rootDir, filePath).replace(/\\/g, '/');
+  if (rel === 'index.html') return '/';
+  if (rel.endsWith('/index.html')) return '/' + rel.replace(/\/index\.html$/, '');
+  return '/' + rel.replace(/\.html$/, '');
+}
+
+/**
+ * Normalized warning message format used by all validators.
+ */
+export function formatWarning(route, message) {
+  return `[WARN] ${route} -> ${message}`;
+}
+
+/**
+ * Reads an attribute value from an HTML tag string.
+ */
+export function getAttr(tag, attrName) {
+  const match = tag.match(new RegExp(`${attrName}=["']([^"']+)["']`, 'i'));
+  return match?.[1]?.trim();
+}
+
+/**
+ * Recursively collects all HTML files from a directory.
+ */
+export async function walkHtmlFiles(dirPath) {
+  const entries = await fs.readdir(dirPath, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) files.push(...(await walkHtmlFiles(fullPath)));
+    if (entry.isFile() && entry.name.endsWith('.html')) files.push(fullPath);
+  }
+
+  return files;
+}
+
+/**
+ * Shared runner for validators that operate page-by-page over HTML files.
+ */
+export async function runHtmlValidation({ dirPath, validatePage }) {
+  await ensureDirExists(dirPath);
+  const htmlFiles = await walkHtmlFiles(dirPath);
+  const warnings = [];
+
+  for (const filePath of htmlFiles) {
+    const route = toRoute(filePath, dirPath);
+    if (route.startsWith('/decapcms')) continue;
+
+    const html = await fs.readFile(filePath, 'utf8');
+    const pageWarnings = (await validatePage({ html, route, filePath })) ?? [];
+
+    for (const warning of pageWarnings) {
+      warnings.push(formatWarning(route, warning));
+    }
+  }
+
+  return {
+    checkedPages: htmlFiles.length,
+    warnings,
+  };
+}

package/src/validator.mjs

@@ -0,0 +1,98 @@
+import { validateJsonld } from './validators/jsonld.mjs';
+import { validateLinks } from './validators/links.mjs';
+import { validateMeta } from './validators/meta.mjs';
+
+/**
+ * Coordinates all available validators and prints optional summaries.
+ */
+export class Validator {
+  constructor({ dirPath, config = {}, print = true } = {}) {
+    this.dirPath = dirPath;
+
+    this.validators = {
+      jsonld: {
+        label: 'JSON-LD',
+        run: validateJsonld,
+        config: config.jsonld,
+      },
+      links: {
+        label: 'Internal links',
+        run: validateLinks,
+        config: config.links,
+      },
+      meta: {
+        label: 'SEO metadata',
+        run: validateMeta,
+        config: config.meta,
+      },
+    };
+
+    this.print = print;
+  }
+
+  /**
+   * Resolves a selector string into a unique list of validator names.
+   */
+  selectValidators(selector = 'all') {
+    const clean = selector.trim().toLowerCase();
+
+    if (clean === 'all') return Object.keys(this.validators);
+
+    const selected = clean
+      .split(',')
+      .map((item) => item.trim())
+      .filter(Boolean);
+
+    const invalid = selected.filter((name) => !this.validators[name]);
+    if (invalid.length > 0) {
+      throw new Error(
+        `Unknown validators: ${invalid.join(', ')}. ` +
+          `Valid options: all, ${Object.keys(this.validators).join(', ')}`
+      );
+    }
+
+    return [...new Set(selected)];
+  }
+
+  /**
+   * Prints a consistent summary for one validator result.
+   */
+  printResultSummary(result) {
+    console.log(`\n=== ${result.label} ===`);
+    console.log(`Checked ${result.checkedPages} HTML pages.`);
+
+    if (result.warnings.length === 0) {
+      console.log('✅ No warnings.');
+      return;
+    }
+
+    console.log(`⚠️  Warnings found: ${result.warnings.length}`);
+    for (const warning of result.warnings) console.log(warning);
+  }
+
+  /**
+   * Runs one validator by name.
+   */
+  async runValidator(name) {
+    const validator = this.validators[name];
+    const result = await validator.run(this.dirPath, validator.config);
+    result.label = validator.label;
+    if (this.print) this.printResultSummary(result);
+    return result;
+  }
+
+  /**
+   * Runs selected validators sequentially.
+   */
+  async run({ selector = 'all' } = {}) {
+    const results = [];
+    const selectedNames = this.selectValidators(selector);
+
+    for (const name of selectedNames) {
+      const result = await this.runValidator(name);
+      results.push(result);
+    }
+
+    return results;
+  }
+}

package/src/validators/jsonld.mjs

@@ -0,0 +1,74 @@
+import { runHtmlValidation } from '../utils.mjs';
+
+/**
+ * Extracts and parses JSON-LD script blocks from a page.
+ */
+function getJsonLdBlocks(html) {
+  const regex = /<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+  const blocks = [];
+  let match;
+
+  while ((match = regex.exec(html)) !== null) {
+    const raw = match[1]?.trim();
+    if (!raw) continue;
+    try {
+      blocks.push(JSON.parse(raw));
+    } catch {
+      blocks.push({ __parseError: true, __raw: raw });
+    }
+  }
+
+  return blocks;
+}
+
+/**
+ * Flattens top-level JSON-LD nodes and @graph nodes into one list.
+ */
+function getGraphNodes(blocks) {
+  const nodes = [];
+  for (const block of blocks) {
+    if (block.__parseError) continue;
+    if (Array.isArray(block['@graph'])) nodes.push(...block['@graph']);
+    else nodes.push(block);
+  }
+  return nodes;
+}
+
+/**
+ * Validates JSON-LD presence/basic parseability for each HTML page.
+ */
+export async function validateJsonld(dirPath) {
+  const { checkedPages, warnings } = await runHtmlValidation({
+    dirPath,
+    validatePage: ({ html }) => {
+      const pageWarnings = [];
+      const blocks = getJsonLdBlocks(html);
+
+      if (blocks.length === 0) {
+        pageWarnings.push('No JSON-LD block was found.');
+        return pageWarnings;
+      }
+
+      if (blocks.some((b) => b.__parseError)) {
+        pageWarnings.push('At least one JSON-LD block has invalid JSON.');
+        return pageWarnings;
+      }
+
+      const nodes = getGraphNodes(blocks);
+
+      if (nodes.length === 0) {
+        pageWarnings.push('JSON-LD exists but has no nodes in @graph.');
+        return pageWarnings;
+      }
+
+      return pageWarnings;
+    },
+  });
+
+  return {
+    name: 'jsonld',
+    label: 'JSON-LD',
+    checkedPages,
+    warnings,
+  };
+}

package/src/validators/links.mjs

@@ -0,0 +1,81 @@
+import path from 'node:path';
+import { pathExists, runHtmlValidation } from '../utils.mjs';
+
+/**
+ * Extracts local (root-relative) URLs from href/src attributes.
+ */
+function extractInternalUrls(html) {
+  const urls = new Set();
+  const regex = /(?:href|src)=["']([^"']+)["']/gi;
+
+  let match;
+  while ((match = regex.exec(html)) !== null) {
+    const raw = match[1]?.trim();
+    if (!raw) continue;
+
+    if (
+      raw.startsWith('http://') ||
+      raw.startsWith('https://') ||
+      raw.startsWith('//') ||
+      raw.startsWith('#') ||
+      raw.startsWith('mailto:') ||
+      raw.startsWith('tel:') ||
+      raw.startsWith('javascript:') ||
+      raw.startsWith('data:')
+    ) {
+      continue;
+    }
+
+    if (raw.startsWith('/')) {
+      const clean = raw.split('#')[0].split('?')[0];
+      if (clean) urls.add(clean);
+    }
+  }
+
+  return [...urls];
+}
+
+/**
+ * Checks whether an internal URL resolves to an HTML file in dist.
+ */
+async function internalUrlExists(dirPath, urlPath) {
+  if (urlPath === '/') return pathExists(path.join(dirPath, 'index.html'));
+
+  const asFile = path.join(dirPath, urlPath.replace(/^\//, ''));
+  if (await pathExists(asFile)) return true;
+
+  const asIndex = path.join(dirPath, urlPath.replace(/^\//, ''), 'index.html');
+  if (await pathExists(asIndex)) return true;
+
+  const asHtml = path.join(dirPath, `${urlPath.replace(/^\//, '')}.html`);
+  if (await pathExists(asHtml)) return true;
+
+  return false;
+}
+
+/**
+ * Reports broken internal links for each generated HTML page.
+ */
+export async function validateLinks(dirPath) {
+  const { checkedPages, warnings } = await runHtmlValidation({
+    dirPath,
+    validatePage: async ({ html }) => {
+      const pageWarnings = [];
+      const urls = extractInternalUrls(html);
+
+      for (const url of urls) {
+        const exists = await internalUrlExists(dirPath, url);
+        if (!exists) pageWarnings.push(`Internal link not found: ${url}`);
+      }
+
+      return pageWarnings;
+    },
+  });
+
+  return {
+    name: 'links',
+    label: 'Internal links',
+    checkedPages,
+    warnings,
+  };
+}

package/src/validators/meta.mjs

@@ -0,0 +1,130 @@
+import { getAttr, runHtmlValidation } from '../utils.mjs';
+
+// Core metadata tags expected on every page.
+const REQUIRED_META_CHECKS = [
+  { label: 'meta title', check: getTitleContent },
+  { label: 'meta description', check: (html) => hasMeta(html, 'description') },
+  { label: 'canonical', check: hasCanonical },
+  { label: 'meta robots', check: (html) => hasMeta(html, 'robots') },
+  { label: 'og:title', check: (html) => hasMeta(html, 'og:title', true) },
+  { label: 'og:description', check: (html) => hasMeta(html, 'og:description', true) },
+  { label: 'og:url', check: (html) => hasMeta(html, 'og:url', true) },
+  { label: 'og:type', check: (html) => hasMeta(html, 'og:type', true) },
+];
+
+function hasMeta(html, name, isProperty = false) {
+  const tags = html.match(/<meta\b[^>]*>/gi) || [];
+  return tags.some((tag) => {
+    const key = isProperty ? getAttr(tag, 'property') : getAttr(tag, 'name');
+    if (!key || key !== name) return false;
+    const content = getAttr(tag, 'content');
+    return !!content;
+  });
+}
+
+/**
+ * Returns the `content` value for a meta tag by name/property.
+ */
+function getMetaContent(html, name, isProperty = false) {
+  const tags = html.match(/<meta\b[^>]*>/gi) || [];
+  for (const tag of tags) {
+    const key = isProperty ? getAttr(tag, 'property') : getAttr(tag, 'name');
+    if (!key || key !== name) continue;
+    const content = getAttr(tag, 'content');
+    if (content) return content;
+  }
+  return '';
+}
+
+/**
+ * Checks that a canonical link tag exists with a non-empty href.
+ */
+function hasCanonical(html) {
+  const links = html.match(/<link\b[^>]*>/gi) || [];
+  return links.some((tag) => {
+    const rel = getAttr(tag, 'rel');
+    if (!rel || rel.toLowerCase() !== 'canonical') return false;
+    const href = getAttr(tag, 'href');
+    return !!href;
+  });
+}
+
+function getTitleContent(html) {
+  const match = html.match(/<title>([^<]+)<\/title>/i);
+  return match?.[1]?.trim() ?? '';
+}
+
+/**
+ * Validates optional length ranges for title/description fields.
+ */
+function validateLengthRange({ value, min = 1, max = Infinity, fieldLabel }) {
+  if (!value) return;
+  if (value.length >= min && value.length <= max) return;
+  return `Recommended ${fieldLabel} length is ${min}-${max}. Current: ${value.length}.`;
+}
+
+function validateRequiredMeta(html) {
+  const warnings = [];
+
+  for (const item of REQUIRED_META_CHECKS) {
+    if (!item.check(html)) {
+      warnings.push(`Missing ${item.label}.`);
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Runs required and optional SEO metadata checks for one HTML string.
+ */
+function validateHtmlMeta(
+  html,
+  {
+    metaTitleMinLength,
+    metaTitleMaxLength,
+    metaDescriptionMinLength,
+    metaDescriptionMaxLength,
+  } = {}
+) {
+  const warnings = [];
+
+  warnings.push(...validateRequiredMeta(html));
+
+  warnings.push(
+    validateLengthRange({
+      value: getTitleContent(html),
+      min: metaTitleMinLength,
+      max: metaTitleMaxLength,
+      fieldLabel: 'meta title',
+    })
+  );
+
+  warnings.push(
+    validateLengthRange({
+      value: getMetaContent(html, 'description'),
+      min: metaDescriptionMinLength,
+      max: metaDescriptionMaxLength,
+      fieldLabel: 'meta description',
+    })
+  );
+
+  return warnings.filter(Boolean);
+}
+
+/**
+ * Validates SEO metadata for every HTML page in dist.
+ */
+export async function validateMeta(dirPath, options) {
+  const { checkedPages, warnings } = await runHtmlValidation({
+    dirPath,
+    validatePage: ({ html }) => validateHtmlMeta(html, options),
+  });
+
+  return {
+    name: 'meta',
+    label: 'SEO metadata',
+    checkedPages,
+    warnings,
+  };
+}