tlc-claude-code 1.8.5 → 2.0.1

package/server/lib/context-injection.test.js

@@ -0,0 +1,340 @@
+/**
+ * Context Injection Tests
+ * Tests for integrating semantic recall into context building.
+ *
+ * Task 7 (Phase 71): Enhanced Context Injection
+ *   - buildSemanticContext() calls recallForContext when vectorStore provided
+ *   - Falls back to empty conversations when no vectorStore
+ *   - New SEMANTIC_WEIGHTS with VECTOR_SIMILARITY: 0.35
+ *   - Conversation chunks included in semantic context output
+ *   - formatContextForInjection() produces "Related Conversations" section
+ *   - Backward compatible: no vector store = same format as before
+ */
+
+import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
+import {
+  buildSemanticContext,
+  formatContextForInjection,
+  SEMANTIC_WEIGHTS,
+} from './context-injection.js';
+
+/**
+ * Creates a mock vector store with vi.fn() methods.
+ * @returns {object} Mock vector store
+ */
+function createMockVectorStore() {
+  return {
+    insert: vi.fn(),
+    search: vi.fn().mockReturnValue([]),
+    delete: vi.fn(),
+    count: vi.fn().mockReturnValue(0),
+    rebuild: vi.fn(),
+    getAll: vi.fn().mockReturnValue([]),
+    close: vi.fn(),
+  };
+}
+
+/**
+ * Creates a mock embedding client that returns deterministic embeddings.
+ * @returns {object} Mock embedding client
+ */
+function createMockEmbeddingClient() {
+  return {
+    embed: vi.fn().mockResolvedValue(new Float32Array(1024).fill(0.5)),
+    embedBatch: vi.fn().mockResolvedValue([]),
+    isAvailable: vi.fn().mockResolvedValue(true),
+    getModelInfo: () => ({ model: 'mxbai-embed-large', dimensions: 1024 }),
+  };
+}
+
+/**
+ * Creates a mock semantic recall instance with recallForContext.
+ * @param {Array} results - Results to return from recallForContext
+ * @returns {object} Mock semantic recall with vi.fn() methods
+ */
+function createMockSemanticRecall(results = []) {
+  return {
+    recall: vi.fn().mockResolvedValue(results),
+    recallForContext: vi.fn().mockResolvedValue(results),
+  };
+}
+
+/**
+ * Creates a mock conversation recall result.
+ * @param {object} overrides - Properties to override
+ * @returns {object} A mock conversation result
+ */
+function createConversationResult(overrides = {}) {
+  return {
+    id: 'conv-1',
+    text: 'Discussed auth token refresh strategy using short-lived JWTs with rotation.',
+    score: 0.85,
+    type: 'conversation',
+    source: {
+      project: 'my-project',
+      workspace: '/ws',
+      branch: 'main',
+      sourceFile: 'sessions/2025-01-15.md',
+    },
+    date: Date.now() - 86400000,
+    permanent: false,
+    ...overrides,
+  };
+}
+
+describe('context-injection', () => {
+  let mockVectorStore;
+  let mockEmbeddingClient;
+  let mockSemanticRecall;
+
+  beforeEach(() => {
+    mockVectorStore = createMockVectorStore();
+    mockEmbeddingClient = createMockEmbeddingClient();
+    mockSemanticRecall = createMockSemanticRecall();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('SEMANTIC_WEIGHTS', () => {
+    it('new relevance weights sum to 1.0', () => {
+      // Task 7 defines new weights:
+      //   VECTOR_SIMILARITY: 0.35, FILE_MATCH: 0.20, BRANCH_MATCH: 0.20,
+      //   RECENCY: 0.15, KEYWORD_MATCH: 0.10
+      const sum = Object.values(SEMANTIC_WEIGHTS).reduce((a, b) => a + b, 0);
+      expect(sum).toBeCloseTo(1.0, 10);
+
+      // Verify individual weights exist with correct values
+      expect(SEMANTIC_WEIGHTS).toHaveProperty('VECTOR_SIMILARITY', 0.35);
+      expect(SEMANTIC_WEIGHTS).toHaveProperty('FILE_MATCH', 0.20);
+      expect(SEMANTIC_WEIGHTS).toHaveProperty('BRANCH_MATCH', 0.20);
+      expect(SEMANTIC_WEIGHTS).toHaveProperty('RECENCY', 0.15);
+      expect(SEMANTIC_WEIGHTS).toHaveProperty('KEYWORD_MATCH', 0.10);
+    });
+  });
+
+  describe('buildSemanticContext', () => {
+    it('calls recallForContext when vectorStore is provided', async () => {
+      const conversationResults = [
+        createConversationResult({ id: 'conv-1', text: 'Auth token discussion' }),
+        createConversationResult({ id: 'conv-2', text: 'Database migration plan' }),
+      ];
+      mockSemanticRecall = createMockSemanticRecall(conversationResults);
+
+      const context = {
+        projectId: 'my-project',
+        workspace: '/ws',
+        branch: 'main',
+        touchedFiles: ['src/auth/token.js'],
+      };
+
+      const result = await buildSemanticContext('/path/to/project', context, {
+        semanticRecall: mockSemanticRecall,
+        vectorStore: mockVectorStore,
+      });
+
+      // recallForContext should have been called with the project root and context
+      expect(mockSemanticRecall.recallForContext).toHaveBeenCalledWith(
+        '/path/to/project',
+        context
+      );
+      // Result should include the recalled conversations
+      expect(result.conversations).toBeDefined();
+      expect(result.conversations).toHaveLength(2);
+    });
+
+    it('returns empty conversations when no vectorStore is provided', async () => {
+      const context = {
+        projectId: 'my-project',
+        workspace: '/ws',
+        branch: 'main',
+        touchedFiles: [],
+      };
+
+      const result = await buildSemanticContext('/path/to/project', context, {
+        // No vectorStore, no semanticRecall
+      });
+
+      // Should fall back gracefully with empty conversations
+      expect(result.conversations).toBeDefined();
+      expect(result.conversations).toHaveLength(0);
+    });
+
+    it('vector similarity score integrated into ranking (scoreWithVector)', async () => {
+      // When vector store is available, the ranking should incorporate
+      // VECTOR_SIMILARITY weight (0.35) from SEMANTIC_WEIGHTS
+      const conversationResults = [
+        createConversationResult({
+          id: 'conv-high',
+          text: 'High relevance auth discussion',
+          score: 0.95,
+        }),
+        createConversationResult({
+          id: 'conv-low',
+          text: 'Low relevance logging setup',
+          score: 0.40,
+        }),
+      ];
+      mockSemanticRecall = createMockSemanticRecall(conversationResults);
+
+      const context = {
+        projectId: 'my-project',
+        workspace: '/ws',
+        branch: 'main',
+        touchedFiles: ['src/auth/login.js'],
+      };
+
+      const result = await buildSemanticContext('/path/to/project', context, {
+        semanticRecall: mockSemanticRecall,
+        vectorStore: mockVectorStore,
+      });
+
+      // Conversations should be ordered by score (highest first)
+      expect(result.conversations.length).toBeGreaterThanOrEqual(2);
+      expect(result.conversations[0].score).toBeGreaterThanOrEqual(
+        result.conversations[1].score
+      );
+    });
+
+    it('includes conversation chunks in semantic context output', async () => {
+      const conversationResults = [
+        createConversationResult({
+          id: 'conv-1',
+          text: 'We decided to use JWT for auth tokens with 15-minute expiry and refresh rotation.',
+          type: 'conversation',
+          score: 0.90,
+        }),
+        createConversationResult({
+          id: 'conv-2',
+          text: 'Database migration strategy: use knex with timestamped migration files.',
+          type: 'conversation',
+          score: 0.80,
+        }),
+      ];
+      mockSemanticRecall = createMockSemanticRecall(conversationResults);
+
+      const context = {
+        projectId: 'my-project',
+        workspace: '/ws',
+        branch: 'main',
+        touchedFiles: [],
+      };
+
+      const result = await buildSemanticContext('/path/to/project', context, {
+        semanticRecall: mockSemanticRecall,
+        vectorStore: mockVectorStore,
+      });
+
+      // Context output should contain actual conversation text chunks
+      expect(result.conversations).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            id: 'conv-1',
+            text: expect.stringContaining('JWT'),
+          }),
+          expect.objectContaining({
+            id: 'conv-2',
+            text: expect.stringContaining('migration'),
+          }),
+        ])
+      );
+    });
+
+    it('conversation summaries are concise (not full exchanges)', async () => {
+      // Conversations returned should have text that is a summary, not a
+      // full multi-turn exchange. The text in each result should be
+      // a concise chunk suitable for context injection.
+      const longExchange = 'A'.repeat(5000); // Simulating a very long conversation
+      const conversationResults = [
+        createConversationResult({
+          id: 'conv-long',
+          text: longExchange,
+          score: 0.85,
+        }),
+      ];
+      mockSemanticRecall = createMockSemanticRecall(conversationResults);
+
+      const context = {
+        projectId: 'my-project',
+        workspace: '/ws',
+        branch: 'main',
+        touchedFiles: [],
+      };
+
+      const result = await buildSemanticContext('/path/to/project', context, {
+        semanticRecall: mockSemanticRecall,
+        vectorStore: mockVectorStore,
+      });
+
+      // Each conversation in the output should be truncated to a concise summary
+      // (implementation should cap at a reasonable length, e.g., 300 chars)
+      for (const convo of result.conversations) {
+        expect(convo.text.length).toBeLessThanOrEqual(300);
+      }
+    });
+  });
+
+  describe('formatContextForInjection', () => {
+    it('includes "Related Conversations" section when conversations exist', () => {
+      const semanticContext = {
+        conversations: [
+          createConversationResult({
+            id: 'conv-1',
+            text: 'Auth token refresh uses short-lived JWTs.',
+            score: 0.90,
+          }),
+          createConversationResult({
+            id: 'conv-2',
+            text: 'Database indexes on user_id for performance.',
+            score: 0.80,
+          }),
+        ],
+      };
+
+      const formatted = formatContextForInjection(semanticContext);
+
+      // Should contain the Related Conversations header
+      expect(formatted).toContain('## Related Conversations');
+      // Should contain the conversation text
+      expect(formatted).toContain('Auth token refresh');
+      expect(formatted).toContain('Database indexes');
+      // Should be valid markdown
+      expect(formatted).toContain('- ');
+    });
+
+    it('omits conversations section when conversations array is empty', () => {
+      const semanticContext = {
+        conversations: [],
+      };
+
+      const formatted = formatContextForInjection(semanticContext);
+
+      // Should NOT contain the Related Conversations header
+      expect(formatted).not.toContain('## Related Conversations');
+      // Formatted output may be empty or contain other sections, but no conversations
+      expect(formatted).not.toContain('conversation');
+    });
+
+    it('backward compatible: without vector store, produces same format', () => {
+      // When no vector store was used, semanticContext has empty conversations.
+      // The formatted output should match the pre-Task-7 format: no new sections,
+      // no "Related Conversations" header, just the existing context structure.
+      const semanticContextWithoutVector = {
+        conversations: [],
+      };
+
+      const formatted = formatContextForInjection(semanticContextWithoutVector);
+
+      // No new sections should appear
+      expect(formatted).not.toContain('## Related Conversations');
+
+      // The output should be a string (possibly empty) that doesn't break
+      // existing CLAUDE.md injection
+      expect(typeof formatted).toBe('string');
+
+      // If there's nothing to inject, the result should be empty or whitespace-only
+      expect(formatted.trim()).toBe('');
+    });
+  });
+});

