src — advanced

Module: src-advanced Cohesion: 0.80 Members: 0

src — advanced

The src/advanced module provides a suite of sophisticated functionalities designed to enhance the core capabilities of the system, offering features typically found in advanced development environments. These components address complex challenges such as collaborative development, intelligent code assistance, and robust version control.

This document details each major component within the src/advanced module, explaining its purpose, internal workings, key APIs, and how it integrates with other parts of the codebase.

Module Overview

The src/advanced module encapsulates several distinct, high-value features:

Most components follow a singleton pattern, providing a get() factory function to ensure a single instance across the application, and extend EventEmitter for event-driven communication.

Conversation Branching and Merging (conversation-branching.ts)

This module provides a mechanism to manage divergent conversation threads, allowing users to explore alternative responses or ideas without losing the original context, similar to how version control systems handle code branches.

Purpose

To enable non-linear conversation flows, allowing users to:

How it Works

The ConversationBranchManager class is the central orchestrator. It maintains a collection of ConversationBranch objects, each representing a distinct conversation path.

  1. Branch Creation: When createBranch or branchFromMessage is called, a new ConversationBranch is created. If a parentBranchId and branchPointMessageId are provided, the new branch inherits all messages from its parent up to and including the branch point message.
  2. Message Management: Messages are added to the currentBranch using addMessage. Each message is assigned a unique ID.
  3. Branch Switching: switchBranch changes the active conversation context.
  4. Merging: The mergeBranches method attempts to combine messages from a sourceBranch into a targetBranch. Currently, it primarily adds unique messages from the source to the target and sorts them by timestamp. Conflict detection is outlined in the MergeConflict interface but not fully implemented for resolution in mergeBranches.
  5. History: getHistory traces a branch back to its root parent.

Key Components

Usage

import { getConversationBranchManager } from './conversation-branching';

const manager = getConversationBranchManager();

class="hl-cmt">// Initial branch is 'main'
const mainBranch = manager.getCurrentBranch();
manager.addMessage('user', 'What is the capital of France?');
manager.addMessage('assistant', 'Paris.');

class="hl-cmt">// Branch off from the assistant's message
const newBranch = manager.branchFromMessage(mainBranch.messages[1].id, 'explore-germany');
manager.switchBranch(newBranch.id);
manager.addMessage('user', 'And Germany?');
manager.addMessage('assistant', 'Berlin.');

class="hl-cmt">// Switch back to main and add more messages
manager.switchBranch(mainBranch.id);
manager.addMessage('user', 'What about Italy?');
manager.addMessage('assistant', 'Rome.');

class="hl-cmt">// Attempt to merge 'explore-germany' into 'main'
const mergeResult = manager.mergeBranches(newBranch.id, mainBranch.id);
console.log('Merged branch messages:', mergeResult.mergedBranch.messages);

Integration

Architecture Diagram

graph TD
    A[ConversationBranchManager] --> B{createBranch/branchFromMessage}
    B --> C[ConversationBranch]
    A --> D{addMessage}
    D --> E[Message]
    A --> F{switchBranch}
    A --> G{mergeBranches}
    G -- Copies & Sorts --> C
    C -- Contains --> E
    A -- Emits Events --> H[Listeners]

Distributed Caching (distributed-cache.ts)

This module provides a local, in-memory cache designed for shared use within a team context, offering performance benefits by storing frequently accessed data.

Purpose

To provide a fast, temporary storage for responses or computed values, reducing redundant computations and improving response times. It includes features like Time-To-Live (TTL) and size-based eviction to manage memory usage.

How it Works

The DistributedCache class manages a Map of CacheEntry objects.

  1. Configuration: The cache is initialized with maxSize (total cache size), ttl (entry expiration), and syncInterval (for periodic cleanup).
  2. Key Generation: All keys are hashed using SHA256 to ensure consistency and fixed-size storage.
  3. Setting Entries: set adds a new entry. It checks if the entry is too large or if adding it would exceed the maxSize. If necessary, it triggers evictIfNeeded to remove older entries.
  4. Retrieving Entries: get retrieves an entry. It checks for expiration and increments a hits counter. If expired or not found, it increments misses.
  5. Eviction: evictIfNeeded implements a basic Least Recently Hit (LRH) eviction strategy, removing entries with the lowest hit count until space is available.
  6. Cleanup: startSync initiates a timer that periodically calls cleanup to remove expired entries and emits cache statistics.

