Trait GraphBuilder 

pub trait GraphBuilder: Send + Sync {
    // Required methods
    fn build_graph(
        &self,
        tree: &Tree,
        content: &[u8],
        file: &Path,
        staging: &mut StagingGraph,
    ) -> GraphResult<()>;
    fn language(&self) -> Language;

    // Provided methods
    fn shape_mapping(&self) -> Option<&dyn ShapeMapping> { ... }
    fn update_graph(
        &self,
        tree: &Tree,
        content: &[u8],
        file: &Path,
        edit: &InputEdit,
        staging: &mut StagingGraph,
    ) -> GraphResult<()> { ... }
    fn detect_cross_language_edges(
        &self,
        _snapshot: &GraphSnapshot,
    ) -> GraphResult<Vec<CodeEdge>> { ... }
}

Trait implemented by all language-specific graph builders.

This trait now uses the unified graph architecture with StagingGraph buffers for transactional builds. The staging pattern enables:

• Parallel per-file building (each file gets its own staging buffer)
• Atomic commits (all-or-nothing semantics)
• Rollback on error (discards partial work)

Required Methods

fn build_graph( &self, tree: &Tree, content: &[u8], file: &Path, staging: &mut StagingGraph, ) -> GraphResult<()>

Build graph artifacts for the given file into a staging buffer.

Builders are expected to walk the supplied tree (parsed from content) and insert nodes/edges into staging. Implementations should be idempotent so repeated calls with the same inputs produce identical results.

The staging buffer will be committed to the main graph after all files in a batch are processed successfully.

Errors

Implementations return an error when the AST cannot be traversed or when extracted metadata violates graph invariants (for example, invalid spans or malformed identifiers).

fn language(&self) -> Language

The language handled by this builder.

Provided Methods

fn shape_mapping(&self) -> Option<&dyn ShapeMapping>

Per-language ShapeMapping for the identifier-blind body-shape descriptor feature, or None if this builder does not (yet) supply one.

Resolved once per file in the build seam (StagingGraph::attach_body_hashes) so the single shared compute_shape_descriptor walker can fingerprint each Function/Method body alongside its body hash. The default returns None: a language with no mapping simply contributes no shape descriptors, exactly as before this feature. Each language plugin overrides this in its own crate, so the fan-out across the 37 plugins stays parallel-safe.

fn update_graph( &self, tree: &Tree, content: &[u8], file: &Path, edit: &InputEdit, staging: &mut StagingGraph, ) -> GraphResult<()>

Incrementally update the graph after an edit.

The default implementation simply rebuilds the file from scratch. Builders that can take advantage of the edit can override this method to provide faster updates.

Errors

Implementations should return an error when incremental updates cannot be applied safely (e.g., inconsistent edit ranges or graph mutation failures).

fn detect_cross_language_edges( &self, _snapshot: &GraphSnapshot, ) -> GraphResult<Vec<CodeEdge>>

Perform any cross-language edge detection that requires whole-graph context.

Implementations can return additional edges to be merged into the graph after all files are processed. The default implementation returns an empty list, which is suitable for languages that do not emit cross-language edges.

This method receives an immutable GraphSnapshot for read-only access, enabling cross-file analysis that requires seeing all nodes.

Errors

Return an error when inspecting the graph fails (for example, if required nodes are missing or metadata cannot be deserialized).

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors