From 58731af10a45cc3446c9b5512e17e0a0a71b96cb Mon Sep 17 00:00:00 2001 From: petrisorcoderabbit Date: Wed, 13 Mar 2024 20:01:12 +0200 Subject: [PATCH 1/3] Move ast-grep documentation under the prompt-customization page --- docs/guides/prompt-customization.md | 264 ++++++++++++++++++++++++++ docs/integrations/ast-grep.md | 279 ---------------------------- sidebars.ts | 2 +- 3 files changed, 265 insertions(+), 280 deletions(-) delete mode 100644 docs/integrations/ast-grep.md diff --git a/docs/guides/prompt-customization.md b/docs/guides/prompt-customization.md index c4ff3fff..8c2f467a 100644 --- a/docs/guides/prompt-customization.md +++ b/docs/guides/prompt-customization.md @@ -48,3 +48,267 @@ Descriptive test names are used to clearly convey the intent of each test. - Test the review feedback on pull requests and tailor as necessary. ::: + +## Abstract Syntax Tree (AST) instructions + +:::note +**Deep dive into AST patterns and AST-Grep rules** + - AST patterns [wikipedia](https://en.wikipedia.org/wiki/Abstract_syntax_tree) + - AST-grep [official documentation](https://ast-grep.github.io/guide/rule-config.html) for detailed guides. +::: + +This section explains how to add custom code review instructions using AST-Grep rules. AST-Grep is a tool used for searching code using abstract syntax trees (AST) patterns. + +By default, you can add AST-Grep rules by following these steps: +1. Create a folder that keeps all the ast-grep rules in your project directory. +2. Add individual `.yaml` files for each AST-Grep rule within the newly created folder. +3. Ensure that each `.yaml` file contains the necessary AST-Grep rule configurations. +4. Ensure that all rules contains a `message` property, that will be used in the review process. +5. Add the rules folder to the `.coderabbit.yml` file under `tools.ast-grep` configuration. + +```yaml +#... +reviews: + #... + tools: + ast-grep: + rules_folder: "custom-name" + #... +``` + +### The rule object + +Rule object is the core concept of ast-grep's rule system and every other features are built on top of it. + +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. +```yaml +rule: + # atomic rule + pattern: 'search.pattern' + kind: 'tree_sitter_node_kind' + regex: 'rust|regex' + # relational rule + inside: { pattern: 'sub.rule' } + has: { kind: 'sub_rule' } + follows: { regex: 'can|use|any' } + precedes: { kind: 'multi_keys', pattern: 'in.sub' } + # composite rule + all: [ {pattern: 'match.all'}, {kind: 'match_all'} ] + any: [ {pattern: 'match.any'}, {kind: 'match_any'} ] + not: { pattern: 'not.this' } + matches: 'utility-rule' +``` + +### Three Rule Categories +To summarize the rule object fields above, we have three categories of rules: + +- **Atomic Rule:** the most basic rule that checks if AST nodes matches. +- **Relational Rule:** rules that check if a node is surrounded by another node. +- **Composite Rule:** rules that combine sub-rules together using logical operators. + +These three categories of rules can be composed together to create more complex rules. + +The rule object is inspired by the CSS selectors but with more composability and expressiveness. +Thinking about how selectors in CSS works can help you understand the rule object! + +> Read ast-grep [documentation](https://ast-grep.github.io/guide/rule-config.html) for detailed guides. + +#### Atomic rule +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`. + +> Official documentation guide on [Atomic Rule](https://ast-grep.github.io/guide/rule-config/atomic-rule.html) + +#### Relational rule +Relational rule defines the relationship between two syntax nodes. There are four kinds of relational rule: `inside`, `has`, `follows` and `precedes`. + +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. + +> Official documentation guide on [Relational Rule](https://ast-grep.github.io/guide/rule-config/relational-rule.html) + +```yaml +rule: + pattern: await $PROMISE + inside: + kind: for_in_statement + stopBy: end +``` + +#### Composite rule +Composite rule defines the logical relationship between multiple sub-rules. There are three kinds of composite rule: `all`, `any` and `not`. + +**all** + +The `all` rule matches if all sub-rules match. +```yaml +rule: + all: + - pattern: console.log('Hello World'); + - kind: expression_statement +``` + +**any** + +`any` rule matches if any sub-rule matches. +```yaml +rule: + any: + - pattern: var a = $A + - pattern: const a = $A + - pattern: let a = $A +``` + +**not** + +`not` applies negation to a sub-rule. It matches if the sub-rule does not match. + +```yaml +rule: + pattern: console.log($GREETING) + not: + pattern: console.log('Hello World') +``` + +> Official documentation guide on [Composite Rule](https://ast-grep.github.io/guide/rule-config/composite-rule.html) + + +### Reusing rule as utility +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. + +#### Local utility rule +Local utility rules are defined in the utils field of the config file. utils is a string-keyed dictionary. + +For example, the following config file defines a local utility rule `is-literal`: + +```yaml +utils: + is-literal: + any: + - kind: string + - kind: number + - kind: boolean +rule: + matches: is-literal +``` + +#### Global utility rule +Global utility rules are defined in a separate file. But they are available across all rule configurations in the project. + +To create global utility rules, you need to have the `rules` folder created on the root of your project and another +`utils` directory inside the root of your project. + +```yaml +my-awesome-project # project root + |- rules # rule directory + | |- my-rule.yml + |- utils # utils directory + | |- is-literal.yml +``` + +>Also, you need to add the `rules` and `utils` folders to the `.coderabbit.yml` file under `tools.ast-grep` configuration. + +```yaml +#... +reviews: + #... + tools: + ast-grep: + rules_folder: "rules" + utils_folder: "utils" + #... +``` + +```yaml +# is-literal.yml +id: is-literal +language: TypeScript +rule: + any: + - kind: 'false' + - kind: undefined + - kind: 'null' + - kind: 'true' + - kind: regex + - kind: number + - kind: string +``` + +> Official documentation guide on [Utility Rule](https://ast-grep.github.io/guide/rule-config/utility-rule.html) + +### Multiple Languages Support + +CodeRabbit supports multiple programming languages for defining AST-Grep rules. + +- JavaScript +- Typescript +- C# +- Golang +- Java +- Kotlin +- Rust +- Python +- C + +Below are examples of AST-Grep rules in different languages: + +#### JavaScript +**Importing files without an extension is not allowed** +```yaml +id: find-import-file +language: js +message: "Importing files without an extension is not allowed" +rule: + regex: "/[^.]+[^/]$" + kind: string_fragment + any: + - inside: + stopBy: end + kind: import_statement + - inside: + stopBy: end + kind: call_expression + has: + field: function + regex: "^import$" +``` + +**No console.log allowed except console.error on the catch block** +```yaml +id: no-console-except-error +language: typescript +message: "No console.log allowed except console.error on the catch block" +rule: + any: + - pattern: console.error($$$) + not: + inside: + kind: catch_clause + stopBy: end + - pattern: console.$METHOD($$$) +constraints: + METHOD: + regex: 'log|debug|warn' +``` + +#### C +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. + +However, this style can have some drawbacks, such as: +- extra memory allocation and reallocation for the struct and the function pointer. +- indirection overhead when calling the function pointer. + +A possible alternative is to use a plain function call with the struct pointer as the first argument. + +```yaml +id: method_receiver +language: c +rule: + pattern: $R.$METHOD($$$ARGS) +transform: + MAYBE_COMMA: + replace: + source: $$$ARGS + replace: '^.+' + by: ', ' +fix: + $METHOD(&$R$MAYBE_COMMA$$$ARGS) +``` diff --git a/docs/integrations/ast-grep.md b/docs/integrations/ast-grep.md deleted file mode 100644 index 51c23ad7..00000000 --- a/docs/integrations/ast-grep.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -title: Ast-Grep rules in CodeRabbit -description: Integrate Ast-Grep rules with CodeRabbit -sidebar_label: Ast-Grep -image: "/preview_meta.jpg" ---- - - - - - - - - - - - - - - - - - - -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. - -### **Setting up AST-Grep rules** -By default, users can add AST-Grep rules by following these steps: - -1. Create a folder that keeps all the `custom-name` in your project directory. -2. Add individual `.yaml` files for each AST-Grep rule within the `custom-name` folder. -3. Ensure each `.yaml` file contains the necessary AST-Grep rule configurations. -4. Ensure that all rules contains a `message` property, that will be used in the review process. -5. Add the `custom-name` folder to the `.code-rabbit.yml` file under `tools.ast-grep` configuration. -```yaml -#... -reviews: - #... - tools: - ast-grep: - rules_folder: "custom-name" - #... -``` - -### **The rule object** - -Rule object is the core concept of ast-grep's rule system and every other features are built on top of it. - -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. -```yaml -rule: - # atomic rule - pattern: 'search.pattern' - kind: 'tree_sitter_node_kind' - regex: 'rust|regex' - # relational rule - inside: { pattern: 'sub.rule' } - has: { kind: 'sub_rule' } - follows: { regex: 'can|use|any' } - precedes: { kind: 'multi_keys', pattern: 'in.sub' } - # composite rule - all: [ {pattern: 'match.all'}, {kind: 'match_all'} ] - any: [ {pattern: 'match.any'}, {kind: 'match_any'} ] - not: { pattern: 'not.this' } - matches: 'utility-rule' -``` - -### **Three Rule Categories** -To summarize the rule object fields above, we have three categories of rules: - -- Atomic Rule: the most basic rule that checks if AST nodes matches. -- Relational Rule: rules that check if a node is surrounded by another node. -- Composite Rule: rules that combine sub-rules together using logical operators. - -These three categories of rules can be composed together to create more complex rules. - -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! - -> Read ast-grep [documentation](https://ast-grep.github.io/guide/rule-config.html) for detailed guides. - -#### **Atomic rule** -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`. - -> Official documentation guide on [Atomic Rule](https://ast-grep.github.io/guide/rule-config/atomic-rule.html) - -#### **Relational rule** -Relational rule defines the relationship between two syntax nodes. There are four kinds of relational rule: `inside`, `has`, `follows` and `precedes`. - -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. - -> Official documentation guide on [Relational Rule](https://ast-grep.github.io/guide/rule-config/relational-rule.html) - -```yaml -rule: - pattern: await $PROMISE - inside: - kind: for_in_statement - stopBy: end -``` - -#### **Composite rule** -Composite rule defines the logical relationship between multiple sub-rules. There are three kinds of composite rule: `all`, `any` and `not`. - -**all** - -The `all` rule matches if all sub-rules match. -```yaml -rule: - all: - - pattern: console.log('Hello World'); - - kind: expression_statement -``` - -**any** - -`any` rule matches if any sub-rule matches. -```yaml -rule: - any: - - pattern: var a = $A - - pattern: const a = $A - - pattern: let a = $A -``` - -**not** - -`not` applies negation to a sub-rule. It matches if the sub-rule does not match. - -```yaml -rule: - pattern: console.log($GREETING) - not: - pattern: console.log('Hello World') -``` - -> Official documentation guide on [Composite Rule](https://ast-grep.github.io/guide/rule-config/composite-rule.html) - - -## Reusing rule as utility -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. - -#### **Local utility rule** -Local utility rules are defined in the utils field of the config file. utils is a string-keyed dictionary. - -For example, the following config file defines a local utility rule `is-literal`: - -```yaml -utils: - is-literal: - any: - - kind: string - - kind: number - - kind: boolean -rule: - matches: is-literal -``` - -#### **Global utility rule** -Global utility rules are defined in a separate file. But they are available across all rule configurations in the project. - -To create global utility rules, you need to have the `rules` folder created on the root of your project and another -`utils` directory inside the root of your project. - -```yaml -my-awesome-project # project root - |- rules # rule directory - | |- my-rule.yml - |- utils # utils directory - | |- is-literal.yml -``` - ->Also, you need to add the `rules` and `utils` folders to the `.code-rabbit.yml` file under `tools.ast-grep` configuration. - -```yaml -#... -reviews: - #... - tools: - ast-grep: - rules_folder: "rules" - utils_folder: "utils" - #... -``` - -```yaml -# is-literal.yml -id: is-literal -language: TypeScript -rule: - any: - - kind: 'false' - - kind: undefined - - kind: 'null' - - kind: 'true' - - kind: regex - - kind: number - - kind: string -``` - -> Official documentation guide on [Utility Rule](https://ast-grep.github.io/guide/rule-config/utility-rule.html) - -## Multiple Languages Support - -CodeRabbit supports multiple programming languages for defining AST-Grep rules. - -- JavaScript -- Typescript -- C# -- Golang -- Java -- Kotlin -- Rust -- Python -- C - -Below are examples of AST-Grep rules in different languages: - -### **JavaScript** -#### Importing files without an extension is not allowed -```yaml -id: find-import-file -language: js -message: "Importing files without an extension is not allowed" -rule: - regex: "/[^.]+[^/]$" - kind: string_fragment - any: - - inside: - stopBy: end - kind: import_statement - - inside: - stopBy: end - kind: call_expression - has: - field: function - regex: "^import$" -``` - -#### No console.log allowed except console.error on the catch block -```yaml -id: no-console-except-error -language: typescript -message: "No console.log allowed except console.error on the catch block" -rule: - any: - - pattern: console.error($$$) - not: - inside: - kind: catch_clause - stopBy: end - - pattern: console.$METHOD($$$) -constraints: - METHOD: - regex: 'log|debug|warn' -``` - -### **C** -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. - -However, this style can have some drawbacks, such as: -- extra memory allocation and reallocation for the struct and the function pointer. -- indirection overhead when calling the function pointer. - -A possible alternative is to use a plain function call with the struct pointer as the first argument. - -```yaml -id: method_receiver -language: c -rule: - pattern: $R.$METHOD($$$ARGS) -transform: - MAYBE_COMMA: - replace: - source: $$$ARGS - replace: '^.+' - by: ', ' -fix: - $METHOD(&$R$MAYBE_COMMA$$$ARGS) -``` diff --git a/sidebars.ts b/sidebars.ts index 7599ed7b..3d051844 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -40,7 +40,7 @@ const sidebars: SidebarsConfig = { { type: "category", label: "Integrations", - items: ["integrations/self-hosted-gitlab", "integrations/ast-grep"], + items: ["integrations/self-hosted-gitlab"], }, "faq/faq", ], From e1f7366450dc68b17c667ff0d9059b01ff9f48ea Mon Sep 17 00:00:00 2001 From: petrisorcoderabbit Date: Wed, 13 Mar 2024 22:18:25 +0200 Subject: [PATCH 2/3] Change ast-grep naming --- docs/guides/prompt-customization.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/guides/prompt-customization.md b/docs/guides/prompt-customization.md index 8c2f467a..728c908c 100644 --- a/docs/guides/prompt-customization.md +++ b/docs/guides/prompt-customization.md @@ -52,17 +52,17 @@ Descriptive test names are used to clearly convey the intent of each test. ## Abstract Syntax Tree (AST) instructions :::note -**Deep dive into AST patterns and AST-Grep rules** +**Deep dive into AST patterns and ast-grep rules** - AST patterns [wikipedia](https://en.wikipedia.org/wiki/Abstract_syntax_tree) - - AST-grep [official documentation](https://ast-grep.github.io/guide/rule-config.html) for detailed guides. + - ast-grep [official documentation](https://ast-grep.github.io/guide/rule-config.html) for detailed guides. ::: -This section explains how to add custom code review instructions using AST-Grep rules. AST-Grep is a tool used for searching code using abstract syntax trees (AST) patterns. +This section explains how to add custom code review instructions using ast-grep rules. ast-grep is a tool used for searching code using abstract syntax trees (AST) patterns. -By default, you can add AST-Grep rules by following these steps: +By default, you can add ast-grep rules by following these steps: 1. Create a folder that keeps all the ast-grep rules in your project directory. -2. Add individual `.yaml` files for each AST-Grep rule within the newly created folder. -3. Ensure that each `.yaml` file contains the necessary AST-Grep rule configurations. +2. Add individual `.yaml` files for each ast-grep rule within the newly created folder. +3. Ensure that each `.yaml` file contains the necessary ast-grep rule configurations. 4. Ensure that all rules contains a `message` property, that will be used in the review process. 5. Add the rules folder to the `.coderabbit.yml` file under `tools.ast-grep` configuration. @@ -236,7 +236,7 @@ rule: ### Multiple Languages Support -CodeRabbit supports multiple programming languages for defining AST-Grep rules. +CodeRabbit supports multiple programming languages for defining ast-grep rules. - JavaScript - Typescript @@ -248,7 +248,7 @@ CodeRabbit supports multiple programming languages for defining AST-Grep rules. - Python - C -Below are examples of AST-Grep rules in different languages: +Below are examples of ast-grep rules in different languages: #### JavaScript **Importing files without an extension is not allowed** From e1e9e85ec7f81bc1e899d71a77d39bec10c3a8c0 Mon Sep 17 00:00:00 2001 From: petrisorcoderabbit Date: Wed, 13 Mar 2024 22:27:37 +0200 Subject: [PATCH 3/3] Correct grammar for ast-grep documentation --- docs/guides/prompt-customization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/prompt-customization.md b/docs/guides/prompt-customization.md index 728c908c..db1db8aa 100644 --- a/docs/guides/prompt-customization.md +++ b/docs/guides/prompt-customization.md @@ -78,7 +78,7 @@ reviews: ### The rule object -Rule object is the core concept of ast-grep's rule system and every other features are built on top of it. +Rule object is the core concept of ast-grep's rule system and every other feature is built on top of it. 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. ```yaml