feat: link typed template variables to their data type section

public/mergify-configuration-schema.json

@@ -606,7 +606,8 @@
             },
             {
               "description": "Why the pull request left the merge queue; empty outside queue contexts.",
-              "name": "queue_dequeue_reason"
+              "name": "queue_dequeue_reason",
+              "type": "queue-dequeue-reason"
             }
           ]
         }
@@ -800,7 +801,8 @@
                 },
                 {
                   "description": "Why the pull request left the merge queue; empty outside queue contexts.",
-                  "name": "queue_dequeue_reason"
+                  "name": "queue_dequeue_reason",
+                  "type": "queue-dequeue-reason"
                 }
               ]
             },
@@ -4754,7 +4756,8 @@
                 },
                 {
                   "description": "Why the pull request left the merge queue; empty outside queue contexts.",
-                  "name": "queue_dequeue_reason"
+                  "name": "queue_dequeue_reason",
+                  "type": "queue-dequeue-reason"
                 }
               ]
             },

src/components/Tables/TemplateVariablesTable.tsx

@@ -8,6 +8,16 @@ interface TemplateVariablesTableProps extends Def {
   field: string;
 }
 
+// A template variable whose value is drawn from an enumerated data type carries a
+// `type` token in the schema (`x-mergify-template-variables[].type`). Map that token
+// to the data type section listing the accepted values, mirroring how option value
+// types link to their data type (see ConfigOptions `valueTypeFormatLinks`). Keying
+// off the schema-published token means a new typed variable needs only its engine
+// annotation plus one entry here — no per-variable-name special-casing.
+const variableTypeLinks: Record<string, string> = {
+  'queue-dequeue-reason': '/configuration/data-types#queue-dequeue-reason',
+};
+
 export default function TemplateVariablesTable({ def, field }: TemplateVariablesTableProps) {
   const schema = configSchema as unknown as ConfigSchema;
   const definition = schema.$defs[def]?.properties?.[field];
@@ -31,14 +41,23 @@ export default function TemplateVariablesTable({ def, field }: TemplateVariables
           </tr>
         </thead>
         <tbody>
-          {variables.map((variable) => (
-            <tr key={variable.name}>
-              <td>
-                <code>{`{{ ${variable.name} }}`}</code>
-              </td>
-              <td dangerouslySetInnerHTML={{ __html: renderMarkdown(variable.description) }} />
-            </tr>
-          ))}
+          {variables.map((variable) => {
+            const typeLink = variable.type ? variableTypeLinks[variable.type] : undefined;
+            return (
+              <tr key={variable.name}>
+                <td>
+                  {typeLink !== undefined ? (
+                    <a style={{ textDecoration: 'underline' }} href={typeLink}>
+                      <code>{`{{ ${variable.name} }}`}</code>
+                    </a>
+                  ) : (
+                    <code>{`{{ ${variable.name} }}`}</code>
+                  )}
+                </td>
+                <td dangerouslySetInnerHTML={{ __html: renderMarkdown(variable.description) }} />
+              </tr>
+            );
+          })}
         </tbody>
       </table>
     </div>

src/util/templateVariables.test.ts

@@ -50,6 +50,29 @@ describe('extractTemplateVariables', () => {
     ]);
   });
 
+  it('carries the optional type token through for enumerated-value variables', () => {
+    const definition = {
+      type: 'string',
+      format: 'simple-template',
+      'x-mergify-template-variables': [
+        { name: 'author', description: 'PR author login' },
+        {
+          name: 'queue_dequeue_reason',
+          description: 'Why the PR left the queue',
+          type: 'queue-dequeue-reason',
+        },
+      ],
+    };
+    expect(extractTemplateVariables(definition)).toEqual([
+      { name: 'author', description: 'PR author login' },
+      {
+        name: 'queue_dequeue_reason',
+        description: 'Why the PR left the queue',
+        type: 'queue-dequeue-reason',
+      },
+    ]);
+  });
+
   it('returns [] when no template variables are present', () => {
     expect(extractTemplateVariables({ type: 'string' })).toEqual([]);
     expect(extractTemplateVariables(null)).toEqual([]);

src/util/templateVariables.ts

@@ -1,6 +1,11 @@
 export interface TemplateVariable {
   name: string;
   description: string;
+  // Some variables resolve to a value drawn from an enumerated data type rather than
+  // a free-form string. The schema tags those with a stable token (e.g.
+  // `queue-dequeue-reason`) that renderers map to the matching data type section.
+  // Absent for free-form string variables.
+  type?: string;
 }
 
 // Field definitions publish their allowlist under this custom JSON-schema key.