mavspec_rust_gen 0.6.7

use std::collections::HashSet;
use std::ffi::OsStr;
use std::fs::remove_dir_all;
use std::path::{Path, PathBuf};
use std::sync::Arc;

extern crate cargo_manifest;
use crate::error::RustGenResult;
use cargo_manifest::{Manifest, Value};
use mavinspect::parser::InspectorBuilder;
use mavinspect::protocol::{Filter, Microservices, Protocol};
use mavinspect::Inspector;

use crate::generator::{Generator, GeneratorParams};

/// Code builder for Rust generator.
///
/// # Usage
///
/// ```rust
/// # use std::fs::remove_dir_all;
/// use mavinspect::protocol::Microservices;
/// use mavspec::rust::gen::BuildHelper;
///
/// // Paths to XML definitions directories.
/// let sources = vec![
///     "./message_definitions/standard",
/// ];
/// // Output path
/// let destination = "../tmp/mavlink";
/// # let destination = "../tmp/mavlink/build_helper";
///
/// // Generate rust bindings
/// BuildHelper::builder(destination)
///     .set_sources(&sources)
///     // Only include the following dialects
///     .set_include_dialects(&["minimal", "common", "ardupilotmega"])
///     // Explicitly exclude the following dialects
///     .set_exclude_dialects(&["ardupilotmega"])
///     // Include only entities from the following MAVLink microservices
///     .set_microservices(&["HEARTBEAT", "COMMAND"])
///     // Explicitly add messages
///     .set_messages(&["PROTOCOL_VERSION"])
///     .generate()
///     .unwrap();
/// # remove_dir_all(destination).unwrap_or_default();
/// ```
#[derive(Clone, Debug, Default)]
pub struct BuildHelper {
    out_path: PathBuf,
    sources: Option<Vec<PathBuf>>,
    manifest_path: Option<PathBuf>,
    include_dialects: Option<HashSet<String>>,
    exclude_dialects: Option<HashSet<String>>,
    messages: Option<Vec<String>>,
    enums: Option<Vec<String>>,
    commands: Option<Vec<String>>,
    protocol: Option<Arc<Protocol>>,
    microservices: Option<Microservices>,
    serde: bool,
    specta: bool,
    generate_tests: Option<bool>,
    internal: bool,
}

/// Configuration builder for [`BuildHelper`].
#[derive(Clone, Debug, Default)]
pub struct BuildHelperBuilder(BuildHelper);

impl BuildHelper {
    /// Creates configuration builder for [`BuildHelper`].
    ///
    /// Takes `out_path` as argument. The output path for generated content.
    pub fn builder<T: Into<PathBuf>>(out_path: T) -> BuildHelperBuilder {
        BuildHelperBuilder(Self {
            out_path: out_path.into(),
            ..Default::default()
        })
    }

    /// Scans for dialects and generates MAVLink dialects.
    pub fn generate(&self) -> RustGenResult<()> {
        if let Err(err) = remove_dir_all(&self.out_path) {
            log::debug!("Error while cleaning output directory: {err:?}");
        }

        let protocol = self.load_filtered_protocol()?;

        Generator::make(
            protocol,
            &self.out_path,
            GeneratorParams {
                serde: self.serde,
                specta: self.specta,
                generate_tests: self.generate_tests.unwrap_or(false),
                internal: self.internal,
                ..Default::default()
            },
        )
        .generate()?;

        Ok(())
    }

    /// Output path for autogenerated files.
    pub fn out_path(&self) -> &Path {
        self.out_path.as_path()
    }

    /// List of directories with MAVLink XML definitions.
    pub fn sources(&self) -> Option<Vec<&Path>> {
        self.sources
            .as_ref()
            .map(|sources| sources.iter().map(|src| src.as_path()).collect())
    }

