fix constant matching doc

Author: myfreess

TODO.md

@@ -8,12 +8,6 @@
   an explicit kind for cross-position reuse, improving the diagnostic, or
   adding a storage-path metavariable kind.
 
-- Clarify constant matching in the RuleSpec overview. Constants are compared
-  using the parser AST constant kind and preserved source spelling, so
-  equivalent values such as `1000` and `1_000` do not necessarily match.
-  Update the English and Chinese summaries so they do not imply that all
-  formatting is ignored.
-
 - Make the Chinese rule documentation available through the `docs` command,
   or document that only English documents are embedded. `docs/export.mbt`
   currently registers only `RuleSpec` and `WritingRules`; consider adding

docs/RuleSpec.md

@@ -15,8 +15,11 @@ rule authors can rely on today.
 
 Rules use YAML format. Every `shape` value is MoonBit surface syntax. The scanner
 matches parsed MoonBit expression structure and does not match raw text.
-Formatting and comments are not significant. Expression form, operators,
-literal values, labels, callee names, and argument structure are significant.
+Whitespace formatting and comments are not significant. Literal source spelling
+is an exception: constants are compared by their parser AST kind and preserved
+source spelling, not by normalized semantic value. Equivalent values such as
+`1000` and `1_000` therefore do not necessarily match. Expression form,
+operators, labels, callee names, and argument structure are also significant.
 Wildcards and declared metavariables modify these matching requirements as
 documented below.
 
@@ -130,13 +133,14 @@ It is one item and cannot represent a whole file or import list.
 Shapes are structural:
 
 - undeclared identifiers and labels match literally
-- constants match by value
+- constants match by parser AST kind and preserved source spelling; equivalent
+  values such as `1000` and `1_000` do not necessarily match
 - operators match literally
 - call and method-call argument kinds, labels, order, and arity must match
 - type annotations and type names in matched syntax must match where present
-- source locations and formatting do not participate in matching; top-level
-  documentation is an AST field and follows the `inside-toplevel` matching
-  mode
+- source locations, comments, and whitespace formatting do not participate in
+  matching; top-level documentation is an AST field and follows the
+  `inside-toplevel` matching mode
 
 The scanner does not type-check shapes and does not resolve names semantically.
 For example, two imported names that refer to the same definition compare as
@@ -487,8 +491,9 @@ Qualified constructor identities include their extra info, such as `@pkg.Ctor`,
 
 A `const` metavar captures a parsed MoonBit constant. In expression position,
 it matches `Expr::Constant`; in pattern position, it matches `Pattern::Constant`.
-It compares the parser AST constant kind and value only; it does not type-check
-or normalize equivalent values.
+It compares the parser AST constant kind and preserved source spelling; it does
+not type-check or normalize equivalent values. For example, `1000` and `1_000`
+do not necessarily compare as the same constant.
 
 Example:
 

docs/RuleSpec_CN.md

@@ -10,7 +10,7 @@
 
 关键词 "must"、"must not"、"may" 和 "currently" 描述的是规则作者今天可以依赖的行为。
 
-规则使用 YAML 格式。每个 `shape` 值都是 MoonBit 表面语法。扫描器匹配解析后的 MoonBit 表达式结构，不匹配原始文本。格式和注释不参与匹配。表达式形式、操作符、字面量值、标签、被调用名称和参数结构参与匹配。通配符和已声明元变量按下文规则修改这些匹配要求。
+规则使用 YAML 格式。每个 `shape` 值都是 MoonBit 表面语法。扫描器匹配解析后的 MoonBit 表达式结构，不匹配原始文本。空白排版和注释不参与匹配，但字面量的源码拼写是例外：常量按 parser AST 中的常量种类和保留的源码拼写比较，而不是按归一化后的语义值比较。因此，`1000` 和 `1_000` 不一定匹配。表达式形式、操作符、标签、被调用名称和参数结构也参与匹配。通配符和已声明元变量按下文规则修改这些匹配要求。
 
 ## 规则文件
 
@@ -105,11 +105,12 @@ Taint `sources`、`sinks` 和 `sanitizers` 同样使用 `shape` 键。这些字
 shape 是结构性的：
 
 - 未声明的标识符和标签按字面匹配
-- 常量按值匹配
+- 常量按 parser AST 中的常量种类和保留的源码拼写匹配；`1000` 和
+  `1_000` 这样的等值常量不一定匹配
 - 操作符按字面匹配
 - 调用和方法调用的参数种类、标签、顺序和数量必须匹配
 - 匹配语法中出现的类型注解和类型名必须匹配
