@kb-labs/adapters 0.5.0

package/packages/adapters-analytics-file/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@kb-labs/adapters-analytics-file",
+  "version": "0.5.0",
+  "type": "module",
+  "description": "File-based analytics adapter for KB Labs platform (writes JSONL to .kb/analytics/buffer)",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "lint": "eslint src --ext .ts,.tsx,.js,.jsx",
+    "lint:fix": "eslint . --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest --passWithNoTests"
+  },
+  "dependencies": {
+    "@kb-labs/core-platform": "link:../../../../platform/kb-labs-core/packages/core-platform",
+    "fs-extra": "^11.0.0",
+    "date-fns": "^3.6.0"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "@types/node": "^24.3.3",
+    "@types/fs-extra": "^11.0.0",
+    "eslint": "^9",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "packageManager": "pnpm@9.11.0"
+}

package/packages/adapters-analytics-file/src/__tests__/daily-stats.spec.ts

@@ -0,0 +1,287 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createAdapter } from "../index";
+import fs from "fs-extra";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import type {
+  IAnalytics,
+} from "@kb-labs/core-platform/adapters";
+
+const TEST_BASE_DIR = join(__dirname, `test-analytics-${randomUUID()}`);
+
+describe("FileAnalytics - getDailyStats", () => {
+  let analytics: IAnalytics;
+
+  beforeEach(async () => {
+    analytics = createAdapter({ baseDir: TEST_BASE_DIR });
+    await fs.ensureDir(TEST_BASE_DIR);
+  });
+
+  afterEach(async () => {
+    await fs.remove(TEST_BASE_DIR);
+  });
+
+  describe("LLM events", () => {
+    it("should aggregate LLM events by day with correct metrics", async () => {
+      // Track events across 3 days
+      await analytics.track("llm.completion.completed", {
+        model: "gpt-4",
+        totalTokens: 1000,
+        cost: 0.05,
+        durationMs: 1500,
+      });
+
+      await analytics.track("llm.completion.completed", {
+        model: "gpt-4",
+        totalTokens: 1500,
+        cost: 0.07,
+        durationMs: 2000,
+      });
+
+      // Get stats
+      const stats = await analytics.getDailyStats?.({
+        type: "llm.completion.completed",
+      });
+
+      expect(stats).toHaveLength(1);
+      expect(stats![0]!.count).toBe(2);
+      expect(stats![0]!.metrics?.totalTokens).toBe(2500);
+      expect(stats![0]!.metrics?.totalCost).toBeCloseTo(0.12, 2);
+      expect(stats![0]!.metrics?.avgDurationMs).toBe(1750);
+      expect(stats![0]!.date).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+    });
+
+    it("should filter by date range", async () => {
+      // Use local date (adapter writes files with local date, not UTC)
+      const d = new Date();
+      const today = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+
+      // Track an event
+      await analytics.track("llm.completion.completed", {
+        model: "gpt-4",
+        totalTokens: 1000,
+        cost: 0.05,
+        durationMs: 1500,
+      });
+
+      const yesterday = new Date(Date.now() - 86400000)
+        .toISOString()
+        .split("T")[0];
+      const tomorrow = new Date(Date.now() + 86400000)
+        .toISOString()
+        .split("T")[0];
+
+      // Query for future dates (should be empty)
+      const futureStats = await analytics.getDailyStats?.({
+        type: "llm.completion.completed",
+        from: `${tomorrow}T00:00:00Z`,
+        to: `${tomorrow}T23:59:59Z`,
+      });
+
+      expect(futureStats).toHaveLength(0);
+
+      // Query for today (should have data)
+      const todayStats = await analytics.getDailyStats?.({
+        type: "llm.completion.completed",
+        from: `${yesterday}T00:00:00Z`,
+        to: `${tomorrow}T23:59:59Z`,
+      });
+
+      expect(todayStats).toHaveLength(1);
+      expect(todayStats![0]!.date).toBe(today);
+    });
+
+    it("should return empty array when no events match", async () => {
+      const stats = await analytics.getDailyStats?.({
+        type: "llm.completion.completed",
+      });
+
+      expect(stats).toEqual([]);
+    });
+  });
+
+  describe("Embeddings events", () => {
+    it("should aggregate embeddings events with correct metrics", async () => {
+      await analytics.track("embeddings.generate.completed", {
+        model: "text-embedding-ada-002",
+        tokens: 500,
+        cost: 0.001,
+        durationMs: 200,
+      });
+
+      await analytics.track("embeddings.generate.completed", {
+        model: "text-embedding-ada-002",
+        tokens: 700,
+        cost: 0.0015,
+        durationMs: 250,
+      });
+
+      const stats = await analytics.getDailyStats?.({
+        type: "embeddings.generate.completed",
+      });
+
+      expect(stats).toHaveLength(1);
+      expect(stats![0]!).toMatchObject({
+        count: 2,
+        metrics: {
+          totalTokens: 1200,
+          totalCost: 0.0025,
+          avgDurationMs: 225,
+        },
+      });
+    });
+  });
+
+  describe("VectorStore events", () => {
+    it("should count operations correctly", async () => {
+      await analytics.track("vectorstore.search.completed", {
+        durationMs: 50,
+        resultsCount: 5,
+      });
+
+      await analytics.track("vectorstore.search.completed", {
+        durationMs: 60,
+        resultsCount: 3,
+      });
+
+      await analytics.track("vectorstore.upsert.completed", {
+        durationMs: 100,
+        vectorCount: 10,
+      });
+
+      await analytics.track("vectorstore.delete.completed", {
+        durationMs: 30,
+      });
+
+      const stats = await analytics.getDailyStats?.({
+        type: [
+          "vectorstore.search.completed",
+          "vectorstore.upsert.completed",
+          "vectorstore.delete.completed",
+        ],
+      });
+
+      expect(stats).toHaveLength(1);
+      expect(stats![0]!.count).toBe(4);
+      expect(stats![0]!.metrics).toMatchObject({
+        totalSearches: 2,
+        totalUpserts: 1,
+        totalDeletes: 1,
+        avgDurationMs: 60, // (50 + 60 + 100 + 30) / 4
+      });
+    });
+  });
+
+  describe("Cache events", () => {
+    it("should calculate hit rate correctly", async () => {
+      // 3 hits, 2 misses, 1 set
+      await analytics.track("cache.hit", { durationMs: 1 });
+      await analytics.track("cache.hit", { durationMs: 1 });
+      await analytics.track("cache.hit", { durationMs: 2 });
+      await analytics.track("cache.miss", { durationMs: 1 });
+      await analytics.track("cache.miss", { durationMs: 1 });
+      await analytics.track("cache.set", { durationMs: 5 });
+
+      const stats = await analytics.getDailyStats?.({
+        type: ["cache.hit", "cache.miss", "cache.set"],
+      });
+
+      expect(stats).toHaveLength(1);
+      expect(stats![0]!.count).toBe(6);
+      expect(stats![0]!.metrics).toMatchObject({
+        totalHits: 3,
+        totalMisses: 2,
+        totalSets: 1,
+        hitRate: 60, // 3/(3+2) * 100 = 60%
+      });
+    });
+
+    it("should handle zero gets gracefully", async () => {
+      await analytics.track("cache.set", { durationMs: 5 });
+
+      const stats = await analytics.getDailyStats?.({
+        type: ["cache.hit", "cache.miss", "cache.set"],
+      });
+
+      expect(stats).toHaveLength(1);
+      expect(stats![0]!.metrics?.hitRate).toBe(0);
+    });
+  });
+
+  describe("Storage events", () => {
+    it("should aggregate bytes read and written", async () => {
+      await analytics.track("storage.read.completed", {
+        durationMs: 10,
+        bytesRead: 1024,
+      });
+
+      await analytics.track("storage.read.completed", {
+        durationMs: 15,
+        bytesRead: 2048,
+      });
+
+      await analytics.track("storage.write.completed", {
+        durationMs: 20,
+        bytesWritten: 512,
+      });
+
+      await analytics.track("storage.delete.completed", {
+        durationMs: 5,
+      });
+
+      const stats = await analytics.getDailyStats?.({
+        type: [
+          "storage.read.completed",
+          "storage.write.completed",
+          "storage.delete.completed",
+        ],
+      });
+
+      expect(stats).toHaveLength(1);
+      expect(stats![0]!.count).toBe(4);
+      expect(stats![0]!.metrics).toMatchObject({
+        totalBytesRead: 3072,
+        totalBytesWritten: 512,
+        avgDurationMs: 12.5, // (10 + 15 + 20 + 5) / 4
+      });
+    });
+  });
+
+  describe("Sorting", () => {
+    it("should sort results by date ascending", async () => {
+      // Note: We can't easily test multi-day sorting in a unit test
+      // since events are timestamped with the current time.
+      // This would require mocking Date or using a more sophisticated approach.
+      // For now, we just verify that single-day results are returned correctly.
+
+      await analytics.track("llm.completion.completed", {
+        totalTokens: 100,
+        cost: 0.01,
+        durationMs: 100,
+      });
+
+      const stats = await analytics.getDailyStats?.({
+        type: "llm.completion.completed",
+      });
+
+      expect(stats).toHaveLength(1);
+      expect(stats![0]!.date).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+    });
+  });
+
+  describe("Empty metrics", () => {
+    it("should not include metrics object for unknown event types", async () => {
+      await analytics.track("custom.event", {
+        someData: "value",
+      });
+
+      const stats = await analytics.getDailyStats?.({
+        type: "custom.event",
+      });
+
+      expect(stats).toHaveLength(1);
+      expect(stats![0]!.count).toBe(1);
+      expect(stats![0]!.metrics).toBeUndefined();
+    });
+  });
+});

