[TT-17973] Render the public retired-versions table from the plan

The pkgs retirement subcommand turns the committed retention plan into
the retired-versions snippet published on tyk.io, and the retention
plan workflow PRs it to tyk-docs whenever the table changes. Rendering
from the plan rather than recomputing guarantees the published table
matches what pruning will enforce.

The hand-written first draft of the table proved the point: it said
5.8.x where the derived cutoff is actually 5.5.x, because the EE
window keeps three released series below the previous LTS.

Author: olamilekan000

.github/workflows/retention-plan.yml

@@ -37,8 +37,9 @@ jobs:
           app-id: ${{ secrets.PROBE_APP_ID }}
           private-key: ${{ secrets.PROBE_APP_PRIVATE_KEY }}
           owner: TykTechnologies
-          repositories: artifact-retention-plans
+          repositories: artifact-retention-plans,tyk-docs
           permission-contents: write
+          permission-pull-requests: write
 
       - name: Checkout gromit
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -131,6 +132,32 @@ jobs:
             echo "Nothing was deleted by this workflow."
           } >> "$GITHUB_STEP_SUMMARY"
 
+      # No PR is opened when the table is unchanged
+      - name: Checkout tyk-docs
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          repository: TykTechnologies/tyk-docs
+          token: ${{ steps.app-token.outputs.token }}
+          path: tyk-docs
+          persist-credentials: false
+
+      - name: Render retired-versions snippet
+        run: go run . pkgs retirement --plan plan.json > tyk-docs/snippets/retired-versions.mdx
+
+      - name: PR the snippet to tyk-docs
+        uses: peter-evans/create-pull-request@5e914681df9dc83aa4e4905692ca88beb2f9e91f # v7.0.5
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          path: tyk-docs
+          branch: gromit/retired-versions
+          delete-branch: true
+          commit-message: 'Update retired versions table'
+          title: 'Update retired versions table'
+          body: |
+            Regenerated from the latest [retention plan](https://github.com/TykTechnologies/artifact-retention-plans/commit/${{ steps.commit.outputs.sha }}) by [this run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}).
+
+            The table in `snippets/retired-versions.mdx` reflects the retention cutoffs the pruning run will enforce.
+
       - name: Slack notice
         if: steps.diff.outputs.new_count != '0'
         uses: slackapi/slack-github-action@af78098f536edbc4de71162a307590698245be95 # v3.0.1

cmd/pkgs.go

@@ -39,6 +39,10 @@ var pkgsCmd = &cobra.Command{
 
 You can perform maintenance using this command tree.`,
 	PersistentPreRun: func(cmd *cobra.Command, args []string) {
+		// retirement works offline, from a plan file
+		if cmd.Name() == "retirement" {
+			return
+		}
 		pcToken := os.Getenv("PACKAGECLOUD_TOKEN")
 		if pcToken == "" {
 			log.Fatal().Msg("Working with packagecloud.io requires PACKAGECLOUD_TOKEN")
@@ -215,10 +219,35 @@ plan must not proceed to deletion.`,
 	},
 }
 