Key Components

Usage

import { getDistributedCache } from './distributed-cache';

const cache = getDistributedCache({ maxSize: 10 * 1024 * 1024, ttl: 60000 }); class="hl-cmt">// 10MB, 1 minute TTL

cache.on('set', ({ key, size }) => console.log(`Cache set: ${key}, size: ${size}`));
cache.on('hit', ({ key }) => console.log(`Cache hit: ${key}`));
cache.on('sync', (stats) => console.log('Cache sync stats:', stats));

cache.set('my-data-key', 'some important data', 'user123');
console.log('Retrieved:', cache.get('my-data-key'));

cache.startSync(); class="hl-cmt">// Start periodic cleanup and stats emission

class="hl-cmt">// Later...
cache.dispose(); class="hl-cmt">// Clean up resources

Integration

Project Style Learning (project-style-learning.ts)

This module enables the system to learn and adapt to the specific coding style of a given project by analyzing its source code.

Purpose

To automatically infer and document a project's coding conventions (e.g., naming, formatting, quote style, semicolon usage, indentation) and apply these preferences when generating or modifying code.

How it Works

The ProjectStyleLearner class performs a deep analysis of a project's codebase.

  1. File Discovery: analyzeProject first calls findSourceFiles to recursively scan the project directory for common source code files (.ts, .js, .py, etc.), ignoring common non-source directories like .git or node_modules.
  2. Content Analysis: For each discovered file, its content is read, and extractPatterns is invoked. This method uses regular expressions to detect prevalent patterns:

  1. Style Storage: The inferred preferences are stored in a ProjectStyle object associated with the projectPath.
  2. Style Application: applyStyleToCode can take a string of code and modify it to conform to the learned preferences (e.g., changing double quotes to single quotes, removing semicolons).
  3. Style Guide Generation: generateStyleGuide produces a human-readable summary of the learned style.

Key Components

Usage

import { getProjectStyleLearner } from './project-style-learning';

const learner = getProjectStyleLearner();

learner.on('analysis-complete', (style) => {
  console.log(`Analysis complete for ${style.projectPath}. Preferences:`, style.preferences);
});

async function runAnalysis() {
  const projectPath = '/path/to/your/project';
  const style = await learner.analyzeProject(projectPath);

  const styleGuide = learner.generateStyleGuide(projectPath);
  console.log(styleGuide);

  const originalCode = 'const myVar = "hello";\nconsole.log(myVar);';
  const styledCode = learner.applyStyleToCode(originalCode, projectPath);
  console.log('Original:\n', originalCode);
  console.log('Styled:\n', styledCode);
}

runAnalysis();

Integration

Selective File Rollback (selective-rollback.ts)

This module provides a lightweight versioning system for individual files, allowing users to save snapshots and revert to previous states without relying on a full-fledged version control system like Git.

Purpose

To offer granular control over file versions, enabling users to:

How it Works

The SelectiveRollbackManager stores an array of FileVersion objects for each tracked file.

  1. Saving Versions: saveVersion takes a file path and its content, creates a FileVersion with a unique ID, hash, and timestamp, and adds it to the beginning of the file's version history. It avoids saving duplicate content.
  2. Retrieving Versions: getVersions returns all saved versions for a given file, while getVersion retrieves a specific version by ID.
  3. Rolling Back: rollbackFile is the core rollback mechanism. Before overwriting the file, it first saves the current state of the file (if it exists) as a new version. Then, it writes the content of the target versionId to the file system.
  4. Multiple Rollbacks: rollbackMultiple allows rolling back several files in a single operation.
  5. Comparison: compareVersions provides a basic line-by-line comparison between two specified versions of a file, counting added, removed, and changed lines.

Key Components

Usage

import { getSelectiveRollbackManager } from './selective-rollback';
import fs from 'fs-extra';

const manager = getSelectiveRollbackManager();

manager.on('version-saved', (version) => console.log(`Version saved for ${version.path}: ${version.id}`));
manager.on('file-rolled-back', ({ path, versionId }) => console.log(`File ${path} rolled back to ${versionId}`));

