flow-debugger 1.0.0

package/tests/Analytics.test.ts

@@ -0,0 +1,136 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Analytics Tests
+// ─────────────────────────────────────────────────────────────
+
+import { Analytics } from '../src/core/Analytics';
+import { Trace, TraceStep } from '../src/core/types';
+
+function createTrace(overrides: Partial<Trace> = {}): Trace {
+    return {
+        traceId: 'req_test_' + Math.random().toString(36).substring(2, 6),
+        endpoint: '/api/test',
+        method: 'GET',
+        statusCode: 200,
+        steps: [],
+        totalDuration: 50,
+        classification: 'INFO',
+        rootCause: null,
+        startTime: 0,
+        endTime: 50,
+        timestamp: new Date(),
+        ...overrides,
+    };
+}
+
+describe('Analytics', () => {
+    let analytics: Analytics;
+
+    beforeEach(() => {
+        analytics = new Analytics(100);
+    });
+
+    test('should record traces', () => {
+        analytics.record(createTrace());
+        analytics.record(createTrace());
+        expect(analytics.getTraceCount()).toBe(2);
+    });
+
+    test('should produce endpoint stats', () => {
+        analytics.record(createTrace({ endpoint: '/api/login', method: 'POST', totalDuration: 30 }));
+        analytics.record(createTrace({ endpoint: '/api/login', method: 'POST', totalDuration: 50 }));
+        analytics.record(createTrace({ endpoint: '/api/orders', method: 'GET', totalDuration: 100 }));
+
+        const report = analytics.getReport();
+        expect(report.totalRequests).toBe(3);
+        expect(report.endpoints).toHaveLength(2);
+
+        const loginStats = report.endpoints.find(e => e.path === '/api/login');
+        expect(loginStats).toBeDefined();
+        expect(loginStats!.totalRequests).toBe(2);
+        expect(loginStats!.avgDuration).toBe(40);
+    });
+
+    test('should count errors and slow requests', () => {
+        analytics.record(createTrace({ classification: 'ERROR' }));
+        analytics.record(createTrace({ classification: 'CRITICAL' }));
+        analytics.record(createTrace({ classification: 'WARN' }));
+        analytics.record(createTrace({ classification: 'INFO' }));
+
+        const report = analytics.getReport();
+        expect(report.totalErrors).toBe(2);
+        expect(report.totalSlow).toBe(1);
+    });
+
+    test('should track service failures', () => {
+        const failedStep: TraceStep = {
+            name: 'Redis get',
+            service: 'redis',
+            status: 'error',
+            classification: 'ERROR',
+            startTime: 0,
+            endTime: 10,
+            duration: 10,
+            error: 'Connection refused',
+        };
+
+        analytics.record(createTrace({
+            steps: [failedStep],
+            classification: 'ERROR',
+        }));
+
+        const report = analytics.getReport();
+        expect(report.topFailures.length).toBeGreaterThan(0);
+        expect(report.topFailures[0].service).toBe('redis');
+        expect(report.topFailures[0].percentage).toBe(100);
+    });
+
+    test('should trim old traces when over max', () => {
+        const analytics = new Analytics(5);
+        for (let i = 0; i < 10; i++) {
+            analytics.record(createTrace());
+        }
+        expect(analytics.getTraceCount()).toBe(5);
+    });
+
+    test('should track common issues', () => {
+        analytics.record(createTrace({
+            rootCause: { cause: 'Redis failure', step: 'Redis GET', service: 'redis', confidence: 'high' },
+        }));
+        analytics.record(createTrace({
+            rootCause: { cause: 'Redis failure', step: 'Redis GET', service: 'redis', confidence: 'high' },
+        }));
+
+        const report = analytics.getReport();
+        const ep = report.endpoints[0];
+        expect(ep.commonIssues.length).toBeGreaterThan(0);
+        expect(ep.commonIssues[0]).toContain('Redis failure');
+    });
+
+    test('should get endpoint-specific report', () => {
+        analytics.record(createTrace({ endpoint: '/api/login', method: 'POST' }));
+        analytics.record(createTrace({ endpoint: '/api/orders', method: 'GET' }));
+
+        const loginReport = analytics.getEndpointReport('/api/login');
+        expect(loginReport).not.toBeNull();
+        expect(loginReport!.path).toBe('/api/login');
+    });
+
+    test('should return health monitor data', () => {
+        const step: TraceStep = {
+            name: 'Mongo find',
+            service: 'mongo',
+            status: 'success',
+            classification: 'INFO',
+            startTime: 0,
+            endTime: 10,
+            duration: 10,
+        };
+
+        analytics.record(createTrace({ steps: [step] }));
+
+        const report = analytics.getReport();
+        expect(report.serviceHealth.length).toBeGreaterThan(0);
+        expect(report.serviceHealth[0].service).toBe('mongo');
+        expect(report.serviceHealth[0].status).toBe('healthy');
+    });
+});

