Skip to main content

lockdocs_core/
query.rs

1//! The three questions agents ask: which versions do I have (`resolve`),
2//! what do the docs say about X (`docs`), and what exactly is this symbol
3//! (`api`). Answers are token-budgeted and cite `package@version path:line`.
4
5mod api;
6mod docs;
7mod entries;
8mod packages;
9mod ranking;
10mod render;
11mod workspace;
12
13#[cfg(test)]
14mod tests;
15
16pub use ranking::redirects;
17pub use render::render_entry;
18
19use crate::index::PackageIndex;
20use crate::project::Project;
21use serde_json::Value;
22use std::collections::HashMap;
23use std::path::{Path, PathBuf};
24use std::sync::{Arc, Mutex};
25
26pub const DEFAULT_TOKENS: usize = 1200;
27
28#[derive(Debug, Clone, PartialEq, Eq)]
29pub struct Options {
30    /// Allow downloading exact versions that are not installed.
31    pub fetch: bool,
32    /// Anonymous release-tag docs on first use; independent of registry downloads.
33    pub upstream: bool,
34    /// lockdocs Pro: read the private registries and git hosts the user has
35    /// configured. Set by the binary after it has verified the licence; the
36    /// core never decides this itself.
37    pub private: bool,
38}
39
40impl Default for Options {
41    fn default() -> Self {
42        let mut fetch = std::env::var("LOCKDOCS_FETCH").is_ok_and(|v| matches!(v.as_str(), "1" | "true" | "yes"));
43        let mut upstream = automatic_upstream(std::env::var("LOCKDOCS_FETCH").ok().as_deref(), std::env::var("LOCKDOCS_NO_UPSTREAM").is_ok());
44        if std::env::var("LOCKDOCS_OFFLINE").is_ok_and(|v| v != "0") {
45            fetch = false;
46            upstream = false;
47        }
48        Options {
49            fetch,
50            upstream,
51            private: false,
52        }
53    }
54}
55
56fn automatic_upstream(fetch: Option<&str>, disabled: bool) -> bool {
57    !disabled && !fetch.is_some_and(|v| matches!(v, "0" | "false" | "no"))
58}
59
60pub struct Answer {
61    pub text: String,
62    pub json: Value,
63}
64
65pub struct Engine {
66    pub project: Project,
67    opts: Options,
68    indexes: Mutex<HashMap<String, Arc<PackageIndex>>>,
69    upstream_notes: Mutex<HashMap<String, String>>,
70    /// Packages that needed a private source this engine was not licensed to read.
71    private_blocked: Mutex<Vec<crate::private::PrivateRequired>>,
72}
73
74impl Engine {
75    pub fn new(root: &Path, opts: Options) -> Engine {
76        Engine {
77            project: Project::load(root),
78            opts,
79            indexes: Mutex::new(HashMap::new()),
80            upstream_notes: Mutex::new(HashMap::new()),
81            private_blocked: Mutex::new(Vec::new()),
82        }
83    }
84
85    /// The packages that needed a private source without Pro since the last
86    /// call. The binary turns a non-empty list into the `pro_required` answer.
87    pub fn take_private_blocked(&self) -> Vec<crate::private::PrivateRequired> {
88        std::mem::take(&mut *self.private_blocked.lock().unwrap())
89    }
90
91    pub fn root(&self) -> &Path {
92        &self.project.root
93    }
94}
95
96/// Where the engine keeps its per-root state for long-running servers.
97#[derive(Default)]
98pub struct Workspace {
99    engines: Mutex<HashMap<PathBuf, (u64, Arc<Engine>)>>,
100}