maintainers-list.nix: Document (current) invitation process, add get-maintainer.sh (#267084)

* maintainer-list: Document automatic invites to @NixOS/nixpkgs-maintainers

* maintainers/scripts: Add `get-maintainer.sh`

Supports querying `maintainers-list.nix` by Nix attribute,
email address, github name or id, matrix account, or name.

* maintainers/scripts/get-maintainer.sh: More verbose help message

* maintainers/scripts/get-maintainer.sh: Fix (some) `shellcheck` lints

* maintainers/scripts: Add README

* maintainers/scripts/get-maintainer.sh: Put inline documentation at the top of the file

* maintainers/scripts: Document this is not a stable interfact to nixpkgs

Co-authored-by: Silvan Mosberger <github@infinisil.com>

* scripts/README: Add example for `get-maintainer.sh`

---------

Co-authored-by: Silvan Mosberger <github@infinisil.com>

4 files changed, 142 insertions, 2 deletions

diff --git a/maintainers/README.md b/maintainers/README.md
index 5bb9c58db024..f121ec756413 100644
--- a/maintainers/README.md
+++ b/maintainers/README.md
@@ -165,3 +165,10 @@ team after giving the existing members a few days to respond.
 
 *Important:* If a team says it is a closed group, do not merge additions
 to the team without an approval by at least one existing member.
+
+
+# Maintainer scripts
+
+Various utility scripts, which are mainly useful for nixpkgs maintainers,
+are available under `./scripts/`.  See its [README](./scripts/README.md)
+for further information.
diff --git a/maintainers/maintainer-list.nix b/maintainers/maintainer-list.nix
index c5ff33f5dd17..542e58ff33ce 100644
--- a/maintainers/maintainer-list.nix
+++ b/maintainers/maintainer-list.nix
@@ -26,8 +26,10 @@
     - `githubId` is your GitHub user ID, which can be found at `https://api.github.com/users/<userhandle>`,
     - `keys` is a list of your PGP/GPG key fingerprints.
 
-    Specifying a GitHub account ensures that you automatically get a review request on
-    pull requests that modify a package for which you are a maintainer.
+    Specifying a GitHub account ensures that you automatically:
+    - get invited to the @NixOS/nixpkgs-maintainers team ;
+    - once you are part of the @NixOS org, OfBorg will request you review
+      pull requests that modify a package for which you are a maintainer.
 
     `handle == github` is strongly preferred whenever `github` is an acceptable attribute name and is short and convenient.
 
diff --git a/maintainers/scripts/README.md b/maintainers/scripts/README.md
new file mode 100644
index 000000000000..2b99a4e75114
--- /dev/null
+++ b/maintainers/scripts/README.md
@@ -0,0 +1,58 @@
+# Maintainer scripts
+
+This folder contains various executable scripts for nixpkgs maintainers,
+and supporting data or nixlang files as needed.
+These scripts generally aren't a stable interface and may changed or be removed.
+
+What follows is a (very incomplete) overview of available scripts.
+
+
+## Metadata
+
+### `get-maintainer.sh`
+
+`get-maintainer.sh [selector] value` returns a JSON object describing
+a given nixpkgs maintainer, equivalent to `lib.maintainers.${x} // { handle = x; }`.
+
+This allows looking up a maintainer's attrset (including GitHub and Matrix
+handles, email address etc.) based on any of their handles, more correctly and
+robustly than text search through `maintainers-list.nix`.
+
+```
+❯ ./get-maintainer.sh nicoo
+{
+  "email": "nicoo@debian.org",
+  "github": "nbraud",
+  "githubId": 1155801,
+  "keys": [
+    {
+      "fingerprint": "E44E 9EA5 4B8E 256A FB73 49D3 EC9D 3708 72BC 7A8C"
+    }
+  ],
+  "name": "nicoo",
+  "handle": "nicoo"
+}
+
+❯ ./get-maintainer.sh name 'Silvan Mosberger'
+{
+  "email": "contact@infinisil.com",
+  "github": "infinisil",
+  "githubId": 20525370,
+  "keys": [
+    {
+      "fingerprint": "6C2B 55D4 4E04 8266 6B7D  DA1A 422E 9EDA E015 7170"
+    }
+  ],
+  "matrix": "@infinisil:matrix.org",
+  "name": "Silvan Mosberger",
+  "handle": "infinisil"
+}
+```
+
+The maintainer is designated by a `selector` which must be one of:
+- `handle` (default): the maintainer's attribute name in `lib.maintainers`;
+- `email`, `name`, `github`, `githubId`, `matrix`, `name`:
+  attributes of the maintainer's object, matched exactly;
+  see [`maintainer-list.nix`] for the fields' definition.
+
+[`maintainer-list.nix`]: ../maintainer-list.nix
diff --git a/maintainers/scripts/get-maintainer.sh b/maintainers/scripts/get-maintainer.sh
new file mode 100755
index 000000000000..3061d2ccc72f
--- /dev/null
+++ b/maintainers/scripts/get-maintainer.sh
@@ -0,0 +1,73 @@
+#!/usr/bin/env nix-shell
+#!nix-shell -i bash -p jq ncurses
+# shellcheck shell=bash
+
+# Get a nixpkgs maintainer's metadata as a JSON object
+#  see HELP_MESSAGE just below, or README.md.
+
+set -euo pipefail
+
+declare -A SELECTORS=( [handle]= [email]= [github]= [githubId]= [matrix]= [name]= )
+HELP_MESSAGE="usage: '$0' [selector] value
+examples:
+  get-maintainer.sh nicoo
+  get-maintainer.sh githubId 1155801
+
+\`selector\` defaults to 'handle', can be one of:
+  ${!SELECTORS[*]}
+"
+
+MAINTAINERS_DIR="$(dirname "$0")/.."
+
+die() {
+  tput setaf 1 # red
+  echo "'$0': $*"
+  tput setaf 0 # back to black
+  exit 1
+}
+
+listAsJSON() {
+  nix-instantiate --eval --strict --json "${MAINTAINERS_DIR}/maintainer-list.nix"
+}
+
+parseArgs() {
+  [ $# -gt 0 -a $# -lt 3 ] || {
+      echo "$HELP_MESSAGE"
+      die "invalid number of arguments (must be 1 or 2)"
+  }
+
+  if [ $# -eq 1 ]; then
+    selector=handle
+  else
+    selector="$1"
+    shift
+  fi
+  [ -z "${SELECTORS[$selector]-n}" ] || {
+    echo "Valid selectors are:" "${!SELECTORS[@]}" >&2
+    die "invalid selector '$selector'"
+  }
+
+  value="$1"
+  shift
+}
+
+query() {
+  # explode { a: A, b: B, ... } into A + {handle: a}, B + {handle: b}, ...
+  local explode="to_entries[] | .value + { \"handle\": .key }"
+
+  # select matching items from the list
+  # TODO(nicoo): Support approximate matching for `name` ?
+  local select
+  case "$selector" in
+    githubId)
+      select="select(.${selector} == $value)"
+      ;;
+    *)
+      select="select(.${selector} == \"$value\")"
+  esac
+
+  echo "$explode | $select"
+}
+
+parseArgs "$@"
+listAsJSON | jq -e "$(query)"