@skillsmith/core 0.1.0

package/dist/src/analytics/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/analytics/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/src/analytics/usage-tracker.d.ts

@@ -0,0 +1,132 @@
+/**
+ * SMI-914: Usage Tracker
+ *
+ * High-level API for tracking skill usage events.
+ * Handles:
+ * - Start/end tracking for duration measurement
+ * - User ID anonymization
+ * - Context hashing
+ * - Periodic cleanup of old events
+ */
+import type { SkillUsageEvent, SkillUsageOutcome, SkillMetrics } from './types.js';
+/**
+ * UsageTracker configuration options
+ */
+export interface UsageTrackerOptions {
+    /**
+     * Custom database path (defaults to ~/.skillsmith/analytics.db)
+     */
+    dbPath?: string;
+    /**
+     * Auto-cleanup interval in milliseconds (0 to disable, default: 1 hour)
+     */
+    cleanupInterval?: number;
+}
+/**
+ * High-level usage tracking API
+ *
+ * @example
+ * ```typescript
+ * const tracker = new UsageTracker();
+ *
+ * // Start tracking a skill invocation
+ * const trackingId = tracker.startTracking('anthropic/commit', 'user123');
+ *
+ * // ... skill execution ...
+ *
+ * // End tracking with outcome
+ * tracker.endTracking(trackingId, 'success', { framework: 'react' });
+ *
+ * // Get metrics
+ * const metrics = tracker.getMetrics('anthropic/commit');
+ *
+ * // Cleanup when done
+ * tracker.close();
+ * ```
+ */
+export declare class UsageTracker {
+    private storage;
+    private pendingEvents;
+    private cleanupTimer;
+    private sessionCleanupTimer;
+    /**
+     * Create a usage tracker instance
+     *
+     * @param options - Configuration options
+     */
+    constructor(options?: UsageTrackerOptions);
+    /**
+     * Start tracking a skill invocation
+     *
+     * @param skillId - The skill identifier (e.g., 'anthropic/commit')
+     * @param userId - Raw user identifier (will be anonymized)
+     * @returns Tracking ID to use when ending tracking
+     */
+    startTracking(skillId: string, userId: string): string;
+    /**
+     * End tracking and record the event
+     *
+     * @param trackingId - The tracking ID from startTracking
+     * @param outcome - The outcome of the skill invocation
+     * @param context - Optional project context (will be hashed)
+     */
+    endTracking(trackingId: string, outcome: SkillUsageOutcome, context?: Record<string, unknown>): void;
+    /**
+     * Record a complete event directly (for events that don't need start/end tracking)
+     *
+     * @param skillId - The skill identifier
+     * @param userId - Raw user identifier (will be anonymized)
+     * @param taskDuration - Duration in milliseconds
+     * @param outcome - The outcome
+     * @param context - Optional project context
+     */
+    recordEvent(skillId: string, userId: string, taskDuration: number, outcome: SkillUsageOutcome, context?: Record<string, unknown>): void;
+    /**
+     * Get metrics for a skill
+     *
+     * @param skillId - The skill identifier
+     * @returns Aggregated metrics or null if no data
+     */
+    getMetrics(skillId: string): SkillMetrics | null;
+    /**
+     * Get events for a skill
+     *
+     * @param skillId - The skill identifier
+     * @param limit - Maximum number of events
+     * @returns Array of usage events
+     */
+    getEvents(skillId: string, limit?: number): SkillUsageEvent[];
+    /**
+     * Get total event count
+     *
+     * @returns Number of stored events
+     */
+    getEventCount(): number;
+    /**
+     * Get count of pending (unfinished) trackings
+     *
+     * @returns Number of pending trackings
+     */
+    getPendingCount(): number;
+    /**
+     * Clean up events older than 30 days
+     *
+     * @returns Number of deleted events
+     */
+    cleanup(): number;
+    /**
+     * Clean up stale sessions that have exceeded the timeout
+     * This prevents unbounded memory growth from sessions that are started but never ended
+     */
+    private cleanupStaleSessions;
+    /**
+     * Close the tracker and release resources
+     */
+    close(): void;
+    /**
+     * Dispose of the tracker (alias for close)
+     * Clears all intervals and releases resources
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=usage-tracker.d.ts.map

package/dist/src/analytics/usage-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-tracker.d.ts","sourceRoot":"","sources":["../../../src/analytics/usage-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAiBlF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,mBAAmB,CAA8C;IAEzE;;;;OAIG;gBACS,OAAO,GAAE,mBAAwB;IAyB7C;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAetD;;;;;;OAMG;IACH,WAAW,CACT,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,IAAI;IAoBP;;;;;;;;OAQG;IACH,WAAW,CACT,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,IAAI;IAaP;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAIhD;;;;;;OAMG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,MAAY,GAAG,eAAe,EAAE;IAIlE;;;;OAIG;IACH,aAAa,IAAI,MAAM;IAIvB;;;;OAIG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;OAIG;IACH,OAAO,IAAI,MAAM;IAIjB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAYb;;;OAGG;IACH,OAAO,IAAI,IAAI;CAGhB"}

package/dist/src/analytics/usage-tracker.js

@@ -0,0 +1,213 @@
+/**
+ * SMI-914: Usage Tracker
+ *
+ * High-level API for tracking skill usage events.
+ * Handles:
+ * - Start/end tracking for duration measurement
+ * - User ID anonymization
+ * - Context hashing
+ * - Periodic cleanup of old events
+ */
+import { AnalyticsStorage } from './storage.js';
+import { anonymizeUserId, hashProjectContext } from './anonymizer.js';
+/**
+ * Session timeout in milliseconds (1 hour)
+ * Sessions older than this are considered stale and will be cleaned up
+ */
+const SESSION_TIMEOUT_MS = 60 * 60 * 1000;
+/**
+ * High-level usage tracking API
+ *
+ * @example
+ * ```typescript
+ * const tracker = new UsageTracker();
+ *
+ * // Start tracking a skill invocation
+ * const trackingId = tracker.startTracking('anthropic/commit', 'user123');
+ *
+ * // ... skill execution ...
+ *
+ * // End tracking with outcome
+ * tracker.endTracking(trackingId, 'success', { framework: 'react' });
+ *
+ * // Get metrics
+ * const metrics = tracker.getMetrics('anthropic/commit');
+ *
+ * // Cleanup when done
+ * tracker.close();
+ * ```
+ */
+export class UsageTracker {
+    storage;
+    pendingEvents;
+    cleanupTimer = null;
+    sessionCleanupTimer = null;
+    /**
+     * Create a usage tracker instance
+     *
+     * @param options - Configuration options
+     */
+    constructor(options = {}) {
+        this.storage = new AnalyticsStorage(options.dbPath);
+        this.pendingEvents = new Map();
+        // Setup auto-cleanup (default: every hour)
+        const cleanupInterval = options.cleanupInterval ?? 60 * 60 * 1000;
+        if (cleanupInterval > 0) {
+            this.cleanupTimer = setInterval(() => this.cleanup(), cleanupInterval);
+            // Don't block Node.js from exiting
+            if (this.cleanupTimer.unref) {
+                this.cleanupTimer.unref();
+            }
+        }
+        // Setup session cleanup at half the timeout interval to prevent unbounded growth
+        this.sessionCleanupTimer = setInterval(() => this.cleanupStaleSessions(), SESSION_TIMEOUT_MS / 2);
+        // Don't block Node.js from exiting
+        if (this.sessionCleanupTimer.unref) {
+            this.sessionCleanupTimer.unref();
+        }
+    }
+    /**
+     * Start tracking a skill invocation
+     *
+     * @param skillId - The skill identifier (e.g., 'anthropic/commit')
+     * @param userId - Raw user identifier (will be anonymized)
+     * @returns Tracking ID to use when ending tracking
+     */
+    startTracking(skillId, userId) {
+        // Clean up stale sessions opportunistically to prevent buildup
+        this.cleanupStaleSessions();
+        const trackingId = `${skillId}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        this.pendingEvents.set(trackingId, {
+            skillId,
+            startTime: Date.now(),
+            rawUserId: userId,
+        });
+        return trackingId;
+    }
+    /**
+     * End tracking and record the event
+     *
+     * @param trackingId - The tracking ID from startTracking
+     * @param outcome - The outcome of the skill invocation
+     * @param context - Optional project context (will be hashed)
+     */
+    endTracking(trackingId, outcome, context = {}) {
+        const pending = this.pendingEvents.get(trackingId);
+        if (!pending) {
+            // Silently ignore unknown tracking IDs (could be from a previous session)
+            return;
+        }
+        const event = {
+            skillId: pending.skillId,
+            userId: anonymizeUserId(pending.rawUserId),
+            timestamp: Date.now(),
+            taskDuration: Date.now() - pending.startTime,
+            outcome,
+            contextHash: hashProjectContext(context),
+        };
+        this.storage.recordEvent(event);
+        this.pendingEvents.delete(trackingId);
+    }
+    /**
+     * Record a complete event directly (for events that don't need start/end tracking)
+     *
+     * @param skillId - The skill identifier
+     * @param userId - Raw user identifier (will be anonymized)
+     * @param taskDuration - Duration in milliseconds
+     * @param outcome - The outcome
+     * @param context - Optional project context
+     */
+    recordEvent(skillId, userId, taskDuration, outcome, context = {}) {
+        const event = {
+            skillId,
+            userId: anonymizeUserId(userId),
+            timestamp: Date.now(),
+            taskDuration,
+            outcome,
+            contextHash: hashProjectContext(context),
+        };
+        this.storage.recordEvent(event);
+    }
+    /**
+     * Get metrics for a skill
+     *
+     * @param skillId - The skill identifier
+     * @returns Aggregated metrics or null if no data
+     */
+    getMetrics(skillId) {
+        return this.storage.getMetricsForSkill(skillId);
+    }
+    /**
+     * Get events for a skill
+     *
+     * @param skillId - The skill identifier
+     * @param limit - Maximum number of events
+     * @returns Array of usage events
+     */
+    getEvents(skillId, limit = 100) {
+        return this.storage.getEventsForSkill(skillId, limit);
+    }
+    /**
+     * Get total event count
+     *
+     * @returns Number of stored events
+     */
+    getEventCount() {
+        return this.storage.getEventCount();
+    }
+    /**
+     * Get count of pending (unfinished) trackings
+     *
+     * @returns Number of pending trackings
+     */
+    getPendingCount() {
+        return this.pendingEvents.size;
+    }
+    /**
+     * Clean up events older than 30 days
+     *
+     * @returns Number of deleted events
+     */
+    cleanup() {
+        return this.storage.cleanup();
+    }
+    /**
+     * Clean up stale sessions that have exceeded the timeout
+     * This prevents unbounded memory growth from sessions that are started but never ended
+     */
+    cleanupStaleSessions() {
+        const now = Date.now();
+        let expiredCount = 0;
+        for (const [trackingId, pending] of this.pendingEvents.entries()) {
+            if (now - pending.startTime > SESSION_TIMEOUT_MS) {
+                this.pendingEvents.delete(trackingId);
+                expiredCount++;
+            }
+        }
+        if (expiredCount > 0) {
+            console.warn(`[usage-tracker] Cleaned up ${expiredCount} stale sessions`);
+        }
+    }
+    /**
+     * Close the tracker and release resources
+     */
+    close() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        if (this.sessionCleanupTimer) {
+            clearInterval(this.sessionCleanupTimer);
+            this.sessionCleanupTimer = null;
+        }
+        this.storage.close();
+    }
+    /**
+     * Dispose of the tracker (alias for close)
+     * Clears all intervals and releases resources
+     */
+    dispose() {
+        this.close();
+    }
+}
+//# sourceMappingURL=usage-tracker.js.map

package/dist/src/analytics/usage-tracker.js.map

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

package/dist/src/benchmarks/BenchmarkRunner.d.ts

@@ -0,0 +1,258 @@
+/**
+ * SMI-632: BenchmarkRunner - Performance benchmark infrastructure
+ * SMI-689: Enhanced with MemoryProfiler integration
+ *
+ * Features:
+ * - Run benchmark suites
+ * - Measure p50, p95, p99 latencies
+ * - Memory usage tracking with MemoryProfiler
+ * - Memory regression detection (fail if heap grows >10% vs baseline)
+ * - Warm-up runs before measurement
+ * - Statistical analysis (mean, stddev)
+ */
+import { MemoryProfiler, type MemoryBaseline, type MemoryRegressionResult } from './MemoryProfiler.js';
+/**
+ * Benchmark configuration options
+ */
+export interface BenchmarkConfig {
+    /** Number of warm-up iterations before measurement */
+    warmupIterations?: number;
+    /** Number of measured iterations */
+    iterations?: number;
+    /** Enable memory profiling */
+    measureMemory?: boolean;
+    /** Suite name for grouping */
+    suiteName?: string;
+    /** Enable detailed memory profiling with MemoryProfiler (SMI-689) */
+    enableMemoryProfiler?: boolean;
+    /** Memory regression threshold percentage (SMI-689, default: 10) */
+    memoryRegressionThreshold?: number;
+    /** Memory baselines for regression comparison (SMI-689) */
+    memoryBaselines?: Record<string, MemoryBaseline>;
+}
+/**
+ * Single benchmark result
+ */
+export interface BenchmarkResult {
+    name: string;
+    iterations: number;
+    latencies: number[];
+    memoryUsage?: MemoryStats;
+    /** Number of errors encountered during benchmark execution */
+    errors: number;
+    /** Error messages (capped at 10 to prevent memory issues) */
+    errorMessages: string[];
+}
+/**
+ * Memory usage statistics
+ */
+export interface MemoryStats {
+    heapUsedBefore: number;
+    heapUsedAfter: number;
+    heapUsedPeak: number;
+    externalBefore: number;
+    externalAfter: number;
+}
+/**
+ * Statistical summary of benchmark results
+ */
+export interface BenchmarkStats {
+    name: string;
+    iterations: number;
+    p50_ms: number;
+    p95_ms: number;
+    p99_ms: number;
+    mean_ms: number;
+    stddev_ms: number;
+    min_ms: number;
+    max_ms: number;
+    memoryPeak_mb?: number;
+    /** Number of errors encountered during benchmark execution */
+    errors?: number;
+    /** Error messages (capped at 10) */
+    errorMessages?: string[];
+}
+/**
+ * Detailed memory profiling stats (SMI-689)
+ */
+export interface DetailedMemoryStats {
+    /** Start heap size in bytes */
+    startHeapSize: number;
+    /** End heap size in bytes */
+    endHeapSize: number;
+    /** Peak heap size in bytes */
+    peakHeapSize: number;
+    /** Heap growth in bytes */
+    heapGrowth: number;
+    /** Heap growth as percentage */
+    heapGrowthPercent: number;
+    /** Duration of profiling in ms */
+    profilingDuration: number;
+    /** Number of samples collected */
+    sampleCount: number;
+}
+/**
+ * Memory regression info (SMI-689)
+ */
+export interface MemoryRegressionInfo {
+    /** Whether any regressions were detected */
+    hasRegressions: boolean;
+    /** Threshold used for detection */
+    threshold: number;
+    /** Details per benchmark */
+    regressions: MemoryRegressionResult[];
+}
+/**
+ * Complete benchmark report
+ */
+export interface BenchmarkReport {
+    suite: string;
+    timestamp: string;
+    environment: EnvironmentInfo;
+    results: Record<string, BenchmarkStats>;
+    summary: {
+        totalBenchmarks: number;
+        totalIterations: number;
+        totalDuration_ms: number;
+    };
+    /** Detailed memory profiling data (SMI-689) */
+    memoryProfile?: Record<string, DetailedMemoryStats>;
+    /** Memory regression info (SMI-689) */
+    memoryRegression?: MemoryRegressionInfo;
+    /** Memory baselines for future comparison (SMI-689) */
+    memoryBaselines?: Record<string, MemoryBaseline>;
+}
+/**
+ * Environment information for reproducibility
+ */
+export interface EnvironmentInfo {
+    node: string;
+    platform: string;
+    arch: string;
+    docker: boolean;
+    database: string;
+    cpuCount: number;
+    memoryTotal_mb: number;
+}
+/**
+ * Benchmark function type
+ */
+export type BenchmarkFn = () => void | Promise<void>;
+/**
+ * Benchmark definition
+ */
+export interface BenchmarkDefinition {
+    name: string;
+    fn: BenchmarkFn;
+    setup?: () => void | Promise<void>;
+    teardown?: () => void | Promise<void>;
+}
+/**
+ * Core benchmark runner for performance testing
+ */
+export declare class BenchmarkRunner {
+    private config;
+    private benchmarks;
+    private results;
+    /** SMI-689: Memory profiler instance */
+    private memoryProfiler;
+    constructor(config?: BenchmarkConfig);
+    /**
+     * Get the memory profiler instance (SMI-689)
+     */
+    getMemoryProfiler(): MemoryProfiler | null;
+    /**
+     * Add a benchmark to the suite
+     */
+    add(definition: BenchmarkDefinition): this;
+    /**
+     * Run all benchmarks in the suite
+     */
+    run(): Promise<BenchmarkReport>;
+    /**
+     * Run a single benchmark with error handling (SMI-678)
+     */
+    private runBenchmark;
+    /**
+     * Generate a benchmark report from results
+     */
+    private generateReport;
+    /**
+     * Calculate statistical metrics from latencies
+     * Uses shared stats module for consistent calculations (SMI-677)
+     * Includes empty array guard (SMI-679) and sample variance (Bessel correction)
+     */
+    private calculateStats;
+    /**
+     * @deprecated Use shared percentile from stats.ts instead (SMI-677)
+     * Calculate percentile value from sorted array
+     */
+    private _legacyPercentile;
+    /**
+     * Get environment information
+     */
+    private getEnvironmentInfo;
+    /**
+     * Detect if running in Docker
+     */
+    private isDocker;
+    /**
+     * Force garbage collection if available
+     */
+    private forceGC;
+    /**
+     * Get raw results
+     */
+    getResults(): BenchmarkResult[];
+    /**
+     * Clear all benchmarks
+     */
+    clear(): void;
+    /**
+     * Enable memory profiler after construction (SMI-689)
+     */
+    enableMemoryProfiler(baselines?: Record<string, MemoryBaseline>): void;
+    /**
+     * Get memory profiling report as string (SMI-689)
+     */
+    getMemoryReport(): string;
+}
+/**
+ * Format a benchmark report as JSON for CI integration
+ */
+export declare function formatReportAsJson(report: BenchmarkReport): string;
+/**
+ * Format a benchmark report as human-readable text
+ */
+export declare function formatReportAsText(report: BenchmarkReport): string;
+/**
+ * Compare two benchmark reports
+ */
+export declare function compareReports(baseline: BenchmarkReport, current: BenchmarkReport): ComparisonResult;
+/**
+ * Comparison result between two reports
+ */
+export interface ComparisonResult {
+    baseline: string;
+    current: string;
+    comparisons: Record<string, MetricComparison>;
+    summary: {
+        totalComparisons: number;
+        regressions: number;
+        improvements: number;
+        unchanged: number;
+    };
+}
+/**
+ * Single metric comparison
+ */
+export interface MetricComparison {
+    baseline: BenchmarkStats;
+    current: BenchmarkStats;
+    p50ChangePercent: number;
+    p95ChangePercent: number;
+    p99ChangePercent: number;
+    isRegression: boolean;
+    isImprovement: boolean;
+}
+//# sourceMappingURL=BenchmarkRunner.d.ts.map

package/dist/src/benchmarks/BenchmarkRunner.d.ts.map

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