modify inside-expr

Author: myfreess

docs/RuleSpec.md

@@ -65,8 +65,8 @@ Only these top-level keys are accepted:
 - `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
-  MoonBit expression snippet used as an outer context
+- `inside-expr` (optional for structural rules): YAML mapping using the same
+  `shape` and optional `guard` schema as `patterns`, used as an outer context
 - `taint` (required for taint rules): YAML mapping
 
 Unknown top-level keys are rejected.
@@ -88,7 +88,8 @@ including trailing newlines produced by block scalars.
 
 ### Pattern Objects
 
-Structural entries in `patterns` and `patterns-not` use this object schema.
+Structural entries in `patterns`, `patterns-not`, and `inside-expr` use this
+object schema.
 
 Only these keys are accepted:
 
@@ -538,12 +539,15 @@ context. It may be used with `patterns`, with `patterns-not`, or with both.
 id: wrapped-target
 description: |
   Match a target call only inside wrapper(...).
-inside-expr: wrapper($(prefix:exp), __TARGET__)
+inside-expr:
+  shape: wrapper($(prefix:exp), __TARGET__)
 patterns:
   - shape: target.call($(prefix:exp))
 ```
 
-`inside-expr` is a YAML string parsed as one MoonBit expression snippet.
+`inside-expr` is a YAML mapping. Its `shape` is parsed as one MoonBit
+expression snippet, and its optional `guard` filters `id` and `const` captures
+declared by that outer shape.
 
 Additional rules:
 
@@ -707,11 +711,11 @@ A rule set or rule file is rejected when any of these conditions occurs:
 - an unsupported key appears at the top level, inside `taint`, or inside a
   pattern object
 - a required key is missing
-- `id`, `description`, `inside-expr`, or `shape` is not a YAML string
+- `id`, `description`, or `shape` is not a YAML string
 - `id` is empty or contains `/`
 - the rule does not choose structural or taint mode
 - `inside-expr` appears on a taint rule
-- `inside-expr` is present but is not a string
+- `inside-expr` is present but is not a mapping
 - `inside-expr` is present without `patterns` or `patterns-not`
 - `patterns` is not an array or is empty
 - a `patterns` entry is not a mapping
@@ -790,7 +794,8 @@ positions. `start`, `limit`, and `body` are expression captures.
 id: unsafe-wrapper
 description: |
   Match a sink only under an unsafe wrapper.
-inside-expr: unsafe(__TARGET__)
+inside-expr:
+  shape: unsafe(__TARGET__)
 patterns:
   - shape: sink(__)
 ```
@@ -823,7 +828,8 @@ own `value`; it does not reuse any positive pattern capture.
 id: wrapper-without-danger
 description: |
   Match wrappers whose payload contains no danger call.
-inside-expr: wrapper(__TARGET__)
+inside-expr:
+  shape: wrapper(__TARGET__)
 patterns-not:
   - shape: danger()
 ```

docs/RuleSpec_CN.md

@@ -53,7 +53,8 @@ rules/security/nested/raw.yml with id: unsafe-html -> security/nested/unsafe-htm
 - `description`（必需）：YAML 字符串
 - `patterns`（结构规则可选）：非空 YAML 数组
 - `patterns-not`（结构规则可选）：与 `patterns` 使用相同条目 schema 的非空 YAML 数组
-- `inside-expr`（结构规则可选）：包含一个 MoonBit 表达式片段的 YAML 字符串，作为外层上下文
+- `inside-expr`（结构规则可选）：YAML 映射，使用与 `patterns` 相同的
+  `shape` 和可选 `guard` schema，作为外层上下文
 - `taint`（污点规则必需）：YAML 映射
 
 未知顶层键会被拒绝。
@@ -70,7 +71,7 @@ rules/security/nested/raw.yml with id: unsafe-html -> security/nested/unsafe-htm
 
 ### Pattern Objects
 
