tighten #moongrep.skip contract

Author: myfreess

SKILL.md

@@ -143,9 +143,41 @@ moongrep scan --pattern 'inspect($_, content="true")' --output-json
 ```
 
 JSON match records are written to standard output, one per line. Verbose
-traversal messages and parse warnings are written to standard error. When no
+traversal messages and scan warnings are written to standard error. When no
 match is found, JSON mode writes nothing to standard output.
 
+## Suppressing Structural Rules in Source
+
+Use a bare `#moongrep.skip` attribute to suppress structural rules for one
+top-level item:
+
+```moonbit
+#moongrep.skip
+fn generated_adapter {
+  legacy_call()
+}
+```
+
+The attribute is supported on function definitions, impl methods, top-level
+`let` definitions, tests, and view declarations. It suppresses all structural
+rules within the attached item. Taint analysis is never suppressed and still
+runs on marked function definitions and impl methods.
+
+The attribute does not accept a payload. Forms such as `#moongrep.skip()`,
+`#moongrep.skip(true)`, `#moongrep.skip(false)`, other payloads, and malformed
+payloads do not suppress structural rules. Each invalid payload produces this
+warning on standard error, and scanning continues without changing the exit
+status:
+
+```text
+warning: <location>: #moongrep.skip does not accept a payload; use bare #moongrep.skip
+```
+
+Unrelated attributes such as `#skip` and `#other.skip` are ignored. If an item
+has both a valid bare attribute and one or more invalid payload forms, each
+invalid form produces a warning while the bare attribute still suppresses
+structural rules.
+
 ## Pattern Guards
 
 Use `--guard` to add filters to an expression pattern. The filters apply to

SKILL_CN.md

@@ -112,9 +112,36 @@ user.name == other.name
 moongrep scan --pattern 'inspect($_, content="true")' --output-json
 ```
 
-JSON 匹配记录会逐行写入标准输出。详细遍历信息和解析 warning 会写入标准错误；
+JSON 匹配记录会逐行写入标准输出。详细遍历信息和扫描 warning 会写入标准错误；
 JSON 模式下没有命中时，标准输出为空。
 
+## 在源码中抑制结构规则
+
+使用裸 `#moongrep.skip` 属性，可以抑制一个顶层项中的结构规则：
+
+```moonbit
+#moongrep.skip
+fn generated_adapter {
+  legacy_call()
+}
+```
+
+该属性支持函数定义、impl 方法、顶层 `let` 定义、test 和 view 声明。它会抑制
+所附顶层项内的全部结构规则。污点分析不会被抑制；对于带标记的函数定义和
+impl 方法，污点分析仍会运行。
+
+该属性不接受 payload。`#moongrep.skip()`、`#moongrep.skip(true)`、
+`#moongrep.skip(false)`、其他 payload 和畸形 payload 都不会抑制结构规则。
+每个无效 payload 都会在标准错误输出以下 warning，扫描会继续，退出码不变：
+
+```text
+warning: <location>: #moongrep.skip does not accept a payload; use bare #moongrep.skip
+```
+
+`#skip`、`#other.skip` 等无关属性会被忽略。如果同一顶层项同时带有有效的裸属性
+和一个或多个无效 payload，每个无效形式仍会产生 warning，而裸属性仍会抑制
+结构规则。
+
 ## 模式附加条件
 
 `--guard`选项可以为表达式模式添加额外的筛选条件，筛选条件的对象是表达式模式里面的元变量捕获的内容。

TODO.md

@@ -8,12 +8,6 @@
   an explicit kind for cross-position reuse, improving the diagnostic, or
   adding a storage-path metavariable kind.
 
-- Define and document the contract for `#moongrep.skip`. It is currently
-  recognized on functions, impls, top-level lets, tests, and views; ignores
-  any payload, including `false`; and suppresses structural rules but not
-  taint analysis. If it remains public, cover those semantics in the user and
-  e2e documentation. Otherwise, make it internal or remove it.
-
 - 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.

cli/json_render.mbt

@@ -67,9 +67,9 @@ fn render_scan_hit_json(hit : ScanHit) -> String {
 }
 
 ///|
-// JSON stdout is finding-only: scan trace, parse warnings, and the human
+// JSON stdout is finding-only: scan trace, scan warnings, and the human
 // no-match summary are omitted so every non-empty line is a machine-readable
-// finding record. Parse warnings are written separately to stderr.
+// finding record. Scan warnings are written separately to stderr.
 fn render_directory_scan_json(result : DirectoryScanResult) -> String {
   let records : Array[String] = []
   for hit in result.hits {

cli/json_render_wbtest.mbt

@@ -84,17 +84,21 @@ test "json directory output contains only one line per finding" {
     render_directory_scan_json({
       scan_trace: ["trace"],
       hits: [],
-      skipped_files: [
-        { file: "bad.mbt", block_start_line: None, reason: "parse failed" },
+      warnings: [
+        Parse({
+          file: "bad.mbt",
+          block_start_line: None,
+          reason: "parse failed",
+        }),
       ],
     }),
     content="",
   )
   let rendered = render_directory_scan_json({
     scan_trace: ["trace"],
     hits: [render_test_hit(3, 3), render_test_hit(8, 8)],
-    skipped_files: [
-      { file: "bad.mbt", block_start_line: None, reason: "parse failed" },
+    warnings: [
+      Parse({ file: "bad.mbt", block_start_line: None, reason: "parse failed" }),
     ],
   })
   let records = rendered.split("\n").to_array()

cli/render.mbt

@@ -1,5 +1,5 @@
 ///|
-// Renders warnings first and match hits second so parse failures never hide
+// Renders warnings first and match hits second so scan diagnostics never hide
 // successful findings from other files.
 fn render_directory_scan_result(
   result : DirectoryScanResult,
@@ -9,7 +9,7 @@ fn render_directory_scan_result(
   if result.scan_trace.length() > 0 {
     sections.push(result.scan_trace.join("\n"))
   }
-  let warnings = render_skipped_file_warnings(result.skipped_files)
+  let warnings = render_scan_warnings(result.warnings)
   if warnings != "" {
     sections.push(warnings)
   }
@@ -26,20 +26,25 @@ fn render_directory_scan_result(
 }
 
 ///|
-fn render_skipped_file_warnings(skipped_files : Array[SkippedFile]) -> String {
-  let warnings : Array[String] = []
-  for skipped in skipped_files {
-    warnings.push(render_skipped_file_warning(skipped))
+fn render_scan_warnings(scan_warnings : Array[ScanWarning]) -> String {
+  let rendered : Array[String] = []
+  for warning in scan_warnings {
+    rendered.push(render_scan_warning(warning))
   }
-  warnings.join("\n")
+  rendered.join("\n")
 }
 
 ///|
-fn render_skipped_file_warning(skipped : SkippedFile) -> String {
-  if skipped.block_start_line is Some(line) {
-    "warning: skipping \{skipped.file} block starting at line \{line}: \{skipped.reason}"
-  } else {
-    "warning: skipping \{skipped.file}: \{skipped.reason}"
+fn render_scan_warning(warning : ScanWarning) -> String {
+  match warning {
+    Parse(parse_warning) =>
+      if parse_warning.block_start_line is Some(line) {
+        "warning: skipping \{parse_warning.file} block starting at line \{line}: \{parse_warning.reason}"
+      } else {
+        "warning: skipping \{parse_warning.file}: \{parse_warning.reason}"
+      }
+    InvalidMoongrepSkipPayload(file, loc) =>
+      "warning: \{format_location(file, loc)}: #moongrep.skip does not accept a payload; use bare #moongrep.skip"
   }
 }