observability-toolkit 1.8.5 → 2.1.0

package/dist/lib/observability/parse-stats.js

@@ -0,0 +1,207 @@
+/**
+ * Parse failure statistics tracking for JSONL files.
+ *
+ * Tracks parse success/failure/empty counts per file with LRU eviction.
+ * Used by streamJsonl() to provide visibility into malformed JSONL data.
+ *
+ * ## Features
+ * - Per-file tracking with success/failure/empty counters
+ * - LRU eviction when exceeding maxTrackedFiles (default: 100)
+ * - Aggregate statistics across all tracked files
+ * - Worst files identification by skip rate
+ *
+ * @example
+ * ```typescript
+ * const tracker = new ParseStatsTracker();
+ * tracker.recordSuccess('/path/to/file.jsonl');
+ * tracker.recordFailure('/path/to/file.jsonl');
+ * const stats = tracker.getAggregateStats();
+ * console.log(`Success rate: ${(stats.parseSuccessRate * 100).toFixed(1)}%`);
+ * ```
+ */
+import { createLogger } from '../core/logger.js';
+import { DEFAULT_QUERY_RESULT_LIMIT, WORST_FILES_LIMIT, } from '../core/constants.js';
+import { PERCENT_MULTIPLIER, } from '../core/units.js';
+const logger = createLogger('parse-stats');
+/** Default threshold for logging warnings about parse failures */
+const DEFAULT_WARN_THRESHOLD_SKIP_RATE = 0.1; // 10% skip rate
+/**
+ * Tracks JSONL parse statistics with LRU eviction.
+ *
+ * Uses Map insertion order for LRU behavior - oldest entries
+ * are evicted first when capacity is reached.
+ */
+export class ParseStatsTracker {
+    stats = new Map();
+    maxTrackedFiles;
+    warnThreshold;
+    /**
+     * Create a new ParseStatsTracker.
+     * @param maxTrackedFiles - Maximum files to track before LRU eviction (default: 100)
+     * @param warnThreshold - Skip rate threshold for warnings (0-1, default: 0.1 = 10%)
+     */
+    constructor(maxTrackedFiles = DEFAULT_QUERY_RESULT_LIMIT, warnThreshold = DEFAULT_WARN_THRESHOLD_SKIP_RATE) {
+        this.maxTrackedFiles = maxTrackedFiles;
+        this.warnThreshold = warnThreshold;
+    }
+    /**
+     * Get or create stats entry for a file, handling LRU eviction.
+     */
+    getOrCreateStats(filePath) {
+        let fileStats = this.stats.get(filePath);
+        if (fileStats) {
+            // Move to end for LRU (delete and re-add)
+            this.stats.delete(filePath);
+            this.stats.set(filePath, fileStats);
+            return fileStats;
+        }
+        // LRU eviction if at capacity
+        if (this.stats.size >= this.maxTrackedFiles) {
+            const firstKey = this.stats.keys().next().value;
+            if (firstKey !== undefined) {
+                this.stats.delete(firstKey);
+            }
+        }
+        // Create new stats entry
+        fileStats = {
+            filePath,
+            totalLines: 0,
+            parsedLines: 0,
+            skippedLines: 0,
+            emptyLines: 0,
+            lastUpdated: Date.now(),
+        };
+        this.stats.set(filePath, fileStats);
+        return fileStats;
+    }
+    /**
+     * Record a successful JSON parse for a file.
+     */
+    recordSuccess(filePath) {
+        const fileStats = this.getOrCreateStats(filePath);
+        fileStats.parsedLines++;
+        fileStats.totalLines++;
+        fileStats.lastUpdated = Date.now();
+    }
+    /**
+     * Record a failed JSON parse (malformed line) for a file.
+     */
+    recordFailure(filePath) {
+        const fileStats = this.getOrCreateStats(filePath);
+        fileStats.skippedLines++;
+        fileStats.totalLines++;
+        fileStats.lastUpdated = Date.now();
+    }
+    /**
+     * Record an empty line for a file.
+     */
+    recordEmpty(filePath) {
+        const fileStats = this.getOrCreateStats(filePath);
+        fileStats.emptyLines++;
+        fileStats.totalLines++;
+        fileStats.lastUpdated = Date.now();
+    }
+    /**
+     * Record a batch of parse results for a file.
+     * More efficient than individual calls when processing is complete.
+     */
+    recordBatch(filePath, parsed, skipped, empty) {
+        const fileStats = this.getOrCreateStats(filePath);
+        fileStats.parsedLines += parsed;
+        fileStats.skippedLines += skipped;
+        fileStats.emptyLines += empty;
+        fileStats.totalLines += parsed + skipped + empty;
+        fileStats.lastUpdated = Date.now();
+        // Log warning if skip rate exceeds threshold
+        const totalProcessed = fileStats.parsedLines + fileStats.skippedLines;
+        if (totalProcessed > 0) {
+            const skipRate = fileStats.skippedLines / totalProcessed;
+            if (skipRate >= this.warnThreshold && skipped > 0) {
+                logger.warn('High parse failure rate detected', {
+                    file: filePath,
+                    skipRate: Math.round(skipRate * PERCENT_MULTIPLIER),
+                    skippedLines: fileStats.skippedLines,
+                });
+            }
+        }
+    }
+    /**
+     * Get stats for a specific file.
+     */
+    getStats(filePath) {
+        return this.stats.get(filePath);
+    }
+    /**
+     * Get aggregate statistics across all tracked files.
+     */
+    getAggregateStats() {
+        let totalLines = 0;
+        let totalParsed = 0;
+        let totalSkipped = 0;
+        const allStats = [];
+        for (const fileStats of this.stats.values()) {
+            totalLines += fileStats.totalLines;
+            totalParsed += fileStats.parsedLines;
+            totalSkipped += fileStats.skippedLines;
+            allStats.push(fileStats);
+        }
+        // Calculate success rate (exclude empty lines from rate calculation)
+        const totalProcessed = totalParsed + totalSkipped;
+        const parseSuccessRate = totalProcessed > 0 ? totalParsed / totalProcessed : 1;
+        // Find worst files by skip rate
+        const worstFiles = allStats
+            .filter(s => s.parsedLines + s.skippedLines > 0) // Only files with actual data
+            .map(s => ({
+            ...s,
+            skipRate: s.skippedLines / (s.parsedLines + s.skippedLines),
+        }))
+            .sort((a, b) => b.skipRate - a.skipRate)
+            .slice(0, WORST_FILES_LIMIT)
+            .map(({ skipRate: _, ...s }) => s); // Remove internal skipRate field
+        return {
+            totalFiles: this.stats.size,
+            totalLines,
+            totalParsed,
+            totalSkipped,
+            parseSuccessRate,
+            worstFiles,
+        };
+    }
+    /**
+     * Reset all tracked statistics.
+     */
+    reset() {
+        this.stats.clear();
+    }
+    /**
+     * Get the number of files currently being tracked.
+     */
+    get trackedFileCount() {
+        return this.stats.size;
+    }
+}
+/**
+ * Global singleton tracker instance for use by backends.
+ * Backends can also create their own instances if isolation is needed.
+ */
+let globalTracker = null;
+/**
+ * Get the global ParseStatsTracker instance.
+ * Creates a new instance if none exists.
+ */
+export function getGlobalParseStatsTracker() {
+    if (!globalTracker) {
+        globalTracker = new ParseStatsTracker();
+    }
+    return globalTracker;
+}
+/**
+ * Reset the global tracker (useful for testing).
+ */
+export function resetGlobalParseStatsTracker() {
+    if (globalTracker) {
+        globalTracker.reset();
+    }
+    globalTracker = null;
+}
+//# sourceMappingURL=parse-stats.js.map

