@stati/core 1.16.3 → 1.17.0

package/dist/metrics/utils/writer.utils.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Metrics file writing utilities.
+ * Handles graceful degradation - never blocks builds on write failures.
+ */
+import type { BuildMetrics } from '../types.js';
+/**
+ * Default metrics output directory (relative to cache dir).
+ */
+export declare const DEFAULT_METRICS_DIR = "metrics";
+/**
+ * Generate a timestamped filename for metrics output.
+ *
+ * @param command - The command that was run (build, dev)
+ * @param timestamp - ISO timestamp
+ * @returns Filename like "build-2024-01-15T10-30-00.json"
+ */
+export declare function generateMetricsFilename(command: string, timestamp: string): string;
+/**
+ * Options for writing metrics.
+ */
+export interface WriteMetricsOptions {
+    /** Base cache directory (e.g., .stati) */
+    cacheDir: string;
+    /** Custom output path (overrides default) */
+    outputPath?: string | undefined;
+    /** Format: json (default) or ndjson */
+    format?: 'json' | 'ndjson' | undefined;
+}
+/**
+ * Result of metrics write operation.
+ */
+export interface WriteMetricsResult {
+    success: boolean;
+    path?: string;
+    error?: string;
+}
+/**
+ * Write build metrics to a JSON file.
+ * Degrades gracefully on failure - logs warning but doesn't throw.
+ *
+ * @param metrics - The metrics to write
+ * @param options - Write options
+ * @returns Result indicating success/failure and path
+ *
+ * @example
+ * ```typescript
+ * const result = await writeMetrics(metrics, {
+ *   cacheDir: '.stati',
+ * });
+ *
+ * if (result.success) {
+ *   console.log(`Metrics written to ${result.path}`);
+ * }
+ * ```
+ */
+export declare function writeMetrics(metrics: BuildMetrics, options: WriteMetricsOptions): Promise<WriteMetricsResult>;
+/**
+ * Format metrics for CLI summary output.
+ *
+ * @param metrics - Build metrics to format
+ * @returns Array of formatted lines for CLI output
+ */
+export declare function formatMetricsSummary(metrics: BuildMetrics): string[];
+//# sourceMappingURL=writer.utils.d.ts.map

package/dist/metrics/utils/writer.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.utils.d.ts","sourceRoot":"","sources":["../../../src/metrics/utils/writer.utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAuB7C;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAIlF;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CA2C7B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CA6CpE"}

package/dist/metrics/utils/writer.utils.js

