cargo_doc2readme/

lib.rs

//! **THIS IS NOT A LIBRARY. NONE OF THE APIS ARE PUBLIC. THEY DON'T
//! ADHERE TO SEMVER. DON'T EVEN USE AT YOUR OWN RISK. DON'T USE IT
//! AT ALL.**

#[doc(hidden)]
pub mod config;
mod depinfo;
#[doc(hidden)]
pub mod diagnostic;
mod input;
mod links;
mod monostate;
mod output;
mod preproc;
mod verify;

// this shall explicitly be documented
#[doc(inline)]
pub use self::{input::TargetType, output::TemplateContext};

use self::{
	config::{Config, ConfigOutput},
	diagnostic::DiagnosticPrinter,
	input::{CrateCode, InputFile}
};
use camino::Utf8Path;
use cargo_metadata::{CargoOpt, Metadata, MetadataCommand, Target};
use either::Either;
use itertools::Itertools as _;
use miette::{miette, Context as _, IntoDiagnostic as _, MietteHandlerOpts, Severity};
use std::{
	borrow::Cow,
	env, fmt,
	fs::{self, File},
	io, iter,
	sync::{Arc, Mutex}
};

#[doc(hidden)]
pub fn install_miette_hook(wrap_lines: bool) {
	// Custom miette hook to make sure that relevant text like "WARNING" isn't hidden
	// behind a simple yellow `!` that means nothing to a user
	miette::set_hook(Box::new(move |_| {
		let mut styles = miette::ThemeStyles::ansi();
		styles.highlights.truncate(1);
		Box::new(
			MietteHandlerOpts::new()
				.unicode(false)
				.graphical_theme(miette::GraphicalTheme {
					characters: miette::ThemeCharacters {
						error: "\nERROR:".into(),
						warning: "\nWARNING:".into(),
						advice: "\nINFO:".into(),
						..miette::ThemeCharacters::unicode()
					},
					styles
				})
				.tab_width(4)
				.wrap_lines(wrap_lines)
				.build()
		)
	}))
	.expect("Failed to initialise error report hook");
}

#[doc(hidden)]
pub struct App<W> {
	cfg: Config,

	/// Writer that diagnostics can be printed to. Usually stderr.
	pub stderr: W,

	/// Output of cargo metadata.
	metadata: Metadata
}

#[doc(hidden)]
pub struct Instance<'a, W> {
	/// App-wide configuration.
	cfg: &'a Config,
	/// App-wide output of cargo metadata.
	metadata: &'a Metadata,

	/// Instance-specific cargo package name.
	pkg: Option<&'a str>,
	/// Instance-specific output file.
	out: Cow<'a, Utf8Path>,
	/// Instance-specific template file.
	template_path: Option<Cow<'a, Utf8Path>>,

	/// Writer that diagnostics can be printed to.
	stderr: W,
	/// The code of the crate of this instance.
	code: CrateCode,

	input_file: InputFile,
	template_filename: Cow<'static, str>,
	template: Cow<'static, str>,
	builtin_template: bool
}

impl<W: io::Write> App<W> {
	pub fn with_config(cfg: Config, stderr: W) -> miette::Result<Self> {
		// call cargo metadata
		let mut cmd = MetadataCommand::new();
		cmd.features(CargoOpt::AllFeatures);
		if let Some(path) = &cfg.manifest_path {
			cmd.manifest_path(path);
		}
		let metadata = cmd
			.exec()
			.map_err(|err| diagnostic::ExecError::new(err, &cmd.cargo_command()))?;

		Ok(Self {
			cfg,
			stderr,
			metadata
		})
	}

