Merge branch 'yasu/branch-filter'

* yasu/branch-filter:
  rule: use keyword "any" for global filter override
  docs: s/if absent/default/
  test: use filter_main_branch in test config
  rule: use main_branch_name for global filtering
  docs: clean up prefix rule fields table
  docs: info about branch filter
  tests: add cases for local+default branch filter
  rule: distinguish undeclared vs empty local filter
  rule: add global `default_branch_filters`
  rule: add `branch_filters` prefix rule

Author: yasunariw

documentation/config_docs.md

@@ -29,7 +29,7 @@ Refer [here](https://docs.github.com/en/free-pro-team@latest/developers/webhooks
 
 | value | description | optional | default |
 |-|-|-|-|
-| `main_branch_name` | main branch used for the repo; filtering notifications about merges of main into other branches | Yes | - |
+| `main_branch_name` | main branch used for the repo; filtering notifications about merges of main into other branches, and constraining prefix rule application | Yes | - |
 | `label_rules` | label rules config object | No | - |
 | `prefix_rules` | prefix rules config object | No | - |
 | `status_rules` | status rules config object | No | - |
@@ -97,6 +97,7 @@ A **label rule** specifies whether or not a Slack channel should be notified, ba
 ```json
 "prefix_rules": {
     "default_channel": "default",
+    "filter_main_branch": true,
     "rules": [
         {
             "match": [
@@ -109,6 +110,7 @@ A **label rule** specifies whether or not a Slack channel should be notified, ba
                 "backend/megaindex",
                 "backend/ahrefskit"
             ],
+            "branch_filters": "any",
             "channel": "backend"
         },
         {
@@ -117,16 +119,27 @@ A **label rule** specifies whether or not a Slack channel should be notified, ba
     ]
 },
 ```
+| value | description | default |
+|-|-|-|
+| `default_channel` | same behavior as label rule `default_channel` |  |
+| `filter_main_branch` | if true and `main_branch_name` is declared, use main branch to filter rules that have no local filter; otherwise, don't apply branch filtering and show `distinct` commits only | false |
+| `rules` | list of `prefix_rule` objects | required field |
 
 ### Prefix Rule
 
 A **prefix rule** specifies whether or not a Slack channel should be notified, based on the filenames present in the commits associated with the given payload. The semantics for the `match` and `ignore` fields are the same as those for label rules (see above).
 
-| value | description | optional | default |
-|-|-|-|-|
-| `match` | if commit files have any prefix in this list, they should be routed to the channel | Yes | all prefixes matched if no list provided |
-| `ignore` | if commit files have any prefix in this list, they shouldn't be routed to the channel (even if they have any `match` prefixes) | Yes | - |
-| `channel` | channel to notify if the rule is matched | No | - |
+Default behavior is to apply each rule regardless of what branch is pushed, and when a rule is matched, show its `distinct` commits only.
+Branch filters limit rule application to selected branches, and shows _all_ commits on match.
+The filters can be declared globally with `filter_main_branch` (see above), or locally per rule with `branch_filters`, where the latter takes precedence.
+To ignore a globally declared filter for a single rule, declare one locally with value "any", as shown in the example above.
+
+| value | description | default |
+|-|-|-|
+| `match` | if commit files have any prefix in this list, they should be routed to the channel | all prefixes matched |
+| `ignore` | if commit files have any prefix in this list, they shouldn't be routed to the channel (even if they have any `match` prefixes) | fall back on `match` field behavior |
+| `branch_filters` | consider commits only if pushed ref branch is in this list; set to "any" to ignore `filter_main_branch` for this rule | fall back on `filter_main_branch` field behavior (see above) |
+| `channel` | channel to notify if the rule is matched | required field |
 
 ## Status Options
 

lib/action.ml

@@ -15,20 +15,24 @@ module Action (Github_api : Api.Github) (Slack_api : Api.Slack) = struct
   let partition_push (cfg : Config_t.config) n =
     let default = Option.to_list cfg.prefix_rules.default_channel in
     let rules = cfg.prefix_rules.rules in
+    let branch = Github.commits_branch_of_ref n.ref in
+    let main_branch = if cfg.prefix_rules.filter_main_branch then cfg.main_branch_name else None in
+    let filter_by_branch = Rule.Prefix.filter_by_branch ~branch ~main_branch in
     n.commits
-    |> List.filter ~f:(fun c -> c.distinct)
     |> List.filter ~f:(fun c ->
-         let branch = Github.commits_branch_of_ref n.ref in
          let skip = Github.is_main_merge_message ~msg:c.message ~branch cfg in
          if skip then log#info "main branch merge, ignoring %s: %s" c.id (first_line c.message);
          not skip)
     |> List.concat_map ~f:(fun commit ->
+         let rules = List.filter ~f:(filter_by_branch ~distinct:commit.distinct) rules in
          let matched_channel_names =
            Github.modified_files_of_commit commit
            |> List.filter_map ~f:(Rule.Prefix.match_rules ~rules)
            |> List.dedup_and_sort ~compare:String.compare
          in
-         let channel_names = if List.is_empty matched_channel_names then default else matched_channel_names in
+         let channel_names =
+           if List.is_empty matched_channel_names && commit.distinct then default else matched_channel_names
+         in
          List.map channel_names ~f:(fun n -> n, commit))
     |> Map.of_alist_multi (module String)
     |> Map.map ~f:(fun commits -> { n with commits })

lib/atd_adapters.ml

@@ -0,0 +1,48 @@
+module List_or_default_field = struct
+  open Atdgen_runtime.Json_adapter
+
+  module type Param = sig
+    (** the name of the field *)
+    val field_name : string
+
+    (** string alias a user can use to denote default value *)
+    val default_alias : string
+
+    (** Yojson representation of default value *)
+    val default_value : Yojson.Safe.t
+  end
+
+  module Make (P : Param) : S = struct
+    open P
+
+    let assoc_replace l k v = List.map (fun x -> if fst x = k then k, v else x) l
+
+    let normalize x =
+      match x with
+      | `Assoc fields ->
+        begin
+          match List.assoc field_name fields with
+          | `String s when String.equal s default_alias -> `Assoc (assoc_replace fields field_name default_value)
+          | _ | (exception Not_found) -> x
+        end
+      | malformed -> malformed
+
+    let restore x =
+      match x with
+      | `Assoc fields ->
+        begin
+          match List.assoc field_name fields with
+          | value when Yojson.Safe.equal value default_value -> `Assoc (assoc_replace fields field_name (`String "any"))
+          | _ | (exception Not_found) -> x
+        end
+      | malformed -> malformed
+  end
+end
+
+module Branch_filters_adapter = List_or_default_field.Make (struct
+  let field_name = "branch_filters"
+
+  let default_alias = "any"
+
+  let default_value = `List []
+end)

lib/config.atd

@@ -12,6 +12,7 @@ type status_rules = {
   files they are related to. *)
 type prefix_rules = {
   ?default_channel: string nullable; (* if none of the rules is matching *)
+  ~filter_main_branch <ocaml default="false">: bool;
   rules: prefix_rule list;
 }
 

lib/rule.atd

@@ -66,8 +66,9 @@ type status_rule = {
 type prefix_rule = {
   ?allow <json name="match"> : string list nullable;
   ?ignore : string list nullable;
+  ?branch_filters : string list nullable;
   channel_name <json name="channel"> : string;
-}
+} <json adapter.ocaml="Atd_adapters.Branch_filters_adapter">
 
 (* A payload matches a label rule with a channel name if absent from the ignore list
    and present in the allow list. Both `allow` and `ignore` are optional. If `allow`

lib/rule.ml

@@ -39,6 +39,18 @@ module Status = struct
 end
 
 module Prefix = struct
+  (** Filters prefix rules based on branch filtering config and current commit.
+      Prioritizes local filters over main branch one. Only allows distinct commits
+      if no filter is matched. *)
+  let filter_by_branch ~branch ~main_branch ~distinct rule =
+    match rule.branch_filters with
+    | Some (_ :: _ as filters) -> List.mem filters branch ~equal:String.equal
+    | Some [] -> distinct
+    | None ->
+    match main_branch with
+    | Some main_branch -> String.equal main_branch branch
+    | None -> distinct
+
   (** `match_rules f rs` returns the channel name of a rule in `rs` that matches
       file name `f` with the longest prefix, if one exists. A rule `r` matches
       `f` with prefix length `l`, if `f` has no prefix in `r.ignore` and `l` is