clean docs

Author: myfreess

SKILL.md

@@ -16,29 +16,32 @@ moon runwasm moonbit-community/moongrep -- scan --pattern 'target()' path/to/src
 Synopsis:
 
 ```text
-moon runwasm moonbit-community/moongrep -- scan [--verbose] [--exclude-dir <dir>...] ((--rules <rules-root> | --rules=<rules-root> | -r <rules-root> | --rule <rule-file>) | --pattern <pattern>)... [scan-root]
+moon runwasm moonbit-community/moongrep -- scan [--verbose] [--enable-builtin-rules] [--exclude-dir <dir>...] ((--rules <rules-root> | --rules=<rules-root> | -r <rules-root> | --rule <rule-file>) | --pattern <pattern>)... [scan-root]
 ```
 
 The scanner is available through the `scan` subcommand. `--rules` / `-r` is
 optional when `--rule <rule-file>` or at least one `--pattern <pattern>` is
-supplied. The long rules option accepts both `--rules <rules-root>` and
-`--rules=<rules-root>` forms. Use `--rule <rule-file>` to load exactly one YAML
-rule file. Inline patterns are treated as anonymous structural rules whose rule
-id is the pattern string itself. One optional positional `scan-root` may appear
-in the `scan` argument list and defaults to `.`. If the rules or rule option
-appears multiple times, the last value wins. Repeated `--pattern` values are
-appended as separate anonymous rules.
+supplied, or when `--enable-builtin-rules` is enabled. The long rules option
+accepts both `--rules <rules-root>` and `--rules=<rules-root>` forms. Use
+`--rule <rule-file>` to load exactly one YAML rule file. Inline patterns are
+treated as anonymous structural rules whose rule id is the pattern string
+itself. `--enable-builtin-rules` loads the embedded builtin rules in addition
+to any rules and inline patterns supplied on the command line. One optional
+positional `scan-root` may appear in the `scan` argument list and defaults to
+`.`. If the rules or rule option appears multiple times, the last value wins.
+Repeated `--pattern` values are appended as separate anonymous rules.
 
 Use `--exclude-dir <dir>...` to skip directory names or paths while recursively
 scanning the source tree. When passing multiple excluded directories after one
 flag, put `scan-root` before `--exclude-dir`; repeated `--exclude-dir <dir>` and
 `--exclude-dir=<dir>` forms are also accepted.
 
 Usage errors print a message and exit with code 2: missing `scan` command,
-missing both rules and pattern options, missing option value, unknown options,
-or more than one scan root. Non-usage errors, including unreadable paths, an
-empty rules directory, invalid YAML/schema/shape, or source read failures,
-abort the run; the CLI prints the error and exits with code 1.
+missing all rule sources (`--rules`, `--rule`, `--pattern`, and
+`--enable-builtin-rules`), missing option value, unknown options, or more than
+one scan root. Non-usage errors, including unreadable paths, an empty rules
+directory, invalid YAML/schema/shape, or source read failures, abort the run;
+the CLI prints the error and exits with code 1.
 
 Pass `--verbose` to print loaded rule ids and the directory traversal progress
 before warnings and match results.
@@ -56,6 +59,7 @@ moon runwasm moonbit-community/moongrep -- scan --rules path/to/rules
 moon runwasm moonbit-community/moongrep -- scan -r path/to/rules
 moon runwasm moonbit-community/moongrep -- scan --rule path/to/rule.yaml
 moon runwasm moonbit-community/moongrep -- scan --pattern 'target()'
