tree-sitter-gh-actions-expressions 0.5.0

Github Actions expressions grammar for tree-sitter

tree-sitter-gh-actions-expressions

Tree-sitter grammar for Github Actions expressions

[!IMPORTANT] ABI version: 15

Parser requirements

• gitignore (optional): for hashFiles() function
• json (optional): for fromJSON() function
• yaml: injection to its block_mapping_pair node. Check the yaml injection section for more information

Usage in Editors

Neovim

• gh-actions.nvim: plugin that integrates this grammar to your Neovim configuration

Helix

WIP

Emacs

WIP

In General

You can get the built files from the release branch. If you have specific instructions for your editor, PR's are welcome.

Injection for yaml parser

Use the following query:

((block_mapping_pair
  key: (flow_node) @_key
  value: [
    (block_node
      (block_scalar) @_value)
    (flow_node
      [
        (plain_scalar
          (string_scalar) @_value)
        (double_quote_scalar) @_value
      ])
  ]
  (#lua-match? @_value "${{")) @injection.content
  (#is-gh-actions-file? "") ; NOTE: NEW PREDICATE
  (#set! injection.language "gh_actions_expressions")
  (#set! injection.include-children))

((block_mapping_pair
  key: (flow_node) @_key
  (#eq? @_key "if")
  value: (flow_node
    (plain_scalar
      (string_scalar) @_value)
    (#not-lua-match? @_value "${{"))) @injection.content
  (#is-gh-actions-file? "") ; NOTE: NEW PREDICATE
  (#set! injection.language "gh_actions_expressions")
  (#set! injection.include-children))

is-gh-actions-file predicate

To avoid injecting this grammar to files other than github actions, is recommended to create a predicate named is-gh-actions-file.

[!NOTE] The creation of this directive varies for each editor

This predicate will be the responsible to allow injection to files that matches the name pattern .github/workflows/*.ya?ml.

Implementations

gh-actions.nvim

• Parser register and new predicate
• Yaml injection

Troubleshooting

AST errors within bash injections when using run key

To avoid these errors, is recommended to surround the expression within a raw_string node, string with single quotes ', i.e.:

jobs:
  dry-run:
    name: dry-run
    runs-on: ubuntu-latest
    steps:
      - name: dry-run
        run: ./script.sh '${{ inputs.mode }}' --dry-run

What if I need it within a variable expansion?

Because variable expansion is done by using $ prefix, the ${{ and }} nodes will cause an AST error. To avoid this declare an auxiliary bash variable or an environment variable:

jobs:
  dry-run:
    name: dry-run
    runs-on: ubuntu-latest
    steps:
      - name: dry-run
        run: |
          auxiliary_var='${{ inputs.mode }}'
          ./script.sh "$MY_VAR and $MODE" --dry-run
          ./script.sh "$MY_VAR and $auxiliary_var" --dry-run
        env:
          MODE: ${{ inputs.mode }}

References

• Github Actions expressions documentation
• if conditional:
  • run.steps[*].if
  • jobs.<job_id>.if
• Gihub Actions Context documentation

Thanks

Thanks to @disrupted for creating tree-sitter-github-actions grammar, which is the base I used to create this grammar.