src/tools/rust-analyzer/crates/project-model/src/project_json.rs - toolchain/rustc - Git at Google

 //! `rust-project.json` file format.
 //!
 //! This format is spiritually a serialization of [`base_db::CrateGraph`]. The
 //! idea here is that people who do not use Cargo, can instead teach their build
 //! system to generate `rust-project.json` which can be ingested by
 //! rust-analyzer.
 //!
 //! This short file is a somewhat big conceptual piece of the architecture of
 //! rust-analyzer, so it's worth elaborating on the underlying ideas and
 //! motivation.
 //!
 //! For rust-analyzer to function, it needs some information about the project.
 //! Specifically, it maintains an in-memory data structure which lists all the
 //! crates (compilation units) and dependencies between them. This is necessary
 //! a global singleton, as we do want, eg, find usages to always search across
 //! the whole project, rather than just in the "current" crate.
 //!
 //! Normally, we get this "crate graph" by calling `cargo metadata
 //! --message-format=json` for each cargo workspace and merging results. This
 //! works for your typical cargo project, but breaks down for large folks who
 //! have a monorepo with an infinite amount of Rust code which is built with bazel or
 //! some such.
 //!
 //! To support this use case, we need to make _something_ configurable. To avoid
 //! a [midlayer mistake](https://lwn.net/Articles/336262/), we allow configuring
 //! the lowest possible layer. `ProjectJson` is essentially a hook to just set
 //! that global singleton in-memory data structure. It is optimized for power,
 //! not for convenience (you'd be using cargo anyway if you wanted nice things,
 //! right? :)
 //!
 //! `rust-project.json` also isn't necessary a file. Architecturally, we support
 //! any convenient way to specify this data, which today is:
 //!
 //! * file on disk
 //! * a field in the config (ie, you can send a JSON request with the contents
 //!   of rust-project.json to rust-analyzer, no need to write anything to disk)
 //!
 //! Another possible thing we don't do today, but which would be totally valid,
 //! is to add an extension point to VS Code extension to register custom
 //! project.
 //!
 //! In general, it is assumed that if you are going to use `rust-project.json`,
 //! you'd write a fair bit of custom code gluing your build system to ra through
 //! this JSON format. This logic can take form of a VS Code extension, or a
 //! proxy process which injects data into "configure" LSP request, or maybe just
 //! a simple build system rule to generate the file.
 //!
 //! In particular, the logic for lazily loading parts of the monorepo as the
 //! user explores them belongs to that extension (it's totally valid to change
 //! rust-project.json over time via configuration request!)

 use base_db::{CrateDisplayName, CrateId, CrateName, Dependency, Edition};
 use la_arena::RawIdx;
 use paths::{AbsPath, AbsPathBuf};
 use rustc_hash::FxHashMap;
 use serde::{de, Deserialize};
 use std::path::PathBuf;

 use crate::cfg_flag::CfgFlag;

 /// Roots and crates that compose this Rust project.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct ProjectJson {
     /// e.g. `path/to/sysroot`
     pub(crate) sysroot: Option<AbsPathBuf>,
     /// e.g. `path/to/sysroot/lib/rustlib/src/rust`
     pub(crate) sysroot_src: Option<AbsPathBuf>,
     project_root: AbsPathBuf,
     crates: Vec<Crate>,
 }

 /// A crate points to the root module of a crate and lists the dependencies of the crate. This is
 /// useful in creating the crate graph.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct Crate {
     pub(crate) display_name: Option<CrateDisplayName>,
     pub(crate) root_module: AbsPathBuf,
     pub(crate) edition: Edition,
     pub(crate) version: Option<String>,
     pub(crate) deps: Vec<Dependency>,
     pub(crate) cfg: Vec<CfgFlag>,
     pub(crate) target: Option<String>,
     pub(crate) env: FxHashMap<String, String>,
     pub(crate) proc_macro_dylib_path: Option<AbsPathBuf>,
     pub(crate) is_workspace_member: bool,
     pub(crate) include: Vec<AbsPathBuf>,
     pub(crate) exclude: Vec<AbsPathBuf>,
     pub(crate) is_proc_macro: bool,
     pub(crate) repository: Option<String>,
 }

 impl ProjectJson {
     /// Create a new ProjectJson instance.
     ///
     /// # Arguments
     ///
     /// * `base` - The path to the workspace root (i.e. the folder containing `rust-project.json`)
     /// * `data` - The parsed contents of `rust-project.json`, or project json that's passed via
     ///            configuration.
     pub fn new(base: &AbsPath, data: ProjectJsonData) -> ProjectJson {
         let absolutize_on_base = |p| base.absolutize(p);
         ProjectJson {
             sysroot: data.sysroot.map(absolutize_on_base),
             sysroot_src: data.sysroot_src.map(absolutize_on_base),
             project_root: base.to_path_buf(),
             crates: data
                 .crates
                 .into_iter()
                 .map(|crate_data| {
                     let root_module = absolutize_on_base(crate_data.root_module);
                     let is_workspace_member = crate_data
                         .is_workspace_member
                         .unwrap_or_else(|| root_module.starts_with(base));
                     let (include, exclude) = match crate_data.source {
                         Some(src) => {
                             let absolutize = |dirs: Vec<PathBuf>| {
                                 dirs.into_iter().map(absolutize_on_base).collect::<Vec<_>>()
                             };
                             (absolutize(src.include_dirs), absolutize(src.exclude_dirs))
                         }
                         None => (vec![root_module.parent().unwrap().to_path_buf()], Vec::new()),
                     };

                     Crate {
                         display_name: crate_data
                             .display_name
                             .map(CrateDisplayName::from_canonical_name),
                         root_module,
                         edition: crate_data.edition.into(),
                         version: crate_data.version.as_ref().map(ToString::to_string),
                         deps: crate_data
                             .deps
                             .into_iter()
                             .map(|dep_data| {
                                 Dependency::new(
                                     dep_data.name,
                                     CrateId::from_raw(RawIdx::from(dep_data.krate as u32)),
                                 )
                             })
                             .collect::<Vec<_>>(),
                         cfg: crate_data.cfg,
                         target: crate_data.target,
                         env: crate_data.env,
                         proc_macro_dylib_path: crate_data
                             .proc_macro_dylib_path
                             .map(absolutize_on_base),
                         is_workspace_member,
                         include,
                         exclude,
                         is_proc_macro: crate_data.is_proc_macro,
                         repository: crate_data.repository,
                     }
                 })
                 .collect(),
         }
     }

     /// Returns the number of crates in the project.
     pub fn n_crates(&self) -> usize {
         self.crates.len()
     }

     /// Returns an iterator over the crates in the project.
     pub fn crates(&self) -> impl Iterator<Item = (CrateId, &Crate)> + '_ {
         self.crates
             .iter()
             .enumerate()
             .map(|(idx, krate)| (CrateId::from_raw(RawIdx::from(idx as u32)), krate))
     }

     /// Returns the path to the project's root folder.
     pub fn path(&self) -> &AbsPath {
         &self.project_root
     }
 }

 #[derive(Deserialize, Debug, Clone)]
 pub struct ProjectJsonData {
     sysroot: Option<PathBuf>,
     sysroot_src: Option<PathBuf>,
     crates: Vec<CrateData>,
 }

 #[derive(Deserialize, Debug, Clone)]
 struct CrateData {
     display_name: Option<String>,
     root_module: PathBuf,
     edition: EditionData,
     #[serde(default)]
     version: Option<semver::Version>,
     deps: Vec<DepData>,
     #[serde(default)]
     cfg: Vec<CfgFlag>,
     target: Option<String>,
     #[serde(default)]
     env: FxHashMap<String, String>,
     proc_macro_dylib_path: Option<PathBuf>,
     is_workspace_member: Option<bool>,
     source: Option<CrateSource>,
     #[serde(default)]
     is_proc_macro: bool,
     #[serde(default)]
     repository: Option<String>,
 }

 #[derive(Deserialize, Debug, Clone)]
 #[serde(rename = "edition")]
 enum EditionData {
     #[serde(rename = "2015")]
     Edition2015,
     #[serde(rename = "2018")]
     Edition2018,
     #[serde(rename = "2021")]
     Edition2021,
     #[serde(rename = "2024")]
     Edition2024,
 }

 impl From<EditionData> for Edition {
     fn from(data: EditionData) -> Self {
         match data {
             EditionData::Edition2015 => Edition::Edition2015,
             EditionData::Edition2018 => Edition::Edition2018,
             EditionData::Edition2021 => Edition::Edition2021,
             EditionData::Edition2024 => Edition::Edition2024,
         }
     }
 }

 #[derive(Deserialize, Debug, Clone)]
 struct DepData {
     /// Identifies a crate by position in the crates array.
     #[serde(rename = "crate")]
     krate: usize,
     #[serde(deserialize_with = "deserialize_crate_name")]
     name: CrateName,
 }

 #[derive(Deserialize, Debug, Clone)]
 struct CrateSource {
     include_dirs: Vec<PathBuf>,
     exclude_dirs: Vec<PathBuf>,
 }

 fn deserialize_crate_name<'de, D>(de: D) -> std::result::Result<CrateName, D::Error>
 where
     D: de::Deserializer<'de>,
 {
     let name = String::deserialize(de)?;
     CrateName::new(&name).map_err(|err| de::Error::custom(format!("invalid crate name: {err:?}")))
 }
	//! `rust-project.json` file format.
	//!
	//! This format is spiritually a serialization of [`base_db::CrateGraph`]. The
	//! idea here is that people who do not use Cargo, can instead teach their build
	//! system to generate `rust-project.json` which can be ingested by
	//! rust-analyzer.
	//!
	//! This short file is a somewhat big conceptual piece of the architecture of
	//! rust-analyzer, so it's worth elaborating on the underlying ideas and
	//! motivation.
	//!
	//! For rust-analyzer to function, it needs some information about the project.
	//! Specifically, it maintains an in-memory data structure which lists all the
	//! crates (compilation units) and dependencies between them. This is necessary
	//! a global singleton, as we do want, eg, find usages to always search across
	//! the whole project, rather than just in the "current" crate.
	//!
	//! Normally, we get this "crate graph" by calling `cargo metadata
	//! --message-format=json` for each cargo workspace and merging results. This
	//! works for your typical cargo project, but breaks down for large folks who
	//! have a monorepo with an infinite amount of Rust code which is built with bazel or
	//! some such.
	//!
	//! To support this use case, we need to make _something_ configurable. To avoid
	//! a [midlayer mistake](https://lwn.net/Articles/336262/), we allow configuring
	//! the lowest possible layer. `ProjectJson` is essentially a hook to just set
	//! that global singleton in-memory data structure. It is optimized for power,
	//! not for convenience (you'd be using cargo anyway if you wanted nice things,
	//! right? :)
	//!
	//! `rust-project.json` also isn't necessary a file. Architecturally, we support
	//! any convenient way to specify this data, which today is:
	//!
	//! * file on disk
	//! * a field in the config (ie, you can send a JSON request with the contents
	//! of rust-project.json to rust-analyzer, no need to write anything to disk)
	//!
	//! Another possible thing we don't do today, but which would be totally valid,
	//! is to add an extension point to VS Code extension to register custom
	//! project.
	//!
	//! In general, it is assumed that if you are going to use `rust-project.json`,
	//! you'd write a fair bit of custom code gluing your build system to ra through
	//! this JSON format. This logic can take form of a VS Code extension, or a
	//! proxy process which injects data into "configure" LSP request, or maybe just
	//! a simple build system rule to generate the file.
	//!
	//! In particular, the logic for lazily loading parts of the monorepo as the
	//! user explores them belongs to that extension (it's totally valid to change
	//! rust-project.json over time via configuration request!)

	use base_db::{CrateDisplayName, CrateId, CrateName, Dependency, Edition};
	use la_arena::RawIdx;
	use paths::{AbsPath, AbsPathBuf};
	use rustc_hash::FxHashMap;
	use serde::{de, Deserialize};
	use std::path::PathBuf;

	use crate::cfg_flag::CfgFlag;

	/// Roots and crates that compose this Rust project.
	#[derive(Clone, Debug, Eq, PartialEq)]
	pub struct ProjectJson {
	/// e.g. `path/to/sysroot`
	pub(crate) sysroot: Option<AbsPathBuf>,
	/// e.g. `path/to/sysroot/lib/rustlib/src/rust`
	pub(crate) sysroot_src: Option<AbsPathBuf>,
	project_root: AbsPathBuf,
	crates: Vec<Crate>,
	}

	/// A crate points to the root module of a crate and lists the dependencies of the crate. This is
	/// useful in creating the crate graph.
	#[derive(Clone, Debug, Eq, PartialEq)]
	pub struct Crate {
	pub(crate) display_name: Option<CrateDisplayName>,
	pub(crate) root_module: AbsPathBuf,
	pub(crate) edition: Edition,
	pub(crate) version: Option<String>,
	pub(crate) deps: Vec<Dependency>,
	pub(crate) cfg: Vec<CfgFlag>,
	pub(crate) target: Option<String>,
	pub(crate) env: FxHashMap<String, String>,
	pub(crate) proc_macro_dylib_path: Option<AbsPathBuf>,
	pub(crate) is_workspace_member: bool,
	pub(crate) include: Vec<AbsPathBuf>,
	pub(crate) exclude: Vec<AbsPathBuf>,
	pub(crate) is_proc_macro: bool,
	pub(crate) repository: Option<String>,
	}

	impl ProjectJson {
	/// Create a new ProjectJson instance.
	///
	/// # Arguments
	///
	/// * `base` - The path to the workspace root (i.e. the folder containing `rust-project.json`)
	/// * `data` - The parsed contents of `rust-project.json`, or project json that's passed via
	/// configuration.
	pub fn new(base: &AbsPath, data: ProjectJsonData) -> ProjectJson {
	let absolutize_on_base = \|p\| base.absolutize(p);
	ProjectJson {
	sysroot: data.sysroot.map(absolutize_on_base),
	sysroot_src: data.sysroot_src.map(absolutize_on_base),
	project_root: base.to_path_buf(),
	crates: data
	.crates
	.into_iter()
	.map(\|crate_data\| {
	let root_module = absolutize_on_base(crate_data.root_module);
	let is_workspace_member = crate_data
	.is_workspace_member
	.unwrap_or_else(\|\| root_module.starts_with(base));
	let (include, exclude) = match crate_data.source {
	Some(src) => {
	let absolutize = \|dirs: Vec<PathBuf>\| {
	dirs.into_iter().map(absolutize_on_base).collect::<Vec<_>>()
	};
	(absolutize(src.include_dirs), absolutize(src.exclude_dirs))
	}
	None => (vec![root_module.parent().unwrap().to_path_buf()], Vec::new()),
	};

	Crate {
	display_name: crate_data
	.display_name
	.map(CrateDisplayName::from_canonical_name),
	root_module,
	edition: crate_data.edition.into(),
	version: crate_data.version.as_ref().map(ToString::to_string),
	deps: crate_data
	.deps
	.into_iter()
	.map(\|dep_data\| {
	Dependency::new(
	dep_data.name,
	CrateId::from_raw(RawIdx::from(dep_data.krate as u32)),
	)
	})
	.collect::<Vec<_>>(),
	cfg: crate_data.cfg,
	target: crate_data.target,
	env: crate_data.env,
	proc_macro_dylib_path: crate_data
	.proc_macro_dylib_path
	.map(absolutize_on_base),
	is_workspace_member,
	include,
	exclude,
	is_proc_macro: crate_data.is_proc_macro,
	repository: crate_data.repository,
	}
	})
	.collect(),
	}
	}

	/// Returns the number of crates in the project.
	pub fn n_crates(&self) -> usize {
	self.crates.len()
	}

	/// Returns an iterator over the crates in the project.
	pub fn crates(&self) -> impl Iterator<Item = (CrateId, &Crate)> + '_ {
	self.crates
	.iter()
	.enumerate()
	.map(\|(idx, krate)\| (CrateId::from_raw(RawIdx::from(idx as u32)), krate))
	}

	/// Returns the path to the project's root folder.
	pub fn path(&self) -> &AbsPath {
	&self.project_root
	}
	}

	#[derive(Deserialize, Debug, Clone)]
	pub struct ProjectJsonData {
	sysroot: Option<PathBuf>,
	sysroot_src: Option<PathBuf>,
	crates: Vec<CrateData>,
	}

	#[derive(Deserialize, Debug, Clone)]
	struct CrateData {
	display_name: Option<String>,
	root_module: PathBuf,
	edition: EditionData,
	#[serde(default)]
	version: Option<semver::Version>,
	deps: Vec<DepData>,
	#[serde(default)]
	cfg: Vec<CfgFlag>,
	target: Option<String>,
	#[serde(default)]
	env: FxHashMap<String, String>,
	proc_macro_dylib_path: Option<PathBuf>,
	is_workspace_member: Option<bool>,
	source: Option<CrateSource>,
	#[serde(default)]
	is_proc_macro: bool,
	#[serde(default)]
	repository: Option<String>,
	}

	#[derive(Deserialize, Debug, Clone)]
	#[serde(rename = "edition")]
	enum EditionData {
	#[serde(rename = "2015")]
	Edition2015,
	#[serde(rename = "2018")]
	Edition2018,
	#[serde(rename = "2021")]
	Edition2021,
	#[serde(rename = "2024")]
	Edition2024,
	}

	impl From<EditionData> for Edition {
	fn from(data: EditionData) -> Self {
	match data {
	EditionData::Edition2015 => Edition::Edition2015,
	EditionData::Edition2018 => Edition::Edition2018,
	EditionData::Edition2021 => Edition::Edition2021,
	EditionData::Edition2024 => Edition::Edition2024,
	}
	}
	}

	#[derive(Deserialize, Debug, Clone)]
	struct DepData {
	/// Identifies a crate by position in the crates array.
	#[serde(rename = "crate")]
	krate: usize,
	#[serde(deserialize_with = "deserialize_crate_name")]
	name: CrateName,
	}

	#[derive(Deserialize, Debug, Clone)]
	struct CrateSource {
	include_dirs: Vec<PathBuf>,
	exclude_dirs: Vec<PathBuf>,
	}

	fn deserialize_crate_name<'de, D>(de: D) -> std::result::Result<CrateName, D::Error>
	where
	D: de::Deserializer<'de>,
	{
	let name = String::deserialize(de)?;
	CrateName::new(&name).map_err(\|err\| de::Error::custom(format!("invalid crate name: {err:?}")))
	}