Struct GraphBuildHelper 

pub struct GraphBuildHelper<'a> { /* private fields */ }

Helper for building graphs in GraphBuilder implementations.

Provides high-level abstractions over StagingGraph that handle:

• String interning with local ID tracking
• Qualified name deduplication
• Node and edge creation with proper types

Implementations

impl<'a> GraphBuildHelper<'a>

pub fn new( staging: &'a mut StagingGraph, file: &Path, language: Language, ) -> Self

Create a new helper for the given staging graph and file.

The file_id should be pre-allocated by the caller (typically 0 for per-file staging buffers).

pub fn with_file_id( staging: &'a mut StagingGraph, file: &Path, language: Language, file_id: FileId, ) -> Self

Create a helper with a specific file ID.

pub fn language(&self) -> Language

Get the language for this helper.

pub fn file_id(&self) -> FileId

Get the file ID for this helper.

pub fn lookup_node(&self, name: &str, kind: NodeKind) -> Option<NodeId>

Look up a node ID by its qualified name and kind from the internal cache.

Returns the NodeId if a node with the given (name, kind) pair was previously created through this helper. This is used by macro boundary analysis to find graph nodes corresponding to AST items.

pub fn file_path(&self) -> &str

Get the file path.

pub fn attach_body_hashes(&mut self, content: &[u8])

Attach body hashes to all staged nodes using the given content bytes.

Multi-language plugins (Vue, Svelte) should call this per extracted script block so that node body spans — which are relative to the block content, not the full SFC file — produce correct hashes. Nodes that already have a hash are skipped, so the later whole-file call in the indexing entrypoint is harmless.

pub fn intern(&mut self, s: &str) -> StringId

Intern a string and get a local StringId.

Strings are deduplicated: calling with the same value returns the same ID. The local StringId is passed to the staging graph so that during commit_strings(), a remap table from local to global IDs can be built.

pub fn has_node(&self, qualified_name: &str) -> bool

Check if a node with the given qualified name already exists.

pub fn get_node(&self, qualified_name: &str) -> Option<NodeId>

Get an existing node by qualified name.

pub fn has_node_with_kind(&self, qualified_name: &str, kind: NodeKind) -> bool

Check if a node with the given qualified name and kind already exists.

pub fn get_node_with_kind( &self, qualified_name: &str, kind: NodeKind, ) -> Option<NodeId>

Get an existing node by qualified name and kind.

pub fn add_function( &mut self, qualified_name: &str, span: Option<Span>, is_async: bool, is_unsafe: bool, ) -> NodeId

Add a function node with the given qualified name.

Returns the NodeId (creating the node if it doesn’t exist).

pub fn add_function_with_visibility( &mut self, qualified_name: &str, span: Option<Span>, is_async: bool, is_unsafe: bool, visibility: Option<&str>, ) -> NodeId

Add a function node with visibility.

Returns the NodeId (creating the node if it doesn’t exist).

pub fn add_function_with_signature( &mut self, qualified_name: &str, span: Option<Span>, is_async: bool, is_unsafe: bool, visibility: Option<&str>, signature: Option<&str>, ) -> NodeId

Add a function node with signature (return type).

The signature is used for returns: queries. Returns the NodeId (creating the node if it doesn’t exist).

pub fn add_method( &mut self, qualified_name: &str, span: Option<Span>, is_async: bool, is_static: bool, ) -> NodeId

Add a method node with the given qualified name.

pub fn add_method_with_visibility( &mut self, qualified_name: &str, span: Option<Span>, is_async: bool, is_static: bool, visibility: Option<&str>, ) -> NodeId

Add a method node with visibility.

pub fn add_method_with_signature( &mut self, qualified_name: &str, span: Option<Span>, is_async: bool, is_static: bool, visibility: Option<&str>, signature: Option<&str>, ) -> NodeId

Add a method node with signature (return type).

The signature is used for returns: queries. Returns the NodeId (creating the node if it doesn’t exist).

pub fn add_class(&mut self, qualified_name: &str, span: Option<Span>) -> NodeId

Add a class node.

pub fn add_class_with_visibility( &mut self, qualified_name: &str, span: Option<Span>, visibility: Option<&str>, ) -> NodeId

Add a class node with visibility.

pub fn add_struct(&mut self, qualified_name: &str, span: Option<Span>) -> NodeId

Add a struct node.

pub fn add_struct_with_visibility( &mut self, qualified_name: &str, span: Option<Span>, visibility: Option<&str>, ) -> NodeId

Add a struct node with visibility.

pub fn add_module(&mut self, qualified_name: &str, span: Option<Span>) -> NodeId

Add a module node.

pub fn add_resource( &mut self, qualified_name: &str, span: Option<Span>, ) -> NodeId

Add a resource node.

pub fn add_endpoint( &mut self, qualified_name: &str, span: Option<Span>, ) -> NodeId

Add an endpoint node for HTTP route handlers.

The qualified name should follow the convention route::{METHOD}::{path}, for example route::GET::/api/users or route::POST::/api/items.

Endpoint nodes are used by Pass 5 (cross-language linking) to match HTTP requests from client code to server-side route handlers.

pub fn add_import(&mut self, qualified_name: &str, span: Option<Span>) -> NodeId

Add an import node.

pub fn add_verbatim_import(&mut self, name: &str, span: Option<Span>) -> NodeId

Add an import node while preserving the original path-like identifier.

Use this for resource imports such as styles.css, app.js, or similar asset filenames where . is part of the path rather than a language-native qualified-name separator.

pub fn add_variable( &mut self, qualified_name: &str, span: Option<Span>, ) -> NodeId

Add a variable node.

pub fn add_verbatim_variable( &mut self, name: &str, span: Option<Span>, ) -> NodeId

Add a variable node while preserving the original identifier exactly.

Use this for static asset references where the literal path is the graph identity.

pub fn add_constant( &mut self, qualified_name: &str, span: Option<Span>, ) -> NodeId

Add a constant node.

pub fn add_constant_with_visibility( &mut self, qualified_name: &str, span: Option<Span>, visibility: Option<&str>, ) -> NodeId

Add a constant node with visibility.

pub fn add_constant_with_static_and_visibility( &mut self, qualified_name: &str, span: Option<Span>, is_static: bool, visibility: Option<&str>, ) -> NodeId

Add a constant node with static and visibility attributes.

pub fn add_property_with_static_and_visibility( &mut self, qualified_name: &str, span: Option<Span>, is_static: bool, visibility: Option<&str>, ) -> NodeId

Add a property node with static and visibility attributes.

pub fn add_enum(&mut self, qualified_name: &str, span: Option<Span>) -> NodeId

Add an enum node.

pub fn add_enum_with_visibility( &mut self, qualified_name: &str, span: Option<Span>, visibility: Option<&str>, ) -> NodeId

Add an enum node with visibility.

pub fn add_interface( &mut self, qualified_name: &str, span: Option<Span>, ) -> NodeId

Add an interface/trait node.

pub fn add_interface_with_visibility( &mut self, qualified_name: &str, span: Option<Span>, visibility: Option<&str>, ) -> NodeId

Add an interface/trait node with visibility.

pub fn add_type(&mut self, qualified_name: &str, span: Option<Span>) -> NodeId

Add a type alias node.

pub fn add_type_with_visibility( &mut self, qualified_name: &str, span: Option<Span>, visibility: Option<&str>, ) -> NodeId

Add a type alias node with visibility.

pub fn add_lifetime( &mut self, qualified_name: &str, span: Option<Span>, ) -> NodeId

Add a lifetime node.

pub fn add_lifetime_constraint_edge( &mut self, source: NodeId, target: NodeId, constraint_kind: LifetimeConstraintKind, )

Add a lifetime constraint edge.

pub fn add_trait_method_binding_edge( &mut self, caller: NodeId, callee: NodeId, trait_name: &str, impl_type: &str, is_ambiguous: bool, )

Add a trait method binding edge.

This edge represents the resolution of a trait method call to a concrete implementation.

pub fn add_macro_expansion_edge( &mut self, invocation: NodeId, expansion: NodeId, expansion_kind: MacroExpansionKind, is_verified: bool, )

Add a macro expansion edge.

Represents the expansion of a macro invocation to its generated code. Only available when macro expansion is enabled.

Arguments

• invocation - The macro invocation site node (e.g., derive attribute or macro call)
• expansion - The macro definition or generated code node
• expansion_kind - The kind of macro expansion (Derive, Attribute, Declarative, Function)
• is_verified - Whether the expansion has been verified (requires cargo expand)

Example

// #[derive(Debug)] on a struct
let struct_id = helper.add_struct("MyStruct", Some(span));
let derive_macro_id = helper.add_node("MyStruct::derive_Debug", None, NodeKind::Macro);
helper.add_macro_expansion_edge(
    struct_id,
    derive_macro_id,
    MacroExpansionKind::Derive,
    false,
);

pub fn add_node( &mut self, qualified_name: &str, span: Option<Span>, kind: NodeKind, ) -> NodeId

Add a generic node with custom kind.

pub fn add_node_with_visibility( &mut self, qualified_name: &str, span: Option<Span>, kind: NodeKind, visibility: Option<&str>, ) -> NodeId

Add a generic node with visibility.

pub fn add_call_edge(&mut self, caller: NodeId, callee: NodeId)

Add a call edge from caller to callee.

pub fn add_call_edge_with_span( &mut self, caller: NodeId, callee: NodeId, spans: Vec<Span>, )

Add a call edge from caller to callee with source span information.

The span should point to the call site location in source code.

Note

This method uses default metadata (argument_count: 255 sentinel for unknown, is_async: false). Use add_call_edge_full when you need to specify argument count or async status explicitly.

pub fn add_call_edge_full( &mut self, caller: NodeId, callee: NodeId, argument_count: u8, is_async: bool, )

Add a call edge with full metadata.

Use this method when you know the argument count or when the call is async. For calls where metadata is unknown, use add_call_edge which uses default values (argument_count: 255 sentinel, is_async: false).

Arguments

• caller - The node making the call
• callee - The node being called
• argument_count - Number of arguments in the call (0-254, use 255 for unknown)
• is_async - Whether this is an async/await call

Canonical Usage

Scenario	Method
Argument count known, sync call	add_call_edge_full(caller, callee, arg_count, false)
Argument count known, async call	add_call_edge_full(caller, callee, arg_count, true)
Argument count unknown, sync call	add_call_edge(caller, callee) or add_call_edge_full(caller, callee, 255, false)

Example

// Function call with 3 arguments
helper.add_call_edge_full(main_id, helper_id, 3, false);

// Async call with 1 argument
helper.add_call_edge_full(main_id, async_fn_id, 1, true);

pub fn add_call_edge_full_with_span( &mut self, caller: NodeId, callee: NodeId, argument_count: u8, is_async: bool, spans: Vec<Span>, )

Add a call edge with full metadata and source span information.

Combines the functionality of add_call_edge_full and span tracking.

pub fn add_table_read_edge_with_span( &mut self, reader: NodeId, table: NodeId, table_name: &str, schema: Option<&str>, spans: Vec<Span>, )

Add a database table read edge (SQL).

pub fn add_table_write_edge_with_span( &mut self, writer: NodeId, table: NodeId, table_name: &str, schema: Option<&str>, operation: TableWriteOp, spans: Vec<Span>, )

Add a database table write edge (SQL).

pub fn add_triggered_by_edge_with_span( &mut self, trigger: NodeId, table: NodeId, trigger_name: &str, schema: Option<&str>, spans: Vec<Span>, )

Add a database trigger relationship edge (SQL).

Convention: trigger -> table with EdgeKind::TriggeredBy.

pub fn add_import_edge(&mut self, importer: NodeId, imported: NodeId)

Add an import edge from importer to imported module/symbol.

This method uses default metadata (alias: None, is_wildcard: false). Use add_import_edge_full when importing with an alias or for wildcard imports.

pub fn add_import_edge_full( &mut self, importer: NodeId, imported: NodeId, alias: Option<&str>, is_wildcard: bool, )

Add an import edge with full metadata.

Use this method when the import has an alias or is a wildcard import. For simple imports without alias or wildcard, use add_import_edge.

Arguments

• importer - The node importing (e.g., module or file)
• imported - The node being imported
• alias - Optional alias string (e.g., for import { foo as bar }, alias is “bar”)
• is_wildcard - Whether this is a wildcard import (e.g., import *)

Canonical Usage

Import Syntax	Method
import foo	add_import_edge(importer, imported)
import foo as bar	add_import_edge_full(importer, imported, Some("bar"), false)
import * / import *.*	add_import_edge_full(importer, imported, None, true)
import * as ns	add_import_edge_full(importer, imported, Some("ns"), true)

Example

// import { HashMap as Map } from "std::collections"
let alias_id = helper.intern("Map");
helper.add_import_edge_full(module_id, hashmap_id, Some("Map"), false);

// import * from "lodash"
helper.add_import_edge_full(module_id, lodash_id, None, true);

pub fn add_export_edge(&mut self, module: NodeId, exported: NodeId)

Add an export edge from module to exported symbol.

This method uses default metadata (kind: ExportKind::Direct, alias: None). Use add_export_edge_full for re-exports, default exports, namespace exports, or exports with aliases.

pub fn add_export_edge_full( &mut self, module: NodeId, exported: NodeId, kind: ExportKind, alias: Option<&str>, )

Add an export edge with full metadata.

Use this method for re-exports, default exports, namespace exports, or exports with aliases. For simple direct exports without alias, use add_export_edge.

Arguments

• module - The module/file node that contains the export
• exported - The symbol being exported
• kind - The kind of export:
  • ExportKind::Direct - Direct export (export { foo })
  • ExportKind::Reexport - Re-export from another module (export { foo } from "mod")
  • ExportKind::Default - Default export (export default foo)
  • ExportKind::Namespace - Namespace export (export * as ns from "mod")
• alias - Optional alias string (e.g., for export { foo as bar }, alias is “bar”)

Canonical Usage

Export Syntax (JS/TS)	Method
export { name }	add_export_edge(module, name)
export default foo	add_export_edge_full(module, foo, ExportKind::Default, None)
export { foo as bar }	add_export_edge_full(module, foo, ExportKind::Direct, Some("bar"))
export { foo } from "mod"	add_export_edge_full(module, foo, ExportKind::Reexport, None)
export { foo as bar } from "mod"	add_export_edge_full(module, foo, ExportKind::Reexport, Some("bar"))
export * from "mod"	add_export_edge_full(module, mod, ExportKind::Reexport, None)
export * as ns from "mod"	add_export_edge_full(module, mod, ExportKind::Namespace, Some("ns"))

Example

// export default MyComponent;
helper.add_export_edge_full(module_id, component_id, ExportKind::Default, None);

// export { helper as utilHelper };
helper.add_export_edge_full(module_id, helper_id, ExportKind::Direct, Some("utilHelper"));

// export * as utils from "./utils";
helper.add_export_edge_full(module_id, utils_id, ExportKind::Namespace, Some("utils"));

pub fn add_reference_edge(&mut self, from: NodeId, to: NodeId)

Add a reference edge (variable/field access).

pub fn add_defines_edge(&mut self, parent: NodeId, child: NodeId)

Add a defines edge (module defines symbol).

pub fn add_typeof_edge(&mut self, source: NodeId, target: NodeId)

Add a type-of edge (symbol has type). Add a TypeOf edge without context metadata (backward compatibility).

For new code, prefer add_typeof_edge_with_context to provide semantic context.

pub fn add_typeof_edge_with_context( &mut self, source: NodeId, target: NodeId, context: Option<TypeOfContext>, index: Option<u16>, name: Option<&str>, )

Add a TypeOf edge with optional context metadata.

Parameters

• source: The node that has this type (e.g., variable, function, parameter)
• target: The type node
• context: Where this type reference appears (Parameter, Return, Field, Variable, etc.)
• index: Position/index (for parameters, returns, fields)
• name: Name (for parameters, returns, fields, variables)

Examples

// Function parameter: func foo(ctx context.Context)
helper.add_typeof_edge_with_context(
    func_id,
    type_id,
    Some(TypeOfContext::Parameter),
    Some(0),
    Some("ctx"),
);

// Function return: func bar() error
helper.add_typeof_edge_with_context(
    func_id,
    error_type_id,
    Some(TypeOfContext::Return),
    Some(0),
    None,
);

// Variable: var x int
helper.add_typeof_edge_with_context(
    var_id,
    int_type_id,
    Some(TypeOfContext::Variable),
    None,
    Some("x"),
);

pub fn add_implements_edge(&mut self, implementor: NodeId, interface: NodeId)

Add an implements edge (class implements interface).

pub fn add_inherits_edge(&mut self, child: NodeId, parent: NodeId)

Add an inherits edge (class extends class).

pub fn add_contains_edge(&mut self, parent: NodeId, child: NodeId)

Add a contains edge (parent contains child, e.g., class contains method).

pub fn add_webassembly_edge(&mut self, caller: NodeId, wasm_target: NodeId)

Add a WebAssembly call edge.

Used when JavaScript/TypeScript code instantiates or calls WebAssembly modules:

• WebAssembly.instantiate() / WebAssembly.instantiateStreaming()
• new WebAssembly.Module() / new WebAssembly.Instance()
• Calling exported WASM functions

pub fn add_ffi_edge( &mut self, caller: NodeId, ffi_target: NodeId, convention: FfiConvention, )

Add an FFI call edge with the specified calling convention.

Used for foreign function interface calls:

• Node.js native addons (.node files)
• ctypes/cffi in Python
• JNI in Java
• P/Invoke in C#

pub fn add_http_request_edge( &mut self, caller: NodeId, target: NodeId, method: HttpMethod, url: Option<&str>, )

Add an HTTP request edge.

Use this when detecting HTTP calls like fetch() or axios.get().

pub fn ensure_function( &mut self, qualified_name: &str, span: Option<Span>, is_async: bool, is_unsafe: bool, ) -> NodeId

Ensure a function node exists, creating it if needed.

Cross-kind reuse: if a Method node with the same canonical qualified name already exists (e.g., created during Stage 1 declaration extraction), the existing Method node is returned as-is. This prevents duplicate spanless Function nodes from being created during Stage 2 call-edge construction, which would cause get_references to silently drop callers due to location-based deduplication at (file, line=0, col=0).

The Stage 1 declaration node is authoritative for metadata — no attributes are mutated on cross-kind reuse.

pub fn ensure_method( &mut self, qualified_name: &str, span: Option<Span>, is_async: bool, is_static: bool, ) -> NodeId

Ensure a method node exists, creating it if needed.

Cross-kind reuse: if a Function node with the same canonical qualified name already exists, the existing Function node is returned as-is. See ensure_function for the rationale.

pub fn stats(&self) -> HelperStats

Get statistics about what’s been staged.

Trait Implementations

impl<'a> Debug for GraphBuildHelper<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.