    /// Path to `Cargo.toml` from which meta information will be extracted.
    ///
    /// You can specify configuration in your `Cargo.toml` file:
    ///
    /// ```toml
    /// [package.metadata.mavspec]
    /// microservices = ["HEARTBEAT", "MISSION", "COMMAND"]
    /// messages = ["PROTOCOL_VERSION", "MAV_INSPECT_V1", "PING"]
    /// enums = ["STORAGE_STATUS", "GIMBAL_*"]
    /// commands = ["MAV_CMD_DO_CHANGE_SPEED", "MAV_CMD_DO_SET_ROI*"]
    /// generate_tests = false
    /// ```
    ///
    /// If [`Self::manifest_path`] is set, then the following parameters will be populated from keys in `Cargo.toml`:
    ///
    /// * [`Self::microservices`] from `microservices` key.
    /// * [`Self::messages`] from `messages` key.
    /// * [`Self::enums`] from `enums` key.
    /// * [`Self::commands`] from `commands` key.
    /// * [`Self::generate_tests`] from `generate_tests` key.
    ///
    /// Note that if set explicitly, these parameters has precedence over keys from manifest.
    pub fn manifest_path(&self) -> Option<&Path> {
        self.manifest_path.as_deref()
    }

    /// Included dialects.
    pub fn include_dialects(&self) -> Option<HashSet<&str>> {
        self.include_dialects.as_ref().map(|include_dialects| {
            include_dialects
                .iter()
                .map(|dialect| dialect.as_str())
                .collect()
        })
    }

    /// Excluded dialects.
    pub fn exclude_dialects(&self) -> Option<HashSet<&str>> {
        self.exclude_dialects.as_ref().map(|include_dialects| {
            include_dialects
                .iter()
                .map(|dialect| dialect.as_str())
                .collect()
        })
    }

    /// If set, then defines the list of MAVLink messages to generate.
    ///
    /// If [`Self::microservices`] are set, then the `messages` will be included in addition to those defined by
    /// microservices specifications.
    pub fn messages(&self) -> Option<Vec<&str>> {
        self.messages
            .as_ref()
            .map(|messages| messages.iter().map(|msg| msg.as_str()).collect())
    }

    /// If set, then defines the list of MAVLink enums to generate.
    ///
    /// If [`Self::microservices`] are set, then the `enums` will be included in addition to those defined by
    /// microservices specifications.
    pub fn enums(&self) -> Option<Vec<&str>> {
        self.enums
            .as_ref()
            .map(|enums| enums.iter().map(|msg| msg.as_str()).collect())
    }

    /// If set, then defines the list of MAVLink commands to generate.
    ///
    /// If [`Self::microservices`] are set, then the `commands` will be included in addition to those defined by
    /// microservices specifications.
    pub fn commands(&self) -> Option<Vec<&str>> {
        self.commands
            .as_ref()
            .map(|commands| commands.iter().map(|msg| msg.as_str()).collect())
    }

    /// If set, then defines MAVLink [microservices](https://mavlink.io/en/services/) to be generated.
    ///
    /// All messages from [`Self::messages`] will be included regardless of microservices specifications.
    pub fn microservices(&self) -> Option<&Microservices> {
        self.microservices.as_ref()
    }

    /// MAVLink protocol containing parsed dialects.
    pub fn protocol(&self) -> Option<&Protocol> {
        match &self.protocol {
            None => None,
            Some(protocol) => Some(protocol.as_ref()),
        }
    }

    /// [Serde](https://serde.rs/) support flag for generated entities.
    pub fn serde(&self) -> bool {
        self.serde
    }

    /// [Specta](https://crates.io/crates/specta) support flag for generated entities.
    pub fn specta(&self) -> bool {
        self.specta
    }

    /// Tests generation flag.
    ///
    /// If set to `true`, then tests will be generated.
    pub fn generate_tests(&self) -> bool {
        self.generate_tests.unwrap_or(false)
    }

    /// <sup>`⚠`</sup> Use imports for generating entities inside MAVSpec.
    ///
    /// **DO NOT SET** unless you know what you are doing!
    pub fn internal(&self) -> bool {
        self.internal
    }

    fn load_filtered_protocol(&self) -> RustGenResult<Arc<Protocol>> {
        Ok(if let Some(protocol) = &self.protocol {
            protocol.clone()
        } else {
            let inspector_builder = self.make_mavlink_inspector_builder();

            let mut protocol = inspector_builder.build()?.parse()?;
            self.retain_protocol_entities(&mut protocol);

            Arc::new(protocol)
        })
    }

