Skip to content

Commit 5d9de3f

Browse files
petrisorcoderabbitpetrisorcoderabbit
authored
Merge pull request #21 from coderabbitai/add_ast_grep_doc_page
Add ast-grep documentation page
2 parents 6d19be2 + 72c2da7 commit 5d9de3f

File tree

4 files changed

+304
-1
lines changed

4 files changed

+304
-1
lines changed

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Editors
2+
.idea
13
# Dependencies
24
/node_modules
35

‎docs/guides/customize-coderabbit.md

+22
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,10 @@ reviews:
6969
base_branches:
7070
- "develop"
7171
- "feat/.*"
72+
tools:
73+
ast-grep:
74+
rules_folder: "custom-rules-folder-name"
75+
utils_folder: "custom-utils-folder-name"
7276
chat:
7377
auto_reply: true
7478
```
@@ -112,6 +116,12 @@ YAML settings:
112116
`true`).
113117
- **base_branches**: A list of base branches where the reviews will occur
114118
apart from the default branch. Accepts regex pattern.
119+
- **tools**: Configurations for the tools used in the review.
120+
- **ast-grep**: Configurations for the ast-grep tool.
121+
- **rules_folder**: The folder name where the custom ast-grep rules are
122+
stored.
123+
- **utils_folder**: The folder name where the custom ast-grep utils are
124+
stored.
115125
4. **chat**: Defines the behavior of CodeRabbit's bot in conversations.
116126
- **auto_reply**: The bot automatically replies without the need of the user
117127
tagging it ( default: `true` ).
@@ -156,6 +166,12 @@ settings:
156166
collapse_walkthrough_comment: true
157167
# Disable automatic code reviews for this repository.
158168
disable_review: false
169+
# External tools configurations
170+
tools:
171+
# tools configuration for ast-grep
172+
ast-grep:
173+
rules_folder: "custom-rules-folder-name"
174+
utils_folder: "custom-utils-folder-name"
159175
```
160176

161177
<!-- ![code](./images/ymlrabbit.png) -->
@@ -189,6 +205,12 @@ This configuration file consists of the following settings:
189205
be posted.
190206
13. **collapse_walkthrough_comment**: Specifies whether to collapse walkthrough
191207
comments on the review.
208+
14. **tools**: Configurations for the tools used in the review.
209+
- **ast-grep**: Configurations for the ast-grep tool.
210+
- **rules_folder**: The folder name where the custom ast-grep rules are
211+
stored.
212+
- **utils_folder**: The folder name where the custom ast-grep utils are
213+
stored.
192214

