add rules to check for block titles

Author: rosieyohannan

styles/circleci-docs/CodeBlockTitles.yml

@@ -0,0 +1,77 @@
+---
+extends: script
+scope: raw
+level: warning
+message: "Code blocks should have a title (line starting with '.' before the code block)."
+link: https://github.com/circleci/circleci-docs
+script: |
+  text := import("text")
+  matches := []
+
+  lines := text.split(scope, "\n")
+
+  // Track delimiter counts for different types
+  listing_count := 0  // ----
+  fenced_count := 0   // ````
+  literal_count := 0  // ....
+
+  for i, line in lines {
+    trimmed := text.trim_space(line)
+
+    // Check for code block delimiters
+    is_listing_block := text.re_match("^-{4,}$", trimmed)
+    is_fenced_block := text.re_match("^`{3,}$", trimmed)
+    is_literal_block := text.re_match("^\\.{4,}$", trimmed)
+
+    if is_listing_block || is_fenced_block || is_literal_block {
+      // Determine which count to use
+      current_count := 0
+      if is_listing_block {
+        current_count = listing_count
+      } else if is_fenced_block {
+        current_count = fenced_count
+      } else if is_literal_block {
+        current_count = literal_count
+      }
+
+      // Even count = opening delimiter, odd count = closing delimiter
+      is_opening := current_count % 2 == 0
+
+      if is_opening {
+        // Look back for a title, skipping empty lines and attributes
+        has_title := false
+
+        for j := i - 1; j >= 0; j-- {
+          prev_trimmed := text.trim_space(lines[j])
+
+          // Skip empty lines and attribute lines (like [,yaml])
+          if prev_trimmed == "" || text.has_prefix(prev_trimmed, "[") {
+            continue
+          }
+
+          // Check if this line is a title
+          if text.has_prefix(prev_trimmed, ".") {
+            has_title = true
+            break
+          }
+
+          // Found a non-attribute, non-empty line that's not a title
+          break
+        }
+
+        if !has_title {
+          start := text.index(scope, line)
+          matches = append(matches, {begin: start, end: start + len(line)})
+        }
+      }
+
+      // Increment the appropriate counter
+      if is_listing_block {
+        listing_count = listing_count + 1
+      } else if is_fenced_block {
+        fenced_count = fenced_count + 1
+      } else if is_literal_block {
+        literal_count = literal_count + 1
+      }
+    }
+  }

styles/circleci-docs/ImageTitles.yml

@@ -0,0 +1,44 @@
+---
+extends: script
+scope: raw
+level: warning
+message: "Images should have a title (line starting with '.' before the image)."
+link: https://github.com/circleci/circleci-docs
+script: |
+  text := import("text")
+  matches := []
+
+  lines := text.split(scope, "\n")
+
+  for i, line in lines {
+    trimmed := text.trim_space(line)
+
+    // Check for image
+    if text.has_prefix(trimmed, "image::") {
+      // Look back for a title, skipping empty lines and attributes
+      has_title := false
+
+      for j := i - 1; j >= 0; j-- {
+        prev_trimmed := text.trim_space(lines[j])
+
+        // Skip empty lines and attribute lines
+        if prev_trimmed == "" || text.has_prefix(prev_trimmed, "[") {
+          continue
+        }
+
+        // Check if this line is a title
+        if text.has_prefix(prev_trimmed, ".") {
+          has_title = true
+          break
+        }
+
+        // Found a non-attribute, non-empty line that's not a title
+        break
+      }
+
+      if !has_title {
+        start := text.index(scope, line)
+        matches = append(matches, {begin: start, end: start + len(line)})
+      }
+    }
+  }

styles/circleci-docs/TableTitles.yml

@@ -0,0 +1,52 @@
+---
+extends: script
+scope: raw
+level: warning
+message: "Tables should have a title (line starting with '.' before the table)."
+link: https://github.com/circleci/circleci-docs
+script: |
+  text := import("text")
+  matches := []
+
+  lines := text.split(scope, "\n")
+  table_delimiter_count := 0
+
+  for i, line in lines {
+    trimmed := text.trim_space(line)
+
+    // Check for table delimiter
+    if trimmed == "|===" {
+      // Even count = opening delimiter, odd count = closing delimiter
+      is_opening := table_delimiter_count % 2 == 0
+
+      if is_opening {
+        // Look back for a title, skipping empty lines, attributes, and block delimiters
+        has_title := false
+
+        for j := i - 1; j >= 0; j-- {
+          prev_trimmed := text.trim_space(lines[j])
+
+          // Skip empty lines, attribute lines, and block delimiters (-- or ==)
+          if prev_trimmed == "" || text.has_prefix(prev_trimmed, "[") || prev_trimmed == "--" || prev_trimmed == "==" {
+            continue
+          }
+
+          // Check if this line is a title
+          if text.has_prefix(prev_trimmed, ".") {
+            has_title = true
+            break
+          }
+
+          // Found a non-attribute, non-empty line that's not a title
+          break
+        }
+
+        if !has_title {
+          start := text.index(scope, line)
+          matches = append(matches, {begin: start, end: start + len(line)})
+        }
+      }
+
+      table_delimiter_count = table_delimiter_count + 1
+    }
+  }