    fn make_mavlink_inspector_builder(&self) -> InspectorBuilder {
        let mut inspector_builder = Inspector::builder();

        let sources: Vec<&Path> = self
            .sources
            .as_ref()
            .unwrap()
            .iter()
            .map(|s| s.as_path())
            .collect();
        inspector_builder.set_sources(&sources);

        if let Some(include_dialects) = &self.include_dialects {
            inspector_builder
                .set_include(&Vec::from_iter(include_dialects.iter().map(|d| d.as_str())));
        }
        if let Some(exclude_dialects) = &self.exclude_dialects {
            inspector_builder
                .set_exclude(&Vec::from_iter(exclude_dialects.iter().map(|d| d.as_str())));
        }

        inspector_builder
    }

    fn retain_protocol_entities(&self, protocol: &mut Protocol) {
        let mut filters = Filter::new();
        if let Some(microservices) = &self.microservices {
            filters = filters.with_microservices(*microservices);
        }
        if let Some(messages) = &self.messages {
            filters = filters.with_messages(messages);
        }
        if let Some(enums) = &self.enums {
            filters = filters.with_enums(enums);
        }
        if let Some(commands) = &self.commands {
            filters = filters.with_commands(commands);
        }

        protocol.retain(&filters);
    }

    fn apply_manifest_config(&mut self) -> RustGenResult<()> {
        // Spaghetti mode: ON
        if let Some(manifest_path) = &self.manifest_path {
            let manifest = Manifest::from_path(manifest_path)?;
            if let Some(package) = manifest.package {
                if let Some(metadata) = package.metadata {
                    if let Some(spec) = metadata.get("mavspec") {
                        // Spaghetti mode: OFF
                        self.apply_manifest_config_spec(spec);
                    }
                }
            }
        }
        Ok(())
    }

    fn apply_manifest_config_spec(&mut self, spec: &Value) {
        self.apply_manifest_config_messages(spec);
        self.apply_manifest_config_enums(spec);
        self.apply_manifest_config_commands(spec);
        self.apply_manifest_config_microservices(spec);

        if let Some(Value::Boolean(generate_tests)) = spec.get("generate_tests") {
            self.generate_tests = Some(*generate_tests);
        }
    }

    fn apply_manifest_config_messages(&mut self, spec: &Value) {
        if let Some(Value::Array(msgs)) = spec.get("messages") {
            if self.messages.is_none() {
                self.messages = Some(Vec::from_iter(
                    msgs.iter().map(|v| v.to_string().replace('"', "")),
                ));
            }
        }
    }

    fn apply_manifest_config_enums(&mut self, spec: &Value) {
        if let Some(Value::Array(msgs)) = spec.get("enums") {
            if self.enums.is_none() {
                self.enums = Some(Vec::from_iter(
                    msgs.iter().map(|v| v.to_string().replace('"', "")),
                ));
            }
        }
    }

    fn apply_manifest_config_commands(&mut self, spec: &Value) {
        if let Some(Value::Array(msgs)) = spec.get("commands") {
            if self.commands.is_none() {
                self.commands = Some(Vec::from_iter(
                    msgs.iter().map(|v| v.to_string().replace('"', "")),
                ));
            }
        }
    }

    fn apply_manifest_config_microservices(&mut self, spec: &Value) {
        if let Some(Value::Array(msgs)) = spec.get("microservices") {
            if self.microservices.is_none() {
                let mut microservices = Microservices::default();
                let flags_map = Microservices::flags_map();

                for flag_name in msgs.iter().map(|v| v.to_string().replace('"', "")) {
                    if let Some(microservice_flag) = flags_map.get(flag_name.as_str()) {
                        microservices |= *microservice_flag;
                    }
                }

                self.microservices = Some(microservices);
            }
        }
    }
}

impl BuildHelperBuilder {
    /// Default constructor.
    pub fn new() -> Self {
        Self::default()
    }

