cargo_doc2readme/

input.rs

use crate::{
	diagnostic::{self, DiagnosticExt as _, DiagnosticPrinter},
	preproc::Preprocessor
};
use camino::Utf8Path;
use cargo_metadata::{Edition, Metadata, Package, Target};
use either::Either;
use hashbrown::{HashMap, HashSet};
use miette::{IntoDiagnostic as _, NamedSource};
use proc_macro2::{Span, TokenStream, TokenTree};
use quote::ToTokens as _;
use semver::{Comparator, Op, Version, VersionReq};
use serde::Serialize;
use std::{
	collections::VecDeque,
	fmt::{self, Debug, Formatter},
	fs::File,
	io::{self, BufReader, Cursor, Read, Write},
	path::Path,
	process::{Command, Output}
};
use syn::{
	parse::{Parse, ParseStream},
	spanned::Spanned as _,
	Expr, ExprLit, Ident, Item, ItemMacro, ItemUse, Lit, LitStr, Meta, Token, UsePath,
	UseTree, Visibility
};

type ScopeScope = HashMap<String, VecDeque<(LinkType, String)>>;

pub struct Scope {
	// use statements and declared items. maps name to path.
	pub scope: ScopeScope,
	// private modules so that `pub use`'d items are considered inlined.
	pub privmods: HashSet<String>
}

impl Debug for Scope {
	fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
		struct ScopeScopeDebug<'a>(&'a ScopeScope);
		impl Debug for ScopeScopeDebug<'_> {
			fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
				let mut dbg = f.debug_map();
				for (name, paths) in self.0 {
					match paths.len() {
						0 => {
							// wtf, can this even happen?
							continue;
						},
						1 => {
							dbg.entry(name, &paths[0]);
						},
						_ => {
							dbg.entry(name, paths);
						}
					}
				}
				dbg.finish()
			}
		}

		f.debug_struct("Scope")
			.field("scope", &ScopeScopeDebug(&self.scope))
			.field("privmods", &self.privmods)
			.finish()
	}
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum LinkType {
	/// A procedural macro attribute.
	Attr,
	Const,
	/// A procedural derive macro.
	Derive,
	Enum,
	ExternCrate,
	Function,
	/// A `macro` can be both a procedural and declarative macro.
	Macro,
	Mod,
	Static,
	Struct,
	Trait,
	TraitAlias,
	Type,
	Union,

	/// `use` statement that links to a path.
	Use,
	/// `pub use` statement that links to the name pub used as.
	PubUse,

	/// Primitive from the standard library
	Primitive
}

fn make_prelude<const N: usize>(
	prelude: [(&'static str, &'static str, LinkType); N]
) -> ScopeScope {
	prelude
		.into_iter()
		.flat_map(|(name, path, link_type)| {
			let path = match path {
				"" => format!("::std::{name}"),
				_ => format!("::std::{path}::{name}")
			};
			let items: VecDeque<_> = [(link_type, path)].into_iter().collect();
			match link_type {
				LinkType::Macro => Either::Left(
					[(name.into(), items.clone()), (format!("{name}!"), items)]
						.into_iter()
				),
				_ => Either::Right([(name.into(), items)].into_iter())
			}
		})
		.collect()
}

impl Scope {
	fn insert<K, V>(&mut self, key: K, ty: LinkType, value: V)
	where
		K: Into<String>,
		V: Into<String>
	{
		self.scope
			.entry(key.into())
			.or_default()
			.push_front((ty, value.into()));
	}

	pub(crate) fn empty() -> Self {
		Self {
			scope: HashMap::new(),
			privmods: HashSet::new()
		}
	}