@@ -0,0 +1,145 @@
+/**
+ * Metrics file writing utilities.
+ * Handles graceful degradation - never blocks builds on write failures.
+ */
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+/**
+ * Default metrics output directory (relative to cache dir).
+ */
+export const DEFAULT_METRICS_DIR = 'metrics';
+/**
+ * Display names for build phases.
+ * Maps raw phase keys (e.g., 'configLoadMs') to human-readable labels.
+ */
+const PHASE_DISPLAY_NAMES = {
+    configLoadMs: 'Config Load',
+    contentDiscoveryMs: 'Content Discovery',
+    navigationBuildMs: 'Navigation Build',
+    cacheManifestLoadMs: 'Cache Manifest Load',
+    typescriptCompileMs: 'TypeScript Compile',
+    pageRenderingMs: 'Page Rendering',
+    assetCopyMs: 'Asset Copy',
+    cacheManifestSaveMs: 'Cache Manifest Save',
+    sitemapGenerationMs: 'Sitemap Generation',
+    rssGenerationMs: 'RSS Generation',
+    hookBeforeAllMs: 'Hook: Before All',
+    hookAfterAllMs: 'Hook: After All',
+    hookBeforeRenderTotalMs: 'Hook: Before Render (Total)',
+    hookAfterRenderTotalMs: 'Hook: After Render (Total)',
+};
+/**
+ * Generate a timestamped filename for metrics output.
+ *
+ * @param command - The command that was run (build, dev)
+ * @param timestamp - ISO timestamp
+ * @returns Filename like "build-2024-01-15T10-30-00.json"
+ */
+export function generateMetricsFilename(command, timestamp) {
+    // Replace colons with dashes for Windows compatibility
+    const safeTimestamp = timestamp.replace(/:/g, '-').replace(/\.\d+Z$/, 'Z');
+    return `${command}-${safeTimestamp}.json`;
+}
+/**
+ * Write build metrics to a JSON file.
+ * Degrades gracefully on failure - logs warning but doesn't throw.
+ *
+ * @param metrics - The metrics to write
+ * @param options - Write options
+ * @returns Result indicating success/failure and path
+ *
+ * @example
+ * ```typescript
+ * const result = await writeMetrics(metrics, {
+ *   cacheDir: '.stati',
+ * });
+ *
+ * if (result.success) {
+ *   console.log(`Metrics written to ${result.path}`);
+ * }
+ * ```
+ */
+export async function writeMetrics(metrics, options) {
+    try {
+        // Determine output path
+        let outputPath;
+        if (options.outputPath) {
+            outputPath = options.outputPath;
+        }
+        else {
+            const metricsDir = join(options.cacheDir, DEFAULT_METRICS_DIR);
+            const filename = generateMetricsFilename(metrics.meta.command, metrics.meta.timestamp);
+            outputPath = join(metricsDir, filename);
+        }
+        // Ensure directory exists
+        await mkdir(dirname(outputPath), { recursive: true });
+        // Format content
+        const format = options.format ?? 'json';
+        let content;
+        if (format === 'ndjson') {
+            // NDJSON: one JSON object per line, no pretty printing
+            content = JSON.stringify(metrics) + '\n';
+        }
+        else {
+            // JSON: pretty printed for readability
+            content = JSON.stringify(metrics, null, 2) + '\n';
+        }
+        // Write file
+        await writeFile(outputPath, content, 'utf-8');
+        return {
+            success: true,
+            path: outputPath,
+        };
+    }
+    catch (error) {
+        // Graceful degradation - don't throw, just report failure
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            error: `Failed to write metrics: ${errorMessage}`,
+        };
+    }
+}
+/**
+ * Format metrics for CLI summary output.
+ *
+ * @param metrics - Build metrics to format
+ * @returns Array of formatted lines for CLI output
+ */
+export function formatMetricsSummary(metrics) {
+    const lines = [];
+    // Header
+    lines.push('');
+    lines.push('Build Metrics Summary');
+    lines.push('─'.repeat(40));
+    // Total duration
+    const totalSeconds = (metrics.totals.durationMs / 1000).toFixed(2);
+    lines.push(`Total build time: ${totalSeconds}s`);
+    // Page stats
+    const { totalPages, renderedPages, cachedPages } = metrics.counts;
+    lines.push(`Pages: ${totalPages} total, ${renderedPages} rendered, ${cachedPages} cached`);
+    // Cache hit rate
+    const hitRate = (metrics.isg.cacheHitRate * 100).toFixed(1);
+    lines.push(`Cache hit rate: ${hitRate}%`);
+    // Memory
+    const peakMB = (metrics.totals.peakRssBytes / 1024 / 1024).toFixed(1);
+    lines.push(`Peak memory: ${peakMB} MB`);
+    // Top phases (sorted by duration, top 3)
+    const phases = Object.entries(metrics.phases)
+        .filter(([, duration]) => duration !== undefined && duration > 0)
+        .map(([name, duration]) => ({ name, duration: duration }))
+        .sort((a, b) => b.duration - a.duration)
+        .slice(0, 3);
+    if (phases.length > 0) {
+        lines.push('');
+        lines.push('Top phases:');
+        for (const phase of phases) {
+            // Use mapped display name if available, otherwise fall back to raw name
+            const phaseName = PHASE_DISPLAY_NAMES[phase.name] || phase.name;
+            const phaseMs = phase.duration.toFixed(0);
+            lines.push(`  ${phaseName}: ${phaseMs}ms`);
+        }
+    }
+    lines.push('─'.repeat(40));
+    return lines;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stati/core",
-  "version": "1.16.3",
+  "version": "1.17.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",