    /// Builds [`BuildHelper`] from configuration.
    pub fn build(&self) -> RustGenResult<BuildHelper> {
        let mut helper = self.0.clone();
        if helper.manifest_path.is_some() {
            helper.apply_manifest_config()?;
        }

        Ok(helper)
    }

    /// Builds [`BuildHelper`] and use it to generates dialects according to configuration.
    pub fn generate(&self) -> RustGenResult<()> {
        self.build()?.generate()
    }

    /// Set paths to MAVLink XML definitions directories. Discards [`Self::set_protocol`].
    ///
    /// If sources are set then [`Self::set_sources`] wil be discarded and MAVLink message definitions will be read from
    /// these specified `sources`. This enables parameters related to XML definitions parsing and filtering.
    ///
    /// The following parameters will take effect:
    ///
    /// * [`Self::set_include_dialects`],
    /// * [`Self::set_exclude_dialects`],
    /// * [`Self::set_microservices`],
    /// * [`Self::set_messages`],
    /// * [`Self::set_enums`],
    /// * [`Self::set_commands`],
    /// * [`Self::set_manifest_path`].
    pub fn set_sources<T>(&mut self, sources: &[T]) -> &mut Self
    where
        T: ?Sized + Into<PathBuf> + Clone,
    {
        self.0.sources = Some(sources.iter().cloned().map(|src| src.into()).collect());
        self.0.manifest_path = None;
        self
    }

    /// Set path to `Cargo.toml` manifest.
    ///
    /// You can control which messages to include by specifying `messages` key in your `Cargo.toml`:
    ///
    /// ```toml
    /// [package.metadata.mavspec]
    /// microservices = ["HEARTBEAT", "MISSION"]
    /// messages = ["PROTOCOL_VERSION", "MAV_INSPECT_V1", "PING"]
    /// enums = ["STORAGE_STATUS", "GIMBAL_*"]
    /// commands = ["MAV_CMD_DO_CHANGE_SPEED", "MAV_CMD_DO_SET_ROI*"]
    /// generate_tests = false
    /// ```
    ///
    /// The following parameters have precedence over configuration defined in Cargo manifest:
    ///
    /// * [`Self::set_microservices`] replaces `microservices` key.
    /// * [`Self::set_messages`] replaces `messages` key.
    /// * [`Self::set_enums`] replaces `enums` key.
    /// * [`Self::set_commands`] replaces `commands` key.
    /// * [`Self::set_generate_tests`] replaces `generate_tests` key.
    pub fn set_manifest_path<T: ?Sized + AsRef<OsStr>>(&mut self, manifest_path: &T) -> &mut Self {
        self.0.manifest_path = Some(PathBuf::from(manifest_path));
        self
    }

    /// Set dialects list. Only dialects from this list will be generated.
    ///
    /// Does not includes dialects ignored by [`Self::set_exclude_dialects`].
    ///
    /// This does not apply to dialect dependencies. If specified dialect has `<include>` tag, all these dialects will
    /// be generated as well.
    pub fn set_include_dialects<T: ToString>(&mut self, include_dialects: &[T]) -> &mut Self {
        self.0.include_dialects = Some(HashSet::from_iter(
            include_dialects.iter().map(|s| s.to_string()),
        ));
        self
    }

    /// Set dialects exclusion list. Dialects from this list will not be generated.
    ///
    /// Has precedence over [`Self::set_include_dialects`].
    ///
    /// This does not apply to dialect dependencies. If a dialect has `<include>` tag, all these dialects will
    /// be generated as well.
    pub fn set_exclude_dialects<T: ToString>(&mut self, include_dialects: &[T]) -> &mut Self {
        self.0.include_dialects = Some(HashSet::from_iter(
            include_dialects.iter().map(|s| s.to_string()),
        ));
        self
    }

    /// Defines which messages will be generated.
    ///
    /// Overrides `messages` configuration key defined by [`Self::set_manifest_path`].
    ///
    /// If [`Self::set_microservices`] are set, then the `messages` will be included in addition to those defined by
    /// microservices specifications.
    pub fn set_messages<T: ToString>(&mut self, messages: &[T]) -> &mut Self {
        self.0.messages = Some(Vec::from_iter(messages.iter().map(|s| s.to_string())));
        self
    }

