Add embedded syntax highlighting for github-script and run blocks#571
Add embedded syntax highlighting for github-script and run blocks#571dncrews wants to merge 11 commits intogithub:mainfrom
Conversation
There was a problem hiding this comment.
Pull request overview
This PR extends the GitHub Actions workflow TextMate grammars to support embedded-language syntax highlighting (notably actions/github-script and run: blocks with explicit shell:), and adds a lightweight fixture-based Jest regression suite to prevent highlighting regressions.
Changes:
- Register new injection grammars and embedded-language mappings for
actions/github-script(with.script) andrun:blocks with explicit supportedshell:values. - Add new TextMate grammar files for
github-scriptembeddings andrun+shellembeddings, plus updates to the expressions grammar for improvedif:handling. - Introduce fixture-based Jest tests and shared utilities/documentation for validating embedded and expression grammar behavior.
Reviewed changes
Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
src/workflow/syntax/syntax-test-utils.ts |
Adds shared helpers for loading grammars/fixtures and asserting embedded/expression boundaries. |
src/workflow/syntax/syntax-embeddings.test.ts |
Adds regression tests for github-script and run/shell embedding detection. |
src/workflow/syntax/expression-syntax.test.ts |
Adds regression tests around expression parsing edge cases and if: tokenization. |
src/workflow/syntax/README.md |
Documents triage process and how to add fixture-based grammar regression tests. |
src/workflow/syntax/fixtures/run-shell-embedded.yml |
Fixture covering supported shell:-driven run: embeddings (pwsh/bash/node). |
src/workflow/syntax/fixtures/run-shell-edge-cases.yml |
Fixture covering non-block run: and comment/quoting edge cases for shell:. |
src/workflow/syntax/fixtures/inline-multiple-expressions.yml |
Fixture for multiple ${{ }} occurrences on one line. |
src/workflow/syntax/fixtures/if-inline-edge-cases.yml |
Fixture for if: with # inside quotes and escaped quotes. |
src/workflow/syntax/fixtures/if-comment-after-string.yml |
Fixture for trailing YAML comment handling after quoted strings in if:. |
src/workflow/syntax/fixtures/if-block-expression.yml |
Fixture for block-scalar `if: |
src/workflow/syntax/fixtures/github-script-embedded.yml |
Fixture for embedding JS only within actions/github-script `script: |
src/workflow/syntax/fixtures/github-script-comments.yml |
Fixture for comments on uses: and script: headers in github-script steps. |
src/workflow/syntax/fixtures/expression-nested-braces.yml |
Fixture for ${{ }} termination with }} inside quoted strings. |
src/workflow/syntax/fixtures/expression-multiline.yml |
Fixture for multi-line inline expression parsing. |
package.json |
Registers new injection grammars and maps embedded scopes to VS Code language IDs. |
language/syntaxes/run-shell-embedded.tmLanguage.json |
Implements run: block embeddings based on explicit shell: in the same step. |
language/syntaxes/github-script-embedded.tmLanguage.json |
Implements embedded JavaScript tokenization for actions/github-script with.script blocks. |
language/syntaxes/expressions.tmGrammar.json |
Updates expression injection patterns and adds operator patterns + improved if: handling. |
language/README.md |
Adds a pointer to the workflow syntax triage/testing documentation. |
src/secrets/index.test.ts |
Aligns test import style by explicitly importing Jest globals. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
f4f1297 to
a55d08a
Compare
|
Hey @ericsciple: First, I apologize in advance for the two direct tags on you (with almost identical text). The main reason for two incoming pings is that I wanted to allow the PRs to stand on their own as much as y'all want, and so I wanted to separate the discussion but let the team have full context. I normally try not to hit people up directly but since these two PRs (#570 & #571) touch on so many issues, there wasn't really a single thread for me to extend the conversation, and I wasn't quite sure how you would like me to proceed. The original issue I wanted to discuss was embedded syntax highlighting. I found #194 that discussed that, so I figured I'd move ahead on that one. In the process of building that, I wanted a bit more confidence in my changes, so I put in some testing components. That made the PR large enough that I didn't feel comfortable moving forward without splitting it into two:
|
Context
This PR is intended as an extension of #570. If we merge this one, that work (and the extracted expression grammar work from #468) would land together.
This also provides a concrete implementation for the long-standing
actions/github-scripthighlighting request in #194.Context from #570
Is your feature request related to a problem? Please describe.
Syntax-highlighting regressions in GitHub Actions workflow expressions are hard to diagnose and easy to reintroduce. This codebase did not have testing around these, and there have been several errors and a few regressions dealt with and managed in Issues.
Describe the solution you'd like
This PR adds a small workflow syntax test harness, fixture-based expression coverage, and the expression grammar changes needed for those cases to pass.
The expression grammar changes in this PR are extracted from and based on prior work by @cdce8p in #468, including fixes for block
if:handling, comment-relatedifbehavior, multi-line inline expressions, and nested-curly-brace expression parsing.My additions in this PR are the supporting work needed to land and maintain that logic in a smaller reviewable unit:
Additional context
Shout-out to @cdce8p for the original expression grammar work in #468, which this PR builds on and extracts into a smaller reviewable unit.
This PR is the first half of a split from a larger change set. It intentionally contains only the expression grammar changes and the supporting regression-test/documentation work. Embedded syntax highlighting for
github-scriptandrunblocks will be submitted separately.Is your feature request related to a problem? Please describe.
Workflow files can contain embedded languages in places like
actions/github-scriptwith.scriptblocks andrun:blocks with explicitshell:values, but those regions are currently highlighted as plain YAML. That makes JavaScript, shell, PowerShell, batch, Python, and similar embedded code harder to read and review.In particular,
actions/github-scriptsupport has been explicitly requested before in #194.Describe the solution you'd like
This PR adds embedded syntax highlighting for workflow script bodies by registering injection grammars for:
actions/github-scriptwith.scriptblocksrun:blocks when the step has an explicit supportedshell:This builds on the expression grammar and test scaffolding work in #570. In particular, this PR adds:
actions/github-scriptrunshells such as bash, PowerShell, batch, Python, and NodeAdditional context
This PR is the second half of a split from a larger change set. It complements #570 by extending the workflow syntax work from expression handling into embedded-language highlighting.
Validation:
npm test