From b59c10317867b4bfff23a753b130324de5263928 Mon Sep 17 00:00:00 2001
From: JakeSCahill <jake@redpanda.com>
Date: Sun, 2 Aug 2026 07:54:27 +0100
Subject: [PATCH] ci: detect page-set changes when flagging adp-docs follow-ups

The structural-change detection only parsed the diff summary for
New/Removed/Deprecated command rows, which keys on the command tree.
The rpk ai connection pages appeared with zero tree changes: the
commands existed in the 0.2.31 tree as stubs, and removing their
overrides excludes is what created the pages. The flag step therefore
skipped on the first production run even though three pages were new
(micheleRP's finding after the first end-to-end run).

The detection now also treats any added, deleted, or renamed page or
partial under the plugin's directories as structural, keeping the
summary grep for tree-level renames. Pure content modifications stay
non-structural.
---
 .github/workflows/update-rpk-plugin-docs.yml | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/update-rpk-plugin-docs.yml b/.github/workflows/update-rpk-plugin-docs.yml
index e843dc603a..c8044e7794 100644
--- a/.github/workflows/update-rpk-plugin-docs.yml
+++ b/.github/workflows/update-rpk-plugin-docs.yml
@@ -209,10 +209,23 @@ jobs:
             git diff --staged --name-only | head -20
           fi
 
-          # Structural changes (commands added/removed/deprecated) matter for
-          # downstream consumers with static stubs (adp-docs for rpk ai)
-          if grep -qE '\| (New|Removed|Deprecated) commands +\|' "${{ runner.temp }}/pr-summary.md" 2>/dev/null; then
+          # Structural changes matter for downstream consumers with static
+          # stubs (adp-docs for rpk ai). Two independent signals, because the
+          # command tree and the page set can change independently: the rpk ai
+          # connection pages appeared with ZERO tree changes (the commands
+          # existed as stubs in 0.2.31; removing their overrides excludes is
+          # what created the pages), so the summary-table grep alone missed
+          # it. Any added, deleted, or renamed page/partial for this plugin is
+          # structural; pure content modifications are not.
+          PLUGIN="${{ steps.params.outputs.plugin }}"
+          PAGESET_CHANGE=$(git diff --staged --name-status -- \
+            "modules/reference/partials/rpk-${PLUGIN}" \
+            "modules/reference/pages/rpk/rpk-${PLUGIN}" \
+            | grep -cE '^[ADR]' || true)
+          if [ "$PAGESET_CHANGE" -gt 0 ] || \
+             grep -qE '\| (New|Removed|Deprecated) commands +\|' "${{ runner.temp }}/pr-summary.md" 2>/dev/null; then
             echo "structural=true" >> $GITHUB_OUTPUT
+            [ "$PAGESET_CHANGE" -gt 0 ] && echo "Page-set change detected: $PAGESET_CHANGE added/deleted/renamed page(s)"
           else
             echo "structural=false" >> $GITHUB_OUTPUT
           fi