@zintrust/core 0.1.27 → 0.1.28

package/src/performance/establish-baseline.ts

@@ -0,0 +1,69 @@
+/**
+ * Establish Performance Baseline
+ * Run all code generator benchmarks and save baseline metrics
+ */
+
+import { esmFilePath } from '@common/index';
+import { Logger } from '@config/logger';
+import { fs } from '@node-singletons';
+import * as path from '@node-singletons/path';
+import { CodeGenerationBenchmark } from '@performance/CodeGenerationBenchmark';
+
+/**
+ * Run baseline and save results
+ */
+export async function establishBaseline(): Promise<void> {
+  Logger.info('📊 Establishing Performance Baseline...');
+
+  const benchmark = CodeGenerationBenchmark();
+  await benchmark.runAll();
+
+  // Save baseline
+  const baselineFile = path.join(process.cwd(), 'performance-baseline.json');
+  benchmark.exportResults(baselineFile);
+
+  Logger.info('✅ Baseline established and saved to performance-baseline.json');
+  Logger.info('📈 Next: Run optimizations and compare results');
+}
+
+// Run if called directly
+type GlobalWithBaselineMainFlag = typeof globalThis & {
+  __ZINTRUST_ESTABLISH_BASELINE_MAIN__?: boolean;
+};
+
+function isMainModuleEsm(): boolean {
+  try {
+    const entry = process.argv[1];
+    if (entry === undefined || entry === '') return false;
+
+    const currentFilePath = esmFilePath(import.meta.url);
+
+    // Use realpathSync to handle symlinks (common on macOS /var -> /private/var)
+    if (!('realpathSync' in fs)) {
+      return path.resolve(entry) === path.resolve(currentFilePath);
+    }
+
+    try {
+      const realpathSync = (fs as unknown as { realpathSync: (value: string) => string })
+        .realpathSync;
+      return realpathSync(entry) === realpathSync(currentFilePath);
+    } catch (err) {
+      Logger.error('realpathSync failed, falling back to path.resolve', err);
+      return path.resolve(entry) === path.resolve(currentFilePath);
+    }
+  } catch (err) {
+    Logger.error('❌ Baseline failed:', err);
+    return false;
+  }
+}
+
+const isMainModule =
+  (globalThis as GlobalWithBaselineMainFlag).__ZINTRUST_ESTABLISH_BASELINE_MAIN__ ??
+  isMainModuleEsm();
+
+if (isMainModule) {
+  await establishBaseline().catch((err) => {
+    Logger.error('❌ Baseline failed:', err);
+    process.exit(1);
+  });
+}

package/src/profiling/MemoryProfiler.ts