	pub fn check_cfg(&mut self) {
		let code = CrateCode::new_unknown();
		let mut printer = DiagnosticPrinter::new(&code, &mut self.stderr);

		if self.cfg.package.is_some() && self.cfg.packages.is_some() {
			printer.print(diagnostic::PackagesIgnored);
		}

		if !self.cfg.expand_macros {
			if self.cfg.features.is_some() {
				printer.print(diagnostic::NoOpWithoutExpandMacros::flag("--features"));
			}
			if !self.cfg.default_features {
				printer.print(diagnostic::NoOpWithoutExpandMacros::flag(
					"--no-default-features"
				));
			}
			if self.cfg.all_features {
				printer
					.print(diagnostic::NoOpWithoutExpandMacros::flag("--all-features"));
			}
		}
	}

	/// Return the instance if the configuration results in exactly one readme instance.
	///
	/// # Panics
	///
	/// If the configuration results in more than one instance.
	#[track_caller]
	pub fn instance(&mut self) -> Instance<'_, &mut W> {
		// --workspace, unless -p is specified, could give multiple instances
		// also, it would potentially invalidate the package of the dumb instance
		if self.cfg.workspace && self.cfg.package.is_none() {
			panic!("There might be multiple instances");
		}
		// when `out` is not a single file, even if it is a one-element array, the
		// template path might be overwritten, so the dumb instance would be wrong
		let out = match &self.cfg.out {
			ConfigOutput::SingleFile(out) => out,
			ConfigOutput::MultiFile(_) => panic!("There might be multiple instances")
		};

		Instance {
			cfg: &self.cfg,
			metadata: &self.metadata,
			pkg: self.cfg.package.as_deref(),
			out: out.as_path().into(),
			template_path: self.cfg.template.as_deref().map(Into::into),
			stderr: &mut self.stderr,
			code: CrateCode::new_unknown(),
			input_file: InputFile::dummy(),
			template_filename: "<builtin-template>".into(),
			template: include_str!("README.j2").into(),
			builtin_template: true
		}
	}

	pub fn instances(
		&mut self
	) -> impl Iterator<Item = Instance<'_, impl io::Write + '_>> + '_ {
		let pkg_iter = if self.cfg.workspace && self.cfg.package.is_none() {
			let iter = self
				.metadata
				.workspace_packages()
				.into_iter()
				.map(|pkg| pkg.name.as_str());
			Either::Left(
				match &self.cfg.packages {
					Some(pkgs) => Either::Left(iter.filter(|pkg| pkgs.contains(*pkg))),
					None => Either::Right(iter)
				}
				.map(Some)
			)
		} else {
			Either::Right(iter::once(self.cfg.package.as_deref()))
		};

		let out_iter = match &self.cfg.out {
			ConfigOutput::SingleFile(out) => {
				Either::Left(iter::once((out, self.cfg.template.as_ref())))
			},
			ConfigOutput::MultiFile(files) if files.is_empty() => {
				let code = CrateCode::new_unknown();
				let mut printer = DiagnosticPrinter::new(&code, &mut self.stderr);
				printer.print(diagnostic::NoOutputs);
				return Either::Left(iter::empty());
			},
			ConfigOutput::MultiFile(files) => Either::Right(files.iter().map(|file| {
				(
					&file.out,
					file.template.as_ref().or(self.cfg.template.as_ref())
				)
			}))
		};

		let cfg = &self.cfg;
		let metadata = &self.metadata;
		let stderr = SharedWrite::new(&mut self.stderr);

		Either::Right(pkg_iter.cartesian_product(out_iter).map(
			move |(pkg, (out, template_path))| Instance {
				cfg,
				metadata,
				pkg,
				out: out.as_path().into(),
				template_path: template_path.map(|path| path.as_path().into()),
				stderr: stderr.clone(),
				code: CrateCode::new_unknown(),
				input_file: InputFile::dummy(),
				template_filename: "<builtin-template>".into(),
				template: include_str!("README.j2").into(),
				builtin_template: true
			}
		))
	}
}

struct SharedWrite<'a, W>(Arc<Mutex<&'a mut W>>);

