add --guard

Author: myfreess

SKILL.md

@@ -11,12 +11,13 @@ Run the scanner with a rule directory and an optional scan target directory or
 ```bash
 moon runwasm moonbit-community/moongrep -- scan --rules path/to/rules path/to/src
 moon runwasm moonbit-community/moongrep -- scan --pattern 'target()' path/to/src
+moon runwasm moonbit-community/moongrep -- scan --pattern '$(callee:id)()' --guard '{$callee: "^safe_"}' path/to/src
 ```
 
 Synopsis:
 
 ```text
-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]
+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> [--guard <guard>])... [scan-root]
 ```
 
 The scanner is available through the `scan` subcommand. `--rules` / `-r` is
@@ -29,7 +30,9 @@ 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.
+Repeated `--pattern` values are appended as separate anonymous rules. Use
+`--guard <guard>` after an anonymous `--pattern` to attach a YAML guard map with
+`$`-prefixed metavariable keys, using the same schema as rule-file `guard`.
 
 Use `--exclude-dir <dir>...` to skip directory names or paths while recursively
 scanning the source tree. When passing multiple excluded directories after one
@@ -38,8 +41,9 @@ flag, put `scan-root` before `--exclude-dir`; repeated `--exclude-dir <dir>` and
 
 Usage errors print a message and exit with code 2: missing `scan` command,
 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
+`--enable-builtin-rules`), missing option value, misplaced or malformed
+`--guard`, 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.
 
@@ -59,6 +63,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 --pattern '$(callee:id)()' --guard '{$callee: "^safe_"}'
 moon runwasm moonbit-community/moongrep -- scan --enable-builtin-rules
 ```
 

cli_args.mbt

@@ -9,7 +9,7 @@ priv suberror CliError {
 priv struct CliOptions {
   rules_root : String?
   rule_file : String?
-  patterns : Array[String]
+  patterns : Array[@rule_model.RulePatternSpec]
   scan_root : String
   exclude_dirs : Array[String]
   verbose : Bool
@@ -59,6 +59,11 @@ let scan_command : @argparse.Command = @argparse.Command(
       action=@argparse.OptionAction::Append,
       about="Anonymous structural pattern to match.",
     ),
+    @argparse.OptionArg(
+      "guard",
+      action=@argparse.OptionAction::Append,
+      about="YAML guard map for the preceding anonymous pattern.",
+    ),
     @argparse.OptionArg(
       "exclude-dir",
       action=@argparse.OptionAction::Append,
@@ -218,6 +223,7 @@ fn dump_cli_command(
 fn scan_cli_options(
   scan_matches : @argparse.Matches,
   env : Map[String, String],
+  argv : Array[String],
 ) -> CliOptions raise {
   let verbose = cli_flag_enabled(scan_matches.flags, "verbose")
   let enable_builtin_rules = cli_flag_enabled(
@@ -227,7 +233,7 @@ fn scan_cli_options(
   let no_color = no_color_enabled(env)
   let rules_root = last_cli_value(scan_matches.values, "rules")
   let rule_file = last_cli_value(scan_matches.values, "rule")
-  let patterns = all_cli_values(scan_matches.values, "pattern")
+  let patterns = parse_scan_pattern_specs(argv)
   let exclude_dirs = normalize_scan_exclude_dirs(
     all_cli_values(scan_matches.values, "exclude-dir"),
   )
@@ -258,6 +264,115 @@ fn scan_cli_options(
   }
 }
 
+///|
+fn parse_scan_pattern_specs(
+  argv : Array[String],
+) -> Array[@rule_model.RulePatternSpec] raise {
+  let patterns : Array[@rule_model.RulePatternSpec] = []
+  let has_guard : Array[Bool] = []
+  let mut index = 1
+  while index < argv.length() {
+    let arg = argv[index]
+    if arg == "--pattern" {
+      if index + 1 >= argv.length() {
+        raise CliError::Usage(
+          message="missing value for --pattern",
+          exit_code=2,
+        )
+      }
+      patterns.push({ shape: argv[index + 1], guards: {} })
+      has_guard.push(false)
+      index += 2
+    } else if arg.has_prefix("--pattern=") {
+      patterns.push({
+        shape: arg["--pattern=".length():].to_owned(),
+        guards: {},
+      })
+      has_guard.push(false)
+      index += 1
+    } else if arg == "--guard" {
+      if index + 1 >= argv.length() {
+        raise CliError::Usage(message="missing value for --guard", exit_code=2)
+      }
+      attach_scan_guard(
+        patterns,
+        has_guard,
+        parse_cli_guard_map(argv[index + 1]),
+      )
+      index += 2
+    } else if arg.has_prefix("--guard=") {
+      attach_scan_guard(
+        patterns,
+        has_guard,
+        parse_cli_guard_map(arg["--guard=".length():].to_owned()),
+      )
+      index += 1
+    } else {
+      index += 1
+    }
+  }
+  patterns
+}
+
+///|
+fn attach_scan_guard(
+  patterns : Array[@rule_model.RulePatternSpec],
+  has_guard : Array[Bool],
+  guards : Map[String, String],
+) -> Unit raise {
+  let mut index = patterns.length()
+  while index > 0 {
+    index -= 1
+    if !has_guard[index] {
+      let shape = patterns[index].shape
+      patterns[index] = { shape, guards }
+      has_guard[index] = true
+      return
+    }
+  }
+  let message = if patterns.is_empty() {
+    "--guard requires a preceding --pattern"
+  } else {
+    "duplicate --guard for anonymous --pattern"
+  }
+  raise CliError::Usage(message~, exit_code=2)
+}
+
+///|
+fn parse_cli_guard_map(source : String) -> Map[String, String] raise {
+  let docs = @yaml.Yaml::load_from_string(source) catch {
+    err =>
+      raise CliError::Usage(message="invalid --guard YAML: \{err}", exit_code=2)
+  }
+  if docs.length() != 1 {
+    raise CliError::Usage(
+      message="--guard must contain exactly one YAML document",
+      exit_code=2,
+    )
+  }
+  guard docs[0] is Map(map) else {
+    raise CliError::Usage(message="--guard must be a YAML mapping", exit_code=2)
+  }
+  let guards : Map[String, String] = {}
+  for key, value in map {
+    if !key.has_prefix("$") || key.length() <= 1 {
+      raise CliError::Usage(
+        message="guard key \{key} must be a $-prefixed metavar name",
+        exit_code=2,
+      )
+    }
+    match value {
+      String(regex_source) => guards[key] = regex_source
+      _ =>
+        raise CliError::Usage(
+          message="--guard.\{key} must be a string",
+          exit_code=2,
+        )
+    }
+  }
+  guards
+}
+
 ///|
 fn normalize_scan_exclude_dir_args(argv : Array[String]) -> Array[String] raise {
   if argv.length() == 0 || argv[0] != "scan" {
@@ -318,7 +433,7 @@ fn parse_cli_command(
   }
   match matches.subcommand {
     Some(("scan", scan_matches)) =>
-      ("scan", Some(scan_cli_options(scan_matches, env)), None)
+      ("scan", Some(scan_cli_options(scan_matches, env, normalized_argv)), None)
     Some(("docs", docs_matches)) => docs_cli_command(docs_matches)
     Some(("dump", dump_matches)) => dump_cli_command(dump_matches)
     _ => raise CliError::Usage(message="missing required command", exit_code=2)