@@ -0,0 +1,111 @@
+/**
+ * Memory Profiler
+ * Tracks heap memory usage and garbage collection events
+ */
+
+import type { MemoryDelta, MemorySnapshot } from '@profiling/types';
+
+export interface IMemoryProfiler {
+  start(): void;
+  end(): MemorySnapshot;
+  delta(): MemoryDelta;
+  getStartSnapshot(): MemorySnapshot | null;
+  getEndSnapshot(): MemorySnapshot | null;
+  getReport(): string;
+}
+
+/**
+ * MemoryProfiler captures memory usage before and after request execution
+ * Sealed namespace for immutability
+ */
+export const MemoryProfiler = Object.freeze({
+  /**
+   * Create a new memory profiler instance
+   */
+  create(): IMemoryProfiler {
+    let startSnapshot: MemorySnapshot | null = null;
+    let endSnapshot: MemorySnapshot | null = null;
+
+    const captureSnapshot = (): MemorySnapshot => {
+      const mem = process.memoryUsage();
+      return {
+        heapUsed: mem.heapUsed,
+        heapTotal: mem.heapTotal,
+        external: mem.external,
+        rss: mem.rss,
+        timestamp: new Date(),
+      };
+    };
+
+    const delta = (): MemoryDelta => {
+      if (!startSnapshot || !endSnapshot) {
+        return { heapUsed: 0, heapTotal: 0, external: 0, rss: 0 };
+      }
+
+      return {
+        heapUsed: endSnapshot.heapUsed - startSnapshot.heapUsed,
+        heapTotal: endSnapshot.heapTotal - startSnapshot.heapTotal,
+        external: endSnapshot.external - startSnapshot.external,
+        rss: endSnapshot.rss - startSnapshot.rss,
+      };
+    };
+
+    const profiler: IMemoryProfiler = {
+      start() {
+        if (globalThis.gc) globalThis.gc();
+        startSnapshot = captureSnapshot();
+        endSnapshot = null;
+      },
+      end() {
+        endSnapshot = captureSnapshot();
+        return endSnapshot;
+      },
+      delta,
+      getStartSnapshot() {
+        return startSnapshot;
+      },
+      getEndSnapshot() {
+        return endSnapshot;
+      },
+      getReport() {
+        if (!startSnapshot || !endSnapshot) {
+          return 'Memory profiling not started or completed';
+        }
+
+        const d = delta();
+        const lines: string[] = ['Memory Profile Report:'];
+
+        lines.push(
+          `  Heap Used: ${formatBytes(d.heapUsed)}`,
+          `  Heap Total: ${formatBytes(d.heapTotal)}`,
+          `  External: ${formatBytes(d.external)}`,
+          `  RSS: ${formatBytes(d.rss)}`
+        );
+
+        return lines.join('\n');
+      },
+    };
+
+    return profiler;
+  },
+
+  /**
+   * Format memory value as human-readable string
+   */
+  formatBytes(bytes: number): string {
+    return formatBytes(bytes);
+  },
+});
+
+/**
+ * Format memory value as human-readable string
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(Math.abs(bytes)) / Math.log(k));
+
+  return `${(bytes / Math.pow(k, i)).toFixed(2)} ${sizes[i]}`;
+}

package/src/profiling/N1Detector.ts

@@ -0,0 +1,144 @@
+/**
+ * N+1 Query Pattern Detector
+ * Analyzes query logs to identify N+1 patterns
+ */
+
+import type { IN1Detector, N1Pattern, QueryLogEntry } from '@profiling/types';
+
+/**\n * N1Detector analyzes query logs to identify N+1 patterns
+ * Groups identical queries and flags those executed 5+ times as critical
+ * Sealed namespace for immutability
+ */
+export const N1Detector = Object.freeze({
+  /**
+   * Create a new N1Detector instance
+   */
+  create(): IN1Detector {
+    return {
+      /**
+       * Extract table name from SQL query
+       * Handles SELECT, INSERT, UPDATE, DELETE statements
+       */
+      extractTableFromSQL(sql: string): string {
+        return extractTableFromSQL(sql);
+      },
+
+      /**
+       * Detect N+1 patterns in query log
+       * Groups identical queries and returns those executed 5+ times as patterns
+       */
+      detect(queryLog: QueryLogEntry[]): N1Pattern[] {
+        return detectN1Patterns(queryLog);
+      },
+
+      /**
+       * Get severity level based on repetition count
+       */
+      getSeverity(count: number): 'warning' | 'critical' {
+        return getSeverity(count);
+      },
+
+      /**
+       * Generate human-readable summary of N+1 patterns
+       */
+      generateSummary(patterns: N1Pattern[]): string {
+        return generateSummary(patterns);
+      },
+    };
+  },
+});
+
+/**
+ * Extract table name from SQL query
+ */
+function extractTableFromSQL(sql: string): string {
+  // Remove excess whitespace and normalize
+  const normalized = sql.trim().replaceAll(/\s+/g, ' ');
+
+  // INSERT INTO table
+  let match = new RegExp(/INSERT\s+INTO\s+`?(\w+)`?/i).exec(normalized);
+  if (match) return match[1];
+
+  // UPDATE table
+  match = new RegExp(/UPDATE\s+`?(\w+)`?/i).exec(normalized);
+  if (match) return match[1];
+
+  // DELETE FROM table
+  match = new RegExp(/DELETE\s+FROM\s+`?(\w+)`?/i).exec(normalized);
+  if (match) return match[1];
+
+  // SELECT ... FROM table
+  match = new RegExp(/FROM\s+`?(\w+)`?/i).exec(normalized);
+  if (match) return match[1];
+
+  return 'unknown';
+}
+
+/**
+ * Detect N+1 patterns in query log
+ */
+function detectN1Patterns(queryLog: QueryLogEntry[]): N1Pattern[] {
+  if (queryLog.length === 0) {
+    return [];
+  }
+
+  // Group queries by SQL
+  const queryGroups = new Map<string, QueryLogEntry[]>();
+
+  for (const entry of queryLog) {
+    if (!queryGroups.has(entry.sql)) {
+      queryGroups.set(entry.sql, []);
+    }
+    queryGroups.get(entry.sql)?.push(entry);
+  }
+
+  // Find patterns with 5+ executions
+  const patterns: N1Pattern[] = [];
+
+  for (const [sql, entries] of queryGroups) {
+    const count = entries.length;
+
+    if (count >= 5) {
+      const severity = getSeverity(count);
+      const table = extractTableFromSQL(sql);
+
+      patterns.push({
+        table,
+        queryCount: count,
+        query: sql,
+        severity,
+      });
+    }
+  }
+
+  // Sort by query count descending
+  patterns.sort((a, b) => b.queryCount - a.queryCount);
+
+  return patterns;
+}
+
+/**
+ * Get severity level based on repetition count
+ */
+function getSeverity(count: number): 'warning' | 'critical' {
+  return count >= 10 ? 'critical' : 'warning';
+}
+
+/**
+ * Generate human-readable summary of N+1 patterns
+ */
+function generateSummary(patterns: N1Pattern[]): string {
+  if (patterns.length === 0) {
+    return 'No N+1 patterns detected';
+  }
+
+  const lines: string[] = ['N+1 Query Patterns Detected:'];
+
+  for (const pattern of patterns) {
+    lines.push(
+      `  [${pattern.severity.toUpperCase()}] Table "${pattern.table}": ${pattern.queryCount} identical queries`
+    );
+  }
+
+  return lines.join('\n');
+}

