Contributors' Guide

---
extends: script
message: "Abstract must be between 50 and 300 characters. Place any information that exceeds 300 characters in a new paragraph or paragraphs. It cannot be part of the abstract."
level: error
scope: raw
script: |
  // Import required Tengo modules
  text := import("text")  // Text manipulation functions
  fmt := import("fmt")    // String formatting functions

  // Initialize empty array to store rule violations
  matches := []

  // Compile regex to find the abstract paragraph in AsciiDoc
  // Each module contains exactly one abstract (a single paragraph following [role="_abstract"])
  // Pattern breakdown:
  //   \[role="_abstract"\]  - Matches the abstract role marker
  //   \s*\n                 - Matches optional whitespace and newline after marker
  //   ([\s\S]+?)            - Captures the abstract paragraph (non-greedy, including newlines)
  //   \n\n                  - Matches double newline (blank line) that ends paragraph
  // Note: Using [\s\S] instead of . to match across multiple lines
  abstract_regex := text.re_compile(`\[role="_abstract"\]\s*\n([\s\S]+?)\n\n`)

  // Find the abstract (there's only one per module)
  // scope = the full document text being checked
  // 1 = find only first match (since there's only one abstract per module)
  result := abstract_regex.find(scope, 1)

  // Check if an abstract was found (find returns undefined if no match)
  if result != undefined && len(result) > 0 && len(result[0]) > 1 {
    // result[0][0] = full match including [role="_abstract"] marker
    // result[0][1] = captured group (just the abstract paragraph text)
    abstract_text := result[0][1].text

    // Count characters in the abstract
    char_count := len(abstract_text)

    // Check if character count is outside valid range (50-300)
    if char_count < 50 || char_count > 300 {
      // Build custom error message with actual character count
      msg := fmt.sprintf("Abstract must be between 50 and 300 characters (currently %d characters).", char_count)

      // Add this violation to the matches array
      matches = append(matches, {
        begin: result[0][1].begin,    // Start position of abstract paragraph
        end: result[0][1].end,        // End position of abstract paragraph
        message: msg                  // Custom error message with character count
      })
    }
  }

---
extends: substitution
level: error
message: "Use attribute '%s' instead of a branded term."
action:
  name: replace
swap:
  "(?:orcharhino|Satellite) Server": "{ProjectServer}"
  "(?:orcharhino Proxy|Capsule)": "{SmartProxy}"
  "(?:orcharhino Proxy|Capsule) Server": "{SmartProxyServer}"
  "Red Hat Satellite": "{ProjectName}"
  "(?:orcharhino|Satellite)": "{Project}"

---
extends: substitution
ignorecase: false
level: error
message: "Use '%s' instead of '%s' unless you are using the term in a context that requires different capitalization. For example, different capitalization might be required in Web UI buttons, settings, or templates."
action:
  name: replace
swap:
  ansible: Ansible
  candlepin: candlepin
  chef: Chef
  discovery: Discovery
  enterprise linux: Enterprise Linux
  hammer: Hammer
  katello: Katello
  library: Library
  openscap: OpenSCAP
  postgresql: PostgreSQL
  pulp: Pulp
  python: Python
  salt: Salt
  salt minions: Salt Minions
  secure boot: Secure Boot
  subscription manager: Subscription Manager
  tracer: Tracer
  Lifecycle Environment: lifecycle environment
  '(?<!Pulp )Manifest': manifest
  Pulp manifest: Pulp Manifest
  Remote Execution: remote execution
  '(?<=\s)Subscription(?! Manager)': subscription
  Red Hat network: Red{nbsp}Hat Network