	/// Create a new scope from the Rust prelude.
	pub fn prelude(edition: Edition) -> Self {
		let mut scope = Self {
			scope: make_prelude([
				// https://doc.rust-lang.org/stable/std/primitive/index.html#reexports
				("bool", "", LinkType::Primitive),
				("char", "", LinkType::Primitive),
				("f32", "", LinkType::Primitive),
				("f64", "", LinkType::Primitive),
				("i128", "", LinkType::Primitive),
				("i16", "", LinkType::Primitive),
				("i32", "", LinkType::Primitive),
				("i64", "", LinkType::Primitive),
				("i8", "", LinkType::Primitive),
				("isize", "", LinkType::Primitive),
				("str", "", LinkType::Primitive),
				("u128", "", LinkType::Primitive),
				("u16", "", LinkType::Primitive),
				("u32", "", LinkType::Primitive),
				("u64", "", LinkType::Primitive),
				("u8", "", LinkType::Primitive),
				("usize", "", LinkType::Primitive),
				// https://doc.rust-lang.org/stable/std/prelude/index.html#prelude-contents
				("Copy", "marker", LinkType::Trait),
				("Send", "marker", LinkType::Trait),
				("Sized", "marker", LinkType::Trait),
				("Sync", "marker", LinkType::Trait),
				("Unpin", "marker", LinkType::Trait),
				("Drop", "ops", LinkType::Trait),
				("Fn", "ops", LinkType::Trait),
				("FnMut", "ops", LinkType::Trait),
				("FnOnce", "ops", LinkType::Trait),
				("drop", "mem", LinkType::Function),
				("Box", "boxed", LinkType::Struct),
				("ToOwned", "borrow", LinkType::Trait),
				("Clone", "clone", LinkType::Trait),
				("PartialEq", "cmp", LinkType::Trait),
				("PartialOrd", "cmp", LinkType::Trait),
				("Eq", "cmp", LinkType::Trait),
				("Ord", "cmp", LinkType::Trait),
				("AsRef", "convert", LinkType::Trait),
				("AsMut", "convert", LinkType::Trait),
				("Into", "convert", LinkType::Trait),
				("From", "convert", LinkType::Trait),
				("Default", "default", LinkType::Trait),
				("Iterator", "iter", LinkType::Trait),
				("Extend", "iter", LinkType::Trait),
				("IntoIterator", "iter", LinkType::Trait),
				("DoubleEndedIterator", "iter", LinkType::Trait),
				("ExactSizeIterator", "iter", LinkType::Trait),
				("Option", "option", LinkType::Enum),
				("Some", "option::Option", LinkType::Use),
				("None", "option::Option", LinkType::Use),
				("Result", "result", LinkType::Struct),
				("Ok", "result::Result", LinkType::Use),
				("Err", "result::Result", LinkType::Use),
				("String", "string", LinkType::Struct),
				("ToString", "string", LinkType::Trait),
				("Vec", "vec", LinkType::Struct),
				// https://doc.rust-lang.org/stable/std/index.html#macros
				("assert", "", LinkType::Macro),
				("assert_eq", "", LinkType::Macro),
				("assert_ne", "", LinkType::Macro),
				("cfg", "", LinkType::Macro),
				("column", "", LinkType::Macro),
				("compile_error", "", LinkType::Macro),
				("concat", "", LinkType::Macro),
				("dbg", "", LinkType::Macro),
				("debug_assert", "", LinkType::Macro),
				("debug_assert_eq", "", LinkType::Macro),
				("debug_assert_ne", "", LinkType::Macro),
				("env", "", LinkType::Macro),
				("eprint", "", LinkType::Macro),
				("eprintln", "", LinkType::Macro),
				("file", "", LinkType::Macro),
				("format", "", LinkType::Macro),
				("format_args", "", LinkType::Macro),
				("include", "", LinkType::Macro),
				("include_bytes", "", LinkType::Macro),
				("include_str", "", LinkType::Macro),
				("is_x86_feature_detected", "", LinkType::Macro),
				("line", "", LinkType::Macro),
				("matches", "", LinkType::Macro),
				("module_path", "", LinkType::Macro),
				("option_env", "", LinkType::Macro),
				("panic", "", LinkType::Macro),
				("print", "", LinkType::Macro),
				("println", "", LinkType::Macro),
				("stringify", "", LinkType::Macro),
				("thread_local", "", LinkType::Macro),
				("todo", "", LinkType::Macro),
				("unimplemented", "", LinkType::Macro),
				("unreachable", "", LinkType::Macro),
				("vec", "", LinkType::Macro),
				("write", "", LinkType::Macro),
				("writeln", "", LinkType::Macro)
			]),
			privmods: HashSet::new()
		};

		if edition >= Edition::E2021 {
			// https://blog.rust-lang.org/2021/05/11/edition-2021.html#additions-to-the-prelude
			for (key, value) in make_prelude([
				("TryInto", "convert", LinkType::Use),
				("TryFrom", "convert", LinkType::Use),
				("FromIterator", "iter", LinkType::Use)
			]) {
				scope.scope.insert(key, value);
			}
		}

		if edition >= Edition::E2024 {
			// https://doc.rust-lang.org/edition-guide/rust-2024/prelude.html
			for (key, value) in make_prelude([
				("Future", "future", LinkType::Trait),
				("IntoFuture", "future", LinkType::Trait)
			]) {
				scope.scope.insert(key, value);
			}
		}

		scope
	}
}

