Struct AnnotationStore 

pub struct AnnotationStore { /* private fields */ }

In-memory index of annotation sidecar files.

Implementations

impl AnnotationStore

pub fn new(project_root: &Path) -> Self

Create an empty store rooted at the given project directory. Uses colocated sidecar strategy by default.

pub fn with_locator( project_root: &Path, locator: Arc<dyn SidecarLocator>, ) -> Self

Create an empty store with a custom sidecar locator strategy.

pub fn locator(&self) -> &dyn SidecarLocator

Return the sidecar locator used by this store.

pub fn load_all_from_locator(&mut self) -> Vec<String>

Discover and load all sidecar files using the configured locator. Returns parse errors for files that failed to load.

pub fn load_all(&mut self, sidecar_paths: &[PathBuf]) -> Vec<String>

Load from pre-resolved sidecar paths (backward-compatible). Returns parse errors for files that failed to load.

pub fn load_file(&mut self, sidecar_path: &Path) -> Result<(), String>

Load or reload a single sidecar file. Returns Err if the sidecar exists but fails to parse. Returns Ok(()) if loaded successfully or the file was removed.

pub fn refresh_if_stale(&mut self, rel_source: &RelativePath) -> bool

Check mtime and reload if the sidecar changed. Entries with no sidecar path (extractor-only or load_xml) are skipped.

pub fn is_stale(&self, rel_source: &RelativePath) -> bool

Check whether a file’s sidecar is stale (mtime changed on disk).

Returns true if the sidecar file on disk has a newer mtime than the cached entry, or if the sidecar file no longer exists. Returns false for extractor-only entries (no sidecar path).

pub fn get_file_annotations(&self, rel_source: &str) -> Vec<&Annotation>

Get cached code element tree for a file.

Accepts a source path (src/api.ts) or sidecar path (src/api.aqm). Falls back to stem-prefix matching when an exact key is not found.

pub fn get_all_annotations(&self) -> Vec<&Annotation>

Get all annotations across all files.

pub fn get_scope_annotations(&self, scope: &Scope) -> Vec<&Annotation>

Return annotations from files whose relative path starts with scope.

pub fn select( &self, selector_str: &str, file: Option<&str>, scope: Option<&str>, opts: Option<&QueryOptions>, ) -> Result<Vec<Annotation>, AqlError>

Query annotations by selector string. If file is provided, only search that file’s annotations. If scope is provided, only search annotations under that directory prefix. Supports combinator selectors for nested annotations (e.g. parser > helper).

pub fn refresh_scope(&mut self, scope: &Scope) -> Vec<String>

Refresh all sidecar files whose rel_source starts with scope. Also discovers newly added sidecar files via the locator. Returns parse errors encountered during discovery. If scope is empty, refreshes all files.

pub fn annotations_in_scope( &self, scope: &Scope, ) -> Vec<(&RelativePath, Vec<&Annotation>)>

Get all annotations grouped by file within a scope prefix.

pub fn file_count(&self) -> usize

Number of loaded annotation files.

pub fn annotated_files(&self) -> Vec<RelativePath>

All source file paths that have annotations.

pub fn load_xml( &mut self, rel_source: &RelativePath, xml: &str, ) -> Result<(), AqlError>

Load annotations from an XML string for a given relative source path. Unlike load_file, this does not touch the filesystem. Returns Err if the XML is malformed.

pub fn load_extractor_output(&mut self, annotations: Vec<Annotation>)

Load annotations from extractor output, merging with existing sidecar data.

For bindings that already exist in sidecar files, sidecar attributes take precedence — extractor attrs are only used as defaults.