doc: add --include-metadata option

fix #742

Author: HerringtonDarkholme

website/reference/cli.md

@@ -62,6 +62,7 @@ ast-grep scan [OPTIONS] [PATHS]...
 | -r | --rule `<RULE_FILE>`| Scan the codebase with the single rule located at the path `RULE_FILE`.|
 |    | --inline-rules `<RULE_TEXT>` | Scan the codebase with a rule defined by the provided `RULE_TEXT` |
 |    | --filter `<REGEX>` |Scan the codebase with rules with ids matching `REGEX` |
+|    | --include-metadata | Include rule metadata in the json output |
 | -j | --threads `<NUM>`   | Set the approximate number of threads to use [default: heuristic]
 | -i | --interactive|Start interactive edit session.|
 | | --color `<WHEN>`|Controls output color [default: auto] [possible values: auto, always, ansi, never]|

website/reference/cli/scan.md

@@ -40,6 +40,12 @@ Scan the codebase with rules with ids matching REGEX.
 
 This flags conflicts with --rule. It is useful to scan with a subset of rules from a large set of rule definitions within a project.
 
+### `--include-metadata`
+
+Include rule [metadata](/reference/yaml.html#metadata) in the json output.
+
+This flags requires --json mode. Default is false.
+
 ## Input Options
 
 ### `--no-ignore <FILE_TYPE>`

website/reference/yaml.md

@@ -261,11 +261,15 @@ url: 'https://ast-grep.github.io/catalog/python/#migrate-openai-sdk'
 * type: `HashMap<String, String>`
 * required: false
 
-Extra information for the rule.
+Extra information for the rule. This section can include custom data for external program to consume. For example, CVE/OWASP information can be added here for security research.
+
+ast-grep will output `metadata` with matches in [`--json`](/reference/cli/scan.html#json-style) mode if [`--include-metadata`](/reference/cli/scan.html#include-metadata) is on.
 
 Example:
 
 ```yaml
 metadata:
   extraField: 'Extra information for other usages'
+  complexData:
+    key: value
 ```