No clear syntax to avoid shellcheck SC2086 for expression substitutions

[williamrowell]

Describe the bug
sprocket lint + shellcheck complains about unquoted placeholder expressions that are ignored by miniwdl check + shellcheck. Some of these are valid complaints, I think, but others don't have clear workarounds.

Example: {if threads > 1 then "--threads " + (threads - 1) else ""}

Because the leading -- is missing, it isn't treated as an option and shellcheck (when called by sprocket lint) flags it as SC2086.

Incidentally, miniwdl check + shellcheck also doesn't flag unquoted substitutions in filenames with SC2086, but I think the correct behavior is to flag those. I'm not sure what the appropriate solution for the longer expression substitutions should be, though.

Expected behavior
Ideally we'd have some workaround to handle command substitutions that wouldn't require suppressing the rule for the entire command.

Terminal Output

$ cat << EOF > samtools_index.wdl
version 1.0

task samtools_index {
  meta {
    description: "index a bam with samtools"
    outputs: {
      index: {
        description: "bam index"
      }
    }
  }

  parameter_meta {
    bam: {
      description: "aligned, sorted bam"
    }
  }

  input {
    File bam
  }

  Int threads = 4
  Int mem_gb = 8

  command <<<
    set -euo pipefail

    samtools index --bai \
      ~{if threads > 1 then "--threads " + (threads - 1) else ""} \
      --output ~{bam}.bai \
      ~{bam}
  >>>

  output {
    File index = "${bam}.bai"
  }

  runtime {
    docker: "quay.io/pacbio/pb_wdl_base@sha256:4b889a1f21a6a7fecf18820613cf610103966a93218de772caba126ab70a8e87"
    cpu: threads
    memory: mem_gb + " GiB"
  }
}

EOF

$ shellcheck --version

ShellCheck - shell script analysis tool
version: 0.9.0
license: GNU General Public License, version 3
website: https://www.shellcheck.net

$ sprocket --version

sprocket 0.20.1 (2026-02-04)

$ sprocket lint --report-mode one-line samtools_index.wdl

samtools_index.wdl:30:7: note[ShellCheck]: Double quote to prevent globbing and word splitting.
samtools_index.wdl:31:16: note[ShellCheck]: Double quote to prevent globbing and word splitting.
samtools_index.wdl:32:7: note[ShellCheck]: Double quote to prevent globbing and word splitting.

$ miniwdl version

miniwdl v1.13.1

$ miniwdl check --debug --strict samtools_index.wdl 

samtools_index.wdl
    task samtools_index

Environment (please complete the following information):

• OS: linux, Rocky 9
• Version: WDL version 1.0, sprocket 0.20.1
• Shell: bash
• Toolchain version: rustc 1.93.0 (254b59607 2026-01-19)

Additional context

[kris70lesgo]

@williamrowell @a-frantz Should WDL expression substitutions (~{...}) be replaced with
a placeholder before running shellcheck to avoid false positives
like SC2086? or is there a preferred strategy already used in the wdl crates?

[a-frantz]

@williamrowell there is a workaround for this case! Replacing the command block with the below makes shellcheck happy and is the "most correct" Bash:

  command <<<
    set -euo pipefail

    samtools index --bai \
      ~{if threads > 1 then "--threads '" + (threads - 1) + "'" else ""} \
      --output "~{bam}.bai" \
      "~{bam}"
  >>>

The key is that you need to quote '(threads - 1)' instead of quoting the entire substitution. I think we can improve the fix message here, but I think the diagnostic itself is correct and does not need to be suppressed. Maybe the diagnostic should only highlight the interpolation portion of the placeholder? 🤔

[a-frantz]

@kris70lesgo sorry for the delay in responding! I've had this tab open for ages and have just gotten around to testing my theory this morning 😅

Should WDL expression substitutions (~{...}) be replaced with
a placeholder before running shellcheck to avoid false positives
like SC2086? or is there a preferred strategy already used in the wdl crates?

There is a lot of existing placeholder replacement logic in the implementation: https://github.com/stjude-rust-labs/sprocket/blob/main/crates/wdl-lint/src/rules/shellcheck.rs
but there's room for improvement! I have two improvements to this rule in mind:

First, as I suggested above:

we can improve the fix message here... Maybe the diagnostic should only highlight the interpolation portion of the placeholder?

this would be possible with refactoring the to_bash_var() function . In the case that a Bash variable is inserted, there could be an additional Span returned which just highlights the problematic portion of the interpolated string. So instead of the current diagnostic:

note[ShellCheck]: Double quote to prevent globbing and word splitting.
   ┌─ tmp.wdl:30:7
   │
30 │       ~{if threads > 1 then "--threads " + (threads - 1) else ""} \
   │       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   │       │
   │       SC2086[info]: Double quote to prevent globbing and word splitting.
   │       more info: https://www.shellcheck.net/wiki/SC2086
   │
   = fix: address the diagnostic as recommended in the message

we could just highlight the "--threads " + (threads - 1) portion which would have made the "correct" Bash solution clearer in this original issue.

A second improvement would be resolving the existing TODO in the rule's code: https://github.com/stjude-rust-labs/sprocket/blob/main/crates/wdl-lint/src/rules/shellcheck.rs#L57
There are some ShellCheck rules we've suppressed completely, but ideally they would be emitted for non-placeholder instances of the rule. 2043, 2050, 2157 should be emitted if a WDL author writes incorrect Bash, but the existing substitution logic causes these to be falsely emitted in some placeholders.

[kris70lesgo]

@a-frantz Thanks for the clarification!

[williamrowell]

@a-frantz: What's the best way to prevent ~{sep=" " vcfs} from triggering SC2086?

[a-frantz]

@a-frantz: What's the best way to prevent ~{sep=" " vcfs} from triggering SC2086?

    command <<<
        foo ~{sep(" ", squote(vcfs))}
    >>>

Is the best solution I see. Although I don't think either of those stdlib functions are available in WDLv1.0. Both were added in v1.1. There may not be a v1.0 compliant solution 🤔