@stati/core 1.1.0 → 1.3.0

package/dist/core/isg/deps.js

@@ -0,0 +1,332 @@
+import { join, dirname, relative, posix } from 'path';
+import fse from 'fs-extra';
+const { pathExists, readFile } = fse;
+import glob from 'fast-glob';
+/**
+ * Error thrown when a circular dependency is detected in templates.
+ */
+export class CircularDependencyError extends Error {
+    dependencyChain;
+    constructor(dependencyChain, message) {
+        super(message);
+        this.dependencyChain = dependencyChain;
+        this.name = 'CircularDependencyError';
+    }
+}
+/**
+ * Tracks all template dependencies for a given page.
+ * This includes the layout file and all accessible partials.
+ * Includes circular dependency detection.
+ *
+ * @param page - The page model to track dependencies for
+ * @param config - Stati configuration
+ * @returns Array of absolute paths to dependency files
+ * @throws {CircularDependencyError} When circular dependencies are detected
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const deps = await trackTemplateDependencies(page, config);
+ *   console.log(`Page depends on ${deps.length} template files`);
+ * } catch (error) {
+ *   if (error instanceof CircularDependencyError) {
+ *     console.error(`Circular dependency: ${error.dependencyChain.join(' -> ')}`);
+ *   }
+ * }
+ * ```
+ */
+export async function trackTemplateDependencies(page, config) {
+    // Early return if required config values are missing
+    if (!config.srcDir) {
+        console.warn('Config srcDir is missing, cannot track template dependencies');
+        return [];
+    }
+    const deps = [];
+    const srcDir = join(process.cwd(), config.srcDir);
+    const relativePath = relative(srcDir, page.sourcePath);
+    // Track dependencies with circular detection
+    const visited = new Set();
+    const currentPath = new Set();
+    // 1. Find the layout file that will be used for this page
+    const layoutPath = await discoverLayout(relativePath, config, page.frontMatter.layout, isCollectionIndexPage(page));
+    if (layoutPath) {
+        const absoluteLayoutPath = join(srcDir, layoutPath);
+        deps.push(absoluteLayoutPath);
+        // Check for circular dependencies in layout chain
+        await detectCircularDependencies(absoluteLayoutPath, srcDir, visited, currentPath);
+    }
+    // 2. Find all partials accessible to this page
+    const partialDeps = await findPartialDependencies(relativePath, config);
+    deps.push(...partialDeps);
+    return deps;
+}
+/**
+ * Finds all partial dependencies for a given page path.
+ * Searches up the directory hierarchy for _* folders containing .eta files.
+ *
+ * @param pagePath - Relative path to the page from srcDir
+ * @param config - Stati configuration
+ * @returns Array of absolute paths to partial files
+ *
+ * @example
+ * ```typescript
+ * const partials = await findPartialDependencies('blog/post.md', config);
+ * ```
+ */
+export async function findPartialDependencies(pagePath, config) {
+    // Early return if required config values are missing
+    if (!config.srcDir) {
+        console.warn('Config srcDir is missing, cannot find partial dependencies');
+        return [];
+    }
+    const deps = [];
+    const srcDir = join(process.cwd(), config.srcDir);
+    // Get the directory of the current page
+    const pageDir = dirname(pagePath);
+    const pathSegments = pageDir === '.' ? [] : pageDir.split(/[/\\]/);
+    // Build list of directories to search (current dir up to root)
+    const dirsToSearch = [];
+    // Add directories from current up to root
+    if (pathSegments.length > 0) {
+        for (let i = pathSegments.length; i >= 0; i--) {
+            if (i === 0) {
+                dirsToSearch.push(''); // Root directory
+            }
+            else {
+                dirsToSearch.push(pathSegments.slice(0, i).join('/'));
+            }
+        }
+    }
+    else {
+        dirsToSearch.push(''); // Root directory only
+    }
+    // Search each directory for _* folders containing .eta files
+    for (const dir of dirsToSearch) {
+        const searchDir = dir ? join(srcDir, dir) : srcDir;
+        try {
+            // Find all .eta files in _* subdirectories
+            // Use posix.join to ensure forward slashes for glob patterns
+            const normalizedSearchDir = searchDir.replace(/\\/g, '/');
+            const pattern = posix.join(normalizedSearchDir, '_*/**/*.eta');
+            const partialFiles = await glob(pattern, { absolute: true });
+            deps.push(...partialFiles);
+        }
+        catch {
+            // Continue if directory doesn't exist or can't be read
+            continue;
+        }
+    }
+    return deps;
+}
+/**
+ * Resolves a template name to its file path.
+ * Used for explicit layout specifications in front matter.
+ *
+ * @param layout - Layout name (without .eta extension)
+ * @param config - Stati configuration
+ * @returns Absolute path to template file, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const templatePath = await resolveTemplatePath('post', config);
+ * if (templatePath) {
+ *   console.log(`Found template at: ${templatePath}`);
+ * }
+ * ```
+ */
+export async function resolveTemplatePath(layout, config) {
+    const srcDir = join(process.cwd(), config.srcDir);
+    const layoutPath = join(srcDir, `${layout}.eta`);
+    if (await pathExists(layoutPath)) {
+        return layoutPath;
+    }
+    return null;
+}
+/**
+ * Helper function to determine if a page is a collection index page.
+ * Duplicated from templates.ts to avoid circular dependencies.
+ */
+function isCollectionIndexPage(page) {
+    // This is a simplified version - in a real implementation,
+    // we'd need access to all pages to determine this properly.
+    // For now, we'll assume any page ending in /index or at root is a collection page.
+    return page.url === '/' || page.url.endsWith('/index') || page.slug === 'index';
+}
+/**
+ * Helper function to discover layout files.
+ * Duplicated from templates.ts to avoid circular dependencies.
+ */
+async function discoverLayout(pagePath, config, explicitLayout, isIndexPage) {
+    // Early return if required config values are missing
+    if (!config.srcDir) {
+        return null;
+    }
+    const srcDir = join(process.cwd(), config.srcDir);
+    // If explicit layout is specified, use it
+    if (explicitLayout) {
+        const layoutPath = join(srcDir, `${explicitLayout}.eta`);
+        if (await pathExists(layoutPath)) {
+            return `${explicitLayout}.eta`;
+        }
+    }
+    // Get the directory of the current page
+    const pageDir = dirname(pagePath);
+    const pathSegments = pageDir === '.' ? [] : pageDir.split(/[/\\]/);
+    // Search for layout.eta from current directory up to root
+    const dirsToSearch = [];
+    // Add current directory if not root
+    if (pathSegments.length > 0) {
+        for (let i = pathSegments.length; i > 0; i--) {
+            dirsToSearch.push(pathSegments.slice(0, i).join('/'));
+        }
+    }
+    // Add root directory
+    dirsToSearch.push('');
+    for (const dir of dirsToSearch) {
+        // For index pages, first check for index.eta in each directory
+        if (isIndexPage) {
+            const indexLayoutPath = dir ? join(srcDir, dir, 'index.eta') : join(srcDir, 'index.eta');
+            if (await pathExists(indexLayoutPath)) {
+                const relativePath = dir ? `${dir}/index.eta` : 'index.eta';
+                return posix.normalize(relativePath);
+            }
+        }
+        // Then check for layout.eta as fallback
+        const layoutPath = dir ? join(srcDir, dir, 'layout.eta') : join(srcDir, 'layout.eta');
+        if (await pathExists(layoutPath)) {
+            const relativePath = dir ? `${dir}/layout.eta` : 'layout.eta';
+            return posix.normalize(relativePath);
+        }
+    }
+    return null;
+}
+/**
+ * Detects circular dependencies in template includes/extends.
+ * Uses DFS to traverse the dependency graph and detect cycles.
+ *
+ * @param templatePath - Absolute path to template file to check
+ * @param srcDir - Source directory for resolving relative template paths
+ * @param visited - Set of all visited template paths (for optimization)
+ * @param currentPath - Set of templates in current DFS path (for cycle detection)
+ * @throws {CircularDependencyError} When a circular dependency is detected
+ */
+async function detectCircularDependencies(templatePath, srcDir, visited, currentPath) {
+    // Skip if already processed
+    if (visited.has(templatePath)) {
+        return;
+    }
+    // Check for circular dependency
+    if (currentPath.has(templatePath)) {
+        const chain = Array.from(currentPath);
+        chain.push(templatePath);
+        throw new CircularDependencyError(chain, `Circular dependency detected in templates: ${chain.join(' -> ')}`);
+    }
+    // Check if template file exists
+    if (!(await pathExists(templatePath))) {
+        // Don't treat missing files as circular dependencies
+        // They will be handled by the missing file error handling
+        return;
+    }
+    // Add to current path
+    currentPath.add(templatePath);
+    visited.add(templatePath);
+    try {
+        // Read template content to find includes/extends
+        const content = await readFile(templatePath, 'utf-8');
+        const dependencies = await parseTemplateDependencies(content, templatePath, srcDir);
+        // Recursively check dependencies
+        for (const depPath of dependencies) {
+            await detectCircularDependencies(depPath, srcDir, visited, currentPath);
+        }
+    }
+    catch (error) {
+        // If we can't read the file, don't treat it as a circular dependency
+        if (error instanceof Error && !error.message.includes('Circular dependency')) {
+            console.warn(`Warning: Could not read template ${templatePath}: ${error.message}`);
+        }
+        else {
+            throw error; // Re-throw circular dependency errors
+        }
+    }
+    finally {
+        // Remove from current path when backtracking
+        currentPath.delete(templatePath);
+    }
+}
+/**
+ * Parses a template file to find included/extended templates.
+ * This is a basic implementation that looks for common Eta patterns.
+ *
+ * @param content - Template file content
+ * @param templatePath - Path to the template file (for error context)
+ * @param srcDir - Source directory for resolving relative paths
+ * @returns Array of absolute paths to dependent templates
+ */
+async function parseTemplateDependencies(content, templatePath, srcDir) {
+    const dependencies = [];
+    // Look for Eta include patterns: <%~ include('template') %>
+    const includePatterns = [
+        /<%[~-]?\s*include\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g,
+        /<%[~-]?\s*include\s*\(\s*['"`]([^'"`]+)['"`]\s*,/g, // with parameters
+    ];
+    for (const pattern of includePatterns) {
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+            const includePath = match[1];
+            if (includePath) {
+                const resolvedPath = await resolveTemplatePathInternal(includePath, srcDir);
+                if (resolvedPath) {
+                    dependencies.push(resolvedPath);
+                }
+            }
+        }
+    }
+    // Look for Eta layout/extends patterns: <%~ layout('template') %>
+    const layoutPatterns = [
+        /<%[~-]?\s*layout\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g,
+        /<%[~-]?\s*extends?\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g,
+    ];
+    for (const pattern of layoutPatterns) {
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+            const layoutPath = match[1];
+            if (layoutPath) {
+                const resolvedPath = await resolveTemplatePathInternal(layoutPath, srcDir);
+                if (resolvedPath) {
+                    dependencies.push(resolvedPath);
+                }
+            }
+        }
+    }
+    return dependencies;
+}
+/**
+ * Internal helper to resolve template paths (renamed to avoid naming conflict).
+ * Handles relative paths and adds .eta extension if needed.
+ *
+ * @param templateRef - Template reference from include/layout statement
+ * @param srcDir - Source directory for resolving paths
+ * @returns Absolute path to template file, or null if not found
+ */
+async function resolveTemplatePathInternal(templateRef, srcDir) {
+    // Add .eta extension if not present
+    const templateName = templateRef.endsWith('.eta') ? templateRef : `${templateRef}.eta`;
+    // Try absolute path from srcDir
+    const absolutePath = join(srcDir, templateName);
+    if (await pathExists(absolutePath)) {
+        return absolutePath;
+    }
+    // Try resolving relative to template directories
+    // This is a simplified version - real implementation might need more sophisticated resolution
+    const possiblePaths = [
+        join(srcDir, '_templates', templateName),
+        join(srcDir, '_partials', templateName),
+        join(srcDir, '_layouts', templateName),
+    ];
+    for (const path of possiblePaths) {
+        if (await pathExists(path)) {
+            return path;
+        }
+    }
+    return null;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Computes a SHA-256 hash of page content and front matter.
+ * Used to detect when page content has changed.
+ *
+ * @param content - The raw markdown content of the page
+ * @param frontMatter - The parsed front matter object
+ * @returns SHA-256 hash as a hex string
+ *
+ * @example
+ * ```typescript
+ * const hash = computeContentHash('# Hello World', { title: 'My Post' });
+ * console.log(hash); // "sha256-abc123..."
+ * ```
+ */
+export declare function computeContentHash(content: string, frontMatter: Record<string, unknown>): string;
+/**
+ * Computes a SHA-256 hash of a file's contents.
+ * Used for tracking template and partial file changes.
+ *
+ * @param filePath - Absolute path to the file
+ * @returns Promise resolving to SHA-256 hash as a hex string, or null if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const hash = await computeFileHash('/path/to/template.eta');
+ * if (hash) {
+ *   console.log(`Template hash: ${hash}`);
+ * }
+ * ```
+ */
+export declare function computeFileHash(filePath: string): Promise<string | null>;
+/**
+ * Computes a combined hash from content hash and dependency hashes.
+ * This represents the complete input state for a page.
+ *
+ * @param contentHash - Hash of the page content and front matter
+ * @param depsHashes - Array of dependency file hashes
+ * @returns Combined SHA-256 hash as a hex string
+ *
+ * @example
+ * ```typescript
+ * const contentHash = computeContentHash(content, frontMatter);
+ * const depsHashes = ['sha256-dep1...', 'sha256-dep2...'];
+ * const inputsHash = computeInputsHash(contentHash, depsHashes);
+ * ```
+ */
+export declare function computeInputsHash(contentHash: string, depsHashes: string[]): string;
+//# sourceMappingURL=hash.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/core/isg/hash.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAWhG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiB9E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAanF"}

package/dist/core/isg/hash.js

@@ -0,0 +1,82 @@
+import { createHash } from 'crypto';
+import fse from 'fs-extra';
+const { readFile, pathExists } = fse;
+/**
+ * Computes a SHA-256 hash of page content and front matter.
+ * Used to detect when page content has changed.
+ *
+ * @param content - The raw markdown content of the page
+ * @param frontMatter - The parsed front matter object
+ * @returns SHA-256 hash as a hex string
+ *
+ * @example
+ * ```typescript
+ * const hash = computeContentHash('# Hello World', { title: 'My Post' });
+ * console.log(hash); // "sha256-abc123..."
+ * ```
+ */
+export function computeContentHash(content, frontMatter) {
+    const hash = createHash('sha256');
+    // Hash the content
+    hash.update(content, 'utf-8');
+    // Hash the front matter (sorted for consistency)
+    const sortedFrontMatter = JSON.stringify(frontMatter, Object.keys(frontMatter).sort());
+    hash.update(sortedFrontMatter, 'utf-8');
+    return `sha256-${hash.digest('hex')}`;
+}
+/**
+ * Computes a SHA-256 hash of a file's contents.
+ * Used for tracking template and partial file changes.
+ *
+ * @param filePath - Absolute path to the file
+ * @returns Promise resolving to SHA-256 hash as a hex string, or null if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const hash = await computeFileHash('/path/to/template.eta');
+ * if (hash) {
+ *   console.log(`Template hash: ${hash}`);
+ * }
+ * ```
+ */
+export async function computeFileHash(filePath) {
+    try {
+        if (!(await pathExists(filePath))) {
+            return null;
+        }
+        const content = await readFile(filePath, 'utf-8');
+        const hash = createHash('sha256');
+        hash.update(content, 'utf-8');
+        return `sha256-${hash.digest('hex')}`;
+    }
+    catch (error) {
+        console.warn(`Failed to compute hash for ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/**
+ * Computes a combined hash from content hash and dependency hashes.
+ * This represents the complete input state for a page.
+ *
+ * @param contentHash - Hash of the page content and front matter
+ * @param depsHashes - Array of dependency file hashes
+ * @returns Combined SHA-256 hash as a hex string
+ *
+ * @example
+ * ```typescript
+ * const contentHash = computeContentHash(content, frontMatter);
+ * const depsHashes = ['sha256-dep1...', 'sha256-dep2...'];
+ * const inputsHash = computeInputsHash(contentHash, depsHashes);
+ * ```
+ */
+export function computeInputsHash(contentHash, depsHashes) {
+    const hash = createHash('sha256');
+    // Hash the content hash
+    hash.update(contentHash, 'utf-8');
+    // Hash each dependency hash in sorted order for consistency
+    const sortedDepsHashes = [...depsHashes].sort();
+    for (const depHash of sortedDepsHashes) {
+        hash.update(depHash, 'utf-8');
+    }
+    return `sha256-${hash.digest('hex')}`;
+}

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

@@ -0,0 +1,47 @@
+import type { CacheManifest } from '../../types.js';
+/**
+ * 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 declare function loadCacheManifest(cacheDir: string): Promise<CacheManifest | 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 declare function saveCacheManifest(cacheDir: string, manifest: CacheManifest): Promise<void>;
+/**
+ * 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 declare function createEmptyManifest(): CacheManifest;
+//# sourceMappingURL=manifest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/core/isg/manifest.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,gBAAgB,CAAC;AAchE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAyFvF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA6ChG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAInD"}