feat: add CodeQL CLI transformer for Article API (#58771)

Author: heiskr

src/article-api/lib/strip-html-comments.ts

@@ -0,0 +1,31 @@
+/**
+ * Strips HTML comments from markdown content.
+ * Removes single-line HTML comments like <!-- markdownlint-disable GHD053 -->
+ * while preserving other content.
+ *
+ * @param content - The markdown content to process
+ * @returns The content with HTML comments removed
+ */
+export function stripHtmlComments(content: string): string {
+  // Remove single-line HTML comments (<!-- ... -->)
+  // This matches comments that are on their own line or inline
+  return content.replace(/<!--.*?-->/g, '').trim()
+}
+
+/**
+ * Strips HTML comments and cleans up extra blank lines.
+ * Useful for cleaning up rendered markdown content where HTML comments
+ * were on separate lines and their removal creates gaps.
+ *
+ * @param content - The markdown content to process
+ * @returns The content with HTML comments removed and blank lines normalized
+ */
+export function stripHtmlCommentsAndNormalizeWhitespace(content: string): string {
+  // Remove HTML comments
+  let cleaned = stripHtmlComments(content)
+
+  // Normalize multiple consecutive blank lines to at most 2 blank lines
+  cleaned = cleaned.replace(/\n{3,}/g, '\n\n')
+
+  return cleaned.trim()
+}

src/article-api/tests/codeql-cli-transformer.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test, beforeAll } from 'vitest'
+import { get } from '@/tests/helpers/e2etest'
+
+const makeURL = (pathname: string): string =>
+  `/api/article/body?${new URLSearchParams({ pathname })}`
+
+describe('codeql cli article body api', () => {
+  beforeAll(() => {
+    if (!process.env.ROOT) {
+      console.warn(
+        'WARNING: The CodeQL CLI transformer tests require the ROOT environment variable to be set to the fixture root',
+      )
+    }
+  })
+
+  test('database-analyze page', async () => {
+    const res = await get(
+      makeURL('/en/code-security/codeql-cli/codeql-cli-manual/database-analyze'),
+    )
+
+    expect(res.statusCode).toBe(200)
+    expect(res.headers['content-type']).toContain('text/markdown')
+
+    // Check for title injection
+    expect(res.body).toContain('# database analyze')
+
+    // Check for intro injection
+    expect(res.body).toContain(
+      'Analyze a database, producing meaningful results in the context of the source code.',
+    )
+
+    // Check for content
+    expect(res.body).toContain('## Synopsis')
+    expect(res.body).toContain('## Description')
+    expect(res.body).toContain('## Options')
+
+    // Verify HTML comments are stripped
+    expect(res.body).not.toContain('<!-- markdownlint-disable GHD053 -->')
+    expect(res.body).not.toContain('<!-- markdownlint-disable GHD030 -->')
+    expect(res.body).not.toContain('<!-- Content after this section is automatically generated -->')
+  })
+
+  test('canTransform returns false for non-codeql-cli pages', async () => {
+    const res = await get(makeURL('/en/get-started/start-your-journey/hello-world'))
+    // This should not be transformed by CodeQL CLI transformer
+    expect(res.statusCode).toBe(200)
+  })
+})

src/article-api/tests/strip-html-comments.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from 'vitest'
+import {
+  stripHtmlComments,
+  stripHtmlCommentsAndNormalizeWhitespace,
+} from '@/article-api/lib/strip-html-comments'
+
+describe('stripHtmlComments', () => {
+  test('removes single-line HTML comments', () => {
+    const input = '<!-- markdownlint-disable GHD053 -->'
+    const expected = ''
+    expect(stripHtmlComments(input)).toBe(expected)
+  })
+
+  test('removes multiple HTML comments', () => {
+    const input = '<!-- comment 1 -->\nSome content\n<!-- comment 2 -->'
+    const expected = 'Some content'
+    expect(stripHtmlComments(input)).toBe(expected)
+  })
+
+  test('removes inline HTML comments', () => {
+    const input = 'Text before <!-- comment --> text after'
+    const expected = 'Text before  text after'
+    expect(stripHtmlComments(input)).toBe(expected)
+  })
+
+  test('preserves content without HTML comments', () => {
+    const input = 'Just regular markdown content'
+    const expected = 'Just regular markdown content'
+    expect(stripHtmlComments(input)).toBe(expected)
+  })
+
+  test('handles multiple comments on same line', () => {
+    const input = '<!-- comment 1 --> text <!-- comment 2 -->'
+    const expected = 'text'
+    expect(stripHtmlComments(input)).toBe(expected)
+  })
+})
+
+describe('stripHtmlCommentsAndNormalizeWhitespace', () => {
+  test('removes HTML comments and normalizes blank lines', () => {
+    const input = `<!-- markdownlint-disable GHD053 -->
+
+<!-- markdownlint-disable GHD030 -->
+
+Content here`
+    const expected = 'Content here'
+    expect(stripHtmlCommentsAndNormalizeWhitespace(input)).toBe(expected)
+  })
+
+  test('normalizes multiple blank lines to at most two', () => {
+    const input = `Line 1
+
+
+
+Line 2`
+    const expected = `Line 1
+
+Line 2`
+    expect(stripHtmlCommentsAndNormalizeWhitespace(input)).toBe(expected)
+  })
+
+  test('handles real CodeQL CLI content pattern', () => {
+    const input = `# database analyze
+
+Analyze a database, producing meaningful results
+
+<!-- markdownlint-disable GHD053 -->
+
+<!-- markdownlint-disable GHD030 -->
+
+<!-- Content after this section is automatically generated -->
+
+## Synopsis
+
+\`\`\`shell
+codeql database analyze
+\`\`\``
+
+    const expected = `# database analyze
+
+Analyze a database, producing meaningful results
+
+## Synopsis
+
+\`\`\`shell
+codeql database analyze
+\`\`\``
+
+    expect(stripHtmlCommentsAndNormalizeWhitespace(input)).toBe(expected)
+  })
+
+  test('preserves intentional double line breaks', () => {
+    const input = `# Title
+
+Paragraph 1
+
+Paragraph 2`
+    const expected = `# Title
+
+Paragraph 1
+
+Paragraph 2`
+    expect(stripHtmlCommentsAndNormalizeWhitespace(input)).toBe(expected)
+  })
+})