-结构规则中的 `patterns` 和 `patterns-not` 条目使用以下对象 schema。
+结构规则中的 `patterns`、`patterns-not` 条目以及 `inside-expr` 使用以下对象 schema。
 
 只接受这些键：
 
@@ -339,7 +340,8 @@ patterns:
 
 ## Guard
 
-结构规则的 pattern object 可以包含可选的 `guard` 映射。guard 的键是带
+结构规则的 pattern object（包括 `patterns`、`patterns-not` 和
+`inside-expr`）可以包含可选的 `guard` 映射。guard 的键是带
 `$` 前缀的捕获名，值是正则字符串：
 
 ```yaml
@@ -422,12 +424,14 @@ patterns-not:
 id: wrapped-target
 description: |
   Match a target call only inside wrapper(...).
-inside-expr: wrapper($(prefix:exp), __TARGET__)
+inside-expr:
+  shape: wrapper($(prefix:exp), __TARGET__)
 patterns:
   - shape: target.call($(prefix:exp))
 ```
 
-`inside-expr` 是 YAML 字符串，会作为一个 MoonBit 表达式片段解析。
+`inside-expr` 是 YAML 映射。它的 `shape` 会作为一个 MoonBit 表达式片段解析；
+可选 `guard` 会过滤这个外层 shape 声明的 `id` 和 `const` 捕获。
 
 额外规则：
 
@@ -558,11 +562,11 @@ taint 命中报告的 pattern index 是匹配 sink 条目的零基索引。
 - 顶层 YAML 文档不是映射
 - 顶层、`taint` 内或 pattern object 内出现不支持的键
 - 缺少必需键
-- `id`、`description`、`inside-expr` 或 `shape` 不是 YAML 字符串
+- `id`、`description` 或 `shape` 不是 YAML 字符串
 - `id` 为空或包含 `/`
 - 规则没有选择结构模式或污点模式
 - taint 规则中出现 `inside-expr`
-- `inside-expr` 存在但不是字符串
+- `inside-expr` 存在但不是映射
 - `inside-expr` 存在但没有 `patterns` 或 `patterns-not`
 - `patterns` 不是数组或为空
 - `patterns` 条目不是映射
@@ -635,7 +639,8 @@ patterns:
 id: unsafe-wrapper
 description: |
   Match a sink only under an unsafe wrapper.
-inside-expr: unsafe(__TARGET__)
+inside-expr:
+  shape: unsafe(__TARGET__)
 patterns:
   - shape: sink(__)
 ```

docs/WritingRules.md

@@ -306,16 +306,18 @@ captures.
 id: wrapped-target
 description: |
   Match a call only when it appears inside a specific wrapper.
-inside-expr: |
-  wrapper($(prefix:exp), __TARGET__)
+inside-expr:
+  shape: |
+    wrapper($(prefix:exp), __TARGET__)
 patterns:
   - shape: |
       target.call($(prefix:exp))
 ```
 
 Rules for `inside-expr`:
 
-- it uses the same metavar syntax as one structural pattern
+- it uses the same `shape` and optional `guard` schema as one structural
+  pattern
 - 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 metavar name
@@ -357,7 +359,8 @@ reported only when the captured target subtree contains no forbidden shape:
 id: wrapper-without-danger
 description: |
   Wrapper payload contains no danger call.
-inside-expr: wrapper(__TARGET__)
+inside-expr:
+  shape: wrapper(__TARGET__)
 patterns-not:
   - shape: danger()
 ```
@@ -370,7 +373,8 @@ matches cover their whole matched subtrees. Any negative match outside those
 covered positive subtrees rejects the outer context.
 
 ```yaml
-inside-expr: wrapper($(counter:id), __TARGET__)
+inside-expr:
+  shape: wrapper($(counter:id), __TARGET__)
 patterns:
   - shape: arr[$(counter:id)]
 patterns-not:
@@ -520,9 +524,10 @@ exact supported normalization cases in [RuleSpec.md](RuleSpec.md).
 
 ### A rule with `guard` fails to load
 
-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.
+Check that `guard` is under a structural `patterns`, `patterns-not`, or
+`inside-expr` pattern object, 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

@@ -210,16 +210,17 @@ patterns:
 id: wrapped-target
 description: |
   Match a call only when it appears inside a specific wrapper.
-inside-expr: |
-  wrapper($(prefix:exp), __TARGET__)
+inside-expr:
+  shape: |
+    wrapper($(prefix:exp), __TARGET__)
 patterns:
   - shape: |
       target.call($(prefix:exp))
 ```
 
 `inside-expr` 的规则：
 
-- 它使用与一个结构 pattern 相同的内联元变量语法
+- 它使用与一个结构 pattern 相同的 `shape` 和可选 `guard` schema
 - 它必须放置且只放置一个支持的 `__TARGET__`；请将其放在期望完整表达式的位置，使运行时遍历可以搜索该子树
 - `__TARGET__` 是保留名称，不能用作内联元变量名
 - 内部 `patterns` 和 `patterns-not` 不能包含 `__TARGET__`；target placeholder 选择要搜索的子树，但不是内部 shape 可用的绑定
@@ -249,7 +250,8 @@ patterns-not:
 id: wrapper-without-danger
 description: |
   Wrapper payload contains no danger call.
-inside-expr: wrapper(__TARGET__)
+inside-expr:
+  shape: wrapper(__TARGET__)
 patterns-not:
   - shape: danger()
 ```
@@ -260,7 +262,8 @@ patterns-not:
 当 `inside-expr` 同时使用 `patterns` 和 `patterns-not` 时，正向命中的整个子树会覆盖负向匹配；任何出现在这些正向覆盖子树之外的负向命中都会拒绝外层上下文。
 
 ```yaml
-inside-expr: wrapper($(counter:id), __TARGET__)
+inside-expr:
+  shape: wrapper($(counter:id), __TARGET__)
 patterns:
   - shape: arr[$(counter:id)]
 patterns-not:
@@ -395,9 +398,9 @@ patterns:
 
 ### 带 `guard` 的规则加载失败
 
-请检查 `guard` 是否位于结构规则的 `patterns` 或 `patterns-not` 条目下，是否是映射，并且每个键
-都引用了该 pattern 可见的 `id` 或 `const` 捕获。taint 子句中仍然会拒绝
-`guard`。
+请检查 `guard` 是否位于结构规则的 `patterns`、`patterns-not` 或 `inside-expr`
+pattern object 下，是否是映射，并且每个键都引用了该 pattern 可见的 `id` 或
+`const` 捕获。taint 子句中仍然会拒绝 `guard`。
 
 ## 测试工作流
 

docs/rule_spec.mbt

@@ -69,8 +69,8 @@ let _embed_rulespec_md : String =
   #|- `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
-  #|  MoonBit expression snippet used as an outer context
+  #|- `inside-expr` (optional for structural rules): YAML mapping using the same
+  #|  `shape` and optional `guard` schema as `patterns`, used as an outer context
   #|- `taint` (required for taint rules): YAML mapping
   #|
   #|Unknown top-level keys are rejected.
@@ -92,7 +92,8 @@ let _embed_rulespec_md : String =
   #|
   #|### Pattern Objects
   #|
-  #|Structural entries in `patterns` and `patterns-not` use this object schema.
+  #|Structural entries in `patterns`, `patterns-not`, and `inside-expr` use this
+  #|object schema.
   #|
   #|Only these keys are accepted:
   #|
@@ -542,12 +543,15 @@ let _embed_rulespec_md : String =
   #|id: wrapped-target
   #|description: |
   #|  Match a target call only inside wrapper(...).
-  #|inside-expr: wrapper($(prefix:exp), __TARGET__)
+  #|inside-expr:
+  #|  shape: wrapper($(prefix:exp), __TARGET__)
   #|patterns:
   #|  - shape: target.call($(prefix:exp))
   #|```
   #|