package/dist/lib/observability/parse-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-stats.js","sourceRoot":"","sources":["../../../src/lib/observability/parse-stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,0BAA0B,EACjC,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,MAAM,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;AAsC3C,kEAAkE;AAClE,MAAM,gCAAgC,GAAG,GAAG,CAAC,CAAC,gBAAgB;AAE9D;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IACpB,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;IACjC,eAAe,CAAS;IACxB,aAAa,CAAS;IAEvC;;;;OAIG;IACH,YAAY,eAAe,GAAG,0BAA0B,EAAE,aAAa,GAAG,gCAAgC;QACxG,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;IAED;;OAEG;IACK,gBAAgB,CAAC,QAAgB;QACvC,IAAI,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEzC,IAAI,SAAS,EAAE,CAAC;YACd,0CAA0C;YAC1C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC5B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YACpC,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,8BAA8B;QAC9B,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAChD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;QAED,yBAAyB;QACzB,SAAS,GAAG;YACV,QAAQ;YACR,UAAU,EAAE,CAAC;YACb,WAAW,EAAE,CAAC;YACd,YAAY,EAAE,CAAC;YACf,UAAU,EAAE,CAAC;YACb,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;SACxB,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QACpC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,QAAgB;QAC5B,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAClD,SAAS,CAAC,WAAW,EAAE,CAAC;QACxB,SAAS,CAAC,UAAU,EAAE,CAAC;QACvB,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,QAAgB;QAC5B,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAClD,SAAS,CAAC,YAAY,EAAE,CAAC;QACzB,SAAS,CAAC,UAAU,EAAE,CAAC;QACvB,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,QAAgB;QAC1B,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAClD,SAAS,CAAC,UAAU,EAAE,CAAC;QACvB,SAAS,CAAC,UAAU,EAAE,CAAC;QACvB,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,WAAW,CACT,QAAgB,EAChB,MAAc,EACd,OAAe,EACf,KAAa;QAEb,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAClD,SAAS,CAAC,WAAW,IAAI,MAAM,CAAC;QAChC,SAAS,CAAC,YAAY,IAAI,OAAO,CAAC;QAClC,SAAS,CAAC,UAAU,IAAI,KAAK,CAAC;QAC9B,SAAS,CAAC,UAAU,IAAI,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;QACjD,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEnC,6CAA6C;QAC7C,MAAM,cAAc,GAAG,SAAS,CAAC,WAAW,GAAG,SAAS,CAAC,YAAY,CAAC;QACtE,IAAI,cAAc,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,QAAQ,GAAG,SAAS,CAAC,YAAY,GAAG,cAAc,CAAC;YACzD,IAAI,QAAQ,IAAI,IAAI,CAAC,aAAa,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;gBAClD,MAAM,CAAC,IAAI,CAAC,kCAAkC,EAAE;oBAC9C,IAAI,EAAE,QAAQ;oBACd,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,kBAAkB,CAAC;oBACnD,YAAY,EAAE,SAAS,CAAC,YAAY;iBACrC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,QAAgB;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,iBAAiB;QACf,IAAI,UAAU,GAAG,CAAC,CAAC;QACnB,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,IAAI,YAAY,GAAG,CAAC,CAAC;QAErB,MAAM,QAAQ,GAAqB,EAAE,CAAC;QAEtC,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YAC5C,UAAU,IAAI,SAAS,CAAC,UAAU,CAAC;YACnC,WAAW,IAAI,SAAS,CAAC,WAAW,CAAC;YACrC,YAAY,IAAI,SAAS,CAAC,YAAY,CAAC;YACvC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC3B,CAAC;QAED,qEAAqE;QACrE,MAAM,cAAc,GAAG,WAAW,GAAG,YAAY,CAAC;QAClD,MAAM,gBAAgB,GAAG,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;QAE/E,gCAAgC;QAChC,MAAM,UAAU,GAAG,QAAQ;aACxB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,8BAA8B;aAC9E,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACT,GAAG,CAAC;YACJ,QAAQ,EAAE,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,YAAY,CAAC;SAC5D,CAAC,CAAC;aACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;aACvC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC;aAC3B,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,iCAAiC;QAEvE,OAAO;YACL,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YAC3B,UAAU;YACV,WAAW;YACX,YAAY;YACZ,gBAAgB;YAChB,UAAU;SACX,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,IAAI,gBAAgB;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF;AAED;;;GAGG;AACH,IAAI,aAAa,GAA6B,IAAI,CAAC;AAEnD;;;GAGG;AACH,MAAM,UAAU,0BAA0B;IACxC,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,aAAa,GAAG,IAAI,iBAAiB,EAAE,CAAC;IAC1C,CAAC;IACD,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,4BAA4B;IAC1C,IAAI,aAAa,EAAE,CAAC;QAClB,aAAa,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;IACD,aAAa,GAAG,IAAI,CAAC;AACvB,CAAC"}