+moon runwasm moonbit-community/moongrep -- scan --enable-builtin-rules
 ```
 
 The scanner recursively reads `.mbt` files. When descending from `scan-root`,

TODO.md

@@ -4,7 +4,8 @@
 
 - Matching is AST based and location preserving. Reported locations are exactly
   the locations supplied by the parser/tree builder.
-- Rule `guard` keys are rejected in runtime AST mode.
+- Structural `id` and `const` guards are supported. Guards for `exp` captures,
+  `pat` captures, unknown captures, and taint clauses are still rejected.
 - Taint analysis is intra-procedural. Cross-function behavior must be described
   with call models or matched directly by rule shapes.
 - Unknown call handling depends on the selected `taint.UnknownCallPolicy`; YAML

docs/RuleSpec.md

@@ -62,7 +62,7 @@ Only these top-level keys are accepted:
 
 - `id` (required): non-empty YAML string that must not contain `/`
 - `description` (required): YAML string
-- `patterns` (required for ordinary structural rules): non-empty YAML array
+- `patterns` (optional for structural rules): non-empty YAML array
 - `patterns-not` (optional for structural rules): non-empty YAML array using
   the same object schema as `patterns`
 - `inside-expr` (optional for structural rules): YAML string containing one
@@ -73,7 +73,8 @@ Unknown top-level keys are rejected.
 
 Each rule must choose exactly one rule mode:
 
-- structural mode: `patterns`, or `inside-expr` with `patterns-not`
+- structural mode: `patterns`, optionally with `patterns-not`; or
+  `inside-expr` with `patterns`, `patterns-not`, or both
 - taint mode: `taint`
 
 `patterns` and `taint` are mutually exclusive. `inside-expr` and `patterns-not`
@@ -257,13 +258,11 @@ make(value) == make(other)
 different syntactic roles, such as once as a binder and later as an identifier
 expression. Use `id` for that.
 
-Repeated `exp` equality is currently guaranteed for common expression forms,
-including identifiers, holes, constants, unit, infix expressions, calls, method
-calls, field access, method references, constructor expressions, grouped
-expressions, blocks, array literals, tuple literals, and `for` expressions.
-Some expression forms can be matched once but are not yet supported for
-repeated equality. If a repeated `exp` capture uses an unsupported equality
-form, that match fails rather than producing a hit.
+Repeated `exp` equality is currently guaranteed because captured values are
+compared as untyped AST nodes by node kind and child values, ignoring source
+locations. It is not limited to a fixed list of expression shapes. Semantic
+equivalents with different AST structure still do not match unless a
+placeholder absorbs the difference.
 
 ### `id`
 
@@ -386,7 +385,7 @@ and booleans as `true` or `false`.
 ## Structural Rules
 
 A structural rule has a non-empty `patterns` array, or has `inside-expr` with
-non-empty `patterns-not`.
+non-empty `patterns`, non-empty `patterns-not`, or both.
 
 ```yaml
 id: repeated-equality

docs/RuleSpec_CN.md

@@ -51,7 +51,7 @@ rules/security/nested/raw.yml with id: unsafe-html -> security/nested/unsafe-htm
 
 - `id`（必需）：非空 YAML 字符串，且不能包含 `/`
 - `description`（必需）：YAML 字符串
-- `patterns`（结构规则必需）：非空 YAML 数组
+- `patterns`（结构规则可选）：非空 YAML 数组
 - `patterns-not`（结构规则可选）：与 `patterns` 使用相同条目 schema 的非空 YAML 数组
 - `inside-expr`（结构规则可选）：包含一个 MoonBit 表达式片段的 YAML 字符串，作为外层上下文
 - `taint`（污点规则必需）：YAML 映射
@@ -60,7 +60,8 @@ rules/security/nested/raw.yml with id: unsafe-html -> security/nested/unsafe-htm
 
 每条规则必须且只能选择一种规则模式：
 
-- 结构模式：`patterns`，或带 `patterns-not` 的 `inside-expr`
+- 结构模式：`patterns`，可选搭配 `patterns-not`；或 `inside-expr`
+  搭配 `patterns`、`patterns-not`，或两者同时存在
 - 污点模式：`taint`
 
 `patterns` 和 `taint` 互斥。`inside-expr` 和 `patterns-not` 只对结构规则有效；它们在污点规则中会被拒绝。`patterns-not` 必须和 `patterns` 或 `inside-expr` 一起出现；没有 `patterns` 的 `inside-expr` 规则必须包含 `patterns-not`。
@@ -69,7 +70,7 @@ rules/security/nested/raw.yml with id: unsafe-html -> security/nested/unsafe-htm
 
 ### Pattern Objects
 
-结构规则中的 `patterns` 条目使用以下对象 schema。
+结构规则中的 `patterns` 和 `patterns-not` 条目使用以下对象 schema。
 
 只接受这些键：
 
@@ -210,7 +211,7 @@ make(value) == make(other)
 
 当同一个源码层面的名称出现在不同语法角色中时，例如一次作为 binder，之后作为标识符表达式出现，`exp` 通常不是合适选择。此时应使用 `id`。
 
