Skip to main content

lockdocs_core/
upstream.rs

1//! Upstream docs: many packages ship no documentation (Next.js, Django,
2//! FastAPI...). Their repositories do, under the exact version's git tag.
3//! This module finds the repository from the package's own metadata, finds
4//! the tag for the pinned version, and downloads only the docs folders
5//! (Markdown, MDX, reStructuredText) from GitHub into the cache, once.
6//! First-use queries fetch public docs at an immutable release commit. Explicit
7//! `fetch` also supports major-version docs sites and optional GitHub credentials.
8
9use serde::{Deserialize, Serialize};
10
11mod archive;
12mod cache_entry;
13mod client;
14mod docs_sites;
15mod fetch;
16mod git_refs;
17mod github_files;
18mod package_docs;
19mod repository;
20
21pub use cache_entry::{cached, dir, needs_refresh, stale};
22pub use fetch::{fetch, fetch_automatic, fetch_private};
23pub use git_refs::tag_candidates;
24pub use repository::{parse_github, repo_of, repo_of_with};
25
26const MAX_FILES: usize = 2500;
27const MAX_BYTES: u64 = 40 * 1024 * 1024;
28const MAX_FILE: u64 = 2 * 1024 * 1024;
29
30#[derive(Debug, Clone, PartialEq)]
31pub struct Repo {
32    pub owner: String,
33    pub name: String,
34    /// Package directory inside a monorepo (npm `repository.directory`).
35    pub subdir: Option<String>,
36    /// The git host when it is not github.com (lockdocs Pro private sources).
37    pub host: Option<crate::private::Origin>,
38}
39
40/// Bump when what `fetch` downloads changes, so `lockdocs fetch` refreshes
41/// older copies (a stale copy is still used until then).
42pub const FORMAT: u32 = 7;
43
44#[derive(Debug, Clone, Serialize, Deserialize)]
45pub struct Manifest {
46    /// `FORMAT` when downloaded (0 before it existed).
47    #[serde(default)]
48    pub format: u32,
49    pub repo: String,
50    pub tag: Option<String>,
51    /// Immutable package-repository commit resolved from the release tag.
52    #[serde(default)]
53    pub commit: Option<String>,
54    /// Explicit enrichment completed a docs-site lookup (including a genuine empty result).
55    #[serde(default)]
56    pub docs_sites_checked: bool,
57    pub files: usize,
58    pub bytes: u64,
59    /// Why nothing was downloaded, when files == 0.
60    pub note: Option<String>,
61    /// A separate docs-site repository also included (see `DOCS_SITES`).
62    #[serde(default)]
63    pub site: Option<String>,
64    /// Docs pages written as JS/TSX components, relative to the cache folder.
65    #[serde(default)]
66    pub pages: Vec<String>,
67    /// How the package repository was read: `codeload` (one tarball) or `rest`
68    /// (the per-file fallback, after a codeload failure or an over-size archive).
69    #[serde(default)]
70    pub via: Option<String>,
71}
72
73#[cfg(test)]
74mod tests;