use super::Analysis;
use super::modules::Export;
use crate::project::Package;
use crate::toolchain::rustdoc::{self, Library};
use serde::Deserialize;
use serde::de::IgnoredAny;
use serde_json::Value;
use std::collections::HashMap;
use std::sync::Arc;
pub(crate) enum Listing {
Read,
Compiled(Arc<Documented>),
Refused(String),
}
impl Analysis {
pub(super) fn listing(&self, package: &Package, module: &[String]) -> Listing {
if !self.krate(package).opaque(module) {
return Listing::Read;
}
let mut asked = self.documented.lock().unwrap_or_else(|p| p.into_inner());
let answer = asked.entry(package.lib.clone()).or_insert_with(|| {
let library = Library { package: &package.name, name: &package.lib, dir: &package.dir };
let text = rustdoc::document(&library, &self.project.work.join("doc"))?;
Documented::read(&text).map(Arc::new)
});
match answer {
Ok(documented) => Listing::Compiled(Arc::clone(documented)),
Err(why) => Listing::Refused(why.clone()),
}
}
}
const EXPORTED: [&str; 7] = ["constant", "static", "function", "struct", "union", "trait", "type_alias"];
type Id = u32;
#[derive(Deserialize)]
pub(crate) struct Documented {
root: Id,
index: HashMap<Id, Item>,
paths: HashMap<Id, Declared>,
}
#[derive(Deserialize)]
struct Item {
name: Option<String>,
visibility: Visibility,
inner: Inner,
}
#[derive(Deserialize)]
#[serde(rename_all = "snake_case")]
enum Visibility {
Public,
Default,
Crate,
Restricted(IgnoredAny),
}
#[derive(Deserialize)]
#[serde(try_from = "HashMap<String, Value>")]
enum Inner {
Module(Vec<Id>),
Enum(Vec<Id>),
Use(Use),
Other(String),
}
#[derive(Deserialize)]
struct Use {
name: String,
id: Option<Id>,
is_glob: bool,
}
#[derive(Deserialize)]
struct Declared {
crate_id: u32,
path: Vec<String>,
}
impl TryFrom<HashMap<String, Value>> for Inner {
type Error = String;
fn try_from(tagged: HashMap<String, Value>) -> Result<Inner, String> {
#[derive(Deserialize)]
struct Module {
items: Vec<Id>,
}
#[derive(Deserialize)]
struct Enum {
variants: Vec<Id>,
}
let (kind, body) = tagged.into_iter().next().ok_or("an item of no kind")?;
let unreadable = |err: serde_json::Error| format!("{kind}: {err}");
Ok(match kind.as_str() {
"module" => Inner::Module(serde_json::from_value::<Module>(body).map_err(unreadable)?.items),
"enum" => Inner::Enum(serde_json::from_value::<Enum>(body).map_err(unreadable)?.variants),
"use" => Inner::Use(serde_json::from_value(body).map_err(unreadable)?),
_ => Inner::Other(kind),
})
}
}
impl Documented {
pub(crate) fn read(text: &str) -> Result<Documented, String> {
#[derive(Deserialize)]
struct Format {
format_version: u32,
}
let unreadable = |why: String| match serde_json::from_str::<Format>(text) {
Ok(Format { format_version }) => {
format!("rustdoc's JSON (format {format_version}) is not one this adapter reads: {why}")
}
Err(_) => format!("rustdoc's JSON cannot be read: {why}"),
};
let documented: Documented = serde_json::from_str(text).map_err(|err| unreadable(err.to_string()))?;
match documented.index.get(&documented.root).map(|root| &root.inner) {
Some(Inner::Module(_)) => Ok(documented),
_ => Err(unreadable("its root is not a module".to_string())),
}
}
pub(crate) fn exports(&self, path: &[String]) -> Option<Vec<Export>> {
let mut out = Vec::new();
self.list(self.module(path)?, &mut Vec::new(), &mut out);
Some(out)
}
fn module(&self, path: &[String]) -> Option<&[Id]> {
let mut items = self.held(self.root)?;
for name in path {
items = items.iter().find_map(|id| {
let named = self.index.get(id)?.name.as_deref() == Some(name.as_str());
self.held(*id).filter(|_| named)
})?;
}
Some(items)
}
fn held(&self, id: Id) -> Option<&[Id]> {
match &self.index.get(&id)?.inner {
Inner::Module(items) => Some(items),
_ => None,
}
}
fn list(&self, items: &[Id], seen: &mut Vec<Id>, out: &mut Vec<Export>) {
for id in items {
let Some(item) = self.index.get(id).filter(|item| matches!(item.visibility, Visibility::Public))
else {
continue;
};
let named =
|name: &str, declared: Id| Export { name: name.to_string(), origin: self.declared(declared) };
let export = match (&item.inner, &item.name) {
(Inner::Use(used), _) if used.is_glob => {
self.list_whole(used.id, seen, out);
None
}
(Inner::Use(used), _) => {
Some(Export { name: used.name.clone(), origin: used.id.and_then(|id| self.declared(id)) })
}
(Inner::Enum(_), Some(name)) => Some(named(name, *id)),
(Inner::Other(kind), Some(name)) if EXPORTED.contains(&kind.as_str()) => {
Some(named(name, *id))
}
_ => None,
};
add(out, export);
}
}
fn list_whole(&self, whole: Option<Id>, seen: &mut Vec<Id>, out: &mut Vec<Export>) {
let Some(whole) = whole.filter(|id| !seen.contains(id)) else { return };
seen.push(whole);
match self.index.get(&whole).map(|item| &item.inner) {
Some(Inner::Module(items)) => self.list(items, seen, out),
Some(Inner::Enum(variants)) => {
let names = variants.iter().filter_map(|id| self.index.get(id)?.name.clone());
names.for_each(|name| add(out, Some(Export { name, origin: self.declared(whole) })));
}
_ => {}
}
}
fn declared(&self, id: Id) -> Option<(Vec<String>, String)> {
let place = self.paths.get(&id).filter(|place| place.crate_id == 0)?;
let (name, module) = place.path.split_last()?;
Some((module.iter().skip(1).cloned().collect(), name.clone()))
}
}
fn add(out: &mut Vec<Export>, export: Option<Export>) {
out.extend(export.filter(|export| !out.iter().any(|held| held.name == export.name)));
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn documented() -> Documented {
let item = |name: Value, visibility: &str, inner: Value| json!({ "name": name, "visibility": visibility, "inner": inner });
let reexport = |name: &str, id: u32, is_glob: bool| {
item(Value::Null, "public", json!({ "use": { "name": name, "id": id, "is_glob": is_glob } }))
};
let whole = json!({
"format_version": 61,
"root": 0,
"index": {
"0": item(json!("c"), "public", json!({ "module": { "items": [1, 2, 3, 4, 5, 9, 10, 11] } })),
"1": item(json!("low"), "crate", json!({ "module": { "items": [6, 7] } })),
"2": reexport("low", 1, true),
"3": reexport("Renamed", 6, false),
"4": item(json!("by_macro"), "public", json!({ "function": {} })),
"5": item(json!("HIDDEN"), "crate", json!({ "constant": {} })),
"6": item(json!("Low"), "public", json!({ "struct": {} })),
"7": item(json!("deep"), "public", json!({ "module": { "items": [8] } })),
"8": item(json!("below"), "public", json!({ "function": {} })),
"9": reexport("Map", 20, false),
"10": item(json!("Kind"), "public", json!({ "enum": { "variants": [12] } })),
"11": reexport("Kind", 10, true),
"12": item(json!("Small"), "default", json!({ "variant": {} })),
"13": item(json!("make"), "public", json!({ "macro": "macro_rules! make" })),
},
"paths": {
"4": { "crate_id": 0, "path": ["c", "by_macro"] },
"6": { "crate_id": 0, "path": ["c", "low", "Low"] },
"10": { "crate_id": 0, "path": ["c", "Kind"] },
"20": { "crate_id": 1, "path": ["std", "collections", "HashMap"] },
},
});
Documented::read(&whole.to_string()).unwrap()
}
fn path(written: &str) -> Vec<String> {
written.split("::").filter(|segment| !segment.is_empty()).map(str::to_string).collect()
}
#[test]
fn exports_are_what_the_compiler_lists() {
let exports = documented().exports(&[]).unwrap();
let export = |name: &str, origin: Option<(&str, &str)>| Export {
name: name.to_string(),
origin: origin.map(|(module, name)| (path(module), name.to_string())),
};
let want = [
export("Low", Some(("low", "Low"))),
export("Renamed", Some(("low", "Low"))),
export("by_macro", Some(("", "by_macro"))),
export("Map", None),
export("Kind", Some(("", "Kind"))),
export("Small", Some(("", "Kind"))),
];
assert_eq!(exports, want);
}
#[test]
fn a_module_is_found_by_its_path() {
let documented = documented();
let names = |module: &str| {
documented.exports(&path(module)).map(|all| all.into_iter().map(|e| e.name).collect::<Vec<_>>())
};
assert_eq!(names("low::deep"), Some(vec!["below".to_string()]));
assert_eq!(names("nowhere"), None);
}
#[test]
fn output_of_another_shape_is_refused() {
let refused = |text: &str| Documented::read(text).err().unwrap_or_default();
assert!(refused("{\"format_version\":99,\"root\":0}").contains("format 99"));
assert!(refused("not json").starts_with("rustdoc's JSON cannot be read"));
}
}