-重复 `exp` 相等性目前保证支持常见表达式形式，包括标识符、hole、常量、unit、中缀表达式、调用、方法调用、字段访问、方法引用、构造器表达式、分组表达式、块、数组字面量、元组字面量和 `for` 表达式。某些表达式形式可以单次匹配，但尚不支持重复相等性。如果重复 `exp` 捕获使用了不支持的相等形式，该次匹配会失败，而不会产生命中。
+重复 `exp` 相等性由 untyped AST 节点比较保证：比较节点 kind 和子值，并忽略源码位置。它不再限定为一组固定表达式形状。AST 结构不同的语义等价代码仍然不会匹配，除非差异被占位符吸收。
 
 ### `id`
 
@@ -318,8 +319,8 @@ Guard 会在结构 AST 匹配成功后检查。单个 pattern object 中的所
 
 ## 结构规则
 
-结构规则具有非空 `patterns` 数组，或者具有 `inside-expr` 和非空
-`patterns-not`。
+结构规则具有非空 `patterns` 数组，或者具有 `inside-expr` 并搭配非空
+`patterns`、非空 `patterns-not`，或两者同时存在。
 
 ```yaml
 id: repeated-equality
@@ -369,7 +370,8 @@ patterns-not:
 
 ### `inside-expr`
 
-`inside-expr` 将结构规则限制在更大的表达式上下文内部匹配。
+`inside-expr` 将结构规则限制在更大的表达式上下文内部匹配。它可以搭配
+`patterns`、`patterns-not`，或两者同时使用。
 
 ```yaml
 id: wrapped-target
@@ -513,9 +515,10 @@ taint 命中报告的 pattern index 是匹配 sink 条目的零基索引。
 - 缺少必需键
 - `id`、`description`、`inside-expr` 或 `shape` 不是 YAML 字符串
 - `id` 为空或包含 `/`
-- 规则没有且只有一个 `patterns` 或 `taint`
+- 规则没有选择结构模式或污点模式
 - taint 规则中出现 `inside-expr`
 - `inside-expr` 存在但不是字符串
+- `inside-expr` 存在但没有 `patterns` 或 `patterns-not`
 - `patterns` 不是数组或为空
 - `patterns` 条目不是映射
 - `patterns-not` 不是数组或为空
@@ -540,8 +543,9 @@ taint 命中报告的 pattern index 是匹配 sink 条目的零基索引。
 - guard 键引用未知捕获、`exp` 捕获或 `pat` 捕获
 - guard 正则无效
 - `inside-expr` 没有且只有一个可绑定的 `__TARGET__`
-- 结构规则的 `patterns` 条目包含可绑定的 `__TARGET__`
-- 结构规则的 `patterns` 条目用不同 kind 使用了继承自 `inside-expr` 的元变量名
+- 结构规则的 `patterns` 或 `patterns-not` 条目包含可绑定的 `__TARGET__`
+- 结构规则的 `patterns` 或 `patterns-not` 条目用不同 kind 使用了继承自
+  `inside-expr` 的元变量名
 - taint source 包含可绑定的 `__SOURCE__`
 - taint sink 或 sanitizer 没有且只有一个可绑定的 `__SOURCE__`
 - taint sink 或 sanitizer 没有将 `__SOURCE__` 放在整个 receiver 或整个参数值的位置

docs/WritingRules.md

@@ -26,9 +26,10 @@ and must not contain `/`; directory ownership is encoded by file location.
 
 Each YAML file must contain exactly one document, and that document must be a
 mapping. A complete rule file requires string `id` and `description` fields,
-rejects unknown top-level keys, and uses exactly one of these top-level modes:
+rejects unknown top-level keys, and chooses one of these rule modes:
 
-- `patterns`: structural expression matching
+- structural: non-empty `patterns`, or `inside-expr` with `patterns`,
+  `patterns-not`, or both
 - `taint`: intraprocedural taint modeling compiled to the `taint` package
 
 `patterns` must be a non-empty array when present. Structural rules may also
