@stati/core 1.16.3 → 1.17.0

package/dist/core/build.d.ts

@@ -1,7 +1,22 @@
 import type { BuildStats, Logger } from '../types/index.js';
+import type { BuildMetrics } from '../metrics/index.js';
+/**
+ * Options for metrics collection during builds.
+ */
+export interface MetricsOptions {
+    /** Enable metrics collection */
+    enabled?: boolean;
+    /** Include per-page timing details */
+    detailed?: boolean;
+}
 /**
  * Options for customizing the build process.
  *
+ * @remarks
+ * The `| undefined` on optional properties is intentional due to
+ * `exactOptionalPropertyTypes: true` in tsconfig.json, allowing callers
+ * to explicitly pass `undefined` values.
+ *
  * @example
  * ```typescript
  * const options: BuildOptions = {
@@ -9,23 +24,33 @@ import type { BuildStats, Logger } from '../types/index.js';
  *   clean: true,        // Clean output directory before build
  *   configPath: './custom.config.js',  // Custom config file path
  *   includeDrafts: true, // Include draft pages in build
- *   version: '1.0.0'    // Version to display in build messages
+ *   version: '1.0.0',   // Version to display in build messages
+ *   metrics: { enabled: true, detailed: true }  // Enable metrics collection
  * };
  * ```
  */
 export interface BuildOptions {
     /** Force rebuild of all pages, ignoring cache */
-    force?: boolean;
+    force?: boolean | undefined;
     /** Clean the output directory before building */
-    clean?: boolean;
+    clean?: boolean | undefined;
     /** Path to a custom configuration file */
-    configPath?: string;
+    configPath?: string | undefined;
     /** Include draft pages in the build */
-    includeDrafts?: boolean;
+    includeDrafts?: boolean | undefined;
     /** Custom logger for build output */
-    logger?: Logger;
+    logger?: Logger | undefined;
     /** Version information to display in build messages */
-    version?: string;
+    version?: string | undefined;
+    /** Metrics collection options */
+    metrics?: MetricsOptions | undefined;
+}
+/**
+ * Extended build result including optional metrics.
+ */
+export interface BuildResult extends BuildStats {
+    /** Build metrics (only present when metrics enabled) */
+    buildMetrics?: BuildMetrics;
 }
 /**
  * Builds the Stati site with ISG support.
@@ -43,20 +68,24 @@ export interface BuildOptions {
  * 5. Update cache manifest
  *
  * @param options - Build configuration options
- * @returns Promise resolving to build statistics
+ * @returns Promise resolving to build result with statistics and optional metrics
  * @throws {Error} When configuration is invalid
  * @throws {Error} When template rendering fails
  * @throws {Error} When build lock cannot be acquired
  *
  * @example
  * ```typescript
- * const stats = await build({
+ * const result = await build({
  *   force: true,
  *   clean: true,
- *   includeDrafts: false
+ *   includeDrafts: false,
+ *   metrics: { enabled: true }
  * });
- * console.log(`Built ${stats.pageCount} pages in ${stats.buildTime}ms`);
+ * console.log(`Built ${result.totalPages} pages in ${result.buildTimeMs}ms`);
+ * if (result.buildMetrics) {
+ *   console.log(`Cache hit rate: ${result.buildMetrics.isg.cacheHitRate}`);
+ * }
  * ```
  */
-export declare function build(options?: BuildOptions): Promise<BuildStats>;
+export declare function build(options?: BuildOptions): Promise<BuildResult>;
 //# sourceMappingURL=build.d.ts.map

package/dist/core/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/core/build.ts"],"names":[],"mappings":"AA+CA,OAAO,KAAK,EAEV,UAAU,EACV,MAAM,EAMP,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA4FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAW3E"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/core/build.ts"],"names":[],"mappings":"AAgDA,OAAO,KAAK,EAEV,UAAU,EACV,MAAM,EAMP,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,uCAAuC;IACvC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,iCAAiC;IACjC,OAAO,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,wDAAwD;IACxD,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AA4FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAW5E"}

package/dist/core/build.js

@@ -1,5 +1,6 @@
 import { ensureDir, writeFile, remove, pathExists, stat, readdir, copyFile, resolveOutDir, resolveStaticDir, resolveCacheDir, enableInventoryTracking, disableInventoryTracking, clearInventory, writeTailwindClassInventory, getInventorySize, isTailwindUsed, loadPreviousInventory, compileTypeScript, autoInjectBundles, getBundlePathsForPage, } from './utils/index.js';
 import { join, dirname, relative, posix } from 'node:path';
