add arg metavar

Author: myfreess

docs/RuleSpec.md

@@ -161,16 +161,18 @@ binder, label, constructor, type-name, or qualified-identifier positions infer
 `id`. For example, in `for $counter = 0; $counter < $limit; ...`, `$counter`
 infers `id` from the binder position and `$limit` infers `exp`.
 
-Only `exp`, `id`, `const`, and `pat` are supported. A name may be repeated
+Only `exp`, `id`, `const`, `arg`, and `pat` are supported. A name may be repeated
 within one kind, but using the same payload across multiple kinds such as
-`$(name:exp)`, `$(name:id)`, `$(name:const)`, and `$(name:pat)` in one shape is
-invalid.
+`$(name:exp)`, `$(name:id)`, `$(name:const)`, `$(name:arg)`, and
+`$(name:pat)` in one shape is invalid.
 
 Bare `$name` inference is intentionally conservative. It does not default to
-`const` or `pat`. A simple pattern variable such as `match input { $item => body
-}` is ambiguous between `id`, `const`, and `pat`; write `$(item:id)`,
-`$(item:const)`, or `$(item:pat)` to choose. An explicit same-name occurrence
-also fixes later bare occurrences when the positions are compatible.
+`const`, `arg`, or `pat`. A simple pattern variable such as
+`match input { $item => body }` is ambiguous between `id`, `const`, and `pat`;
+write `$(item:id)`, `$(item:const)`, or `$(item:pat)` to choose. Bare `$name`
+does not infer `arg`; use explicit `$(name:arg)` for whole call arguments. An
+explicit same-name occurrence also fixes later bare occurrences when the
+positions are compatible.
 
 The old YAML `metavars` key is not supported. Pattern objects that contain it
 are rejected as using an unsupported key.
@@ -214,6 +216,19 @@ Use `$(name:const)` for literal constants. It is valid only as a whole bare
 identifier expression or as a simple pattern variable position, and it matches
 only parsed MoonBit constants. 
 
+Use `$(name:arg)` for a whole function-call argument slot. It is valid only as
+an entire bare positional argument in a call pattern:
+
+```yaml
+patterns:
+  - shape: sink($(arg:arg))
+```
+
+The placeholder can match a candidate positional argument, labelled argument,
+labelled pun, optional labelled argument, or optional labelled pun. The captured
+value is the whole `Argument` AST node, including argument kind, label, and
+value.
+
 Use `$(name:pat)` for a whole pattern AST capture. It is valid only as a simple
 pattern variable position:
 
@@ -355,6 +370,41 @@ patterns:
   - shape: match input { $(lit:const) => lit }
 ```
 
+### `arg`
+
+An `arg` metavar captures a complete call argument node. It is useful when a
+rule should accept any argument spelling in one slot while still comparing the
+entire slot on repeated occurrences.
+
+Example:
+
+```yaml
+patterns:
+  - shape: sink($(arg:arg))
+```
+
+This can match all of these one-argument calls:
+
+```moonbit
+sink(value)
+sink(label=value)
+sink(label~)
+sink(label?=value)
+sink(label?)
+```
+
+Repeating the same `arg` name requires the full argument nodes to be
+structurally equal, ignoring source locations. Argument kind, label, and value
+must all match. The pattern `sink($(arg:arg), $(arg:arg))` can match
+`sink(value, value)` and `sink(label=value, label=value)`, but not
+`sink(value, other)` or `sink(label=value, other=value)`.
+
+`arg` is explicit-only. Bare `$arg` in `sink($arg)` still follows normal bare
+metavar inference and is an `exp` capture unless the name was explicitly
+declared as another kind elsewhere. `$(arg:arg)` must occupy the whole
+argument slot; `sink(label=$(arg:arg))`, `sink($(arg:arg) + 1)`, and a root
+shape `$(arg:arg)` are invalid.
+
 ### `pat`
 
 A `pat` metavar captures the whole candidate `Pattern` AST. It is valid only in
@@ -387,9 +437,9 @@ patterns:
 ```
 
 Only `id` and `const` captures can be guarded. A guard key that refers to an