-  #|`inside-expr` is a YAML string parsed as one MoonBit expression snippet.
+  #|`inside-expr` is a YAML mapping. Its `shape` is parsed as one MoonBit
+  #|expression snippet, and its optional `guard` filters `id` and `const` captures
+  #|declared by that outer shape.
   #|
   #|Additional rules:
   #|
@@ -711,11 +715,11 @@ let _embed_rulespec_md : String =
   #|- an unsupported key appears at the top level, inside `taint`, or inside a
   #|  pattern object
   #|- a required key is missing
-  #|- `id`, `description`, `inside-expr`, or `shape` is not a YAML string
+  #|- `id`, `description`, or `shape` is not a YAML string
   #|- `id` is empty or contains `/`
   #|- the rule does not choose structural or taint mode
   #|- `inside-expr` appears on a taint rule
-  #|- `inside-expr` is present but is not a string
+  #|- `inside-expr` is present but is not a mapping
   #|- `inside-expr` is present without `patterns` or `patterns-not`
   #|- `patterns` is not an array or is empty
   #|- a `patterns` entry is not a mapping
@@ -794,7 +798,8 @@ let _embed_rulespec_md : String =
   #|id: unsafe-wrapper
   #|description: |
   #|  Match a sink only under an unsafe wrapper.
-  #|inside-expr: unsafe(__TARGET__)
+  #|inside-expr:
+  #|  shape: unsafe(__TARGET__)
   #|patterns:
   #|  - shape: sink(__)
   #|```
@@ -827,7 +832,8 @@ let _embed_rulespec_md : String =
   #|id: wrapper-without-danger
   #|description: |
   #|  Match wrappers whose payload contains no danger call.
-  #|inside-expr: wrapper(__TARGET__)
+  #|inside-expr:
+  #|  shape: wrapper(__TARGET__)
   #|patterns-not:
   #|  - shape: danger()
   #|```

docs/writing_rules.mbt

@@ -310,16 +310,18 @@ let _embed_writingrules_md : String =
   #|id: wrapped-target
   #|description: |
   #|  Match a call only when it appears inside a specific wrapper.
-  #|inside-expr: |
-  #|  wrapper($(prefix:exp), __TARGET__)
+  #|inside-expr:
+  #|  shape: |
+  #|    wrapper($(prefix:exp), __TARGET__)
   #|patterns:
   #|  - shape: |
   #|      target.call($(prefix:exp))
   #|```
   #|
   #|Rules for `inside-expr`:
   #|
-  #|- it uses the same metavar syntax as one structural pattern
+  #|- it uses the same `shape` and optional `guard` schema as one structural
+  #|  pattern
   #|- 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 metavar name
@@ -361,7 +363,8 @@ let _embed_writingrules_md : String =
   #|id: wrapper-without-danger
   #|description: |
   #|  Wrapper payload contains no danger call.
-  #|inside-expr: wrapper(__TARGET__)
+  #|inside-expr:
+  #|  shape: wrapper(__TARGET__)
   #|patterns-not:
   #|  - shape: danger()
   #|```
@@ -374,7 +377,8 @@ let _embed_writingrules_md : String =
   #|covered positive subtrees rejects the outer context.
   #|
   #|```yaml
-  #|inside-expr: wrapper($(counter:id), __TARGET__)
+  #|inside-expr:
+  #|  shape: wrapper($(counter:id), __TARGET__)
   #|patterns:
   #|  - shape: arr[$(counter:id)]
   #|patterns-not:
@@ -524,9 +528,10 @@ let _embed_writingrules_md : String =
   #|
   #|### A rule with `guard` fails to load
   #|
-  #|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.
+  #|Check that `guard` is under a structural `patterns`, `patterns-not`, or
+  #|`inside-expr` pattern object, 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
   #|