+import { performance } from 'node:perf_hooks';
 import { loadConfig } from '../config/loader.js';
 import { loadContent } from './content.js';
 import { createMarkdownProcessor, renderMarkdown } from './markdown.js';
@@ -10,6 +11,7 @@ import { generateSitemap, generateRobotsTxtFromConfig, autoInjectSEO, } from '..
 import { generateRSSFeeds, validateRSSConfig } from '../rss/index.js';
 import { getEnv } from '../env.js';
 import { DEFAULT_OUT_DIR } from '../constants.js';
+import { createMetricRecorder, noopMetricRecorder } from '../metrics/index.js';
 /**
  * Recursively calculates the total size of a directory in bytes.
  * Used for build statistics.
@@ -103,19 +105,23 @@ const defaultLogger = {
  * 5. Update cache manifest
  *
  * @param options - Build configuration options
- * @returns Promise resolving to build statistics
+ * @returns Promise resolving to build result with statistics and optional metrics
  * @throws {Error} When configuration is invalid
  * @throws {Error} When template rendering fails
  * @throws {Error} When build lock cannot be acquired
  *
  * @example
  * ```typescript
- * const stats = await build({
+ * const result = await build({
  *   force: true,
  *   clean: true,
- *   includeDrafts: false
+ *   includeDrafts: false,
+ *   metrics: { enabled: true }
  * });
- * console.log(`Built ${stats.pageCount} pages in ${stats.buildTime}ms`);
+ * console.log(`Built ${result.totalPages} pages in ${result.buildTimeMs}ms`);
+ * if (result.buildMetrics) {
+ *   console.log(`Cache hit rate: ${result.buildMetrics.isg.cacheHitRate}`);
+ * }
  * ```
  */
 export async function build(options = {}) {
@@ -184,14 +190,16 @@ async function loadContentAndBuildNavigation(config, options, logger) {
 /**
  * Processes pages with ISG caching logic.
  */
-async function processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles) {
+async function processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles, recorder = noopMetricRecorder) {
     let cacheHits = 0;
     let cacheMisses = 0;
     // Build context
     const buildContext = { config, pages };
     // Run beforeAll hook
     if (config.hooks?.beforeAll) {
+        const endHookBeforeAll = recorder.startSpan('hookBeforeAllMs');
         await config.hooks.beforeAll(buildContext);
+        endHookBeforeAll();
     }
     // Render each page with tree-based progress tracking and ISG
     if (logger.step) {
@@ -239,14 +247,18 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
             else {
                 logger.processing(`📋 Cached ${page.url}`);
             }
+            // Record page timing for cached pages (0ms render time)
+            recorder.recordPageTiming(page.url, 0, true);
             continue;
         }
         // Cache miss - need to rebuild
         cacheMisses++;
-        const startTime = Date.now();
+        const startTime = performance.now();
         // Run beforeRender hook
         if (config.hooks?.beforeRender) {
+            const hookStart = performance.now();
             await config.hooks.beforeRender({ page, config });
+            recorder.addToPhase('hookBeforeRenderTotalMs', performance.now() - hookStart);
         }
         // Render markdown to HTML
         const htmlContent = renderMarkdown(page.content, md);
@@ -254,7 +266,10 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
         const bundlePaths = getBundlePathsForPage(page.url, compiledBundles);
         const assets = bundlePaths.length > 0 ? { bundlePaths } : undefined;
         // Render with template
-        let finalHtml = await renderPage(page, htmlContent, config, eta, navigation, pages, assets);
+        const renderResult = await renderPage(page, htmlContent, config, eta, navigation, pages, assets);
+        let finalHtml = renderResult.html;
+        // Record templates loaded for this page
+        recorder.increment('templatesLoaded', renderResult.templatesLoaded);
         // Auto-inject SEO tags if enabled
         if (config.seo?.autoInject !== false) {
             const injectOptions = {
@@ -273,7 +288,9 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
         if (shouldAutoInject && assets && assets.bundlePaths.length > 0) {
             finalHtml = autoInjectBundles(finalHtml, assets.bundlePaths);
         }
-        const renderTime = Date.now() - startTime;
+        const renderTime = Math.round(performance.now() - startTime);
+        // Record page timing for rendered pages (includes template count)
+        recorder.recordPageTiming(page.url, renderTime, false, renderResult.templatesLoaded);
         if (logger.updateTreeNode) {
             logger.updateTreeNode(pageId, 'completed', {
                 timing: renderTime,
@@ -292,7 +309,9 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
         }
         // Run afterRender hook
         if (config.hooks?.afterRender) {
+            const hookStart = performance.now();
             await config.hooks.afterRender({ page, config });
+            recorder.addToPhase('hookAfterRenderTotalMs', performance.now() - hookStart);
         }
     }
     // Display final rendering tree and clear it
@@ -347,11 +366,29 @@ async function generateBuildStats(pages, assetsCount, buildStartTime, outDir, ca
  * Separated for cleaner error handling and testing.
  */
 async function buildInternal(options = {}) {
+    // Date.now() is used for user-facing build duration display (wall-clock time, in milliseconds).
+    // Note: Date.now() can be affected by system clock changes and is not monotonic.
+    // Internal metrics use performance.now() via the MetricRecorder for higher precision and monotonic timing,
+    // which is not affected by system clock adjustments.
     const buildStartTime = Date.now();
     const logger = options.logger || defaultLogger;
+    // Create metric recorder (noop if disabled)
+    const recorder = createMetricRecorder({
+        enabled: options.metrics?.enabled,
+        detailed: options.metrics?.detailed,
+        command: 'build',
+        flags: {
+            force: options.force,
+            clean: options.clean,
+            includeDrafts: options.includeDrafts,
+        },
+        statiVersion: options.version,
+    });
     logger.building('Building your site...');
-    // Load configuration
+    // Load configuration (instrumented)
+    const endConfigSpan = recorder.startSpan('configLoadMs');
     const { config, outDir, cacheDir } = await loadAndValidateConfig(options);
+    endConfigSpan();
     // Initialize cache stats
     let cacheHits = 0;
     let cacheMisses = 0;
@@ -384,17 +421,27 @@ async function buildInternal(options = {}) {
         }
     }
     // Load cache manifest for ISG (after potential clean operation)
+    const endManifestLoadSpan = recorder.startSpan('cacheManifestLoadMs');
     const { manifest } = await setupCacheAndManifest(cacheDir);
+    endManifestLoadSpan();
     // Load content and build navigation
     if (logger.step) {
         console.log(); // Add spacing before content loading
     }
+    const endContentSpan = recorder.startSpan('contentDiscoveryMs');
     const { pages, navigation, md, eta, navigationHash } = await loadContentAndBuildNavigation(config, options, logger);
+    endContentSpan();
+    // Record content discovery counts.
+    // Both totalPages and markdownFilesProcessed are incremented by pages.length
+    // because loadContent() only processes *.md files, so all pages are markdown files.
+    recorder.increment('totalPages', pages.length);
+    recorder.increment('markdownFilesProcessed', pages.length);
     // Store navigation hash in manifest for change detection in dev server
     manifest.navigationHash = navigationHash;
     // Compile TypeScript if enabled
     let compiledBundles = [];
     if (config.typescript?.enabled) {
+        const endTsSpan = recorder.startSpan('typescriptCompileMs');
         compiledBundles = await compileTypeScript({
             projectRoot: process.cwd(),
             config: config.typescript,
@@ -402,15 +449,21 @@ async function buildInternal(options = {}) {
             mode: getEnv() === 'production' ? 'production' : 'development',
             logger,
         });
+        endTsSpan();
     }
     // Process pages with ISG caching logic
     if (logger.step) {
         console.log(); // Add spacing before page processing
     }
+    const endPageRenderSpan = recorder.startSpan('pageRenderingMs');
     const buildTime = new Date();
-    const pageProcessingResult = await processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles);
+    const pageProcessingResult = await processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles, recorder);
+    endPageRenderSpan();
     cacheHits = pageProcessingResult.cacheHits;
     cacheMisses = pageProcessingResult.cacheMisses;
+    // Record page rendering counts
+    recorder.increment('renderedPages', cacheMisses);
+    recorder.increment('cachedPages', cacheHits);
     // Write Tailwind class inventory after all templates have been rendered (if Tailwind is used)
     if (hasTailwind) {
         const inventorySize = getInventorySize();
@@ -423,10 +476,15 @@ async function buildInternal(options = {}) {
         disableInventoryTracking();
     }
     // Save updated cache manifest
+    const endManifestSaveSpan = recorder.startSpan('cacheManifestSaveMs');
     await saveCacheManifest(cacheDir, manifest);
+    endManifestSaveSpan();
     // Copy static assets and count them
+    const endAssetSpan = recorder.startSpan('assetCopyMs');
     let assetsCount = 0;
     assetsCount = await copyStaticAssets(config, outDir, logger);
+    endAssetSpan();
+    recorder.increment('assetsCopied', assetsCount);
     // Get current environment
     const currentEnv = getEnv();
     // Generate sitemap if enabled (only in production mode)
@@ -435,8 +493,10 @@ async function buildInternal(options = {}) {
             console.log(); // Add spacing before sitemap generation
         }
         logger.info('Generating sitemap...');
+        const endSitemapSpan = recorder.startSpan('sitemapGenerationMs');
         const sitemapResult = generateSitemap(pages, config, config.sitemap);
         await writeFile(join(outDir, 'sitemap.xml'), sitemapResult.xml);
+        endSitemapSpan();
         // Write additional sitemap files if split
         if (sitemapResult.sitemaps) {
             for (const { filename, xml } of sitemapResult.sitemaps) {
@@ -506,9 +566,30 @@ async function buildInternal(options = {}) {
     }
     // Run afterAll hook
     if (config.hooks?.afterAll) {
+        const endHookAfterAll = recorder.startSpan('hookAfterAllMs');
         await config.hooks.afterAll({ config, pages });
+        endHookAfterAll();
     }
     // Calculate build statistics
     const buildStats = await generateBuildStats(pages, assetsCount, buildStartTime, outDir, cacheHits, cacheMisses, logger);
-    return buildStats;
+    // Set ISG metrics
+    const totalPages = pages.length;
+    const cacheHitRate = totalPages > 0 ? cacheHits / totalPages : 0;
+    recorder.setISGMetrics({
+        enabled: config.isg?.enabled !== false,
+        cacheHitRate,
+        manifestEntries: Object.keys(manifest.entries).length,
+        invalidatedEntries: cacheMisses,
+    });
+    // Take final memory snapshot
+    recorder.snapshotMemory();
+    // Build result with optional metrics
+    const result = {
+        ...buildStats,
+    };
+    // Add metrics if enabled
+    if (recorder.enabled) {
+        result.buildMetrics = recorder.finalize();
+    }
+    return result;
 }

package/dist/core/index.d.ts

@@ -3,7 +3,7 @@
  * Barrel file for all core Stati functionality including build, dev server, preview, and invalidation.
  */
 export { build } from './build.js';
-export type { BuildOptions } from './build.js';
+export type { BuildOptions, MetricsOptions, BuildResult } from './build.js';
 export { createDevServer } from './dev.js';
 export type { DevServerOptions } from './dev.js';
 export { createPreviewServer } from './preview.js';

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAGjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG5E,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAGjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/core/templates.d.ts

@@ -1,5 +1,14 @@
 import { Eta } from 'eta';
 import type { StatiConfig, PageModel, NavNode } from '../types/index.js';
+/**
+ * Result of rendering a page template.
+ */
+export interface RenderResult {
+    /** The rendered HTML content */
+    html: string;
+    /** Number of templates loaded (layout + partials) */
+    templatesLoaded: number;
+}
 export declare function createTemplateEngine(config: StatiConfig): Eta;
-export declare function renderPage(page: PageModel, body: string, config: StatiConfig, eta: Eta, navigation?: NavNode[], allPages?: PageModel[], assets?: import('../types/index.js').StatiAssets): Promise<string>;
+export declare function renderPage(page: PageModel, body: string, config: StatiConfig, eta: Eta, navigation?: NavNode[], allPages?: PageModel[], assets?: import('../types/index.js').StatiAssets): Promise<RenderResult>;
 //# sourceMappingURL=templates.d.ts.map

package/dist/core/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/core/templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAG1B,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAkB,MAAM,mBAAmB,CAAC;AAmNzF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,GAAG,CAW7D;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,GAAG,EACR,UAAU,CAAC,EAAE,OAAO,EAAE,EACtB,QAAQ,CAAC,EAAE,SAAS,EAAE,EACtB,MAAM,CAAC,EAAE,OAAO,mBAAmB,EAAE,WAAW,GAC/C,OAAO,CAAC,MAAM,CAAC,CA+KjB"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/core/templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAG1B,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAkB,MAAM,mBAAmB,CAAC;AAiBzF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,eAAe,EAAE,MAAM,CAAC;CACzB;AAoMD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,GAAG,CAW7D;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,GAAG,EACR,UAAU,CAAC,EAAE,OAAO,EAAE,EACtB,QAAQ,CAAC,EAAE,SAAS,EAAE,EACtB,MAAM,CAAC,EAAE,OAAO,mBAAmB,EAAE,WAAW,GAC/C,OAAO,CAAC,YAAY,CAAC,CAsLvB"}

package/dist/core/templates.js

@@ -187,6 +187,8 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
     const srcDir = resolveSrcDir(config);
     const relativePath = relative(srcDir, page.sourcePath);
     const partialPaths = await discoverPartials(relativePath, config);
+    // Count templates: partials + layout (if found)
+    const partialsCount = Object.keys(partialPaths).length;
     // Build collection data based on page type
     let collectionData;
     const isIndexPage = allPages && isCollectionIndexPage(page, allPages);
@@ -203,6 +205,8 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
     // Discover the appropriate layout using hierarchical layout.eta convention
     // Pass isIndexPage flag to enable index.eta lookup for aggregation pages
     const layoutPath = await discoverLayout(relativePath, config, page.frontMatter.layout, isIndexPage);
+    // Calculate total templates loaded (partials + layout if present)
+    const templatesLoaded = partialsCount + (layoutPath ? 1 : 0);
     // Create navigation helpers
     const navTree = navigation || [];
     const navHelpers = createNavigationHelpers(navTree, page);
@@ -303,9 +307,10 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
     try {
         if (!layoutPath) {
             console.warn('No layout template found, using fallback');
-            return createFallbackHtml(page, body);
+            return { html: createFallbackHtml(page, body), templatesLoaded };
         }
-        return await eta.renderAsync(layoutPath, context);
+        const html = await eta.renderAsync(layoutPath, context);
+        return { html, templatesLoaded };
     }
     catch (error) {
         console.error(`Error rendering layout ${layoutPath || 'unknown'}:`, error);
@@ -314,7 +319,7 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
             const templateError = createTemplateError(error instanceof Error ? error : new Error(String(error)), layoutPath || undefined);
             throw templateError;
         }
-        return createFallbackHtml(page, body);
+        return { html: createFallbackHtml(page, body), templatesLoaded };
     }
 }
 function createFallbackHtml(page, body) {

package/dist/index.d.ts

@@ -23,8 +23,10 @@ export type { StatiConfig, PageModel, FrontMatter, BuildContext, PageContext, Bu
 export type { SEOMetadata, SEOConfig, SEOContext, SEOValidationResult, SEOTagType, RobotsConfig, OpenGraphConfig, OpenGraphImage, OpenGraphArticle, TwitterCardConfig, AuthorConfig, } from './types/index.js';
 export type { SitemapConfig, SitemapEntry, SitemapGenerationResult, ChangeFrequency, } from './types/index.js';
 export type { RSSConfig, RSSFeedConfig, RSSGenerationResult } from './types/index.js';
-export type { BuildOptions, DevServerOptions, PreviewServerOptions, InvalidationResult, } from './core/index.js';
+export type { BuildOptions, MetricsOptions, BuildResult, DevServerOptions, PreviewServerOptions, InvalidationResult, } from './core/index.js';
 export { build, createDevServer, createPreviewServer, invalidate } from './core/index.js';
+export type { BuildMetrics, MetricsMeta, MetricsFlags, MetricsTotals, MetricsPhases, MetricsCounts, MetricsISG, PageTiming, IncrementalMetrics, MetricRecorder, MetricRecorderOptions, PhaseName, CounterName, } from './metrics/index.js';
+export { createMetricRecorder, noopMetricRecorder, writeMetrics, formatMetricsSummary, } from './metrics/index.js';
 export type { AutoInjectOptions } from './seo/index.js';
 export { generateSEOMetadata, generateSEO, generateOpenGraphTags, generateTwitterCardTags, generateSitemap, generateSitemapEntry, generateSitemapXml, generateSitemapIndexXml, generateRobotsTxt, generateRobotsTxtFromConfig, escapeHtml, generateRobotsContent, validateSEOMetadata, detectExistingSEOTags, normalizeUrlPath, resolveAbsoluteUrl, isValidUrl, autoInjectSEO, shouldAutoInject, } from './seo/index.js';
 export type { RSSValidationResult } from './rss/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,YAAY,EACV,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,EACZ,WAAW,EACX,UAAU,EACV,OAAO,EACP,SAAS,EACT,SAAS,EACT,UAAU,EACV,YAAY,GACb,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EACV,WAAW,EACX,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,GACb,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,aAAa,EACb,YAAY,EACZ,uBAAuB,EACvB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGtF,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG1F,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,2BAA2B,EAC3B,UAAU,EACV,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAG1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAE7D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,YAAY,EACV,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,EACZ,WAAW,EACX,UAAU,EACV,OAAO,EACP,SAAS,EACT,SAAS,EACT,UAAU,EACV,YAAY,GACb,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EACV,WAAW,EACX,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,GACb,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,aAAa,EACb,YAAY,EACZ,uBAAuB,EACvB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGtF,YAAY,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG1F,YAAY,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,aAAa,EACb,aAAa,EACb,aAAa,EACb,UAAU,EACV,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,SAAS,EACT,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,2BAA2B,EAC3B,UAAU,EACV,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAG1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAE7D"}

package/dist/index.js

@@ -20,6 +20,7 @@
  * ```
  */
 export { build, createDevServer, createPreviewServer, invalidate } from './core/index.js';
+export { createMetricRecorder, noopMetricRecorder, writeMetrics, formatMetricsSummary, } from './metrics/index.js';
 export { generateSEOMetadata, generateSEO, generateOpenGraphTags, generateTwitterCardTags, generateSitemap, generateSitemapEntry, generateSitemapXml, generateSitemapIndexXml, generateRobotsTxt, generateRobotsTxtFromConfig, escapeHtml, generateRobotsContent, validateSEOMetadata, detectExistingSEOTags, normalizeUrlPath, resolveAbsoluteUrl, isValidUrl, autoInjectSEO, shouldAutoInject, } from './seo/index.js';
 export { generateRSSFeed, generateRSSFeeds, validateRSSConfig, validateRSSFeedConfig, } from './rss/index.js';
 // Re-export config and env utilities

package/dist/metrics/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Stati Build Metrics System
+ *
+ * Provides performance measurement and reporting for Stati builds.
+ * Uses Node.js built-ins only - no external dependencies.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { createMetricRecorder, writeMetrics, formatMetricsSummary } from '@stati/core';
+ *
+ * // Create recorder (noop when disabled)
+ * const recorder = createMetricRecorder({ enabled: true });
+ *
+ * // Record phases with spans
+ * const endConfig = recorder.startSpan('configLoadMs');
+ * await loadConfig();
+ * endConfig();
+ *
+ * // Increment counters
+ * recorder.increment('renderedPages');
+ *
+ * // Finalize and write
+ * const metrics = recorder.finalize();
+ * await writeMetrics(metrics, { cacheDir: '.stati' });
+ *
+ * // Format for CLI
+ * const summary = formatMetricsSummary(metrics);
+ * summary.forEach(line => console.log(line));
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { BuildMetrics, MetricsMeta, MetricsFlags, MetricsTotals, MetricsPhases, MetricsCounts, MetricsISG, PageTiming, IncrementalMetrics, MetricRecorder, MetricRecorderOptions, PhaseName, CounterName, GaugeName, } from './types.js';
+export { createMetricRecorder } from './recorder.js';
+export { noopMetricRecorder } from './noop.js';
+export { writeMetrics, formatMetricsSummary, generateMetricsFilename, DEFAULT_METRICS_DIR, isCI, getGitCommit, getGitBranch, getCpuCount, getPlatform, getArch, getNodeVersion, getMemoryUsage, } from './utils/index.js';
+export type { WriteMetricsOptions, WriteMetricsResult } from './utils/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/metrics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/metrics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,YAAY,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,aAAa,EACb,aAAa,EACb,aAAa,EACb,UAAU,EACV,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAG/C,OAAO,EAEL,YAAY,EACZ,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EAEnB,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,WAAW,EACX,OAAO,EACP,cAAc,EACd,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/metrics/index.js

@@ -0,0 +1,42 @@
+/**
+ * Stati Build Metrics System
+ *
+ * Provides performance measurement and reporting for Stati builds.
+ * Uses Node.js built-ins only - no external dependencies.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { createMetricRecorder, writeMetrics, formatMetricsSummary } from '@stati/core';
+ *
+ * // Create recorder (noop when disabled)
+ * const recorder = createMetricRecorder({ enabled: true });
+ *
+ * // Record phases with spans
+ * const endConfig = recorder.startSpan('configLoadMs');
+ * await loadConfig();
+ * endConfig();
+ *
+ * // Increment counters
+ * recorder.increment('renderedPages');
+ *
+ * // Finalize and write
+ * const metrics = recorder.finalize();
+ * await writeMetrics(metrics, { cacheDir: '.stati' });
+ *
+ * // Format for CLI
+ * const summary = formatMetricsSummary(metrics);
+ * summary.forEach(line => console.log(line));
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Recorder factory
+export { createMetricRecorder } from './recorder.js';
+// Noop recorder singleton
+export { noopMetricRecorder } from './noop.js';
+// Utilities (file writing, system info)
+export { 
+// Writer utilities
+writeMetrics, formatMetricsSummary, generateMetricsFilename, DEFAULT_METRICS_DIR, 
+// System utilities
+isCI, getGitCommit, getGitBranch, getCpuCount, getPlatform, getArch, getNodeVersion, getMemoryUsage, } from './utils/index.js';

package/dist/metrics/noop.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Noop MetricRecorder implementation.
+ * Used when metrics collection is disabled - has zero overhead.
+ * (Null Object Pattern)
+ */
+import type { MetricRecorder } from './types.js';
+/**
+ * Singleton noop recorder instance.
+ * Use this when metrics are disabled for zero-overhead operation.
+ */
+export declare const noopMetricRecorder: MetricRecorder;
+//# sourceMappingURL=noop.d.ts.map

package/dist/metrics/noop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../src/metrics/noop.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EAOf,MAAM,YAAY,CAAC;AAiGpB;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,cAAyC,CAAC"}

package/dist/metrics/noop.js

@@ -0,0 +1,88 @@
+/**
+ * Noop MetricRecorder implementation.
+ * Used when metrics collection is disabled - has zero overhead.
+ * (Null Object Pattern)
+ */
+/**
+ * Empty function that does nothing.
+ */
+const noop = () => {
+    /* intentionally empty */
+};
+/**
+ * Noop implementation of MetricRecorder.
+ * All methods are no-ops with minimal overhead.
+ */
+class NoopMetricRecorder {
+    enabled = false;
+    detailed = false;
+    startSpan(_name) {
+        return noop;
+    }
+    recordPhase(_name, _durationMs) {
+        /* noop */
+    }
+    addToPhase(_name, _durationMs) {
+        /* noop */
+    }
+    increment(_name, _amount) {
+        /* noop */
+    }
+    setGauge(_name, _value) {
+        /* noop */
+    }
+    recordPageTiming(_url, _durationMs, _cached, _templatesLoaded) {
+        /* noop */
+    }
+    snapshotMemory() {
+        /* noop */
+    }
+    setISGMetrics(_metrics) {
+        /* noop */
+    }
+    setIncrementalMetrics(_metrics) {
+        /* noop */
+    }
+    finalize() {
+        // Return minimal valid metrics object
+        return {
+            schemaVersion: '1',
+            meta: {
+                timestamp: new Date().toISOString(),
+                ci: false,
+                nodeVersion: process.version.replace(/^v/, ''),
+                platform: process.platform,
+                arch: process.arch,
+                cpuCount: 1,
+                statiVersion: 'unknown',
+                command: 'build',
+                flags: {},
+            },
+            totals: {
+                durationMs: 0,
+                peakRssBytes: 0,
+                heapUsedBytes: 0,
+            },
+            phases: {},
+            counts: {
+                totalPages: 0,
+                renderedPages: 0,
+                cachedPages: 0,
+                assetsCopied: 0,
+                templatesLoaded: 0,
+                markdownFilesProcessed: 0,
+            },
+            isg: {
+                enabled: false,
+                cacheHitRate: 0,
+                manifestEntries: 0,
+                invalidatedEntries: 0,
+            },
+        };
+    }
+}
+/**
+ * Singleton noop recorder instance.
+ * Use this when metrics are disabled for zero-overhead operation.
+ */
+export const noopMetricRecorder = new NoopMetricRecorder();