add content-linter rule to validate that introLinks keys exist in ui.yml (#58137)

Author: Ebonsignori

src/content-linter/lib/linting-rules/frontmatter-intro-links.ts

@@ -0,0 +1,67 @@
+// @ts-ignore - markdownlint-rule-helpers doesn't have TypeScript declarations
+import { addError } from 'markdownlint-rule-helpers'
+
+import { getFrontmatter } from '../helpers/utils'
+import { getUIDataMerged } from '@/data-directory/lib/get-data'
+import type { RuleParams, RuleErrorCallback, Rule } from '@/content-linter/types'
+
+interface Frontmatter {
+  introLinks?: Record<string, string>
+  [key: string]: any
+}
+
+// Get the valid introLinks keys from ui.yml
+function getValidIntroLinksKeys(): string[] {
+  try {
+    const ui = getUIDataMerged('en')
+
+    if (!ui || !ui.product_landing || typeof ui.product_landing !== 'object') {
+      return []
+    }
+
+    // Get all keys from product_landing in ui.yml
+    return Object.keys(ui.product_landing)
+  } catch (error) {
+    console.error('Error loading ui.yml data:', error)
+    return []
+  }
+}
+
+export const frontmatterIntroLinks: Rule = {
+  names: ['GHD062', 'frontmatter-intro-links'],
+  description: 'introLinks keys must be valid keys defined in data/ui.yml under product_landing',
+  tags: ['frontmatter', 'single-source'],
+  function: (params: RuleParams, onError: RuleErrorCallback) => {
+    const fm = getFrontmatter(params.lines) as Frontmatter | null
+    if (!fm || !fm.introLinks) return
+
+    const introLinks = fm.introLinks
+    if (typeof introLinks !== 'object' || Array.isArray(introLinks)) return
+
+    const validKeys = getValidIntroLinksKeys()
+    if (validKeys.length === 0) {
+      // If we can't load the valid keys, skip validation
+      return
+    }
+
+    // Check each key in introLinks
+    for (const key of Object.keys(introLinks)) {
+      if (!validKeys.includes(key)) {
+        // Find the line with this key
+        const line = params.lines.find((line: string) => {
+          const trimmed = line.trim()
+          return trimmed.startsWith(`${key}:`) && !trimmed.startsWith('introLinks:')
+        })
+        const lineNumber = line ? params.lines.indexOf(line) + 1 : 1
+
+        addError(
+          onError,
+          lineNumber,
+          `Invalid introLinks key: '${key}'. Valid keys are: ${validKeys.join(', ')}`,
+          line || '',
+          null, // No fix possible
+        )
+      }
+    }
+  },
+}

src/content-linter/lib/linting-rules/index.ts

@@ -62,6 +62,7 @@ import { journeyTracksLiquid } from './journey-tracks-liquid'
 import { journeyTracksGuidePathExists } from './journey-tracks-guide-path-exists'
 import { journeyTracksUniqueIds } from './journey-tracks-unique-ids'
 import { frontmatterHeroImage } from './frontmatter-hero-image'
+import { frontmatterIntroLinks } from './frontmatter-intro-links'
 
 // Using any type because @github/markdownlint-github doesn't provide TypeScript declarations
 // The elements in the array have a 'names' property that contains rule identifiers
@@ -132,6 +133,7 @@ export const gitHubDocsMarkdownlint = {
     journeyTracksGuidePathExists, // GHD059
     journeyTracksUniqueIds, // GHD060
     frontmatterHeroImage, // GHD061
+    frontmatterIntroLinks, // GHD062
 
     // Search-replace rules
     searchReplace, // Open-source plugin

src/content-linter/style/github-docs.ts

@@ -354,6 +354,12 @@ export const githubDocsFrontmatterConfig = {
     'partial-markdown-files': false,
     'yml-files': false,
   },
+  'frontmatter-intro-links': {
+    // GHD062
+    severity: 'error',
+    'partial-markdown-files': false,
+    'yml-files': false,
+  },
 }
 
 // Configures rules from the `github/markdownlint-github` repo

src/content-linter/tests/unit/frontmatter-intro-links.ts

@@ -0,0 +1,126 @@
+import path from 'path'
+
+import { afterAll, beforeAll, describe, expect, test } from 'vitest'
+
+import { runRule } from '../../lib/init-test'
+import { frontmatterIntroLinks } from '../../lib/linting-rules/frontmatter-intro-links'
+
+const fmOptions = { markdownlintOptions: { frontMatter: null } }
+
+describe(frontmatterIntroLinks.names.join(' - '), () => {
+  const envVarValueBefore = process.env.ROOT
+
+  beforeAll(() => {
+    process.env.ROOT = path.join('src', 'fixtures', 'fixtures')
+  })
+
+  afterAll(() => {
+    process.env.ROOT = envVarValueBefore
+  })
+
+  test('valid introLinks keys pass', async () => {
+    const markdown = [
+      '---',
+      'title: Test',
+      'introLinks:',
+      '  overview: /path/to/overview',
+      '  quickstart: /path/to/quickstart',
+      '---',
+      '',
+      '# Test',
+    ].join('\n')
+    const result = await runRule(frontmatterIntroLinks, {
+      strings: { 'content/test/index.md': markdown },
+      ...fmOptions,
+    })
+    const errors = result['content/test/index.md']
+    expect(errors.length).toBe(0)
+  })
+
+  test('missing introLinks is ignored', async () => {
+    const markdown = ['---', 'title: Test', '---', '', '# Test'].join('\n')
+    const result = await runRule(frontmatterIntroLinks, {
+      strings: { 'content/test/index.md': markdown },
+      ...fmOptions,
+    })
+    const errors = result['content/test/index.md']
+    expect(errors.length).toBe(0)
+  })
+
+  test('invalid introLinks key fails', async () => {
+    const markdown = [
+      '---',
+      'title: Test',
+      'introLinks:',
+      '  overview: /path/to/overview',
+      '  invalidKey: /path/to/invalid',
+      '---',
+      '',
+      '# Test',
+    ].join('\n')
+    const result = await runRule(frontmatterIntroLinks, {
+      strings: { 'content/test/index.md': markdown },
+      ...fmOptions,
+    })
+    const errors = result['content/test/index.md']
+    expect(errors.length).toBe(1)
+    expect(errors[0].errorDetail).toContain('Invalid introLinks key')
+    expect(errors[0].errorDetail).toContain('invalidKey')
+  })
+
+  test('multiple invalid introLinks keys fail', async () => {
+    const markdown = [
+      '---',
+      'title: Test',
+      'introLinks:',
+      '  invalidKey1: /path/to/invalid1',
+      '  invalidKey2: /path/to/invalid2',
+      '---',
+      '',
+      '# Test',
+    ].join('\n')
+    const result = await runRule(frontmatterIntroLinks, {
+      strings: { 'content/test/index.md': markdown },
+      ...fmOptions,
+    })
+    const errors = result['content/test/index.md']
+    expect(errors.length).toBe(2)
+  })
+
+  test('all common valid introLinks keys pass', async () => {
+    const markdown = [
+      '---',
+      'title: Test',
+      'introLinks:',
+      '  overview: /path/to/overview',
+      '  quickstart: /path/to/quickstart',
+      '  reference: /path/to/reference',
+      '---',
+      '',
+      '# Test',
+    ].join('\n')
+    const result = await runRule(frontmatterIntroLinks, {
+      strings: { 'content/test/index.md': markdown },
+      ...fmOptions,
+    })
+    const errors = result['content/test/index.md']
+    expect(errors.length).toBe(0)
+  })
+
+  test('non-object introLinks is ignored', async () => {
+    const markdown = [
+      '---',
+      'title: Test',
+      'introLinks: this is not an object',
+      '---',
+      '',
+      '# Test',
+    ].join('\n')
+    const result = await runRule(frontmatterIntroLinks, {
+      strings: { 'content/test/index.md': markdown },
+      ...fmOptions,
+    })
+    const errors = result['content/test/index.md']
+    expect(errors.length).toBe(0)
+  })
+})