#[derive(Debug)]
pub struct CrateCode {
	pub filename: String,
	pub code: String
}

impl From<&CrateCode> for NamedSource<String> {
	fn from(code: &CrateCode) -> Self {
		NamedSource::new(&code.filename, code.code.clone()).with_language("Rust")
	}
}

impl CrateCode {
	pub fn new_unknown() -> Self {
		Self {
			filename: "<unknown>".into(),
			code: String::new()
		}
	}

	fn read_from<R>(filename: String, read: R) -> io::Result<Self>
	where
		R: io::BufRead
	{
		let mut preproc = Preprocessor::new(read);
		let mut code = String::new();
		preproc.read_to_string(&mut code)?;

		Ok(Self { filename, code })
	}

	pub fn read_from_disk<P>(path: P) -> io::Result<Self>
	where
		P: AsRef<Utf8Path>
	{
		let path = path.as_ref();
		let filename = path.file_name().unwrap_or(path.as_str());
		Self::read_from(filename.into(), BufReader::new(File::open(path)?))
	}

	pub fn read_expansion<P>(
		manifest_path: Option<P>,
		package: Option<&str>,
		target: &Target,
		features: Option<&str>,
		no_default_features: bool,
		all_features: bool
	) -> miette::Result<CrateCode>
	where
		P: AsRef<Path>
	{
		let mut cmd = Command::new("cargo");
		cmd.arg("+nightly").arg("rustc");
		if let Some(manifest_path) = manifest_path {
			cmd.arg("--manifest-path").arg(manifest_path.as_ref());
		}
		if let Some(package) = package {
			cmd.arg("-p").arg(package);
		}
		if let Some(features) = features {
			cmd.arg("--features").arg(features);
		}
		if no_default_features {
			cmd.arg("--no-default-features");
		}
		if all_features {
			cmd.arg("--all-features");
		}
		if target.is_lib() {
			cmd.arg("--lib");
		} else if target.is_bin() {
			cmd.arg("--bin").arg(&target.name);
		}
		cmd.arg("--").arg("-Zunpretty=expanded");

		let Output {
			stdout,
			stderr,
			status
		} = cmd.output()
			.map_err(|err| diagnostic::ExecError::new(err, &cmd))?;

		if !status.success() {
			// Something bad happened during the compilation. Let's print
			// anything Cargo reported to us and return an error.
			io::stdout()
				.lock()
				.write_all(stderr.as_slice())
				.expect("Failed to write cargo errors to stdout");

			let err = diagnostic::ExecError::new(
				format!("Command finished with non-zero exit code {status}"),
				&cmd
			);
			return Err(err.into());
		}

		Self::read_from("<cargo-expand>".into(), Cursor::new(stdout)).into_diagnostic()
	}
}

/// The crate target type, either `bin` or `lib`.
///
/// All variants are renamed to their lowercase counterparts for the template.
#[derive(Clone, Copy, Debug, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum TargetType {
	Bin,
	Lib
}