package/tests/Classifier.test.ts

@@ -0,0 +1,57 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Classifier Tests
+// ─────────────────────────────────────────────────────────────
+
+import { classify, classifyTrace, classifyQuery } from '../src/core/Classifier';
+import { TraceStep } from '../src/core/types';
+
+const config = { slowThreshold: 300, slowQueryThreshold: 300 };
+
+describe('Classifier', () => {
+    describe('classify (single step)', () => {
+        test('INFO for fast success', () => {
+            expect(classify(50, 'success', config)).toBe('INFO');
+        });
+
+        test('WARN for slow success', () => {
+            expect(classify(500, 'success', config)).toBe('WARN');
+        });
+
+        test('ERROR for failed step', () => {
+            expect(classify(10, 'error', config)).toBe('ERROR');
+        });
+
+        test('CRITICAL for timeout', () => {
+            expect(classify(5000, 'timeout', config)).toBe('CRITICAL');
+        });
+
+        test('respects custom threshold', () => {
+            expect(classify(150, 'success', { slowThreshold: 100 })).toBe('WARN');
+            expect(classify(150, 'success', { slowThreshold: 200 })).toBe('INFO');
+        });
+    });
+
+    describe('classifyTrace', () => {
+        test('inherits highest severity from steps', () => {
+            const steps: TraceStep[] = [
+                { name: 'a', service: 'mongo', status: 'success', classification: 'INFO', startTime: 0, endTime: 10, duration: 10 },
+                { name: 'b', service: 'redis', status: 'error', classification: 'ERROR', startTime: 10, endTime: 15, duration: 5 },
+            ];
+            expect(classifyTrace(steps, 20, config)).toBe('ERROR');
+        });
+
+        test('WARN when total duration is slow even if steps are fast', () => {
+            const steps: TraceStep[] = [
+                { name: 'a', service: 'internal', status: 'success', classification: 'INFO', startTime: 0, endTime: 10, duration: 10 },
+            ];
+            expect(classifyTrace(steps, 500, config)).toBe('WARN');
+        });
+    });
+
+    describe('classifyQuery', () => {
+        test('uses slowQueryThreshold', () => {
+            expect(classifyQuery(100, 'success', { slowQueryThreshold: 300 })).toBe('INFO');
+            expect(classifyQuery(400, 'success', { slowQueryThreshold: 300 })).toBe('WARN');
+        });
+    });
+});

package/tests/RootCause.test.ts

