@stati/core 1.6.4 → 1.7.1

package/dist/seo/sitemap.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Sitemap generation utilities for Stati
+ * @module seo/sitemap
+ */
+import type { SitemapEntry, SitemapConfig, SitemapGenerationResult } from '../types/sitemap.js';
+import type { PageModel } from '../types/content.js';
+import type { StatiConfig } from '../types/config.js';
+/**
+ * Generates a sitemap entry from a page model
+ * @param page - Page to generate entry for
+ * @param config - Stati configuration
+ * @param sitemapConfig - Sitemap configuration
+ * @returns Sitemap entry or null if page should be excluded
+ */
+export declare function generateSitemapEntry(page: PageModel, config: StatiConfig, sitemapConfig: SitemapConfig): SitemapEntry | null;
+/**
+ * Generates sitemap XML from entries
+ * @param entries - Sitemap entries
+ * @returns Complete sitemap XML
+ */
+export declare function generateSitemapXml(entries: SitemapEntry[]): string;
+/**
+ * Generates sitemap index XML for multiple sitemaps
+ * @param sitemapUrls - Array of sitemap URLs
+ * @param siteUrl - Base site URL
+ * @returns Sitemap index XML
+ */
+export declare function generateSitemapIndexXml(sitemapUrls: string[], siteUrl: string): string;
+/**
+ * Generates sitemap(s) from pages
+ * @param pages - All pages to include in sitemap
+ * @param config - Stati configuration
+ * @param sitemapConfig - Sitemap configuration
+ * @returns Sitemap generation result with XML content
+ */
+export declare function generateSitemap(pages: PageModel[], config: StatiConfig, sitemapConfig: SitemapConfig): SitemapGenerationResult;
+//# sourceMappingURL=sitemap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap.d.ts","sourceRoot":"","sources":["../../src/seo/sitemap.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EAEb,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA6ItD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,EACnB,aAAa,EAAE,aAAa,GAC3B,YAAY,GAAG,IAAI,CA4ErB;AA2BD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAUlE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAatF;AAoBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,EAAE,EAClB,MAAM,EAAE,WAAW,EACnB,aAAa,EAAE,aAAa,GAC3B,uBAAuB,CA8CzB"}

package/dist/seo/sitemap.js

