Skip to main content

vvv_engine/capabilities/
context.rs

1//! Bounded, evidence-bearing context for one exact symbol. No semantic service required.
2use super::incoming::{DiscoveryWork, IncomingReferences};
3use crate::graph::Graph;
4use crate::{
5    ContentId, Engine, EngineError, NavigationOrigin, NavigationOutcome, NavigationQuery,
6    Selection, SnapshotId, SourceAnchor, SourceVersion, Span, SymbolRef, UnavailableReason,
7};
8use serde::{Deserialize, Serialize};
9
10/// Source detail requested for every context item. Bodies remain the default.
11#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
12#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
13#[serde(rename_all = "snake_case")]
14pub enum ContextDetail {
15    #[default]
16    Body,
17    Signature,
18}
19
20/// Present only for signature requests; absence preserves the body contract.
21#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
22#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
23#[serde(tag = "outcome", rename_all = "snake_case")]
24pub enum ContextSignature {
25    Available { requested: SourceAnchor },
26    Unsupported,
27}
28
29/// The selected source range, shared by one-shot and paged assembly.
30struct ContextExtent {
31    span: Span,
32    signature: Option<ContextSignature>,
33}
34impl ContextExtent {
35    fn capture(
36        detail: ContextDetail,
37        target: &SymbolRef,
38        file: &crate::Candidate,
39    ) -> Result<Self, EngineError> {
40        let declaration = target.declaration.span;
41        if detail == ContextDetail::Body {
42            return Ok(Self {
43                span: declaration,
44                signature: None,
45            });
46        }
47        let span = file
48            .facts()?
49            .signatures
50            .iter()
51            .find(|signature| signature.name_span == target.name_span)
52            .map(|signature| signature.span)
53            .filter(|span| {
54                declaration.contains(span)
55                    && span.contains(&target.name_span)
56                    && file.text().get(span.start..span.end).is_some()
57            });
58        Ok(match span {
59            Some(span) => Self {
60                span,
61                signature: Some(ContextSignature::Available {
62                    requested: SourceAnchor {
63                        span,
64                        ..target.declaration.clone()
65                    },
66                }),
67            },
68            None => Self {
69                span: Span::new(declaration.start, declaration.start),
70                signature: Some(ContextSignature::Unsupported),
71            },
72        })
73    }
74    fn supported(&self) -> bool {
75        !matches!(self.signature, Some(ContextSignature::Unsupported))
76    }
77}
78
79#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
80#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
81#[serde(default, deny_unknown_fields)]
82pub struct ContextBudget {
83    /// Maximum compact JSON bytes in the result, excluding the response envelope.
84    #[cfg_attr(feature = "schema", schemars(range(min = Self::MIN_BYTES, max = Self::MAX_BYTES)))]
85    pub max_bytes: usize,
86    #[cfg_attr(feature = "schema", schemars(range(min = 1, max = Self::MAX_ITEMS)))]
87    pub max_items: usize,
88    #[cfg_attr(feature = "schema", schemars(range(min = 1, max = Self::MAX_LOOKUPS)))]
89    pub max_lookups: usize,
90    /// Maximum source files examined for incoming written-name and named-alias references.
91    #[cfg_attr(feature = "schema", schemars(range(min = 1, max = Self::MAX_FILES)))]
92    pub max_files: usize,
93}
94impl Default for ContextBudget {
95    fn default() -> Self {
96        Self {
97            max_bytes: Self::DEFAULT_BYTES,
98            max_items: Self::DEFAULT_ITEMS,
99            max_lookups: Self::DEFAULT_LOOKUPS,
100            max_files: Self::DEFAULT_FILES,
101        }
102    }
103}
104impl ContextBudget {
105    pub const MIN_BYTES: usize = 1024;
106    pub const MAX_BYTES: usize = 1_048_576;
107    pub const MAX_ITEMS: usize = 64;
108    pub const MAX_LOOKUPS: usize = 512;
109    pub const MAX_FILES: usize = 1024;
110    pub const DEFAULT_BYTES: usize = 16_384;
111    pub const DEFAULT_ITEMS: usize = 12;
112    pub const DEFAULT_LOOKUPS: usize = 64;
113    pub const DEFAULT_FILES: usize = 64;
114
115    pub const MAXIMUM: Self = Self {
116        max_bytes: Self::MAX_BYTES,
117        max_items: Self::MAX_ITEMS,
118        max_lookups: Self::MAX_LOOKUPS,
119        max_files: Self::MAX_FILES,
120    };
121
122    pub fn validate(&self) -> Result<(), EngineError> {
123        if !(Self::MIN_BYTES..=Self::MAX_BYTES).contains(&self.max_bytes)
124            || !(1..=Self::MAX_ITEMS).contains(&self.max_items)
125            || !(1..=Self::MAX_LOOKUPS).contains(&self.max_lookups)
126            || !(1..=Self::MAX_FILES).contains(&self.max_files)
127        {
128            return Err(EngineError::InvalidBudget);
129        }
130        Ok(())
131    }
132}
133
134#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
135#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
136pub struct ContextQuery {
137    pub origin: NavigationOrigin,
138    #[serde(default)]
139    pub detail: ContextDetail,
140    #[serde(default)]
141    pub selection: Selection,
142    #[serde(default)]
143    pub budget: ContextBudget,
144    /// Include incoming written-name and named-import-alias references, validated by navigation.
145    #[serde(default)]
146    pub references: bool,
147    /// Include the enclosing declaration at the requested detail as a separate item.
148    #[serde(default)]
149    pub include_enclosing: bool,
150}
151impl ContextQuery {
152    pub fn new(origin: NavigationOrigin) -> Self {
153        Self {
154            origin,
155            detail: ContextDetail::Body,
156            selection: Selection::All,
157            budget: ContextBudget::default(),
158            references: false,
159            include_enclosing: false,
160        }
161    }
162    pub fn execute(self, engine: &Engine) -> Result<ContextReply, EngineError> {
163        let _operation = engine.operation();
164        self.execute_in(&mut *engine.graph()?)
165    }
166    pub(crate) fn execute_in(self, graph: &mut Graph) -> Result<ContextReply, EngineError> {
167        self.budget.validate()?;
168        let mut observed = Vec::new();
169        let reply = graph.navigate_observed(
170            NavigationQuery {
171                origin: self.origin,
172                selection: self.selection,
173            },
174            &mut observed,
175        )?;
176        let mut context = ContextReply {
177            snapshot: reply.snapshot.clone(),
178            outcome: ContextOutcome::Resolved,
179            items: vec![],
180            enclosing: None,
181            omissions: ContextOmissions::default(),
182            references_by_name: self.references,
183        };
184        let mut snapshots = vec![reply.snapshot];
185        match reply.outcome {
186            NavigationOutcome::Unavailable { reason } => {
187                context.outcome = ContextOutcome::Unavailable { reason }
188            }
189            NavigationOutcome::Ambiguous { candidates } => {
190                context.outcome = ContextOutcome::Ambiguous {
191                    candidates: candidates
192                        .into_iter()
193                        .map(|c| ContextCandidate {
194                            id: c.declaration.id,
195                            target: c.target,
196                        })
197                        .collect(),
198                };
199            }
200            NavigationOutcome::Resolved {
201                target, preview, ..
202            } => {
203                let name = preview
204                    .declaration
205                    .symbol
206                    .as_ref()
207                    .expect("navigation declaration")
208                    .name
209                    .clone();
210                let enclosing = ContextPending::enclosing(&target, &preview.source.symbols);
211                context.enclosing = enclosing.as_ref().map(|item| item.target.clone());
212                let file = graph.file(&target.declaration.path)?;
213                let selected = ContextExtent::capture(self.detail, &target, &file)?;
214                context.add(
215                    ContextPending {
216                        target: target.clone(),
217                        relation: ContextRelation::Definition,
218                        via: None,
219                    },
220                    &file,
221                    self.detail,
222                    &self.budget,
223                )?;
224                if self.include_enclosing
225                    && let Some(item) = enclosing
226                {
227                    context.add(item, &file, self.detail, &self.budget)?;
228                }
229                let mut lookups = 0;
230                for anchor in preview.identifiers {
231                    graph.check_read()?;
232                    if anchor.span == target.name_span || !selected.span.contains(&anchor.span) {
233                        continue;
234                    }
235                    if lookups == self.budget.max_lookups {
236                        context.omissions.lookup_limit += 1;
237                        continue;
238                    }
239                    lookups += 1;
240                    let reply = graph.navigate_observed(
241                        NavigationQuery::occurrence(anchor.clone()),
242                        &mut observed,
243                    )?;
244                    snapshots.push(reply.snapshot);
245                    match reply.outcome {
246                        NavigationOutcome::Resolved {
247                            target: related, ..
248                        } => {
249                            if let Some(item) = ContextPending::outgoing(&target, related, anchor) {
250                                let file = graph.file(&item.target.declaration.path)?;
251                                context.add(item, &file, self.detail, &self.budget)?;
252                            }
253                        }
254                        other => context.omissions.resolution(&other),
255                    }
256                }
257                if self.references {
258                    let files = graph
259                        .relationship_files(&target.language, &crate::SearchScope::default())?;
260                    context.omissions.file_limit =
261                        files.len().saturating_sub(self.budget.max_files);
262                    for file in files.into_iter().take(self.budget.max_files) {
263                        observed.push(SourceVersion {
264                            path: file.path().into(),
265                            content: file.file().content_id(),
266                        });
267                        let mut incoming = IncomingReferences::new(&file, &name, false)?;
268                        let mut discovery = DiscoveryWork {
269                            lookups,
270                            max_lookups: self.budget.max_lookups,
271                            unresolved_imports: 0,
272                        };
273                        let ready = incoming.prepare(
274                            graph,
275                            &file,
276                            &target,
277                            &mut discovery,
278                            &mut observed,
279                        )?;
280                        lookups = discovery.lookups;
281                        context.omissions.unresolved_imports += discovery.unresolved_imports;
282                        if !ready {
283                            context.omissions.lookup_limit += 1;
284                            break;
285                        }
286                        for (_, _, span) in file.facts()?.tokens().filter(|(name, _, span)| {
287                            incoming.names().contains(*name)
288                                && !(file.path() == target.declaration.path.as_path()
289                                    && *span == target.name_span)
290                        }) {
291                            if lookups == self.budget.max_lookups {
292                                context.omissions.lookup_limit += 1;
293                                continue;
294                            }
295                            lookups += 1;
296                            let anchor = SourceAnchor {
297                                path: file.path().into(),
298                                content: file.file().content_id(),
299                                span,
300                            };
301                            let reply = graph.navigate_observed(
302                                NavigationQuery::occurrence(anchor.clone()),
303                                &mut observed,
304                            )?;
305                            snapshots.push(reply.snapshot);
306                            match reply.outcome {
307                                NavigationOutcome::Resolved { target: found, .. }
308                                    if found == target =>
309                                {
310                                    if let Some(item) =
311                                        ContextPending::incoming(&target, anchor, &file)?
312                                    {
313                                        context.add(item, &file, self.detail, &self.budget)?;
314                                    } else {
315                                        context.omissions.no_container += 1;
316                                    }
317                                }
318                                NavigationOutcome::Resolved { .. } => {}
319                                other => context.omissions.resolution(&other),
320                            }
321                        }
322                    }
323                }
324            }
325        }
326        graph.validate_versions(&observed)?;
327        let identity = match self.detail {
328            ContextDetail::Body => serde_json::to_string(&(snapshots, observed)),
329            ContextDetail::Signature => serde_json::to_string(&(snapshots, observed, self.detail)),
330        }
331        .expect("context inputs serialize");
332        context.snapshot = ContentId::of(&identity).into();
333        context.fit(&self.budget)?;
334        Ok(context)
335    }
336}
337
338#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
339#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
340pub struct ContextReply {
341    pub snapshot: SnapshotId,
342    #[serde(flatten)]
343    pub outcome: ContextOutcome,
344    pub items: Vec<ContextItem>,
345    /// Location of the enclosing declaration, without repeating its body.
346    #[serde(default, skip_serializing_if = "Option::is_none")]
347    pub enclosing: Option<SymbolRef>,
348    pub omissions: ContextOmissions,
349    /// Incoming scanning follows written names and resolvable named import aliases, without runtime inference.
350    pub references_by_name: bool,
351}
352#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
353#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
354#[serde(tag = "outcome", rename_all = "snake_case")]
355pub enum ContextOutcome {
356    Resolved,
357    Ambiguous { candidates: Vec<ContextCandidate> },
358    Unavailable { reason: UnavailableReason },
359}
360#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
361#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
362pub struct ContextCandidate {
363    pub id: crate::MatchId,
364    pub target: SymbolRef,
365}
366#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
367#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
368#[serde(rename_all = "snake_case")]
369pub enum ContextRelation {
370    Definition,
371    EnclosingDeclaration,
372    ReferencedDefinition,
373    Reference,
374    ReferenceInTestPath,
375}
376#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
377#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
378pub struct ContextItem {
379    pub target: SymbolRef,
380    pub relation: ContextRelation,
381    /// The exact occurrence establishing this relationship; absent for the seed.
382    pub via: Option<SourceAnchor>,
383    /// Range of the returned text, which can be shorter than the target extent.
384    pub excerpt: SourceAnchor,
385    pub start: crate::Position,
386    pub text: String,
387    /// Complete for the requested detail, not necessarily the whole declaration.
388    pub complete: bool,
389    #[serde(default, skip_serializing_if = "Option::is_none")]
390    pub signature: Option<ContextSignature>,
391}
392#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
393#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
394pub struct ContextOmissions {
395    pub item_limit: usize,
396    pub byte_limit: usize,
397    pub lookup_limit: usize,
398    pub file_limit: usize,
399    pub ambiguous: usize,
400    pub unavailable: usize,
401    pub no_container: usize,
402    #[serde(default)]
403    pub unresolved_imports: usize,
404}
405impl ContextOmissions {
406    fn resolution(&mut self, outcome: &NavigationOutcome) {
407        match outcome {
408            NavigationOutcome::Ambiguous { .. } => self.ambiguous += 1,
409            NavigationOutcome::Unavailable { .. } => self.unavailable += 1,
410            _ => {}
411        }
412    }
413}
414impl ContextReply {
415    fn add(
416        &mut self,
417        pending: ContextPending,
418        file: &crate::Candidate,
419        detail: ContextDetail,
420        budget: &ContextBudget,
421    ) -> Result<(), EngineError> {
422        let ContextPending {
423            target,
424            relation,
425            via,
426        } = pending;
427        let source = file.text();
428        if (self.enclosing.as_ref() == Some(&target)
429            && relation != ContextRelation::EnclosingDeclaration)
430            || self.items.iter().any(|item| item.target == target)
431        {
432            return Ok(());
433        }
434        if self.items.len() >= budget.max_items {
435            self.omissions.item_limit += 1;
436            return Ok(());
437        }
438        let selected = ContextExtent::capture(detail, &target, file)?;
439        let extent = selected.span;
440        let mut end = extent
441            .end
442            .min(extent.start.saturating_add(budget.max_bytes / 2));
443        while !source.is_char_boundary(end) {
444            end -= 1;
445        }
446        let excerpt = SourceAnchor {
447            span: Span::new(extent.start, end),
448            ..target.declaration.clone()
449        };
450        let complete = selected.supported() && end == extent.end;
451        if end < extent.end {
452            self.omissions.byte_limit += 1;
453        }
454        self.items.push(ContextItem {
455            start: vvv_core::text::LineIndex::new(source).position(source, extent.start),
456            target,
457            relation,
458            via,
459            text: source[extent.start..end].to_owned(),
460            excerpt,
461            complete,
462            signature: selected.signature,
463        });
464        Ok(())
465    }
466    fn fit(&mut self, budget: &ContextBudget) -> Result<(), EngineError> {
467        loop {
468            let bytes = serde_json::to_vec(self).expect("context serializes").len();
469            if bytes <= budget.max_bytes {
470                return Ok(());
471            }
472            if let Some(item) = self.items.last_mut() {
473                if !item.text.is_empty() {
474                    let mut end = item
475                        .text
476                        .len()
477                        .saturating_sub((bytes - budget.max_bytes).max(1));
478                    while !item.text.is_char_boundary(end) {
479                        end -= 1;
480                    }
481                    item.text.truncate(end);
482                    item.excerpt.span.end = item.excerpt.span.start + end;
483                    if item.complete {
484                        self.omissions.byte_limit += 1;
485                    }
486                    item.complete = false;
487                } else {
488                    if matches!(item.signature, Some(ContextSignature::Unsupported)) {
489                        self.omissions.byte_limit += 1;
490                    }
491                    self.items.pop();
492                }
493            } else {
494                // Never return a silently shortened ambiguity candidate set.
495                return Err(EngineError::OutputLimit {
496                    max_bytes: budget.max_bytes,
497                    required_bytes: bytes,
498                });
499            }
500        }
501    }
502}
503
504impl crate::report::Document {
505    pub(crate) fn context(reply: &ContextReply) -> Self {
506        use crate::protocol::display::{Line, Role};
507        let mut doc = Self::new();
508        match &reply.outcome {
509            ContextOutcome::Unavailable { reason } => {
510                doc.notes([Line::single(Role::Dim, reason.message())])
511            }
512            ContextOutcome::Ambiguous { candidates } => {
513                doc.notes([Line::single(
514                    Role::Dim,
515                    "Several definitions match; use --select with a match id",
516                )]);
517                for candidate in candidates {
518                    doc.body([Line::single(Role::Plain, candidate.id.to_string())
519                        .and(Role::Plain, " ")
520                        .and(Role::Path, candidate.target.declaration.path.to_string())]);
521                }
522            }
523            ContextOutcome::Resolved => {}
524        }
525        for item in &reply.items {
526            let label = match item.relation {
527                ContextRelation::Definition => "Definition",
528                ContextRelation::EnclosingDeclaration => "Enclosing declaration",
529                ContextRelation::ReferencedDefinition => "Referenced definition",
530                ContextRelation::Reference => "Confirmed reference",
531                ContextRelation::ReferenceInTestPath => "Confirmed reference in a test path",
532            };
533            doc.body([Line::single(Role::Strong, label)
534                .and(Role::Plain, "  ")
535                .and(Role::Path, item.excerpt.path.to_string())
536                .and(
537                    Role::LineNumber,
538                    format!(":{}:{}", item.start.line + 1, item.start.column + 1),
539                )]);
540            doc.body(item.text.lines().map(|s| Line::single(Role::Plain, s)));
541            if matches!(item.signature, Some(ContextSignature::Unsupported)) {
542                doc.notes([Line::single(Role::Dim, "Signature extraction is not supported for this declaration; request body detail")]);
543            } else if !item.complete {
544                doc.notes([Line::single(
545                    Role::Dim,
546                    "Excerpt shortened by the output budget",
547                )]);
548            }
549        }
550        let omissions = &reply.omissions;
551        if [
552            omissions.item_limit,
553            omissions.byte_limit,
554            omissions.lookup_limit,
555            omissions.file_limit,
556            omissions.ambiguous,
557            omissions.unavailable,
558            omissions.no_container,
559        ]
560        .iter()
561        .any(|count| *count != 0)
562        {
563            doc.notes([Line::single(Role::Dim, format!("Omitted: {} item limit, {} byte limit, {} lookup limit, {} file limit, {} ambiguous, {} unavailable, {} without a declaration", omissions.item_limit, omissions.byte_limit, omissions.lookup_limit, omissions.file_limit, omissions.ambiguous, omissions.unavailable, omissions.no_container))]);
564        }
565        if omissions.unresolved_imports > 0 {
566            doc.notes([Line::single(
567                Role::Dim,
568                format!(
569                    "{} import bindings could not be resolved during reference discovery",
570                    omissions.unresolved_imports
571                ),
572            )]);
573        }
574        doc
575    }
576}
577
578#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
579#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
580#[serde(deny_unknown_fields)]
581pub struct ContextPageQuery {
582    pub origin: NavigationOrigin,
583    #[serde(default)]
584    pub detail: ContextDetail,
585    #[serde(default)]
586    pub selection: Selection,
587    #[serde(default)]
588    pub references: bool,
589    /// Include the enclosing declaration at the requested detail as a separate item.
590    #[serde(default)]
591    pub include_enclosing: bool,
592    #[serde(default)]
593    pub page: crate::PageBudget,
594    #[serde(default)]
595    pub work: crate::WorkBudget,
596}
597#[derive(Debug, Clone, Serialize, Deserialize)]
598#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
599#[serde(tag = "kind", rename = "context")]
600pub struct ContextPage {
601    pub snapshot: SnapshotId,
602    #[serde(flatten)]
603    pub outcome: ContextOutcome,
604    pub items: Vec<PagedContextItem>,
605    #[serde(default, skip_serializing_if = "Option::is_none")]
606    pub enclosing: Option<SymbolRef>,
607    pub references_by_name: bool,
608    pub work: ContextWork,
609    pub unresolved: ContextUnresolved,
610    pub traversal_complete: bool,
611    pub next_cursor: Option<crate::Cursor>,
612}
613#[derive(Debug, Clone, Serialize, Deserialize)]
614#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
615pub struct PagedContextItem {
616    #[serde(flatten)]
617    pub item: ContextItem,
618    pub expansion: Option<crate::Cursor>,
619    /// In signature mode, retrieve the entire declaration from its beginning.
620    #[serde(default, skip_serializing_if = "Option::is_none")]
621    pub body_expansion: Option<crate::Cursor>,
622}
623#[derive(Debug, Default, Clone, Serialize, Deserialize)]
624#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
625pub struct ContextWork {
626    pub lookups: usize,
627    pub files: usize,
628}
629#[derive(Debug, Default, Clone, Serialize, Deserialize)]
630#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
631pub struct ContextUnresolved {
632    pub ambiguous: usize,
633    pub unavailable: usize,
634    pub no_container: usize,
635    #[serde(default)]
636    pub unresolved_imports: usize,
637}
638impl ContextUnresolved {
639    fn resolution(&mut self, outcome: &NavigationOutcome) {
640        match outcome {
641            NavigationOutcome::Ambiguous { .. } => self.ambiguous += 1,
642            NavigationOutcome::Unavailable { .. } => self.unavailable += 1,
643            _ => {}
644        }
645    }
646}
647#[derive(Debug, Serialize)]
648pub(crate) struct ContextSeed {
649    detail: ContextDetail,
650    outcome: ContextOutcome,
651    target: Option<SymbolRef>,
652    name: String,
653    initial: Vec<ContextPending>,
654    enclosing: Option<SymbolRef>,
655    outgoing: Vec<SourceAnchor>,
656    incoming: Vec<crate::RelPath>,
657    references: bool,
658}
659#[derive(Debug, Clone, Serialize)]
660struct ContextPending {
661    target: SymbolRef,
662    relation: ContextRelation,
663    via: Option<SourceAnchor>,
664}
665#[derive(Debug, Default, Clone, Serialize)]
666pub(crate) struct ContextSession {
667    initial: usize,
668    outgoing: usize,
669    file: usize,
670    incoming: Option<IncomingReferences>,
671    seen: Vec<SymbolRef>,
672    pending: Option<ContextPending>,
673}
674impl ContextPageQuery {
675    pub fn execute(self, engine: &Engine) -> Result<ContextPage, EngineError> {
676        let _operation = engine.operation();
677        self.execute_in(engine)
678    }
679    pub(crate) fn execute_in(self, engine: &Engine) -> Result<ContextPage, EngineError> {
680        self.page.validate()?;
681        self.work.validate()?;
682        let (mut graph, snapshot) = crate::graph::query_snapshot::QuerySnapshot::capture(engine)?;
683        let seed = ContextSeed::capture(&mut graph, &self)?;
684        let identity = (
685            &self.origin,
686            &self.selection,
687            self.references,
688            self.include_enclosing,
689            self.detail,
690        );
691        let state = ContextSession {
692            seen: if self.include_enclosing {
693                vec![]
694            } else {
695                seed.enclosing.clone().into_iter().collect()
696            },
697            ..Default::default()
698        };
699        let mut session = super::pagination::PageSession::new(
700            engine,
701            snapshot,
702            &identity,
703            crate::query_store::QueryData::Context(seed),
704        );
705        let result = state.page(engine, &mut graph, &mut session, self.page, self.work);
706        match session.finish(engine, result)? {
707            crate::PageReply::Context(page) => Ok(page),
708            _ => unreachable!("capability returns its own page"),
709        }
710    }
711}
712impl ContextSeed {
713    fn capture(graph: &mut Graph, query: &ContextPageQuery) -> Result<Self, EngineError> {
714        let reply = graph.navigate_observed(
715            NavigationQuery {
716                origin: query.origin.clone(),
717                selection: query.selection.clone(),
718            },
719            &mut vec![],
720        )?;
721        let mut seed = Self {
722            detail: query.detail,
723            outcome: ContextOutcome::Resolved,
724            target: None,
725            name: String::new(),
726            initial: vec![],
727            enclosing: None,
728            outgoing: vec![],
729            incoming: vec![],
730            references: query.references,
731        };
732        match reply.outcome {
733            NavigationOutcome::Unavailable { reason } => {
734                seed.outcome = ContextOutcome::Unavailable { reason }
735            }
736            NavigationOutcome::Ambiguous { candidates } => {
737                seed.outcome = ContextOutcome::Ambiguous {
738                    candidates: candidates
739                        .into_iter()
740                        .map(|c| ContextCandidate {
741                            id: c.declaration.id,
742                            target: c.target,
743                        })
744                        .collect(),
745                }
746            }
747            NavigationOutcome::Resolved {
748                target, preview, ..
749            } => {
750                seed.name = preview
751                    .declaration
752                    .symbol
753                    .as_ref()
754                    .expect("navigation declaration")
755                    .name
756                    .to_string();
757                seed.initial.push(ContextPending {
758                    target: target.clone(),
759                    relation: ContextRelation::Definition,
760                    via: None,
761                });
762                if let Some(item) = ContextPending::enclosing(&target, &preview.source.symbols) {
763                    seed.enclosing = Some(item.target.clone());
764                    if query.include_enclosing {
765                        seed.initial.push(item);
766                    }
767                }
768                let file = graph.file(&target.declaration.path)?;
769                let selected = ContextExtent::capture(query.detail, &target, &file)?;
770                seed.outgoing = preview
771                    .identifiers
772                    .into_iter()
773                    .filter(|a| a.span != target.name_span && selected.span.contains(&a.span))
774                    .collect();
775                if query.references {
776                    seed.incoming = graph
777                        .relationship_files(&target.language, &crate::SearchScope::default())?
778                        .iter()
779                        .map(|f| f.path().into())
780                        .collect();
781                }
782                seed.target = Some(target);
783            }
784        }
785        Ok(seed)
786    }
787}
788impl ContextSession {
789    fn done(&self, seed: &ContextSeed) -> bool {
790        self.pending.is_none()
791            && self.initial == seed.initial.len()
792            && self.outgoing == seed.outgoing.len()
793            && self.file == seed.incoming.len()
794    }
795    /// Resolve at most the additional work budget. A pending item survives delivery stops.
796    fn advance(
797        &mut self,
798        graph: &mut Graph,
799        seed: &ContextSeed,
800        budget: &crate::WorkBudget,
801        page: &mut ContextPage,
802        charged_file: &mut Option<usize>,
803    ) -> Result<(), EngineError> {
804        while self.pending.is_none() && !self.done(seed) {
805            graph.check_read()?;
806            if self.initial < seed.initial.len() {
807                self.pending = Some(seed.initial[self.initial].clone());
808                self.initial += 1;
809            } else if self.outgoing < seed.outgoing.len() {
810                if page.work.lookups == budget.max_lookups {
811                    break;
812                }
813                let anchor = seed.outgoing[self.outgoing].clone();
814                self.outgoing += 1;
815                page.work.lookups += 1;
816                let reply = graph
817                    .navigate_observed(NavigationQuery::occurrence(anchor.clone()), &mut vec![])?;
818                match reply.outcome {
819                    NavigationOutcome::Resolved { target, .. } => {
820                        let original = seed.target.as_ref().expect("resolved context");
821                        self.pending = ContextPending::outgoing(original, target, anchor);
822                    }
823                    other => page.unresolved.resolution(&other),
824                }
825            } else {
826                if *charged_file != Some(self.file) {
827                    if page.work.files == budget.max_files {
828                        break;
829                    }
830                    page.work.files += 1;
831                    *charged_file = Some(self.file);
832                }
833                let file = graph.file(&seed.incoming[self.file])?;
834                let original = seed.target.as_ref().expect("resolved context");
835                if self.incoming.is_none() {
836                    self.incoming = Some(IncomingReferences::new(&file, &seed.name, false)?);
837                }
838                let incoming = self.incoming.as_mut().expect("current file discovery");
839                let mut discovery = DiscoveryWork {
840                    lookups: page.work.lookups,
841                    max_lookups: budget.max_lookups,
842                    unresolved_imports: 0,
843                };
844                let ready =
845                    incoming.prepare(graph, &file, original, &mut discovery, &mut vec![])?;
846                page.work.lookups = discovery.lookups;
847                page.unresolved.unresolved_imports += discovery.unresolved_imports;
848                if !ready {
849                    break;
850                }
851                if incoming.sites.is_none() {
852                    incoming.sites = Some(
853                        file.facts()?
854                            .tokens()
855                            .filter(|(name, _, span)| {
856                                incoming.names().contains(*name)
857                                    && !(file.path() == original.declaration.path.as_path()
858                                        && *span == original.name_span)
859                            })
860                            .map(|(_, _, span)| span)
861                            .collect(),
862                    );
863                }
864                let Some(&span) = incoming
865                    .sites
866                    .as_ref()
867                    .expect("discovered sites")
868                    .get(incoming.site)
869                else {
870                    self.file += 1;
871                    self.incoming = None;
872                    continue;
873                };
874                if page.work.lookups == budget.max_lookups {
875                    break;
876                }
877                incoming.site += 1;
878                page.work.lookups += 1;
879                let anchor = SourceAnchor {
880                    path: file.path().into(),
881                    content: file.file().content_id(),
882                    span,
883                };
884                let reply = graph
885                    .navigate_observed(NavigationQuery::occurrence(anchor.clone()), &mut vec![])?;
886                match reply.outcome {
887                    NavigationOutcome::Resolved { target, .. } if &target == original => {
888                        self.pending = ContextPending::incoming(original, anchor, &file)?;
889                        if self.pending.is_none() {
890                            page.unresolved.no_container += 1;
891                        }
892                    }
893                    other => page.unresolved.resolution(&other),
894                }
895            }
896            if self
897                .pending
898                .as_ref()
899                .is_some_and(|p| self.seen.contains(&p.target))
900            {
901                self.pending = None;
902            }
903        }
904        Ok(())
905    }
906    pub(crate) fn page(
907        mut self,
908        engine: &Engine,
909        graph: &mut Graph,
910        session: &mut super::pagination::PageSession,
911        budget: crate::PageBudget,
912        work: crate::WorkBudget,
913    ) -> Result<crate::PageReply, EngineError> {
914        use crate::{
915            PageReply,
916            query_store::{Checkpoint, QueryData},
917        };
918        let root = session.root.clone();
919        let QueryData::Context(seed) = &root.data else {
920            return Err(EngineError::InvalidCursor);
921        };
922        let mut page = ContextPage {
923            enclosing: seed.enclosing.clone(),
924            snapshot: root.identity.clone(),
925            outcome: seed.outcome.clone(),
926            items: vec![],
927            references_by_name: seed.references,
928            work: ContextWork::default(),
929            unresolved: ContextUnresolved::default(),
930            traversal_complete: false,
931            next_cursor: None,
932        };
933        let mut charged_file = None;
934        while page.items.len() < budget.max_items {
935            engine.check_read()?;
936            self.advance(graph, seed, &work, &mut page, &mut charged_file)?;
937            let Some(pending) = self.pending.clone() else {
938                break;
939            };
940            let source = graph.file(&pending.target.declaration.path)?;
941            let selected = ContextExtent::capture(seed.detail, &pending.target, &source)?;
942            let extent = selected.span;
943            let body =
944                (seed.detail == ContextDetail::Signature).then(|| super::excerpts::Excerpt {
945                    target: pending.target.clone(),
946                    requested: pending.target.declaration.span,
947                    next: pending.target.declaration.span.start,
948                });
949            let text = &source.text()[extent.start..extent.end];
950            let mut end = text.len().min(budget.max_bytes);
951            while !text.is_char_boundary(end) {
952                end -= 1;
953            }
954            let mut after = self.clone();
955            after.pending = None;
956            after.seen.push(pending.target.clone());
957            page.traversal_complete = after.done(seed);
958            page.next_cursor = (!page.traversal_complete)
959                .then(|| session.token(engine, &Checkpoint::Context(after.clone())));
960            let minimum = text.chars().next().map_or(0, char::len_utf8);
961            let mut accepted = None;
962            loop {
963                let excerpt = super::excerpts::Excerpt {
964                    target: pending.target.clone(),
965                    requested: extent,
966                    next: extent.start + end,
967                };
968                let expansion = (end < text.len())
969                    .then(|| session.token(engine, &Checkpoint::Excerpt(excerpt.clone())));
970                page.items.push(PagedContextItem {
971                    item: ContextItem {
972                        target: pending.target.clone(),
973                        relation: pending.relation,
974                        via: pending.via.clone(),
975                        excerpt: SourceAnchor {
976                            span: Span::new(extent.start, extent.start + end),
977                            ..pending.target.declaration.clone()
978                        },
979                        start: source.file().source().position(extent.start),
980                        text: text[..end].to_owned(),
981                        complete: selected.supported() && end == text.len(),
982                        signature: selected.signature.clone(),
983                    },
984                    expansion,
985                    body_expansion: body.as_ref().map(|excerpt| {
986                        session.token(engine, &Checkpoint::Excerpt(excerpt.clone()))
987                    }),
988                });
989                match budget.check(&PageReply::Context(page.clone())) {
990                    Ok(()) => {
991                        accepted = Some(excerpt);
992                        break;
993                    }
994                    Err(EngineError::OutputLimit {
995                        max_bytes,
996                        required_bytes,
997                    }) => {
998                        page.items.pop();
999                        if end == minimum {
1000                            if page.items.is_empty() {
1001                                return Err(EngineError::PageOutputLimit {
1002                                    max_bytes,
1003                                    required_bytes,
1004                                    anchor: Some(pending.target.declaration.clone()),
1005                                });
1006                            }
1007                            break;
1008                        }
1009                        end = end.saturating_sub(required_bytes - max_bytes).max(minimum);
1010                        while !text.is_char_boundary(end) {
1011                            end -= 1;
1012                        }
1013                    }
1014                    Err(error) => return Err(error),
1015                }
1016            }
1017            let Some(excerpt) = accepted else {
1018                break;
1019            };
1020            if excerpt.next < extent.end {
1021                session.retain(Checkpoint::Excerpt(excerpt));
1022            }
1023            if let Some(body) = body {
1024                session.retain(Checkpoint::Excerpt(body));
1025            }
1026            self = after;
1027        }
1028        page.traversal_complete = self.done(seed);
1029        let checkpoint = Checkpoint::Context(self);
1030        page.next_cursor = (!page.traversal_complete).then(|| session.token(engine, &checkpoint));
1031        let reply = PageReply::Context(page);
1032        budget.check(&reply)?;
1033        if reply.next_cursor().is_some() {
1034            session.retain(checkpoint);
1035        }
1036        Ok(reply)
1037    }
1038}
1039impl crate::report::Document {
1040    pub(crate) fn context_page(page: &ContextPage) -> Self {
1041        let context = ContextReply {
1042            enclosing: page.enclosing.clone(),
1043            snapshot: page.snapshot.clone(),
1044            outcome: page.outcome.clone(),
1045            items: page.items.iter().map(|p| p.item.clone()).collect(),
1046            omissions: ContextOmissions {
1047                ambiguous: page.unresolved.ambiguous,
1048                unavailable: page.unresolved.unavailable,
1049                no_container: page.unresolved.no_container,
1050                unresolved_imports: page.unresolved.unresolved_imports,
1051                ..Default::default()
1052            },
1053            references_by_name: page.references_by_name,
1054        };
1055        Self::context(&context)
1056    }
1057}
1058
1059impl ContextPending {
1060    /// Shared relationship rules for one-shot and paged context assembly.
1061    fn enclosing(target: &SymbolRef, symbols: &[crate::Symbol]) -> Option<Self> {
1062        let outer = symbols
1063            .iter()
1064            .filter(|s| {
1065                s.extent != target.declaration.span && s.extent.contains(&target.declaration.span)
1066            })
1067            .min_by_key(|s| s.extent.len())?;
1068        Some(Self {
1069            target: SymbolRef {
1070                language: target.language.clone(),
1071                declaration: SourceAnchor {
1072                    span: outer.extent,
1073                    ..target.declaration.clone()
1074                },
1075                name_span: outer.name_span,
1076                kind: outer.kind,
1077            },
1078            relation: ContextRelation::EnclosingDeclaration,
1079            via: Some(target.declaration.clone()),
1080        })
1081    }
1082    fn outgoing(original: &SymbolRef, target: SymbolRef, anchor: SourceAnchor) -> Option<Self> {
1083        if target.declaration.path == original.declaration.path
1084            && original.declaration.span.contains(&target.declaration.span)
1085        {
1086            return None;
1087        }
1088        Some(Self {
1089            target,
1090            relation: ContextRelation::ReferencedDefinition,
1091            via: Some(anchor),
1092        })
1093    }
1094    fn incoming(
1095        original: &SymbolRef,
1096        anchor: SourceAnchor,
1097        file: &crate::Candidate,
1098    ) -> Result<Option<Self>, EngineError> {
1099        let Some(outer) = file
1100            .facts()?
1101            .symbols
1102            .iter()
1103            .filter(|s| s.extent.contains(&anchor.span))
1104            .min_by_key(|s| s.extent.len())
1105        else {
1106            return Ok(None);
1107        };
1108        let target = SymbolRef {
1109            language: original.language.clone(),
1110            declaration: SourceAnchor {
1111                span: outer.extent,
1112                ..anchor.clone()
1113            },
1114            name_span: outer.name_span,
1115            kind: outer.kind,
1116        };
1117        let relation = if file
1118            .path()
1119            .components()
1120            .any(|c| c.as_os_str() == "test" || c.as_os_str() == "tests")
1121        {
1122            ContextRelation::ReferenceInTestPath
1123        } else {
1124            ContextRelation::Reference
1125        };
1126        Ok(Some(Self {
1127            target,
1128            relation,
1129            via: Some(anchor),
1130        }))
1131    }
1132}