Add table column integrity checker content linter rule (GHD047) (#56099)

Author: heiskr

data/reusables/contributing/content-linter-rules.md

@@ -64,6 +64,7 @@
 | GHD038 | expired-content | Expired content must be remediated. | warning | expired |
 | GHD039 | expiring-soon | Content that expires soon should be proactively addressed. | warning | expired |
 | [GHD040](https://github.com/github/docs/blob/main/src/content-linter/README.md) | table-liquid-versioning | Tables must use the correct liquid versioning format | error | tables |
+| GHD047 | table-column-integrity | Tables must have consistent column counts across all rows | warning | tables, accessibility, formatting |
 | GHD041 | third-party-action-pinning | Code examples that use third-party actions must always pin to a full length commit SHA | error | feature, actions |
 | GHD042 | liquid-tag-whitespace | Liquid tags should start and end with one whitespace. Liquid tag arguments should be separated by only one whitespace. | error | liquid, format |
 | GHD043 | link-quotation | Internal link titles must not be surrounded by quotations | error | links, url |

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

@@ -31,6 +31,7 @@ import { raiReusableUsage } from './rai-reusable-usage.js'
 import { imageNoGif } from './image-no-gif.js'
 import { expiredContent, expiringSoon } from './expired-content.js'
 import { tableLiquidVersioning } from './table-liquid-versioning.js'
+import { tableColumnIntegrity } from './table-column-integrity.js'
 import { thirdPartyActionPinning } from './third-party-action-pinning.js'
 import { liquidTagWhitespace } from './liquid-tag-whitespace.js'
 import { linkQuotation } from './link-quotation.js'
@@ -85,6 +86,7 @@ export const gitHubDocsMarkdownlint = {
     expiredContent,
     expiringSoon,
     tableLiquidVersioning,
+    tableColumnIntegrity,
     thirdPartyActionPinning,
     liquidTagWhitespace,
     linkQuotation,

src/content-linter/lib/linting-rules/table-column-integrity.js

@@ -0,0 +1,134 @@
+import { addError } from 'markdownlint-rule-helpers'
+import { getRange } from '../helpers/utils.js'
+import frontmatter from '#src/frame/lib/read-frontmatter.js'
+
+// Regex to detect table rows (must start with |, contain at least one more |, and end with optional whitespace)
+const TABLE_ROW_REGEX = /^\s*\|.*\|\s*$/
+// Regex to detect table separator rows (contains only |, :, -, and whitespace)
+const TABLE_SEPARATOR_REGEX = /^\s*\|[\s\-:|\s]*\|\s*$/
+// Regex to detect Liquid-only cells (whitespace, liquid tag, whitespace)
+const LIQUID_ONLY_CELL_REGEX = /^\s*{%\s*(ifversion|else|endif|elsif).*%}\s*$/
+
+/**
+ * Counts the number of columns in a table row by splitting on | and handling edge cases
+ */
+function countColumns(row) {
+  // Remove leading and trailing whitespace
+  const trimmed = row.trim()
+
+  // Handle empty rows
+  if (!trimmed || !trimmed.includes('|')) {
+    return 0
+  }
+
+  // Split by | and filter out empty cells at start/end (from leading/trailing |)
+  const cells = trimmed.split('|')
+
+  // Remove first and last elements if they're empty (from leading/trailing |)
+  if (cells.length > 0 && cells[0].trim() === '') {
+    cells.shift()
+  }
+  if (cells.length > 0 && cells[cells.length - 1].trim() === '') {
+    cells.pop()
+  }
+
+  return cells.length
+}
+
+/**
+ * Checks if a table row contains only Liquid conditionals
+ */
+function isLiquidOnlyRow(row) {
+  const trimmed = row.trim()
+  if (!trimmed.includes('|')) return false
+
+  const cells = trimmed.split('|')
+  // Remove empty cells from leading/trailing |
+  const filteredCells = cells.filter((cell, index) => {
+    if (index === 0 && cell.trim() === '') return false
+    if (index === cells.length - 1 && cell.trim() === '') return false
+    return true
+  })
+
+  // Check if all cells contain only Liquid tags
+  return (
+    filteredCells.length > 0 && filteredCells.every((cell) => LIQUID_ONLY_CELL_REGEX.test(cell))
+  )
+}
+
+export const tableColumnIntegrity = {
+  names: ['GHD047', 'table-column-integrity'],
+  description: 'Tables must have consistent column counts across all rows',
+  tags: ['tables', 'accessibility', 'formatting'],
+  severity: 'error',
+  function: (params, onError) => {
+    // Skip autogenerated files
+    const frontmatterString = params.frontMatterLines.join('\n')
+    const fm = frontmatter(frontmatterString).data
+    if (fm && fm.autogenerated) return
+
+    const lines = params.lines
+    let inTable = false
+    let expectedColumnCount = null
+    let tableStartLine = null
+    let headerRow = null
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      const isTableRow = TABLE_ROW_REGEX.test(line)
+      const isSeparatorRow = TABLE_SEPARATOR_REGEX.test(line)
+
+      // Check if we're starting a new table
+      if (!inTable && isTableRow) {
+        // Look ahead to see if next line is a separator (confirming this is a table)
+        const nextLine = lines[i + 1]
+        if (nextLine && TABLE_SEPARATOR_REGEX.test(nextLine)) {
+          inTable = true
+          tableStartLine = i + 1
+          headerRow = line
+          expectedColumnCount = countColumns(line)
+          continue
+        }
+      }
+
+      // Check if we're ending a table
+      if (inTable && !isTableRow) {
+        inTable = false
+        expectedColumnCount = null
+        tableStartLine = null
+        headerRow = null
+        continue
+      }
+
+      // If we're in a table, validate column count
+      if (inTable && isTableRow && !isSeparatorRow) {
+        // Skip Liquid-only rows as they're allowed to have different column counts
+        if (isLiquidOnlyRow(line)) {
+          continue
+        }
+
+        const actualColumnCount = countColumns(line)
+
+        if (actualColumnCount !== expectedColumnCount) {
+          const range = getRange(line, line.trim())
+          let errorMessage
+
+          if (actualColumnCount > expectedColumnCount) {
+            errorMessage = `Table row has ${actualColumnCount} columns but header has ${expectedColumnCount}. Add ${actualColumnCount - expectedColumnCount} more column(s) to the header row to match this row.`
+          } else {
+            errorMessage = `Table row has ${actualColumnCount} columns but header has ${expectedColumnCount}. Add ${expectedColumnCount - actualColumnCount} missing column(s) to this row.`
+          }
+
+          addError(
+            onError,
+            i + 1,
+            errorMessage,
+            line,
+            range,
+            null, // No auto-fix available due to complexity
+          )
+        }
+      }
+    }
+  },
+}

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

@@ -186,6 +186,12 @@ const githubDocsConfig = {
     'partial-markdown-files': true,
     'yml-files': true,
   },
+  'table-column-integrity': {
+    // GHD047
+    severity: 'warning',
+    'partial-markdown-files': true,
+    'yml-files': true,
+  },
   'british-english-quotes': {
     // GHD048
     severity: 'warning',

src/content-linter/tests/unit/table-column-integrity-simple.js

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'vitest'
+
+import { runRule } from '../../lib/init-test.js'
+import { tableColumnIntegrity } from '../../lib/linting-rules/table-column-integrity.js'
+
+describe(tableColumnIntegrity.names.join(' - '), () => {
+  test('Valid table with consistent columns passes', async () => {
+    const markdown = [
+      '| Artist | Album | Year |',
+      '|--------|-------|------|',
+      '| Beyoncé | Lemonade | 2016 |',
+      '| Kendrick Lamar | DAMN. | 2017 |',
+    ].join('\n')
+    const result = await runRule(tableColumnIntegrity, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(0)
+  })
+
+  test('Table with extra columns causes error', async () => {
+    const markdown = ['| Name | Age |', '|------|-----|', '| Alice | 25 | Extra |'].join('\n')
+    const result = await runRule(tableColumnIntegrity, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(1)
+    expect(errors[0].lineNumber).toBe(3)
+    if (errors[0].detail) {
+      expect(errors[0].detail).toContain('Table row has 3 columns but header has 2')
+    } else if (errors[0].errorDetail) {
+      expect(errors[0].errorDetail).toContain('Table row has 3 columns but header has 2')
+    } else {
+      console.log('Error structure:', JSON.stringify(errors[0], null, 2))
+      expect(errors[0]).toHaveProperty('detail')
+    }
+  })
+
+  test('Table with missing columns causes error', async () => {
+    const markdown = ['| Name | Age | City |', '|------|-----|------|', '| Bob | 30 |'].join('\n')
+    const result = await runRule(tableColumnIntegrity, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(1)
+    expect(errors[0].lineNumber).toBe(3)
+    if (errors[0].detail) {
+      expect(errors[0].detail).toContain('Table row has 2 columns but header has 3')
+    } else if (errors[0].errorDetail) {
+      expect(errors[0].errorDetail).toContain('Table row has 2 columns but header has 3')
+    } else {
+      console.log('Error structure:', JSON.stringify(errors[0], null, 2))
+      expect(errors[0]).toHaveProperty('detail')
+    }
+  })
+
+  test('Liquid-only rows are ignored', async () => {
+    const markdown = [
+      '| Feature | Status |',
+      '|---------|--------|',
+      '| {% ifversion ghes %} |',
+      '| Advanced | Enabled |',
+      '| {% endif %} |',
+    ].join('\n')
+    const result = await runRule(tableColumnIntegrity, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(0)
+  })
+})