@@ -168,9 +169,8 @@ patterns:
   - shape: $(expr:exp) == $(expr:exp)
 ```
 
-Use `$(name:id)` when the same source-level name must be consistent across
-binders, identifier expressions, pattern variables, labels, or simple variable
-targets:
+Use `$(name:id)` when the same source-level name must remain consistent between
+its definition and use sites:
 
 ```yaml
 patterns:
@@ -218,7 +218,7 @@ patterns:
   - shape: $(expr:exp) == $(expr:exp)
 ```
 
-This is a good fit for supported repeated expression shapes such as:
+This is a good fit for whole-expression comparisons such as:
 
 - `x == x`
 - `user.profile.name == user.profile.name`
@@ -283,14 +283,14 @@ Rules for `inside-expr`:
 - it must place exactly one supported `__TARGET__`; place it where a whole
   expression is expected so runtime traversal can search that subtree
 - `__TARGET__` is reserved and must not be used as an inline metavar name
-- inner `patterns` must not contain `__TARGET__`; the target placeholder
-  selects the subtree to search, but it is not a binding available to inner
-  shapes
+- inner `patterns` and `patterns-not` must not contain `__TARGET__`; the target
+  placeholder selects the subtree to search, but it is not a binding available
+  to inner shapes
 - inherited `id` captures observe lexical shadowing inside the searched target
   subtree
-- inner `patterns` reference outer captures by repeating the same inline
-  metavar form, such as `$(prefix:exp)`; using the same name with a different
-  kind is rejected
+- inner `patterns` and `patterns-not` reference outer captures by repeating the
+  same inline metavar form, such as `$(prefix:exp)`; using the same name with a
+  different kind is rejected
 
 ### 3.6 Use `patterns-not` to prune blocked branches
 
@@ -438,7 +438,7 @@ patterns:
 Why it works:
 
 - `counter` is compared by normalized identifier name, not by raw AST equality
-- `start`, `limit`, and `body` are expression captures stored as parser AST nodes
+- `start`, `limit`, and `body` are expression captures stored as untyped AST nodes
 
 ### Same rule, multiple shapes
 
@@ -483,9 +483,9 @@ exact supported normalization cases in [RuleSpec.md](RuleSpec.md).
 
 ### A rule with `guard` fails to load
 
-Check that `guard` is under a structural `patterns` entry, that it is a
-mapping, and that every key names an `id` or `const` capture visible to that
-pattern. `guard` is still rejected in taint clauses.
+Check that `guard` is under a structural `patterns` or `patterns-not` entry,
+that it is a mapping, and that every key names an `id` or `const` capture
+visible to that pattern. `guard` is still rejected in taint clauses.
 
 ## Testing Workflow
 

docs/WritingRules_CN.md

@@ -14,14 +14,14 @@ YAML 规则文件是扫描器的输入。规则根目录可以是通过 `--rules
 
 规则 id 来自规则文件目录加 YAML `id`。例如，当 `rules` 是规则根目录时，`rules/security/raw.yaml` 中的 `id: raw-html` 会变成 `security/raw-html`。直接位于规则根目录下的文件只使用其 `id`。文件名不参与规则 id。YAML `id` 不能为空，且不能包含 `/`；目录归属由文件位置编码。
 
-每个 YAML 文件必须只包含一个文档，且该文档必须是映射。完整规则文件需要字符串字段 `id` 和 `description`，会拒绝未知顶层键，并且使用且只使用以下顶层模式之一：
+每个 YAML 文件必须只包含一个文档，且该文档必须是映射。完整规则文件需要字符串字段 `id` 和 `description`，会拒绝未知顶层键，并且选择以下规则模式之一：
 
-- `patterns`：结构化表达式匹配
+- 结构模式：非空 `patterns`，或 `inside-expr` 搭配 `patterns`、`patterns-not`，或两者同时存在
 - `taint`：过程内污点建模，编译到 `taint` package
 
 `patterns` 必须是非空数组。未知键会在每个 schema 层级被拒绝：顶层规则键、`taint` 键和规则子句键。
 
-结构规则还可以添加可选顶层 `inside-expr`。它会过滤外层表达式、绑定外层内联捕获，然后使用内部 `patterns` 搜索捕获到的 `__TARGET__` 表达式子树。
+结构规则还可以添加可选顶层 `inside-expr`。它会过滤外层表达式、绑定外层内联捕获，然后使用内部 `patterns` 或 `patterns-not` 搜索捕获到的 `__TARGET__` 表达式子树。
 
 ## 心智模型
 