package/src/profiling/QueryLogger.ts

@@ -0,0 +1,233 @@
+/**
+ * Query Logger
+ * Tracks database query execution with parameters, duration, and context
+ */
+
+import type { QueryLogEntry } from '@profiling/types';
+
+/**
+ * QueryLogger tracks all database queries executed during a request context
+ * Provides N+1 detection heuristic by flagging identical queries executed 5+ times
+ */
+export type QueryLoggerInstance = IQueryLogger;
+
+export interface IQueryLogger {
+  /**
+   * Set current request context ID
+   */
+  setContext(context: string): void;
+
+  /**
+   * Get current request context ID
+   */
+  getContext(): string;
+
+  /**
+   * Log a query execution
+   */
+  logQuery(sql: string, params: unknown[], duration: number, context?: string): void;
+
+  /**
+   * Get query log for a context
+   */
+  getQueryLog(context?: string): QueryLogEntry[];
+
+  /**
+   * Get query summary (grouped by SQL) for a context
+   */
+  getQuerySummary(context?: string): Map<string, QueryLogEntry & { executionCount: number }>;
+
+  /**
+   * Get N+1 suspects (queries executed 5+ times in same context)
+   */
+  getN1Suspects(context?: string, threshold?: number): QueryLogEntry[];
+
+  /**
+   * Clear logs for a context
+   */
+  clear(context?: string): void;
+
+  /**
+   * Get all logs
+   */
+  getAllLogs(): Map<string, QueryLogEntry[]>;
+
+  /**
+   * Get total query count for a context
+   */
+  getQueryCount(context?: string): number;
+
+  /**
+   * Get total duration for all queries in a context
+   */
+  getTotalDuration(context?: string): number;
+}
+
+// Private state (exposed on QueryLogger for targeted unit-test coverage)
+const logs = new Map<string, QueryLogEntry[] | undefined>();
+let currentContext = 'default';
+
+const MAX_CONTEXTS = 1000;
+const MAX_QUERIES_PER_CONTEXT = 500;
+
+/**
+ * QueryLogger tracks all database queries executed during a request context
+ * Provides N+1 detection heuristic by flagging identical queries executed 5+ times
+ * Sealed namespace for immutability
+ */
+export const QueryLogger = Object.freeze({
+  // Exposed for rare-branch tests that deliberately corrupt the map.
+  logs,
+  getInstance(): IQueryLogger {
+    return this;
+  },
+  /**
+   * Set current request context ID
+   */
+  setContext(context: string): void {
+    currentContext = context;
+    if (!logs.has(context)) {
+      // Prevent unbounded growth of contexts
+      if (logs.size >= MAX_CONTEXTS) {
+        const firstKey = logs.keys().next().value;
+        if (firstKey !== undefined) {
+          logs.delete(firstKey);
+        }
+      }
+      logs.set(context, []);
+    }
+  },
+
+  /**
+   * Get current request context ID
+   */
+  getContext(): string {
+    return currentContext;
+  },
+
+  /**
+   * Log a query execution
+   */
+  logQuery(
+    sql: string,
+    params: unknown[],
+    duration: number,
+    context: string = currentContext
+  ): void {
+    if (!logs.has(context)) {
+      // Prevent unbounded growth of contexts
+      if (logs.size >= MAX_CONTEXTS) {
+        const firstKey = logs.keys().next().value;
+        if (firstKey !== undefined) {
+          logs.delete(firstKey);
+        }
+      }
+      logs.set(context, []);
+    }
+
+    const entry: QueryLogEntry = {
+      sql,
+      params,
+      duration,
+      timestamp: new Date(),
+      context,
+    };
+
+    const contextLogs = logs.get(context);
+    if (Array.isArray(contextLogs)) {
+      contextLogs.push(entry);
+
+      // Prevent unbounded growth of queries per context
+      if (contextLogs.length > MAX_QUERIES_PER_CONTEXT) {
+        contextLogs.shift();
+      }
+    }
+  },
+
+  /**
+   * Get query log for a context
+   */
+  getQueryLog(context: string = currentContext): QueryLogEntry[] {
+    const contextLogs = logs.get(context);
+    return Array.isArray(contextLogs) ? contextLogs : [];
+  },
+
+  /**
+   * Get query summary (grouped by SQL) for a context
+   */
+  getQuerySummary(
+    context: string = currentContext
+  ): Map<string, QueryLogEntry & { executionCount: number }> {
+    const queryLogs = this.getQueryLog(context);
+    const summary = new Map<string, QueryLogEntry & { executionCount: number }>();
+
+    for (const log of queryLogs) {
+      if (!summary.has(log.sql)) {
+        summary.set(log.sql, { ...log, executionCount: 0 });
+      }
+      const entry = summary.get(log.sql);
+      if (entry !== undefined) {
+        entry.executionCount++;
+      }
+    }
+
+    return summary;
+  },
+
+  /**
+   * Get N+1 suspects (queries executed 5+ times in same context)
+   * Simple heuristic: identical queries executed many times suggests N+1
+   */
+  getN1Suspects(context: string = currentContext, threshold: number = 5): QueryLogEntry[] {
+    const summary = this.getQuerySummary(context);
+    const suspects: QueryLogEntry[] = [];
+
+    for (const [, entry] of summary) {
+      if (entry.executionCount >= threshold) {
+        suspects.push(entry);
+      }
+    }
+
+    return suspects;
+  },
+
+  /**
+   * Clear logs for a context
+   */
+  clear(context?: string): void {
+    if (context === undefined) {
+      logs.clear();
+      currentContext = 'default';
+    } else {
+      logs.delete(context);
+    }
+  },
+
+  /**
+   * Get all logs
+   */
+  getAllLogs(): Map<string, QueryLogEntry[]> {
+    const copy = new Map<string, QueryLogEntry[]>();
+    for (const [key, value] of logs.entries()) {
+      if (Array.isArray(value)) {
+        copy.set(key, value);
+      }
+    }
+    return copy;
+  },
+
+  /**
+   * Get total query count for a context
+   */
+  getQueryCount(context: string = currentContext): number {
+    return this.getQueryLog(context).length;
+  },
+
+  /**
+   * Get total duration for all queries in a context
+   */
+  getTotalDuration(context: string = currentContext): number {
+    const queryLogs = this.getQueryLog(context);
+    return queryLogs.reduce((total, log) => total + log.duration, 0);
+  },
+});