src/article-api/transformers/codeql-cli-transformer.ts

@@ -0,0 +1,30 @@
+import type { Context, Page } from '@/types'
+import type { PageTransformer } from './types'
+import { stripHtmlCommentsAndNormalizeWhitespace } from '@/article-api/lib/strip-html-comments'
+
+/**
+ * Transformer for CodeQL CLI reference pages.
+ * Renders autogenerated CodeQL CLI documentation pages as markdown.
+ * Sets `markdownRequested` to true in the context to ensure the page is rendered as markdown,
+ * bypassing the default article type check.
+ */
+export class CodeQLCliTransformer implements PageTransformer {
+  canTransform(page: Page): boolean {
+    return page.autogenerated === 'codeql-cli'
+  }
+
+  async transform(page: Page, _pathname: string, context: Context): Promise<string> {
+    // CodeQL CLI pages are fully generated markdown files in the repo.
+    // We render them with markdownRequested=true to get the markdown output,
+    // similar to how regular articles are rendered but through the transformer pattern.
+    context.markdownRequested = true
+    const content = await page.render(context)
+
+    const intro = page.intro ? await page.renderProp('intro', context, { textOnly: true }) : ''
+
+    const result = `# ${page.title}\n\n${intro}\n\n${content}`
+
+    // Strip HTML comments (e.g., markdownlint-disable comments) from the output
+    return stripHtmlCommentsAndNormalizeWhitespace(result)
+  }
+}

src/article-api/transformers/index.ts

@@ -1,5 +1,6 @@
 import { TransformerRegistry } from './types'
 import { RestTransformer } from './rest-transformer'
+import { CodeQLCliTransformer } from './codeql-cli-transformer'
 import { AuditLogsTransformer } from './audit-logs-transformer'
 import { GraphQLTransformer } from './graphql-transformer'
 
@@ -10,6 +11,7 @@ import { GraphQLTransformer } from './graphql-transformer'
 export const transformerRegistry = new TransformerRegistry()
 
 transformerRegistry.register(new RestTransformer())
+transformerRegistry.register(new CodeQLCliTransformer())
 transformerRegistry.register(new AuditLogsTransformer())
 transformerRegistry.register(new GraphQLTransformer())
 

src/fixtures/fixtures/content/code-security/codeql-cli/codeql-cli-manual/database-analyze.md

@@ -0,0 +1,36 @@
+---
+title: database analyze
+intro: Analyze a database, producing meaningful results in the context of the source code.
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '*'
+type: reference
+product: Code Security
+autogenerated: codeql-cli
+---
+
+<!-- markdownlint-disable GHD053 -->
+
+<!-- markdownlint-disable GHD030 -->
+
+<!-- Content after this section is automatically generated -->
+
+## Synopsis
+
+```shell copy
+codeql database analyze --format=<format> --output=<output> [--threads=<num>] [--ram=<MB>] <options>... -- <database> <query|dir|suite|pack>...
+```
+
+## Description
+
+Analyze a database, producing meaningful results in the context of the
+source code.
+
+## Options
+
+### Primary Options
+
+#### `<database>`
+
+[Mandatory] Path to the CodeQL database to query.

src/fixtures/fixtures/content/code-security/codeql-cli/codeql-cli-manual/index.md

@@ -0,0 +1,10 @@
+---
+title: CodeQL CLI Manual
+intro: Manual for CodeQL CLI
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghec: '*'
+children:
+  - /database-analyze
+---

src/fixtures/fixtures/content/code-security/codeql-cli/index.md

@@ -0,0 +1,10 @@
+---
+title: CodeQL CLI
+intro: CodeQL CLI documentation
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghec: '*'
+children:
+  - /codeql-cli-manual
+---

src/fixtures/fixtures/content/code-security/index.md

@@ -14,4 +14,5 @@ versions:
 children:
   - /getting-started
   - /guides
+  - /codeql-cli
 ---