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;