Skip to main content

vvv_engine/capabilities/
excerpts.rs

1//! Exact, UTF-8 aligned continuation of a declaration's captured extent.
2use super::pagination::PageSession;
3use crate::query_store::Checkpoint;
4use crate::{Cursor, Engine, EngineError, Position, SnapshotId, SourceAnchor, Span, SymbolRef};
5use serde::{Deserialize, Serialize};
6
7#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
8#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
9#[serde(deny_unknown_fields)]
10pub struct ExpandQuery {
11    pub cursor: Cursor,
12    #[cfg_attr(feature = "schema", schemars(range(min = 1024, max = 1048576)))]
13    pub max_bytes: usize,
14}
15#[derive(Debug, Clone, Serialize, Deserialize)]
16#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
17pub struct Expansion {
18    pub snapshot: SnapshotId,
19    pub target: SymbolRef,
20    /// Full extent being expanded; the excerpt is the returned subrange.
21    pub requested: SourceAnchor,
22    pub excerpt: SourceAnchor,
23    pub start: Position,
24    pub text: String,
25    pub done: bool,
26    pub next_cursor: Option<Cursor>,
27}
28#[derive(Debug, Clone, Serialize)]
29pub(crate) struct Excerpt {
30    pub target: SymbolRef,
31    pub requested: Span,
32    pub next: usize,
33}
34impl ExpandQuery {
35    pub fn execute(self, engine: &Engine) -> Result<Expansion, EngineError> {
36        let _operation = engine.operation();
37        self.execute_in(engine)
38    }
39    pub(crate) fn execute_in(self, engine: &Engine) -> Result<Expansion, EngineError> {
40        let budget = crate::PageBudget {
41            max_bytes: self.max_bytes,
42            max_items: 1,
43        };
44        budget.validate()?;
45        let (mut session, state, graph) = PageSession::resume(engine, &self.cursor, true)?;
46        let Checkpoint::Excerpt(excerpt) = state else {
47            return Err(EngineError::InvalidCursor);
48        };
49        let result = excerpt.expand(engine, &graph, &mut session, budget);
50        session.finish(engine, result)
51    }
52}
53impl Excerpt {
54    fn expand(
55        self,
56        engine: &Engine,
57        graph: &crate::graph::Graph,
58        session: &mut PageSession,
59        budget: crate::PageBudget,
60    ) -> Result<Expansion, EngineError> {
61        let file = graph.file(&self.target.declaration.path)?;
62        let text = &file.text()[self.next..self.requested.end];
63        let minimum = text.chars().next().map_or(0, char::len_utf8);
64        let mut length = text.len().min(budget.max_bytes);
65        while !text.is_char_boundary(length) {
66            length -= 1;
67        }
68        loop {
69            let after = Self {
70                target: self.target.clone(),
71                requested: self.requested,
72                next: self.next + length,
73            };
74            let done = after.next == self.requested.end;
75            let next = Checkpoint::Excerpt(after);
76            let reply = Expansion {
77                snapshot: session.root.identity.clone(),
78                target: self.target.clone(),
79                requested: SourceAnchor {
80                    span: self.requested,
81                    ..self.target.declaration.clone()
82                },
83                excerpt: SourceAnchor {
84                    span: Span::new(self.next, self.next + length),
85                    ..self.target.declaration.clone()
86                },
87                start: file.file().source().position(self.next),
88                text: text[..length].to_owned(),
89                done,
90                next_cursor: (!done).then(|| session.token(engine, &next)),
91            };
92            match budget.check(&reply) {
93                Ok(()) => {
94                    if !done {
95                        session.retain(next);
96                    }
97                    return Ok(reply);
98                }
99                Err(EngineError::OutputLimit {
100                    max_bytes,
101                    required_bytes,
102                }) => {
103                    if length == minimum {
104                        return Err(EngineError::PageOutputLimit {
105                            max_bytes,
106                            required_bytes,
107                            anchor: Some(self.target.declaration.clone()),
108                        });
109                    }
110                    length = length
111                        .saturating_sub(required_bytes - max_bytes)
112                        .max(minimum);
113                    while !text.is_char_boundary(length) {
114                        length -= 1;
115                    }
116                }
117                Err(error) => return Err(error),
118            }
119        }
120    }
121}
122impl crate::report::Document {
123    pub(crate) fn expansion(reply: &Expansion) -> Self {
124        use crate::protocol::display::{Line, Role};
125        let mut doc = Self::new();
126        doc.body([Line::single(Role::Path, reply.excerpt.path.to_string())]);
127        doc.body(
128            reply
129                .text
130                .lines()
131                .map(|line| Line::single(Role::Plain, line)),
132        );
133        doc
134    }
135}