doc: add doc for FixConfig

part of ast-grep/ast-grep#656

website/.vitepress/config.ts

@@ -99,6 +99,7 @@ export default defineConfig({
           { text: 'Project Config', link: '/reference/sgconfig.html' },
           { text: 'Rule Config', link: '/reference/yaml.html', collapsed: true,
             items: [
+              { text: 'fix', link: '/reference/yaml/fix.html' },
               { text: 'transformation', link: '/reference/yaml/transformation.html' },
             ],
           },

website/reference/yaml.md

@@ -1,6 +1,10 @@
 # Configuration Reference
 
-An ast-grep rule is a YAML file with the following keys:
+ast-grep's rules are written in YAML files.
+
+One YAML file can contain multiple rules, separated by `---`.
+
+An ast-grep rule is a YAML object with the following keys:
 
 ## `id`
 
@@ -72,22 +76,24 @@ language: JavaScript
 * type: `Rule`
 * required: true
 
-The object specify the method to find matching AST nodes. See details in [rule object reference](/reference/rule).
+The object specify the method to find matching AST nodes. See details in [rule object reference](/reference/rule.html).
 
 ```yaml
 rule:
-  pattern: console.log($$$args)
+  pattern: console.log($$$ARGS)
 ```
 
 ## `fix`
 
-* type: `String`
+* type: `String` or `FixConfig`
 * required: false
 
-A pattern to auto fix the issue. It can reference meta variables appeared in the rule.
+A pattern or a `FixConfig` object to auto fix the issue. See details in [fix object reference](/reference/yaml/fix.html).
+
+It can reference meta variables appeared in the rule.
 
 ```yaml
-fix: logger.log($$$args)
+fix: logger.log($$$ARGS)
 
 # you can also use empty string to delete match
 fix: ""

website/reference/yaml/fix.md

@@ -0,0 +1,70 @@
+# Fix
+
+ast-grep has two kinds of fixes: `string` and `FixConfig`.
+
+## String Fix
+
+* type: `String`
+
+A string fix is a string that will be used to replace the matched AST node.
+
+You can use meta variables in the string fix to reference the matched AST node.
+
+N.B. Fix string is not parsed by tree-sitter. So meta variables can appear anywhere in the string.
+
+Example:
+
+```yaml
+rule:
+  pattern: console.log($$$ARGS)
+fix: logger.log($$$ARGS)
+```
+
+## `FixConfig`
+
+* type: `Object`
+
+A `FixConfig` is an advanced object configuration that specifies how to fix the matched AST node.
+
+ast-grep rule can only fix one target node at one time by replacing the target node text with a new string.
+This works fine for function statement/calls but it has always been problematic for list-item like items in an array, key-value pairs in a dictionary. We cannot delete an item completely because we also need to delete the surrounding comma.
+
+`FixConfig` is designed to solve this problem. It allows you to specify a template string and two additional rules to expand the matched AST node to the start and end of the matched AST node.
+
+
+It has the following fields:
+
+### `template`
+
+* type: `String`
+
+This is the same as the string fix.
+
+### `expandStart`
+* type: `Rule`
+
+A rule object, which is a rule object with one additional field `stopBy`.
+
+The fixing range's start will be expanded until the rule is not met.
+
+### `expandEnd`
+
+* type: `Rule`
+
+A rule object, which is a rule object with one additional field `stopBy`.
+
+The fixing range' end start will be expanded until the rule is not met.
+
+Example:
+
+```yaml
+rule:
+  kind: pair
+  has:
+    field: key
+    regex: Remove
+# remove the key-value pair and its comma
+fix:
+  template: ''
+  expandEnd: { regex: ',' } # expand the range to the comma
+```