ci(docs): add support for option flags

Author: lowlighter

source/app/metrics/metadata.mjs

@@ -106,7 +106,7 @@ metadata.plugin = async function({__plugins, name, logger}) {
         }
         //Inputs checks
         const result = Object.fromEntries(
-          Object.entries(inputs).map(([key, {type, format, default:defaulted, min, max, values}]) => [
+          Object.entries(inputs).map(([key, {type, format, default:defaulted, min, max, values, inherits}]) => [
             //Format key
             metadata.to.query(key, {name}),
             //Format value
@@ -269,25 +269,46 @@ metadata.plugin = async function({__plugins, name, logger}) {
       const demo = raw.match(/(?<demo><table>[\s\S]*?<[/]table>)/)?.groups?.demo?.replace(/<[/]?(?:table|tr)>/g, "")?.trim() ?? "<td></td>"
 
       //Options table
+      let flags = new Set()
       const table = [
         "| Option | Type *(format)* **[default]** *{allowed values}* | Description |",
         "| ------ | -------------------------------- | ----------- |",
         Object.entries(inputs).map(([option, {description, type, ...o}]) => {
           let row = []
           {
-            const cell = [`${"`"}${option}${"`"}`]
+            let cell = []
+            if (o.required)
+              cell.push("✔️"), flags.add("required")
             if (type === "token")
-              cell.push("🔐")
+              cell.push("🔐"), flags.add("secret")
+            if (o.inherits)
+              cell.push("⏩"), flags.add("inherits")
+            if (o.global)
+              cell.push("⏭️"), flags.add("global")
+            if (o.testing)
+              cell.push("🔧"), flags.add("testing")
             if (!Object.keys(previous?.inputs ?? {}).includes(option))
-              cell.push("✨")
+              cell.push("✨"), flags.add("beta")
+            if (o.extras)
+              cell.push("🧰"), flags.add("extras")
+            cell = cell.map(flag => `<sup>${flag}</sup>`)
+            cell.unshift(`${"`"}${option}${"`"}`)
             row.push(cell.join(" "))
           }
           {
             const cell = [`${"`"}${type}${"`"}`]
             if ("format" in o)
-              cell.push(`*(${o.format})*`)
-            if ("default" in o)
-              cell.push(`**[${o.default}]**`)
+              cell.push(`*(${Array.isArray(o.format) ? o.format[0] : o.format})*`)
+            if ("default" in o) {
+              let text = o.default
+              if (o.default === ".user.login")
+                text = "*→ User login*"
+              if (o.default === ".user.twitter")
+                text = "*→ User attached twitter*"
+              if (o.default === ".user.website")
+                text = "*→ User attached website*"
+              cell.push(`**[${text}]**`)
+            }
             if ("values" in o)
               cell.push(`*{${o.values.map(value => `"${value}"`).join(", ")}}*`)
             if ("min" in o)
@@ -302,9 +323,14 @@ metadata.plugin = async function({__plugins, name, logger}) {
           return `| ${row.join(" | ")} |`
         }).join("\n"),
         "\n",
-        "Legend for option icons:",
-        "* 🔐 Value should be stored in repository secrets",
-        "* ✨ New feature currently in testing on `master`/`main`"
+        flags.size ? "Legend for option icons:" : "",
+        flags.has("required") ? "* ✔️ Value must be provided" : "",
+        flags.has("secret") ? "* 🔐 Value should be stored in repository secrets" : "",
+        flags.has("inherits") ? "* ⏩ Value inherits from its related global-level option" : "",
+        flags.has("global") ? "* ⏭️ Value be inherited by its related plugin-level option" : "",
+        flags.has("testing") ? "* 🔧 For development purposes, use with caution" : "",
+        flags.has("beta") ? "* ✨ Currently in beta-testing on `master`/`main`" : "",
+        flags.has("extras") ? "* 🧰 Must be enabled in `settings.json` (for web instances)" : "",
       ].flat(Infinity).filter(s => s).join("\n")
 
       //Readme descriptor

source/plugins/activity/metadata.yml

@@ -88,8 +88,10 @@ inputs:
     format: comma-separated
     default: ""
     example: my-repo-1, my-repo-2, owner/repo-3, ...
+    inherits: repositories_skipped
 
   # Ignored actors (useful to ignore bots users)
   plugin_activity_ignored:
     description: Actors to ignore
-    default: github-actions[bot], dependabot[bot], dependabot-preview[bot]
+    default: ""
+    inherits: users_ignored

source/plugins/base/metadata.yml

@@ -29,7 +29,6 @@ inputs:
     default: 100
     min: 0
 
-
   # Number of repositories to load at once by queries
   # If you encounter GitHub queries timeouts, using a lower value here may solve issues
   repositories_batch:
@@ -66,6 +65,16 @@ inputs:
     format: comma-separated
     default: ""
     example: my-repo-1, my-repo-2, owner/repo-3, ...
+    global: yes
+
+  # List of default ignored users
+  # Plugins supporting a "skip users option" will automatically append users listed in this option
+  users_ignored:
+    description: Default users to ignore
+    type: array
+    format: comma-separated
+    default: github-actions[bot], dependabot[bot], dependabot-preview[bot]
+    global: yes
 
   # List of surnames or email addresses you use when authoring commits
   # These are mostly used to perform commits analysis to detect ownership
@@ -75,3 +84,4 @@ inputs:
     format: comma-seperated
     default: .user.login
     example: lowlighter, lowlighter@users.noreply.github.com
+    global: yes

source/plugins/code/metadata.yml

@@ -45,6 +45,7 @@ inputs:
     format: comma-separated
     default: ""
     example: my-repo-1, my-repo-2, owner/repo-3, ...
+    inherits: repositories_skipped
 
   # Restrict code snippet languages
   # These are guessed through linguist

source/plugins/contributors/metadata.yml

@@ -32,6 +32,7 @@ inputs:
     type: array
     format: comma-separated
     default: github-actions[bot], dependabot[bot], dependabot-preview[bot]
+    inherits: users_ignored
 
   # Display total contributions for each contributor
   plugin_contributors_contributions:
@@ -65,3 +66,4 @@ inputs:
         "💻 Code": ["source/**", "src/**"],
         "#️⃣ Others": ["*"]
       }
+    extras: yes

source/plugins/core/examples.yml

@@ -1,12 +1,12 @@
-- name: 📗 Classic template
+- name: Classic template
   uses: lowlighter/metrics@latest
   with:
     filename: metrics.classic.svg
     token: ${{ secrets.METRICS_TOKEN }}
     base: header, repositories
     plugin_lines: yes
 
-- name: 📘 Repository template
+- name: Repository template
   uses: lowlighter/metrics@latest
   with:
     template: repository
@@ -19,15 +19,15 @@
     plugin_projects: yes
     plugin_projects_repositories: lowlighter/metrics/projects/1
 
-- name: 📙 Terminal template
+- name: Terminal template
   uses: lowlighter/metrics@latest
   with:
     template: terminal
     filename: metrics.terminal.svg
     token: ${{ secrets.METRICS_TOKEN }}
     base: header, metadata
 
-- name: 📒 Markdown template
+- name: Markdown template
   uses: lowlighter/metrics@latest
   with:
     template: markdown
@@ -36,7 +36,7 @@
     config_output: markdown
     token: ${{ secrets.METRICS_TOKEN }}
 
-- name: 📒 Markdown template (with plugins)
+- name: Markdown template (with plugins)
   uses: lowlighter/metrics@latest
   with:
     template: markdown
@@ -66,7 +66,7 @@
     plugin_languages: yes
     token: ${{ secrets.METRICS_TOKEN }}
 
-- name: 📒 Markdown template (pdf output)
+- name: Markdown template (pdf output)
   uses: lowlighter/metrics@latest
   with:
     template: markdown
@@ -81,7 +81,7 @@
     config_padding: 5%
     token: ${{ secrets.METRICS_TOKEN }}
 
-- name: 📕 Community templates
+- name: Community templates
   uses: lowlighter/metrics@latest
   with:
     token: ${{ secrets.METRICS_TOKEN }}

source/plugins/core/metadata.yml

@@ -124,6 +124,7 @@ inputs:
       - comma-separated
       - /(?<user>[-a-z0-9]+)[/](?<repo>[-a-z0-9]+)@(?<branch>[-a-z0-9]+):(?<template>[-a-z0-9]+)/
     default: ""
+    extras: yes
 
   # Template to use
   # To use community template, prefix its name with "@"
@@ -150,13 +151,15 @@ inputs:
     description: Extra CSS
     type: string
     default: ""
+    extras: yes
 
   # Timezone used by metrics
   # See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
   config_timezone:
     description: Timezone used
     type: string
     default: ""
+    global: yes
 
   # Specify in which order metrics content will be displayed
   # If you omit some partials, they'll be appended at the end in default order
@@ -167,20 +170,23 @@ inputs:
     format: comma-separated
     default: ""
     example: base.header, base.repositories
+    global: yes
 
   # Use twemojis instead of emojis
   # May increase filesize but emojis will be rendered the same across all platforms
   config_twemoji:
     description: Use twemojis instead of emojis
     type: boolean
     default: no
+    global: yes
 
   # Render GitHub custom emojis (like ":octocat:", see full list at https://api.github.com/emojis)
   # May increase filesize
   config_gemoji:
     description: Use GitHub custom emojis
     type: boolean
     default: yes
+    global: yes
 
   # Render display width
   config_display:
@@ -191,19 +197,22 @@ inputs:
       - regular  # 480px width
       - large    # 960px width (may not be supported by all templates)
       - columns  # Full width with two columns on desktop / One column on mobile
+    global: yes
 
   # Enable SVG CSS animations
   config_animations:
     description: SVG CSS animations
     type: boolean
     default: yes
+    global: yes
 
   # Encode images links into base64 data
   # Advised to be true when generating images and false when generating texts or JSON
   config_base64:
     description: Encode images links into base64 data
     type: boolean
     default: yes
+    global: yes
 
   # Configure padding for output image (percentage value)
   # It can be used to add padding to generated metrics if rendering is cropped or has too much empty space
@@ -260,6 +269,23 @@ inputs:
     min: 0
     max: 3600
 
+  # Time to wait (in seconds) at the end of job
+  # Use this to avoid triggering abuse mechanics on large workflows
+  delay:
+    description: Use this to avoid triggering abuse mechanics on large workflows
+    type: number
+    default: 0
+    min: 0
+    max: 3600
+
+  # Use a pre-built image from GitHub registry when using unreleased versions of "lowlighter/metrics"
+  # This option has no effect on forks (images will always be rebuilt from Dockerfile)
+  # See https://github.com/users/lowlighter/packages/container/package/metrics for more information
+  use_prebuilt_image:
+    description: Use pre-built image from GitHub registry
+    type: boolean
+    default: yes
+
   # ====================================================================================
   # 🚧 Options below are mostly used for testing
 
@@ -269,19 +295,22 @@ inputs:
     description: Die on plugins errors
     type: boolean
     default: no
+    testing: yes
 
   # Debug mode
   # Note that this will automatically be enabled if job fails
   debug:
     description: Debug logs
     type: boolean
     default: no
+    testing: yes
 
   # Ensure SVG can be correctly parsed after generation
   verify:
     description: Verify SVG
     type: boolean
     default: no
+    testing: yes
 
   # Debug flags
   debug_flags:
@@ -294,13 +323,15 @@ inputs:
       - --hireable
       - --halloween
       - --error
+    testing: yes
 
   # Dry-run mode (perform generation without output)
   # Unlike "output_action" set to "none", output file won't be available in "/metrics_renders"
   dryrun:
     description: Enable dry-run
     type: boolean
     default: no
+    testing: yes
 
   # Experimental features
   # Note that no backward compatibility are guaranteed for these features
@@ -311,26 +342,11 @@ inputs:
     default: ""
     values:
       - --optimize-svg
+    testing: yes
 
   # Use mocked data to bypass external APIs
   use_mocked_data:
     description: Use mocked data instead of live APIs
     type: boolean
     default: no
-
-  # Use a pre-built image from GitHub registry when using unreleased versions of "lowlighter/metrics"
-  # This option has no effect on forks (images will always be rebuilt from Dockerfile)
-  # See https://github.com/users/lowlighter/packages/container/package/metrics for more information
-  use_prebuilt_image:
-    description: Use pre-built image from GitHub registry
-    type: boolean
-    default: yes
-
-  # Time to wait (in seconds) at the end of job
-  # Use this to avoid triggering abuse mechanics on large workflows
-  delay:
-    description: Use this to avoid triggering abuse mechanics on large workflows
-    type: number
-    default: 0
-    min: 0
-    max: 3600
+    testing: yes

source/plugins/followup/metadata.yml

@@ -29,4 +29,5 @@ inputs:
   plugin_followup_indepth:
     description: Indepth follow-up processing
     type: boolean
-    default: no
+    default: no
+    extras: yes

source/plugins/habits/metadata.yml

@@ -44,6 +44,7 @@ inputs:
     description: Display coding habits charts based on recent activity
     type: boolean
     default: no
+    extras: yes
 
   # Trim unused hours on daily chart
   plugin_habits_trim: