VB6Semantic / Documentation

Overview

The Query system in vb6semantic is an editor-oriented index built over the semantic analyzer's resolved identifier occurrences. Its sole purpose is to power IDE features: go-to-definition, find-all-references, and hover information for any identifier in a VB6 source file.

Rather than storing declarations (which belongs to the symbol table), the query index stores occurrences -- every place a resolved identifier appears in the source code, classified by the role that occurrence plays for its symbol. It provides two complementary query directions:

• Symbol-to-occurrences: Given a scope and name, find every place that symbol appears, including its definition.
• Position-to-symbol: Given a file and cursor position, determine which symbol the identifier at that position resolves to, and from there find all its occurrences.

Purpose & IDE Features

The query index serves as the backbone for three core IDE capabilities in the VB6 ecosystem:

Go-to-Definition

When a user places the cursor on an identifier and requests go-to-definition, the query index performs a position lookup to find the symbol under the cursor, then returns the Reference with ReferenceKind::Definition. This works even when the cursor is on a usage site -- the index finds the definition location in a different file or a later line in the same file.

// Given cursor at (Runner.bas, line 5, column 11)
// where `Greet` is called:

let def = index.definition_at("Runner", 5, 11);
// Returns Reference at (Greeter.bas, line 3, column 17)
// The actual `Public Function Greet(...)` declaration

Find-All-References

When a user requests find-references for a symbol, the index returns all occurrences (definition + usages + type references) across the project. The returned references include precise source locations and byte offsets, enabling tools to highlight or list every usage with exact positions.

let refs = index.references_at("Runner", 5, 11).unwrap();
// Returns: 3 references
//   1. Greeter.bas:3:17 -- Definition (declaration)
//   2. Greeter.bas:4:5  -- Usage (Greet = ...)
//   3. Runner.bas:5:11  -- Usage (call site in Runner)

Hover Information

For hover tooltips, the query index identifies which symbol the cursor is on. The host tool then combines this with the symbol table (for type information, visibility, and documentation) to produce a rich hover display.

Architecture

The query index sits at the base of the analysis pipeline, collecting occurrences during symbol processing and then serving queries after analysis completes.

Core Data Types

The query system is built on three types defined in projects/vb6semantic/src/query.rs:

ReferenceKind

An enum that classifies the role an identifier occurrence plays for its symbol:

pub enum ReferenceKind {
    /// The declaration that defines the symbol.
    Definition,

    /// A use of the symbol as a value or call target.
    Usage,

    /// A use of the symbol as a type name (As clause, New target).
    TypeReference,
}

Reference

A single occurrence of a symbol in the source, carrying its classification, precise location, and byte offsets:

pub struct Reference {
    pub kind: ReferenceKind,
    pub location: SourceLocation,  // file, line (1-based), column (1-based)
    pub start_offset: u32,          // inclusive start byte offset
    pub end_offset: u32,            // exclusive end byte offset
    pub end_column: usize,          // exclusive end column
}

The byte offsets (start_offset and end_offset) come directly from the CST token's range, enabling tools to extract the exact source text. The end_column is 1-based and exclusive, consistent with LSP position semantics. VB6 identifiers are stored in source text and can span multiple columns for longer names.

SymbolKey

The unique identity of a symbol inside the query index, consisting of a scope ID and the lowercase name. Names are lowercased because VB6 is case-insensitive:

pub struct SymbolKey {
    pub scope_id: usize,   // which scope the symbol lives in
    pub name: String,      // lowercased symbol name
}

The scope_id distinguishes between symbols with the same name in different scopes. For example, a module-level variable counter and a procedure-local variable counter have different scope IDs even though their names are identical.

Two-Pass Collection

The query index is populated during semantic analysis through a carefully ordered two-pass process. This ordering ensures that forward references -- calling a function before its declaration appears in the source -- resolve correctly.

Pass 1: Record Definitions

As the analyzer walks declaration nodes in the CST, it records each symbol's Definition occurrence. This includes module-level procedures (Public and Private), module-level variables, parameters, class members, and enum values.

fn record_definition(
    &mut self,
    scope_id: usize,
    name: &str,
    start_offset: u32,
    end_offset: u32,
) {
    let reference = QueryReference::new(
        ReferenceKind::Definition,
        self.location_at(start_offset),
        start_offset,
        end_offset,
    );
    self.query_index.record(scope_id, name, reference);
}

Pass 2: Collect Usages

After all declarations are registered, the analyzer walks identifier usages in each module's CST. For each identifier token that resolves against the scope manager, it records a Usage or TypeReference occurrence:

fn collect_usages_in(&mut self, node: &CstNode) -> Result<()> {
    for child in node.descendants() {
        if child.kind() != SyntaxKind::Identifier {
            continue;
        }
        // Type references: preceded by `As` or `New` keywords
        let is_type_reference = matches!(
            prev_significant_kind,
            Some(SyntaxKind::AsKeyword) | Some(SyntaxKind::NewKeyword)
        );

        // Skip already-recorded tokens (definitions)
        if self.query_index.is_recorded(...) {
            continue;
        }

        // Resolve identifier against scope manager
        let Some(symbol) = self.scope_manager.lookup(child.text()) else {
            continue;
        };

        // Record usage or type reference
        self.query_index.record(symbol.scope_id, &symbol.name, reference);
    }
}

Deferred Resolution

When analyzing a complete project (as opposed to a single module), reference resolution is deferred until all files in the project are registered. This ensures that cross-module references resolve correctly -- a call to Greeter.Greet() in one module can find the Greet function declared in a different module.