+var retirementSubCmd = &cobra.Command{
+	Use:   "retirement",
+	Short: "Render the public retired-versions table from a plan",
+	Long: `Reads a plan (the JSON from 'pkgs plan --json') and emits the
+retired-versions snippet published on the tyk.io retention policy
+page. Only track-driven repos appear in the table.
+
+Rendering from the committed plan rather than recomputing keeps the
+published table identical to what the pruning run will enforce.`,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		planFile, _ := cmd.Flags().GetString("plan")
+		data, err := os.ReadFile(planFile)
+		if err != nil {
+			return err
+		}
+		var plans []pkgs.Plan
+		if err := json.Unmarshal(data, &plans); err != nil {
+			return fmt.Errorf("parsing %s: %w", planFile, err)
+		}
+		fmt.Fprint(cmd.OutOrStdout(), pkgs.RenderRetiredVersions(plans))
+		return nil
+	},
+}
+
 func init() {
 	pkgsCmd.AddCommand(cleanSubCmd)
 	pkgsCmd.AddCommand(planSubCmd)
 	pkgsCmd.AddCommand(mirrorSubCmd)
+	pkgsCmd.AddCommand(retirementSubCmd)
 	rootCmd.AddCommand(pkgsCmd)
 
 	pkgsCmd.PersistentFlags().String("owner", "tyk", "PackageCloud repo owner")
@@ -238,4 +267,7 @@ func init() {
 	mirrorSubCmd.Flags().String("bucket", "tyk-artifact-archive", "S3 bucket to archive to")
 	mirrorSubCmd.Flags().Bool("verify", false, "Read every archived object back and check its hash")
 	mirrorSubCmd.Flags().Int("concurrency", 3, "Repos to mirror in parallel")
+
+	retirementSubCmd.Flags().String("plan", "", "Plan file from 'pkgs plan --json'")
+	retirementSubCmd.MarkFlagRequired("plan")
 }

pkgs/retire.go

@@ -0,0 +1,59 @@
+package pkgs
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"golang.org/x/mod/semver"
+)
+
+var productNames = map[string]string{
+	"tyk-gateway":   "Tyk Gateway",
+	"tyk-dashboard": "Tyk Dashboard",
+	"tyk-pump":      "Tyk Pump",
+	"tyk-mdcb":      "Tyk MDCB",
+}
+
+// ProductName returns the display name for a repo
+func ProductName(repo string) string {
+	if name, found := productNames[repo]; found {
+		return name
+	}
+	words := strings.Split(repo, "-")
+	for i, w := range words {
+		if w == "" {
+			continue
+		}
+		words[i] = strings.ToUpper(w[:1]) + w[1:]
+	}
+	return strings.Join(words, " ")
+}
+
+// RenderRetiredVersions renders the tyk-docs retirement table from a
+// plan. Only track-driven repos appear, so the published table cannot
+// disagree with what pruning will do.
+func RenderRetiredVersions(plans []Plan) string {
+	var b strings.Builder
+	b.WriteString(`{/* This table is generated by gromit from the release tracks
+    configuration. Do not edit it by hand: changes will be
+    overwritten by the next sync. */}
+
+| Product | Retained from | Retired below |
+|---------|---------------|---------------|
+`)
+	rows := make([]string, 0, len(plans))
+	for _, p := range plans {
+		if p.Track == "" || p.Cutoff == "" {
+			continue
+		}
+		series := strings.TrimPrefix(semver.MajorMinor(p.Cutoff), "v")
+		oldest := strings.TrimPrefix(semver.Canonical(p.Cutoff), "v")
+		rows = append(rows, fmt.Sprintf("| %s | %s.x | %s |\n", ProductName(p.Repo), series, oldest))
+	}
+	sort.Strings(rows)
+	for _, r := range rows {
+		b.WriteString(r)
+	}
+	return b.String()
+}

pkgs/retire_test.go

@@ -0,0 +1,33 @@
+package pkgs
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestRenderRetiredVersions(t *testing.T) {
+	plans := []Plan{
+		{Repo: "tyk-gateway", Track: "gateway", Cutoff: "v5.5"},
+		{Repo: "tyk-dashboard", Track: "gateway", Cutoff: "v5.5"},
+		// not track-driven, must not appear
+		{Repo: "tyk-pump", Cutoff: "v1.0.0"},
+		{Repo: "tyk-identity-broker"},
+	}
+	want := `{/* This table is generated by gromit from the release tracks
+    configuration. Do not edit it by hand: changes will be
+    overwritten by the next sync. */}
+
+| Product | Retained from | Retired below |
+|---------|---------------|---------------|
+| Tyk Dashboard | 5.5.x | 5.5.0 |
+| Tyk Gateway | 5.5.x | 5.5.0 |
+`
+	assert.Equal(t, want, RenderRetiredVersions(plans))
+}
+
+func TestProductName(t *testing.T) {
+	assert.Equal(t, "Tyk Gateway", ProductName("tyk-gateway"))
+	assert.Equal(t, "Tyk MDCB", ProductName("tyk-mdcb"))
+	assert.Equal(t, "Tyk Sync", ProductName("tyk-sync"))
+}