@@ -107,7 +107,7 @@ patterns:
   - shape: $(expr:exp) == $(expr:exp)
 ```
 
-当同一个源码层面的名称必须在 binder、标识符表达式、pattern 变量、标签或简单变量目标之间保持一致时，请使用 `$(name:id)`：
+当同一个源码层面的名称必须在定义和使用的地方保持一致时, 请使用 `$(name:id)`
 
 ```yaml
 patterns:
@@ -146,7 +146,7 @@ patterns:
   - shape: $(expr:exp) == $(expr:exp)
 ```
 
-它适合支持的重复表达式形状，例如：
+它适合完整表达式比较，例如：
 
 - `x == x`
 - `user.profile.name == user.profile.name`
@@ -327,7 +327,7 @@ patterns:
 为什么它能工作：
 
 - `counter` 按归一化后的标识符名称比较，而不是按原始 AST 相等性比较
-- `start`、`limit` 和 `body` 是以 parser AST 节点保存的表达式捕获
+- `start`、`limit` 和 `body` 是以 untyped AST 节点保存的表达式捕获
 
 ### 同一规则，多个 shape
 
@@ -369,7 +369,7 @@ patterns:
 
 ### 带 `guard` 的规则加载失败
 
-请检查 `guard` 是否位于结构规则的 `patterns` 条目下，是否是映射，并且每个键
+请检查 `guard` 是否位于结构规则的 `patterns` 或 `patterns-not` 条目下，是否是映射，并且每个键
 都引用了该 pattern 可见的 `id` 或 `const` 捕获。taint 子句中仍然会拒绝
 `guard`。
 

docs/rule_spec.mbt

@@ -66,7 +66,7 @@ let _embed_rulespec_md : String =
   #|
   #|- `id` (required): non-empty YAML string that must not contain `/`
   #|- `description` (required): YAML string
-  #|- `patterns` (required for ordinary structural rules): non-empty YAML array
+  #|- `patterns` (optional for structural rules): non-empty YAML array
   #|- `patterns-not` (optional for structural rules): non-empty YAML array using
   #|  the same object schema as `patterns`
   #|- `inside-expr` (optional for structural rules): YAML string containing one
@@ -77,7 +77,8 @@ let _embed_rulespec_md : String =
   #|
   #|Each rule must choose exactly one rule mode:
   #|
-  #|- structural mode: `patterns`, or `inside-expr` with `patterns-not`
+  #|- structural mode: `patterns`, optionally with `patterns-not`; or
+  #|  `inside-expr` with `patterns`, `patterns-not`, or both
   #|- taint mode: `taint`
   #|
   #|`patterns` and `taint` are mutually exclusive. `inside-expr` and `patterns-not`
@@ -261,13 +262,11 @@ let _embed_rulespec_md : String =
   #|different syntactic roles, such as once as a binder and later as an identifier
   #|expression. Use `id` for that.
   #|
-  #|Repeated `exp` equality is currently guaranteed for common expression forms,
-  #|including identifiers, holes, constants, unit, infix expressions, calls, method
-  #|calls, field access, method references, constructor expressions, grouped
-  #|expressions, blocks, array literals, tuple literals, and `for` expressions.
-  #|Some expression forms can be matched once but are not yet supported for
-  #|repeated equality. If a repeated `exp` capture uses an unsupported equality
-  #|form, that match fails rather than producing a hit.
+  #|Repeated `exp` equality is currently guaranteed because captured values are
+  #|compared as untyped AST nodes by node kind and child values, ignoring source
+  #|locations. It is not limited to a fixed list of expression shapes. Semantic
+  #|equivalents with different AST structure still do not match unless a
+  #|placeholder absorbs the difference.
   #|
   #|### `id`
   #|
@@ -390,7 +389,7 @@ let _embed_rulespec_md : String =
   #|## Structural Rules
   #|
   #|A structural rule has a non-empty `patterns` array, or has `inside-expr` with
-  #|non-empty `patterns-not`.
+  #|non-empty `patterns`, non-empty `patterns-not`, or both.
   #|
   #|```yaml
   #|id: repeated-equality