@skillsmith/core 0.2.0 → 2.0.0

package/dist/src/analysis/metrics.d.ts

@@ -0,0 +1,300 @@
+/**
+ * SMI-1337: Analysis Pipeline Metrics and Telemetry
+ *
+ * Provides metrics collection for the multi-language analysis pipeline:
+ * - Files parsed per language (counter)
+ * - Parse duration by language (histogram)
+ * - Cache hit/miss rates (gauge)
+ * - Worker pool utilization (gauge)
+ * - Memory usage (gauge)
+ * - Error counts by type (counter)
+ *
+ * Configuration:
+ * - SKILLSMITH_TELEMETRY_ENABLED: Master switch for all telemetry (default: auto)
+ * - SKILLSMITH_ANALYSIS_METRICS_ENABLED: Enable/disable analysis metrics (default: true)
+ *
+ * Graceful Fallback:
+ * - If OpenTelemetry packages are not installed, uses in-memory implementations
+ * - Metrics APIs remain functional for local statistics
+ *
+ * @see docs/architecture/multi-language-analysis.md
+ * @module analysis/metrics
+ */
+import type { Counter, Histogram, Gauge, MetricLabels } from '../telemetry/metrics.js';
+import type { SupportedLanguage } from './types.js';
+/**
+ * Analysis metrics configuration
+ */
+export interface AnalysisMetricsConfig {
+    /** Whether to enable metrics collection (default: true) */
+    enabled?: boolean;
+    /** Prefix for all metric names (default: skillsmith.analysis) */
+    metricPrefix?: string;
+}
+/**
+ * In-memory counter implementation
+ */
+declare class InMemoryCounter implements Counter {
+    private values;
+    add(value: number, labels?: MetricLabels): void;
+    increment(labels?: MetricLabels): void;
+    getValues(): Map<string, number>;
+    getTotal(): number;
+    reset(): void;
+}
+/**
+ * In-memory histogram implementation
+ */
+declare class InMemoryHistogram implements Histogram {
+    private values;
+    private labeledValues;
+    record(value: number, labels?: MetricLabels): void;
+    getStats(): {
+        count: number;
+        sum: number;
+        mean: number;
+        p50: number;
+        p95: number;
+        p99: number;
+    };
+    getStatsByLabel(labels: MetricLabels): ReturnType<typeof this.getStats>;
+    reset(): void;
+}
+/**
+ * In-memory gauge implementation
+ */
+declare class InMemoryGauge implements Gauge {
+    private values;
+    set(value: number, labels?: MetricLabels): void;
+    getValue(labels?: MetricLabels): number;
+    getAllValues(): Map<string, number>;
+    reset(): void;
+}
+/**
+ * Analysis metrics snapshot for export
+ */
+export interface AnalysisMetricsSnapshot {
+    timestamp: string;
+    filesParsed: {
+        total: number;
+        byLanguage: Record<string, number>;
+    };
+    parseDuration: {
+        stats: {
+            count: number;
+            sum: number;
+            mean: number;
+            p50: number;
+            p95: number;
+            p99: number;
+        };
+        byLanguage: Record<string, {
+            count: number;
+            sum: number;
+            mean: number;
+            p50: number;
+            p95: number;
+            p99: number;
+        }>;
+    };
+    cache: {
+        hits: number;
+        misses: number;
+        hitRate: number;
+        size: number;
+    };
+    workerPool: {
+        activeWorkers: number;
+        queuedTasks: number;
+        utilization: number;
+    };
+    memory: {
+        heapUsed: number;
+        heapTotal: number;
+        rss: number;
+    };
+    errors: {
+        total: number;
+        byType: Record<string, number>;
+    };
+    aggregator: {
+        filesProcessed: number;
+        totalImports: number;
+        totalExports: number;
+        totalFunctions: number;
+    };
+}
+/**
+ * Analysis Pipeline Metrics Collector
+ *
+ * Provides comprehensive metrics collection for the multi-language
+ * analysis pipeline with graceful fallback when telemetry is unavailable.
+ *
+ * @example
+ * ```typescript
+ * const metrics = new AnalysisMetrics()
+ *
+ * // Record file parse
+ * metrics.recordFileParsed('typescript')
+ *
+ * // Record parse duration
+ * metrics.recordParseDuration('typescript', 15.5)
+ *
+ * // Record cache operations
+ * metrics.recordCacheHit()
+ * metrics.recordCacheMiss()
+ *
+ * // Get snapshot
+ * const snapshot = metrics.getSnapshot()
+ * console.log(`Parse p95: ${snapshot.parseDuration.stats.p95}ms`)
+ * ```
+ */
+export declare class AnalysisMetrics {
+    private readonly enabled;
+    private readonly prefix;
+    readonly filesParsed: InMemoryCounter;
+    readonly parseDuration: InMemoryHistogram;
+    readonly cacheHits: InMemoryCounter;
+    readonly cacheMisses: InMemoryCounter;
+    readonly cacheSize: InMemoryGauge;
+    readonly workerPoolActive: InMemoryGauge;
+    readonly workerPoolQueued: InMemoryGauge;
+    readonly workerPoolUtilization: InMemoryGauge;
+    readonly memoryHeapUsed: InMemoryGauge;
+    readonly memoryHeapTotal: InMemoryGauge;
+    readonly memoryRss: InMemoryGauge;
+    readonly errorCount: InMemoryCounter;
+    readonly aggregatorFilesProcessed: InMemoryGauge;
+    readonly aggregatorImports: InMemoryGauge;
+    readonly aggregatorExports: InMemoryGauge;
+    readonly aggregatorFunctions: InMemoryGauge;
+    constructor(config?: AnalysisMetricsConfig);
+    /**
+     * Check if metrics collection is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Record a file being parsed
+     *
+     * @param language - The language of the parsed file
+     */
+    recordFileParsed(language: SupportedLanguage | string): void;
+    /**
+     * Record parse duration for a file
+     *
+     * @param language - The language of the parsed file
+     * @param durationMs - Parse duration in milliseconds
+     */
+    recordParseDuration(language: SupportedLanguage | string, durationMs: number): void;
+    /**
+     * Record a cache hit
+     *
+     * @param language - Optional language for the cache hit
+     */
+    recordCacheHit(language?: SupportedLanguage | string): void;
+    /**
+     * Record a cache miss
+     *
+     * @param language - Optional language for the cache miss
+     */
+    recordCacheMiss(language?: SupportedLanguage | string): void;
+    /**
+     * Update cache size
+     *
+     * @param size - Current cache size in bytes
+     * @param entries - Current number of cache entries
+     */
+    updateCacheSize(size: number, entries?: number): void;
+    /**
+     * Update worker pool metrics
+     *
+     * @param activeWorkers - Number of currently active workers
+     * @param queuedTasks - Number of tasks waiting in queue
+     * @param poolSize - Total pool size for utilization calculation
+     */
+    updateWorkerPool(activeWorkers: number, queuedTasks: number, poolSize?: number): void;
+    /**
+     * Update memory usage metrics
+     *
+     * Records current Node.js memory usage stats.
+     */
+    updateMemoryUsage(): void;
+    /**
+     * Record an error
+     *
+     * @param errorType - Type/category of the error
+     * @param language - Optional language context
+     */
+    recordError(errorType: string, language?: SupportedLanguage | string): void;
+    /**
+     * Update aggregator metrics
+     *
+     * @param filesProcessed - Number of files processed
+     * @param imports - Total imports found
+     * @param exports - Total exports found
+     * @param functions - Total functions found
+     */
+    updateAggregatorStats(filesProcessed: number, imports: number, exports: number, functions: number): void;
+    /**
+     * Get cache hit rate
+     *
+     * @returns Cache hit rate as a decimal (0-1)
+     */
+    getCacheHitRate(): number;
+    /**
+     * Get files parsed by language
+     *
+     * @returns Map of language to count
+     */
+    getFilesByLanguage(): Record<string, number>;
+    /**
+     * Get parse duration stats by language
+     *
+     * @param language - Language to get stats for
+     * @returns Duration statistics
+     */
+    getParseDurationByLanguage(language: SupportedLanguage | string): ReturnType<InMemoryHistogram['getStats']>;
+    /**
+     * Get complete metrics snapshot
+     *
+     * @returns Snapshot of all current metrics
+     */
+    getSnapshot(): AnalysisMetricsSnapshot;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+}
+/**
+ * Get the default analysis metrics instance
+ *
+ * @returns The shared AnalysisMetrics instance
+ */
+export declare function getAnalysisMetrics(): AnalysisMetrics;
+/**
+ * Initialize the default analysis metrics instance
+ *
+ * @param config - Optional configuration
+ * @returns The initialized AnalysisMetrics instance
+ */
+export declare function initializeAnalysisMetrics(config?: AnalysisMetricsConfig): AnalysisMetrics;
+/**
+ * Helper: Time an async operation and record to analysis metrics
+ *
+ * @param language - Language being parsed
+ * @param fn - Async function to time
+ * @param metrics - Optional metrics instance (uses default if not provided)
+ * @returns Result of the function
+ */
+export declare function timeParseAsync<T>(language: SupportedLanguage | string, fn: () => Promise<T>, metrics?: AnalysisMetrics): Promise<T>;
+/**
+ * Helper: Time a sync operation and record to analysis metrics
+ *
+ * @param language - Language being parsed
+ * @param fn - Function to time
+ * @param metrics - Optional metrics instance (uses default if not provided)
+ * @returns Result of the function
+ */
+export declare function timeParseSync<T>(language: SupportedLanguage | string, fn: () => T, metrics?: AnalysisMetrics): T;
+export {};
+//# sourceMappingURL=metrics.d.ts.map

package/dist/src/analysis/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/analysis/metrics.ts"],"names":[],"mappings":"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"}