docs(plugins): clarification, fix typos and style

Author: lowlighter

.github/readme/partials/documentation/setup/web.md

@@ -84,7 +84,9 @@ Configuration file also contains settings about enabled templates, plugins and f
 }
 ```
 
-> ⚠️ Extras features **should not** be enabled on a public server, most of these are compute-intensive and some of some even allow remote code execution! Use with caution
+> ⚠️ Extras features **should not** be enabled on a public server, most of these are either compute, network or API intensive tasks. Some extras features even allow remote code execution which could compromise server security.
+>
+> Use at your own risk, *metrics* and its authors cannot be held responsible for any damage caused.
 
 ## 3️ Start docker container
 

.github/scripts/quickstart/plugin/metadata.yml

@@ -1,6 +1,7 @@
-name: "🧩 <%= `${name.charAt(0).toLocaleUpperCase()}${name.substring(1)}` %>"
+name: 🧩 <%= `${name.charAt(0).toLocaleUpperCase()}${name.substring(1)}` %>
 category: community
-description: Short description
+description: |
+  Short description
 examples:
   default: https://via.placeholder.com/468x60?text=No%20preview%20available
 authors:
@@ -13,6 +14,7 @@ scopes: []
 inputs:
 
   plugin_<%= name %>:
-    description: Enable <%= name %> plugin
+    description: |
+      Enable <%= name %> plugin
     type: boolean
     default: no

.github/scripts/quickstart/template/metadata.yml

@@ -1,6 +1,7 @@
-name: "🖼️ Template name"
+name: 🖼️ Template name
 extends: classic
-description: Short description
+description: |
+  Short description
 examples:
   default: https://via.placeholder.com/468x60?text=No%20preview%20available
 authors:

source/app/metrics/metadata.mjs

@@ -212,6 +212,38 @@ metadata.plugin = async function({__plugins, __templates, name, logger}) {
       Object.assign(meta.inputs, inputs, Object.fromEntries(Object.entries(inputs).map(([key, value]) => [metadata.to.query(key, {name}), value])))
     }
 
+    //Extra features parser
+    {
+      meta.extras = function(input, {extras = {}}) {
+        //Required permissions
+        const required = inputs[metadata.to.yaml(input, {name})]?.extras ?? null
+        if (!required)
+          return true
+        console.debug(`metrics/extras > ${name} > ${input} > require [${required}]`)
+
+        //Legacy handling
+        const enabled = extras?.features ?? extras?.default ?? false
+        if (typeof enabled === "boolean") {
+          console.debug(`metrics/extras > ${name} > ${input} > extras features is set to ${enabled}`)
+          return enabled
+        }
+        if (!Array.isArray(required)) {
+          console.debug(`metrics/extras > ${name} > ${input} > extras is not a permission array, skipping`)
+          return false
+        }
+
+        //Check permissions
+        if (!Array.isArray(extras.features))
+          throw new Error(`metrics/extras > ${name} > ${input} > extras.features is not an array`)
+        const missing = required.filter(permission => !extras.features.includes(permission))
+        if (missing.length > 0) {
+          console.debug(`metrics/extras > ${name} > ${input} > missing permissions [${missing}], skipping`)
+          return false
+        }
+        return true
+      }
+    }
+
     //Action metadata
     {
       //Extract comments
@@ -538,6 +570,12 @@ metadata.to = {
     key = key.replace(/^plugin_/, "").replace(/_/g, ".")
     return name ? key.replace(new RegExp(`^(${name}.)`, "g"), "") : key
   },
+  yaml(key, {name = ""} = {}) {
+    const parts = [key.replaceAll(".", "_")]
+    if (name)
+      parts.unshift((name === "base") ? name : `plugin_${name}`)
+    return parts.join("_")
+  }
 }
 
 //Demo for main and individual readmes

source/plugins/achievements/metadata.yml

@@ -1,6 +1,7 @@
-name: "🏆 Achievements"
+name: 🏆 Achievements
 category: github
-description: This plugin displays several highlights about what you achieved on GitHub.
+description: |
+  This plugin displays several highlights about what an account has achieved on GitHub.
 examples:
   +compact display: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.achievements.compact.svg
   detailed display: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.achievements.svg
@@ -13,13 +14,14 @@ scopes:
 inputs:
 
   plugin_achievements:
-    description: Enable achievements plugin
+    description: |
+      Enable achievements plugin
     type: boolean
     default: no
 
   plugin_achievements_threshold:
     description: |
-      Display rank threshold
+      Rank threshold filter
 
       Use `X` to display achievements not yet unlocked
     type: string
@@ -32,13 +34,15 @@ inputs:
       - X
 
   plugin_achievements_secrets:
-    description: Display secrets achievements
+    description: |
+      Secrets achievements
     type: boolean
     default: yes
 
   plugin_achievements_display:
     description: |
       Display style
+
       - `detailed`: display icon, name, description and ranking
       - `compact`: display icon, name and value
     type: string
@@ -48,28 +52,30 @@ inputs:
       - compact
 
   plugin_achievements_limit:
-    description: Display limit
+    description: |
+      Display limit
     type: number
     default: 0
     min: 0
+    zero: disable
 
   plugin_achievements_ignored:
     description: |
-      Hide specified achievements
+      Ignored achievements
 
-      Use names without the rank adjective (i.e. without "great", "super" or "master")
+      Use achievements names without their rank adjective (i.e. without "great", "super" or "master")
     type: array
     format: comma-separated
     default: ""
     example: octonaut, automator, explorer
 
   plugin_achievements_only:
     description: |
-      Restrict display to specified achievements
+      Showcased achievements
 
-      Use names without the rank adjective (i.e. without "great", "super" or "master")
+      Use achievements names without their rank adjective (i.e. without "great", "super" or "master")
 
-      This option is equivalent to `plugin_achievements_ignored` with all existing achievements but the ones listed in this option
+      This option is equivalent to [`plugin_achievements_ignored`](/source/plugins/achievements/README.md#plugin_achievements_ignored) with all existing achievements except the ones listed in this option
     type: array
     format: comma-separated
     default: ""

source/plugins/activity/metadata.yml

@@ -1,6 +1,7 @@
-name: "📰 Recent activity"
+name: 📰 Recent activity
 category: github
-description: This plugin displays your recent activity on GitHub.
+description: |
+  This plugin displays recent activity on GitHub.
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.activity.svg
 index: 13
@@ -13,26 +14,30 @@ scopes:
 inputs:
 
   plugin_activity:
-    description: Enable activity plugin
+    description: |
+      Enable activity plugin
     type: boolean
     default: no
 
   plugin_activity_limit:
-    description: Display limit
+    description: |
+      Display limit
     type: number
     default: 5
     min: 1
     max: 1000
 
   plugin_activity_load:
-    description: Events to load
+    description: |
+      Events to load
     type: number
     default: 300
     min: 100
     max: 1000
 
   plugin_activity_days:
-    description: Events maximum age
+    description: |
+      Events maximum age
     type: number
     default: 14
     min: 0
@@ -43,20 +48,22 @@ inputs:
     description: |
       Events visibility
 
-      Lets you hide private activity when using a `repo` scope token
+      Can be used to toggle private activity visibility when using a token with `repo` scope
     type: string
     default: all
     values:
       - public
       - all
 
   plugin_activity_timestamps:
-    description: Display events timestamps
+    description: |
+      Events timestamps
     type: boolean
     default: no
 
   plugin_activity_skipped:
-    description: Skipped repositories
+    description: |
+      Skipped repositories
     type: array
     format: comma-separated
     default: ""
@@ -67,7 +74,7 @@ inputs:
     description: |
       Ignored users
 
-      Useful to ignore bots activity
+      Can be used to ignore bots activity
     type: array
     format: comma-separated
     default: ""

source/plugins/anilist/metadata.yml

@@ -1,6 +1,7 @@
-name: "🌸 Anilist watch list and reading list"
+name: 🌸 Anilist watch list and reading list
 category: social
-description: This plugin displays your favorites animes, mangas and characters from your [AniList](https://anilist.co) account.
+description: |
+  This plugin displays favorites animes, mangas and characters from a [AniList](https://anilist.co) account.
 examples:
   +for anime watchers: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.anilist.svg
   for manga readers: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.anilist.manga.svg
@@ -13,12 +14,21 @@ scopes: []
 inputs:
 
   plugin_anilist:
-    description: Enable aniList plugin
+    description: |
+      Enable aniList plugin
     type: boolean
     default: no
 
+  plugin_anilist_user:
+    type: string
+    description: |
+      AniList login
+    default: .user.login
+    preset: no
+
   plugin_anilist_medias:
-    description: Display medias types
+    description: |
+      Medias types
     type: array
     format: comma-separated
     default: anime, manga
@@ -29,7 +39,8 @@ inputs:
   plugin_anilist_sections:
     description: |
       Displayed sections
-      - `favorites` will display favorites `plugin_anilist_medias`
+
+      - `favorites` will display favorites from `plugin_anilist_medias`
       - `watching` will display animes currently in watching list
       - `reading` will display manga currently in reading list
       - `characters` will display liked characters
@@ -44,26 +55,25 @@ inputs:
       - characters
 
   plugin_anilist_limit:
-    description: Display limit (medias)
+    description: |
+      Display limit (medias)
     type: number
     default: 2
     min: 0
     zero: disable
 
   plugin_anilist_limit_characters:
-    description: Display limit (characters)
+    description: |
+      Display limit (characters)
     type: number
     default: 22
     min: 0
     zero: disable
 
   plugin_anilist_shuffle:
-    description: Shuffle data for varied outputs
+    description: |
+      Shuffle data
+
+      Can be used to create varied outputs
     type: boolean
     default: yes
-
-  plugin_anilist_user:
-    type: string
-    description: AniList login
-    default: .user.login
-    preset: no