JSON output for scarb-doc

extensions/scarb-doc/src/lib.rs

@@ -1,5 +1,3 @@
-use anyhow::Result;
-
 use cairo_lang_compiler::project::ProjectConfig;
 use cairo_lang_filesystem::db::FilesGroup;
 use cairo_lang_filesystem::ids::CrateLongId;
@@ -10,14 +8,15 @@ use types::Crate;
 pub mod compilation;
 pub mod db;
 pub mod types;
+pub mod versioned_json_output;
 
 pub fn generate_language_elements_tree_for_package(
     package_name: String,
     project_config: ProjectConfig,
-) -> Result<Crate> {
+) -> Crate {
     let db = ScarbDocDatabase::new(Some(project_config));
 
     let main_crate_id = db.intern_crate(CrateLongId::Real(package_name.into()));
 
-    Ok(Crate::new(&db, main_crate_id))
+    Crate::new(&db, main_crate_id)
 }

extensions/scarb-doc/src/main.rs

@@ -1,30 +1,89 @@
-use anyhow::Result;
+use anyhow::{Context, Result};
 use clap::Parser;
 use scarb_doc::compilation::get_project_config;
+use std::collections::BTreeMap;
+use std::fs;
 
 use scarb_metadata::MetadataCommand;
 use scarb_ui::args::PackagesFilter;
 
 use scarb_doc::generate_language_elements_tree_for_package;
+use scarb_doc::versioned_json_output::VersionedJsonOutput;
+
+#[derive(Default, Debug, Clone, clap::ValueEnum)]
+enum OutputFormat {
+    /// Generates documentation in Markdown format.
+    #[default]
+    Markdown,
+    /// Saves information collected from packages in JSON format instead of generating
+    /// documentation.
+    /// This may be useful if you want to generate documentation files by yourself.
+    /// The precise output structure is not guaranteed to be stable.
+    Json,
+}
 
 #[derive(Parser, Debug)]
 #[command(version, about, long_about = None)]
 struct Args {
     #[command(flatten)]
     packages_filter: PackagesFilter,
+
+    /// Specifies a format of generated files.
+    #[arg(long, value_enum, default_value_t)]
+    output_format: OutputFormat,
 }
 
-fn main() -> Result<()> {
+fn main_inner() -> Result<()> {
     let args = Args::parse();
 
-    let metadata = MetadataCommand::new().inherit_stderr().exec()?;
+    let metadata = MetadataCommand::new()
+        .inherit_stderr()
+        .exec()
+        .context("metadata command failed")?;
     let metadata_for_packages = args.packages_filter.match_many(&metadata)?;
 
+    let mut package_information_map = BTreeMap::new();
+
     for package_metadata in metadata_for_packages {
         let project_config = get_project_config(&metadata, &package_metadata);
-        let _crate_ =
-            generate_language_elements_tree_for_package(package_metadata.name, project_config)?;
+        let crate_ = generate_language_elements_tree_for_package(
+            package_metadata.name.clone(),
+            project_config,
+        );
+
+        package_information_map.insert(package_metadata.name, crate_);
+    }
+
+    let output_dir = metadata
+        .target_dir
+        .unwrap_or_else(|| metadata.workspace.root.join("target"))
+        .join("doc");
+
+    fs::create_dir_all(&output_dir).context("failed to create output directory for scarb doc")?;
+
+    match args.output_format {
+        OutputFormat::Json => {
+            let versioned_json_output = VersionedJsonOutput::new(package_information_map);
+            let output = serde_json::to_string_pretty(&versioned_json_output)
+                .expect("failed to serialize information about crates");
+            let output_path = output_dir.join("output.json");
+
+            fs::write(output_path, output)
+                .context("failed to write output of scarb doc to a file")?;
+        }
+        OutputFormat::Markdown => todo!("#1424"),
     }
 
     Ok(())
 }
+
+fn main() {
+    match main_inner() {
+        Ok(()) => std::process::exit(0),
+        Err(error) => {
+            scarb_ui::Ui::new(scarb_ui::Verbosity::Normal, scarb_ui::OutputFormat::Text)
+                .error(error.to_string());
+            std::process::exit(1);
+        }
+    }
+}

extensions/scarb-doc/src/versioned_json_output.rs

@@ -0,0 +1,22 @@
+use crate::types::Crate;
+use serde::Serialize;
+use std::collections::BTreeMap;
+
+type PackageName = String;
+
+const FORMAT_VERSION: u8 = 1;
+
+#[derive(Serialize)]
+pub struct VersionedJsonOutput {
+    format_version: u8,
+    pub package_information_map: BTreeMap<PackageName, Crate>,
+}
+
+impl VersionedJsonOutput {
+    pub fn new(package_information_map: BTreeMap<PackageName, Crate>) -> Self {
+        Self {
+            format_version: FORMAT_VERSION,
+            package_information_map,
+        }
+    }
+}