#[derive(Debug)]
pub struct InputFile {
	/// The name of the crate.
	pub crate_name: String,
	/// The version of the crate
	pub crate_version: Version,
	/// The target type.
	pub target_type: TargetType,
	/// The repository url (if specified).
	pub repository: Option<String>,
	/// The license field (if specified).
	pub license: Option<String>,
	/// The rust_version field (if specified).
	pub rust_version: Option<Version>,
	/// The unmodified rustdoc string
	pub rustdoc: String,
	/// The crate-level dependencies, mapping the valid identifier in rust code to the (possibly
	/// renamed, containing invalid characters, etc.) crate name and version.
	pub dependencies: HashMap<String, Dependency>,
	/// The scope at the crate root.
	pub scope: Scope
}

impl InputFile {
	pub fn dummy() -> Self {
		Self {
			crate_name: "N/A".into(),
			crate_version: Version::new(0, 0, 0),
			target_type: TargetType::Lib,
			repository: None,
			license: None,
			rust_version: None,
			rustdoc: String::new(),
			dependencies: HashMap::new(),
			scope: Scope::empty()
		}
	}
}

pub struct Dependency {
	/// The crate name as it appears on crates.io.
	pub crate_name: String,

	/// The version requirement of the dependency.
	pub req: VersionReq,

	/// The exact version of the dependency.
	pub version: Version
}

impl Dependency {
	pub fn new(crate_name: String, req: VersionReq, version: Version) -> Self {
		Self {
			crate_name,
			req,
			version
		}
	}

	pub fn as_tuple(&self) -> (&str, Option<&Version>) {
		(self.crate_name.as_str(), Some(&self.version))
	}
}

impl Debug for Dependency {
	fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
		write!(
			f,
			"{} = \"{}\" ({})",
			self.crate_name, self.req, self.version
		)
	}
}

pub fn read_code<W: io::Write>(
	metadata: &Metadata,
	pkg: &Package,
	code: &CrateCode,
	target_type: TargetType,
	printer_stderr: W
) -> miette::Result<InputFile> {
	let crate_name = pkg.name.as_str().to_owned();
	let crate_version = pkg.version.clone();
	let repository = pkg.repository.clone();
	let license = pkg.license.clone();
	let rust_version = pkg.rust_version.clone();

	let file = match syn::parse_file(code.code.as_str()) {
		Ok(file) => file,
		Err(err) => {
			let err = diagnostic::SyntaxError::new_rust(code, err);
			return Err(err.into());
		}
	};

	let mut printer = DiagnosticPrinter::new(code, printer_stderr);

	let rustdoc = read_rustdoc_from_file(&file, &mut printer)?;
	let dependencies = resolve_dependencies(metadata, pkg, &mut printer);
	let scope = read_scope_from_file(pkg, &file, &mut printer)?;

	Ok(InputFile {
		crate_name,
		crate_version,
		target_type,
		repository,
		license,
		rust_version,
		rustdoc,
		dependencies,
		scope
	})
}

fn read_rustdoc_from_file<W: io::Write>(
	file: &syn::File,
	printer: &mut DiagnosticPrinter<'_, W>
) -> miette::Result<String> {
	let mut doc = String::new();
	let mut errs = Vec::new();
	for attr in &file.attrs {
		match &attr.meta {
			Meta::NameValue(nv) if nv.path.is_ident("doc") => {
				match parse_doc_attr(&nv.value, printer) {
					Ok(Some(str)) => {
						doc.push('\n');
						doc.push_str(&str.value());
					},
					Ok(None) => {},
					Err(err) => {
						errs.push(err);
					}
				}
			},

			Meta::List(l) if l.path.is_ident("cfg_attr") => {
				parse_cfg_attr(l.tokens.clone(), attr.span(), printer);
			},

			_ => {}
		}
	}
	if !errs.is_empty() {
		let err = diagnostic::SyntaxError::new_rust_multi(printer.code, errs);
		Err(err.into())
	} else {
		Ok(doc)
	}
}

