use std::io::Cursor;
use std::path::Path;
use std::process::Command;
use anyhow::{bail, Result};
use flate2::read::GzDecoder;
use super::{
collect_doc_files, detect_docs_path, to_entry_files, DocFile, FetchMeta, FetchResult,
NPM_DOC_CANDIDATES,
};
use crate::http::HttpClient;
use crate::store::{
acquire_entry_lock, lexical_clean, npm_store_path, stamp_entry, write_entry_atomic,
};
#[derive(Debug, Clone, Default)]
pub struct NpmOptions {
pub name: String,
pub version: String,
pub package: Option<String>,
pub docs_path: Option<String>,
}
pub fn fetch(
client: &dyn HttpClient,
opts: &NpmOptions,
project_dir: &Path,
ask_home: &Path,
) -> Result<FetchResult> {
let pkg = opts.package.as_deref().unwrap_or(&opts.name);
if let Some(mut local) =
try_local_read(project_dir, pkg, &opts.version, opts.docs_path.as_deref())
{
write_to_store(ask_home, pkg, &local.resolved_version, &local.files)?;
local.store_path = Some(npm_store_path(ask_home, pkg, &local.resolved_version)?);
return Ok(local);
}
fetch_from_tarball(client, opts, pkg, ask_home)
}
fn version_matches(requested: &str, installed: &str) -> bool {
if requested == "latest" {
return true;
}
if semver::Version::parse(requested).is_ok() {
return requested == installed;
}
if let (Ok(req), Ok(v)) = (
semver::VersionReq::parse(requested),
semver::Version::parse(installed),
) {
return req.matches(&v);
}
requested == installed
}
pub fn try_local_read(
project_dir: &Path,
pkg: &str,
requested_version: &str,
docs_path: Option<&str>,
) -> Option<FetchResult> {
let docs_path = docs_path?;
let pkg_dir = project_dir.join("node_modules").join(pkg);
let pkg_json = pkg_dir.join("package.json");
let meta_text = std::fs::read_to_string(&pkg_json).ok()?;
let installed_version = serde_json::from_str::<serde_json::Value>(&meta_text)
.ok()?
.get("version")?
.as_str()?
.to_string();
if !version_matches(requested_version, &installed_version) {
return None;
}
let docs_dir = pkg_dir.join(docs_path);
if !lexical_clean(&docs_dir).starts_with(lexical_clean(&pkg_dir)) {
return None;
}
if !docs_dir.exists() {
return None;
}
let real_pkg = std::fs::canonicalize(&pkg_dir).ok()?;
let real_docs = std::fs::canonicalize(&docs_dir).ok()?;
if !real_docs.starts_with(&real_pkg) {
return None;
}
let files = if docs_dir.is_file() {
let content = std::fs::read_to_string(&docs_dir).ok()?;
let name = docs_dir.file_name()?.to_string_lossy().into_owned();
vec![DocFile {
path: name,
content,
}]
} else {
collect_doc_files(&docs_dir, &docs_dir).ok()?
};
if files.is_empty() {
return None;
}
Some(FetchResult {
files,
resolved_version: installed_version,
store_path: None,
store_subpath: None,
from_store_cache: false,
meta: FetchMeta {
install_path: Some(pkg_dir),
..Default::default()
},
})
}
fn npm_view(spec: &str, field: &str) -> Result<String> {
let output = Command::new("npm").args(["view", spec, field]).output()?;
if !output.status.success() {
bail!(
"npm view {spec} {field} failed: {}",
String::from_utf8_lossy(&output.stderr).trim()
);
}
Ok(String::from_utf8_lossy(&output.stdout).trim().to_string())
}
fn fetch_from_tarball(
client: &dyn HttpClient,
opts: &NpmOptions,
pkg: &str,
ask_home: &Path,
) -> Result<FetchResult> {
let spec = format!("{pkg}@{}", opts.version);
let resolved_version = npm_view(&spec, "version")?;
let tarball_url = npm_view(&spec, "dist.tarball")?;
let integrity = npm_view(&spec, "dist.integrity")
.ok()
.filter(|s| !s.is_empty());
let response = client.get_bytes(&tarball_url, &[])?;
if !response.ok() {
bail!("Failed to download {tarball_url}: HTTP {}", response.status);
}
let tmp = tempfile::Builder::new().prefix("ask-npm-").tempdir()?;
let decoder = GzDecoder::new(Cursor::new(&response.body));
tar::Archive::new(decoder).unpack(tmp.path())?;
let package_dir = tmp.path().join("package");
let docs_path = opts
.docs_path
.clone()
.or_else(|| detect_docs_path(&package_dir, NPM_DOC_CANDIDATES))
.ok_or_else(|| {
anyhow::anyhow!(
"No docs found in {spec}. Specify --docs-path to point to the docs directory \
within the package."
)
})?;
let docs_dir = package_dir.join(&docs_path);
if !lexical_clean(&docs_dir).starts_with(lexical_clean(&package_dir)) {
bail!("Docs path \"{docs_path}\" escapes the package directory in {spec}.");
}
if !docs_dir.exists() {
bail!(
"Docs path \"{docs_path}\" not found in {spec}. Available paths:\n{}",
list_dirs(&package_dir)
);
}
let real_pkg = std::fs::canonicalize(&package_dir)?;
let real_docs = std::fs::canonicalize(&docs_dir)?;
if !real_docs.starts_with(&real_pkg) {
bail!("Docs path \"{docs_path}\" resolves outside the package directory in {spec}.");
}
let files = if docs_dir.is_file() {
let content = std::fs::read_to_string(&docs_dir)?;
let name = docs_dir
.file_name()
.map(|n| n.to_string_lossy().into_owned())
.unwrap_or_default();
vec![DocFile {
path: name,
content,
}]
} else {
collect_doc_files(&docs_dir, &docs_dir)?
};
write_to_store(ask_home, pkg, &resolved_version, &files)?;
Ok(FetchResult {
files,
resolved_version: resolved_version.clone(),
store_path: Some(npm_store_path(ask_home, pkg, &resolved_version)?),
store_subpath: None,
from_store_cache: false,
meta: FetchMeta {
tarball: Some(tarball_url),
integrity,
..Default::default()
},
})
}
fn list_dirs(dir: &Path) -> String {
let Ok(entries) = std::fs::read_dir(dir) else {
return String::new();
};
let mut names: Vec<String> = entries
.flatten()
.filter(|e| e.file_type().map(|t| t.is_dir()).unwrap_or(false))
.map(|e| format!(" - {}/", e.file_name().to_string_lossy()))
.collect();
names.sort();
names.join("\n")
}
fn write_to_store(ask_home: &Path, pkg: &str, version: &str, files: &[DocFile]) -> Result<()> {
let store_dir = npm_store_path(ask_home, pkg, version)?;
if store_dir.exists() {
return Ok(());
}
if let Some(lock) = acquire_entry_lock(&store_dir)? {
write_entry_atomic(&store_dir, &to_entry_files(files))?;
stamp_entry(&store_dir)?;
drop(lock);
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn version_matches_node_semver_semantics() {
assert!(version_matches("latest", "9.9.9"));
assert!(version_matches("1.2.3", "1.2.3"));
assert!(!version_matches("1.2.3", "1.2.4"));
assert!(version_matches("^1.2.0", "1.5.0"));
assert!(!version_matches("^1.2.0", "2.0.0"));
assert!(version_matches("~3.22.0", "3.22.9"));
assert!(version_matches("canary", "canary"));
assert!(!version_matches("canary", "1.0.0"));
}
fn setup_pkg(project: &Path, pkg: &str, version: &str) -> std::path::PathBuf {
let pkg_dir = project.join("node_modules").join(pkg);
std::fs::create_dir_all(&pkg_dir).unwrap();
std::fs::write(
pkg_dir.join("package.json"),
format!(r#"{{"name":"{pkg}","version":"{version}"}}"#),
)
.unwrap();
pkg_dir
}
#[test]
fn local_read_returns_docs_when_version_matches() {
let dir = tempfile::tempdir().unwrap();
let pkg_dir = setup_pkg(dir.path(), "acme", "2.0.0");
std::fs::create_dir_all(pkg_dir.join("dist/docs")).unwrap();
std::fs::write(pkg_dir.join("dist/docs/a.md"), "A").unwrap();
let result = try_local_read(dir.path(), "acme", "2.0.0", Some("dist/docs")).unwrap();
assert_eq!(result.resolved_version, "2.0.0");
assert_eq!(
result.files,
vec![DocFile {
path: "a.md".into(),
content: "A".into()
}]
);
assert_eq!(result.meta.install_path.as_deref(), Some(pkg_dir.as_path()));
}
#[test]
fn local_read_none_without_docs_path() {
let dir = tempfile::tempdir().unwrap();
setup_pkg(dir.path(), "acme", "2.0.0");
assert!(try_local_read(dir.path(), "acme", "2.0.0", None).is_none());
}
#[test]
fn local_read_none_on_version_mismatch() {
let dir = tempfile::tempdir().unwrap();
let pkg_dir = setup_pkg(dir.path(), "acme", "1.0.0");
std::fs::create_dir_all(pkg_dir.join("docs")).unwrap();
std::fs::write(pkg_dir.join("docs/a.md"), "A").unwrap();
assert!(try_local_read(dir.path(), "acme", "2.0.0", Some("docs")).is_none());
}
#[test]
fn local_read_none_on_traversal_docs_path() {
let dir = tempfile::tempdir().unwrap();
setup_pkg(dir.path(), "acme", "2.0.0");
assert!(try_local_read(dir.path(), "acme", "2.0.0", Some("../../etc")).is_none());
}
#[test]
fn local_read_none_when_empty_docs_dir() {
let dir = tempfile::tempdir().unwrap();
let pkg_dir = setup_pkg(dir.path(), "acme", "2.0.0");
std::fs::create_dir_all(pkg_dir.join("docs")).unwrap();
assert!(try_local_read(dir.path(), "acme", "2.0.0", Some("docs")).is_none());
}
#[test]
fn local_read_single_file_docs_path() {
let dir = tempfile::tempdir().unwrap();
let pkg_dir = setup_pkg(dir.path(), "acme", "2.0.0");
std::fs::write(pkg_dir.join("README.md"), "readme").unwrap();
let result = try_local_read(dir.path(), "acme", "2.0.0", Some("README.md")).unwrap();
assert_eq!(
result.files,
vec![DocFile {
path: "README.md".into(),
content: "readme".into()
}]
);
}
#[test]
fn fetch_writes_local_read_into_store() {
let dir = tempfile::tempdir().unwrap();
let ask_home = dir.path().join("ask-home");
let pkg_dir = setup_pkg(dir.path(), "acme", "2.0.0");
std::fs::create_dir_all(pkg_dir.join("docs")).unwrap();
std::fs::write(pkg_dir.join("docs/a.md"), "A").unwrap();
let client = crate::http::mock::MockClient::new();
let opts = NpmOptions {
name: "acme".into(),
version: "2.0.0".into(),
docs_path: Some("docs".into()),
..Default::default()
};
let result = fetch(&client, &opts, dir.path(), &ask_home).unwrap();
let store = result.store_path.unwrap();
assert!(store.ends_with("npm/acme@2.0.0"));
assert!(store.join("a.md").exists());
}
}