package/server/lib/conversation-chunker.js

@@ -0,0 +1,320 @@
+/**
+ * Conversation Chunker — splits exchanges into topic-coherent chunks.
+ *
+ * Detects boundaries from TLC commands (hard), user signals (soft),
+ * and topic shifts (semantic). Generates titles, summaries, and metadata.
+ *
+ * @module conversation-chunker
+ */
+
+import crypto from 'crypto';
+
+/** TLC command patterns that trigger hard boundaries */
+const TLC_COMMAND_PATTERN = /^\/?tlc:/i;
+
+/** User signals that indicate topic transition (soft boundaries) */
+const SOFT_BOUNDARY_SIGNALS = [
+  /^ok\b/i,
+  /^okay\b/i,
+  /^done\b/i,
+  /^next\b/i,
+  /^moving on/i,
+  /^let'?s move on/i,
+  /^let'?s build/i,
+  /^let'?s do/i,
+  /^sounds good/i,
+  /^got it/i,
+  /^alright/i,
+];
+
+/** File path pattern */
+const FILE_PATH_PATTERN = /(?:^|\s|['"`(])([a-zA-Z0-9._-]+\/[a-zA-Z0-9._\-/]+\.[a-zA-Z]{1,10})(?:['"`)\s,]|$)/g;
+
+/** Decision patterns */
+const DECISION_PATTERNS = [
+  /let'?s use (\S+.*?)(?:\.|$)/gi,
+  /we (?:decided|chose|agreed) to (.*?)(?:\.|$)/gi,
+  /(?:going|switched?) (?:with|to) (.*?)(?:\.|$)/gi,
+  /instead of (\S+),?\s+(?:we'?ll|let'?s|use) (.*?)(?:\.|$)/gi,
+];
+
+/** Minimum keyword overlap ratio to consider exchanges on the same topic */
+const SEMANTIC_SIMILARITY_THRESHOLD = 0.15;
+
+/**
+ * Extract significant words from text for keyword overlap comparison.
+ * @param {string} text
+ * @returns {Set<string>}
+ */
+function extractKeywords(text) {
+  const words = text.toLowerCase().replace(/[^a-z0-9\s]/g, ' ').split(/\s+/);
+  return new Set(words.filter((w) => w.length > 3));
+}
+
+/**
+ * Calculate keyword overlap ratio between two texts.
+ * @param {string} textA
+ * @param {string} textB
+ * @returns {number} 0-1 overlap ratio
+ */
+function keywordOverlap(textA, textB) {
+  const wordsA = extractKeywords(textA);
+  const wordsB = extractKeywords(textB);
+  if (wordsA.size === 0 || wordsB.size === 0) return 0;
+  let intersection = 0;
+  for (const w of wordsA) {
+    if (wordsB.has(w)) intersection++;
+  }
+  return intersection / Math.min(wordsA.size, wordsB.size);
+}
+
+/**
+ * Get full text of an exchange (user + assistant combined).
+ * @param {object} exchange
+ * @returns {string}
+ */
+function exchangeText(exchange) {
+  return `${exchange.user || ''} ${exchange.assistant || ''}`;
+}
+
+/**
+ * Detect whether a boundary exists between the current and previous exchange.
+ *
+ * @param {object} exchange - Current exchange `{ user, assistant, timestamp }`
+ * @param {object|undefined} previousExchange - Previous exchange
+ * @returns {{ isBoundary: boolean, type: 'hard'|'soft'|'semantic'|null }}
+ */
+export function detectBoundary(exchange, previousExchange) {
+  // No boundary on first exchange
+  if (!previousExchange) {
+    return { isBoundary: false, type: null };
+  }
+
+  const userText = (exchange.user || '').trim();
+
+  // Hard boundary: TLC command invocation
+  if (TLC_COMMAND_PATTERN.test(userText)) {
+    return { isBoundary: true, type: 'hard' };
+  }
+
+  // Soft boundary: user transition signals
+  for (const pattern of SOFT_BOUNDARY_SIGNALS) {
+    if (pattern.test(userText)) {
+      return { isBoundary: true, type: 'soft' };
+    }
+  }
+
+  // Semantic boundary: topic divergence via keyword overlap
+  // Skip semantic detection for very short exchanges (Q&A style)
+  const prevText = exchangeText(previousExchange);
+  const currText = exchangeText(exchange);
+  const prevKeywords = extractKeywords(prevText);
+  const currKeywords = extractKeywords(currText);
+
+  if (prevKeywords.size >= 5 && currKeywords.size >= 5) {
+    const overlap = keywordOverlap(prevText, currText);
+    if (overlap < SEMANTIC_SIMILARITY_THRESHOLD) {
+      return { isBoundary: true, type: 'semantic' };
+    }
+  }
+
+  return { isBoundary: false, type: null };
+}
+
+/**
+ * Generate a deterministic hash-based ID for a chunk.
+ * @param {object[]} exchanges
+ * @returns {string}
+ */
+function generateChunkId(exchanges) {
+  const content = exchanges.map((e) => `${e.timestamp}:${e.user}`).join('|');
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+/**
+ * Generate a title from chunk exchanges. Extracts the most meaningful
+ * question or decision phrase from the first user message.
+ *
+ * @param {object[]} exchanges
+ * @returns {string}
+ */
+export function generateChunkTitle(exchanges) {
+  if (!exchanges || exchanges.length === 0) return 'Untitled';
+
+  const firstUser = (exchanges[0].user || '').trim();
+
+  // If it's a TLC command, use it as title
+  if (TLC_COMMAND_PATTERN.test(firstUser)) {
+    return firstUser;
+  }
+
+  // If it's a question, use it (truncated)
+  if (firstUser.includes('?')) {
+    const question = firstUser.split('?')[0] + '?';
+    return question.length > 80 ? question.slice(0, 77) + '...' : question;
+  }
+
+  // Otherwise use the first meaningful sentence
+  const firstSentence = firstUser.split(/[.!?\n]/)[0].trim();
+  if (firstSentence.length > 0) {
+    return firstSentence.length > 80 ? firstSentence.slice(0, 77) + '...' : firstSentence;
+  }
+
+  return 'Untitled';
+}
+
+/**
+ * Generate a summary from chunk exchanges. Combines key points from
+ * user questions and assistant answers.
+ *
+ * @param {object[]} exchanges
+ * @returns {string}
+ */
+export function generateChunkSummary(exchanges) {
+  if (!exchanges || exchanges.length === 0) return '';
+
+  const parts = [];
+
+  // Summarize what was discussed
+  const firstUser = (exchanges[0].user || '').trim();
+  if (firstUser) {
+    parts.push(`Discussed: ${firstUser.length > 100 ? firstUser.slice(0, 97) + '...' : firstUser}.`);
+  }
+
+  // Summarize key response
+  const firstAssistant = (exchanges[0].assistant || '').trim();
+  if (firstAssistant) {
+    const firstSentence = firstAssistant.split(/[.!?]/)[0].trim();
+    if (firstSentence.length > 0) {
+      parts.push(`${firstSentence}.`);
+    }
+  }
+
+  // If multiple exchanges, note the follow-up
+  if (exchanges.length > 1) {
+    parts.push(`${exchanges.length} exchanges in this topic.`);
+  }
+
+  return parts.join(' ');
+}
+
+/**
+ * Extract metadata from chunk exchanges: file paths, project names,
+ * TLC commands used, and decisions made.
+ *
+ * @param {object[]} exchanges
+ * @returns {{ projects: string[], files: string[], commands: string[], decisions: string[] }}
+ */
+export function extractChunkMetadata(exchanges) {
+  const files = new Set();
+  const commands = new Set();
+  const decisions = [];
+  const projects = new Set();
+
+  for (const exchange of exchanges) {
+    const fullText = exchangeText(exchange);
+    const userText = (exchange.user || '');
+
+    // Extract file paths
+    let fileMatch;
+    const fileRegex = new RegExp(FILE_PATH_PATTERN.source, 'g');
+    while ((fileMatch = fileRegex.exec(fullText)) !== null) {
+      files.add(fileMatch[1]);
+    }
+
+    // Extract TLC commands
+    const cmdMatch = userText.match(/\/?tlc:\S+/i);
+    if (cmdMatch) {
+      // Normalize to /tlc:command format (strip arguments)
+      const cmd = cmdMatch[0].startsWith('/') ? cmdMatch[0] : '/' + cmdMatch[0];
+      const cmdBase = cmd.split(/\s/)[0];
+      commands.add(cmdBase);
+    }
+
+    // Extract decisions
+    for (const pattern of DECISION_PATTERNS) {
+      const regex = new RegExp(pattern.source, pattern.flags);
+      let decMatch;
+      while ((decMatch = regex.exec(fullText)) !== null) {
+        const decision = decMatch[0].trim();
+        if (decision.length > 5) {
+          decisions.push(decision);
+        }
+      }
+    }
+
+    // Extract project names (heuristic: capitalized proper nouns that look like project names)
+    const projectPattern = /\b(?:the\s+)?([A-Z][a-zA-Z0-9-]+)(?:\s+(?:project|module|service|repo|package))/g;
+    let projMatch;
+    while ((projMatch = projectPattern.exec(fullText)) !== null) {
+      projects.add(projMatch[1]);
+    }
+  }
+
+  return {
+    files: [...files],
+    commands: [...commands],
+    decisions: [...new Set(decisions)],
+    projects: [...projects],
+  };
+}
+
+/**
+ * Chunk a conversation into topic-coherent segments.
+ *
+ * @param {object[]} exchanges - Array of `{ user, assistant, timestamp }`
+ * @param {object} [options]
+ * @param {number} [options.minChunkSize=1] - Minimum exchanges per chunk
+ * @param {number} [options.maxChunkSize=8] - Maximum exchanges per chunk
+ * @returns {object[]} Array of chunks
+ */
+export function chunkConversation(exchanges, options = {}) {
+  if (!exchanges || exchanges.length === 0) return [];
+
+  const { minChunkSize = 1, maxChunkSize = 8 } = options;
+
+  const chunks = [];
+  let currentChunk = [];
+
+  for (let i = 0; i < exchanges.length; i++) {
+    const exchange = exchanges[i];
+    const prevExchange = i > 0 ? exchanges[i - 1] : undefined;
+    const boundary = detectBoundary(exchange, prevExchange);
+
+    // Check if we should split
+    const shouldSplit = boundary.isBoundary && currentChunk.length >= minChunkSize;
+    const exceedsMax = currentChunk.length >= maxChunkSize;
+
+    if ((shouldSplit || exceedsMax) && currentChunk.length > 0) {
+      chunks.push(buildChunk(currentChunk));
+      currentChunk = [];
+    }
+
+    currentChunk.push(exchange);
+  }
+
+  // Flush remaining
+  if (currentChunk.length > 0) {
+    chunks.push(buildChunk(currentChunk));
+  }
+
+  return chunks;
+}
+
+/**
+ * Build a chunk object from a set of exchanges.
+ * @param {object[]} exchanges
+ * @returns {object}
+ */
+function buildChunk(exchanges) {
+  return {
+    id: generateChunkId(exchanges),
+    title: generateChunkTitle(exchanges),
+    summary: generateChunkSummary(exchanges),
+    topic: generateChunkTitle(exchanges),
+    exchanges,
+    startTime: exchanges[0].timestamp,
+    endTime: exchanges[exchanges.length - 1].timestamp,
+    metadata: extractChunkMetadata(exchanges),
+  };
+}