@@ -0,0 +1,69 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Root Cause Tests
+// ─────────────────────────────────────────────────────────────
+
+import { detectRootCause } from '../src/core/RootCause';
+import { TraceStep } from '../src/core/types';
+
+const config = { slowThreshold: 300, slowQueryThreshold: 300 };
+
+describe('RootCause', () => {
+    test('returns null for empty steps', () => {
+        expect(detectRootCause([], 200, config)).toBeNull();
+    });
+
+    test('returns null for all-healthy trace', () => {
+        const steps: TraceStep[] = [
+            { name: 'DB query', service: 'mongo', status: 'success', classification: 'INFO', startTime: 0, endTime: 10, duration: 10 },
+            { name: 'Redis get', service: 'redis', status: 'success', classification: 'INFO', startTime: 10, endTime: 15, duration: 5 },
+        ];
+        expect(detectRootCause(steps, 200, config)).toBeNull();
+    });
+
+    test('detects timeout as high-confidence root cause', () => {
+        const steps: TraceStep[] = [
+            { name: 'DB query', service: 'mongo', status: 'success', classification: 'INFO', startTime: 0, endTime: 10, duration: 10 },
+            { name: 'Redis SET', service: 'redis', status: 'timeout', classification: 'CRITICAL', startTime: 10, endTime: 5010, duration: 5000, error: 'timeout' },
+        ];
+        const rc = detectRootCause(steps, 500, config);
+        expect(rc).not.toBeNull();
+        expect(rc!.service).toBe('redis');
+        expect(rc!.confidence).toBe('high');
+        expect(rc!.cause).toContain('timed out');
+    });
+
+    test('detects first failed step on 500 response', () => {
+        const steps: TraceStep[] = [
+            { name: 'DB find', service: 'mongo', status: 'error', classification: 'ERROR', startTime: 0, endTime: 10, duration: 10, error: 'Connection lost' },
+            { name: 'Redis set', service: 'redis', status: 'success', classification: 'INFO', startTime: 10, endTime: 15, duration: 5 },
+        ];
+        const rc = detectRootCause(steps, 500, config);
+        expect(rc).not.toBeNull();
+        expect(rc!.step).toBe('DB find');
+        expect(rc!.service).toBe('mongo');
+        expect(rc!.confidence).toBe('high');
+    });
+
+    test('detects slow DB as root cause', () => {
+        const steps: TraceStep[] = [
+            { name: 'DB orders query', service: 'postgres', status: 'success', classification: 'WARN', startTime: 0, endTime: 800, duration: 800 },
+            { name: 'Redis cache', service: 'redis', status: 'success', classification: 'INFO', startTime: 800, endTime: 805, duration: 5 },
+        ];
+        const rc = detectRootCause(steps, 200, config);
+        expect(rc).not.toBeNull();
+        expect(rc!.service).toBe('postgres');
+        expect(rc!.cause).toContain('Slow');
+        expect(rc!.confidence).toBe('high'); // >50% of total
+    });
+
+    test('medium confidence when multiple slow steps', () => {
+        const steps: TraceStep[] = [
+            { name: 'DB query', service: 'postgres', status: 'success', classification: 'WARN', startTime: 0, endTime: 400, duration: 400 },
+            { name: 'Redis op', service: 'redis', status: 'success', classification: 'WARN', startTime: 400, endTime: 800, duration: 400 },
+        ];
+        const rc = detectRootCause(steps, 200, config);
+        expect(rc).not.toBeNull();
+        // Both are equally slow, so confidence should be medium
+        expect(rc!.confidence).toBe('medium');
+    });
+});

package/tests/TraceEngine.test.ts

