The guide explains how to add custom review instructions for the entire project.Also, see the guide on how toconfigure CodeRabbit.

Path-based instructions​

This section explains how to add custom code review instructions for the entireproject or specific file paths in your project using glob patterns. Developerscan provide tailored review guidelines based on the file paths. Theseinstructions are needed only if you want CodeRabbit to follow specificinstructions besides the standard review.

For example, you may want to enforce a style guide by file types or directories.

Sample Usage​

#...
reviews:
#...
path_instructions:
-path:"**/*.js"
instructions:|
        Review the JavaScript code against the Google JavaScript style guide and point out any mismatches
-path:"tests/**.*"
instructions:|
        Review the following unit test code written using the Mocha test library. Ensure that:
        - The code adheres to best practices associated with Mocha.
        - Descriptive test names are used to clearly convey the intent of each test.

Abstract Syntax Tree (AST) based instructions​

CodeRabbit offers review instructions based on Abstract Syntax Tree (AST)patterns. Under the hood, CodeRabbit usesast-grep to power this feature.ast-grep iswritten in Rust and uses the tree-sitter parser to generate the AST for popularlanguages.ast-grep is written and maintained byHerrington Darkholme.

This section explains how to add custom code review instructions usingast-grep rules.ast-grep is a tool used for searching code using abstractsyntax trees (AST) patterns.

By default, you can addast-grep rules by following these steps:

1. Create a directory that keeps all theast-grep rules in your projectdirectory.
2. Add individual.yaml files for eachast-grep rule within the newlycreated directory.
3. Ensure that each.yaml file contains the necessaryast-grep ruleconfigurations.
4. Ensure that all rules contains amessage property, that will be used in thereview process.
5. Add the rules' directory to the.coderabbit.yml file undertools.ast-grepconfiguration.
6. Optionally, you can addpackages property to the configuration to specifythe packages that should be installed before running theast-grep tool.Please read thepackages section for detailed information.

#...
reviews:
#...
tools:
ast-grep:
essential_rules:true# option to enable essential security rules
rule_dirs:
-"custom-name"
packages:
-"myorg/myawesomepackage"# custom package name following the format organization/repository
#...

The rule object​

Rule object is the core concept ofast-grep rule system and every otherfeature is built on top of it.

Below is the full list of fields in a rule object. Every rule field is optionaland can be omitted, but at least one field should be present in a rule. A nodewill match a rule if and only if it satisfies all fields in the rule object.

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"

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

These three categories of rules can be composed together to create more complexrules.

The rule object is inspired by the CSS selectors but with more composability andexpressiveness. Thinking about how selectors in CSS works can help youunderstand the rule object!

Readast-grep >documentation fordetailed guides.

Atomic rule​

Atomic rule defines the most basic matching rule that determines whether onesyntax node matches the rule or not. There are three kinds of atomic rule:pattern,kind andregex.

Official documentation guide onAtomic Rule

Relational rule​

A relational rule defines the relationship between two syntax nodes. There arefour kinds of relational rule:inside,has,follows andprecedes.

All four relational rules accept a sub-rule object as their value. The sub-rulewill match the surrounding node, while the relational rule itself will match thetarget node.

Official documentation guide onRelational Rule

rule:
pattern: await $PROMISE
inside:
kind: for_in_statement
stopBy: end

Composite rule​

A composite rule defines the logical relationship between multiple sub-rules.There are three kinds of composite rule:all,any andnot.

all

Theall rule matches if all sub-rules match.

rule:
all:
-pattern: console.log('Hello World');
-kind: expression_statement

any

any rule matches if any sub-rule matches.

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.

rule:
pattern: console.log($GREETING)
not:
pattern: console.log('Hello World')

Official documentation guide onComposite Rule

Reusing rule as utility​

ast-grep chooses to use YAML for rule representation. While this decisionmakes writing rules easier, it does impose some limitations on the ruleauthoring. 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 isa string-keyed dictionary.

For example, the following config file defines a local utility ruleis-literal:

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 availableacross all rule configurations in the project.

To create global utility rules, you need to have therules directory createdon the root of your project and anotherutils directory inside the root ofyour project.

my-awesome-project# project root
|- rules# rule directory
||- my-rule.yml
|- utils# utils directory
||- is-literal.yml

Also, you need to add therules andutils directories to the.coderabbit.yml file undertools.ast-grep configuration. The rules canalso be inside a package. If you have a package that contains rules, you canadd the package name to thepackages field in the.coderabbit.yml file.

#...
reviews:
#...
tools:
ast-grep:
essential_rules:true
rule_dirs:
-"rules"
util_dirs:
-"utils"
packages:
-"my-awesome-org/my-awesome-package"# public repository that contains ast-grep rules
#...

# 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 onUtility Rule

Packages​

A package is what allows you to share rules across multiple projects.Essentially, a package is a collection ofast-grep rules.

CodeRabbit provides a set of packages that you can use out of the box. You canalso create your own packages and share them with the community or just use themwithin your organization.

Packages provided by CodeRabbit are:

• ast-grep-essentials: A set of essential security rules. Because we valuesecurity, this package gets its own property in the.coderabbit.yml file, tomake it easier to install and not overwrite. Check thepackage repository formore information.

To use a package, you need to add the package name to thepackages field inthe.coderabbit.yml file.

#...
reviews:
#...
tools:
ast-grep:
essential_rules:true
packages:# list of packages to install, in future coderabbit will provide a set of packages, beside the essentials one.
-"my-awesome-org/my-awesome-package"# custom package name following the format organization/repository
#...

Using custom package​

Let's say that you have a public repository that containsast-grep rules. Youcan add the package name to thepackages field in the.coderabbit.yml file.

Requirements for a package:

• It should be a public repository

• It contains rules that follow theast-grep rule format

• It has the following folder structure:

  my-awesome-project   # project root
    |- rules           # rule directory
    | |- my-rule.yml
    |- utils           # utils directory
    | |- is-literal.yml
  

  rules andutils directories are keywords, and it should be the same.Inside each directory, the structure is up to you. You can also have any otherroot directories or files beside the two shown above.

• Name should be in the formatorganization/repository

#...
reviews:
#...
tools:
ast-grep:
packages:
-"my-awesome-org/my-awesome-package"
#...

Multiple Languages Support​

CodeRabbit supports multiple programming languages for definingast-greprules.

• JavaScript
• Typescript
• C#
• Golang
• Java
• Kotlin
• Rust
• Python
• C

Below are examples ofast-grep rules in different languages:

JavaScript​

Importing files without an extension is not allowed​

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 exceptconsole.error on the catch block​

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 someprogrammers 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 functionpointer.
• Indirection overhead when calling the function pointer.

A possible alternative is to use a plain function call with the struct pointeras the first argument.

id: method_receiver
language: c
rule:
pattern: $R.$METHOD($$$ARGS)
transform:
MAYBE_COMMA:
replace:
source: $$$ARGS
replace:"^.+"
by:", "
fix: $METHOD(&$R$MAYBE_COMMA$$$ARGS)