-`exp` capture, a `pat` capture, or an unknown name is rejected during rule
-compilation. Inner `patterns` may guard `id` and `const` captures established by
-`inside-expr`.
+`exp` capture, an `arg` capture, a `pat` capture, or an unknown name is
+rejected during rule compilation. Inner `patterns` may guard `id` and `const`
+captures established by `inside-expr`.
 
 Guards are checked after the structural AST match succeeds. All guards in a
 single pattern object must match; this is AND semantics. Regex matching uses
@@ -686,8 +736,9 @@ A rule set or rule file is rejected when any of these conditions occurs:
 - an metavar uses a reserved name
 - `$(name:exp)` appears outside a bare expression position
 - `$(name:const)` appears outside a constant expression or constant pattern position
+- `$(name:arg)` appears outside a bare argument position
 - `$(name:pat)` appears outside a bare pattern position
-- a guard key is not `$`-prefixed, or references an unknown, `exp`, or `pat` capture
+- a guard key is not `$`-prefixed, or references an unknown, `exp`, `arg`, or `pat` capture
 - a guard regex is invalid
 - `inside-expr` does not contain exactly one binding-capable `__TARGET__`
 - a structural `patterns` or `patterns-not` entry contains binding-capable

docs/RuleSpec_CN.md

@@ -131,9 +131,9 @@ patterns:
 
 moongrep会为同名的所有出现位置推导出单一 kind。只出现在表达式占位位置的裸名称会推导为 `exp`；出现在 binder、标签、构造器、类型名或限定标识符位置的裸名称会推导为 `id`。例如 `for $counter = 0; $counter < $limit; ...` 中，`$counter` 会从 binder 位置推导为 `id`，`$limit` 会推导为 `exp`。
 
-只支持 `exp`、`id`、`const` 和 `pat`。同一个 payload 可以在同一种 kind 中重复使用；同一个 shape 中不能跨 `$(name:exp)`、`$(name:id)`、`$(name:const)` 和 `$(name:pat)` 等多个 kind 使用同一个 payload。
+只支持 `exp`、`id`、`const`、`arg` 和 `pat`。同一个 payload 可以在同一种 kind 中重复使用；同一个 shape 中不能跨 `$(name:exp)`、`$(name:id)`、`$(name:const)`、`$(name:arg)` 和 `$(name:pat)` 等多个 kind 使用同一个 payload。
 
-裸 `$name` 的推导是保守的。它不会默认推导为 `const` 或 `pat`。像 `match input { $item => body }` 这样的简单 pattern variable 在 `id`、`const` 和 `pat` 之间有歧义；请写成 `$(item:id)`、`$(item:const)` 或 `$(item:pat)` 来明确选择。同名的显式出现也可以在位置兼容时为后续裸出现确定 kind。
+裸 `$name` 的推导是保守的。它不会默认推导为 `const`、`arg` 或 `pat`。像 `match input { $item => body }` 这样的简单 pattern variable 在 `id`、`const` 和 `pat` 之间有歧义；请写成 `$(item:id)`、`$(item:const)` 或 `$(item:pat)` 来明确选择。裸 `$name` 不会推导为 `arg`；完整调用参数请显式写 `$(name:arg)`。同名的显式出现也可以在位置兼容时为后续裸出现确定 kind。
 
 旧的 YAML `metavars` 键不再支持。包含该键的 pattern object 会因为使用不支持的键而被拒绝。
 
@@ -167,6 +167,15 @@ patterns:
 
 如果需要匹配字面常量，请使用 `$(name:const)`。它只在整个裸标识符表达式位置或简单 pattern variable 位置有效，并且只匹配解析后的 MoonBit 常量。重复使用同一个 `const` kind 名称时，常量 kind 和存储值都必须相等。它不会匹配变量、构造器、标签、操作符、限定标识符或普通 binder。
 
