explaine.rs

The ExplorationState struct is used to maintain the current position during an exploration session. It tracks:

• location_index: The current index in the list of syntax node locations.
• comment_index: The current index in the list of comments.

This state must be passed to the Analyzer during iteration to ensure the process can resume or continue correctly through the source file.

The analyzer provides semantic context for paths and how they relate to receivers:

• Special Path Segments: Recognizes super, self, Self, and crate as specific path components.
• Receiver Context: When self is used in a path, the analyzer determines if it is a ReceiverPath by looking up the ancestor method signature to find the method name.
• QSelf: Identifies <T> as Trait syntax via HelpItem::QSelf, noting if it is an as_trait operation.
• Path Separators: Identifies the :: colon separator in paths.

The IR uses two main types for addressing parts of the source code:

• NodeId: A wrapper around usize used as a unique identifier for nodes in the syntax tree.
• Location: Represents a specific point in the source code using a 1-based line and a 0-based column.

To start the development environment, run the start.sh script located in the etc/ directory. This script performs two main actions:

1. Executes ./etc/build-wasm.sh to compile WebAssembly components.
2. Runs npx vite to launch the Vite development server.

The script uses set -e, meaning it will exit immediately if any command fails.

./etc/start.sh

To use the playground SDK, you must first call initialize(debug: bool). If debug is set to true, it will initialize logging (when the dev feature is enabled).

// In the WASM environment
initialize(true);

To transform a Rust source file into an analyzed intermediate representation, use IrVisitor::new followed by .visit().

IrVisitor::new takes a syn::File (the parsed AST) and the original source code as a String. The .visit() method performs the traversal, handles comment association, and returns a crate::analysis::Analyzer containing the processed NodeMap and sorted locations.

let visitor = IrVisitor::new(parsed_file, source_string);
let analyzer = visitor.visit();

Use Session::explain(line: usize, column: usize) to query the analyzer for a specific Explanation at a given line and column. This is useful for targeted lookups rather than full exploration.

// Returns Option<Explanation>
if let Some(explanation) = session.explain(10, 5) {
    // Use the explanation
}

An Explanation object contains metadata about a specific code insight. You can extract the following information:

• start_line, start_column, end_line, end_column: The coordinates of the item.
• .elaborate(): Returns a JsValue containing the detailed message.
• .title(): Returns a JsValue containing the title of the help item.
• .info(): Returns a Box<[JsValue]> containing a flattened list of links and metadata types associated with the help item.

// Assuming 'explanation' is an Explanation object
let title = explanation.title();
let message = explanation.elaborate();
let info_items = explanation.info(); // Array of [link, kind, link, kind, ...]

The Syn wrapper implements From<&'a Syn<'b>> for SynKind. This allows you to easily map a specific syn syntax node to its corresponding SynKind enum variant, which is useful for categorizing or dispatching logic based on the type of syntax node being processed.

// Convert a specific syn node to a SynKind
let kind = SynKind::from(some_syn_node);

The ExplorationIterator allows for sequential exploration of a Rust source file. It iterates through a provided source of Location objects (representing syntax nodes) and then continues to iterate through non-doc comments. This is useful for building tools that need to surface help items for both code elements and the comments surrounding them.

// I is an iterator of Location
let mut state = ExplorationState::default();
let iterator = ExplorationIterator {
    analyzer,
    state: &mut state,
    source: location_iterator,
};

for item in iterator {
    if let Some(analysis) = item {
        // Handle the AnalysisResult
    }
}