feat(publish): gate auto-publish on releases + publish summary table + docs

.github/scripts/build-publish-summary.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# Builds a markdown table summarizing the package versions produced by a
+# publish.yml run, from the per-job JSON result fragments it wrote.
+#
+# Usage: build-publish-summary.sh <results-dir>
+#
+# Each fragment in <results-dir> looks like:
+#   {
+#     "language": "cpp",
+#     "type": "src",
+#     "package": "codeql-cpp-queries",
+#     "previous_version": "0.2.1",
+#     "target_version": "0.2.2",
+#     "status": "published"   # published | up-to-date | failed
+#   }
+set -euo pipefail
+
+RESULTS_DIR="${1:?usage: build-publish-summary.sh <results-dir>}"
+REPO="${GITHUB_REPOSITORY:-GitHubSecurityLab/CodeQL-Community-Packs}"
+RUN_URL="${GITHUB_SERVER_URL:-https://github.com}/${REPO}/actions/runs/${GITHUB_RUN_ID:-}"
+
+shopt -s nullglob
+FRAGMENTS=("$RESULTS_DIR"/*.json)
+if [ "${#FRAGMENTS[@]}" -eq 0 ]; then
+  MERGED='[]'
+else
+  MERGED=$(jq -s '.' "${FRAGMENTS[@]}")
+fi
+
+LANGUAGES=(cpp csharp go java javascript python ruby)
+TYPES=(src lib ext ext-library-sources)
+EXT_LANGUAGES=(csharp java)
+
+lang_label() {
+  case "$1" in
+    cpp) echo "C++" ;;
+    csharp) echo "C#" ;;
+    go) echo "Go" ;;
+    java) echo "Java" ;;
+    javascript) echo "JavaScript" ;;
+    python) echo "Python" ;;
+    ruby) echo "Ruby" ;;
+    *) echo "$1" ;;
+  esac
+}
+
+is_ext_language() {
+  local lang="$1"
+  for l in "${EXT_LANGUAGES[@]}"; do
+    [ "$l" == "$lang" ] && return 0
+  done
+  return 1
+}
+
+cell() {
+  local lang="$1" type="$2"
+  local entry
+  entry=$(echo "$MERGED" | jq -c --arg l "$lang" --arg t "$type" \
+    '[.[] | select(.language == $l and .type == $t)] | first // empty')
+
+  if [ -z "$entry" ] || [ "$entry" == "null" ]; then
+    # This combo is expected to publish (unlike the "n/a" combos filtered out
+    # by the caller) but no result fragment was found for it.
+    echo "❓ no result"
+    return
+  fi
+
+  local package version status previous
+  package=$(echo "$entry" | jq -r '.package')
+  version=$(echo "$entry" | jq -r '.target_version')
+  status=$(echo "$entry" | jq -r '.status')
+  previous=$(echo "$entry" | jq -r '.previous_version')
+  local url="https://github.com/${REPO}/pkgs/container/${package}?tag=${version}"
+
+  case "$status" in
+    published)  echo "[${version}](${url}) 🆕" ;;
+    up-to-date) echo "[${version}](${url})" ;;
+    failed)     echo "⚠️ publish failed (still \`${previous}\`)" ;;
+    *)          echo "❓ unknown" ;;
+  esac
+}
+
+echo "## Publish summary"
+echo
+echo "_Generated by [publish.yml run #${GITHUB_RUN_NUMBER:-}](${RUN_URL}) — 🆕 marks a package republished by this run._"
+echo
+echo "| Language | Queries (\`src\`) | Library (\`lib\`) | Extensions (\`ext\`) | Library sources (\`ext-library-sources\`) |"
+echo "| --- | --- | --- | --- | --- |"
+for lang in "${LANGUAGES[@]}"; do
+  row="| $(lang_label "$lang") |"
+  for type in "${TYPES[@]}"; do
+    if { [ "$type" == "ext" ] || [ "$type" == "ext-library-sources" ]; } && ! is_ext_language "$lang"; then
+      row="$row n/a |"
+      continue
+    fi
+    row="$row $(cell "$lang" "$type") |"
+  done
+  echo "$row"
+done

.github/scripts/upsert-release-table.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Upserts the publish-summary table (built by build-publish-summary.sh) into
+# the GitHub Release matching .release.yml's current version, creating that
+# release as a pre-release if it doesn't exist yet.
+#
+# Usage: upsert-release-table.sh <table-markdown-file>
+#
+# The table is stored between marker comments so re-runs only replace that
+# block and leave the rest of the release body (e.g. "What's Changed") alone.
+set -euo pipefail
+
+TABLE_FILE="${1:?usage: upsert-release-table.sh <table-markdown-file>}"
+START_MARKER="<!-- publish-summary:start -->"
+END_MARKER="<!-- publish-summary:end -->"
+
+VERSION=$(grep -E '^version:' .release.yml | head -1 | sed -E 's/^version:[[:space:]]*"?([^"[:space:]]*)"?/\1/')
+if [ -z "$VERSION" ]; then
+  echo "::error::Could not read version from .release.yml" >&2
+  exit 1
+fi
+TAG="v${VERSION}"
+
+BLOCK_FILE=$(mktemp)
+{
+  echo "$START_MARKER"
+  cat "$TABLE_FILE"
+  echo "$END_MARKER"
+} > "$BLOCK_FILE"
+
+if gh release view "$TAG" >/dev/null 2>&1; then
+  echo "Release $TAG exists; refreshing its publish-summary block."
+  CURRENT_BODY=$(mktemp)
+  gh release view "$TAG" --json body -q .body > "$CURRENT_BODY"
+
+  NEW_BODY=$(mktemp)
+  if grep -qF "$START_MARKER" "$CURRENT_BODY"; then
+    awk -v start="$START_MARKER" -v end="$END_MARKER" -v blockfile="$BLOCK_FILE" '
+      $0 == start {
+        while ((getline line < blockfile) > 0) print line
+        skip = 1
+        next
+      }
+      $0 == end {
+        skip = 0
+        next
+      }
+      skip { next }
+      { print }
+    ' "$CURRENT_BODY" > "$NEW_BODY"
+  else
+    # Older release predating this automation: append the block once.
+    cat "$CURRENT_BODY" > "$NEW_BODY"
+    echo "" >> "$NEW_BODY"
+    cat "$BLOCK_FILE" >> "$NEW_BODY"
+  fi
+
+  gh release edit "$TAG" --notes-file "$NEW_BODY"
+else
+  echo "Release $TAG does not exist yet; creating it as a pre-release."
+  gh release create "$TAG" \
+    --title "$TAG" \
+    --notes-file "$BLOCK_FILE" \
+    --generate-notes \
+    --prerelease \
+    --target "${GITHUB_SHA:-main}"
+fi