@@ -0,0 +1,320 @@
+/**
+ * Sitemap generation utilities for Stati
+ * @module seo/sitemap
+ */
+import { escapeHtml, resolveAbsoluteUrl } from './utils/index.js';
+/**
+ * Maximum entries per sitemap file (per sitemap.org spec)
+ */
+const MAX_SITEMAP_ENTRIES = 50000;
+/**
+ * Formats a date for sitemap lastmod field (W3C Datetime / ISO 8601)
+ * @param date - Date to format
+ * @returns ISO 8601 formatted date string (YYYY-MM-DD)
+ */
+function formatSitemapDate(date) {
+    const parts = date.toISOString().split('T');
+    if (parts[0]) {
+        return parts[0];
+    }
+    return date.toISOString().substring(0, 10);
+}
+/**
+ * Validates and clamps priority value to 0.0-1.0 range
+ * @param priority - Priority value to validate
+ * @returns Clamped priority value
+ */
+function validatePriority(priority) {
+    if (isNaN(priority)) {
+        return 0.5;
+    }
+    return Math.max(0.0, Math.min(1.0, priority));
+}
+/**
+ * Validates change frequency value
+ * @param changefreq - Change frequency to validate
+ * @returns Valid change frequency or undefined
+ */
+function validateChangeFreq(changefreq) {
+    const validFreqs = ['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never'];
+    if (changefreq && validFreqs.includes(changefreq)) {
+        return changefreq;
+    }
+    return undefined;
+}
+/**
+ * Escapes regex special characters in a string, except glob wildcards
+ * @param str - String to escape
+ * @returns String with regex special characters escaped
+ */
+function escapeRegexExceptGlob(str) {
+    // Escape all regex special characters except * and ?
+    return str.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Checks if a page URL matches a list of patterns.
+ * @param url - The URL to check.
+ * @param patterns - An array of glob-style patterns.
+ * @returns `true` if the URL matches any pattern, `false` otherwise.
+ */
+function urlMatchesAnyPattern(url, patterns) {
+    for (const pattern of patterns) {
+        // Simple glob patterns
+        if (pattern.includes('*') || pattern.includes('?')) {
+            // Escape regex special characters first, then convert glob wildcards
+            const escapedPattern = escapeRegexExceptGlob(pattern);
+            const regexPattern = escapedPattern.replace(/\*/g, '.*').replace(/\?/g, '.');
+            const regex = new RegExp('^' + regexPattern + '$');
+            if (regex.test(url)) {
+                return true;
+            }
+        }
+        else if (url === pattern || url.startsWith(pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Checks if a page matches exclude patterns
+ * @param page - Page to check
+ * @param patterns - Exclude patterns (glob or regex)
+ * @returns true if page should be excluded
+ */
+function matchesExcludePattern(page, patterns) {
+    if (!patterns || patterns.length === 0) {
+        return false;
+    }
+    return urlMatchesAnyPattern(page.url, patterns);
+}
+/**
+ * Checks if a page matches include patterns
+ * @param page - Page to check
+ * @param patterns - Include patterns (glob or regex)
+ * @returns true if page should be included
+ */
+function matchesIncludePattern(page, patterns) {
+    if (!patterns || patterns.length === 0) {
+        return true; // Include all by default
+    }
+    return urlMatchesAnyPattern(page.url, patterns);
+}
+/**
+ * Determines priority for a page based on priority rules
+ * @param page - Page to evaluate
+ * @param rules - Priority rules from config
+ * @param defaultPriority - Default priority value
+ * @returns Calculated priority
+ */
+function determinePriority(page, rules, defaultPriority = 0.5) {
+    if (!rules || rules.length === 0) {
+        return defaultPriority;
+    }
+    // Check each rule in order (first match wins)
+    for (const rule of rules) {
+        const pattern = rule.pattern;
+        if (pattern.includes('*') || pattern.includes('?')) {
+            // Escape regex special characters first, then convert glob wildcards
+            const escapedPattern = escapeRegexExceptGlob(pattern);
+            const regexPattern = escapedPattern.replace(/\*/g, '.*').replace(/\?/g, '.');
+            const regex = new RegExp('^' + regexPattern + '$');
+            if (regex.test(page.url)) {
+                return validatePriority(rule.priority);
+            }
+        }
+        else if (page.url === pattern || page.url.startsWith(pattern)) {
+            return validatePriority(rule.priority);
+        }
+    }
+    return defaultPriority;
+}
+/**
+ * Generates a sitemap entry from a page model
+ * @param page - Page to generate entry for
+ * @param config - Stati configuration
+ * @param sitemapConfig - Sitemap configuration
+ * @returns Sitemap entry or null if page should be excluded
+ */
+export function generateSitemapEntry(page, config, sitemapConfig) {
+    // Check frontmatter exclude flag
+    if (page.frontMatter.sitemap?.exclude === true) {
+        return null;
+    }
+    // Check exclude patterns
+    if (matchesExcludePattern(page, sitemapConfig.excludePatterns)) {
+        return null;
+    }
+    // Check include patterns
+    if (!matchesIncludePattern(page, sitemapConfig.includePatterns)) {
+        return null;
+    }
+    // Apply filter function if provided
+    if (sitemapConfig.filter && !sitemapConfig.filter(page)) {
+        return null;
+    }
+    const siteUrl = config.site.baseUrl;
+    // Determine lastmod
+    let lastmod;
+    if (page.frontMatter.sitemap?.lastmod) {
+        lastmod = formatSitemapDate(new Date(page.frontMatter.sitemap.lastmod));
+    }
+    else if (page.frontMatter.updated) {
+        lastmod = formatSitemapDate(new Date(page.frontMatter.updated));
+    }
+    else if (page.frontMatter.date) {
+        lastmod = formatSitemapDate(new Date(page.frontMatter.date));
+    }
+    // Determine changefreq
+    let changefreq;
+    if (page.frontMatter.sitemap?.changefreq) {
+        changefreq = validateChangeFreq(page.frontMatter.sitemap.changefreq);
+    }
+    if (!changefreq && sitemapConfig.defaultChangeFreq) {
+        changefreq = sitemapConfig.defaultChangeFreq;
+    }
+    // Determine priority
+    let priority;
+    if (page.frontMatter.sitemap?.priority !== undefined) {
+        priority = validatePriority(page.frontMatter.sitemap.priority);
+    }
+    else {
+        priority = determinePriority(page, sitemapConfig.priorityRules, sitemapConfig.defaultPriority);
+    }
+    // Resolve absolute URL
+    let url = resolveAbsoluteUrl(page.url, siteUrl);
+    // Apply transformUrl if provided
+    if (sitemapConfig.transformUrl) {
+        url = sitemapConfig.transformUrl(url, page, config);
+    }
+    // Build entry
+    const entry = { url };
+    if (lastmod !== undefined) {
+        entry.lastmod = lastmod;
+    }
+    if (changefreq !== undefined) {
+        entry.changefreq = changefreq;
+    }
+    if (priority !== undefined) {
+        entry.priority = priority;
+    }
+    // Apply transformEntry if provided
+    if (sitemapConfig.transformEntry) {
+        return sitemapConfig.transformEntry(entry, page);
+    }
+    return entry;
+}
+/**
+ * Generates XML for a single sitemap entry
+ * @param entry - Sitemap entry
+ * @returns XML string for entry
+ */
+function generateEntryXml(entry) {
+    let xml = '  <url>\n';
+    xml += `    <loc>${escapeHtml(entry.url)}</loc>\n`;
+    if (entry.lastmod) {
+        xml += `    <lastmod>${escapeHtml(entry.lastmod)}</lastmod>\n`;
+    }
+    if (entry.changefreq) {
+        xml += `    <changefreq>${escapeHtml(entry.changefreq)}</changefreq>\n`;
+    }
+    if (entry.priority !== undefined) {
+        xml += `    <priority>${entry.priority.toFixed(1)}</priority>\n`;
+    }
+    xml += '  </url>\n';
+    return xml;
+}
+/**
+ * Generates sitemap XML from entries
+ * @param entries - Sitemap entries
+ * @returns Complete sitemap XML
+ */
+export function generateSitemapXml(entries) {
+    let xml = '<?xml version="1.0" encoding="UTF-8"?>\n';
+    xml += '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n';
+    for (const entry of entries) {
+        xml += generateEntryXml(entry);
+    }
+    xml += '</urlset>\n';
+    return xml;
+}
+/**
+ * Generates sitemap index XML for multiple sitemaps
+ * @param sitemapUrls - Array of sitemap URLs
+ * @param siteUrl - Base site URL
+ * @returns Sitemap index XML
+ */
+export function generateSitemapIndexXml(sitemapUrls, siteUrl) {
+    let xml = '<?xml version="1.0" encoding="UTF-8"?>\n';
+    xml += '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n';
+    for (const url of sitemapUrls) {
+        const absoluteUrl = resolveAbsoluteUrl(url, siteUrl);
+        xml += '  <sitemap>\n';
+        xml += `    <loc>${escapeHtml(absoluteUrl)}</loc>\n`;
+        xml += '  </sitemap>\n';
+    }
+    xml += '</sitemapindex>\n';
+    return xml;
+}
+/**
+ * Splits entries into multiple sitemaps if needed
+ * @param entries - All sitemap entries
+ * @returns Array of entry arrays (one per sitemap file)
+ */
+function splitEntriesIntoSitemaps(entries) {
+    if (entries.length <= MAX_SITEMAP_ENTRIES) {
+        return [entries];
+    }
+    const sitemaps = [];
+    for (let i = 0; i < entries.length; i += MAX_SITEMAP_ENTRIES) {
+        sitemaps.push(entries.slice(i, i + MAX_SITEMAP_ENTRIES));
+    }
+    return sitemaps;
+}
+/**
+ * Generates sitemap(s) from pages
+ * @param pages - All pages to include in sitemap
+ * @param config - Stati configuration
+ * @param sitemapConfig - Sitemap configuration
+ * @returns Sitemap generation result with XML content
+ */
+export function generateSitemap(pages, config, sitemapConfig) {
+    // Generate entries for all pages
+    const entries = [];
+    for (const page of pages) {
+        const entry = generateSitemapEntry(page, config, sitemapConfig);
+        if (entry) {
+            entries.push(entry);
+        }
+    }
+    // Check if we need multiple sitemaps
+    const sitemapGroups = splitEntriesIntoSitemaps(entries);
+    if (sitemapGroups.length === 1 && sitemapGroups[0]) {
+        // Single sitemap
+        const xml = generateSitemapXml(sitemapGroups[0]);
+        return {
+            xml,
+            entryCount: entries.length,
+            sizeInBytes: Buffer.byteLength(xml, 'utf8'),
+        };
+    }
+    // Multiple sitemaps - generate index
+    const sitemapUrls = [];
+    const sitemapFiles = [];
+    for (let i = 0; i < sitemapGroups.length; i++) {
+        const group = sitemapGroups[i];
+        if (!group)
+            continue;
+        const filename = `sitemap-${i + 1}.xml`;
+        const xml = generateSitemapXml(group);
+        sitemapUrls.push(`/${filename}`);
+        sitemapFiles.push({ filename, xml });
+    }
+    // Generate index
+    const indexXml = generateSitemapIndexXml(sitemapUrls, config.site.baseUrl);
+    return {
+        xml: indexXml,
+        entryCount: entries.length,
+        sizeInBytes: Buffer.byteLength(indexXml, 'utf8'),
+        sitemaps: sitemapFiles,
+    };
+}

package/dist/seo/utils/escape-and-validation.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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';
+import type { Logger } from '../../types/logging.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.
+ *
+ * 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 declare function sanitizeStructuredData(data: unknown, logger: Logger, 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=escape-and-validation.d.ts.map

package/dist/seo/utils/escape-and-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-and-validation.d.ts","sourceRoot":"","sources":["../../../src/seo/utils/escape-and-validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,wBAAwB,CAAC;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AASrD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA4B/C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAU,EACjB,QAAQ,GAAE,MAAW,GACpB,OAAO,CA0CT;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"}