impl<'a, W> SharedWrite<'a, W> {
	pub fn new(inner: &'a mut W) -> Self {
		Self(Arc::new(Mutex::new(inner)))
	}
}

impl<W> Clone for SharedWrite<'_, W> {
	fn clone(&self) -> Self {
		Self(Arc::clone(&self.0))
	}
}

impl<W: io::Write> io::Write for SharedWrite<'_, W> {
	fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
		self.0.lock().unwrap().write(buf)
	}

	fn write_vectored(&mut self, bufs: &[io::IoSlice<'_>]) -> io::Result<usize> {
		self.0.lock().unwrap().write_vectored(bufs)
	}

	fn flush(&mut self) -> io::Result<()> {
		self.0.lock().unwrap().flush()
	}

	fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
		self.0.lock().unwrap().write_all(buf)
	}

	fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
		self.0.lock().unwrap().write_fmt(args)
	}
}

impl<W: io::Write> Instance<'_, W> {
	pub fn read_input(&mut self) -> miette::Result<()> {
		// (re)assemble features string
		let features = match &self.cfg.features {
			None => None,
			Some(Either::Left(features)) => Some(features.clone()),
			Some(Either::Right(features)) => Some(features.join(","))
		};

		// find the correct package within the metadata
		let pkg = match self.pkg {
			Some(package) => {
				let pkg = self
					.metadata
					.packages
					.iter()
					.find(|pkg| pkg.name == package)
					.ok_or_else(|| {
						diagnostic::PackageNotFoundError::new(
							package,
							self.metadata.workspace_packages()
						)
					})?;
				if !self.metadata.workspace_members.contains(&pkg.id) {
					let code = CrateCode::new_unknown();
					let mut printer = DiagnosticPrinter::new(&code, &mut self.stderr);

					printer.print(diagnostic::PackageNotInWorkspace::new(
						package,
						self.metadata.workspace_packages()
					));
				}
				// TODO issue warning if package not in workspace
				pkg
			},
			None => self.metadata.root_package().ok_or_else(|| {
				diagnostic::NoPackageError::new(self.metadata.workspace_packages())
			})?
		};

		// in workspace mode, use the pkg's manifest path to make relative path's absolute
		if self.cfg.workspace {
			let parent = match pkg.manifest_path.parent() {
				Some(parent) => parent,
				None => {
					return Err(miette!(
						"Unable to get parent directory of {}",
						pkg.manifest_path
					))
				},
			};
			if self.out.is_relative() {
				self.out = parent.join(&self.out).into();
			}
			if let Some(template_path) = self.template_path.as_deref() {
				if template_path.is_relative() {
					self.template_path = Some(parent.join(template_path).into());
				}
			}
		}

		// find the target whose rustdoc comment we'll use.
		// this uses a library target if exists, otherwise a binary target with the same name as the
		// package, or otherwise the first binary target
		let is_lib = |target: &&Target| target.is_lib() || target.is_proc_macro();
		let is_default_bin =
			|target: &&Target| target.is_bin() && target.name == pkg.name.as_str();
		let target_and_type = if self.cfg.preferred_target == config::Target::Bin {
			pkg.targets
				.iter()
				.find(is_default_bin)
				.map(|target| (target, TargetType::Bin))
				.or_else(|| {
					pkg.targets
						.iter()
						.find(is_lib)
						.map(|target| (target, TargetType::Lib))
				})
		} else {
			pkg.targets
				.iter()
				.find(is_lib)
				.map(|target| (target, TargetType::Lib))
				.or_else(|| {
					pkg.targets
						.iter()
						.find(is_default_bin)
						.map(|target| (target, TargetType::Bin))
				})
		};
		let (target, target_type) = target_and_type
			.or_else(|| {
				pkg.targets
					.iter()
					.find(|target| target.is_bin())
					.map(|target| (target, TargetType::Bin))
			})
			.ok_or(diagnostic::NoTargetError)?;

		// resolve the template
		let default_template: &Utf8Path = "README.j2".as_ref();
		let (template_filename, template, builtin_template) = match &self.template_path {
			Some(template_path) => {
				let template = fs::read_to_string(template_path.as_std_path())
					.into_diagnostic()
					.with_context(|| {
						format!("Failed to read template from `{template_path}'",)
					})?;
				let template_path_stripped =
					template_path.strip_prefix(env::current_dir().unwrap());
				(
					template_path_stripped
						.unwrap_or(template_path)
						.to_string()
						.into(),
					template.into(),
					false
				)
			},
			None if default_template.exists() => {
				let template = fs::read_to_string(default_template)
					.into_diagnostic()
					.with_context(|| {
						format!("Failed to read template from `{default_template}'",)
					})?;
				(default_template.as_str().into(), template.into(), false)
			},
			None => (
				"<builtin-template>".into(),
				include_str!("README.j2").into(),
				true
			)
		};
		self.template_filename = template_filename;
		self.template = template;
		self.builtin_template = builtin_template;

		// read crate code
		let file = &target.src_path;
		self.code = if self.cfg.expand_macros {
			CrateCode::read_expansion(
				self.cfg.manifest_path.as_ref(),
				self.pkg,
				target,
				features.as_deref(),
				!self.cfg.default_features,
				self.cfg.all_features
			)?
		} else {
			CrateCode::read_from_disk(file)
				.into_diagnostic()
				.with_context(|| format!("Failed to read source from `{file}'"))?
		};

		// process the target
		self.input_file = input::read_code(
			self.metadata,
			pkg,
			&self.code,
			target_type,
			&mut self.stderr
		)?;

		Ok(())
	}

	/// Create an `io::Read` for the output.
	///
	/// This is used when checking the existing readme file.
	fn out_reader(&self) -> io::Result<impl io::Read> {
		Ok(if self.out.as_str() == "-" {
			Either::Left(io::stdin())
		} else {
			Either::Right(File::open(self.out.as_std_path())?)
		})
	}

	/// Create an `io::Write` for the output.
	fn out_writer(&self) -> io::Result<impl io::Write> {
		Ok(if self.out.as_str() == "-" {
			Either::Left(io::stdout())
		} else {
			Either::Right(File::create(self.out.as_std_path())?)
		})
	}

	/// Check whether this README instance is up to date. Returns `true` if it is, and
	/// `false` if needs updating.
	pub fn check_up2date(self) -> bool {
		let reader = self.out_reader().into_diagnostic().with_context(|| {
			let out_str = if self.out.as_str() == "-" {
				"<stdin>"
			} else {
				self.out.as_str()
			};
			format!("Failed to open {out_str}")
		});
		let reader = match reader {
			Ok(reader) => reader,
			Err(err) => {
				let mut printer = DiagnosticPrinter::new(&self.code, self.stderr);
				printer.print(err);
				return false;
			}
		};

		let res = verify::check_up2date(
			self.input_file,
			&self.template_filename,
			&self.template,
			self.builtin_template,
			reader
		);
		if let Err(err) = res {
			let is_error = err.severity().is_none_or(|s| s == Severity::Error);
			let mut printer = DiagnosticPrinter::new(&self.code, self.stderr);
			printer.print(err);
			return !is_error;
		}

		true
	}

	pub fn emit(self) -> miette::Result<()> {
		let writer = self.out_writer().into_diagnostic().with_context(|| {
			let out_str = if self.out.as_str() == "-" {
				"<stdout>"
			} else {
				self.out.as_str()
			};
			format!("Failed to open {out_str}")
		})?;
		self.emit_to(writer)
	}

	pub fn emit_to(self, writer: impl io::Write) -> miette::Result<()> {
		output::emit(
			&self.input_file,
			&self.template_filename,
			&self.template,
			self.builtin_template,
			writer
		)
	}
}