-- 源码位置和格式不参与匹配；顶层文档是 AST 字段，遵循
+- 源码位置、注释和空白排版不参与匹配；顶层文档是 AST 字段，遵循
   `inside-toplevel` 的匹配模式
 
 扫描器不会对 shape 做类型检查，也不会按语义解析名称。例如，两个指向同一定义的导入名称只在解析后的源码拼写一致或被元变量捕获时视为相同。
@@ -391,6 +392,8 @@ for i = 0; j < n; i = i + 1 {
 
 `const` 元变量捕获解析后的 MoonBit 常量。在表达式位置，它匹配 `Expr::Constant`；在 pattern 位置，它匹配 `Pattern::Constant`。
 
+常量比较使用 parser AST 中的常量种类和保留的源码拼写；它不会进行类型检查，也不会归一化等值常量。例如，`1000` 和 `1_000` 不一定被视为同一个常量。
+
 示例：
 
 ```yaml

docs/rule_spec.mbt

@@ -19,8 +19,11 @@ let _embed_rulespec_md : String =
   #|
   #|Rules use YAML format. Every `shape` value is MoonBit surface syntax. The scanner
   #|matches parsed MoonBit expression structure and does not match raw text.
-  #|Formatting and comments are not significant. Expression form, operators,
-  #|literal values, labels, callee names, and argument structure are significant.
+  #|Whitespace formatting and comments are not significant. Literal source spelling
+  #|is an exception: constants are compared by their parser AST kind and preserved
+  #|source spelling, not by normalized semantic value. Equivalent values such as
+  #|`1000` and `1_000` therefore do not necessarily match. Expression form,
+  #|operators, labels, callee names, and argument structure are also significant.
   #|Wildcards and declared metavariables modify these matching requirements as
   #|documented below.
   #|
@@ -134,13 +137,14 @@ let _embed_rulespec_md : String =
   #|Shapes are structural:
   #|
   #|- undeclared identifiers and labels match literally
-  #|- constants match by value
+  #|- constants match by parser AST kind and preserved source spelling; equivalent
+  #|  values such as `1000` and `1_000` do not necessarily match
   #|- operators match literally
   #|- call and method-call argument kinds, labels, order, and arity must match
   #|- type annotations and type names in matched syntax must match where present
-  #|- source locations and formatting do not participate in matching; top-level
-  #|  documentation is an AST field and follows the `inside-toplevel` matching
-  #|  mode
+  #|- source locations, comments, and whitespace formatting do not participate in
+  #|  matching; top-level documentation is an AST field and follows the
+  #|  `inside-toplevel` matching mode
   #|
   #|The scanner does not type-check shapes and does not resolve names semantically.
   #|For example, two imported names that refer to the same definition compare as
@@ -491,8 +495,9 @@ let _embed_rulespec_md : String =
   #|
   #|A `const` metavar captures a parsed MoonBit constant. In expression position,
   #|it matches `Expr::Constant`; in pattern position, it matches `Pattern::Constant`.
-  #|It compares the parser AST constant kind and value only; it does not type-check
-  #|or normalize equivalent values.
+  #|It compares the parser AST constant kind and preserved source spelling; it does
+  #|not type-check or normalize equivalent values. For example, `1000` and `1_000`
+  #|do not necessarily compare as the same constant.
   #|
   #|Example:
   #|

e2etests/SCAN.md

@@ -225,6 +225,26 @@ source:
 4 |   render("raw")
 ```
 
+## Constant source spelling
+
+Constant equality preserves the spelling stored in the parser AST instead of
+normalizing numeric values. A literal `1000` pattern therefore matches only the
+identically spelled call; the equivalent `1_000` call is omitted.
+
+```mooncram
+$ cd "$TESTDIR"/.. && moonrun "$TESTDIR"/moongrep.wasm -- scan --output-json --pattern 'literal(1000)' testdata/constant-spelling/sample.mbt | sed -n 's/.*"matched_source":"\(.*\)","source_context".*/\1/p'
+literal(1000)
+```
+
+The same comparison applies when a named `const` metavariable is repeated.
+Pairs with consistent spelling match, while `repeated(1000, 1_000)` does not.
+
+```mooncram
+$ cd "$TESTDIR"/.. && moonrun "$TESTDIR"/moongrep.wasm -- scan --output-json --pattern 'repeated($(value:const), $(value:const))' testdata/constant-spelling/sample.mbt | sed -n 's/.*"matched_source":"\(.*\)","source_context".*/\1/p'
+repeated(1000, 1000)
+repeated(1_000, 1_000)
+```
+
 ## Rule filtering
 
 Loading the prefilter rule directory runs both rules and reports their matches

testdata/constant-spelling/sample.mbt

@@ -0,0 +1,8 @@
+///|
+fn constant_spellings {
+  literal(1000)
+  literal(1_000)
+  repeated(1000, 1000)
+  repeated(1_000, 1_000)
+  repeated(1000, 1_000)
+}