1use 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#[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#[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
29struct 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 #[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 #[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 #[serde(default)]
146 pub references: bool,
147 #[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 #[serde(default, skip_serializing_if = "Option::is_none")]
347 pub enclosing: Option<SymbolRef>,
348 pub omissions: ContextOmissions,
349 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 pub via: Option<SourceAnchor>,
383 pub excerpt: SourceAnchor,
385 pub start: crate::Position,
386 pub text: String,
387 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 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 #[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 #[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 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 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}