mcp-web-validator 1.0.0 → 1.2.0

package/dist/screenshot.js

@@ -1,11 +1,113 @@
 import puppeteer from "puppeteer";
 import * as path from "path";
 import * as fs from "fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { assertPublicHttpUrl, getErrorMessage } from "./network.js";
 const DEFAULT_VIEWPORTS = [
     { name: "desktop", width: 1440, height: 900 },
     { name: "tablet", width: 768, height: 1024 },
     { name: "mobile", width: 375, height: 812 }
 ];
+const MAX_VIEWPORTS = 10;
+const MIN_VIEWPORT_DIMENSION = 100;
+const MAX_VIEWPORT_DIMENSION = 7_680;
+const SAFE_VIEWPORT_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+const NAVIGATION_TIMEOUT_MS = 30_000;
+export const SCREENSHOT_HEADLESS_MODE = "shell";
+function validateViewports(viewports) {
+    if (viewports.length === 0 || viewports.length > MAX_VIEWPORTS) {
+        throw new Error(`Between 1 and ${MAX_VIEWPORTS} viewports are required`);
+    }
+    const outputNames = new Set();
+    return viewports.map((viewport, index) => {
+        if (!viewport || typeof viewport !== "object") {
+            throw new Error(`Viewport #${index + 1} must be an object`);
+        }
+        if (typeof viewport.name !== "string" || !SAFE_VIEWPORT_NAME.test(viewport.name)) {
+            throw new Error(`Viewport #${index + 1} name must match ${SAFE_VIEWPORT_NAME.source}`);
+        }
+        for (const [label, value] of [["width", viewport.width], ["height", viewport.height]]) {
+            if (!Number.isSafeInteger(value)
+                || value < MIN_VIEWPORT_DIMENSION
+                || value > MAX_VIEWPORT_DIMENSION) {
+                throw new Error(`Viewport #${index + 1} ${label} must be an integer between ${MIN_VIEWPORT_DIMENSION} and ${MAX_VIEWPORT_DIMENSION}`);
+            }
+        }
+        const outputName = `${viewport.name}_${viewport.width}x${viewport.height}.png`.toLowerCase();
+        if (outputNames.has(outputName)) {
+            throw new Error(`Duplicate viewport output filename: ${outputName}`);
+        }
+        outputNames.add(outputName);
+        return { name: viewport.name, width: viewport.width, height: viewport.height };
+    });
+}
+function resolveContainedOutputPath(outputDirectory, fileName) {
+    const outputPath = path.resolve(outputDirectory, fileName);
+    const relativePath = path.relative(outputDirectory, outputPath);
+    if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+        throw new Error("Screenshot output path escapes the requested output directory");
+    }
+    return outputPath;
+}
+function isPathWithinDirectory(directory, filePath) {
+    const relativePath = path.relative(directory, filePath);
+    return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
+}
+async function assertLocalScreenshotRequestAllowed(requestUrl, localDirectory) {
+    if (requestUrl.hostname) {
+        throw new Error("Blocked local file request with a host name");
+    }
+    let resolvedPath;
+    try {
+        resolvedPath = await fs.realpath(fileURLToPath(requestUrl));
+    }
+    catch (error) {
+        throw new Error(`Blocked local file request: ${getErrorMessage(error)}`);
+    }
+    if (!isPathWithinDirectory(localDirectory, resolvedPath)) {
+        throw new Error("Blocked local file request outside the selected file directory");
+    }
+}
+async function assertScreenshotRequestAllowed(requestUrl, localDirectory) {
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(requestUrl);
+    }
+    catch {
+        throw new Error("Blocked invalid page request URL");
+    }
+    if (parsedUrl.protocol === "http:" || parsedUrl.protocol === "https:") {
+        await assertPublicHttpUrl(parsedUrl);
+        return;
+    }
+    if (parsedUrl.protocol === "data:" || parsedUrl.protocol === "blob:") {
+        return;
+    }
+    if (parsedUrl.protocol === "file:" && localDirectory) {
+        await assertLocalScreenshotRequestAllowed(parsedUrl, localDirectory);
+        return;
+    }
+    throw new Error(`Blocked unsupported page request protocol ${parsedUrl.protocol}`);
+}
+async function resolveScreenshotRequest(request, localDirectory, onBlocked) {
+    if (request.isInterceptResolutionHandled()) {
+        return;
+    }
+    try {
+        await assertScreenshotRequestAllowed(request.url(), localDirectory);
+        if (request.isInterceptResolutionHandled()) {
+            return;
+        }
+        await request.continue();
+    }
+    catch (error) {
+        onBlocked(getErrorMessage(error));
+        if (request.isInterceptResolutionHandled()) {
+            return;
+        }
+        await request.abort("blockedbyclient");
+    }
+}
 /**
  * Captures screenshots of a local HTML file or remote URL at different viewport sizes.
  * @param targetPath Local file path or HTTP(S) URL
@@ -13,23 +115,49 @@ const DEFAULT_VIEWPORTS = [
  * @param customViewports Optional custom viewport settings
  */
 export async function captureScreenshots(targetPath, outputDirectory, customViewports) {
-    const viewports = customViewports && customViewports.length > 0 ? customViewports : DEFAULT_VIEWPORTS;
+    if (typeof targetPath !== "string" || targetPath.trim() === "") {
+        throw new Error("targetPath must be a non-empty string");
+    }
+    if (typeof outputDirectory !== "string" || outputDirectory.trim() === "") {
+        throw new Error("outputDirectory must be a non-empty string");
+    }
+    const viewports = validateViewports(customViewports && customViewports.length > 0 ? customViewports : DEFAULT_VIEWPORTS);
+    const resolvedOutputDirectory = path.resolve(outputDirectory);
     // Resolve target to file:// URL if it is a local file path
-    let targetUrl = targetPath;
-    if (!targetPath.startsWith("http://") && !targetPath.startsWith("https://")) {
+    let targetUrl;
+    let localDirectory;
+    if (/^https?:\/\//i.test(targetPath)) {
+        targetUrl = (await assertPublicHttpUrl(targetPath)).href;
+    }
+    else {
         const absolutePath = path.resolve(targetPath);
-        targetUrl = `file://${absolutePath.replace(/\\/g, "/")}`;
+        const resolvedPath = await fs.realpath(absolutePath);
+        const stats = await fs.stat(resolvedPath);
+        if (!stats.isFile()) {
+            throw new Error(`Screenshot target is not a regular file: ${resolvedPath}`);
+        }
+        localDirectory = path.dirname(resolvedPath);
+        targetUrl = pathToFileURL(resolvedPath).href;
     }
     // Ensure output directory exists
-    await fs.mkdir(outputDirectory, { recursive: true });
-    // Launch browser in headless mode
+    await fs.mkdir(resolvedOutputDirectory, { recursive: true });
+    // Launch Puppeteer's bundled headless shell.
     const browser = await puppeteer.launch({
-        headless: true,
-        args: ["--no-sandbox", "--disable-setuid-sandbox"]
+        headless: SCREENSHOT_HEADLESS_MODE,
     });
     const results = [];
     try {
         const page = await browser.newPage();
+        page.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
+        let blockedRequestMessage;
+        await page.setRequestInterception(true);
+        page.on("request", (request) => {
+            void resolveScreenshotRequest(request, localDirectory, (message) => {
+                blockedRequestMessage ??= message;
+            }).catch(() => {
+                // Puppeteer will surface navigation failures; avoid an unhandled listener rejection.
+            });
+        });
         for (const vp of viewports) {
             await page.setViewport({
                 width: vp.width,
@@ -37,14 +165,22 @@ export async function captureScreenshots(targetPath, outputDirectory, customView
                 deviceScaleFactor: 1
             });
             // Load URL (wait until network is idle or DOM loaded)
-            await page.goto(targetUrl, {
-                waitUntil: "domcontentloaded",
-                timeout: 30000
-            });
+            try {
+                await page.goto(targetUrl, {
+                    waitUntil: "domcontentloaded",
+                    timeout: NAVIGATION_TIMEOUT_MS,
+                });
+            }
+            catch (error) {
+                if (blockedRequestMessage) {
+                    throw new Error(`Screenshot navigation blocked: ${blockedRequestMessage}`);
+                }
+                throw new Error(`Screenshot navigation failed: ${getErrorMessage(error)}`);
+            }
             // Short wait for any animations or layout adjustments to settle
             await new Promise((resolve) => setTimeout(resolve, 500));
             const fileName = `${vp.name}_${vp.width}x${vp.height}.png`;
-            const outputPath = path.join(outputDirectory, fileName);
+            const outputPath = resolveContainedOutputPath(resolvedOutputDirectory, fileName);
             await page.screenshot({
                 path: outputPath,
                 fullPage: false // Captures above the fold viewport
@@ -53,7 +189,7 @@ export async function captureScreenshots(targetPath, outputDirectory, customView
                 viewportName: vp.name,
                 width: vp.width,
                 height: vp.height,
-                outputPath: path.resolve(outputPath)
+                outputPath
             });
         }
     }

package/dist/screenshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../src/screenshot.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../src/screenshot.ts"],"names":[],"mappings":"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","sourcesContent":["import puppeteer from \"puppeteer\";\nimport * as path from \"path\";\nimport * as fs from \"fs/promises\";\nimport { fileURLToPath, pathToFileURL } from \"node:url\";\nimport { assertPublicHttpUrl, getErrorMessage } from \"./network.js\";\n\nexport interface ViewportConfig {\n  name: string;\n  width: number;\n  height: number;\n}\n\nexport interface ScreenshotResult {\n  viewportName: string;\n  width: number;\n  height: number;\n  outputPath: string;\n}\n\nconst DEFAULT_VIEWPORTS: ViewportConfig[] = [\n  { name: \"desktop\", width: 1440, height: 900 },\n  { name: \"tablet\", width: 768, height: 1024 },\n  { name: \"mobile\", width: 375, height: 812 }\n];\n\nconst MAX_VIEWPORTS = 10;\nconst MIN_VIEWPORT_DIMENSION = 100;\nconst MAX_VIEWPORT_DIMENSION = 7_680;\nconst SAFE_VIEWPORT_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;\nconst NAVIGATION_TIMEOUT_MS = 30_000;\n\nexport const SCREENSHOT_HEADLESS_MODE = \"shell\" as const;\n\ninterface InterceptedRequest {\n  url(): string;\n  isInterceptResolutionHandled(): boolean;\n  continue(): Promise<unknown>;\n  abort(errorCode?: string): Promise<unknown>;\n}\n\nfunction validateViewports(viewports: ViewportConfig[]): ViewportConfig[] {\n  if (viewports.length === 0 || viewports.length > MAX_VIEWPORTS) {\n    throw new Error(`Between 1 and ${MAX_VIEWPORTS} viewports are required`);\n  }\n\n  const outputNames = new Set<string>();\n  return viewports.map((viewport, index) => {\n    if (!viewport || typeof viewport !== \"object\") {\n      throw new Error(`Viewport #${index + 1} must be an object`);\n    }\n    if (typeof viewport.name !== \"string\" || !SAFE_VIEWPORT_NAME.test(viewport.name)) {\n      throw new Error(\n        `Viewport #${index + 1} name must match ${SAFE_VIEWPORT_NAME.source}`,\n      );\n    }\n    for (const [label, value] of [[\"width\", viewport.width], [\"height\", viewport.height]] as const) {\n      if (\n        !Number.isSafeInteger(value)\n        || value < MIN_VIEWPORT_DIMENSION\n        || value > MAX_VIEWPORT_DIMENSION\n      ) {\n        throw new Error(\n          `Viewport #${index + 1} ${label} must be an integer between ${MIN_VIEWPORT_DIMENSION} and ${MAX_VIEWPORT_DIMENSION}`,\n        );\n      }\n    }\n\n    const outputName = `${viewport.name}_${viewport.width}x${viewport.height}.png`.toLowerCase();\n    if (outputNames.has(outputName)) {\n      throw new Error(`Duplicate viewport output filename: ${outputName}`);\n    }\n    outputNames.add(outputName);\n    return { name: viewport.name, width: viewport.width, height: viewport.height };\n  });\n}\n\nfunction resolveContainedOutputPath(outputDirectory: string, fileName: string): string {\n  const outputPath = path.resolve(outputDirectory, fileName);\n  const relativePath = path.relative(outputDirectory, outputPath);\n  if (relativePath.startsWith(\"..\") || path.isAbsolute(relativePath)) {\n    throw new Error(\"Screenshot output path escapes the requested output directory\");\n  }\n  return outputPath;\n}\n\nfunction isPathWithinDirectory(directory: string, filePath: string): boolean {\n  const relativePath = path.relative(directory, filePath);\n  return relativePath === \"\" || (!relativePath.startsWith(\"..\") && !path.isAbsolute(relativePath));\n}\n\nasync function assertLocalScreenshotRequestAllowed(requestUrl: URL, localDirectory: string): Promise<void> {\n  if (requestUrl.hostname) {\n    throw new Error(\"Blocked local file request with a host name\");\n  }\n\n  let resolvedPath: string;\n  try {\n    resolvedPath = await fs.realpath(fileURLToPath(requestUrl));\n  } catch (error: unknown) {\n    throw new Error(`Blocked local file request: ${getErrorMessage(error)}`);\n  }\n\n  if (!isPathWithinDirectory(localDirectory, resolvedPath)) {\n    throw new Error(\"Blocked local file request outside the selected file directory\");\n  }\n}\n\nasync function assertScreenshotRequestAllowed(requestUrl: string, localDirectory?: string): Promise<void> {\n  let parsedUrl: URL;\n  try {\n    parsedUrl = new URL(requestUrl);\n  } catch {\n    throw new Error(\"Blocked invalid page request URL\");\n  }\n\n  if (parsedUrl.protocol === \"http:\" || parsedUrl.protocol === \"https:\") {\n    await assertPublicHttpUrl(parsedUrl);\n    return;\n  }\n\n  if (parsedUrl.protocol === \"data:\" || parsedUrl.protocol === \"blob:\") {\n    return;\n  }\n\n  if (parsedUrl.protocol === \"file:\" && localDirectory) {\n    await assertLocalScreenshotRequestAllowed(parsedUrl, localDirectory);\n    return;\n  }\n\n  throw new Error(`Blocked unsupported page request protocol ${parsedUrl.protocol}`);\n}\n\nasync function resolveScreenshotRequest(\n  request: InterceptedRequest,\n  localDirectory: string | undefined,\n  onBlocked: (message: string) => void,\n): Promise<void> {\n  if (request.isInterceptResolutionHandled()) {\n    return;\n  }\n\n  try {\n    await assertScreenshotRequestAllowed(request.url(), localDirectory);\n    if (request.isInterceptResolutionHandled()) {\n      return;\n    }\n    await request.continue();\n  } catch (error: unknown) {\n    onBlocked(getErrorMessage(error));\n    if (request.isInterceptResolutionHandled()) {\n      return;\n    }\n    await request.abort(\"blockedbyclient\");\n  }\n}\n\n/**\n * Captures screenshots of a local HTML file or remote URL at different viewport sizes.\n * @param targetPath Local file path or HTTP(S) URL\n * @param outputDirectory Absolute path to save screenshots\n * @param customViewports Optional custom viewport settings\n */\nexport async function captureScreenshots(\n  targetPath: string,\n  outputDirectory: string,\n  customViewports?: ViewportConfig[]\n): Promise<ScreenshotResult[]> {\n  if (typeof targetPath !== \"string\" || targetPath.trim() === \"\") {\n    throw new Error(\"targetPath must be a non-empty string\");\n  }\n  if (typeof outputDirectory !== \"string\" || outputDirectory.trim() === \"\") {\n    throw new Error(\"outputDirectory must be a non-empty string\");\n  }\n\n  const viewports = validateViewports(\n    customViewports && customViewports.length > 0 ? customViewports : DEFAULT_VIEWPORTS,\n  );\n  const resolvedOutputDirectory = path.resolve(outputDirectory);\n\n  // Resolve target to file:// URL if it is a local file path\n  let targetUrl: string;\n  let localDirectory: string | undefined;\n  if (/^https?:\\/\\//i.test(targetPath)) {\n    targetUrl = (await assertPublicHttpUrl(targetPath)).href;\n  } else {\n    const absolutePath = path.resolve(targetPath);\n    const resolvedPath = await fs.realpath(absolutePath);\n    const stats = await fs.stat(resolvedPath);\n    if (!stats.isFile()) {\n      throw new Error(`Screenshot target is not a regular file: ${resolvedPath}`);\n    }\n    localDirectory = path.dirname(resolvedPath);\n    targetUrl = pathToFileURL(resolvedPath).href;\n  }\n\n  // Ensure output directory exists\n  await fs.mkdir(resolvedOutputDirectory, { recursive: true });\n\n  // Launch Puppeteer's bundled headless shell.\n  const browser = await puppeteer.launch({\n    headless: SCREENSHOT_HEADLESS_MODE,\n  });\n\n  const results: ScreenshotResult[] = [];\n\n  try {\n    const page = await browser.newPage();\n    page.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);\n\n    let blockedRequestMessage: string | undefined;\n    await page.setRequestInterception(true);\n    page.on(\"request\", (request) => {\n      void resolveScreenshotRequest(request, localDirectory, (message) => {\n        blockedRequestMessage ??= message;\n      }).catch(() => {\n        // Puppeteer will surface navigation failures; avoid an unhandled listener rejection.\n      });\n    });\n\n    for (const vp of viewports) {\n      await page.setViewport({\n        width: vp.width,\n        height: vp.height,\n        deviceScaleFactor: 1\n      });\n\n      // Load URL (wait until network is idle or DOM loaded)\n      try {\n        await page.goto(targetUrl, {\n          waitUntil: \"domcontentloaded\",\n          timeout: NAVIGATION_TIMEOUT_MS,\n        });\n      } catch (error: unknown) {\n        if (blockedRequestMessage) {\n          throw new Error(`Screenshot navigation blocked: ${blockedRequestMessage}`);\n        }\n        throw new Error(`Screenshot navigation failed: ${getErrorMessage(error)}`);\n      }\n\n      // Short wait for any animations or layout adjustments to settle\n      await new Promise((resolve) => setTimeout(resolve, 500));\n\n      const fileName = `${vp.name}_${vp.width}x${vp.height}.png`;\n      const outputPath = resolveContainedOutputPath(resolvedOutputDirectory, fileName);\n\n      await page.screenshot({\n        path: outputPath,\n        fullPage: false // Captures above the fold viewport\n      });\n\n      results.push({\n        viewportName: vp.name,\n        width: vp.width,\n        height: vp.height,\n        outputPath\n      });\n    }\n  } finally {\n    await browser.close();\n  }\n\n  return results;\n}\n"]}

package/dist/seo-auditor.d.ts

@@ -1,3 +1,5 @@
+export declare const MAX_AUDIT_ISSUES = 200;
+export declare const MAX_LINKS_TO_CHECK = 25;
 export interface SEOIssue {
     severity: "error" | "warning" | "info";
     category: "SEO" | "Schema" | "BrokenLinks" | "Accessibility";
@@ -10,15 +12,22 @@ export interface LinkStatus {
     ok: boolean;
     message?: string;
 }
+export interface AuditDetails {
+    issues: SEOIssue[];
+    totalIssues: number;
+    truncated: boolean;
+}
 /**
  * Audits technical SEO and accessibility basics on HTML content using Cheerio
  */
+export declare function auditSeoMetadataDetailed(htmlContent: string): AuditDetails;
 export declare function auditSeoMetadata(htmlContent: string): SEOIssue[];
 /**
  * Parses and validates JSON-LD Schema markup
  */
+export declare function validateSchemaMarkupDetailed(htmlContent: string): AuditDetails;
 export declare function validateSchemaMarkup(htmlContent: string): SEOIssue[];
 /**
- * Extracts and tests all links inside the HTML content for broken links (4xx / 5xx)
+ * Extracts and tests links, treating 3xx responses as reachable redirects and 4xx/5xx as broken.
  */
-export declare function checkBrokenLinks(htmlContent: string, baseUrl?: string): Promise<LinkStatus[]>;
+export declare function checkBrokenLinks(htmlContent: string, baseUrl?: string, maxLinks?: number): Promise<LinkStatus[]>;

package/dist/seo-auditor.js

@@ -1,41 +1,72 @@
 import * as cheerio from "cheerio";
+import { assertPublicHttpUrl, cancelResponseBody, fetchPublicHttp, getErrorMessage, PublicUrlError, } from "./network.js";
+import { PACKAGE_VERSION } from "./version.js";
+export const MAX_AUDIT_ISSUES = 200;
+export const MAX_LINKS_TO_CHECK = 25;
+const LINK_CHECK_CONCURRENCY = 5;
+const LINK_CHECK_TIMEOUT_MS = 5_000;
+const LINK_CHECK_USER_AGENT = `mcp-web-validator/${PACKAGE_VERSION} (+https://digestseo.com/validator-mcp/)`;
+function addIssue(issues, issue) {
+    if (issues.length < MAX_AUDIT_ISSUES) {
+        issues.push(issue);
+    }
+}
+function createIssueCollector() {
+    const issues = [];
+    let totalIssues = 0;
+    return {
+        issues,
+        add(issue) {
+            totalIssues += 1;
+            addIssue(issues, issue);
+        },
+        details() {
+            return {
+                issues,
+                totalIssues,
+                truncated: totalIssues > issues.length,
+            };
+        },
+    };
+}
 /**
  * Audits technical SEO and accessibility basics on HTML content using Cheerio
  */
-export function auditSeoMetadata(htmlContent) {
+export function auditSeoMetadataDetailed(htmlContent) {
     const $ = cheerio.load(htmlContent);
-    const issues = [];
+    const collector = createIssueCollector();
+    const { add } = collector;
     // --- Title Tag Audits ---
     const titleTag = $("title");
     if (titleTag.length === 0) {
-        issues.push({
+        add({
             severity: "error",
             category: "SEO",
-            message: "Missing <title> tag. This is critical for search indexing and click-through rates.",
+            message: "Missing <title> tag. Add a concise, descriptive title to help represent the page in search results.",
         });
     }
     else {
         const titleText = titleTag.text().trim();
         if (titleText.length === 0) {
-            issues.push({
+            add({
                 severity: "error",
                 category: "SEO",
                 message: "The <title> tag is empty.",
             });
         }
         else if (titleText.length < 30) {
-            issues.push({
+            add({
                 severity: "warning",
                 category: "SEO",
-                message: `Title length (${titleText.length} chars) is too short. Try to make it at least 30-50 characters.`,
+                message: `Title is ${titleText.length} characters. This is shorter than the audit's common editorial range; review whether it describes the page clearly.`,
                 element: `<title>${titleText}</title>`,
             });
         }
         else if (titleText.length > 60) {
-            issues.push({
+            add({
                 severity: "warning",
                 category: "SEO",
-                message: `Title length (${titleText.length} chars) is too long. Search engines will truncate it. Keep it under 60 characters.`,
+                message: `Title is ${titleText.length} characters. This is longer than the audit's common editorial range; Google title links may be shortened or rewritten depending on context and device.`,
                 element: `<title>${titleText}</title>`,
             });
         }
@@ -43,34 +74,34 @@ export function auditSeoMetadata(htmlContent) {
     // --- Meta Description Audits ---
     const metaDescription = $('meta[name="description"]');
     if (metaDescription.length === 0) {
-        issues.push({
+        add({
             severity: "error",
             category: "SEO",
-            message: "Missing <meta name=\"description\">. Search engines will automatically generate snippets, which may lower CTR.",
+            message: "Missing <meta name=\"description\">. Add a concise, accurate page summary; Google may use page content or this description to generate a snippet.",
         });
     }
     else {
         const descText = metaDescription.attr("content")?.trim() || "";
         if (descText.length === 0) {
-            issues.push({
+            add({
                 severity: "error",
                 category: "SEO",
                 message: "Meta description content attribute is empty.",
             });
         }
         else if (descText.length < 120) {
-            issues.push({
+            add({
                 severity: "warning",
                 category: "SEO",
-                message: `Meta description is too short (${descText.length} chars). Aim for 120-160 characters to optimize your search snippet.`,
+                message: `Meta description is ${descText.length} characters. This is shorter than the audit's common editorial range; review whether it provides a useful page summary.`,
                 element: `<meta name="description" content="${descText}">`,
             });
         }
         else if (descText.length > 160) {
-            issues.push({
+            add({
                 severity: "warning",
                 category: "SEO",
-                message: `Meta description is too long (${descText.length} chars). Search engines will truncate it. Keep it under 160 characters.`,
+                message: `Meta description is ${descText.length} characters. This is longer than the audit's common editorial range; displayed snippets may be shortened depending on the query and device.`,
                 element: `<meta name="description" content="${descText}">`,
             });
         }
@@ -78,7 +109,7 @@ export function auditSeoMetadata(htmlContent) {
     // --- Canonical Link ---
     const canonical = $('link[rel="canonical"]');
     if (canonical.length === 0) {
-        issues.push({
+        add({
             severity: "warning",
             category: "SEO",
             message: "Missing canonical tag (<link rel=\"canonical\">). This helps prevent duplicate content issues.",
@@ -87,23 +118,23 @@ export function auditSeoMetadata(htmlContent) {
     // --- Viewport Meta Tag (Mobile Responsiveness) ---
     const viewport = $('meta[name="viewport"]');
     if (viewport.length === 0) {
-        issues.push({
+        add({
             severity: "error",
             category: "SEO",
-            message: "Missing <meta name=\"viewport\"> tag. Mobile friendliness is a critical ranking factor.",
+            message: "Missing <meta name=\"viewport\"> tag. Review mobile rendering; this tag helps browsers size and scale the page on mobile devices.",
         });
     }
     // --- Heading Structure ---
     const h1Tags = $("h1");
     if (h1Tags.length === 0) {
-        issues.push({
+        add({
             severity: "error",
             category: "SEO",
             message: "Missing <h1> tag. Every page must have exactly one <h1> representing the main topic.",
         });
     }
     else if (h1Tags.length > 1) {
-        issues.push({
+        add({
             severity: "warning",
             category: "SEO",
             message: `Found multiple (${h1Tags.length}) <h1> tags. Multiple <h1> tags dilutes topic keyword focus.`,
@@ -115,7 +146,7 @@ export function auditSeoMetadata(htmlContent) {
         const src = img.attr("src") || "unknown-source";
         const alt = img.attr("alt");
         if (alt === undefined) {
-            issues.push({
+            add({
                 severity: "error",
                 category: "Accessibility",
                 message: "Missing 'alt' attribute on image. This makes it inaccessible to screen readers.",
@@ -124,7 +155,7 @@ export function auditSeoMetadata(htmlContent) {
         }
         else if (alt.trim() === "") {
             // Empty alt is acceptable for purely decorative images, but worth warning
-            issues.push({
+            add({
                 severity: "info",
                 category: "Accessibility",
                 message: "Empty 'alt' attribute found. Ensure this image is purely decorative, otherwise add descriptive text.",
@@ -136,24 +167,28 @@ export function auditSeoMetadata(htmlContent) {
     const ogTitle = $('meta[property="og:title"]');
     const ogImage = $('meta[property="og:image"]');
     if (ogTitle.length === 0 || ogImage.length === 0) {
-        issues.push({
+        add({
             severity: "info",
             category: "SEO",
             message: "Missing Open Graph social metadata (og:title / og:image). Add these to control preview cards on platforms like LinkedIn and X.",
         });
     }
-    return issues;
+    return collector.details();
+}
+export function auditSeoMetadata(htmlContent) {
+    return auditSeoMetadataDetailed(htmlContent).issues;
 }
 /**
  * Parses and validates JSON-LD Schema markup
  */
-export function validateSchemaMarkup(htmlContent) {
+export function validateSchemaMarkupDetailed(htmlContent) {
     const $ = cheerio.load(htmlContent);
-    const issues = [];
+    const collector = createIssueCollector();
+    const { add } = collector;
     $('script[type="application/ld+json"]').each((index, element) => {
         const scriptText = $(element).html() || "";
         if (scriptText.trim() === "") {
-            issues.push({
+            add({
                 severity: "warning",
                 category: "Schema",
                 message: `JSON-LD block #${index + 1} is empty.`,
@@ -163,71 +198,129 @@ export function validateSchemaMarkup(htmlContent) {
         try {
             JSON.parse(scriptText);
         }
-        catch (e) {
-            issues.push({
+        catch (error) {
+            add({
                 severity: "error",
                 category: "Schema",
-                message: `Invalid JSON-LD schema syntax: ${e.message}`,
+                message: `Invalid JSON-LD schema syntax: ${getErrorMessage(error)}`,
                 element: `<script type="application/ld+json">...</script>`,
             });
         }
     });
-    return issues;
+    return collector.details();
+}
+export function validateSchemaMarkup(htmlContent) {
+    return validateSchemaMarkupDetailed(htmlContent).issues;
 }
 /**
- * Extracts and tests all links inside the HTML content for broken links (4xx / 5xx)
+ * Extracts and tests links, treating 3xx responses as reachable redirects and 4xx/5xx as broken.
  */
-export async function checkBrokenLinks(htmlContent, baseUrl) {
+export async function checkBrokenLinks(htmlContent, baseUrl, maxLinks = MAX_LINKS_TO_CHECK) {
+    if (!Number.isSafeInteger(maxLinks) || maxLinks <= 0) {
+        throw new Error("maxLinks must be a positive integer");
+    }
+    const linkLimit = Math.min(maxLinks, MAX_LINKS_TO_CHECK);
     const $ = cheerio.load(htmlContent);
+    const parsedBaseUrl = baseUrl ? await assertPublicHttpUrl(baseUrl) : undefined;
     const urls = [];
+    const seenUrls = new Set();
     $("a").each((_, element) => {
-        const href = $(element).attr("href");
-        if (href && !href.startsWith("#") && !href.startsWith("mailto:") && !href.startsWith("tel:") && !href.startsWith("javascript:")) {
-            let resolvedUrl = href;
-            if (href.startsWith("/") && baseUrl) {
-                resolvedUrl = new URL(href, baseUrl).toString();
-            }
-            if (!urls.includes(resolvedUrl)) {
-                urls.push(resolvedUrl);
-            }
+        if (urls.length >= linkLimit) {
+            return false;
+        }
+        const href = $(element).attr("href")?.trim();
+        if (!href || href.startsWith("#")) {
+            return;
+        }
+        let resolvedUrl;
+        try {
+            resolvedUrl = parsedBaseUrl ? new URL(href, parsedBaseUrl) : new URL(href);
+        }
+        catch {
+            // Relative links require a public base URL; unsupported or malformed links are skipped.
+            return;
+        }
+        if (resolvedUrl.protocol !== "http:" && resolvedUrl.protocol !== "https:") {
+            return;
+        }
+        resolvedUrl.hash = "";
+        const normalizedUrl = resolvedUrl.href;
+        if (!seenUrls.has(normalizedUrl)) {
+            seenUrls.add(normalizedUrl);
+            urls.push(normalizedUrl);
         }
     });
-    const results = [];
-    // Parallel requests with timeout limits to keep validation fast
-    const requests = urls.map(async (url) => {
+    const results = new Array(urls.length);
+    let nextIndex = 0;
+    async function checkLink(url) {
         try {
-            const response = await fetch(url, {
+            const headResult = await fetchPublicHttp(url, {
                 method: "HEAD",
-                // Avoid rejection on self-signed certs or SSL errors commonly found on local testing servers
-                signal: AbortSignal.timeout(5000),
+                headers: { "User-Agent": LINK_CHECK_USER_AGENT },
+                timeoutMs: LINK_CHECK_TIMEOUT_MS,
+                maxRedirects: 0,
             });
-            // If HEAD is not allowed (e.g. Cloudflare / 405 Method Not Allowed), retry with GET
-            if (response.status === 405 || response.status === 403) {
-                const getResponse = await fetch(url, {
+            const headStatus = headResult.response.status;
+            const headFinalUrl = headResult.url.href;
+            await cancelResponseBody(headResult.response);
+            // Some sites reject or do not implement HEAD even when the linked resource is available.
+            if (headStatus === 405 || headStatus === 403 || headStatus === 501) {
+                const getResult = await fetchPublicHttp(url, {
                     method: "GET",
-                    signal: AbortSignal.timeout(5000),
+                    headers: {
+                        Range: "bytes=0-0",
+                        "User-Agent": LINK_CHECK_USER_AGENT,
+                    },
+                    timeoutMs: LINK_CHECK_TIMEOUT_MS,
+                    maxRedirects: 0,
                 });
+                const status = getResult.response.status;
+                const ok = status >= 200 && status < 400;
+                const finalUrl = getResult.url.href;
+                await cancelResponseBody(getResult.response);
                 return {
                     url,
-                    status: getResponse.status,
-                    ok: getResponse.ok,
+                    status,
+                    ok,
+                    message: status >= 300 && status < 400
+                        ? "Redirect not followed"
+                        : finalUrl !== url
+                            ? `Redirected to ${finalUrl}`
+                            : undefined,
                 };
             }
             return {
                 url,
-                status: response.status,
-                ok: response.ok,
+                status: headStatus,
+                ok: headStatus >= 200 && headStatus < 400,
+                message: headStatus >= 300 && headStatus < 400
+                    ? "Redirect not followed"
+                    : headFinalUrl !== url
+                        ? `Redirected to ${headFinalUrl}`
+                        : undefined,
             };
         }
         catch (error) {
             return {
                 url,
-                status: "FAILED",
+                status: error instanceof PublicUrlError ? "blocked" : "failed",
                 ok: false,
-                message: error.name === "TimeoutError" ? "Timeout" : error.message,
+                message: getErrorMessage(error),
             };
         }
-    });
-    return Promise.all(requests);
+    }
+    async function worker() {
+        while (true) {
+            const index = nextIndex;
+            nextIndex += 1;
+            if (index >= urls.length) {
+                return;
+            }
+            results[index] = await checkLink(urls[index]);
+        }
+    }
+    const workerCount = Math.min(LINK_CHECK_CONCURRENCY, urls.length);
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    return results;
 }
 //# sourceMappingURL=seo-auditor.js.map