Add AUTOTITLE-like functionality for audit log reference links (#56232)

Author: heiskr

data/ui.yml

@@ -144,6 +144,7 @@ parameter_table:
 audit_logs:
   action: Action
   description: Description
+  reference: Reference
 graphql:
   reference:
     implements: <code>{{ GraphQLItemTitle }}</code> Implements

src/audit-logs/components/GroupedEvents.tsx

@@ -22,16 +22,40 @@ export default function GroupedEvents({ auditLogEvents, category }: Props) {
           <tr>
             <th scope="col">{t('action')}</th>
             <th scope="col">{t('description')}</th>
+            <th scope="col">{t('reference')}</th>
           </tr>
         </thead>
         <tbody>
           {auditLogEvents.map((event) => {
+            const renderReferenceLinks = () => {
+              if (!event.docs_reference_links || event.docs_reference_links === 'N/A') {
+                return null
+              }
+
+              const links = event.docs_reference_links
+                .split(/[,\s]+/)
+                .map((link) => link.trim())
+                .filter((link) => link && link !== 'N/A')
+
+              const titles = event.docs_reference_titles
+                ? event.docs_reference_titles.split(', ')
+                : links
+
+              return links.map((link, index) => (
+                <span key={link}>
+                  <a href={link}>{titles[index] || link}</a>
+                  {index < links.length - 1 && ', '}
+                </span>
+              ))
+            }
+
             return (
               <tr key={event.action}>
                 <td>
                   <code>{event.action}</code>
                 </td>
                 <td>{event.description}</td>
+                <td>{renderReferenceLinks()}</td>
               </tr>
             )
           })}

src/audit-logs/lib/index.ts

@@ -2,6 +2,7 @@ import path from 'path'
 
 import { readCompressedJsonFileFallback } from '@/frame/lib/read-json-file'
 import { getOpenApiVersion } from '@/versions/lib/all-versions'
+import findPage from '@/frame/lib/find-page'
 import type {
   AuditLogEventT,
   CategorizedEvents,
@@ -20,6 +21,61 @@ type PipelineConfig = {
   appendedDescriptions: Record<string, string>
 }
 
+type TitleResolutionContext = {
+  pages: Record<string, any>
+  redirects: Record<string, string>
+}
+
+// Resolves docs_reference_links URLs to page titles
+async function resolveReferenceLinksToTitles(
+  docsReferenceLinks: string,
+  context: TitleResolutionContext,
+): Promise<string> {
+  if (!docsReferenceLinks || docsReferenceLinks === 'N/A') {
+    return ''
+  }
+
+  // Handle multiple comma-separated or space-separated links
+  const links = docsReferenceLinks
+    .split(/[,\s]+/)
+    .map((link) => link.trim())
+    .filter((link) => link && link !== 'N/A')
+
+  const titles = []
+  for (const link of links) {
+    try {
+      const page = findPage(link, context.pages, context.redirects)
+      if (page) {
+        // Create a minimal context for rendering the title
+        const renderContext = {
+          currentLanguage: 'en',
+          currentVersion: 'free-pro-team@latest',
+          pages: context.pages,
+          redirects: context.redirects,
+        }
+        const title = await page.renderProp('title', renderContext, { textOnly: true })
+        titles.push(title)
+      } else {
+        // If we can't resolve the link, use the original URL
+        titles.push(link)
+      }
+    } catch (error) {
+      // If resolution fails, use the original URL
+      console.warn(
+        `Failed to resolve title for link: ${link}`,
+        error instanceof Error
+          ? error instanceof Error
+            ? error.message
+            : String(error)
+          : String(error),
+      )
+      titles.push(link)
+    }
+  }
+
+  return titles.join(', ')
+}
+
 // get audit log event data for the requested page and version
 //
 // returns an array of event objects that look like this:
@@ -87,17 +143,19 @@ export function getCategorizedAuditLogEvents(page: string, version: string) {
 }
 
 // Filters audit log events based on allowlist values.
-//
-// * eventsToCheck: events to consider
-// * allowListvalues: allowlist values to filter by
-// * currentEvents: events already collected
-// * pipelineConfig: audit log pipeline config data
-export function filterByAllowlistValues(
-  eventsToCheck: RawAuditLogEventT[],
-  allowListValues: string | string[],
-  currentEvents: AuditLogEventT[],
-  pipelineConfig: PipelineConfig,
-) {
+export async function filterByAllowlistValues({
+  eventsToCheck,
+  allowListValues,
+  currentEvents = [],
+  pipelineConfig,
+  titleContext,
+}: {
+  eventsToCheck: RawAuditLogEventT[]
+  allowListValues: string | string[]
+  currentEvents?: AuditLogEventT[]
+  pipelineConfig: PipelineConfig
+  titleContext?: TitleResolutionContext
+}) {
   if (!Array.isArray(allowListValues)) allowListValues = [allowListValues]
   if (!currentEvents) currentEvents = []
 
@@ -112,12 +170,27 @@ export function filterByAllowlistValues(
       if (seen.has(event.action)) continue
       seen.add(event.action)
 
-      const minimal = {
+      const minimal: AuditLogEventT = {
         action: event.action,
         description: processAndGetEventDescription(event, eventAllowlists, pipelineConfig),
         docs_reference_links: event.docs_reference_links,
       }
 
+      // Resolve reference link titles if context is provided
+      if (titleContext && event.docs_reference_links && event.docs_reference_links !== 'N/A') {
+        try {
+          minimal.docs_reference_titles = await resolveReferenceLinksToTitles(
+            event.docs_reference_links,
+            titleContext,
+          )
+        } catch (error) {
+          console.warn(
+            `Failed to resolve titles for event ${event.action}:`,
+            error instanceof Error ? error.message : String(error),
+          )
+        }
+      }
+
       minimalEvents.push(minimal)
     }
   }
@@ -132,6 +205,7 @@ export function filterByAllowlistValues(
 // * currentEvents: events already collected
 // * pipelineConfig: audit log pipeline config data
 // * auditLogPage: the audit log page the event belongs to
+// * titleContext: optional context for resolving reference link titles
 //
 // Mutates `currentGhesEvents` and updates it with any new filtered for audit
 // log events, the object maps GHES versions to page events for that version e.g.:
@@ -148,13 +222,21 @@ export function filterByAllowlistValues(
 //     user: [...],
 //   },
 // }
-export function filterAndUpdateGhesDataByAllowlistValues(
-  eventsToCheck: RawAuditLogEventT[],
-  allowListValue: string,
-  currentGhesEvents: VersionedAuditLogData,
-  pipelineConfig: PipelineConfig,
-  auditLogPage: string,
-) {
+export async function filterAndUpdateGhesDataByAllowlistValues({
+  eventsToCheck,
+  allowListValue,
+  currentGhesEvents,
+  pipelineConfig,
+  auditLogPage,
+  titleContext,
+}: {
+  eventsToCheck: RawAuditLogEventT[]
+  allowListValue: string
+  currentGhesEvents: VersionedAuditLogData
+  pipelineConfig: PipelineConfig
+  auditLogPage: string
+  titleContext?: TitleResolutionContext
+}) {
   if (!currentGhesEvents) currentGhesEvents = {}
 
   const seenByGhesVersion = new Map()
@@ -173,12 +255,27 @@ export function filterAndUpdateGhesDataByAllowlistValues(
       if (seenByGhesVersion.get(fullGhesVersion)?.has(event.action)) continue
 
       if (ghesVersionAllowlists.includes(allowListValue)) {
-        const minimal = {
+        const minimal: AuditLogEventT = {
           action: event.action,
           description: processAndGetEventDescription(event, ghesVersionAllowlists, pipelineConfig),
           docs_reference_links: event.docs_reference_links,
         }
 
+        // Resolve reference link titles if context is provided
+        if (titleContext && event.docs_reference_links && event.docs_reference_links !== 'N/A') {
+          try {
+            minimal.docs_reference_titles = await resolveReferenceLinksToTitles(
+              event.docs_reference_links,
+              titleContext,
+            )
+          } catch (error) {
+            console.warn(
+              `Failed to resolve titles for event ${event.action}:`,
+              error instanceof Error ? error.message : String(error),
+            )
+          }
+        }
+
         // we need to initialize as we go to build up the `minimalEvents`
         // object that we'll return which will contain the GHES events for
         // each versions + page type combos e.g. when processing GHES events

src/audit-logs/scripts/sync.ts

@@ -15,6 +15,8 @@ import path from 'path'
 import { filterByAllowlistValues, filterAndUpdateGhesDataByAllowlistValues } from '../lib/index'
 import { getContents, getCommitSha } from '@/workflows/git-utils'
 import { latest, latestStable, releaseCandidate } from '@/versions/lib/enterprise-server-releases'
+import { loadPages, loadPageMap } from '@/frame/lib/page-data'
+import loadRedirects from '@/redirects/lib/precompile'
 import type { AuditLogEventT, VersionedAuditLogData } from '../types'
 
 if (!process.env.GITHUB_TOKEN) {
@@ -53,6 +55,13 @@ async function main() {
   pipelineConfig.sha = mainSha
   await writeFile(configFilepath, JSON.stringify(pipelineConfig, null, 2))
 
+  // Load pages and redirects for title resolution
+  console.log('Loading pages and redirects for title resolution...')
+  const pageList = await loadPages(undefined, ['en'])
+  const pages = await loadPageMap(pageList)
+  const redirects = await loadRedirects(pageList)
+  const titleContext = { pages, redirects }
+
   // store an array of audit log event data keyed by version and audit log page,
   // will look like this (depends on supported GHES versions):
   //
@@ -75,32 +84,39 @@ async function main() {
   // Wrapper around filterByAllowlistValues() because we always need all the
   // schema events and pipeline config data.
   const filter = (allowListValues: string | string[], currentEvents: AuditLogEventT[] = []) =>
-    filterByAllowlistValues(schemaEvents, allowListValues, currentEvents, pipelineConfig)
+    filterByAllowlistValues({
+      eventsToCheck: schemaEvents,
+      allowListValues,
+      currentEvents,
+      pipelineConfig,
+      titleContext,
+    })
   // Wrapper around filterGhesByAllowlistValues() because we always need all the
   // schema events and pipeline config data.
   const filterAndUpdateGhes = (
-    allowListValues: string,
+    allowListValue: string,
     auditLogPage: string,
-    currentEvents: VersionedAuditLogData,
+    currentGhesEvents: VersionedAuditLogData,
   ) =>
-    filterAndUpdateGhesDataByAllowlistValues(
-      schemaEvents,
-      allowListValues,
-      currentEvents,
+    filterAndUpdateGhesDataByAllowlistValues({
+      eventsToCheck: schemaEvents,
+      allowListValue,
+      currentGhesEvents,
       pipelineConfig,
       auditLogPage,
-    )
+      titleContext,
+    })
 
   auditLogData.fpt = {}
-  auditLogData.fpt.user = filter('user')
-  auditLogData.fpt.organization = filter(['organization', 'org_api_only'])
+  auditLogData.fpt.user = await filter('user')
+  auditLogData.fpt.organization = await filter(['organization', 'org_api_only'])
 
   auditLogData.ghec = {}
-  auditLogData.ghec.user = filter('user')
-  auditLogData.ghec.organization = filter('organization')
-  auditLogData.ghec.organization = filter('org_api_only', auditLogData.ghec.organization)
-  auditLogData.ghec.enterprise = filter('business')
-  auditLogData.ghec.enterprise = filter('business_api_only', auditLogData.ghec.enterprise)
+  auditLogData.ghec.user = await filter('user')
+  auditLogData.ghec.organization = await filter('organization')
+  auditLogData.ghec.organization = await filter('org_api_only', auditLogData.ghec.organization)
+  auditLogData.ghec.enterprise = await filter('business')
+  auditLogData.ghec.enterprise = await filter('business_api_only', auditLogData.ghec.enterprise)
 
   // GHES versions are numbered (i.e. "3.9", "3.10", etc.) and filterGhes()
   // gives us back an object of GHES versions to page events for each version
@@ -114,11 +130,15 @@ async function main() {
   // so there's no single auditLogData.ghes like the other versions.
   const ghesVersionsAuditLogData = {}
 
-  filterAndUpdateGhes('business', AUDIT_LOG_PAGES.ENTERPRISE, ghesVersionsAuditLogData)
-  filterAndUpdateGhes('business_api_only', AUDIT_LOG_PAGES.ENTERPRISE, ghesVersionsAuditLogData)
-  filterAndUpdateGhes('user', AUDIT_LOG_PAGES.USER, ghesVersionsAuditLogData)
-  filterAndUpdateGhes('organization', AUDIT_LOG_PAGES.ORGANIZATION, ghesVersionsAuditLogData)
-  filterAndUpdateGhes('org_api_only', AUDIT_LOG_PAGES.ORGANIZATION, ghesVersionsAuditLogData)
+  await filterAndUpdateGhes('business', AUDIT_LOG_PAGES.ENTERPRISE, ghesVersionsAuditLogData)
+  await filterAndUpdateGhes(
+    'business_api_only',
+    AUDIT_LOG_PAGES.ENTERPRISE,
+    ghesVersionsAuditLogData,
+  )
+  await filterAndUpdateGhes('user', AUDIT_LOG_PAGES.USER, ghesVersionsAuditLogData)
+  await filterAndUpdateGhes('organization', AUDIT_LOG_PAGES.ORGANIZATION, ghesVersionsAuditLogData)
+  await filterAndUpdateGhes('org_api_only', AUDIT_LOG_PAGES.ORGANIZATION, ghesVersionsAuditLogData)
   Object.assign(auditLogData, ghesVersionsAuditLogData)
 
   // We don't maintain the order of events as we process them so after filtering