Add content linter rule for code annotation comment spacing (GHD045) (#56087)

Author: heiskr

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

@@ -53,6 +53,7 @@
 | GHD011 | frontmatter-video-transcripts | Video transcript must be configured correctly | error | frontmatter, feature, video-transcripts |
 | GHD012 | frontmatter-schema | Frontmatter must conform to the schema | error | frontmatter, schema |
 | GHD007 | code-annotations | Code annotations defined in Markdown must contain a specific layout frontmatter property | error | code, feature, annotate, frontmatter |
+| GHD045 | code-annotation-comment-spacing | Code comments in annotation blocks must have exactly one space after the comment character(s) | warning | code, comments, annotate, spacing |
 | GHD017 | frontmatter-liquid-syntax | Frontmatter properties must use valid Liquid | error | liquid, frontmatter |
 | GHD018 | liquid-syntax | Markdown content must use valid Liquid | error | liquid |
 | GHD019 | liquid-if-tags | Liquid `ifversion` tags should be used instead of `if` tags when the argument is a valid version | error | liquid, versioning |

src/content-linter/lib/linting-rules/code-annotation-comment-spacing.js

@@ -0,0 +1,98 @@
+import { addError, filterTokens } from 'markdownlint-rule-helpers'
+
+export const codeAnnotationCommentSpacing = {
+  names: ['GHD045', 'code-annotation-comment-spacing'],
+  description:
+    'Code comments in annotation blocks must have exactly one space after the comment character(s)',
+  tags: ['code', 'comments', 'annotate', 'spacing'],
+  parser: 'markdownit',
+  function: (params, onError) => {
+    filterTokens(params, 'fence', (token) => {
+      if (!token.info.includes('annotate')) return
+
+      const lines = token.content.split('\n')
+
+      lines.forEach((line, index) => {
+        const trimmedLine = line.trim()
+        if (!trimmedLine) return
+
+        // Define a map of comment patterns
+        const commentPatterns = {
+          '//': /^(\/\/)(.*)/, // JavaScript/TypeScript/Java/C# style comments
+          '#': /^(#)(.*)/, // Python/Ruby/Shell/YAML style comments
+          '--': /^(--)(.*)/, // SQL/Lua style comments
+        }
+
+        // Check for different comment patterns
+        let commentMatch = null
+        let commentChar = null
+        let restOfLine = null
+
+        // Iterate over the map to find a matching comment style
+        for (const [char, pattern] of Object.entries(commentPatterns)) {
+          if (trimmedLine.startsWith(char)) {
+            commentMatch = trimmedLine.match(pattern)
+            commentChar = char
+            restOfLine = commentMatch ? commentMatch[2] : ''
+            break
+          }
+        }
+
+        if (commentMatch && restOfLine !== null) {
+          // Skip shebang lines (#!/...)
+          if (trimmedLine.startsWith('#!')) {
+            return
+          }
+
+          // Allow empty comments or comments with exactly one space
+          if (restOfLine === '' || restOfLine.startsWith(' ')) {
+            // If it starts with a space, make sure it's exactly one space
+            if (restOfLine.startsWith(' ') && restOfLine.length > 1 && restOfLine[1] === ' ') {
+              // Multiple spaces - this is an error
+              const lineNumber = token.lineNumber + index + 1
+              const fixedLine = line.replace(
+                new RegExp(`^(\\s*${commentChar.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})\\s+`),
+                `$1 `,
+              )
+
+              addError(
+                onError,
+                lineNumber,
+                `Comment must have exactly one space after '${commentChar}', found multiple spaces`,
+                line,
+                [1, line.length],
+                {
+                  lineNumber,
+                  editColumn: 1,
+                  deleteCount: line.length,
+                  insertText: fixedLine,
+                },
+              )
+            }
+            // Single space or empty - this is correct
+            return
+          } else {
+            // No space after comment character - this is an error
+            const lineNumber = token.lineNumber + index + 1
+            const leadingWhitespace = line.match(/^\s*/)[0]
+            const fixedLine = leadingWhitespace + commentChar + ' ' + restOfLine
+
+            addError(
+              onError,
+              lineNumber,
+              `Comment must have exactly one space after '${commentChar}'`,
+              line,
+              [1, line.length],
+              {
+                lineNumber,
+                editColumn: 1,
+                deleteCount: line.length,
+                insertText: fixedLine,
+              },
+            )
+          }
+        }
+      })
+    })
+  },
+}

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

@@ -24,6 +24,7 @@ import { liquidQuotedConditionalArg } from './liquid-quoted-conditional-arg.js'
 import { liquidDataReferencesDefined, liquidDataTagFormat } from './liquid-data-tags.js'
 import { frontmatterSchema } from './frontmatter-schema.js'
 import { codeAnnotations } from './code-annotations.js'
+import { codeAnnotationCommentSpacing } from './code-annotation-comment-spacing.js'
 import { frontmatterLiquidSyntax, liquidSyntax } from './liquid-syntax.js'
 import { liquidIfTags, liquidIfVersionTags } from './liquid-versioning.js'
 import { raiReusableUsage } from './rai-reusable-usage.js'
@@ -73,6 +74,7 @@ export const gitHubDocsMarkdownlint = {
     frontmatterVideoTranscripts,
     frontmatterSchema,
     codeAnnotations,
+    codeAnnotationCommentSpacing,
     frontmatterLiquidSyntax,
     liquidSyntax,
     liquidIfTags,

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

@@ -180,6 +180,12 @@ const githubDocsConfig = {
     'partial-markdown-files': true,
     'yml-files': true,
   },
+  'code-annotation-comment-spacing': {
+    // GHD045
+    severity: 'warning',
+    'partial-markdown-files': true,
+    'yml-files': true,
+  },
   'british-english-quotes': {
     // GHD048
     severity: 'warning',