+如果需要捕获完整函数调用参数槽，请使用 `$(name:arg)`。它只在调用 pattern 的整个裸位置参数中有效：
+
+```yaml
+patterns:
+  - shape: sink($(arg:arg))
+```
+
+该占位符可以匹配候选中的 positional、labelled、labelled pun、optional labelled 和 optional pun 参数。捕获值是完整 `Argument` AST 节点，包括参数 kind、标签和值。
+
 如果需要捕获整个 pattern AST，请使用 `$(name:pat)`。它只在简单 pattern variable 位置有效：
 
 ```yaml
@@ -290,6 +299,31 @@ patterns:
 
 内部 body 通过普通 payload 名称 `lit` 引用外层常量捕获。
 
+### `arg`
+
+`arg` 元变量捕获完整调用参数节点。当规则需要在一个参数槽中接受任意参数写法，同时又希望重复出现时比较整个参数槽，使用它很合适。
+
+示例：
+
+```yaml
+patterns:
+  - shape: sink($(arg:arg))
+```
+
+它可以匹配这些单参数调用：
+
+```moonbit
+sink(value)
+sink(label=value)
+sink(label~)
+sink(label?=value)
+sink(label?)
+```
+
+重复使用同一个 `arg` 名称时，完整参数节点必须结构相等；源码位置会被忽略。参数 kind、标签和值都必须相同。`sink($(arg:arg), $(arg:arg))` 可以匹配 `sink(value, value)` 和 `sink(label=value, label=value)`，但不会匹配 `sink(value, other)` 或 `sink(label=value, other=value)`。
+
+`arg` 只能显式使用。`sink($arg)` 中的裸 `$arg` 仍按普通裸元变量推导处理，除非该名称在别处已经被显式声明为其他 kind，否则它是 `exp` 捕获。`$(arg:arg)` 必须占据整个参数槽；`sink(label=$(arg:arg))`、`sink($(arg:arg) + 1)` 和根 shape `$(arg:arg)` 都无效。
+
 ### `pat`
 
 `pat` 元变量捕获整个候选 `Pattern` AST。它只在简单 pattern variable 位置有效。
@@ -317,8 +351,8 @@ patterns:
 ```
 
 只有 `id` 和 `const` 捕获可以被 guard 过滤。guard 键如果引用 `exp` 捕获、
-`pat` 捕获或未知名称，会在规则编译时报错。内部 `patterns` 可以 guard 由
-`inside-expr` 建立的 `id` 和 `const` 捕获。
+`arg` 捕获、`pat` 捕获或未知名称，会在规则编译时报错。内部 `patterns` 可以
+guard 由 `inside-expr` 建立的 `id` 和 `const` 捕获。
 
 Guard 会在结构 AST 匹配成功后检查。单个 pattern object 中的所有 guard 都必须
 匹配，即 AND 语义。正则使用包含匹配语义；如果需要整串匹配，请使用 `^...$`
@@ -552,8 +586,9 @@ taint 命中报告的 pattern index 是匹配 sink 条目的零基索引。
 - 内联元变量使用保留名称
 - `$(name:exp)` 出现在裸表达式位置之外
 - `$(name:const)` 出现在常量表达式或常量 pattern 位置之外
+- `$(name:arg)` 出现在裸参数位置之外
 - `$(name:pat)` 出现在裸 pattern 位置之外
-- guard 键没有 `$` 前缀，或引用未知捕获、`exp` 捕获或 `pat` 捕获
+- guard 键没有 `$` 前缀，或引用未知捕获、`exp` 捕获、`arg` 捕获或 `pat` 捕获
 - guard 正则无效
 - `inside-expr` 没有且只有一个可绑定的 `__TARGET__`
 - 结构规则的 `patterns` 或 `patterns-not` 条目包含可绑定的 `__TARGET__`

docs/WritingRules.md

@@ -183,8 +183,8 @@ patterns:
 ```
 
 Use explicit `$(name:kind)` when inference would be ambiguous or when you need
-`const` or `pat`. Use `$(name:const)` when the same literal constant must be
-consistent and variables should not match:
+`const`, `arg`, or `pat`. Use `$(name:const)` when the same literal constant
+must be consistent and variables should not match:
 
 ```yaml
 patterns:
@@ -198,13 +198,24 @@ patterns:
   - shape: match input { $(item:pat) => body }
 ```
 
+Use `$(name:arg)` for a whole call argument slot:
+
+```yaml
+patterns:
+  - shape: sink($(arg:arg))
+```
+
+That pattern can match positional, labelled, labelled pun, optional labelled,
+and optional pun arguments in the single slot. Bare `$arg` does not infer
+`arg`; write the explicit kind at each argument slot.
+
 A bare simple pattern variable such as `match input { $item => body }` is
 ambiguous between `id`, `const`, and `pat`, so rule compilation asks you to
 choose explicitly. The `exp` kind is expression-only. The `const` kind is valid
-only in constant expression or constant pattern positions. The `pat` kind is
-valid only in a simple pattern variable position. If you need a non-expression
-source name, use `id` or leave the name literal. Any other kind is a compile
-error.
+only in constant expression or constant pattern positions. The `arg` kind is
+valid only as a whole bare argument in a call pattern. The `pat` kind is valid
+only in a simple pattern variable position. If you need a non-expression source
+name, use `id` or leave the name literal. Any other kind is a compile error.
 
 The old YAML `metavars` key is invalid.
 
@@ -220,7 +231,7 @@ When one of these names appears in a supported metavar position, it matches
 anything there without binding a value or participating in repeated-name
 equality. Repeated ignore placeholders are independent wildcards.
 
-### 3. Choose `exp`, `id`, `const`, or `pat`
+### 3. Choose `exp`, `id`, `const`, `arg`, or `pat`
 
 Use `exp` when you want to match and compare a whole expression. Repeating an
 `exp` metavar means the repeated captures must be structurally equal according
@@ -273,6 +284,18 @@ patterns:
   - shape: match input { $(item:pat) => body }
 ```
 
+Use `arg` when the candidate must be a complete call argument slot, including
+its kind, label, and value. Repeated `arg` captures compare the whole argument
+node while ignoring source locations.
+
+```yaml
+patterns:
+  - shape: sink($(arg:arg), $(arg:arg))
+```
+
+This can match `sink(value, value)` and `sink(label=value, label=value)`, but
+not `sink(value, other)` or `sink(label=value, other=value)`.
+
 ### 3.5 Use `inside-expr` when the interesting node must appear inside a larger context
 
 Reach for `inside-expr` when the thing you want to flag is only meaningful
@@ -377,8 +400,8 @@ normalized names such as `name` or `@pkg.name`. `const` guards see parser
 constant values, such as `raw` for `"raw"`, `42` for `42`, and `true` for
 `true`.
 
-Guards cannot filter `exp` or `pat` captures, and taint clauses do not support
-`guard`.
+Guards cannot filter `exp`, `arg`, or `pat` captures, and taint clauses do not
+support `guard`.
 
 ### 5. Add more `patterns` when the message is shared
 
@@ -481,9 +504,10 @@ valid expression-sized shape, then build back up carefully.
 
 Check, in order:
 
-- the kind annotation is exactly `exp`, `id`, `const`, or `pat`
+- the kind annotation is exactly `exp`, `id`, `const`, `arg`, or `pat`
 - `$(name:exp)` appears as a whole bare expression placeholder
 - `$(name:const)` appears only where a constant expression or constant pattern can match
+- `$(name:arg)` appears only as a whole bare call argument
 - `$(name:pat)` appears only as a whole bare pattern placeholder
 - the same payload name is not used across multiple metavar kinds
 - the payload is not a reserved name such as `__`, `__TARGET__`, or `__SOURCE__`

docs/WritingRules_CN.md

@@ -117,7 +117,7 @@ patterns:
       }
 ```
 
-当推导有歧义，或需要 `const` 或 `pat` 时，请使用显式 `$(name:kind)`。当同一个字面常量必须保持一致，并且变量不应该匹配时，请使用 `$(name:const)`：
+当推导有歧义，或需要 `const`、`arg` 或 `pat` 时，请使用显式 `$(name:kind)`。当同一个字面常量必须保持一致，并且变量不应该匹配时，请使用 `$(name:const)`：
 
 ```yaml
 patterns:
@@ -131,7 +131,16 @@ patterns:
   - shape: match input { $(item:pat) => body }
 ```
 
-像 `match input { $item => body }` 这样的裸简单 pattern variable 在 `id`、`const` 和 `pat` 之间有歧义，因此规则编译会要求你显式选择。`exp` kind 只能出现在表达式位置。`const` kind 只在常量表达式或常量 pattern 位置有效。`pat` kind 只在简单 pattern variable 位置有效。如果需要非表达式源码名称，请使用 `id`，或者让该名称保持字面量。任何其他 kind 都是编译错误。
+使用 `$(name:arg)` 捕获完整调用参数槽：
+
+```yaml
+patterns:
+  - shape: sink($(arg:arg))
+```
+
+这个 pattern 可以在单个参数槽中匹配 positional、labelled、labelled pun、optional labelled 和 optional pun 参数。裸 `$arg` 不会推导为 `arg`；请在每个参数槽显式写出 kind。
+
+像 `match input { $item => body }` 这样的裸简单 pattern variable 在 `id`、`const` 和 `pat` 之间有歧义，因此规则编译会要求你显式选择。`exp` kind 只能出现在表达式位置。`const` kind 只在常量表达式或常量 pattern 位置有效。`arg` kind 只在调用 pattern 的整个裸参数位置有效。`pat` kind 只在简单 pattern variable 位置有效。如果需要非表达式源码名称，请使用 `id`，或者让该名称保持字面量。任何其他 kind 都是编译错误。
 
 旧的 YAML `metavars` 键无效。
 
@@ -144,7 +153,7 @@ patterns:
 
 当这些名称之一出现在支持的元变量位置时，它会匹配该位置上的任何内容，不绑定值，也不参与重复名称相等性检查。重复的忽略占位符是彼此独立的通配符。
 
-### 3. 选择 `exp`、`id`、`const` 或 `pat`
+### 3. 选择 `exp`、`id`、`const`、`arg` 或 `pat`
 
 当你想匹配并比较完整表达式时，使用 `exp`。重复使用同一个 `exp` 元变量意味着这些捕获必须根据运行时 matcher 的结构相等规则相等；源码位置会被忽略。
 
@@ -184,6 +193,15 @@ patterns:
   - shape: match input { $(item:pat) => body }
 ```
 
+当候选必须是完整调用参数槽时，使用 `arg`；它会包含参数 kind、标签和值。重复的 `arg` 捕获会比较完整参数节点，并忽略源码位置。
+
+```yaml
+patterns:
+  - shape: sink($(arg:arg), $(arg:arg))
+```
+
+这可以匹配 `sink(value, value)` 和 `sink(label=value, label=value)`，但不会匹配 `sink(value, other)` 或 `sink(label=value, other=value)`。
+
 ### 3.5 当关注节点必须出现在更大上下文内时，使用 `inside-expr`
 
 当你想标记的内容只有在特定外层表达式内才有意义，并且你希望内部匹配继承外层捕获时，可以使用 `inside-expr`。
@@ -268,7 +286,7 @@ Guard 键是带 `$` 前缀的捕获名。值是正则字符串，使用包含匹
 `@pkg.name`。`const` guard 看到的是 parser 常量值，例如 `"raw"` 对应 `raw`，
 `42` 对应 `42`，`true` 对应 `true`。
 
-Guard 不能过滤 `exp` 或 `pat` 捕获，taint 子句也不支持 `guard`。
+Guard 不能过滤 `exp`、`arg` 或 `pat` 捕获，taint 子句也不支持 `guard`。
 
 ### 5. 当消息共享时添加更多 `patterns`
 
@@ -365,6 +383,7 @@ patterns:
 
 - `$(name:exp)` 只出现在完整的裸表达式位置
 - `$(name:const)` 只出现在可匹配常量表达式或常量 pattern 的位置
+- `$(name:arg)` 只出现在完整的裸调用参数位置
 - `$(name:pat)` 只出现在完整的裸 pattern 位置
 - 非表达式源码名称使用 `$(name:id)`，或者保持字面量
 - 没有使用不支持的 kind