package/dist/lib/observability/parse-stats.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for ParseStatsTracker
+ */
+export {};
+//# sourceMappingURL=parse-stats.test.d.ts.map

package/dist/lib/observability/parse-stats.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-stats.test.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/parse-stats.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/lib/observability/parse-stats.test.js

@@ -0,0 +1,287 @@
+/**
+ * Tests for ParseStatsTracker
+ */
+import { describe, it, beforeEach } from 'vitest';
+import * as assert from 'node:assert';
+import { DEFAULT_LIMIT_10, PROBABILITY_EIGHTY_FIVE_PERCENT, PROBABILITY_NINETY_PERCENT, SAMPLE_SIZE_100, COUNT_FIFTEEN, COUNT_FIFTY, COUNT_FIVE, COUNT_FOUR, COUNT_NINE, COUNT_NINETY, COUNT_THREE, COUNT_TWENTY, COUNT_TWO, } from '../../test-helpers/test-constants.js';
+import { ParseStatsTracker, getGlobalParseStatsTracker, resetGlobalParseStatsTracker, } from './parse-stats.js';
+const ONE_SKIPPED_LINE = 1;
+const HIGH_VOLUME_PARSED_LINES = SAMPLE_SIZE_100 * SAMPLE_SIZE_100 - ONE_SKIPPED_LINE;
+const HIGH_VOLUME_TOTAL_PROCESSED = HIGH_VOLUME_PARSED_LINES + ONE_SKIPPED_LINE;
+describe('ParseStatsTracker', () => {
+    let tracker;
+    beforeEach(() => {
+        tracker = new ParseStatsTracker();
+    });
+    describe('single file tracking', () => {
+        it('tracks successful parses', () => {
+            tracker.recordSuccess('/path/to/file.jsonl');
+            tracker.recordSuccess('/path/to/file.jsonl');
+            tracker.recordSuccess('/path/to/file.jsonl');
+            const stats = tracker.getStats('/path/to/file.jsonl');
+            assert.ok(stats);
+            assert.strictEqual(stats.parsedLines, COUNT_THREE);
+            assert.strictEqual(stats.skippedLines, 0);
+            assert.strictEqual(stats.emptyLines, 0);
+            assert.strictEqual(stats.totalLines, COUNT_THREE);
+        });
+        it('tracks failed parses', () => {
+            tracker.recordFailure('/path/to/file.jsonl');
+            tracker.recordFailure('/path/to/file.jsonl');
+            const stats = tracker.getStats('/path/to/file.jsonl');
+            assert.ok(stats);
+            assert.strictEqual(stats.parsedLines, 0);
+            assert.strictEqual(stats.skippedLines, COUNT_TWO);
+            assert.strictEqual(stats.totalLines, COUNT_TWO);
+        });
+        it('tracks empty lines separately', () => {
+            tracker.recordEmpty('/path/to/file.jsonl');
+            tracker.recordEmpty('/path/to/file.jsonl');
+            tracker.recordSuccess('/path/to/file.jsonl');
+            const stats = tracker.getStats('/path/to/file.jsonl');
+            assert.ok(stats);
+            assert.strictEqual(stats.emptyLines, COUNT_TWO);
+            assert.strictEqual(stats.parsedLines, 1);
+            assert.strictEqual(stats.totalLines, COUNT_THREE);
+        });
+        it('tracks mixed operations correctly', () => {
+            tracker.recordSuccess('/path/to/file.jsonl');
+            tracker.recordSuccess('/path/to/file.jsonl');
+            tracker.recordFailure('/path/to/file.jsonl');
+            tracker.recordEmpty('/path/to/file.jsonl');
+            const stats = tracker.getStats('/path/to/file.jsonl');
+            assert.ok(stats);
+            assert.strictEqual(stats.parsedLines, COUNT_TWO);
+            assert.strictEqual(stats.skippedLines, 1);
+            assert.strictEqual(stats.emptyLines, 1);
+            assert.strictEqual(stats.totalLines, COUNT_FOUR);
+        });
+        it('updates lastUpdated timestamp', async () => {
+            tracker.recordSuccess('/path/to/file.jsonl');
+            const stats1 = tracker.getStats('/path/to/file.jsonl');
+            const time1 = stats1?.lastUpdated;
+            await new Promise(resolve => setTimeout(resolve, DEFAULT_LIMIT_10));
+            tracker.recordSuccess('/path/to/file.jsonl');
+            const stats2 = tracker.getStats('/path/to/file.jsonl');
+            assert.ok(time1);
+            assert.ok(stats2?.lastUpdated);
+            assert.ok(stats2.lastUpdated >= time1);
+        });
+    });
+    describe('multiple files independently', () => {
+        it('tracks multiple files separately', () => {
+            tracker.recordSuccess('/file1.jsonl');
+            tracker.recordSuccess('/file1.jsonl');
+            tracker.recordFailure('/file2.jsonl');
+            tracker.recordFailure('/file2.jsonl');
+            tracker.recordFailure('/file2.jsonl');
+            const stats1 = tracker.getStats('/file1.jsonl');
+            const stats2 = tracker.getStats('/file2.jsonl');
+            assert.ok(stats1);
+            assert.strictEqual(stats1.parsedLines, COUNT_TWO);
+            assert.strictEqual(stats1.skippedLines, 0);
+            assert.ok(stats2);
+            assert.strictEqual(stats2.parsedLines, 0);
+            assert.strictEqual(stats2.skippedLines, COUNT_THREE);
+        });
+        it('returns undefined for untracked files', () => {
+            tracker.recordSuccess('/tracked.jsonl');
+            const stats = tracker.getStats('/untracked.jsonl');
+            assert.strictEqual(stats, undefined);
+        });
+    });
+    describe('batch recording', () => {
+        it('records batch stats correctly', () => {
+            tracker.recordBatch('/file.jsonl', DEFAULT_LIMIT_10, COUNT_TWO, COUNT_THREE);
+            const stats = tracker.getStats('/file.jsonl');
+            assert.ok(stats);
+            assert.strictEqual(stats.parsedLines, DEFAULT_LIMIT_10);
+            assert.strictEqual(stats.skippedLines, COUNT_TWO);
+            assert.strictEqual(stats.emptyLines, COUNT_THREE);
+            assert.strictEqual(stats.totalLines, COUNT_FIFTEEN);
+        });
+        it('accumulates multiple batches', () => {
+            tracker.recordBatch('/file.jsonl', COUNT_FIVE, 1, 0);
+            tracker.recordBatch('/file.jsonl', DEFAULT_LIMIT_10, COUNT_TWO, 1);
+            const stats = tracker.getStats('/file.jsonl');
+            assert.ok(stats);
+            assert.strictEqual(stats.parsedLines, COUNT_FIFTEEN);
+            assert.strictEqual(stats.skippedLines, COUNT_THREE);
+            assert.strictEqual(stats.emptyLines, 1);
+            assert.strictEqual(stats.totalLines, DEFAULT_LIMIT_10 + COUNT_NINE);
+        });
+    });
+    describe('aggregate stats calculation', () => {
+        it('calculates totals across files', () => {
+            tracker.recordBatch('/file1.jsonl', SAMPLE_SIZE_100, DEFAULT_LIMIT_10, COUNT_FIVE);
+            tracker.recordBatch('/file2.jsonl', COUNT_FIFTY, COUNT_FIVE, COUNT_TWO);
+            const agg = tracker.getAggregateStats();
+            assert.strictEqual(agg.totalFiles, COUNT_TWO);
+            assert.strictEqual(agg.totalLines, SAMPLE_SIZE_100 + DEFAULT_LIMIT_10 + COUNT_FIVE + COUNT_FIFTY + COUNT_FIVE + COUNT_TWO);
+            assert.strictEqual(agg.totalParsed, SAMPLE_SIZE_100 + COUNT_FIFTY);
+            assert.strictEqual(agg.totalSkipped, COUNT_FIFTEEN);
+        });
+        it('calculates success rate correctly', () => {
+            tracker.recordBatch('/file1.jsonl', COUNT_NINETY, DEFAULT_LIMIT_10, 0); // 90% success
+            tracker.recordBatch('/file2.jsonl', SAMPLE_SIZE_100 - COUNT_TWENTY, COUNT_TWENTY, 0); // 80% success
+            const agg = tracker.getAggregateStats();
+            // Overall: 170 parsed, 30 skipped = 170/200 = 0.85
+            assert.strictEqual(agg.parseSuccessRate, PROBABILITY_EIGHTY_FIVE_PERCENT);
+        });
+        it('returns 1.0 success rate when no data', () => {
+            const agg = tracker.getAggregateStats();
+            assert.strictEqual(agg.parseSuccessRate, 1);
+            assert.strictEqual(agg.totalFiles, 0);
+        });
+        it('excludes empty lines from success rate calculation', () => {
+            tracker.recordBatch('/file.jsonl', COUNT_NINETY, DEFAULT_LIMIT_10, SAMPLE_SIZE_100); // 100 empty lines
+            const agg = tracker.getAggregateStats();
+            // Success rate based only on parsed vs skipped (not empty)
+            // 90 parsed / (90 + 10) = 0.9
+            assert.strictEqual(agg.parseSuccessRate, PROBABILITY_NINETY_PERCENT);
+        });
+    });
+    describe('worst files sorted by skip rate', () => {
+        it('returns worst files sorted by skip rate descending', () => {
+            tracker.recordBatch('/good.jsonl', SAMPLE_SIZE_100, COUNT_FIVE, 0); // 5% skip
+            tracker.recordBatch('/bad.jsonl', COUNT_FIFTY, COUNT_FIFTY, 0); // 50% skip
+            tracker.recordBatch('/worst.jsonl', DEFAULT_LIMIT_10, COUNT_NINETY, 0); // 90% skip
+            tracker.recordBatch('/okay.jsonl', SAMPLE_SIZE_100 - COUNT_TWENTY, COUNT_TWENTY, 0); // 20% skip
+            const agg = tracker.getAggregateStats();
+            assert.strictEqual(agg.worstFiles.length, COUNT_FOUR);
+            assert.strictEqual(agg.worstFiles[0].filePath, '/worst.jsonl');
+            assert.strictEqual(agg.worstFiles[1].filePath, '/bad.jsonl');
+            assert.strictEqual(agg.worstFiles[2].filePath, '/okay.jsonl');
+            assert.strictEqual(agg.worstFiles[3].filePath, '/good.jsonl');
+        });
+        it('limits worst files to top 5', () => {
+            for (let i = 0; i < DEFAULT_LIMIT_10; i++) {
+                tracker.recordBatch(`/file${i}.jsonl`, SAMPLE_SIZE_100 - i * DEFAULT_LIMIT_10, i * DEFAULT_LIMIT_10, 0);
+            }
+            const agg = tracker.getAggregateStats();
+            assert.strictEqual(agg.worstFiles.length, COUNT_FIVE);
+        });
+        it('excludes files with no actual data from worst files', () => {
+            tracker.recordBatch('/empty.jsonl', 0, 0, SAMPLE_SIZE_100); // Only empty lines
+            tracker.recordBatch('/real.jsonl', COUNT_FIFTY, DEFAULT_LIMIT_10, 0);
+            const agg = tracker.getAggregateStats();
+            assert.strictEqual(agg.worstFiles.length, 1);
+            assert.strictEqual(agg.worstFiles[0].filePath, '/real.jsonl');
+        });
+    });
+    describe('LRU eviction at 100 files', () => {
+        it('evicts oldest files when exceeding max', () => {
+            const smallTracker = new ParseStatsTracker(COUNT_FIVE); // Max 5 files
+            // Add 5 files
+            for (let i = 0; i < COUNT_FIVE; i++) {
+                smallTracker.recordSuccess(`/file${i}.jsonl`);
+            }
+            assert.strictEqual(smallTracker.trackedFileCount, COUNT_FIVE);
+            // Add 6th file - should evict file0
+            smallTracker.recordSuccess('/file5.jsonl');
+            assert.strictEqual(smallTracker.trackedFileCount, COUNT_FIVE);
+            assert.strictEqual(smallTracker.getStats('/file0.jsonl'), undefined);
+            assert.ok(smallTracker.getStats('/file5.jsonl'));
+        });
+        it('maintains LRU order on access', () => {
+            const smallTracker = new ParseStatsTracker(COUNT_THREE);
+            // Add 3 files in order
+            smallTracker.recordSuccess('/a.jsonl');
+            smallTracker.recordSuccess('/b.jsonl');
+            smallTracker.recordSuccess('/c.jsonl');
+            // Access /a.jsonl to make it most recently used
+            smallTracker.recordSuccess('/a.jsonl');
+            // Add new file - should evict /b.jsonl (oldest)
+            smallTracker.recordSuccess('/d.jsonl');
+            assert.strictEqual(smallTracker.getStats('/b.jsonl'), undefined);
+            assert.ok(smallTracker.getStats('/a.jsonl'));
+            assert.ok(smallTracker.getStats('/c.jsonl'));
+            assert.ok(smallTracker.getStats('/d.jsonl'));
+        });
+        it('defaults to 100 max files', () => {
+            // Add 101 files
+            for (let i = 0; i < SAMPLE_SIZE_100 + ONE_SKIPPED_LINE; i++) {
+                tracker.recordSuccess(`/file${i}.jsonl`);
+            }
+            assert.strictEqual(tracker.trackedFileCount, SAMPLE_SIZE_100);
+            // file0 should be evicted
+            assert.strictEqual(tracker.getStats('/file0.jsonl'), undefined);
+            // file100 should exist
+            assert.ok(tracker.getStats('/file100.jsonl'));
+        });
+    });
+    describe('reset clears all stats', () => {
+        it('clears all tracked files', () => {
+            tracker.recordSuccess('/file1.jsonl');
+            tracker.recordSuccess('/file2.jsonl');
+            tracker.recordFailure('/file3.jsonl');
+            assert.strictEqual(tracker.trackedFileCount, COUNT_THREE);
+            tracker.reset();
+            assert.strictEqual(tracker.trackedFileCount, 0);
+            assert.strictEqual(tracker.getStats('/file1.jsonl'), undefined);
+            assert.strictEqual(tracker.getStats('/file2.jsonl'), undefined);
+            assert.strictEqual(tracker.getStats('/file3.jsonl'), undefined);
+        });
+        it('returns clean aggregate stats after reset', () => {
+            tracker.recordBatch('/file.jsonl', SAMPLE_SIZE_100, DEFAULT_LIMIT_10, COUNT_FIVE);
+            tracker.reset();
+            const agg = tracker.getAggregateStats();
+            assert.strictEqual(agg.totalFiles, 0);
+            assert.strictEqual(agg.totalLines, 0);
+            assert.strictEqual(agg.totalParsed, 0);
+            assert.strictEqual(agg.totalSkipped, 0);
+            assert.strictEqual(agg.parseSuccessRate, 1);
+            assert.strictEqual(agg.worstFiles.length, 0);
+        });
+    });
+    describe('success rate calculation accuracy', () => {
+        it('handles edge case of all failures', () => {
+            tracker.recordBatch('/file.jsonl', 0, SAMPLE_SIZE_100, 0);
+            const agg = tracker.getAggregateStats();
+            assert.strictEqual(agg.parseSuccessRate, 0);
+        });
+        it('handles edge case of all successes', () => {
+            tracker.recordBatch('/file.jsonl', SAMPLE_SIZE_100, 0, 0);
+            const agg = tracker.getAggregateStats();
+            assert.strictEqual(agg.parseSuccessRate, 1);
+        });
+        it('handles very small skip rates accurately', () => {
+            tracker.recordBatch('/file.jsonl', HIGH_VOLUME_PARSED_LINES, ONE_SKIPPED_LINE, 0);
+            const agg = tracker.getAggregateStats();
+            assert.strictEqual(agg.parseSuccessRate, HIGH_VOLUME_PARSED_LINES / HIGH_VOLUME_TOTAL_PROCESSED);
+        });
+    });
+    describe('global tracker singleton', () => {
+        beforeEach(() => {
+            resetGlobalParseStatsTracker();
+        });
+        it('returns same instance on multiple calls', () => {
+            const tracker1 = getGlobalParseStatsTracker();
+            const tracker2 = getGlobalParseStatsTracker();
+            assert.strictEqual(tracker1, tracker2);
+        });
+        it('reset creates new instance', () => {
+            const tracker1 = getGlobalParseStatsTracker();
+            tracker1.recordSuccess('/file.jsonl');
+            resetGlobalParseStatsTracker();
+            const tracker2 = getGlobalParseStatsTracker();
+            assert.notStrictEqual(tracker1, tracker2);
+            assert.strictEqual(tracker2.trackedFileCount, 0);
+        });
+    });
+    describe('file path edge cases', () => {
+        it('handles paths with special characters', () => {
+            const specialPath = '/path/with spaces/and-dashes/file.jsonl';
+            tracker.recordSuccess(specialPath);
+            const stats = tracker.getStats(specialPath);
+            assert.ok(stats);
+            assert.strictEqual(stats.filePath, specialPath);
+        });
+        it('treats different paths as different files', () => {
+            tracker.recordSuccess('/dir1/file.jsonl');
+            tracker.recordSuccess('/dir2/file.jsonl');
+            assert.strictEqual(tracker.trackedFileCount, COUNT_TWO);
+        });
+    });
+});
+//# sourceMappingURL=parse-stats.test.js.map