async function demonstrateRollback() {
  const filePath = 'temp_file.txt';
  await fs.writeFile(filePath, 'Initial content\nLine 2', 'utf-8');

  class="hl-cmt">// Save initial version
  const v1 = manager.saveVersion(filePath, await fs.readFile(filePath, 'utf-8'));

  class="hl-cmt">// Modify file and save new version
  await fs.writeFile(filePath, 'Modified content\nNew Line 2\nLine 3', 'utf-8');
  const v2 = manager.saveVersion(filePath, await fs.readFile(filePath, 'utf-8'));

  console.log('Current file content:', await fs.readFile(filePath, 'utf-8'));

  class="hl-cmt">// Rollback to v1
  const result = await manager.rollbackFile(filePath, v1.id);
  if (result.success) {
    console.log('File rolled back successfully.');
    console.log('Content after rollback:', await fs.readFile(filePath, 'utf-8'));
  }

  class="hl-cmt">// Compare versions
  const comparison = manager.compareVersions(filePath, v1.id, v2.id);
  console.log('Comparison v1 vs v2:', comparison);

  class="hl-cmt">// Clean up
  await fs.remove(filePath);
}

demonstrateRollback();

Integration

Architecture Diagram

graph TD
    A[SelectiveRollbackManager] --> B{saveVersion}
    B -- Stores --> C[FileVersion]
    A --> D{rollbackFile}
    D -- Reads/Writes --> E[File System]
    D -- Saves Current State --> B
    A --> F{getVersions/getVersion}
    A --> G{compareVersions}
    G -- Compares --> C
    A -- Emits Events --> H[Listeners]

Deterministic Session Replay (session-replay.ts)

This module provides functionality to record and replay user interaction sessions, capturing a sequence of events for debugging, analysis, or demonstration purposes.

Purpose

To enable the capture of a user's interaction flow with the system, including inputs, outputs, tool calls, and state changes. These recorded sessions can then be deterministically replayed to reproduce issues, understand user behavior, or demonstrate features.

How it Works

The SessionReplayManager manages the recording, storage, and replay of ReplaySession objects.

  1. Recording:

  1. Storage: saveSession serializes a ReplaySession to a JSON file within a dedicated .codebuddy/replays directory. loadSession and listSessions handle retrieving and listing saved sessions.
  2. Replay: The replay method takes a sessionId and iterates through its recorded events. It introduces delays between events to simulate the original timing (adjustable via speed option) and emits each event for external processing (e.g., UI updates).
  3. Integrity: verifyIntegrity re-computes the hash for each event's data and compares it to the stored hash, ensuring the session data has not been tampered with.

Key Components

Usage

import { getSessionReplayManager } from './session-replay';
import fs from 'fs-extra';

const manager = getSessionReplayManager();

manager.on('recording-started', (sessionId) => console.log(`Recording session ${sessionId}`));
manager.on('event-recorded', (event) => console.log(`Recorded event: ${event.type}`));
manager.on('replay-event', (event) => console.log(`Replaying event: ${event.type} - ${JSON.stringify(event.data)}`));

async function demonstrateReplay() {
  const metadata = { model: 'gpt-4', systemPrompt: 'You are a helpful AI.', toolsEnabled: ['search'] };
  const session = manager.startRecording('My Test Session', metadata);

  manager.recordEvent('input', { text: 'Hello AI' });
  await new Promise(r => setTimeout(r, 100));
  manager.recordEvent('output', { text: 'Hello user!' });
  await new Promise(r => setTimeout(r, 50));
  manager.recordEvent('tool', { name: 'search', query: 'latest news' });

  const savedSession = manager.stopRecording();
  if (savedSession) {
    const filePath = await manager.saveSession(savedSession);
    console.log(`Session saved to ${filePath}`);

    console.log('\nStarting replay...');
    await manager.replay(savedSession.id, { speed: 2, onEvent: (e) => console.log(`Custom handler: ${e.type}`) });
    console.log('Replay completed.');

    const integrity = manager.verifyIntegrity(savedSession);
    console.log(`Session integrity verified: ${integrity}`);
  }

  class="hl-cmt">// Clean up
  await fs.remove('.codebuddy/replays');
}

demonstrateReplay();

Integration

Architecture Diagram

graph TD
    A[SessionReplayManager] --> B{startRecording}
    B -- Creates --> C[ReplaySession]
    A --> D{recordEvent}
    D -- Adds to --> C
    A --> E{stopRecording}
    E -- Finalizes --> C
    A --> F{saveSession}
    F -- Writes JSON --> G[File System (.codebuddy/replays)]
    A --> H{loadSession}
    H -- Reads JSON --> G
    A --> I{replay}
    I -- Reads Events --> C
    I -- Emits Events --> J[Listeners]
    A --> K{verifyIntegrity}
    K -- Checks Hashes --> C

