☂️ GritQL Formatter

[arendjr]

Description

This issue will act as the hub for tracking the GritQL formatter as it gets built out. Listed here are all of the different pieces that will need to be implemented to get "complete" support in place.

To see how this issue fits into our plugin efforts, please look at the overview here: https://github.com/biomejs/biome/issues/2463

How to Contribute

Everyone is welcome to contribute pieces here! Some of these may also be good first issues, so if you're looking for guidance, just reach out to us.

If you'd like to tackle something, please leave a comment below this issue for which item(s) of the checklist below you'd like to pick up. We will create a separate issue and assign it to you to simplify tracking.

[!NOTE] In order to have the issue assigned to you, you must comment on this issue.

Please only pick a single piece or group to work on at a time, and try to have time available to work on the piece when you select it so that we can keep progressing quickly. If you need any help or have any questions about our plugin efforts in Biome, feel free to ask in the #plugins channel in Discord.

Testing

Since GritQL is quite a new language, there is no reference formatter to base our efforts on. However, there is a Grit stdlib that has a wide variety of common patterns that can be used as reference. It's probably best if we start by taking some of their patterns and using them as "expected results" in our test suite. Then we can mangle the formatting and verify the formatter returns them as expected.

Formatting Infrastructure

Listed here are various things that are ready to be implemented or fixed that apply to the GritQL formatter in general.

• [ ] Configuration
  • We need to add GritQL as a language in the configuration format, and let it support the common options around indentation, line length and type of newlines.
• [ ] Add test suite
• [ ] Introduce a can_format_grit_yet flag into biome_service
• [ ] Comment placement
• [ ] Handle biome ignore: format suppression comments in appropriate places

GritQL node types

This is a guide that covers most of the nodes that need formatting rules:

• [ ] Patterns
  • [ ] before / after
  • [ ] any / some / every / and / or
  • [ ] bubble
  • [ ] contains / includes / within
  • [ ] if
  • [ ] like / where
  • [ ] assignments
  • [ ] rewrites
  • [ ] lists and maps
  • [ ] math operators
• [ ] Predicates
  • [ ] any / and / or
  • [ ] if
  • [ ] assignments
  • [ ] accumulators
  • [ ] match operator
  • [ ] rewrites
  • [ ] returns
• [ ] Function calls (node-likes)
• [ ] Code snippets

Releasability

These tasks need to be completed for the GritQL formatter to be "publicly available" with parity with the JS formatter:

• [ ] Support GritQL files in the playground
• [ ] Support GritQL configuration options in the playground

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• We receive the funding once the issue is completed & confirmed by you.
• Thank you in advance for helping prioritize & fund our backlog.

[abidjappie]

I'd like to help out with GritQL, it looks interesting!

Is there any recommended starting point? otherwise, I'm interested in Function calls if I can get some guidance to build it 🙇

[ematipico]

Thank you @abidjappie

The first thing to do is to create the crate biome_gritql_formatter and run the code gen. There's a contribution guide that you can reach from the mean contribution.md document.

[arendjr]

@abidjappie Thanks! If you prefer, I can also set up the basic infrastructure in a PR first so you can focus on a more specific part of the formatter. Just let me know what you prefer!

[abidjappie]

I don't mind having a look at the basic infrastructure sometime this weekend. I don't want to delay the development of this feature, so if it's okay that I can have it ready within a day or two I can take it! 🙇 As the @arendjr mentioned, we want to keep this one progressing quickly!

[ematipico]

There's no pressure here!

[arendjr]

Indeed, don’t worry about delays. My offer for setting up the infra was intended more for your convenience, than quick progress. I don’t have much time on my hands to work on this feature, but happy to help anyone who does!

[abidjappie]

I gave it a try, please have a look at https://github.com/biomejs/biome/pull/2837 and let me know if I'm on the right track.

[arendjr]

Great start, @abidjappie ! I'll assign this issue to you so it's yours to finish at your own pace. Just keep in mind Polar.sh enforces a 6 month limit on the bounties, but otherwise there's no rush.

[yossydev]

hi, is this issue going ahead now? 👀

[arendjr]

Good question! After the initial infrastructure it went silent. @abidjappie are you still interested in continuing this work?

[branberry]

Hi! I'd be interested in contributing to this as well.

[arendjr]

@branberry I’d say contributions are welcome regardless! So if you’re happy to chip in, feel free to send PRs!

As for the bounty, it looks like it was opened 5 months ago and if I’m not mistaken Polar.sh has a 6 month expiry, so I think it expires in a month. I think it’s good to check with @morgante to check if he’s willing to renew, so you’d still be eligible even if it takes a bit longer.

That said, it’s currently assigned to @abidjappie so if they want to finish it within the remaining month it’s only fair they remain eligible (this is also in accordance with our governance rules).

[branberry]

Thanks for the reply! As for the bounty, I'm not concerned with that at all. I'm looking to poke around a bit to learn more about Biome and the codebase, so I'll be on a very slow timeline haha!

Is the expectation to have each checkbox in the original post completed by a single individual for the bounty? I was thinking of possibly grabbing one or two as a way to dip my toes in the codebase a bit.

[ematipico]

I'd say to unassign @abidjappie, and assign the issue to @branberry.

It's been months without tangible progresses, so let's go ahead, and see if @morgante wants to renew the bounty

[ematipico]

Is the expectation to have each checkbox in the original post completed by a single individual for the bounty? I was thinking of possibly grabbing one or two as a way to dip my toes in the codebase a bit.

No, a bounty can be split among multiple contributors

[morgante]

I probably won't renew the bounty, mostly because it didn't seem to incentivize much progress and it's no longer a high priority for me.

I'd still love to see this implemented.

[abidjappie]

Sorry for the slow response, I've been incredibly busy recently.

I'm happy to have it handed over to @branberry, and hopefully when I have capacity I can help out again. I recently introduced GritQL to my team's project so I feel a bit more familiar with it's syntax!