Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/getgrit/gritql
GritQL is a query language for searching, linting, and modifying code.
https://github.com/getgrit/gritql
ast codemod javascript linter refactoring rust search tree-sitter
Last synced: 3 days ago
JSON representation
GritQL is a query language for searching, linting, and modifying code.
- Host: GitHub
- URL: https://github.com/getgrit/gritql
- Owner: getgrit
- License: mit
- Created: 2024-03-08T23:18:51.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2024-10-26T22:48:26.000Z (about 2 months ago)
- Last Synced: 2024-10-29T10:45:26.515Z (about 1 month ago)
- Topics: ast, codemod, javascript, linter, refactoring, rust, search, tree-sitter
- Language: Rust
- Homepage: https://docs.grit.io/
- Size: 47.3 MB
- Stars: 3,104
- Watchers: 8
- Forks: 74
- Open Issues: 104
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
- my-awesome-list - gritql
- jimsghstars - getgrit/gritql - GritQL is a query language for searching, linting, and modifying code. (Rust)
README
[](https://github.com/getgrit/gritql/actions/workflows/main.yaml)
[](https://github.com/getgrit/gritql/blob/main/LICENSE)
[](https://docs.grit.io/discord)
[Playground](https://app.grit.io/studio) |
[Tutorial](https://docs.grit.io/tutorials/gritql) |
[Docs](https://docs.grit.io/language)
GritQL is a declarative query language for searching and modifying source code.
- đź“– Start simply without learning AST details: any code snippet is a valid GritQL query
- ⚡️ Use Rust and query optimization to scale up to 10M+ line repositories
- 📦 Use Grit's built-in module system to reuse 200+ [standard patterns](https://github.com/getgrit/stdlib) or [share your own](https://docs.grit.io/guides/sharing#anchor-publishing-patterns)
- ♻️ Once you learn GritQL, you can use it to rewrite any [target language](https://docs.grit.io/language/target-languages): JavaScript/TypeScript, Python, JSON, Java, Terraform, Solidity, CSS, Markdown, YAML, Rust, Go, or SQL
- 🔧 GritQL makes it easy to include auto-fix rules for faster remediation
## Getting started
Read the [documentation](https://docs.grit.io/language/overview), [interactive tutorial](https://docs.grit.io/tutorials/gritql), or run `grit --help`.
### Installation
Install the Grit CLI:
```
curl -fsSL https://docs.grit.io/install | bash
```
### Usage
Search for all your `console.log` calls by putting the desired pattern in backticks:
```
grit apply '`console.log($_)`'
```
Replace `console.log` with `winston.log`, using `=>` to create rewrites:
```
grit apply '`console.log($msg)` => `winston.log($msg)`'
```
Save the pattern to a [`grit.yaml`](https://docs.grit.io/guides/config) file and exclude test cases in a where clause:
```
cat << 'EOF' > .grit/grit.yaml
patterns:
- name: use_winston
level: error
body: |
`console.log($msg)` => `winston.log($msg)` where {
$msg <: not within or { `it($_, $_)`, `test($_, $_)`, `describe($_, $_)` }
}
EOF
grit apply use_winston
```
Run `grit check` to enforce your patterns as [custom lints](https://docs.grit.io/guides/ci).
```
grit check
```
## Examples
### Remove all `console.log` calls, unless they are inside a try-catch block
```grit
`console.log($log)` => . where {
$log <: not within `try { $_ } catch { $_ }`
}
```
### Replace a method call with a new method call
```grit
`$instance.oldMethod($args)` => `$instance.newMethod($args)` where {
$program <: contains `$instance = new TargetClass($_)`
}
```
### More examples
Many more examples can be found in the [GritQL standard library](https://github.com/getgrit/stdlib/blob/main/.grit/patterns/).
Patterns can be combined to create complex queries, including [large refactors](https://github.com/getgrit/stdlib/blob/main/.grit/patterns/python/openai.md).
## Why GritQL?
GritQL comes from our experiences with conducting large scale refactors and migrations.
Usually, migrations start with exploratory work to figure out the scope of the problem—often using simple grep searches. These are easy to start with, but most migrations end up accumulating additional requirements like ensuring the right packages are imported and excluding cases which don’t have a viable migration path.
Eventually, any complex migration ends up being a full codemod program written with a tool like [jscodeshift](https://github.com/facebook/jscodeshift). This comes with its own problems:
- Most of the exploratory work has to be abandoned as you figure out how to represent your original regex search as an AST.
- Reading/writing a codemod requires mentally translating from AST names back to what source code actually looks like.
- Most frameworks are not composable, so you’re stuck copying patterns back and forth.
- Performance is often an afterthought, so iterating on a large codemod can be painfully slow.
- Codemod frameworks are language-specific, so if you’re hopping between multiple languages—or trying to migrate a shared API—you have to learn different frameworks.
GritQL is our attempt to develop a powerful middle ground:
- Exploratory analysis is easy: just put a code snippet in backticks and use `$metavariables` for holes you want to represent.
- Incrementally add complexity by introducing side conditions with where clauses.
- Reuse named patterns to avoid rebuilding queries, and use shared patterns from our [standard library](https://github.com/getgrit/stdlib) for common tasks like ensuring modules are imported.
- Written in Rust for maximum performance: rewrite millions of lines of code in seconds.
## Acknowledgements
GritQL uses [tree-sitter](https://github.com/tree-sitter/tree-sitter) for all language parsers and benefits greatly from the Rust ecosystem.
GritQL is released under the MIT license.
## Contributing
Contributions are welcome. To get started, check out the [**contributing guidelines**](./CONTRIBUTING.md).
You can also join us on [**Discord**](https://docs.grit.io/discord).