---
extends: script
message: "To improve content usability and user focus, links and cross references in the main body of a concept module are discouraged. Move them to the Additional resources section."
level: warning
scope: raw
script: |
  text              := import("text")
  matches           := []

  r_add_resources   := text.re_compile("^(?:={2,}[ \\t]+|\\.{1,2})Additional resources[ \\t]*$")
  r_any_title       := text.re_compile("^(?:={2,}[ \\t]+|\\.{1,2})[^ \\t.].*$")
  r_attr_link       := text.re_compile("\\{[0-9A-Za-z_][0-9A-Za-z_-]*URL\\}[^\\[\\n]*\\[[^\\]]*\\]")
  r_code_block      := text.re_compile("^(?:\\.{4,}|-{4,})[ \\t]*$")
  r_comment_block   := text.re_compile("^/{4,}\\s*$")
  r_comment_line    := text.re_compile("^(//|//[^/].*)$")
  r_content_type    := text.re_compile("^:_(?:mod-docs-content|content|module)-type:[ \\t]+(?i:assembly|concept)")

  document          := text.split(text.trim_suffix(scope, "\n"), "\n")

  is_relevant       := false
  in_code_block     := false
  in_comment_block  := false
  in_add_resources  := false
  start             := 0
  end               := 0

  for line in document {
    start += end
    end    = len(line) + 1

    if r_comment_block.match(line) {
      delimiter := text.trim_space(line)
      if ! in_comment_block {
        in_comment_block = delimiter
      } else if in_comment_block == delimiter {
        in_comment_block = false
      }
      continue
    }
    if in_comment_block { continue }
    if r_comment_line.match(line) { continue }

    if r_code_block.match(line) {
      delimiter := text.trim_space(line)
      if ! in_code_block {
        in_code_block = delimiter
      } else if in_code_block == delimiter {
        in_code_block = false
      }
      continue
    }
    if in_code_block { continue }

    if r_content_type.match(line) {
      is_relevant = true
      continue
    }

    if r_add_resources.match(line) {
      in_add_resources = true
      continue
    }

    if r_any_title.match(line) {
      in_add_resources = false
      continue
    }

    if in_add_resources { continue }

    for i, entry in r_attr_link.find(line, -1) {
      link := entry[0]
      matches = append(matches, {begin: start + link.begin, end: start + link.end - 1})
    }
  }

  if ! is_relevant {
    matches = []
  }

---
extends: script
message: "Heading must have between 3 and 11 words."
level: error
scope: raw
script: |
  // Import required Tengo modules
  text := import("text")  // Text manipulation functions
  fmt := import("fmt")    // String formatting functions

  // Initialize empty array to store rule violations
  matches := []

  // Compile regex to find the module heading
  // Each module contains exactly one heading (line starting with = )
  // Pattern breakdown:
  //   (?m)        - Multi-line mode (^ and $ match line boundaries, not just string boundaries)
  //   ^=[ \t]+    - Matches line starting with = followed by whitespace
  //   (.+)$       - Captures the heading text to end of line
  heading_regex := text.re_compile(`(?m)^=[ ]+(.+)$`)

  // Find the heading (there's only one per module)
  // scope = the full document text being checked
  // 1 = find only first match (since there's only one heading per module)
  result := heading_regex.find(scope, 1)

  // Check if a heading was found (find returns undefined if no match)
  if result != undefined && len(result) > 0 && len(result[0]) > 1 {
    // result[0][1] = captured group (just the heading text)
    heading_text := result[0][1].text

    // Count words including AsciiDoc attributes as words
    // Match either {AttributeName} or regular words
    word_regex := text.re_compile(`\{[A-Za-z][A-Za-z0-9_-]*\}|\b\w+\b`)
    words := word_regex.find(heading_text, -1)

    // Get word count (0 if no words found)
    word_count := 0
    if words != undefined {
      word_count = len(words)
    }

    // Check if word count is outside valid range (3-11)
    if word_count < 3 || word_count > 11 {
      msg := fmt.sprintf("Heading must have between 3 and 11 words (currently %d words).", word_count)
      matches = append(matches, {
        begin: result[0][1].begin,
        end: result[0][1].end,
        message: msg
      })
    }
  }

---
extends: existence
message: "Write one sentence per line."
level: error
scope: raw
nonword: true
tokens:
  # Match: word/)/]/quote + sentence-end punctuation + space/tab + capital letter/[
  # Using [ \t] instead of \s to match only horizontal whitespace, not newlines
  - '[a-z0-9\)\]"][.!?][ \t]+[A-Z\[]'

---
extends: script
message: "Procedure contains more than 10 steps. Split it into multiple procedures or leverage substeps to group related steps. If the procedure contains conditionals, review the preview to ensure all built targets comply with the limit of 10 steps."
level: error
scope: raw
script: |
  text := import("text")
  matches := []
  lines := text.split(scope, "\n")
  count := 0
  step_positions := []
  position := 0
  in_procedure := false

  for line in lines {
    // Detect .Procedure heading (only one per file)
    if text.re_match("^\\.Procedure", line) {
      in_procedure = true
    }
    // Reset when we encounter another heading at the same level
    if text.re_match("^\\.[A-Z]", line) && !text.re_match("^\\.Procedure", line) {
      in_procedure = false
    }
    // Count steps only when inside a .Procedure section
    if in_procedure && text.re_match("^\\. [^\\.]", line) {
      count += 1
      step_positions = append(step_positions, position)
    }
    position += len(line) + 1
  }

  if count > 10 {
    // Report error on ALL steps to ensure it appears in GitHub Actions diff context
    // when ANY step is modified in a procedure that exceeds the 10-step limit
    for i := 0; i < count; i++ {
      step_pos := step_positions[i]
      matches = append(matches, {begin: step_pos, end: step_pos + 1})
    }
  }