    /// Defines which enums will be generated.
    ///
    /// Overrides `enums` configuration key defined by [`Self::set_manifest_path`].
    ///
    /// If [`Self::set_microservices`] are set, then the `enums` will be included in addition to those defined by
    /// microservices specifications.
    pub fn set_enums<T: ToString>(&mut self, enums: &[T]) -> &mut Self {
        self.0.enums = Some(Vec::from_iter(enums.iter().map(|s| s.to_string())));
        self
    }

    /// Defines which commands will be generated.
    ///
    /// Overrides `commands` configuration key defined by [`Self::set_manifest_path`].
    ///
    /// If [`Self::set_microservices`] are set, then the `commands` will be included in addition to those defined by
    /// microservices specifications.
    pub fn set_commands<T: ToString>(&mut self, commands: &[T]) -> &mut Self {
        self.0.commands = Some(Vec::from_iter(commands.iter().map(|s| s.to_string())));
        self
    }

    /// Defines which MAVLink [microservices](https://mavlink.io/en/services/) will be generated.
    ///
    /// The list of available microservices and their names matches [`Microservices`] flags of MAVInspect.
    ///
    /// Overrides `microservices` configuration key defined by [`Self::set_manifest_path`].
    ///
    /// All messages defined by [`Self::set_messages`] will be included regardless of microservices specifications.
    pub fn set_microservices<T: ToString>(&mut self, microservices: &[T]) -> &mut Self {
        let mut microservices_ = Microservices::default();
        for microservice in microservices {
            microservices_ |= Microservices::from(microservice.to_string())
        }

        self.0.microservices = Some(microservices_);
        self
    }

    /// Enables/disables [Serde](https://serde.rs/) support for generated entities.
    pub fn set_serde(&mut self, serde: bool) -> &mut Self {
        self.0.serde = serde;
        self
    }

    /// Enables/disables [Specta](https://crates.io/crates/specta) support for generated entities.
    pub fn set_specta(&mut self, specta: bool) -> &mut Self {
        self.0.specta = specta;
        self
    }

    /// Manually define MAVInspect [`Protocol`].
    ///
    /// If set, then [`Self::set_sources`] will be discarded and all parameters controlling MAVLink XML definitions will
    /// be ignored.
    ///
    /// These parameters will be ignored upon protocol setting:
    ///
    /// * [`Self::set_include_dialects`],
    /// * [`Self::set_exclude_dialects`],
    /// * [`Self::set_messages`],
    /// * [`Self::set_enums`],
    /// * [`Self::set_commands`],
    /// * [`Self::set_manifest_path`].
    pub fn set_protocol(&mut self, protocol: Protocol) -> &mut Self {
        self.0.protocol = Some(Arc::new(protocol));
        self.0.sources = None;
        self
    }

    /// Enables/disables tests generation.
    ///
    /// Set to `true` if you want include autogenerated tests.
    ///
    /// Overrides `generate_tests` configuration flag set by [`Self::set_manifest_path`].
    pub fn set_generate_tests(&mut self, generate_tests: bool) -> &mut Self {
        self.0.generate_tests = Some(generate_tests);
        self
    }