package/src/profiling/RequestProfiler.ts

@@ -0,0 +1,123 @@
+/**
+ * Request Profiler
+ * Comprehensive profiling of request execution combining query, N+1, and memory metrics
+ */
+
+import type { IMemoryProfiler } from '@profiling/MemoryProfiler';
+import { MemoryProfiler } from '@profiling/MemoryProfiler';
+import { N1Detector } from '@profiling/N1Detector';
+import type { IQueryLogger } from '@profiling/QueryLogger';
+import { QueryLogger } from '@profiling/QueryLogger';
+import type { IN1Detector, N1Pattern, ProfileReport } from '@profiling/types';
+
+export interface IRequestProfiler {
+  getQueryLogger(): IQueryLogger;
+  getN1Detector(): IN1Detector;
+  getMemoryProfiler(): IMemoryProfiler;
+  captureRequest(fn: () => Promise<unknown>): Promise<ProfileReport>;
+  generateReport(profile: ProfileReport): string;
+}
+
+/**
+ * RequestProfiler orchestrates query logging, N+1 detection, and memory profiling
+ * Sealed namespace for immutability
+ */
+export const RequestProfiler = Object.freeze({
+  /**
+   * Create a new request profiler instance
+   */
+  create(): IRequestProfiler {
+    const queryLogger = QueryLogger.getInstance();
+    const n1Detector = N1Detector.create();
+    const memoryProfiler = MemoryProfiler.create();
+    let startTime: number = 0;
+    let endTime: number = 0;
+
+    return {
+      getQueryLogger(): IQueryLogger {
+        return queryLogger;
+      },
+      getN1Detector(): IN1Detector {
+        return n1Detector;
+      },
+      getMemoryProfiler(): IMemoryProfiler {
+        return memoryProfiler;
+      },
+      async captureRequest(fn: () => Promise<unknown>): Promise<ProfileReport> {
+        // Start profiling
+        startTime = Date.now();
+        memoryProfiler.start();
+        queryLogger.setContext('profiling');
+
+        try {
+          // Execute the request
+          await fn();
+        } finally {
+          // End profiling
+          endTime = Date.now();
+          memoryProfiler.end();
+        }
+
+        // Gather profiling data
+        const duration = endTime - startTime;
+        const queryLog = queryLogger.getQueryLog('profiling');
+        const queriesExecuted = queryLog.length;
+        const patterns = n1Detector.detect(queryLog);
+        const memoryDelta = memoryProfiler.delta();
+
+        const report = {
+          duration,
+          queriesExecuted,
+          n1Patterns: patterns,
+          memoryDelta,
+          timestamp: new Date(),
+        };
+
+        queryLogger.clear('profiling');
+
+        return report;
+      },
+      generateReport(profile: ProfileReport): string {
+        const n1Section = formatN1Section(profile.n1Patterns);
+
+        const lines = [
+          '=== Performance Profile Report ===',
+          `\nTiming: ${profile.duration}ms`,
+          `Queries: ${profile.queriesExecuted}`,
+          ...n1Section,
+          '\nMemory Delta:',
+          `  Heap Used: ${MemoryProfiler.formatBytes(profile.memoryDelta.heapUsed)}`,
+          `  Heap Total: ${MemoryProfiler.formatBytes(profile.memoryDelta.heapTotal)}`,
+          `  External: ${MemoryProfiler.formatBytes(profile.memoryDelta.external)}`,
+          `  RSS: ${MemoryProfiler.formatBytes(profile.memoryDelta.rss)}`,
+        ];
+
+        return lines.join('\n');
+      },
+    };
+  },
+});
+
+/**
+ * Format N+1 section for report
+ */
+function formatN1Section(patterns: N1Pattern[]): string[] {
+  if (patterns.length === 0) {
+    return ['\nN+1 Patterns: None detected'];
+  }
+
+  return [
+    '\nN+1 Patterns:',
+    ...patterns.map(
+      (pattern) =>
+        `  [${pattern.severity.toUpperCase()}] "${pattern.table}": ${pattern.queryCount}x`
+    ),
+  ];
+}
+
+/**
+ * Re-export MemoryProfiler's static formatBytes for convenience
+ */
+export { MemoryProfiler } from '@profiling/MemoryProfiler';
+
+export default RequestProfiler;