/// Parse the expr of a `#[doc = ...]` attribute. Returns a string if possible, a warning
/// if it encounters an unexpanded macro or an error if it finds something else.
fn parse_doc_attr<W: io::Write>(
	expr: &Expr,
	printer: &mut DiagnosticPrinter<'_, W>
) -> syn::Result<Option<LitStr>> {
	match expr {
		Expr::Lit(ExprLit {
			lit: Lit::Str(lit), ..
		}) => Ok(Some(lit.clone())),
		Expr::Macro(makro) => {
			diagnostic::MacroNotExpanded::new(printer.code, makro.span()).print(printer);
			Ok(None)
		},
		expr => Err(syn::Error::new(
			expr.span(),
			"Expected string literal or macro invokation"
		))
	}
}

/// Parse a `#[cfg_attr(..., ...)]` attribute. Returns a warning if it contains a doc
/// attribute.
fn parse_cfg_attr<W: io::Write>(
	tokens: TokenStream,
	span: Span,
	printer: &mut DiagnosticPrinter<'_, W>
) {
	struct CfgAttr;

	impl Parse for CfgAttr {
		fn parse(input: ParseStream) -> syn::Result<Self> {
			// skip to the 2nd argument
			while !input.peek(Token![,]) {
				let _: TokenTree = input.parse()?;
			}
			let _: Token![,] = input.parse()?;

			let path: syn::Path = input.parse()?;
			if !path.is_ident("doc") {
				return Err(syn::Error::new(
					path.span(),
					format!("Expected `doc`, found `{}`", path.into_token_stream())
				));
			}

			let _: Token![=] = input.parse()?;
			let _: TokenStream = input.parse()?;
			Ok(CfgAttr)
		}
	}

	if syn::parse2::<CfgAttr>(tokens).is_ok() {
		diagnostic::MacroNotExpanded::new(printer.code, span).print(printer);
	}
}

fn sanitize_crate_name<T: AsRef<str>>(name: T) -> String {
	name.as_ref().replace('-', "_")
}

fn resolve_dependencies<W: io::Write>(
	metadata: &Metadata,
	pkg: &Package,
	printer: &mut DiagnosticPrinter<'_, W>
) -> HashMap<String, Dependency> {
	let mut deps = HashMap::new();

	// We currently insert our own crate as a dependency to allow doc links referencing
	// ourself. However, we might want to change this so that custom doc urls can be used,
	// so that e.g. the repository readme points to some rustdoc generated from the main
	// branch, instead of the last release. Also, the version in the current manifest
	// might not be released, so those links might be dead.
	let version = pkg.version.clone();
	deps.insert(
		sanitize_crate_name(&pkg.name),
		Dependency::new(
			pkg.name.as_str().to_owned(),
			[Comparator {
				op: Op::Exact,
				major: version.major,
				minor: Some(version.minor),
				patch: Some(version.patch),
				pre: version.pre.clone()
			}]
			.into_iter()
			.collect(),
			version
		)
	);

	for dep in &pkg.dependencies {
		let dep_name = sanitize_crate_name(&dep.name);
		let version = metadata
			.packages
			.iter()
			.filter(|pkg| pkg.name.as_str() == dep.name)
			.map(|pkg| &pkg.version)
			.find(|pkgver| dep.req.matches(pkgver));
		let rename = dep.rename.as_ref().unwrap_or(&dep_name);

		if let Some(version) = version {
			if deps
				.get(rename)
				.map(|dep| dep.version < *version)
				.unwrap_or(true)
			{
				deps.insert(
					rename.to_owned(),
					Dependency::new(dep_name, dep.req.clone(), version.to_owned())
				);
			}
		} else {
			diagnostic::NoDependencyVersion::new(dep.name.clone()).print(printer);
		}
	}

	deps
}

struct ScopeEditor<'a, 'w, W: io::Write> {
	scope: &'a mut Scope,
	crate_name: &'a str,
	printer: &'a mut DiagnosticPrinter<'w, W>,
	glob_warn: Option<diagnostic::GlobImport>
}

impl<W: io::Write> Drop for ScopeEditor<'_, '_, W> {
	fn drop(&mut self) {
		if let Some(warning) = self.glob_warn.take() {
			self.printer.print(warning);
		}
	}
}

