VSCode File Indexing

Relevant source files

The following files were used as context for generating this wiki page:

• vscode-extension/src/fileIndexer/FileIndexer.ts
• vscode-extension/src/fileIndexer/PathCompleter.ts
• vscode-extension/src/chatView/ChatViewProvider.ts
• vscode-extension/src/chatView/messageProcessor.ts
• vscode-extension/media/webview/chat.js

VSCode File Indexing is a core component of the QQCode companion extension that enables efficient file discovery, autocomplete suggestions, and context-aware messaging. It maintains an in-memory representation of the workspace structure to provide fast lookup capabilities for "@" file mentions within the chat interface.

The system ensures that the AI assistant has access to precise file paths and contents when referenced by the user, facilitating a seamless "mention-to-context" workflow. This is achieved through a combination of recursive directory scanning, real-time file system watching, and fuzzy matching algorithms.
Sources: vscode-extension/src/fileIndexer/FileIndexer.ts:1-7, vscode-extension/src/chatView/messageProcessor.ts:1-5, vscode-extension/media/webview/chat.js:1010-1015

Architecture and Components

The indexing system is composed of several specialized classes and scripts that handle the lifecycle of workspace metadata from the disk to the user interface.

Component Overview

Component	Description
FileIndexer	Manages the in-memory cache of workspace files and directories. Handles initial indexing and file system events.
PathCompleter	Provides fuzzy-search logic and scoring for file suggestions based on user input after an "@" symbol.
MessageProcessor	Resolves mentions in user messages, reads file contents, and embeds them into the final prompt for the backend.
ChatViewProvider	Acts as the orchestrator in the extension host, connecting the indexer to the webview and backend.
chat.js	Manages the UI side of completions, including the popup rendering and keyboard navigation.

Sources: vscode-extension/src/fileIndexer/FileIndexer.ts:18-24, vscode-extension/src/fileIndexer/PathCompleter.ts:28-35, vscode-extension/src/chatView/messageProcessor.ts:36-40, vscode-extension/src/chatView/ChatViewProvider.ts:60-75, vscode-extension/media/webview/chat.js:910-915

Data Structures

The system uses specific interfaces to represent file metadata and suggestions:

export interface IndexEntry {
    rel: string;        // Relative path from workspace root
    relLower: string;   // Lowercased for case-insensitive matching
    name: string;       // File/directory name
    uri: vscode.Uri;    // Full URI
    isDir: boolean;     // Directory flag
}

export interface CompletionSuggestion {
    label: string;      // The completion text (e.g., "@src/index.ts")
    path: string;       // The relative path
    isDirectory: boolean;
}

Sources: vscode-extension/src/fileIndexer/FileIndexer.ts:9-17, vscode-extension/src/fileIndexer/PathCompleter.ts:12-18

Indexing Logic and Synchronization

The FileIndexer is responsible for building and maintaining the file map. It performs an initial recursive scan and then listens for changes to keep the index fresh.

Lifecycle of the Index

1. Initial Scan: Triggered by getIndex(), it recursively traverses the workspace using vscode.workspace.fs.readDirectory.
2. Exclusion Rules: Common directories like node_modules, .git, and dist are ignored to maintain performance.
3. Synchronization: A vscode.FileSystemWatcher monitors onDidCreate and onDidDelete events to update the in-memory Map without requiring a full rebuild.

Autocomplete and Search Flow

When a user types "@" in the chat, the system initiates a completion flow. The PathCompleter scores matches from the indexer to provide the most relevant suggestions.

Search Contexts

The search behavior adapts based on the input:

• Pure "@": Lists immediate top-level files and directories.
• Path ending in "/": Lists immediate children of the specified directory.
• Partial Path: Performs a fuzzy search across the entire index.

Mention Resolution and Context Embedding

When a message is submitted, the messageProcessor converts text mentions into actual file content to provide context for the LLM.

Processing Steps

1. Mention Extraction: Scans the message for the "@" anchor.
2. Resolution: Verifies the path against the file system using vscode.workspace.fs.stat.
3. Embedding:
   • Directories: Adds the URI and name as a reference.
   • Files: Reads the file content. If it is within size limits (default 256KB) and determined to be text (non-binary), the full content is wrapped in a markdown code block.
4. Final Prompt: Joins the original user message with the gathered file contents for backend transmission.

Sources: vscode-extension/src/chatView/messageProcessor.ts:41-80, vscode-extension/src/chatView/messageProcessor.ts:167-190, vscode-extension/src/chatView/messageProcessor.ts:196-220

Configuration and Constraints

The indexing and completion systems operate under several technical constraints to ensure VS Code remains responsive.

Constraint	Value / Behavior	Source
Max Embed Size	256 KB	messageProcessor.ts
Max Processed Entries	32,000	PathCompleter.ts
Max UI Suggestions	50	PathCompleter.ts
Ignore Patterns	node_modules, .git, __pycache__, dist, etc.	FileIndexer.ts
Binary Check	Checks for null bytes and non-printable char proportion (> 10%)	messageProcessor.ts

Sources: vscode-extension/src/chatView/messageProcessor.ts:8, vscode-extension/src/fileIndexer/PathCompleter.ts:8-10, vscode-extension/src/fileIndexer/FileIndexer.ts:124-148, vscode-extension/src/chatView/messageProcessor.ts:222-258

Summary

VSCode File Indexing provides the foundational metadata layer for QQCode's agentic features. By maintaining an efficient FileIndexer and utilizing a PathCompleter for fuzzy-matched suggestions, the extension enables users to reference their codebase naturally. The messageProcessor then bridges the gap between these UI mentions and the backend by resolving paths and embedding relevant file contents into the model prompts.