// In analyze_project():
self.defer_resolution = true;

// Register all modules first (definitions only)
for file in project_files {
    analyzer.analyze_module(file);
}

// Then resolve all references across modules
for file in project_files {
    analyzer.resolve_file(file);
}

// Finalize: sort position index for binary search
self.query_index.finalize();

Query Methods

The QueryIndex struct provides six public methods for querying the index, organized into symbol-based and position-based query categories:

Symbol-Based Queries

// Find all occurrences of a symbol by scope and name
let refs = index.references_for(scope_id, "square");
// Returns: [Definition at (MathUtils, 8:17), Usage at (9:5),
//          Usage at (15:13), Usage at (16:17)]

// Names are matched case-insensitively
index.references_for(scope_id, "SQUARE")  // same result
index.references_for(scope_id, "Square")  // same result

Position-Based Queries

Position-based queries first find which symbol the cursor is on, then look up that symbol's full set of occurrences. The position lookup uses binary search over a sorted position index, built by calling finalize() after collection completes.

// Find the symbol at a cursor position
let key = index.symbol_at("MathUtils", 9, 5);
// Returns SymbolKey { scope_id: 1, name: "square" }

// Get all occurrences of that symbol
let all_refs = index.references_at("MathUtils", 9, 5).unwrap();
// Returns the same 4 references as references_for() above

// Jump directly to the definition
let def = index.definition_at("MathUtils", 9, 5).unwrap();
// Returns Reference { kind: Definition, location: (MathUtils, 8:17) }

Iteration & Metadata

For tools that need to inspect the entire index (for diagnostics, visualization, or caching):

// Iterate over every symbol and its occurrences
for (key, refs) in index.iter() {
    println!("{} in scope {}: {} occurrences", key.name, key.scope_id, refs.len());
}

// Total number of recorded occurrences
let total = index.len();

// Whether the index is empty
let empty = index.is_empty();

Deduplication

The query index tracks every recorded occurrence's byte range in a HashSet to prevent duplicate entries during usage collection. This matters when the same identifier token could be visited by multiple analysis paths.

pub fn record(&mut self, scope_id: usize, name: &str, reference: Reference) {
    // Track for deduplication
    self.recorded_ranges.insert((
        reference.location.file.clone(),
        reference.start_offset,
        reference.end_offset,
    ));
    // Store in by_symbol and by_position maps...
}

pub fn is_recorded(&self, file: &str, start: u32, end: u32) -> bool {
    self.recorded_ranges.contains(&(file.to_string(), start, end))
}

The is_recorded check happens in collect_usages_in() before resolving an identifier. If the byte range was already recorded (e.g., it's a definition that was already added in Pass 1), the occurrence is skipped.

Integration with Analysis

The query index is a field on SemanticAnalyzer and is populated automatically during the analysis process. Users access it through the query_index() getter after analysis completes:

let mut analyzer = SemanticAnalyzer::new();
analyzer.analyze_project(&project).expect("analysis");

// Access the query index after analysis
let index = analyzer.query_index();

// Query for all references to a symbol in a module scope
let refs = index.references_for(module_scope_id, "report")
    .expect("report symbol not found");

for r in refs {
    println!("{}:{}:{} {:?}",
        r.location.file, r.location.line, r.location.column, r.kind);
}

Call Sites in the Analyzer

The query index is recorded at these key points during analysis:

• Procedure declarations: When a Sub, Function, Property Get/Let/Set, or event handler is encountered, its name is recorded as a Definition at the procedure keyword position.
• Module-level declarations: Public/Private variables, constants, type definitions, and enum values are recorded as Definition at their declaration position.
• Parameters: Procedure parameters are recorded as Definition in the procedure's scope.
• Identifier tokens: Every identifier in the CST that resolves against the scope manager is recorded as Usage (value use) or TypeReference (type use in As clauses).

What Is Not Collected

Procedure-local Dim variables and Const declarations are intentionally excluded from the query index in version 1. These symbols have procedure scope and their usages are visible only within the same procedure, making the cross-reference information less valuable for the primary IDE use cases. This also keeps the index size manageable.

// These procedure-local symbols are NOT collected:
// Dim origin As Point     // "origin" not in index
// Dim value As Double     // "value" not in index

External Exposure

The query index is exposed to external consumers (IDEs, the playground, WASM hosts) through serialization. In the WASM module, each Reference is converted to WasmSymbolReference and included in the AnalysisOutput.references field alongside scopes and diagnostics.

pub struct WasmSymbolReference {
    pub scope_id: usize,
    pub name: String,           // lowercased
    pub kind: String,           // "Definition", "Usage", or "TypeReference"
    pub location: LocationInfo,  // file, line, column
    pub start_offset: u32,
    pub end_offset: u32,
    pub end_column: usize,
}

This allows JavaScript consumers in the playground or an editor extension to run semantic analysis in the browser and query the results client-side, without needing a server.

Design Decisions

' Line 1, Column 1 is the first character of the file
Attribute VB_Name = "MyModule"

Summary

The Query system in vb6semantic is a lean, bidirectional index that bridges the gap between the semantic analyzer's symbol data and the practical needs of IDE tools. By recording every resolved identifier occurrence with precise positions and byte offsets, it enables go-to-definition, find-references, and hover features with minimal overhead.

1. Two-pass collection during analysis ensures all forward references resolve correctly.
2. Bidirectional lookup -- symbol-to-occurrences and position-to-symbol -- covers the full range of IDE query patterns.
3. Case-insensitive design matches VB6 semantics exactly.
4. WASM exposure enables browser-based playgrounds and editor extensions.