package/packages/adapters-analytics-file/src/__tests__/scoped-analytics.test.ts

@@ -0,0 +1,233 @@
+/**
+ * @module @kb-labs/adapters-analytics-file/__tests__/scoped-analytics
+ * Tests for analytics source attribution and scoping
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { join } from "node:path";
+import { mkdtemp, rm, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { createAdapter } from "../index.js";
+import type {
+  IAnalytics,
+  AnalyticsContext,
+} from "@kb-labs/core-platform/adapters";
+
+/** Local date stamp for event file names. Adapter uses local date, not UTC. */
+function todayStamp(): string {
+  const d = new Date();
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}${m}${day}`;
+}
+
+function eventFile(dir: string, stamp: string): string {
+  return join(dir, `events-${stamp}.jsonl`);
+}
+
+describe("Analytics Source Attribution", () => {
+  let testDir: string;
+  let analytics: IAnalytics;
+
+  beforeEach(async () => {
+    // Create temporary directory for test events
+    testDir = await mkdtemp(join(tmpdir(), "analytics-test-"));
+  });
+
+  afterEach(async () => {
+    // Clean up test directory
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  describe("Default behavior (current implementation)", () => {
+    it("should use source from AnalyticsContext", async () => {
+      // Create analytics with explicit context (simulating root package.json)
+      const context: AnalyticsContext = {
+        source: {
+          product: "@kb-labs/ai-review",
+          version: "1.0.0",
+        },
+        runId: "test-run-123",
+      };
+
+      analytics = createAdapter({ baseDir: testDir, analytics: context });
+      const stamp = todayStamp();
+      await analytics.track("test.event", { foo: "bar" });
+
+      const files = await readFile(eventFile(testDir, stamp), "utf-8");
+      const event = JSON.parse(files.trim());
+
+      expect(event.source).toEqual({
+        product: "@kb-labs/ai-review",
+        version: "1.0.0",
+      });
+    });
+
+    it("should use default source if no context provided", async () => {
+      analytics = createAdapter({ baseDir: testDir });
+      const stamp = todayStamp();
+      await analytics.track("test.event", { foo: "bar" });
+
+      const files = await readFile(eventFile(testDir, stamp), "utf-8");
+      const event = JSON.parse(files.trim());
+
+      expect(event.source).toEqual({
+        product: "unknown",
+        version: "0.0.0",
+      });
+    });
+  });
+
+  describe("Multiple plugins tracking events", () => {
+    it("should track events from different plugins with same analytics instance", async () => {
+      // This test demonstrates the CURRENT PROBLEM:
+      // All events show the same source, even if they come from different plugins
+
+      const rootContext: AnalyticsContext = {
+        source: {
+          product: "@kb-labs/ai-review", // Root package.json
+          version: "1.0.0",
+        },
+        runId: "test-run-123",
+      };
+
+      analytics = createAdapter({ baseDir: testDir, analytics: rootContext });
+      const stamp = todayStamp();
+
+      await analytics.track("mind.rag-index.started", { scope: "default" });
+      await analytics.track("workflow.run.started", { workflowId: "test-workflow" });
+      await analytics.track("commit.generated", { commits: 2 });
+
+      const files = await readFile(eventFile(testDir, stamp), "utf-8");
+      const events = files
+        .trim()
+        .split("\n")
+        .map((line) => JSON.parse(line));
+
+      expect(events).toHaveLength(3);
+
+      // CURRENT BEHAVIOR: All events show same source (ROOT)
+      // This is the problem we're trying to fix!
+      expect(events[0].source.product).toBe("@kb-labs/ai-review");
+      expect(events[1].source.product).toBe("@kb-labs/ai-review");
+      expect(events[2].source.product).toBe("@kb-labs/ai-review");
+
+      // DESIRED BEHAVIOR (after fix):
+      // expect(events[0].source.product).toBe('@kb-labs/mind');
+      // expect(events[1].source.product).toBe('@kb-labs/workflow');
+      // expect(events[2].source.product).toBe('@kb-labs/commit');
+    });
+  });
+
+  describe("Event schema validation", () => {
+    it("should create events with kb.v1 schema", async () => {
+      const context: AnalyticsContext = {
+        source: { product: "test-product", version: "1.0.0" },
+        runId: "test-run-123",
+        actor: { type: "user", id: "test@example.com", name: "Test User" },
+        ctx: { workspace: "/test/workspace", branch: "main" },
+      };
+
+      analytics = createAdapter({ baseDir: testDir, analytics: context });
+      const stamp = todayStamp();
+      await analytics.track("test.event", { data: "test" });
+
+      const files = await readFile(eventFile(testDir, stamp), "utf-8");
+      const event = JSON.parse(files.trim());
+
+      // Validate kb.v1 schema
+      expect(event).toMatchObject({
+        schema: "kb.v1",
+        type: "test.event",
+        source: { product: "test-product", version: "1.0.0" },
+        runId: "test-run-123",
+        actor: { type: "user", id: "test@example.com", name: "Test User" },
+        ctx: { workspace: "/test/workspace", branch: "main" },
+        payload: { data: "test" },
+      });
+
+      // Verify auto-generated fields
+      expect(event.id).toBeDefined();
+      expect(event.ts).toBeDefined();
+      expect(event.ingestTs).toBeDefined();
+    });
+  });
+
+  describe("getEvents filtering by source", () => {
+    it("should filter events by source.product", async () => {
+      const context: AnalyticsContext = {
+        source: { product: "@kb-labs/mind", version: "0.1.0" },
+        runId: "test-run-123",
+      };
+
+      analytics = createAdapter({ baseDir: testDir, analytics: context });
+
+      await analytics.track("mind.event1", {});
+      await analytics.track("mind.event2", {});
+      await analytics.track("mind.event3", {});
+
+      // Filter by source
+      const result = await analytics.getEvents!({ source: "@kb-labs/mind" });
+
+      expect(result.total).toBe(3);
+      expect(result.events).toHaveLength(3);
+      expect(
+        result.events.every((e) => e.source.product === "@kb-labs/mind"),
+      ).toBe(true);
+    });
+
+    it("should return empty when filtering for non-existent source", async () => {
+      const context: AnalyticsContext = {
+        source: { product: "@kb-labs/mind", version: "0.1.0" },
+        runId: "test-run-123",
+      };
+
+      analytics = createAdapter({ baseDir: testDir, analytics: context });
+      await analytics.track("mind.event", {});
+
+      // Filter for different source
+      const result = await analytics.getEvents!({
+        source: "@kb-labs/workflow",
+      });
+
+      expect(result.total).toBe(0);
+      expect(result.events).toHaveLength(0);
+    });
+  });
+
+  describe("getStats aggregation by source", () => {
+    it("should aggregate events by source", async () => {
+      // Create multiple analytics instances with different sources
+      const mindAnalytics = createAdapter(
+        { baseDir: testDir },
+        {
+          source: { product: "@kb-labs/mind", version: "0.1.0" },
+          runId: "run-1",
+        },
+      );
+
+      const workflowAnalytics = createAdapter(
+        { baseDir: testDir },
+        {
+          source: { product: "@kb-labs/workflow", version: "2.0.0" },
+          runId: "run-2",
+        },
+      );
+
+      // Track events from different sources
+      await mindAnalytics.track("mind.event1", {});
+      await mindAnalytics.track("mind.event2", {});
+      await workflowAnalytics.track("workflow.event1", {});
+
+      // Get stats (reads all events from directory)
+      const stats = await mindAnalytics.getStats!();
+
+      expect(stats.totalEvents).toBe(3);
+      expect(stats.bySource).toEqual({
+        "@kb-labs/mind": 2,
+        "@kb-labs/workflow": 1,
+      });
+    });
+  });
+});