Skip to main content

vvv_engine/capabilities/
semantic.rs

1//! Host-supplied semantic navigation. All positions are absolute UTF-8 byte spans.
2use crate::{ContentId, RelPath, SourceAnchor, SymbolRef};
3use serde::{Deserialize, Serialize};
4use std::sync::{
5    Arc,
6    atomic::{AtomicBool, Ordering},
7};
8
9#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
10#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
11pub struct ProviderVersion {
12    pub provider: String,
13    pub revision: String,
14}
15
16#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
17#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
18pub struct SourceVersion {
19    pub path: RelPath,
20    pub content: ContentId,
21}
22
23#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
24pub struct SemanticRequest {
25    pub version: ProviderVersion,
26    pub origin: SourceAnchor,
27    /// The exact source against which a protocol adapter converts positions.
28    pub source: String,
29}
30
31#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
32#[serde(tag = "kind", rename_all = "snake_case")]
33pub enum SemanticTarget {
34    Workspace {
35        symbol: SymbolRef,
36    },
37    /// External locations stay explicit; the engine does not read provider URIs.
38    External {
39        uri: String,
40        content: ContentId,
41        span: crate::Span,
42    },
43}
44
45#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
46pub struct SemanticReply {
47    pub version: ProviderVersion,
48    pub origin: SourceAnchor,
49    /// Every consulted workspace source/configuration, beyond origin and targets.
50    pub dependencies: Vec<SourceVersion>,
51    /// The complete candidate set, never a preferred candidate.
52    pub targets: Vec<SemanticTarget>,
53}
54
55#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
56#[serde(rename_all = "snake_case")]
57pub enum SemanticFailure {
58    Unavailable,
59    Incomplete,
60    Cancelled,
61}
62
63/// A provider revision must change whenever any semantic input changes, including
64/// build options and external dependencies. Providers must be bounded, cooperate
65/// with cancellation, and must not re-enter this engine while answering.
66pub trait NavigationProvider: Send + Sync {
67    fn version(&self) -> ProviderVersion;
68    fn navigate(
69        &self,
70        request: &SemanticRequest,
71        cancellation: &NavigationCancellation,
72    ) -> Result<SemanticReply, SemanticFailure>;
73}
74
75#[derive(Debug, Clone, Default)]
76pub struct NavigationCancellation(Arc<AtomicBool>);
77impl NavigationCancellation {
78    pub fn cancel(&self) {
79        self.0.store(true, Ordering::Release);
80    }
81    pub fn is_cancelled(&self) -> bool {
82        self.0.load(Ordering::Acquire)
83    }
84    pub(crate) fn check(&self) -> Result<(), crate::EngineError> {
85        if self.is_cancelled() {
86            Err(crate::EngineError::NavigationCancelled)
87        } else {
88            Ok(())
89        }
90    }
91}
92
93pub(crate) struct SemanticNavigation<'a> {
94    pub provider: &'a dyn NavigationProvider,
95    pub cancellation: &'a NavigationCancellation,
96}