Specialized Language/Framework Agents (specialized-agents.ts)

This module manages a registry of AI agents that are specifically optimized for different programming languages and frameworks.

Purpose

To allow the system to select and utilize AI agents that possess deep expertise in a particular technology stack, leading to more accurate, context-aware, and high-quality code generation, analysis, and refactoring.

How it Works

The SpecializedAgentManager maintains a collection of SpecializedAgent objects.

  1. Agent Registry: The manager is initialized with a predefined set of SPECIALIZED_AGENTS (e.g., TypeScript Expert, Python Expert, React Expert), each detailing its capabilities (languages, frameworks, specialties) and a systemPrompt. Additional agents can be registered dynamically using registerAgent.
  2. Agent Selection:

  1. Current Agent: setCurrentAgent sets an agent as the active one, and getCurrentAgent retrieves it.

Key Components

Usage

import { getSpecializedAgentManager } from './specialized-agents';

const manager = getSpecializedAgentManager();

manager.on('agent-selected', (agent) => console.log(`Selected agent: ${agent.name}`));

class="hl-cmt">// Get all available agents
console.log('Available agents:', manager.getAgents().map(a => a.name));

class="hl-cmt">// Select an agent for a specific language
const tsAgent = manager.selectAgentForLanguage('typescript');
console.log('TypeScript agent:', tsAgent?.name);

class="hl-cmt">// Auto-select based on context
const reactContextAgent = manager.autoSelectAgent({ language: 'typescript', framework: 'react' });
console.log('Auto-selected for React context:', reactContextAgent?.name);

class="hl-cmt">// Set a specific agent as current
manager.setCurrentAgent('python-expert');
console.log('Current agent:', manager.getCurrentAgent()?.name);

class="hl-cmt">// Register a new custom agent
manager.registerAgent({
  id: 'vue-expert',
  name: 'Vue.js Expert',
  description: 'Specialized in Vue.js and frontend development',
  capabilities: { languages: ['javascript', 'typescript'], frameworks: ['vue'], specialties: ['composition API', 'state management'] },
  systemPrompt: 'You are a Vue.js expert. Focus on Vue 3, Composition API, and reactivity.',
  examples: [],
});
console.log('New agent registered:', manager.getAgent('vue-expert')?.name);

Integration

Team Mode with Shared Context (team-mode.ts)

This module facilitates collaborative development by providing a shared context and communication mechanisms for a team working with the AI.

Purpose

To enable multiple team members to interact with the AI in a shared environment, where the AI maintains a consistent understanding of the project, shared knowledge, and team activities. This fosters better collaboration and more relevant AI assistance.

How it Works

The TeamModeManager orchestrates shared context and team member management.

  1. Initialization: The manager is created with TeamConfig (e.g., teamId, syncInterval, maxMembers). It initializes a SharedTeamContext.
  2. Member Management: addMember and removeMember manage the team roster, assigning roles and tracking activity.
  3. Shared Context:

  1. Synchronization: startSync initiates a timer that periodically emits the entire SharedTeamContext, allowing connected clients or other modules to stay updated.
  2. Access: getContext and getMembers provide read-only access to the current shared state.

Key Components

Usage

import { createTeamMode } from './team-mode';

const teamManager = createTeamMode({ teamId: 'dev-team-alpha', maxMembers: 10 });

teamManager.on('member-joined', (member) => console.log(`${member.name} joined the team.`));
teamManager.on('knowledge-updated', ({ key, value }) => console.log(`Shared knowledge updated: ${key} = ${value}`));
teamManager.on('sync', (context) => console.log('Team context synced:', context.history.length, 'actions'));

const member1 = teamManager.addMember('Alice', 'admin');
const member2 = teamManager.addMember('Bob');

teamManager.addKnowledge('project-goal', 'Build a scalable microservice architecture.');
teamManager.addPattern('use-async-await', 'Prefer async/await over callbacks.');
teamManager.addConvention('commit-message-format', 'feat: (scope) message');

teamManager.recordAction(member1.id, 'query', 'How to implement feature X?');
teamManager.recordAction(member2.id, 'edit', 'Refactored auth module.');

