Function extractHeredocs

src/utils/bash/heredoc.ts:113–687

(
  command: string,
  options?: { quotedOnly?: boolean },
)

 * ```
 */
export function extractHeredocs(
  command: string,
  options?: { quotedOnly?: boolean },
): HeredocExtractionResult {
  const heredocs = new Map<string, HeredocInfo>()

  // Quick check: if no << present, skip processing
  if (!command.includes('<<')) {
    return { processedCommand: command, heredocs }
  }

  // Security: Paranoid pre-validation. Our incremental quote/comment scanner
  // (see advanceScan below) does simplified parsing that cannot handle all
  // bash quoting constructs. If the command contains
  // constructs that could desync our quote tracking, bail out entirely
  // rather than risk extracting a heredoc with incorrect boundaries.
  // This is defense-in-depth: each construct below has caused or could
  // cause a security bypass if we attempt extraction.
  //
  // Specifically, we bail if the command contains:
  // 1. $'...' or $"..." (ANSI-C / locale quoting — our quote tracker
  //    doesn't handle the $ prefix, would misparse the quotes)
  // 2. Backtick command substitution (backtick nesting has complex parsing
  //    rules, and backtick acts as shell_eof_token for PST_EOFTOKEN in
  //    make_cmd.c:606, enabling early heredoc closure that our parser
  //    can't replicate)
  if (/\$['"]/.test(command)) {
    return { processedCommand: command, heredocs }
  }
  // Check for backticks in the command text before the first <<.
  // Backtick nesting has complex parsing rules, and backtick acts as
  // shell_eof_token for PST_EOFTOKEN (make_cmd.c:606), enabling early
  // heredoc closure that our parser can't replicate. We only check
  // before << because backticks in heredoc body content are harmless.
  const firstHeredocPos = command.indexOf('<<')
  if (firstHeredocPos > 0 && command.slice(0, firstHeredocPos).includes('`')) {
    return { processedCommand: command, heredocs }
  }

  // Security: Check for arithmetic evaluation context before the first `<<`.
  // In bash, `(( x = 1 << 2 ))` uses `<<` as a BIT-SHIFT operator, not a
  // heredoc. If we mis-extract it, subsequent lines become "heredoc content"
  // and are hidden from security validators, while bash executes them as
  // separate commands. We bail entirely if `((` appears before `<<` without
  // a matching `))` — we can't reliably distinguish arithmetic `<<` from
  // heredoc `<<` in that context. Note: $(( is already caught by
  // validateDangerousPatterns, but bare (( is not.
  if (firstHeredocPos > 0) {
    const beforeHeredoc = command.slice(0, firstHeredocPos)
    // Count (( and )) occurrences — if unbalanced, `<<` may be arithmetic
    const openArith = (beforeHeredoc.match(/\(\(/g) || []).length
    const closeArith = (beforeHeredoc.match(/\)\)/g) || []).length
    if (openArith > closeArith) {
      return { processedCommand: command, heredocs }
    }
  }

  // Create a global version of the pattern for iteration