@@ -0,0 +1,110 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — TraceEngine Tests
+// ─────────────────────────────────────────────────────────────
+
+import { TraceEngine } from '../src/core/TraceEngine';
+
+describe('TraceEngine', () => {
+    let engine: TraceEngine;
+
+    beforeEach(() => {
+        engine = new TraceEngine({
+            enableTimeline: false, // suppress console output in tests
+            slowThreshold: 300,
+            slowQueryThreshold: 300,
+        });
+    });
+
+    test('should generate unique trace IDs', () => {
+        const t1 = engine.startTrace('/api/login', 'POST');
+        const t2 = engine.startTrace('/api/orders', 'GET');
+        expect(t1.getTraceId()).not.toBe(t2.getTraceId());
+        expect(t1.getTraceId()).toMatch(/^req_/);
+    });
+
+    test('should track steps with timing', async () => {
+        const tracer = engine.startTrace('/api/test', 'GET');
+
+        await tracer.step('DB query', async () => {
+            await new Promise(r => setTimeout(r, 10));
+            return 'result';
+        }, { service: 'mongo' });
+
+        const trace = tracer.end(200);
+        expect(trace.steps).toHaveLength(1);
+        expect(trace.steps[0].name).toBe('DB query');
+        expect(trace.steps[0].service).toBe('mongo');
+        expect(trace.steps[0].status).toBe('success');
+        expect(trace.steps[0].duration).toBeGreaterThan(5);
+    });
+
+    test('should return step result', async () => {
+        const tracer = engine.startTrace('/test', 'GET');
+        const result = await tracer.step('compute', async () => {
+            return { value: 42 };
+        });
+        expect(result).toEqual({ value: 42 });
+        tracer.end(200);
+    });
+
+    test('should catch step errors', async () => {
+        const tracer = engine.startTrace('/test', 'GET');
+
+        await expect(
+            tracer.step('failing step', async () => {
+                throw new Error('DB connection failed');
+            }, { service: 'postgres' })
+        ).rejects.toThrow('DB connection failed');
+
+        const trace = tracer.end(500);
+        expect(trace.steps[0].status).toBe('error');
+        expect(trace.steps[0].error).toBe('DB connection failed');
+        expect(trace.steps[0].stackTrace).toBeDefined();
+    });
+
+    test('should detect step timeout', async () => {
+        const tracer = engine.startTrace('/test', 'GET');
+
+        await expect(
+            tracer.step('slow query', async () => {
+                await new Promise(r => setTimeout(r, 500));
+            }, { service: 'mysql', timeout: 50 })
+        ).rejects.toThrow('timed out');
+
+        const trace = tracer.end(500);
+        expect(trace.steps[0].status).toBe('timeout');
+        expect(trace.steps[0].classification).toBe('CRITICAL');
+    });
+
+    test('should track multiple steps in order', async () => {
+        const tracer = engine.startTrace('/api/login', 'POST');
+
+        await tracer.step('DB find user', async () => 'user', { service: 'mongo' });
+        await tracer.step('Redis cache', async () => 'OK', { service: 'redis' });
+        await tracer.step('JWT generate', async () => 'token', { service: 'internal' });
+
+        const trace = tracer.end(200);
+        expect(trace.steps).toHaveLength(3);
+        expect(trace.steps[0].name).toBe('DB find user');
+        expect(trace.steps[1].name).toBe('Redis cache');
+        expect(trace.steps[2].name).toBe('JWT generate');
+    });
+
+    test('should emit trace events', (done) => {
+        engine.on('trace:end', (trace) => {
+            expect(trace.traceId).toMatch(/^req_/);
+            expect(trace.endpoint).toBe('/test');
+            done();
+        });
+
+        const tracer = engine.startTrace('/test', 'GET');
+        tracer.end(200);
+    });
+
+    test('should set total duration', async () => {
+        const tracer = engine.startTrace('/test', 'GET');
+        await new Promise(r => setTimeout(r, 20));
+        const trace = tracer.end(200);
+        expect(trace.totalDuration).toBeGreaterThan(15);
+    });
+});

package/tsconfig.cjs.json

@@ -0,0 +1,9 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "module": "commonjs",
+        "outDir": "./dist/cjs",
+        "declaration": false,
+        "declarationMap": false
+    }
+}

package/tsconfig.esm.json

@@ -0,0 +1,9 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "module": "ES2020",
+        "outDir": "./dist/esm",
+        "declaration": false,
+        "declarationMap": false
+    }
+}

package/tsconfig.json

@@ -0,0 +1,31 @@
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "module": "commonjs",
+        "lib": [
+            "ES2020"
+        ],
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "moduleResolution": "node",
+        "allowSyntheticDefaultImports": true
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist",
+        "tests",
+        "example",
+        "dashboard"
+    ]
+}

package/tsconfig.types.json

@@ -0,0 +1,8 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "outDir": "./dist/types",
+        "declaration": true,
+        "emitDeclarationOnly": true
+    }
+}