    /// <sup>`⚠`</sup> Enables/disables internal generation.
    ///
    /// Set to `true` only if used within MAVSpec.
    ///
    /// **DO NOT SET** unless you know what you are doing!
    pub fn set_internal(&mut self, internal: bool) -> &mut Self {
        self.0.internal = internal;
        self
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::fs::remove_dir_all;
    use std::path::Path;

    #[test]
    fn build_helper_basic() {
        let out_path = "../tmp/mavlink/helper_basics";
        BuildHelper::builder(Path::new(out_path))
            .set_sources(&[
                PathBuf::from("message_definitions").join("standard"),
                PathBuf::from("message_definitions").join("test"),
            ])
            .set_include_dialects(&["minimal"])
            .generate()
            .unwrap();

        remove_dir_all(out_path).unwrap();
    }

    #[test]
    fn build_helper_new_generic() {
        // Accepts `&str`.
        BuildHelper::builder("../tmp/mavlink");

        // Accepts `String`.
        BuildHelper::builder("../tmp/mavlink".to_string());

        // Accepts `&Path`.
        BuildHelper::builder(Path::new("../tmp/mavlink"));

        // Accepts `PathBuf`
        BuildHelper::builder(Path::new("../tmp").join("mavlink"));
    }

    #[test]
    fn build_helper_set_sources_generic() {
        // Accepts `&str`.
        BuildHelper::builder("../tmp/mavlink").set_sources(&["./message_definitions/standard"]);

        // Accepts `String`.
        BuildHelper::builder("../tmp/mavlink")
            .set_sources(&["./message_definitions/standard".to_string()]);

        // Accepts `&Path`.
        BuildHelper::builder("../tmp/mavlink")
            .set_sources(&[Path::new("./message_definitions/standard")]);

        // Accepts `PathBuf`
        BuildHelper::builder("../tmp/mavlink")
            .set_sources(&[Path::new("./message_definitions").join("extra")]);
    }

    #[test]
    fn build_helper_protocol_filtering() {
        let out_path = "../tmp/mavlink/protocol_filtering";
        let protocol = BuildHelper::builder(Path::new(out_path))
            .set_sources(&[
                PathBuf::from("message_definitions").join("standard"),
                PathBuf::from("message_definitions").join("test"),
            ])
            .set_microservices(&["HEARTBEAT", "FTP", "GIMBAL_V1"])
            .set_messages(&["PROTOCOL_VERSION", "MAV_INSPECT_V1"])
            .set_commands(&["MAV_CMD_DO_CHANGE_SPEED", "MAV_CMD_DO_SET_ROI*"])
            .set_enums(&["STORAGE_STATUS", "GIMBAL_*"])
            .set_include_dialects(&["minimal", "standard", "common", "mav_inspect_test"])
            .build()
            .unwrap()
            .load_filtered_protocol()
            .unwrap();

        let dialect = protocol.get_dialect_by_canonical_name("common").unwrap();

        // `MAV_CMD` enum should be present
        assert!(dialect.contains_enum_with_name("MAV_CMD"));
        let mav_cmd = dialect.get_enum_by_name("MAV_CMD").unwrap();

        // These messages are required by command protocol
        assert!(dialect.contains_message_with_name("COMMAND_LONG"));
        assert!(dialect.contains_message_with_name("COMMAND_INT"));
        assert!(dialect.contains_message_with_name("COMMAND_ACK"));
        assert!(dialect.contains_message_with_name("COMMAND_CANCEL"));

        // This enum is required by command protocol
        assert!(dialect.contains_enum_with_name("MAV_FRAME"));

        // This enum is required by `MAV_CMD_DO_CHANGE_SPEED` command
        assert!(dialect.contains_enum_with_name("SPEED_TYPE"));
        // These enums are required by `MAV_CMD_DO_SET_ROI*` commands
        assert!(dialect.contains_enum_with_name("MAV_ROI"));

        // These commands were explicitly requested
        assert!(mav_cmd.has_entry_with_name("MAV_CMD_DO_CHANGE_SPEED"));
        assert!(mav_cmd.has_entry_with_name("MAV_CMD_DO_SET_ROI"));
        assert!(mav_cmd.has_entry_with_name("MAV_CMD_DO_SET_ROI_LOCATION"));
        assert!(mav_cmd.has_entry_with_name("MAV_CMD_DO_SET_ROI_NONE"));
        /* and others */

        // These commands should not be present
        assert!(!mav_cmd.has_entry_with_name("MAV_CMD_DO_INVERTED_FLIGHT"));
        assert!(!mav_cmd.has_entry_with_name("MAV_CMD_DO_GRIPPER"));
        assert!(!mav_cmd.has_entry_with_name("MAV_CMD_PREFLIGHT_CALIBRATION"));
        /* and others */
    }
}