@stati/core 1.0.0 → 1.2.0

package/dist/core/isg/manifest.js

@@ -0,0 +1,233 @@
+import fse from 'fs-extra';
+const { readFile, writeFile, pathExists, ensureDir } = fse;
+import { join } from 'path';
+/**
+ * Path to the cache manifest file within the cache directory
+ */
+const MANIFEST_FILENAME = 'manifest.json';
+/**
+ * Loads the ISG cache manifest from the cache directory.
+ * Returns null if no manifest exists or if it's corrupted.
+ * Provides detailed error reporting for different failure scenarios.
+ *
+ * @param cacheDir - Path to the .stati cache directory
+ * @returns Promise resolving to the cache manifest or null
+ *
+ * @example
+ * ```typescript
+ * const manifest = await loadCacheManifest('.stati');
+ * if (manifest) {
+ *   console.log(`Found ${Object.keys(manifest.entries).length} cached entries`);
+ * }
+ * ```
+ */
+export async function loadCacheManifest(cacheDir) {
+    const manifestPath = join(cacheDir, MANIFEST_FILENAME);
+    try {
+        if (!(await pathExists(manifestPath))) {
+            return null;
+        }
+        const manifestContent = await readFile(manifestPath, 'utf-8');
+        // Handle empty files
+        if (!manifestContent.trim()) {
+            console.warn('Cache manifest is empty, creating new cache');
+            return null;
+        }
+        let manifest;
+        try {
+            manifest = JSON.parse(manifestContent);
+        }
+        catch (parseError) {
+            console.warn(`Cache manifest contains invalid JSON, ignoring existing cache. ` +
+                `Error: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+            return null;
+        }
+        // Detailed validation of manifest structure
+        if (!manifest || typeof manifest !== 'object') {
+            console.warn('Cache manifest is not an object, ignoring existing cache');
+            return null;
+        }
+        const manifestObj = manifest;
+        if (!manifestObj.entries) {
+            console.warn('Cache manifest missing "entries" field, ignoring existing cache');
+            return null;
+        }
+        if (typeof manifestObj.entries !== 'object' || Array.isArray(manifestObj.entries)) {
+            console.warn('Cache manifest "entries" field is not an object, ignoring existing cache');
+            return null;
+        }
+        // Validate individual cache entries
+        const entries = manifestObj.entries;
+        const validatedEntries = {};
+        let invalidEntryCount = 0;
+        for (const [path, entry] of Object.entries(entries)) {
+            if (validateCacheEntry(entry, path)) {
+                validatedEntries[path] = entry;
+            }
+            else {
+                invalidEntryCount++;
+            }
+        }
+        if (invalidEntryCount > 0) {
+            console.warn(`Removed ${invalidEntryCount} invalid cache entries`);
+        }
+        return { entries: validatedEntries };
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT') {
+            return null; // File doesn't exist, this is normal
+        }
+        if (nodeError.code === 'EACCES') {
+            console.error(`Permission denied reading cache manifest at ${manifestPath}. ` +
+                `Please check file permissions or run with appropriate privileges.`);
+            return null;
+        }
+        if (nodeError.code === 'EMFILE' || nodeError.code === 'ENFILE') {
+            console.error(`Too many open files when reading cache manifest. ` +
+                `Consider reducing concurrent operations or increasing file descriptor limits.`);
+            return null;
+        }
+        console.warn(`Failed to load cache manifest: ${error instanceof Error ? error.message : String(error)}. ` +
+            `Starting with fresh cache.`);
+        return null;
+    }
+}
+/**
+ * Saves the ISG cache manifest to the cache directory.
+ * Creates the cache directory if it doesn't exist.
+ * Provides detailed error handling for common file system issues.
+ *
+ * @param cacheDir - Path to the .stati cache directory
+ * @param manifest - The cache manifest to save
+ * @throws {Error} If the manifest cannot be saved
+ *
+ * @example
+ * ```typescript
+ * const manifest: CacheManifest = { entries: {} };
+ * await saveCacheManifest('.stati', manifest);
+ * ```
+ */
+export async function saveCacheManifest(cacheDir, manifest) {
+    const manifestPath = join(cacheDir, MANIFEST_FILENAME);
+    try {
+        // Ensure cache directory exists
+        await ensureDir(cacheDir);
+        // Save manifest with pretty formatting for debugging
+        const manifestContent = JSON.stringify(manifest, null, 2);
+        await writeFile(manifestPath, manifestContent, 'utf-8');
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'EACCES') {
+            throw new Error(`Permission denied saving cache manifest to ${manifestPath}. ` +
+                `Please check directory permissions or run with appropriate privileges.`);
+        }
+        if (nodeError.code === 'ENOSPC') {
+            throw new Error(`No space left on device when saving cache manifest to ${manifestPath}. ` +
+                `Please free up disk space and try again.`);
+        }
+        if (nodeError.code === 'EMFILE' || nodeError.code === 'ENFILE') {
+            throw new Error(`Too many open files when saving cache manifest. ` +
+                `Consider reducing concurrent operations or increasing file descriptor limits.`);
+        }
+        if (nodeError.code === 'ENOTDIR') {
+            throw new Error(`Cache directory path ${cacheDir} is not a directory. ` +
+                `Please remove the conflicting file and try again.`);
+        }
+        throw new Error(`Failed to save cache manifest to ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Creates an empty cache manifest with no entries.
+ *
+ * @returns A new empty cache manifest
+ *
+ * @example
+ * ```typescript
+ * const manifest = createEmptyManifest();
+ * console.log(Object.keys(manifest.entries).length); // 0
+ * ```
+ */
+export function createEmptyManifest() {
+    return {
+        entries: {},
+    };
+}
+/**
+ * Validates a cache entry object to ensure it has the required structure.
+ * Used when loading cache manifest to filter out corrupted entries.
+ *
+ * @param entry - The cache entry to validate
+ * @param path - The path key for error context
+ * @returns True if the entry is valid, false otherwise
+ */
+function validateCacheEntry(entry, path) {
+    if (!entry || typeof entry !== 'object') {
+        console.warn(`Invalid cache entry for ${path}: not an object`);
+        return false;
+    }
+    const entryObj = entry;
+    // Check required fields
+    const requiredFields = ['path', 'inputsHash', 'deps', 'tags', 'renderedAt', 'ttlSeconds'];
+    for (const field of requiredFields) {
+        if (!(field in entryObj)) {
+            console.warn(`Invalid cache entry for ${path}: missing required field "${field}"`);
+            return false;
+        }
+    }
+    // Validate field types
+    if (typeof entryObj.path !== 'string') {
+        console.warn(`Invalid cache entry for ${path}: "path" must be a string`);
+        return false;
+    }
+    if (typeof entryObj.inputsHash !== 'string') {
+        console.warn(`Invalid cache entry for ${path}: "inputsHash" must be a string`);
+        return false;
+    }
+    if (!Array.isArray(entryObj.deps)) {
+        console.warn(`Invalid cache entry for ${path}: "deps" must be an array`);
+        return false;
+    }
+    if (!Array.isArray(entryObj.tags)) {
+        console.warn(`Invalid cache entry for ${path}: "tags" must be an array`);
+        return false;
+    }
+    if (typeof entryObj.renderedAt !== 'string') {
+        console.warn(`Invalid cache entry for ${path}: "renderedAt" must be a string`);
+        return false;
+    }
+    if (typeof entryObj.ttlSeconds !== 'number') {
+        console.warn(`Invalid cache entry for ${path}: "ttlSeconds" must be a number`);
+        return false;
+    }
+    // Validate optional fields if present
+    if (entryObj.publishedAt !== undefined && typeof entryObj.publishedAt !== 'string') {
+        console.warn(`Invalid cache entry for ${path}: "publishedAt" must be a string if present`);
+        return false;
+    }
+    if (entryObj.maxAgeCapDays !== undefined && typeof entryObj.maxAgeCapDays !== 'number') {
+        console.warn(`Invalid cache entry for ${path}: "maxAgeCapDays" must be a number if present`);
+        return false;
+    }
+    // Validate that deps and tags arrays contain strings
+    if (!entryObj.deps.every((dep) => typeof dep === 'string')) {
+        console.warn(`Invalid cache entry for ${path}: all "deps" must be strings`);
+        return false;
+    }
+    if (!entryObj.tags.every((tag) => typeof tag === 'string')) {
+        console.warn(`Invalid cache entry for ${path}: all "tags" must be strings`);
+        return false;
+    }
+    // Validate date format for renderedAt
+    if (isNaN(new Date(entryObj.renderedAt).getTime())) {
+        console.warn(`Invalid cache entry for ${path}: "renderedAt" is not a valid date`);
+        return false;
+    }
+    // Validate date format for publishedAt if present
+    if (entryObj.publishedAt && isNaN(new Date(entryObj.publishedAt).getTime())) {
+        console.warn(`Invalid cache entry for ${path}: "publishedAt" is not a valid date`);
+        return false;
+    }
+    return true;
+}

package/dist/core/isg/ttl.d.ts

@@ -0,0 +1,101 @@
+import type { PageModel, ISGConfig, AgingRule, CacheEntry } from '../../types.js';
+/**
+ * Safely gets the current UTC time with drift protection.
+ * Ensures all ISG operations use consistent UTC time.
+ *
+ * @param providedDate - Optional date to use instead of system time (for testing)
+ * @returns UTC Date object
+ */
+export declare function getSafeCurrentTime(providedDate?: Date): Date;
+/**
+ * Safely parses and normalizes a date string to UTC.
+ * Handles various date formats and timezone issues.
+ *
+ * @param dateStr - Date string to parse
+ * @param context - Context for error messages
+ * @returns Parsed UTC date or null if invalid
+ */
+export declare function parseSafeDate(dateStr: string, context?: string): Date | null;
+/**
+ * Computes the effective TTL for a page based on configuration and page-specific overrides.
+ * Takes into account aging rules and front-matter overrides.
+ * Uses safe time handling to avoid timezone issues.
+ *
+ * @param page - The page model
+ * @param isgConfig - ISG configuration
+ * @param currentTime - Optional current time (for testing)
+ * @returns Effective TTL in seconds
+ *
+ * @example
+ * ```typescript
+ * const ttl = computeEffectiveTTL(page, config.isg);
+ * console.log(`Page will be cached for ${ttl} seconds`);
+ * ```
+ */
+export declare function computeEffectiveTTL(page: PageModel, isgConfig: ISGConfig, currentTime?: Date): number;
+/**
+ * Computes the next rebuild date for a page based on TTL and aging rules.
+ * Returns null if the page is frozen (beyond max age cap).
+ * Uses safe time handling with clock drift protection.
+ *
+ * @param options - Configuration options
+ * @param options.now - Current date/time
+ * @param options.publishedAt - When the content was originally published
+ * @param options.ttlSeconds - TTL for this page in seconds
+ * @param options.maxAgeCapDays - Maximum age cap in days
+ * @returns Next rebuild date, or null if frozen
+ *
+ * @example
+ * ```typescript
+ * const nextRebuild = computeNextRebuildAt({
+ *   now: new Date(),
+ *   publishedAt: new Date('2024-01-01'),
+ *   ttlSeconds: 3600,
+ *   maxAgeCapDays: 365
+ * });
+ * ```
+ */
+export declare function computeNextRebuildAt(options: {
+    now: Date;
+    publishedAt?: Date;
+    ttlSeconds: number;
+    maxAgeCapDays?: number;
+}): Date | null;
+/**
+ * Determines if a page is frozen (beyond its max age cap).
+ * Frozen pages are not rebuilt unless their content changes.
+ * Uses safe time handling to avoid timezone issues.
+ *
+ * @param entry - Cache entry for the page
+ * @param now - Current date/time
+ * @returns True if the page is frozen
+ *
+ * @example
+ * ```typescript
+ * if (isPageFrozen(cacheEntry, new Date())) {
+ *   console.log('Page is frozen, will not rebuild based on TTL');
+ * }
+ * ```
+ */
+export declare function isPageFrozen(entry: CacheEntry, now: Date): boolean;
+/**
+ * Applies aging rules to determine the appropriate TTL for content based on its age.
+ * Aging rules allow older content to be cached longer.
+ *
+ * @param publishedAt - When the content was originally published
+ * @param agingRules - Array of aging rules (sorted by untilDays ascending)
+ * @param defaultTTL - Default TTL to use if no rules match
+ * @param now - Current date/time
+ * @returns Appropriate TTL in seconds
+ *
+ * @example
+ * ```typescript
+ * const rules = [
+ *   { untilDays: 7, ttlSeconds: 3600 },    // 1 hour for week-old content
+ *   { untilDays: 30, ttlSeconds: 86400 }   // 1 day for month-old content
+ * ];
+ * const ttl = applyAgingRules(publishedAt, rules, 1800, new Date());
+ * ```
+ */
+export declare function applyAgingRules(publishedAt: Date, agingRules: AgingRule[], defaultTTL: number, now: Date): number;
+//# sourceMappingURL=ttl.d.ts.map

package/dist/core/isg/ttl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl.d.ts","sourceRoot":"","sources":["../../../src/core/isg/ttl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAQlF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,CAAC,EAAE,IAAI,GAAG,IAAI,CAW5D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAqB5E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,EACf,SAAS,EAAE,SAAS,EACpB,WAAW,CAAC,EAAE,IAAI,GACjB,MAAM,CAkBR;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC5C,GAAG,EAAE,IAAI,CAAC;IACV,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,IAAI,GAAG,IAAI,CAqBd;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAiBlE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,IAAI,EACjB,UAAU,EAAE,SAAS,EAAE,EACvB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,IAAI,GACR,MAAM,CAyBR"}

package/dist/core/isg/ttl.js

@@ -0,0 +1,222 @@
+/**
+ * Clock drift tolerance in milliseconds.
+ * Accounts for small differences between system clocks.
+ */
+const CLOCK_DRIFT_TOLERANCE_MS = 30000; // 30 seconds
+/**
+ * Safely gets the current UTC time with drift protection.
+ * Ensures all ISG operations use consistent UTC time.
+ *
+ * @param providedDate - Optional date to use instead of system time (for testing)
+ * @returns UTC Date object
+ */
+export function getSafeCurrentTime(providedDate) {
+    const now = providedDate || new Date();
+    // Ensure we're working with valid dates
+    if (isNaN(now.getTime())) {
+        console.warn('Invalid system date detected, using fallback date');
+        return new Date('2025-01-01T00:00:00.000Z'); // Fallback to known good date
+    }
+    // Normalize to UTC to avoid timezone issues
+    return new Date(now.toISOString());
+}
+/**
+ * Safely parses and normalizes a date string to UTC.
+ * Handles various date formats and timezone issues.
+ *
+ * @param dateStr - Date string to parse
+ * @param context - Context for error messages
+ * @returns Parsed UTC date or null if invalid
+ */
+export function parseSafeDate(dateStr, context) {
+    try {
+        const parsed = new Date(dateStr);
+        if (isNaN(parsed.getTime())) {
+            if (context) {
+                console.warn(`Invalid date "${dateStr}" in ${context}, ignoring`);
+            }
+            return null;
+        }
+        // Normalize to UTC
+        return new Date(parsed.toISOString());
+    }
+    catch (error) {
+        if (context) {
+            console.warn(`Failed to parse date "${dateStr}" in ${context}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return null;
+    }
+}
+/**
+ * Computes the effective TTL for a page based on configuration and page-specific overrides.
+ * Takes into account aging rules and front-matter overrides.
+ * Uses safe time handling to avoid timezone issues.
+ *
+ * @param page - The page model
+ * @param isgConfig - ISG configuration
+ * @param currentTime - Optional current time (for testing)
+ * @returns Effective TTL in seconds
+ *
+ * @example
+ * ```typescript
+ * const ttl = computeEffectiveTTL(page, config.isg);
+ * console.log(`Page will be cached for ${ttl} seconds`);
+ * ```
+ */
+export function computeEffectiveTTL(page, isgConfig, currentTime) {
+    // Check for page-specific TTL override in front matter
+    if (typeof page.frontMatter.ttlSeconds === 'number' && page.frontMatter.ttlSeconds > 0) {
+        return page.frontMatter.ttlSeconds;
+    }
+    // Get publishedAt date for aging calculations
+    const publishedAt = getPublishedDate(page);
+    const now = getSafeCurrentTime(currentTime);
+    // Apply aging rules if we have a published date and aging rules configured
+    if (publishedAt && isgConfig.aging && isgConfig.aging.length > 0) {
+        const defaultTTL = isgConfig.ttlSeconds ?? 21600; // 6 hours default
+        return applyAgingRules(publishedAt, isgConfig.aging, defaultTTL, now);
+    }
+    // Fall back to default TTL
+    return isgConfig.ttlSeconds ?? 21600; // 6 hours default
+}
+/**
+ * Computes the next rebuild date for a page based on TTL and aging rules.
+ * Returns null if the page is frozen (beyond max age cap).
+ * Uses safe time handling with clock drift protection.
+ *
+ * @param options - Configuration options
+ * @param options.now - Current date/time
+ * @param options.publishedAt - When the content was originally published
+ * @param options.ttlSeconds - TTL for this page in seconds
+ * @param options.maxAgeCapDays - Maximum age cap in days
+ * @returns Next rebuild date, or null if frozen
+ *
+ * @example
+ * ```typescript
+ * const nextRebuild = computeNextRebuildAt({
+ *   now: new Date(),
+ *   publishedAt: new Date('2024-01-01'),
+ *   ttlSeconds: 3600,
+ *   maxAgeCapDays: 365
+ * });
+ * ```
+ */
+export function computeNextRebuildAt(options) {
+    const { publishedAt, ttlSeconds, maxAgeCapDays } = options;
+    // Normalize the provided time to UTC
+    const now = getSafeCurrentTime(options.now);
+    // If there's a max age cap and published date, check if content is frozen
+    if (maxAgeCapDays && publishedAt) {
+        const normalizedPublishedAt = getSafeCurrentTime(publishedAt);
+        const maxAgeMs = maxAgeCapDays * 24 * 60 * 60 * 1000;
+        const ageMs = now.getTime() - normalizedPublishedAt.getTime();
+        if (ageMs > maxAgeMs) {
+            // Content is frozen, no rebuild needed
+            return null;
+        }
+    }
+    // Add clock drift tolerance to prevent rebuild loops
+    const nextRebuildTime = now.getTime() + ttlSeconds * 1000 + CLOCK_DRIFT_TOLERANCE_MS;
+    return new Date(nextRebuildTime);
+}
+/**
+ * Determines if a page is frozen (beyond its max age cap).
+ * Frozen pages are not rebuilt unless their content changes.
+ * Uses safe time handling to avoid timezone issues.
+ *
+ * @param entry - Cache entry for the page
+ * @param now - Current date/time
+ * @returns True if the page is frozen
+ *
+ * @example
+ * ```typescript
+ * if (isPageFrozen(cacheEntry, new Date())) {
+ *   console.log('Page is frozen, will not rebuild based on TTL');
+ * }
+ * ```
+ */
+export function isPageFrozen(entry, now) {
+    if (!entry.maxAgeCapDays || !entry.publishedAt) {
+        return false;
+    }
+    const safeNow = getSafeCurrentTime(now);
+    const publishedAt = parseSafeDate(entry.publishedAt, `cache entry for ${entry.path}`);
+    if (!publishedAt) {
+        // If we can't parse the published date, don't freeze
+        return false;
+    }
+    const maxAgeMs = entry.maxAgeCapDays * 24 * 60 * 60 * 1000;
+    const ageMs = safeNow.getTime() - publishedAt.getTime();
+    return ageMs > maxAgeMs;
+}
+/**
+ * Applies aging rules to determine the appropriate TTL for content based on its age.
+ * Aging rules allow older content to be cached longer.
+ *
+ * @param publishedAt - When the content was originally published
+ * @param agingRules - Array of aging rules (sorted by untilDays ascending)
+ * @param defaultTTL - Default TTL to use if no rules match
+ * @param now - Current date/time
+ * @returns Appropriate TTL in seconds
+ *
+ * @example
+ * ```typescript
+ * const rules = [
+ *   { untilDays: 7, ttlSeconds: 3600 },    // 1 hour for week-old content
+ *   { untilDays: 30, ttlSeconds: 86400 }   // 1 day for month-old content
+ * ];
+ * const ttl = applyAgingRules(publishedAt, rules, 1800, new Date());
+ * ```
+ */
+export function applyAgingRules(publishedAt, agingRules, defaultTTL, now) {
+    const ageMs = now.getTime() - publishedAt.getTime();
+    const ageDays = ageMs / (24 * 60 * 60 * 1000);
+    // Sort rules by untilDays in ascending order to apply the most specific rule
+    const sortedRules = [...agingRules].sort((a, b) => a.untilDays - b.untilDays);
+    // Find the most specific rule that applies
+    let applicableRule = null;
+    for (const rule of sortedRules) {
+        if (ageDays <= rule.untilDays) {
+            applicableRule = rule;
+            break;
+        }
+    }
+    // If no rule applies, use the last (highest untilDays) rule if age exceeds all rules
+    if (!applicableRule && sortedRules.length > 0) {
+        const lastRule = sortedRules[sortedRules.length - 1];
+        if (lastRule && ageDays > lastRule.untilDays) {
+            applicableRule = lastRule;
+        }
+    }
+    return applicableRule ? applicableRule.ttlSeconds : defaultTTL;
+}
+/**
+ * Helper function to extract published date from page front matter.
+ * Supports various date formats and field names.
+ * Uses safe date parsing to handle timezone issues.
+ */
+function getPublishedDate(page) {
+    const frontMatter = page.frontMatter;
+    // Try common field names for published date
+    const dateFields = ['publishedAt', 'published', 'date', 'createdAt'];
+    for (const field of dateFields) {
+        const value = frontMatter[field];
+        if (value) {
+            // Handle string dates
+            if (typeof value === 'string') {
+                const safeDate = parseSafeDate(value, `front-matter field "${field}" in ${page.sourcePath}`);
+                if (safeDate) {
+                    return safeDate;
+                }
+            }
+            // Handle Date objects
+            if (value instanceof Date) {
+                const safeDate = getSafeCurrentTime(value);
+                if (safeDate && !isNaN(safeDate.getTime())) {
+                    return safeDate;
+                }
+            }
+        }
+    }
+    return null;
+}

package/dist/core/isg/validation.d.ts

@@ -0,0 +1,71 @@
+import type { ISGConfig } from '../../types.js';
+/**
+ * Error codes for ISG validation failures.
+ * These provide structured error identification for better debugging.
+ */
+export declare enum ISGValidationError {
+    INVALID_TTL = "ISG_INVALID_TTL",
+    INVALID_MAX_AGE_CAP = "ISG_INVALID_MAX_AGE_CAP",
+    INVALID_AGING_RULE = "ISG_INVALID_AGING_RULE",
+    DUPLICATE_AGING_RULE = "ISG_DUPLICATE_AGING_RULE",
+    UNSORTED_AGING_RULES = "ISG_UNSORTED_AGING_RULES",
+    AGING_RULE_EXCEEDS_CAP = "ISG_AGING_RULE_EXCEEDS_CAP"
+}
+/**
+ * Represents a validation error with context and actionable message.
+ */
+export declare class ISGConfigurationError extends Error {
+    readonly code: ISGValidationError;
+    readonly field: string;
+    readonly value: unknown;
+    constructor(code: ISGValidationError, field: string, value: unknown, message: string);
+}
+/**
+ * Validates ISG configuration and provides actionable error messages.
+ * Throws ISGConfigurationError for invalid configurations.
+ *
+ * @param config - ISG configuration to validate
+ * @throws {ISGConfigurationError} When configuration is invalid
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validateISGConfig(userConfig.isg);
+ * } catch (error) {
+ *   if (error instanceof ISGConfigurationError) {
+ *     console.error(`${error.code}: ${error.message}`);
+ *     console.error(`Field: ${error.field}, Value: ${error.value}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function validateISGConfig(config: ISGConfig): void;
+/**
+ * Validates front-matter ISG overrides for a single page.
+ * Provides helpful error messages for invalid page-level configuration.
+ *
+ * @param frontMatter - Page front-matter object
+ * @param sourcePath - Path to source file for error context
+ * @throws {ISGConfigurationError} When front-matter overrides are invalid
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validatePageISGOverrides(page.frontMatter, page.sourcePath);
+ * } catch (error) {
+ *   console.error(`Error in ${page.sourcePath}: ${error.message}`);
+ * }
+ * ```
+ */
+export declare function validatePageISGOverrides(frontMatter: Record<string, unknown>, sourcePath: string): void;
+/**
+ * Safely extracts numeric value from front-matter with validation.
+ * Used for TTL and max age cap overrides.
+ *
+ * @param value - Value from front-matter
+ * @param fieldName - Name of the field for error messages
+ * @param sourcePath - Source file path for error context
+ * @returns Validated number or undefined if not set
+ */
+export declare function extractNumericOverride(value: unknown, fieldName: string, sourcePath: string): number | undefined;
+//# sourceMappingURL=validation.d.ts.map

package/dist/core/isg/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/core/isg/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,gBAAgB,CAAC;AAE3D;;;GAGG;AACH,oBAAY,kBAAkB;IAC5B,WAAW,oBAAoB;IAC/B,mBAAmB,4BAA4B;IAC/C,kBAAkB,2BAA2B;IAC7C,oBAAoB,6BAA6B;IACjD,oBAAoB,6BAA6B;IACjD,sBAAsB,+BAA+B;CACtD;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,IAAI,EAAE,kBAAkB;aACxB,KAAK,EAAE,MAAM;aACb,KAAK,EAAE,OAAO;gBAFd,IAAI,EAAE,kBAAkB,EACxB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,EAC9B,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAmBzD;AAmLD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,UAAU,EAAE,MAAM,GACjB,IAAI,CAwDN;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CAoCpB"}