impl<'a, 'w, W: io::Write> ScopeEditor<'a, 'w, W> {
	fn new(
		scope: &'a mut Scope,
		crate_name: &'a str,
		printer: &'a mut DiagnosticPrinter<'w, W>
	) -> Self {
		Self {
			scope,
			crate_name,
			printer,
			glob_warn: None
		}
	}

	fn add_privmod(&mut self, ident: &Ident) {
		self.scope.privmods.insert(ident.to_string());
	}

	fn insert(&mut self, ident: &Ident, ty: LinkType) {
		let path = format!("::{}::{ident}", self.crate_name);
		self.scope.insert(ident.to_string(), ty, path);
	}

	fn insert_fun(&mut self, ident: &Ident) {
		let path = format!("::{}::{ident}", self.crate_name);
		self.scope
			.insert(ident.to_string(), LinkType::Function, &path);
		self.scope
			.insert(format!("{ident}()"), LinkType::Function, path);
	}

	fn insert_macro(&mut self, ident: &Ident) {
		let path = format!("::{}::{ident}", self.crate_name);
		self.scope.insert(ident.to_string(), LinkType::Macro, &path);
		self.scope
			.insert(format!("{ident}!"), LinkType::Macro, path);
	}

	fn insert_use_tree(&mut self, vis: &Visibility, tree: &UseTree) {
		self.insert_use_tree_impl(vis, String::new(), tree)
	}

	fn insert_use_tree_impl(&mut self, vis: &Visibility, prefix: String, tree: &UseTree) {
		match tree {
			UseTree::Path(path) if prefix.is_empty() && path.ident == "self" => {
				self.insert_use_tree_impl(vis, prefix, &path.tree)
			},
			UseTree::Path(path) => self.insert_use_tree_impl(
				vis,
				format!("{prefix}{}::", path.ident),
				&path.tree
			),
			UseTree::Name(name) => {
				// skip `pub use dependency;` style uses; they don't add any unknown
				// elements to the scope
				if !prefix.is_empty() {
					self.insert_use_item(vis, &prefix, &name.ident, &name.ident);
				}
			},
			UseTree::Rename(name) => {
				self.insert_use_item(vis, &prefix, &name.rename, &name.ident);
			},
			UseTree::Glob(glob) => {
				let span = glob.star_token.spans[0];
				if let Some(warning) = &mut self.glob_warn {
					warning.add_span(span);
				} else {
					self.glob_warn =
						Some(diagnostic::GlobImport::new(self.printer.code, span));
				}
			},
			UseTree::Group(group) => {
				for tree in &group.items {
					self.insert_use_tree_impl(vis, prefix.clone(), tree);
				}
			},
		};
	}

	fn insert_use_item(
		&mut self,
		vis: &Visibility,
		prefix: &str,
		rename: &Ident,
		ident: &Ident
	) {
		if matches!(vis, Visibility::Public(_)) {
			self.insert(rename, LinkType::PubUse);
		}
		self.scope.insert(
			rename.to_string(),
			LinkType::Use,
			format!("{prefix}{ident}")
		);
	}
}

fn is_public(vis: &Visibility) -> bool {
	matches!(vis, Visibility::Public(_))
}

fn is_exported(mac: &ItemMacro) -> bool {
	mac.attrs
		.iter()
		.any(|attr| attr.path().is_ident("macro_export"))
}