console.log('Current team members:', teamManager.getMembers().map(m => m.name));
console.log('Shared knowledge:', teamManager.getContext().sharedKnowledge.get('project-goal'));

teamManager.startSync(); class="hl-cmt">// Start periodic context synchronization

class="hl-cmt">// Later...
teamManager.dispose(); class="hl-cmt">// Clean up resources

Integration

Architecture Diagram

graph TD
    A[TeamModeManager] --> B{addMember/removeMember}
    B -- Manages --> C[TeamMember]
    A --> D{addKnowledge/addPattern/addConvention}
    D -- Updates --> E[SharedTeamContext]
    A --> F{recordAction}
    F -- Adds to History --> E
    A --> G{startSync}
    G -- Periodically Emits --> E
    E -- Accessed by --> H[AI Agents/Clients]
    A -- Emits Events --> I[Listeners]

Three-Way Diff for Conflict Resolution (three-way-diff.ts)

This module provides a robust implementation of a three-way diff algorithm, essential for identifying and resolving merge conflicts between different versions of text content.

Purpose

To accurately compare three versions of a file (a common ancestor, "ours," and "theirs") to:

How it Works

The ThreeWayDiff class implements the core diffing logic.

  1. Diffing (diff):

  1. Conflict Formatting (formatConflictMarkers): Generates a string with standard Git-style conflict markers (<<<<<<< OURS, =======, >>>>>>> THEIRS) for a given DiffHunk.
  2. Conflict Parsing (parseConflictMarkers): Extracts DiffHunk objects from a string containing Git-style conflict markers.
  3. Conflict Resolution (resolveConflicts): Takes a ThreeWayDiffResult (which contains conflicts) and an array of ConflictResolution objects. For each specified hunk, it applies the chosen resolution strategy ('ours', 'theirs', 'both', or 'custom content') and then reconstructs the merged string.

Key Components

Usage

import { getThreeWayDiff } from &#39;./three-way-diff&#39;;

const diffManager = getThreeWayDiff();

const base = `Line 1
Line 2
Line 3
Line 4`;

const ours = `Line 1
Our change on Line 2
Line 3
Line 4 added by ours`;

const theirs = `Line 1
Their change on Line 2
Line 3
Line 4 added by theirs`;

class="hl-cmt">// Perform a diff
const result = diffManager.diff(base, ours, theirs);
console.log(&#39;Has conflicts:&#39;, result.hasConflicts);
console.log(&#39;Conflict count:&#39;, result.conflictCount);

if (result.hasConflicts) {
  console.log(&#39;\nConflicts found:&#39;);
  result.hunks.filter(h => h.status === &#39;conflict&#39;).forEach((hunk, index) => {
    console.log(`--- Hunk ${index + 1} ---`);
    console.log(diffManager.formatConflictMarkers(hunk));
  });

  class="hl-cmt">// Resolve conflicts (e.g., choose &#39;ours&#39; for the first conflict)
  const resolutions = [{ hunkIndex: 0, choice: &#39;ours&#39; }];
  const resolvedContent = diffManager.resolveConflicts(result, resolutions);
  console(&#39;\nResolved content (choosing ours for first conflict):&#39;);
  console.log(resolvedContent);
} else {
  console.log(&#39;\nAuto-merged content:&#39;);
  console.log(result.merged);
}

class="hl-cmt">// Example of parsing conflict markers
const conflictString = `Line A
<<<<<<< OURS
Our version of B
=======
Their version of B
>>>>>>> THEIRS
Line C`;
const parsedHunks = diffManager.parseConflictMarkers(conflictString);
console(&#39;\nParsed conflict hunks:&#39;, parsedHunks);

Integration

Architecture Diagram

graph TD
    A[ThreeWayDiff] --> B{diff(base, ours, theirs)}
    B -- Generates --> C[ThreeWayDiffResult]
    C -- Contains --> D[DiffHunk]
    D -- Status --> E{clean, auto-merged, conflict}
    A --> F{autoMerge}
    F -- If no conflicts --> C
    A --> G{resolveConflicts}
    G -- Takes --> C & H[ConflictResolution]
    G -- Produces --> I[Merged Content]
    A --> J{formatConflictMarkers}
    J -- Formats --> D
    A --> K{parseConflictMarkers}
    K -- Parses --> D