package/dist/lib/observability/parse-stats.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-stats.test.js","sourceRoot":"","sources":["../../../src/lib/observability/parse-stats.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/observability/render-trace-tree.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ASCII trace tree rendering using archy.
+ * Groups spans by session.id attribute, sorts by startTime, renders each session as a tree.
+ *
+ * OTEL3 — ref: docs/BACKLOG.md
+ */
+/** Minimal span shape accepted by the renderer — compatible with ExportedSpan from hooks/lib/otel.ts */
+export interface RenderableSpan {
+    name: string;
+    startTime?: [number, number];
+    endTime?: [number, number];
+    duration?: [number, number];
+    status?: {
+        code: number;
+        message?: string;
+    };
+    attributes?: Record<string, unknown>;
+}
+export interface RenderTraceTreeOptions {
+    /** Enable ANSI color codes (default: true) */
+    color?: boolean;
+}
+/**
+ * Render a flat array of spans as ASCII trees, grouped by session.id.
+ *
+ * @param spans - Array of spans from JSONL telemetry (ExportedSpan-compatible)
+ * @param options - Rendering options
+ * @returns ASCII tree string (archy output); caller decides whether to print or pipe
+ */
+export declare function renderTraceTree(spans: RenderableSpan[], options?: RenderTraceTreeOptions): string;
+//# sourceMappingURL=render-trace-tree.d.ts.map

package/dist/lib/observability/render-trace-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-trace-tree.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/render-trace-tree.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,wGAAwG;AACxG,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAwDD,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAsCrG"}