193215
Refer:
194216
[CodeRabbit configuration schema](https://coderabbit.ai/integrations/coderabbit-overrides.json).

‎docs/integrations/ast-grep.md

+279
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
---
2+
title: Ast-Grep rules in CodeRabbit
3+
description: Integrate Ast-Grep rules with CodeRabbit
4+
sidebar_label: Ast-Grep
5+
image: "/preview_meta.jpg"
6+
---
7+
8+
<head>
9+
<meta charSet="utf-8" />
10+
<meta name="title" content="CodeRabbit integration with ast-grep rules" />
11+
<meta name="description" content="Integrate ast-grep in CodeRabbit on your own repository" />
12+
13+
<meta property="og:type" content="website" />
14+
<meta property="og:url" content="https://coderabbit.ai/" />
15+
<meta property="og:title" content="CodeRabbit integration with ast-grep rules" />
16+
<meta property="og:description" content="CodeRabbit: AI-powered Code Reviews" />
17+
<meta property="og:image" content="/preview_meta.jpg" />
18+
19+
<meta name="twitter:image" content="https://coderabbit.ai/preview_meta.jpg" />
20+
<meta name="twitter:card" content="summary_large_image" />
21+
<meta name="twitter:title" content="CodeRabbit integration with ast-grep rules" />
22+
<meta name="twitter:description" content="CodeRabbit: AI-powered Code Reviews" />
23+
</head>
24+
25+
This documentation provides guidance on integrating AST-Grep rules within the CodeRabbit platform. AST-Grep is a tool used for searching code using abstract syntax trees (AST) patterns.
26+
27+
### **Setting up AST-Grep rules**
28+
By default, users can add AST-Grep rules by following these steps:
29+
30+
1. Create a folder that keeps all the `custom-name` in your project directory.
31+
2. Add individual `.yaml` files for each AST-Grep rule within the `custom-name` folder.
32+
3. Ensure each `.yaml` file contains the necessary AST-Grep rule configurations.
33+
4. Ensure that all rules contains a `message` property, that will be used in the review process.
34+
5. Add the `custom-name` folder to the `.code-rabbit.yml` file under `tools.ast-grep` configuration.
35+
```yaml
36+
#...
37+
reviews:
38+
#...
39+
tools:
40+
ast-grep:
41+
rules_folder: "custom-name"
42+
#...
43+
```
44+
45+
### **The rule object**
46+
47+
Rule object is the core concept of ast-grep's rule system and every other features are built on top of it.
48+
49+
Below is the full list of fields in a rule object. Every rule field is optional and can be omitted but at least one field should be present in a rule. A node will match a rule if and only if it satisfies all fields in the rule object.
50+
```yaml
51+
rule:
52+
# atomic rule
53+
pattern: 'search.pattern'
54+
kind: 'tree_sitter_node_kind'
55+
regex: 'rust|regex'
56+
# relational rule
57+
inside: { pattern: 'sub.rule' }
58+
has: { kind: 'sub_rule' }
59+
follows: { regex: 'can|use|any' }
60+
precedes: { kind: 'multi_keys', pattern: 'in.sub' }
61+
# composite rule
62+
all: [ {pattern: 'match.all'}, {kind: 'match_all'} ]
63+
any: [ {pattern: 'match.any'}, {kind: 'match_any'} ]
64+
not: { pattern: 'not.this' }
65+
matches: 'utility-rule'
66+
```
67+
68+
### **Three Rule Categories**
69+
To summarize the rule object fields above, we have three categories of rules:
70+
71+
- Atomic Rule: the most basic rule that checks if AST nodes matches.
72+
- Relational Rule: rules that check if a node is surrounded by another node.
73+
- Composite Rule: rules that combine sub-rules together using logical operators.
74+
75+
These three categories of rules can be composed together to create more complex rules.
76+
77+
The rule object is inspired by the CSS selectors but with more composability and expressiveness. Think about how selectors in CSS works can help you understand the rule object!
78+
79+
> Read ast-grep [documentation](https://ast-grep.github.io/guide/rule-config.html) for detailed guides.
80+
81+
#### **Atomic rule**
82+
Atomic rule defines the most basic matching rule that determines whether one syntax node matches the rule or not. There are three kinds of atomic rule: `pattern`, `kind` and `regex`.
83+
84+
> Official documentation guide on [Atomic Rule](https://ast-grep.github.io/guide/rule-config/atomic-rule.html)
85+
86+
#### **Relational rule**
87+
Relational rule defines the relationship between two syntax nodes. There are four kinds of relational rule: `inside`, `has`, `follows` and `precedes`.
88+
89+
All four relational rules accept a sub-rule object as their value. The sub-rule will match the surrounding node while the relational rule itself will match the target node.
90+
91+
> Official documentation guide on [Relational Rule](https://ast-grep.github.io/guide/rule-config/relational-rule.html)
92+
93+
```yaml
94+
rule:
95+
pattern: await $PROMISE
96+
inside:
97+
kind: for_in_statement
98+
stopBy: end
99+
```
100+
101+
#### **Composite rule**
102+
Composite rule defines the logical relationship between multiple sub-rules. There are three kinds of composite rule: `all`, `any` and `not`.
103+
104+
**all**
105+
106+
The `all` rule matches if all sub-rules match.
107+
```yaml
108+
rule:
109+
all:
110+
- pattern: console.log('Hello World');
111+
- kind: expression_statement
112+
```
113+
114+
**any**
115+
116+
`any` rule matches if any sub-rule matches.
117+
```yaml
118+
rule:
119+
any:
120+
- pattern: var a = $A
121+
- pattern: const a = $A
122+
- pattern: let a = $A
123+
```
124+
125+
**not**
126+
127+
`not` applies negation to a sub-rule. It matches if the sub-rule does not match.
128+
129+
```yaml
130+
rule:
131+
pattern: console.log($GREETING)
132+
not:
133+
pattern: console.log('Hello World')
134+
```
135+
136+
> Official documentation guide on [Composite Rule](https://ast-grep.github.io/guide/rule-config/composite-rule.html)
137+
138+
139+
## Reusing rule as utility
140+
ast-grep chooses to use YAML for rule representation. While this decision makes writing rules easier, it does impose some limitations on the rule authoring. One of the limitations is that rule objects cannot be reused.
141+
142+
#### **Local utility rule**
143+
Local utility rules are defined in the utils field of the config file. utils is a string-keyed dictionary.
144+
145+
For example, the following config file defines a local utility rule `is-literal`:
146+
147+
```yaml
148+
utils:
149+
is-literal:
150+
any:
151+
- kind: string
152+
- kind: number
153+
- kind: boolean
154+
rule:
155+
matches: is-literal
156+
```
157+
158+
#### **Global utility rule**
159+
Global utility rules are defined in a separate file. But they are available across all rule configurations in the project.
160+
161+
To create global utility rules, you need to have the `rules` folder created on the root of your project and another
162+
`utils` directory inside the root of your project.
163+
164+
```yaml
165+
my-awesome-project # project root
166+
|- rules # rule directory
167+
| |- my-rule.yml
168+
|- utils # utils directory
169+
| |- is-literal.yml
170+
```
171+
172+
>Also, you need to add the `rules` and `utils` folders to the `.code-rabbit.yml` file under `tools.ast-grep` configuration.
173+
174+
```yaml
175+
#...
176+
reviews:
177+
#...
178+
tools:
179+
ast-grep:
180+
rules_folder: "rules"
181+
utils_folder: "utils"
182+
#...
183+
```
184+
185+
```yaml
186+
# is-literal.yml
187+
id: is-literal
188+
language: TypeScript
189+
rule:
190+
any:
191+
- kind: 'false'
192+
- kind: undefined
193+
- kind: 'null'
194+
- kind: 'true'
195+
- kind: regex
196+
- kind: number
197+
- kind: string
198+
```
199+
200+
> Official documentation guide on [Utility Rule](https://ast-grep.github.io/guide/rule-config/utility-rule.html)
201+
202+
## Multiple Languages Support
203+
204+
CodeRabbit supports multiple programming languages for defining AST-Grep rules.
205+
206+
- JavaScript
207+
- Typescript
208+
- C#
209+
- Golang
210+
- Java
211+
- Kotlin
212+
- Rust
213+
- Python
214+
- C
215+
216+
Below are examples of AST-Grep rules in different languages:
217+
218+
### **JavaScript**
219+
#### Importing files without an extension is not allowed
220+
```yaml
221+
id: find-import-file
222+
language: js
223+
message: "Importing files without an extension is not allowed"
224+
rule:
225+
regex: "/[^.]+[^/]$"
226+
kind: string_fragment
227+
any:
228+
- inside:
229+
stopBy: end
230+
kind: import_statement
231+
- inside:
232+
stopBy: end
233+
kind: call_expression
234+
has:
235+
field: function
236+
regex: "^import$"
237+
```
238+
239+
#### No console.log allowed except console.error on the catch block
240+
```yaml
241+
id: no-console-except-error
242+
language: typescript
243+
message: "No console.log allowed except console.error on the catch block"
244+
rule:
245+
any:
246+
- pattern: console.error($$$)
247+
not:
248+
inside:
249+
kind: catch_clause
250+
stopBy: end
251+
- pattern: console.$METHOD($$$)
252+
constraints:
253+
METHOD:
254+
regex: 'log|debug|warn'
255+
```
256+
257+
### **C**
258+
In C, there is no built-in support for object-oriented programming, but some programmers use structs and function pointers to simulate classes and methods.
259+
260+
However, this style can have some drawbacks, such as:
261+
- extra memory allocation and reallocation for the struct and the function pointer.
262+
- indirection overhead when calling the function pointer.
263+
264+
A possible alternative is to use a plain function call with the struct pointer as the first argument.
265+
266+
```yaml
267+
id: method_receiver
268+
language: c
269+
rule:
270+
pattern: $R.$METHOD($$$ARGS)
271+
transform:
272+
MAYBE_COMMA:
273+
replace:
274+
source: $$$ARGS
275+
replace: '^.+'
276+
by: ', '
277+
fix:
278+
$METHOD(&$R$MAYBE_COMMA$$$ARGS)
279+
```

‎sidebars.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ const sidebars: SidebarsConfig = {
4040
{
4141
type: "category",
4242
label: "Integrations",
43-
items: ["integrations/self-hosted-gitlab"],
43+
items: ["integrations/self-hosted-gitlab", "integrations/ast-grep"],
4444
},
4545
"faq/faq",
4646
],

0 commit comments

Comments
 (0)