Skip to content

Add embedded syntax highlighting for github-script and run blocks#571

Open
dncrews wants to merge 11 commits intogithub:mainfrom
dncrews:embedded-syntax-highlighting
Open

Add embedded syntax highlighting for github-script and run blocks#571
dncrews wants to merge 11 commits intogithub:mainfrom
dncrews:embedded-syntax-highlighting

Conversation

@dncrews
Copy link

@dncrews dncrews commented Feb 27, 2026

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-script highlighting 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-related if behavior, 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:

  • focused Jest regression tests for the expression grammar
  • YAML fixtures covering the affected expression cases
  • lightweight syntax test utilities used by those tests
  • documentation for grammar triage and fixture-based regression testing
  • the small Jest import update in the existing secrets test for consistency with the current test style

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-script and run blocks 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-script with.script blocks and run: blocks with explicit shell: 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-script support 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-script with.script blocks
  • run: blocks when the step has an explicit supported shell:

This builds on the expression grammar and test scaffolding work in #570. In particular, this PR adds:

  • grammar registrations for embedded workflow injections
  • an embedded JavaScript grammar for actions/github-script
  • embedded grammars for explicit run shells such as bash, PowerShell, batch, Python, and Node
  • focused fixture-based regression tests for those embedding rules
  • the additional syntax test utilities and documentation updates needed for embedded-language cases

Additional 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

@dncrews dncrews requested a review from a team as a code owner February 27, 2026 18:42
Copilot AI review requested due to automatic review settings February 27, 2026 18:42
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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) and run: blocks with explicit supported shell: values.
  • Add new TextMate grammar files for github-script embeddings and run+shell embeddings, plus updates to the expressions grammar for improved if: 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.

@dncrews dncrews force-pushed the embedded-syntax-highlighting branch from f4f1297 to a55d08a Compare February 27, 2026 19:03
@dncrews
Copy link
Author

dncrews commented Feb 27, 2026

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:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants