@stati/core 1.6.4 → 1.7.1

package/dist/seo/utils/escape-and-validation.js

@@ -0,0 +1,319 @@
+/**
+ * SEO utility functions for HTML escaping, validation, and tag detection
+ */
+import { URL } from 'node:url';
+import { SEOTagType as SEOTagTypeEnum } from '../../types/seo.js';
+/**
+ * HTML escape cache for performance optimization.
+ * Stores up to 1000 frequently used strings to avoid repeated escaping.
+ */
+const escapeHtmlCache = new Map();
+const ESCAPE_CACHE_MAX_SIZE = 1000;
+/**
+ * Escape HTML entities to prevent XSS attacks.
+ * Uses memoization for performance with frequently repeated strings.
+ *
+ * Implements LRU-style cache eviction: when the cache is full, it's cleared
+ * and the new entry is added. This prevents unbounded memory growth while
+ * still providing caching benefits for repeated strings.
+ *
+ * @param text - The text to escape
+ * @returns HTML-safe string with special characters escaped
+ *
+ * @example
+ * ```typescript
+ * escapeHtml('<script>alert("xss")</script>');
+ * // Returns: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+ * ```
+ */
+export function escapeHtml(text) {
+    // Check cache
+    const cached = escapeHtmlCache.get(text);
+    if (cached !== undefined) {
+        return cached;
+    }
+    // Compute result
+    const htmlEscapes = {
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&#39;',
+    };
+    const result = text.replace(/[&<>"']/g, (char) => htmlEscapes[char] || char);
+    // Store in cache with size limit
+    if (escapeHtmlCache.size < ESCAPE_CACHE_MAX_SIZE) {
+        escapeHtmlCache.set(text, result);
+    }
+    else {
+        // Clear cache when full (prevents unbounded growth)
+        // This is a simple LRU-style eviction strategy
+        escapeHtmlCache.clear();
+        escapeHtmlCache.set(text, result);
+    }
+    return result;
+}
+/**
+ * Sanitize structured data to prevent XSS attacks and ensure safe JSON-LD output.
+ * Recursively processes objects and arrays, escaping string values and enforcing depth limits.
+ *
+ * Security: Objects exceeding max depth are completely removed rather than replaced with
+ * a string placeholder to prevent potential XSS vectors.
+ *
+ * @param data - The data to sanitize
+ * @param logger - Logger instance for warnings
+ * @param depth - Current recursion depth (internal use)
+ * @param maxDepth - Maximum allowed recursion depth (default: 50)
+ * @returns Sanitized data safe for JSON-LD output, or undefined if max depth exceeded
+ *
+ * @example
+ * ```typescript
+ * const data = {
+ *   name: '<script>alert("xss")</script>',
+ *   nested: { value: 'test' }
+ * };
+ * sanitizeStructuredData(data, logger);
+ * // Returns: { name: '&lt;script&gt;...', nested: { value: 'test' } }
+ * ```
+ */
+export function sanitizeStructuredData(data, logger, depth = 0, maxDepth = 50) {
+    // Prevent stack overflow from deeply nested objects
+    // Return undefined to remove the deeply nested value entirely (safer than string placeholder)
+    if (depth > maxDepth) {
+        const message = `Structured data exceeds maximum nesting depth of ${maxDepth}, removing deeply nested object`;
+        logger.warning(message);
+        return undefined;
+    }
+    // Handle primitives
+    if (typeof data === 'string') {
+        return escapeHtml(data);
+    }
+    if (typeof data !== 'object' || data === null) {
+        return data;
+    }
+    // Handle arrays
+    if (Array.isArray(data)) {
+        // Filter out undefined values that resulted from depth limit
+        return data
+            .map((item) => sanitizeStructuredData(item, logger, depth + 1, maxDepth))
+            .filter((item) => item !== undefined);
+    }
+    // Handle objects
+    const sanitizedObject = {};
+    for (const key in data) {
+        if (Object.prototype.hasOwnProperty.call(data, key)) {
+            const sanitizedValue = sanitizeStructuredData(data[key], logger, depth + 1, maxDepth);
+            // Only include the property if it's not undefined (i.e., didn't exceed depth)
+            if (sanitizedValue !== undefined) {
+                sanitizedObject[key] = sanitizedValue;
+            }
+        }
+    }
+    return sanitizedObject;
+}
+/**
+ * Generate robots meta tag content from SEO metadata and robots configuration.
+ * Combines noindex flag and robots directives into a comma-separated string.
+ *
+ * @param seo - SEO metadata containing robots configuration
+ * @returns Comma-separated robots directives, or empty string if none
+ *
+ * @example
+ * ```typescript
+ * generateRobotsContent({ noindex: true, robots: { follow: false } });
+ * // Returns: 'noindex, nofollow'
+ * ```
+ */
+export function generateRobotsContent(seo) {
+    const directives = [];
+    // Collect directives from noindex flag
+    if (seo.noindex) {
+        directives.push('noindex');
+    }
+    // Handle robots config
+    if (typeof seo.robots === 'string') {
+        // If string doesn't include noindex but flag is set, prepend it
+        if (seo.noindex && !seo.robots.includes('noindex')) {
+            return `noindex, ${seo.robots}`;
+        }
+        return seo.robots;
+    }
+    else if (seo.robots) {
+        const robots = seo.robots;
+        // Only add if not already added via noindex flag
+        if (robots.index === false && !directives.includes('noindex')) {
+            directives.push('noindex');
+        }
+        if (robots.follow === false) {
+            directives.push('nofollow');
+        }
+        if (robots.archive === false) {
+            directives.push('noarchive');
+        }
+        if (robots.snippet === false) {
+            directives.push('nosnippet');
+        }
+        if (robots.imageindex === false) {
+            directives.push('noimageindex');
+        }
+        if (robots.translate === false) {
+            directives.push('notranslate');
+        }
+        if (robots.maxSnippet !== undefined) {
+            directives.push(`max-snippet:${robots.maxSnippet}`);
+        }
+        if (robots.maxImagePreview) {
+            directives.push(`max-image-preview:${robots.maxImagePreview}`);
+        }
+        if (robots.maxVideoPreview !== undefined) {
+            directives.push(`max-video-preview:${robots.maxVideoPreview}`);
+        }
+    }
+    return directives.length > 0 ? directives.join(', ') : '';
+}
+/**
+ * Validate URL format (http or https only).
+ *
+ * @param url - The URL to validate
+ * @returns True if the URL is valid
+ */
+function isValidUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate SEO metadata before processing.
+ * Checks for common issues like invalid URLs, improper lengths, and malformed data.
+ *
+ * @param seo - SEO metadata to validate
+ * @param _pageUrl - URL of the page being validated (for context in error messages)
+ * @returns Validation result with valid flag, errors, and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateSEOMetadata({
+ *   title: 'My Page',
+ *   canonical: 'invalid-url'
+ * }, '/my-page');
+ * // Returns: { valid: false, errors: ['Invalid canonical URL...'], warnings: [] }
+ * ```
+ */
+export function validateSEOMetadata(seo, _pageUrl) {
+    const errors = [];
+    const warnings = [];
+    // Validate title length
+    if (seo.title) {
+        if (seo.title.length < 5) {
+            warnings.push(`Title is only ${seo.title.length} characters (recommended: 50-60)`);
+        }
+        else if (seo.title.length > 70) {
+            warnings.push(`Title is ${seo.title.length} characters (recommended: 50-60)`);
+        }
+    }
+    // Validate description length
+    if (seo.description) {
+        if (seo.description.length < 50) {
+            warnings.push(`Description is only ${seo.description.length} characters (recommended: 150-160)`);
+        }
+        else if (seo.description.length > 160) {
+            warnings.push(`Description is ${seo.description.length} characters (recommended: 150-160)`);
+        }
+    }
+    // Validate canonical URL
+    if (seo.canonical && !isValidUrl(seo.canonical)) {
+        errors.push(`Invalid canonical URL: ${seo.canonical}`);
+    }
+    // Validate Open Graph image URL and dimensions
+    if (seo.openGraph?.image) {
+        const imageUrl = typeof seo.openGraph.image === 'string' ? seo.openGraph.image : seo.openGraph.image.url;
+        if (!isValidUrl(imageUrl) && !imageUrl.startsWith('/')) {
+            warnings.push(`Open Graph image URL may be invalid: ${imageUrl}`);
+        }
+        // Validate image dimensions if provided
+        if (typeof seo.openGraph.image !== 'string') {
+            const { width, height } = seo.openGraph.image;
+            if (width !== undefined && (!Number.isInteger(width) || width <= 0)) {
+                errors.push(`Open Graph image width must be a positive integer (got ${width})`);
+            }
+            if (height !== undefined && (!Number.isInteger(height) || height <= 0)) {
+                errors.push(`Open Graph image height must be a positive integer (got ${height})`);
+            }
+        }
+    }
+    // Validate Twitter image URL
+    if (seo.twitter?.image && !isValidUrl(seo.twitter.image) && !seo.twitter.image.startsWith('/')) {
+        warnings.push(`Twitter Card image URL may be invalid: ${seo.twitter.image}`);
+    }
+    // Validate structured data size
+    if (seo.structuredData) {
+        const jsonSize = JSON.stringify(seo.structuredData).length;
+        const maxSize = 100 * 1024; // 100KB limit
+        if (jsonSize > maxSize) {
+            warnings.push(`Structured data is ${(jsonSize / 1024).toFixed(2)}KB (recommended: <100KB)`);
+        }
+    }
+    // Validate priority value
+    if (seo.priority !== undefined) {
+        if (typeof seo.priority !== 'number' || seo.priority < 0 || seo.priority > 1) {
+            errors.push('Priority must be a number between 0.0 and 1.0');
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+/**
+ * Detect existing SEO tags in HTML to avoid duplication during auto-injection.
+ * Uses enhanced regex patterns to handle multi-line attributes and edge cases.
+ *
+ * Returns a Set of SEOTagType enum values indicating which tag types are already present.
+ * This allows for granular control: only missing tags will be generated.
+ *
+ * @param html - The HTML content to scan
+ * @returns Set of SEOTagType enum values for existing tags
+ *
+ * @example
+ * ```typescript
+ * const html = '<head><title>My Page</title><meta name="description" content="..."></head>';
+ * const existing = detectExistingSEOTags(html);
+ * // Returns: Set { SEOTagType.Title, SEOTagType.Description }
+ * ```
+ */
+export function detectExistingSEOTags(html) {
+    const existingTags = new Set();
+    // Extract just the <head> section for more efficient parsing
+    const headMatch = html.match(/<head[^>]*>([\s\S]*?)<\/head>/i);
+    if (!headMatch) {
+        console.warn('No <head> tag found in HTML, SEO auto-injection may not work correctly');
+        return existingTags;
+    }
+    const headContent = headMatch[1];
+    // More robust regex patterns that handle multi-line attributes and edge cases
+    const patterns = [
+        { regex: /<title\s*>/i, type: SEOTagTypeEnum.Title },
+        {
+            regex: /<meta\s+[^>]*name\s*=\s*["']description["'][^>]*>/i,
+            type: SEOTagTypeEnum.Description,
+        },
+        { regex: /<meta\s+[^>]*name\s*=\s*["']keywords["'][^>]*>/i, type: SEOTagTypeEnum.Keywords },
+        { regex: /<meta\s+[^>]*name\s*=\s*["']author["'][^>]*>/i, type: SEOTagTypeEnum.Author },
+        { regex: /<meta\s+[^>]*name\s*=\s*["']robots["'][^>]*>/i, type: SEOTagTypeEnum.Robots },
+        { regex: /<link\s+[^>]*rel\s*=\s*["']canonical["'][^>]*>/i, type: SEOTagTypeEnum.Canonical },
+        { regex: /<meta\s+[^>]*property\s*=\s*["']og:/i, type: SEOTagTypeEnum.OpenGraph },
+        { regex: /<meta\s+[^>]*name\s*=\s*["']twitter:/i, type: SEOTagTypeEnum.Twitter },
+        {
+            regex: /<script\s+[^>]*type\s*=\s*["']application\/ld\+json["'][^>]*>/i,
+            type: SEOTagTypeEnum.StructuredData,
+        },
+    ];
+    // Check all patterns in a single pass
+    for (const { regex, type } of patterns) {
+        if (headContent && regex.test(headContent)) {
+            existingTags.add(type);
+        }
+    }
+    return existingTags;
+}

package/dist/seo/utils/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * SEO utilities index
+ * @module seo/utils
+ */
+export { escapeHtml, generateRobotsContent, validateSEOMetadata, detectExistingSEOTags, } from './escape-and-validation.js';
+export { normalizeUrlPath, resolveAbsoluteUrl, isValidUrl } from './url.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/seo/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/seo/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,UAAU,EACV,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}

package/dist/seo/utils/index.js

@@ -0,0 +1,8 @@
+/**
+ * SEO utilities index
+ * @module seo/utils
+ */
+// Re-export escape and validation utilities
+export { escapeHtml, generateRobotsContent, validateSEOMetadata, detectExistingSEOTags, } from './escape-and-validation.js';
+// Re-export URL utilities
+export { normalizeUrlPath, resolveAbsoluteUrl, isValidUrl } from './url.js';

package/dist/seo/utils/url.d.ts

@@ -0,0 +1,46 @@
+/**
+ * URL resolution and normalization utilities for SEO module
+ * @module seo/utils/url
+ */
+/**
+ * Normalizes a path to ensure it starts with /
+ * @param path - Path to normalize
+ * @returns Normalized path starting with /
+ *
+ * @example
+ * ```typescript
+ * normalizeUrlPath('about'); // '/about'
+ * normalizeUrlPath('/about'); // '/about'
+ * ```
+ */
+export declare function normalizeUrlPath(path: string): string;
+/**
+ * Resolves a relative or absolute URL to a full absolute URL
+ * @param url - Relative or absolute URL
+ * @param baseUrl - Base site URL
+ * @returns Absolute URL
+ *
+ * @example
+ * ```typescript
+ * resolveAbsoluteUrl('/about', 'https://example.com');
+ * // Returns: 'https://example.com/about'
+ *
+ * resolveAbsoluteUrl('https://other.com/page', 'https://example.com');
+ * // Returns: 'https://other.com/page'
+ * ```
+ */
+export declare function resolveAbsoluteUrl(url: string, baseUrl: string): string;
+/**
+ * Validates a URL string
+ * @param url - URL to validate
+ * @returns true if valid URL with http/https protocol
+ *
+ * @example
+ * ```typescript
+ * isValidUrl('https://example.com'); // true
+ * isValidUrl('not-a-url'); // false
+ * isValidUrl('ftp://example.com'); // false (only http/https)
+ * ```
+ */
+export declare function isValidUrl(url: string): boolean;
+//# sourceMappingURL=url.d.ts.map

package/dist/seo/utils/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../../src/seo/utils/url.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAavE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO/C"}

package/dist/seo/utils/url.js

@@ -0,0 +1,66 @@
+/**
+ * URL resolution and normalization utilities for SEO module
+ * @module seo/utils/url
+ */
+import { URL } from 'node:url';
+/**
+ * Normalizes a path to ensure it starts with /
+ * @param path - Path to normalize
+ * @returns Normalized path starting with /
+ *
+ * @example
+ * ```typescript
+ * normalizeUrlPath('about'); // '/about'
+ * normalizeUrlPath('/about'); // '/about'
+ * ```
+ */
+export function normalizeUrlPath(path) {
+    return path.startsWith('/') ? path : `/${path}`;
+}
+/**
+ * Resolves a relative or absolute URL to a full absolute URL
+ * @param url - Relative or absolute URL
+ * @param baseUrl - Base site URL
+ * @returns Absolute URL
+ *
+ * @example
+ * ```typescript
+ * resolveAbsoluteUrl('/about', 'https://example.com');
+ * // Returns: 'https://example.com/about'
+ *
+ * resolveAbsoluteUrl('https://other.com/page', 'https://example.com');
+ * // Returns: 'https://other.com/page'
+ * ```
+ */
+export function resolveAbsoluteUrl(url, baseUrl) {
+    // Already absolute
+    if (url.startsWith('http://') || url.startsWith('https://')) {
+        return url;
+    }
+    // Ensure baseUrl doesn't end with /
+    const cleanBaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+    // Ensure url starts with /
+    const path = normalizeUrlPath(url);
+    return `${cleanBaseUrl}${path}`;
+}
+/**
+ * Validates a URL string
+ * @param url - URL to validate
+ * @returns true if valid URL with http/https protocol
+ *
+ * @example
+ * ```typescript
+ * isValidUrl('https://example.com'); // true
+ * isValidUrl('not-a-url'); // false
+ * isValidUrl('ftp://example.com'); // false (only http/https)
+ * ```
+ */
+export function isValidUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/seo/utils.d.ts

@@ -0,0 +1,94 @@
+/**
+ * SEO utility functions for HTML escaping, validation, and tag detection
+ */
+import type { SEOMetadata } from '../types/content.js';
+import type { SEOValidationResult, SEOTagType } from '../types/seo.js';
+/**
+ * Escape HTML entities to prevent XSS attacks.
+ * Uses memoization for performance with frequently repeated strings.
+ *
+ * Implements LRU-style cache eviction: when the cache is full, it's cleared
+ * and the new entry is added. This prevents unbounded memory growth while
+ * still providing caching benefits for repeated strings.
+ *
+ * @param text - The text to escape
+ * @returns HTML-safe string with special characters escaped
+ *
+ * @example
+ * ```typescript
+ * escapeHtml('<script>alert("xss")</script>');
+ * // Returns: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+ * ```
+ */
+export declare function escapeHtml(text: string): string;
+/**
+ * Sanitize structured data to prevent XSS attacks and ensure safe JSON-LD output.
+ * Recursively processes objects and arrays, escaping string values and enforcing depth limits.
+ *
+ * @param data - The data to sanitize
+ * @param depth - Current recursion depth (internal use)
+ * @param maxDepth - Maximum allowed recursion depth (default: 50)
+ * @returns Sanitized data safe for JSON-LD output
+ *
+ * @example
+ * ```typescript
+ * const data = {
+ *   name: '<script>alert("xss")</script>',
+ *   nested: { value: 'test' }
+ * };
+ * sanitizeStructuredData(data);
+ * // Returns: { name: '&lt;script&gt;...', nested: { value: 'test' } }
+ * ```
+ */
+export declare function sanitizeStructuredData(data: unknown, depth?: number, maxDepth?: number): unknown;
+/**
+ * Generate robots meta tag content from SEO metadata and robots configuration.
+ * Combines noindex flag and robots directives into a comma-separated string.
+ *
+ * @param seo - SEO metadata containing robots configuration
+ * @returns Comma-separated robots directives, or empty string if none
+ *
+ * @example
+ * ```typescript
+ * generateRobotsContent({ noindex: true, robots: { follow: false } });
+ * // Returns: 'noindex, nofollow'
+ * ```
+ */
+export declare function generateRobotsContent(seo: SEOMetadata): string;
+/**
+ * Validate SEO metadata before processing.
+ * Checks for common issues like invalid URLs, improper lengths, and malformed data.
+ *
+ * @param seo - SEO metadata to validate
+ * @param _pageUrl - URL of the page being validated (for context in error messages)
+ * @returns Validation result with valid flag, errors, and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateSEOMetadata({
+ *   title: 'My Page',
+ *   canonical: 'invalid-url'
+ * }, '/my-page');
+ * // Returns: { valid: false, errors: ['Invalid canonical URL...'], warnings: [] }
+ * ```
+ */
+export declare function validateSEOMetadata(seo: SEOMetadata, _pageUrl: string): SEOValidationResult;
+/**
+ * Detect existing SEO tags in HTML to avoid duplication during auto-injection.
+ * Uses enhanced regex patterns to handle multi-line attributes and edge cases.
+ *
+ * Returns a Set of SEOTagType enum values indicating which tag types are already present.
+ * This allows for granular control: only missing tags will be generated.
+ *
+ * @param html - The HTML content to scan
+ * @returns Set of SEOTagType enum values for existing tags
+ *
+ * @example
+ * ```typescript
+ * const html = '<head><title>My Page</title><meta name="description" content="..."></head>';
+ * const existing = detectExistingSEOTags(html);
+ * // Returns: Set { SEOTagType.Title, SEOTagType.Description }
+ * ```
+ */
+export declare function detectExistingSEOTags(html: string): Set<SEOTagType>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/seo/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/seo/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,qBAAqB,CAAC;AACrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAUvE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA4B/C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,KAAK,GAAE,MAAU,EACjB,QAAQ,GAAE,MAAW,GACpB,OAAO,CA0BT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAiD9D;AAiBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAwE3F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,UAAU,CAAC,CAuCnE"}