nushell / nushell/vscode-nushell-lang
Consider maintaining a single source of truth for Nushell syntax highlighting grammars
Nobody has claimed this yet.
- Dominant language
- Nushell
- Stars
- 153
- Forks
- 31
- PR merge metrics
- No merged PRs in 30d
Description
While looking into a syntax-highlighting issue with GitHub Linguist, I noticed that there are currently multiple Nushell grammars being maintained independently.
For example, GitHub Linguist currently uses hustcer/nu-grammar, while this repository maintains the grammar used by the VS Code extension. These grammars appear to have diverged over time.
This can result in syntax being highlighted correctly in VS Code but incorrectly on GitHub. For example:
mut t = [[a b]; [1 2]]
The VS Code grammar currently handles this correctly, while the grammar used by GitHub Linguist incorrectly makes the expression after ; appear comment-like. I opened https://github.com/hustcer/nu-grammar/issues/8 for that particular issue.
This seems like a broader maintenance problem rather than just an isolated highlighting bug. If the two grammars are maintained separately, changes to Nushell syntax can easily be implemented in one but not the other.
Possible approaches
One option would be for GitHub Linguist to consume the grammar maintained in this repository directly, rather than relying on a separate third-party copy.
Another option, which may be cleaner, would be to extract the TextMate grammar into a dedicated repository under the Nushell organization and have both this VS Code extension and GitHub Linguist consume that grammar.
I initially considered using nushell/grammar for this purpose, but I noticed that it is a different project: it is a Pest-based Rust grammar intended for parsing and experimentation, rather than a TextMate grammar for syntax highlighting. Therefore, I don't think it would be appropriate to simply replace the TextMate grammar with that project.
A dedicated repository for the TextMate grammar could instead serve as the single source of truth for syntax highlighting, while nushell/grammar can continue to serve its existing purpose.
Why this might be useful
Having a single canonical TextMate grammar would:
- Avoid GitHub and VS Code having subtly different syntax highlighting behavior.
- Prevent grammar changes from getting lost or becoming stale in downstream copies.
- Make Nushell syntax changes easier to propagate to different editors and platforms.
- Give GitHub Linguist and the VS Code extension a common upstream source.
- Make it easier to add regression tests for syntax highlighting once and have them apply to both consumers.
I don't have a strong preference between having vscode-nushell-lang serve as the canonical source or creating a separate nushell-owned repository for the TextMate grammar. I think the latter may be cleaner because it would make the grammar independent of any particular editor.
The current divergence is a concrete example of the problem, so I thought it would be worth discussing whether consolidating these grammars would make sense.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Compare the TextMate grammar maintained in vscode-nushell-lang with hustcer/nu-grammar and the grammar used by GitHub Linguist, starting with the reported mut t = [[a b]; [1 2]] example. Done means agreeing on a canonical grammar source and a concrete way for both the VS Code extension and Linguist to consume it.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- vscode
- Domain
- developer-experience, tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100