fn read_scope_from_file<W: io::Write>(
	pkg: &Package,
	file: &syn::File,
	printer: &mut DiagnosticPrinter<'_, W>
) -> miette::Result<Scope> {
	let crate_name = sanitize_crate_name(&pkg.name);
	let mut scope = Scope::prelude(pkg.edition);
	let mut editor = ScopeEditor::new(&mut scope, &crate_name, printer);
	let mut errs = Vec::new();

	'items: for i in &file.items {
		match i {
			Item::Const(i) if is_public(&i.vis) => {
				editor.insert(&i.ident, LinkType::Const)
			},
			Item::Enum(i) if is_public(&i.vis) => editor.insert(&i.ident, LinkType::Enum),
			Item::ExternCrate(i)
				if is_public(&i.vis) && i.ident != "self" && i.rename.is_some() =>
			{
				editor.scope.insert(
					i.rename.as_ref().unwrap().1.to_string(),
					LinkType::ExternCrate,
					format!("::{}", i.ident)
				);
			},
			Item::Fn(i) if is_public(&i.vis) => {
				for a in &i.attrs {
					let ap = match &a.meta {
						Meta::Path(p) => p,
						Meta::List(l) => &l.path,
						Meta::NameValue(nv) => &nv.path
					};
					let ai = match ap.get_ident() {
						Some(ai) => ai,
						None => continue
					};
					if ai == "proc_macro" {
						editor.insert_macro(&i.sig.ident);
					} else if ai == "proc_macro_attribute" {
						editor.insert(&i.sig.ident, LinkType::Attr);
					} else if ai == "proc_macro_derive" {
						let Meta::List(l) = &a.meta else {
							errs.push(syn::Error::new(
								a.meta.span(),
								"Expected proc_macro_derive to specify a name for the derive macro"
							));
							continue 'items;
						};
						let Some(derive_ident) =
							l.tokens.clone().into_iter().next().and_then(|token| {
								match token {
									TokenTree::Ident(ident) => Some(ident),
									_ => None
								}
							})
						else {
							errs.push(syn::Error::new(
								l.tokens.span(),
								"Expected proc_macro_derive to specify a name for the derive macro"
							));
							continue 'items;
						};
						editor.insert(&derive_ident, LinkType::Derive);
					} else {
						continue;
					}
					// if we didn't find a proc-macro attribute, we would've continued
					// the inner loop before, so in this case, we continue the outer loop
					continue 'items;
				}
				editor.insert_fun(&i.sig.ident)
			},
			Item::Macro(i) if is_exported(i) && i.ident.is_some() => {
				editor.insert_macro(i.ident.as_ref().unwrap())
			},
			Item::Mod(i) if is_public(&i.vis) => editor.insert(&i.ident, LinkType::Mod),
			Item::Mod(i) => editor.add_privmod(&i.ident),
			Item::Static(i) if is_public(&i.vis) => {
				editor.insert(&i.ident, LinkType::Static)
			},
			Item::Struct(i) if is_public(&i.vis) => {
				editor.insert(&i.ident, LinkType::Struct)
			},
			Item::Trait(i) if is_public(&i.vis) => {
				editor.insert(&i.ident, LinkType::Trait)
			},
			Item::TraitAlias(i) if is_public(&i.vis) => {
				editor.insert(&i.ident, LinkType::TraitAlias)
			},
			Item::Type(i) if is_public(&i.vis) => editor.insert(&i.ident, LinkType::Type),
			Item::Union(i) if is_public(&i.vis) => {
				editor.insert(&i.ident, LinkType::Union)
			},
			Item::Use(i) if !is_prelude_import(i) => {
				editor.insert_use_tree(&i.vis, &i.tree)
			},
			_ => {}
		};
	}
	drop(editor);

	// remove privmod imports from scope
	for values in &mut scope.scope.values_mut() {
		let mut i = 0;
		while i < values.len() {
			if values[i].0 == LinkType::Use {
				let path = &values[i].1;
				if (!path.starts_with("::")
					|| path.starts_with(&format!("::{crate_name}::")))
					&& Some(path.split("::").collect::<Vec<_>>())
						.map(|segments| {
							segments.len() > 1 && scope.privmods.contains(segments[0])
						})
						.unwrap()
				{
					values.remove(i);
					continue;
				}
			}

			i += 1;
		}
	}

	if !errs.is_empty() {
		let err = diagnostic::SyntaxError::new_rust_multi(printer.code, errs);
		Err(err.into())
	} else {
		Ok(scope)
	}
}

fn is_prelude_import(item_use: &ItemUse) -> bool {
	match &item_use.tree {
		UseTree::Path(UsePath { ident, tree, .. })
			if ident == "std" || ident == "core" =>
		{
			match tree.as_ref() {
				UseTree::Path(UsePath { ident, .. }) => ident == "prelude",
				_ => false
			}
		},
		_ => false
	}
}