@zintrust/core 0.4.17 → 0.4.18

package/src/performance/establish-baseline.ts

@@ -1,69 +0,0 @@
-/**
- * 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

@@ -1,111 +0,0 @@
-/**
- * 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

@@ -1,144 +0,0 @@
-/**
- * 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

@@ -1,233 +0,0 @@
-/**
- * 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

@@ -1,123 +0,0 @@
-/**
- * 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;