From 3e5c28ff4fb90ef22751df329d8bccbb27bcda38 Mon Sep 17 00:00:00 2001
From: Lucas Fernandes Nogueira <lucas@tauri.app>
Date: Thu, 1 Feb 2024 17:14:23 -0300
Subject: [PATCH] feat(tauri-plugin): generate permissions reference markdown
 file for plugin (#8729)

* feat(acl): generate reference markdown file

* lint

* generate plugin docs instead
---
 core/tauri-plugin/src/build/mod.rs            | 41 ++++++++++++++++++-
 .../permissions/autogenerated/reference.md    | 18 ++++++++
 .../plugins/tauri-plugin-example/Cargo.lock   |  1 +
 .../permissions/autogenerated/reference.md    | 22 ++++++++++
 4 files changed, 81 insertions(+), 1 deletion(-)
 create mode 100644 examples/api/src-tauri/tauri-plugin-sample/permissions/autogenerated/reference.md
 create mode 100644 examples/plugins/tauri-plugin-example/permissions/autogenerated/reference.md

diff --git a/core/tauri-plugin/src/build/mod.rs b/core/tauri-plugin/src/build/mod.rs
index bc65f7ce6..4b2435536 100644
--- a/core/tauri-plugin/src/build/mod.rs
+++ b/core/tauri-plugin/src/build/mod.rs
@@ -52,9 +52,11 @@ impl<'a> Builder<'a> {
     // requirement: links MUST be set and MUST match the name
     let _links = build_var("CARGO_MANIFEST_LINKS")?;
 
-    let autogenerated = Path::new("permissions/autogenerated/");
+    let autogenerated = Path::new("permissions/autogenerated");
     let commands_dir = &autogenerated.join("commands");
 
+    std::fs::create_dir_all(&autogenerated).expect("unable to create permissions dir");
+
     if !self.commands.is_empty() {
       acl::build::autogenerate_command_permissions(commands_dir, self.commands, "");
     }
@@ -62,6 +64,7 @@ impl<'a> Builder<'a> {
     let permissions = acl::build::define_permissions("./permissions/**/*.*", &name, &out_dir)?;
 
     acl::build::generate_schema(&permissions, "./permissions")?;
+    generate_docs(&permissions, &autogenerated)?;
 
     if let Some(global_scope_schema) = self.global_scope_schema {
       acl::build::define_global_scope_schema(global_scope_schema, &name, &out_dir)?;
@@ -74,6 +77,42 @@ impl<'a> Builder<'a> {
   }
 }
 
+fn generate_docs(permissions: &[acl::plugin::PermissionFile], out_dir: &Path) -> Result<(), Error> {
+  let mut docs = format!("# Permissions\n\n");
+
+  fn docs_from(id: &str, description: Option<&str>) -> String {
+    let mut docs = format!("## {id}");
+    if let Some(d) = description {
+      docs.push_str(&format!("\n\n{d}"));
+    }
+    docs
+  }
+
+  for permission in permissions {
+    for set in &permission.set {
+      docs.push_str(&docs_from(&set.identifier, Some(&set.description)));
+      docs.push_str("\n\n");
+    }
+
+    if let Some(default) = &permission.default {
+      docs.push_str(&docs_from("default", default.description.as_deref()));
+      docs.push_str("\n\n");
+    }
+
+    for permission in &permission.permission {
+      docs.push_str(&docs_from(
+        &permission.identifier,
+        permission.description.as_deref(),
+      ));
+      docs.push_str("\n\n");
+    }
+  }
+
+  std::fs::write(out_dir.join("reference.md"), docs).map_err(Error::WriteFile)?;
+
+  Ok(())
+}
+
 /// Grab an env var that is expected to be set inside of build scripts.
 fn build_var(key: &'static str) -> Result<String, Error> {
   std::env::var(key).map_err(|_| Error::BuildVar(key))
diff --git a/examples/api/src-tauri/tauri-plugin-sample/permissions/autogenerated/reference.md b/examples/api/src-tauri/tauri-plugin-sample/permissions/autogenerated/reference.md
new file mode 100644
index 000000000..d44f15c8b
--- /dev/null
+++ b/examples/api/src-tauri/tauri-plugin-sample/permissions/autogenerated/reference.md
@@ -0,0 +1,18 @@
+# Permissions
+
+## allow-ping
+
+Enables the ping command without any pre-configured scope.
+
+## deny-ping
+
+Denies the ping command without any pre-configured scope.
+
+## global-scope
+
+Sets a global scope.
+
+## allow-ping-scoped
+
+Enables the ping command with a test scope.
+
diff --git a/examples/plugins/tauri-plugin-example/Cargo.lock b/examples/plugins/tauri-plugin-example/Cargo.lock
index 5cbacf584..936c14e89 100644
--- a/examples/plugins/tauri-plugin-example/Cargo.lock
+++ b/examples/plugins/tauri-plugin-example/Cargo.lock
@@ -2120,6 +2120,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "45a28f4c49489add4ce10783f7911893516f15afe45d015608d41faca6bc4d29"
 dependencies = [
  "dyn-clone",
+ "indexmap 1.9.3",
  "schemars_derive",
  "serde",
  "serde_json",
diff --git a/examples/plugins/tauri-plugin-example/permissions/autogenerated/reference.md b/examples/plugins/tauri-plugin-example/permissions/autogenerated/reference.md
new file mode 100644
index 000000000..2c05c7d9d
--- /dev/null
+++ b/examples/plugins/tauri-plugin-example/permissions/autogenerated/reference.md
@@ -0,0 +1,22 @@
+# Permissions
+
+## deny-home-dir-config
+
+Denies read access to the complete $HOME folder.
+
+## allow-home-dir
+
+Allows read access to the complete $HOME folder.
+
+## allow-full-homefolder-access
+
+Allows read and write access to the complete $HOME folder.
+
+## deny-homefolder-config-access
+
+Denies access to the $HOME/.config folder.
+
+## default
+
+Default permissions granted
+