mparker3 / gritql

GritQL is a query language for searching, linting, and modifying code.

Playground | Tutorial | Docs

---

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 or share your own
• ♻️ Once you learn GritQL, you can use it to rewrite any target language: 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, interactive tutorial, 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 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.

grit check

Examples

Remove all console.log calls, unless they are inside a try-catch block

`console.log($log)` => . where {
  $log <: not within `try { $_ } catch { $_ }`
}

Replace a method call with a new method call

`$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.

Patterns can be combined to create complex queries, including large refactors.

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. 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 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 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.

You can also join us on Discord.