Merge branch 'edge'

For some reason. Removing blocks fixed rendering error

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: [FoxxMD]
+custom: ["bitcoincash:qqmpsh365r8n9jhp4p8ks7f7qdr7203cws4kmkmr8q"]

README.md

@@ -109,7 +109,7 @@ CM comes equipped with a dashboard designed for use by both moderators and bot o
   * View **real-time logs** of what the bot is doing on your subreddit
   * **Run bot on any permalink**
 
-![Subreddit View](docs/screenshots/subredditStatus.jpg)
+![Subreddit View](docs/images/subredditStatus.jpg)
 
 ### Bot Setup/Authentication
 
@@ -117,11 +117,11 @@ A bot oauth helper allows operators to define oauth credentials/permissions and
 
 Operator view/invite link generation:
 
-![Oauth View](docs/screenshots/oauth.jpg)
+![Oauth View](docs/images/oauth.jpg)
 
 Moderator view/invite and authorization:
 
-![Invite View](docs/screenshots/oauth-invite.jpg)
+![Invite View](docs/images/oauth-invite.jpg)
 
 ### Configuration Editor
 
@@ -134,7 +134,7 @@ A built-in editor using [monaco-editor](https://microsoft.github.io/monaco-edito
 * Authenticated view loads subreddit configurations by simple link found on the subreddit dashboard
 * Switch schemas to edit either subreddit or operator configurations
 
-![Configuration View](docs/screenshots/editor.jpg)
+![Configuration View](docs/images/editor.jpg)
 
 ## License
 

docs/README.md

@@ -5,6 +5,7 @@
 * [Getting Started](#getting-started)
 * [How It Works](#how-it-works)
 * [Concepts](#concepts)
+  * [Run](#runs)
   * [Check](#checks)
   * [Rule](#rule)
     * [Examples](#available-rules)
@@ -36,31 +37,61 @@ Review **at least** the **How It Works** and **Concepts** below, then:
 
 Where possible Context Mod (CM) uses the same terminology as, and emulates the behavior, of **automoderator** so if you are familiar with that much of this may seem familiar to you.
 
+### Diagram
+
+Expand the section below for a simplified flow diagram of how CM processes an incoming Activity. Then refer the text description of the diagram below as well as [Concepts](#Concepts) for descriptions of individual components.
+
+<details>
+<summary>Diagram</summary>
+
+![Flow Diagram](/docs/images/diagram-highlevel.jpg)
+
+</details>
+
 CM's lifecycle looks like this:
 
 #### 1) A new event in your subreddit is received by CM
 
 The events CM watches for are configured by you. These can be new modqueue/unmoderated items, submissions, or comments.
 
-#### 2) CM sequentially processes each Check in your configuration
+#### 2) CM sequentially processes each Run in your configuration
+
+A [**Run**](#Runs) is made up of a set of [**Checks**](#Checks)
+
+#### 3) CM sequentially processes each Check in the current Run
 
 A **Check** is a set of:
 
-* One or more **Rules** that define what conditions should **trigger** this Check
-* One or more **Actions** that define what the bot should do once the Check is **triggered**
+* One or more [**Rules**](#Rule) that define what conditions should **trigger** this Check
+* One or more [**Actions**](#Action) that define what the bot should do once the Check is **triggered**
 
-#### 3) Each Check is processed, *in order*, until a Check is triggered
+#### 4) Each Check is processed, *in order*, until a Check is **triggered**
 
-Once a Check is **triggered** no more Checks will be processed. This means all subsequent Checks in your configuration (in the order you listed them) are basically skipped.
+In CM's default configuration, once a Check is **triggered** no more Checks will be processed. This means all subsequent Checks in this Run (in the order you listed them) are skipped.
 
-#### 4) All Actions from that Check are executed
+#### 5) All Actions from the triggered Check are executed
 
-After all Actions are executed CM returns to waiting for the next Event.
+After all **Actions** from the triggered **Check** are executed CM begins processing the next **Run**
+
+#### 6) Rinse and Repeat from #3
+
+Until all Runs have been processed.
 
 ## Concepts
 
 Core, high-level concepts regarding how CM works.
 
+### Runs
+
+A **Run** is made up of a set of **Checks** that represent a group of related behaviors the bot should check for or perform -- that are independent of any other behaviors the Bot should perform.
+
+An example of Runs:
+
+* A group of Checks that look for missing flairs on a user or a new submission and flair accordingly
+* A group of Checks that detect spam or self-promotion and then remove those activities
+
+Both group of Checks are independent of each other (don't have any patterns or actions in common). Learn more about using [Runs and **Flow Control** to control how CM behaves.](/docs/examples/advancedConcepts/flowControl.md)
+
 ### Checks
 
 A **Check** is the main logical unit of behavior for the bot. It is equivalent to "if X then Y". A Check is comprised of:
@@ -68,7 +99,7 @@ A **Check** is the main logical unit of behavior for the bot. It is equivalent t
 * One or more **Rules** that are tested against an **Activity**
 * One of more **Actions** that are performed when the **Rules** are satisfied
 
-The bot's configuration can be made up of one or more **Checks** that are processed **in the order they are listed in the configuration.**
+A Run can be made up of one or more **Checks** that are processed **in the order they are listed in the Run.**
 
 Once a Check is **triggered** (its Rules are satisfied and Actions performed) all subsequent Checks are skipped.
 
@@ -87,7 +118,7 @@ A **Rule** is some set of **criteria** (conditions) that are tested against an A
 
 There are generally three main properties for a Rule:
 
-* **Critiera** -- The conditions/values you want to test for.
+* **Criteria** -- The conditions/values you want to test for.
 * **Activities Window** -- If applicable, the range of activities that the **criteria** will be tested against.
 * **Rule-specific options** -- Any number of options that modify how the **criteria** are tested.
 
@@ -149,6 +180,7 @@ An **Action** is some action the bot can take against the checked Activity (comm
 
 * Remove (Comment/Submission)
 * Flair (Submission)
+* User Flair (Submission/Comment)
 * Ban (User)
 * Approve (Comment/Submission)
 * Comment (Reply to Comment/Submission)
@@ -160,12 +192,12 @@ For detailed explanation and options of what individual Actions can do [see the
 
 ### Filters
 
-**Checks, Rules, and Actions** all have two additional (optional) criteria "tests". These tests behave differently than rule/check triggers in that:
+**Runs, Checks, Rules, and Actions** all have two additional (optional) criteria "tests". These tests behave differently than rule/check triggers in that:
 
 * When they **pass** the thing being tested continues to process as usual
 * When they **fail** the thing being tested **is skipped, not failed.**
 
-For **Checks** and **Actions** skipping means that the thing is not processed. The Action is not run, the Check is not triggered.
+For **Runs**, **Checks**, and **Actions** skipping means that the thing is not processed. The Action is not run, the Check is not triggered.
 
 In the context of **Rules** (in a Check) skipping means the Rule does not get run BUT it does not fail. The Check will continue processing as if the Rule did not exist. However, if ALL Rules in a Check are skipped then the Check does "fail" (is not triggered).
 

docs/examples/README.md

@@ -21,6 +21,7 @@ This directory contains example of valid, ready-to-go configurations for Context
   * [Author and post flairs](/docs/examples/onlyfansFlair)
 * [Toolbox User Notes](/docs/examples/userNotes)
 * [Advanced Concepts](/docs/examples/advancedConcepts)
+  * [Flow Control](/docs/examples/advancedConcepts/flowControl.md)
   * [Rule Sets](/docs/examples/advancedConcepts/ruleSets.json5)
   * [Name Rules](/docs/examples/advancedConcepts/ruleNameReuse.json5)
   * [Check Ordering](/docs/examples/advancedConcepts)

docs/examples/advancedConcepts/README.md

@@ -2,11 +2,13 @@
 
 See **Rule Name Reuse Examples [YAML](/docs/examples/advancedConcepts/ruleNameReuse.yaml) | [JSON](/docs/examples/advancedConcepts/ruleNameReuse.json5)**
 
-### Check Order
+### Check Order and Flow Control
 
 Checks are run in the order they appear in your configuration, therefore you should place your highest requirement/severe action checks at the top and lowest requirement/moderate actions at the bottom.
 
-This is so that if an Activity warrants a more serious reaction that Check is triggered first rather than having a lower requirement check with less severe actions triggered and causing all subsequent Checks to be skipped.
+This is so that if an Activity warrants a more serious reaction that Check is triggered first rather than having a lower requirement check with less severe actions triggered and causing all subsequent Checks to be skipped. 
+
+This behavior can also be controlled modified using [Flow Control](/docs/examples/advancedConcepts/flowControl.md)
 
 * Attribution >50% AND Repeat Activity 8x AND Recent Activity in 2 subs => remove submission + ban
 * Attribution >20% AND Repeat Activity 4x AND Recent Activity in 5 subs => remove submission + flair user restricted

docs/examples/advancedConcepts/flowControl.md

@@ -0,0 +1,228 @@
+Context Mod's behavior after a **Check** has been processed can be configured by a user. This allows a subreddit to control exactly what Runs/Checks will be processed based on the outcome (triggered or not) of a Check.
+
+# Table of Contents
+
+- [Post-Check Properties](#post-check-properties)
+    * [State](#state)
+    * [Behavior](#behavior)
+        + [Next](#next)
+        + [Next Run](#next-run)
+        + [Stop](#stop)
+        + [Goto](#goto)
+            - [Goto Syntax](#goto-syntax)
+- [Default Behaviors](#default-behaviors)
+    * [Defining Default Behaviors](#defining-default-behaviors)
+- [Examples](#examples)
+
+# Post-Check Properties
+
+## State
+
+When a Check is finished processing it can be in one of two states:
+
+* **Triggered** -- The **Rules** defined in the Check were **triggered** which caused the **Actions** for the Check to be run
+* **Failure** -- The **Rules** defined in the check were **not triggered**, based on the conditions that were set (either from the [Check condition](/docs/README.md#Checks) or [Rule Sets](/docs/examples/advancedConcepts/README.md#Rule-Sets)), and no **Actions** were run
+
+The behavior CM follows is based on which state it is in. The behavior can be specified **by one or both** of these **state properties** on the Check configuration:
+
+* `postTrigger` -- Specifies what behavior to take when the check is **triggered**
+* `postFail` -- Specifies what behavior to take when the check is **not triggered**
+
+## Behavior
+
+There are **four** behaviors CM can take. Both/either **state properties** can be defined with **any behavior.**
+
+### Next
+
+The **Next** behavior tells CM to continue to whatever comes *after the Check that was just processed.* This could be another Check or, if this is the last Check in a Run, the next Run.
+
+NOTE: `next` is the **default behavior** for the `postFail` state
+
+Example
+
+```yaml
+- name: MyCheck
+  # ...
+  postFail: next # if Check is not triggered then CM will start processing AnotherCheck
+  
+- name: AnotherCheck
+  # ...
+```
+
+### Next Run
+
+The **Next Run** behavior tells CM to **skip all remaining Checks in the current Run and start processing the next Run in order.**
+
+NOTE: `nextRun` is the **default behavior** for the `postTrigger` state
+
+Example
+
+```yaml
+runs:
+  - name: MyFirstRun
+    checks:
+      - name: MyCheck
+        # ...
+        postTrigger: nextRun # if Check is triggered then CM will SKIP mySecondCheck and instead start processing MySecondRun
+      - name: MySecondCheck
+        # ...
+        
+  - name: MySecondRun
+    checks:
+      - name: FooCheck
+        # ...
+```
+
+### Stop
+
+The **Stop** behavior tells CM to **stop processing the Activity entirely.** This means all remaining Checks and Runs will not be processed.
+
+Example
+
+```yaml
+runs:
+  - name: MyFirstRun
+    checks:
+      - name: MyCheck
+        # ...
+        postTrigger: stop # if Check is triggered CM will NOT process MySecondCheck OR MySecondRun. The activity is "done" being processed at this point
+      - name: MySecondCheck
+        # ...
+        
+  - name: MySecondRun
+    checks:
+      - name: FooCheck
+        # ...
+```
+
+### Goto
+
+The **Goto** behavior is an **advanced** behavior that allows you to specify that CM should "jump to" a specific place in your configuration, regardless of order/location, and continue processing the Activity from there. It can be used to do things like:
+
+* create a loop/iteration to have CM re-process the Activity on an earlier executed part of your configuration because a later part modified the Activity (flaired, etc...)
+* use a Check as a simplified *switch statement*
+
+**Goto should be use with care.** If you do not fully understand how this mechanism works you should avoid using it as **most** behaviors can be accomplished using the other behaviors. 
+
+As an additional protection **goto depth is limited to 1 by default** which means if a `goto` would be executed more than once during an Activity's lifecycle CM will automatically stop processing that Activity. The `maxGotoDepth` can be raised by the [**Bot Operator**](/docs/gettingStartedOperator.md) per subreddit.
+
+#### Goto Syntax
+
+Location to "jump to" can be specified as:
+
+* **Run** -- `goto:myRunName`
+* **Check inside a different Run** -- `goto:myRunName.aCheckInsideTheRun`
+* **Check inside the current Run** -- `goto:.myCheck`
+
+Example
+
+```yaml
+runs:
+  - name: MyFirstRun
+    checks:
+      - name: FirstCheck
+        # ...
+      - name: MyCheck
+        # ...
+        postTrigger: 'goto:MyThirdRun' # jump to the run MyThirdRun
+        postFail: 'goto:MySecondRun.BuzzCheck' # jump to the Check BuzzCheck inside the Run MySecondRun
+        
+  - name: MySecondRun
+    checks:
+      - name: FooCheck
+        # ...
+      - name: BuzzCheck
+        # ...
+        
+  - name: MyThirdRun
+    checks:
+      - name: BarCheck
+        # ...
+```
+
+# Default Behaviors
+
+It is **not required** to define post-Check behavior. CM uses sane defaults to mimic the behavior of automoderator as well as what is "intuitive" when reading a configuration -- that logic flows from top-to-bottom in the order it was defined. For each Check like this:
+
+```yaml
+- name: MyCheck
+  kind: comment
+  rules: 
+   # ...
+  actions:
+   # ...
+```
+
+`postTrigger` and `postFail` have default behaviors (mentioned in the sections above) that make the Check end up working like this:
+
+```yaml
+- name: MyCheck
+  kind: comment
+  rules: 
+   # ...
+  actions:
+   # ...
+  postTrigger: nextRun # check is triggered and actions were performed, skip remaining checks and go to the next Run
+  postFail: next # check is not triggered and no actions performed, continue to the next check in this Run
+```
+
+**So if you are fine with all Checks running in order until one triggered there is no need to define post-Check behaviors at all.**
+
+## Defining Default Behaviors
+
+Defining `postTrigger` and/or `postFail` on a **Run** will set the default behavior for any **Checks** in the Run that **do not have an explicit behavior set.**
+
+```yaml
+runs:
+  - name: MyFirstRun
+    postTrigger: stop # all Checks without postTrigger defined will have 'stop' as their behavior
+    checks:
+      - name: FooCheck # postTrigger is 'stop' since it is not defined
+        # ...
+      - name: BarCheck
+        # ...
+        postTrigger: next # overrides default behavior
+```
+
+# Examples
+
+One **Run** with **default behavior** (no post-Check behavior explicitly defined)
+
+```mermaid
+flowchart TB
+    subgraph spam ["(Run) Spam"]
+        b1["(Check) self-promotion"] -- "postFail: next" --> b2
+        b2["(Check) repeat spam"] -- "postFail: next" --> b3
+        b3["(Check) Good user"]
+    end
+    b1 -- "postTrigger: nextRun" --> finish
+    b2 -- "postTrigger: nextRun" --> finish
+    b3 -- "postFail: next" --> finish
+    b3 -- "postTrigger: nextRun" --> finish
+    finish[Processing Finished]
+```
+
+Two **Runs** with **default behavior** (no post-Check behavior explicitly defined)
+
+```mermaid
+flowchart TB
+    subgraph flair ["(Run) Flairing"]
+        a1["(Check) Flair Submission based on history"]-- "postFail: next" -->a2
+        a2["(Check) Flair Submission based on user profile"] -- "postFail: next" --> a3
+        a3["(Check) Flair Submission based on self text"]
+    end
+    a1 -- "postTrigger: nextRun" --> b1
+    a2 -- "postTrigger: nextRun" --> b1
+    a3 -- "postFail: next" --> b1
+    a3 -- "postTrigger: nextRun" --> b1
+    subgraph spam ["(Run) Spam"]
+        b1["(Check) self-promotion"] -- "postFail: next" -->b2
+        b2["(Check) repeat spam"] -- "postFail: next" -->b3
+        b3["(Check) Good user"]
+    end
+    b1 -- "postTrigger: nextRun" --> finish
+    b2 -- "postTrigger: nextRun" --> finish
+    b3 -- "postFail: next" --> finish
+    b3 -- "postTrigger: nextRun" --> finish
+    finish[Processing Finished]
+```

docs/examples/advancedConcepts/flowControl.yaml

@@ -0,0 +1,96 @@
+runs:
+  - name: flairAndCategory
+
+    # Runs inherit the same filters as checks/rules/actions
+    # If these filters fail the Run is skipped and CM processes the next run in order
+    #    authorIs:
+    #    itemIs:
+
+    # Set the default behavior for check trigger/fail
+    #    postTrigger:
+    #    postFail:
+
+    # Defaults can also be set for check authorIs/itemIs
+    # same as at operator/subreddit level - any defined here will override "higher" defaults
+    #    filterCriteriaDefaults:
+
+    checks:
+      - name: goodUserFlair
+        description: flair user if they have decent history in sub
+        kind: submission
+        authorIs:
+          exclude:
+            - flairText: 'Good User'
+        rules:
+          - kind: recentActivity
+            thresholds:
+              - threshold: '> 5'
+                karma: '> 10'
+                subreddits:
+                  - mySubreddit
+        actions:
+          - kind: userflair
+            text: 'Good User'
+        # post-behavior after a check has run. Either the check is TRIGGERED or FAIL
+        # there are 4 possible behaviors for each post-behavior type:
+        #
+        # 'next' => Continue to next check in order
+        # 'nextRun' => Exit the current Run (skip all remaining Checks) and go to the next Run in order
+        # 'stop' => Exit the current Run and finish activity processing immediately (skip all remaining Runs)
+        # 'goto:run[.check]' => Specify a run[.check] to jump to. This can be anywhere in your config. CM will continue to process in order from the specified point.
+        #
+        # GOTO syntax --
+        # 'goto:normalFilters' => go to run "normalFilters"
+        # 'goto:normalFilters.myCheck' => go to run "normalFilters" and start at check "myCheck"
+        # 'goto:.goodUserFlair' => go to check 'goodUserFlair' IN THE SAME RUN currently processing
+        #
+
+        # this means if the check triggers then continue to 'good submission flair'
+        postTrigger: next # default is 'nextRun'
+      #        postFail: # default is 'next'
+
+      - name: good submission flair
+        description: flair submission if from good user
+        kind: submission
+        authorIs:
+          include:
+            - flairText: 'Good User'
+        actions:
+          - kind: flair
+            text: 'Trusted Source'
+          - kind: approve
+        # this means if the check is triggered then stop processing the activity entirely
+        postTrigger: stop
+
+  - name: Determine Suspect
+    checks:
+      - name: is suspect
+        kind: submission
+        rules:
+          - kind: recentActivity
+            thresholds:
+              - subreddits:
+                  - over_18: true
+        actions:
+        # do some actions
+
+        # if check is triggered then go to run 'suspectFilters'
+        postTrigger: 'goto:suspectFilters'
+        # if check is not triggered then go to run 'normalFilters'
+        postFail: 'goto:normalFilters'
+
+  - name: suspectFilters
+    postTrigger: stop
+    authorIs:
+      exclude:
+        - flairText: 'Good User'
+    checks:
+    # some checks for users that are suspicious
+
+
+  - name: normalFilters
+    authorIs:
+      exclude:
+        - flairText: 'Good User'
+    checks:
+    # some checks for general activities

docs/examples/advancedConcepts/ruleNameReuse.json5

@@ -1,75 +1,79 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Auto Remove SP Karma",
-      "description": "Remove submission because author has self-promo >10% and posted in karma subs recently",
-      "kind": "submission",
-      "rules": [
-        // named rules can be referenced at any point in the configuration (where they occur does not matter)
-        // and can be used in any Check
-        // Note: rules do not transfer between subreddit configurations
-        "freekarmasub",
+      "checks": [
         {
-          "name": "attr10all",
-          "kind": "attribution",
-          "criteria": [
+          "name": "Auto Remove SP Karma",
+          "description": "Remove submission because author has self-promo >10% and posted in karma subs recently",
+          "kind": "submission",
+          "rules": [
+            // named rules can be referenced at any point in the configuration (where they occur does not matter)
+            // and can be used in any Check
+            // Note: rules do not transfer between subreddit configurations
+            "freekarmasub",
             {
-              "threshold": "> 10%",
-              "window": "90 days"
+              "name": "attr10all",
+              "kind": "attribution",
+              "criteria": [
+                {
+                  "threshold": "> 10%",
+                  "window": "90 days"
+                },
+                {
+                  "threshold": "> 10%",
+                  "window": 100
+                }
+              ],
+            }
+          ],
+          "actions": [
+            {
+              "kind": "remove"
             },
             {
-              "threshold": "> 10%",
-              "window": 100
+              "kind": "comment",
+              "content": "Your submission was removed because you are over reddit's threshold for self-promotion and recently posted this content in a karma sub"
             }
-          ],
-        }
-      ],
-      "actions": [
-        {
-          "kind": "remove"
+          ]
         },
         {
-          "kind": "comment",
-          "content": "Your submission was removed because you are over reddit's threshold for self-promotion and recently posted this content in a karma sub"
-        }
-      ]
-    },
-    {
-      "name": "Free Karma On Submission Alert",
-      "description": "Check if author has posted this submission in 'freekarma' subreddits",
-      "kind": "submission",
-      "rules": [
-        {
-          // rules can be re-used throughout a configuration by referencing them by name
-          //
-          // The rule name itself can only contain spaces, hyphens and underscores
-          // The value used to reference it will have all of these removed, and lower-cased
-          //
-          // so to reference this rule use the value 'freekarmasub'
-          "name": "Free_Karma-SUB",
-          "kind": "recentActivity",
-          "lookAt": "submissions",
-          "useSubmissionAsReference":true,
-          "thresholds": [
+          "name": "Free Karma On Submission Alert",
+          "description": "Check if author has posted this submission in 'freekarma' subreddits",
+          "kind": "submission",
+          "rules": [
             {
-              "threshold": ">= 1",
-              "subreddits": [
-                "DeFreeKarma",
-                "FreeKarma4U",
-                "FreeKarma4You",
-                "upvote"
-              ]
+              // rules can be re-used throughout a configuration by referencing them by name
+              //
+              // The rule name itself can only contain spaces, hyphens and underscores
+              // The value used to reference it will have all of these removed, and lower-cased
+              //
+              // so to reference this rule use the value 'freekarmasub'
+              "name": "Free_Karma-SUB",
+              "kind": "recentActivity",
+              "lookAt": "submissions",
+              "useSubmissionAsReference":true,
+              "thresholds": [
+                {
+                  "threshold": ">= 1",
+                  "subreddits": [
+                    "DeFreeKarma",
+                    "FreeKarma4U",
+                    "FreeKarma4You",
+                    "upvote"
+                  ]
+                }
+              ],
+              "window": "7 days"
             }
           ],
-          "window": "7 days"
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Submission posted {{rules.freekarmasub.totalCount}} times in karma {{rules.freekarmasub.subCount}} subs over {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}"
-        }
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Submission posted {{rules.freekarmasub.totalCount}} times in karma {{rules.freekarmasub.subCount}} subs over {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}"
+            }
+          ]
+        },
       ]
-    },
+    }
   ]
 }

docs/examples/advancedConcepts/ruleNameReuse.yaml

@@ -1,52 +1,53 @@
-checks:
-  - name: Auto Remove SP Karma
-    description: >-
-      Remove submission because author has self-promo >10% and posted in karma
-      subs recently
-    kind: submission
-    rules:
-      # named rules can be referenced at any point in the configuration (where they occur does not matter)
-      # and can be used in any Check
-      # Note: rules do not transfer between subreddit configurations
-      - freekarmasub
-      - name: attr10all
-        kind: attribution
-        criteria:
-          - threshold: '> 10%'
-            window: 90 days
-          - threshold: '> 10%'
-            window: 100
-    actions:
-      - kind: remove
-      - kind: comment
-        content: >-
-          Your submission was removed because you are over reddit's threshold
-          for self-promotion and recently posted this content in a karma sub
-  - name: Free Karma On Submission Alert
-    description: Check if author has posted this submission in 'freekarma' subreddits
-    kind: submission
-    rules:
-      # rules can be re-used throughout a configuration by referencing them by name
-      #
-      # The rule name itself can only contain spaces, hyphens and underscores
-      # The value used to reference it will have all of these removed, and lower-cased
-      #
-      # so to reference this rule use the value 'freekarmasub'
-      - name: Free_Karma-SUB
-        kind: recentActivity
-        lookAt: submissions
-        useSubmissionAsReference: true
-        thresholds:
-          - threshold: '>= 1'
-            subreddits:
-              - DeFreeKarma
-              - FreeKarma4U
-              - FreeKarma4You
-              - upvote
-        window: 7 days
-    actions:
-      - kind: report
-        content: >-
-          Submission posted {{rules.freekarmasub.totalCount}} times in karma
-          {{rules.freekarmasub.subCount}} subs over
-          {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}
+runs:
+  - checks:
+      - name: Auto Remove SP Karma
+        description: >-
+          Remove submission because author has self-promo >10% and posted in karma
+          subs recently
+        kind: submission
+        rules:
+          # named rules can be referenced at any point in the configuration (where they occur does not matter)
+          # and can be used in any Check
+          # Note: rules do not transfer between subreddit configurations
+          - freekarmasub
+          - name: attr10all
+            kind: attribution
+            criteria:
+              - threshold: '> 10%'
+                window: 90 days
+              - threshold: '> 10%'
+                window: 100
+        actions:
+          - kind: remove
+          - kind: comment
+            content: >-
+              Your submission was removed because you are over reddit's threshold
+              for self-promotion and recently posted this content in a karma sub
+      - name: Free Karma On Submission Alert
+        description: Check if author has posted this submission in 'freekarma' subreddits
+        kind: submission
+        rules:
+          # rules can be re-used throughout a configuration by referencing them by name
+          #
+          # The rule name itself can only contain spaces, hyphens and underscores
+          # The value used to reference it will have all of these removed, and lower-cased
+          #
+          # so to reference this rule use the value 'freekarmasub'
+          - name: Free_Karma-SUB
+            kind: recentActivity
+            lookAt: submissions
+            useSubmissionAsReference: true
+            thresholds:
+              - threshold: '>= 1'
+                subreddits:
+                  - DeFreeKarma
+                  - FreeKarma4U
+                  - FreeKarma4You
+                  - upvote
+            window: 7 days
+        actions:
+          - kind: report
+            content: >-
+              Submission posted {{rules.freekarmasub.totalCount}} times in karma
+              {{rules.freekarmasub.subCount}} subs over
+              {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}

docs/examples/advancedConcepts/ruleSets.json5

@@ -1,84 +1,88 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Self Promo All or low comment",
-      "description": "SP >10% of all activities or >10% of submissions with low comment engagement",
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          // this attribution rule is looking at all activities
-          //
-          // we want want this one rule to trigger the check because >10% of all activity (submission AND comments) is a good requirement
-          "name": "attr10all",
-          "kind": "attribution",
-          "criteria": [
-            {
-              "threshold": "> 10%",
-              "window": "90 days"
-            },
-            {
-              "threshold": "> 10%",
-              "window": 100
-            }
-          ],
-        },
-        {
-          // this is a **Rule Set**
-          //
-          // it is made up of "nested" rules with a pass condition (AND/OR)
-          // if the nested rules pass the condition then the Rule Set triggers the Check
-          //
-          // AND = all nested rules must be triggered to make the Rule Set trigger
-          // AND = any of the nested Rules will be the Rule Set trigger
-          "condition": "AND",
-          // in this check we use an Attribution >10% on ONLY submissions, which is a lower requirement then the above attribution rule
-          // and combine it with a History rule looking for low comment engagement
-          // to make a "higher" requirement Rule Set our of two low requirement Rules
+          "name": "Self Promo All or low comment",
+          "description": "SP >10% of all activities or >10% of submissions with low comment engagement",
+          "kind": "submission",
           "rules": [
             {
-              "name": "attr20sub",
+              // this attribution rule is looking at all activities
+              //
+              // we want want this one rule to trigger the check because >10% of all activity (submission AND comments) is a good requirement
+              "name": "attr10all",
               "kind": "attribution",
               "criteria": [
                 {
                   "threshold": "> 10%",
-                  "thresholdOn": "submissions",
                   "window": "90 days"
                 },
                 {
                   "threshold": "> 10%",
-                  "thresholdOn": "submissions",
                   "window": 100
                 }
               ],
-              "lookAt": "media"
             },
             {
-              "name": "lowOrOpComm",
-              "kind": "history",
-              "criteriaJoin": "OR",
-              "criteria": [
+              // this is a **Rule Set**
+              //
+              // it is made up of "nested" rules with a pass condition (AND/OR)
+              // if the nested rules pass the condition then the Rule Set triggers the Check
+              //
+              // AND = all nested rules must be triggered to make the Rule Set trigger
+              // AND = any of the nested Rules will be the Rule Set trigger
+              "condition": "AND",
+              // in this check we use an Attribution >10% on ONLY submissions, which is a lower requirement then the above attribution rule
+              // and combine it with a History rule looking for low comment engagement
+              // to make a "higher" requirement Rule Set our of two low requirement Rules
+              "rules": [
                 {
-                  "window": "90 days",
-                  "comment": "< 50%"
+                  "name": "attr20sub",
+                  "kind": "attribution",
+                  "criteria": [
+                    {
+                      "threshold": "> 10%",
+                      "thresholdOn": "submissions",
+                      "window": "90 days"
+                    },
+                    {
+                      "threshold": "> 10%",
+                      "thresholdOn": "submissions",
+                      "window": 100
+                    }
+                  ],
+                  "lookAt": "media"
                 },
                 {
-                  "window": "90 days",
-                  "comment": "> 40% OP"
+                  "name": "lowOrOpComm",
+                  "kind": "history",
+                  "criteriaJoin": "OR",
+                  "criteria": [
+                    {
+                      "window": "90 days",
+                      "comment": "< 50%"
+                    },
+                    {
+                      "window": "90 days",
+                      "comment": "> 40% OP"
+                    }
+                  ]
                 }
               ]
             }
+          ],
+          "actions": [
+            {
+              "kind": "remove"
+            },
+            {
+              "kind": "comment",
+              "content": "Your submission was removed because you are over reddit's threshold for self-promotion or exhibit low comment engagement"
+            }
           ]
-        }
-      ],
-      "actions": [
-        {
-          "kind": "remove"
         },
-        {
-          "kind": "comment",
-          "content": "Your submission was removed because you are over reddit's threshold for self-promotion or exhibit low comment engagement"
-        }
       ]
-    },
-  ],
+    }
+  ]
 }

docs/examples/advancedConcepts/ruleSets.yaml

@@ -1,53 +1,54 @@
-checks:
-  - name: Self Promo All or low comment
-    description: >-
-      SP >10% of all activities or >10% of submissions with low comment
-      engagement
-    kind: submission
-    rules:
-      # this attribution rule is looking at all activities
-      #
-      # we want want this one rule to trigger the check because >10% of all activity (submission AND comments) is a good requirement
-      - name: attr10all
-        kind: attribution
-        criteria:
-          - threshold: '> 10%'
-            window: 90 days
-          - threshold: '> 10%'
-            window: 100
-        # this is a RULE SET
-        #
-        # it is made up of "nested" rules with a pass condition (AND/OR)
-        # if the nested rules pass the condition then the Rule Set triggers the Check
-        #
-        # AND = all nested rules must be triggered to make the Rule Set trigger
-        # AND = any of the nested Rules will be the Rule Set trigger
-      - condition: AND
-        # in this check we use an Attribution >10% on ONLY submissions, which is a lower requirement then the above attribution rule
-        # and combine it with a History rule looking for low comment engagement
-        # to make a "higher" requirement Rule Set our of two low requirement Rules
+runs:
+  - checks:
+      - name: Self Promo All or low comment
+        description: >-
+          SP >10% of all activities or >10% of submissions with low comment
+          engagement
+        kind: submission
         rules:
-          - name: attr20sub
+          # this attribution rule is looking at all activities
+          #
+          # we want want this one rule to trigger the check because >10% of all activity (submission AND comments) is a good requirement
+          - name: attr10all
             kind: attribution
             criteria:
               - threshold: '> 10%'
-                thresholdOn: submissions
                 window: 90 days
               - threshold: '> 10%'
-                thresholdOn: submissions
                 window: 100
-            lookAt: media
-          - name: lowOrOpComm
-            kind: history
-            criteriaJoin: OR
-            criteria:
-              - window: 90 days
-                comment: < 50%
-              - window: 90 days
-                comment: '> 40% OP'
-    actions:
-      - kind: remove
-      - kind: comment
-        content: >-
-          Your submission was removed because you are over reddit's threshold
-          for self-promotion or exhibit low comment engagement
+            # this is a RULE SET
+            #
+            # it is made up of "nested" rules with a pass condition (AND/OR)
+            # if the nested rules pass the condition then the Rule Set triggers the Check
+            #
+            # AND = all nested rules must be triggered to make the Rule Set trigger
+            # AND = any of the nested Rules will be the Rule Set trigger
+          - condition: AND
+            # in this check we use an Attribution >10% on ONLY submissions, which is a lower requirement then the above attribution rule
+            # and combine it with a History rule looking for low comment engagement
+            # to make a "higher" requirement Rule Set our of two low requirement Rules
+            rules:
+              - name: attr20sub
+                kind: attribution
+                criteria:
+                  - threshold: '> 10%'
+                    thresholdOn: submissions
+                    window: 90 days
+                  - threshold: '> 10%'
+                    thresholdOn: submissions
+                    window: 100
+                lookAt: media
+              - name: lowOrOpComm
+                kind: history
+                criteriaJoin: OR
+                criteria:
+                  - window: 90 days
+                    comment: < 50%
+                  - window: 90 days
+                    comment: '> 40% OP'
+        actions:
+          - kind: remove
+          - kind: comment
+            content: >-
+              Your submission was removed because you are over reddit's threshold
+              for self-promotion or exhibit low comment engagement

docs/examples/attribution/redditSelfPromoAll.json5

@@ -1,37 +1,41 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Self Promo Activities",
-      "description": "Check if any of Author's aggregated submission origins are >10% of entire history",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "attr10all",
-          "kind": "attribution",
-          // criteria defaults to OR -- so either of these criteria will trigger the rule
-          "criteria": [
+          "name": "Self Promo Activities",
+          "description": "Check if any of Author's aggregated submission origins are >10% of entire history",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              // threshold can be a percent or an absolute number
-              "threshold": "> 10%",
-              // The default is "all" -- calculate percentage of entire history (submissions & comments)
-              // "thresholdOn": "all",
+              "name": "attr10all",
+              "kind": "attribution",
+              // criteria defaults to OR -- so either of these criteria will trigger the rule
+              "criteria": [
+                {
+                  // threshold can be a percent or an absolute number
+                  "threshold": "> 10%",
+                  // The default is "all" -- calculate percentage of entire history (submissions & comments)
+                  // "thresholdOn": "all",
 
-              // look at last 90 days of Author's activities (comments and submissions)
-              "window": "90 days"
-            },
-            {
-              "threshold": "> 10%",
-              // look at Author's last 100 activities (comments and submissions)
-              "window": 100
+                  // look at last 90 days of Author's activities (comments and submissions)
+                  "window": "90 days"
+                },
+                {
+                  "threshold": "> 10%",
+                  // look at Author's last 100 activities (comments and submissions)
+                  "window": 100
+                }
+              ],
             }
           ],
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "{{rules.attr10all.largestPercent}}% of {{rules.attr10all.activityTotal}} items over {{rules.attr10all.window}}"
+          "actions": [
+            {
+              "kind": "report",
+              "content": "{{rules.attr10all.largestPercent}}% of {{rules.attr10all.activityTotal}} items over {{rules.attr10all.window}}"
+            }
+          ]
         }
       ]
     }

docs/examples/attribution/redditSelfPromoAll.yaml

@@ -1,27 +1,28 @@
-checks:
-  - name: Self Promo Activities
-    description: >-
-      Check if any of Author's aggregated submission origins are >10% of entire
-      history
-    # check will run on a new submission in your subreddit and look at the Author of that submission
-    kind: submission
-    rules:
-      - name: attr10all
-        kind: attribution
-        # criteria defaults to OR -- so either of these criteria will trigger the rule
-        criteria:
-          - threshold: '> 10%' # threshold can be a percent or an absolute number
-            # The default is "all" -- calculate percentage of entire history (submissions & comments)
-            #thresholdOn: all
-            #
-            # look at last 90 days of Author's activities (comments and submissions)
-            window: 90 days
-          - threshold: '> 10%'
-            # look at Author's last 100 activities (comments and submissions)
-            window: 100
-    actions:
-      - kind: report
-        content: >-
-          {{rules.attr10all.largestPercent}}% of
-          {{rules.attr10all.activityTotal}} items over
-          {{rules.attr10all.window}}
+runs:
+  - checks:
+      - name: Self Promo Activities
+        description: >-
+          Check if any of Author's aggregated submission origins are >10% of entire
+          history
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: attr10all
+            kind: attribution
+            # criteria defaults to OR -- so either of these criteria will trigger the rule
+            criteria:
+              - threshold: '> 10%' # threshold can be a percent or an absolute number
+                # The default is "all" -- calculate percentage of entire history (submissions & comments)
+                #thresholdOn: all
+                #
+                # look at last 90 days of Author's activities (comments and submissions)
+                window: 90 days
+              - threshold: '> 10%'
+                # look at Author's last 100 activities (comments and submissions)
+                window: 100
+        actions:
+          - kind: report
+            content: >-
+              {{rules.attr10all.largestPercent}}% of
+              {{rules.attr10all.activityTotal}} items over
+              {{rules.attr10all.window}}

docs/examples/attribution/redditSelfPromoSubmissionOnly.yaml

@@ -1,24 +1,25 @@
-checks:
-  - name: Self Promo Submissions
-    description: >-
-      Check if any of Author's aggregated submission origins are >10% of their
-      submissions
-    # check will run on a new submission in your subreddit and look at the Author of that submission
-    kind: submission
-    rules:
-      - name: attr10sub
-        kind: attribution
-        # criteria defaults to OR -- so either of these criteria will trigger the rule
-        criteria:
-          - threshold: '> 10%' # threshold can be a percent or an absolute number
-            thresholdOn: submissions # calculate percentage of submissions, rather than entire history (submissions & comments)
-            window: 90 days # look at last 90 days of Author's activities (comments and submissions)
-          - threshold: '> 10%'
-            thresholdOn: submissions
-            window: 100 # look at Author's last 100 activities (comments and submissions)
-    actions:
-      - kind: report
-        content: >-
-          {{rules.attr10sub.largestPercent}}% of
-          {{rules.attr10sub.activityTotal}} items over
-          {{rules.attr10sub.window}}
+runs:
+  - checks:
+      - name: Self Promo Submissions
+        description: >-
+          Check if any of Author's aggregated submission origins are >10% of their
+          submissions
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: attr10sub
+            kind: attribution
+            # criteria defaults to OR -- so either of these criteria will trigger the rule
+            criteria:
+              - threshold: '> 10%' # threshold can be a percent or an absolute number
+                thresholdOn: submissions # calculate percentage of submissions, rather than entire history (submissions & comments)
+                window: 90 days # look at last 90 days of Author's activities (comments and submissions)
+              - threshold: '> 10%'
+                thresholdOn: submissions
+                window: 100 # look at Author's last 100 activities (comments and submissions)
+        actions:
+          - kind: report
+            content: >-
+              {{rules.attr10sub.largestPercent}}% of
+              {{rules.attr10sub.activityTotal}} items over
+              {{rules.attr10sub.window}}

docs/examples/attribution/redditSelfPromoSubmissionsOnly.json5

@@ -1,38 +1,42 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Self Promo Submissions",
-      "description": "Check if any of Author's aggregated submission origins are >10% of their submissions",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "attr10sub",
-          "kind": "attribution",
-          // criteria defaults to OR -- so either of these criteria will trigger the rule
-          "criteria": [
+          "name": "Self Promo Submissions",
+          "description": "Check if any of Author's aggregated submission origins are >10% of their submissions",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              // threshold can be a percent or an absolute number
-              "threshold": "> 10%",
-              // calculate percentage of submissions, rather than entire history (submissions & comments)
-              "thresholdOn": "submissions",
+              "name": "attr10sub",
+              "kind": "attribution",
+              // criteria defaults to OR -- so either of these criteria will trigger the rule
+              "criteria": [
+                {
+                  // threshold can be a percent or an absolute number
+                  "threshold": "> 10%",
+                  // calculate percentage of submissions, rather than entire history (submissions & comments)
+                  "thresholdOn": "submissions",
 
-              // look at last 90 days of Author's activities (comments and submissions)
-              "window": "90 days"
-            },
-            {
-              "threshold": "> 10%",
-              "thresholdOn": "submissions",
-              // look at Author's last 100 activities (comments and submissions)
-              "window": 100
+                  // look at last 90 days of Author's activities (comments and submissions)
+                  "window": "90 days"
+                },
+                {
+                  "threshold": "> 10%",
+                  "thresholdOn": "submissions",
+                  // look at Author's last 100 activities (comments and submissions)
+                  "window": 100
+                }
+              ],
             }
           ],
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "{{rules.attr10sub.largestPercent}}% of {{rules.attr10sub.activityTotal}} items over {{rules.attr10sub.window}}"
+          "actions": [
+            {
+              "kind": "report",
+              "content": "{{rules.attr10sub.largestPercent}}% of {{rules.attr10sub.activityTotal}} items over {{rules.attr10sub.window}}"
+            }
+          ]
         }
       ]
     }

docs/examples/author/authorFilter.json5

@@ -1,67 +1,71 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Karma/Meme Sub Activity",
-      "description": "Report on karma sub activity or meme sub activity if user isn't a memelord",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "freekarma",
-          "kind": "recentActivity",
-          "lookAt": "submissions",
-          "thresholds": [
+          "name": "Karma/Meme Sub Activity",
+          "description": "Report on karma sub activity or meme sub activity if user isn't a memelord",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              "threshold": ">= 1",
-              "subreddits": [
-                "DeFreeKarma",
-                "FreeKarma4U",
-              ]
-            }
-          ],
-          "window": "7 days"
-        },
-        {
-          "name": "noobmemer",
-          "kind": "recentActivity",
-          // authors filter will be checked before a rule is run. If anything passes then the Rule is skipped -- it is not failed or triggered.
-          // if *all* Rules for a Check are skipped due to authors filter then the Check will fail
-          "authorIs": {
-            // each property (include/exclude) can contain multiple AuthorCriteria
-            // if any AuthorCriteria passes its test the Rule is skipped
-            //
-            // for an AuthorCriteria to pass all properties present on it must pass
-            //
-            // if "include" is present it will always run and exclude will be skipped
-            // "include:" []
-            "exclude": [
-              // for this to pass the Author of the Submission must not have the flair "Supreme Memer" and have the name "user1" or "user2"
-              {
-                "flairText": ["Supreme Memer"],
-                "names": ["user1","user2"]
+              "name": "freekarma",
+              "kind": "recentActivity",
+              "lookAt": "submissions",
+              "thresholds": [
+                {
+                  "threshold": ">= 1",
+                  "subreddits": [
+                    "DeFreeKarma",
+                    "FreeKarma4U",
+                  ]
+                }
+              ],
+              "window": "7 days"
+            },
+            {
+              "name": "noobmemer",
+              "kind": "recentActivity",
+              // authors filter will be checked before a rule is run. If anything passes then the Rule is skipped -- it is not failed or triggered.
+              // if *all* Rules for a Check are skipped due to authors filter then the Check will fail
+              "authorIs": {
+                // each property (include/exclude) can contain multiple AuthorCriteria
+                // if any AuthorCriteria passes its test the Rule is skipped
+                //
+                // for an AuthorCriteria to pass all properties present on it must pass
+                //
+                // if "include" is present it will always run and exclude will be skipped
+                // "include:" []
+                "exclude": [
+                  // for this to pass the Author of the Submission must not have the flair "Supreme Memer" and have the name "user1" or "user2"
+                  {
+                    "flairText": ["Supreme Memer"],
+                    "names": ["user1","user2"]
+                  },
+                  {
+                    // for this to pass the Author of the Submission must not have the flair "Decent Memer"
+                    "flairText": ["Decent Memer"]
+                  }
+                ]
               },
-              {
-                // for this to pass the Author of the Submission must not have the flair "Decent Memer"
-                "flairText": ["Decent Memer"]
-              }
-            ]
-          },
-          "lookAt": "submissions",
-          "thresholds": [
-            {
-              "threshold": ">= 1",
-              "subreddits": [
-                "dankmemes",
-              ]
+              "lookAt": "submissions",
+              "thresholds": [
+                {
+                  "threshold": ">= 1",
+                  "subreddits": [
+                    "dankmemes",
+                  ]
+                }
+              ],
+              "window": "7 days"
             }
           ],
-          "window": "7 days"
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Author has posted in free karma sub, or in /r/dankmemes and does not have meme flair in this subreddit"
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Author has posted in free karma sub, or in /r/dankmemes and does not have meme flair in this subreddit"
+            }
+          ]
         }
       ]
     }

docs/examples/author/authorFilter.yaml

@@ -1,48 +1,49 @@
-checks:
-  - name: Karma/Meme Sub Activity
-    description: Report on karma sub activity or meme sub activity if user isn't a memelord
-    # check will run on a new submission in your subreddit and look at the Author of that submission
-    kind: submission
-    rules:
-      - name: freekarma
-        kind: recentActivity
-        lookAt: submissions
-        thresholds:
-          - threshold: '>= 1'
-            subreddits:
-              - DeFreeKarma
-              - FreeKarma4U
-        window: 7 days
-      - name: noobmemer
-        kind: recentActivity
-        # authors filter will be checked before a rule is run. If anything passes then the Rule is skipped -- it is not failed or triggered.
-        # if *all* Rules for a Check are skipped due to authors filter then the Check will fail
-        authorIs:
-          # each property (include/exclude) can contain multiple AuthorCriteria
-          # if any AuthorCriteria passes its test the Rule is skipped
-          #
-          # for an AuthorCriteria to pass all properties present on it must pass
-          #
-          # if include is present it will always run and exclude will be skipped
-          #-include:
-          exclude:
-              # for this to pass the Author of the Submission must not have the flair "Supreme Memer" and have the name "user1" or "user2"
-            - flairText:
-                - Supreme Memer
-              names:
-                - user1
-                - user2
-              # for this to pass the Author of the Submission must not have the flair "Decent Memer"
-            - flairText:
-                - Decent Memer
-        lookAt: submissions
-        thresholds:
-          - threshold: '>= 1'
-            subreddits:
-              - dankmemes
-        window: 7 days
-    actions:
-      - kind: report
-        content: >-
-          Author has posted in free karma sub, or in /r/dankmemes and does not
-          have meme flair in this subreddit
+runs:
+  - checks:
+      - name: Karma/Meme Sub Activity
+        description: Report on karma sub activity or meme sub activity if user isn't a memelord
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: freekarma
+            kind: recentActivity
+            lookAt: submissions
+            thresholds:
+              - threshold: '>= 1'
+                subreddits:
+                  - DeFreeKarma
+                  - FreeKarma4U
+            window: 7 days
+          - name: noobmemer
+            kind: recentActivity
+            # authors filter will be checked before a rule is run. If anything passes then the Rule is skipped -- it is not failed or triggered.
+            # if *all* Rules for a Check are skipped due to authors filter then the Check will fail
+            authorIs:
+              # each property (include/exclude) can contain multiple AuthorCriteria
+              # if any AuthorCriteria passes its test the Rule is skipped
+              #
+              # for an AuthorCriteria to pass all properties present on it must pass
+              #
+              # if include is present it will always run and exclude will be skipped
+              #-include:
+              exclude:
+                # for this to pass the Author of the Submission must not have the flair "Supreme Memer" and have the name "user1" or "user2"
+                - flairText:
+                    - Supreme Memer
+                  names:
+                    - user1
+                    - user2
+                  # for this to pass the Author of the Submission must not have the flair "Decent Memer"
+                - flairText:
+                    - Decent Memer
+            lookAt: submissions
+            thresholds:
+              - threshold: '>= 1'
+                subreddits:
+                  - dankmemes
+            window: 7 days
+        actions:
+          - kind: report
+            content: >-
+              Author has posted in free karma sub, or in /r/dankmemes and does not
+              have meme flair in this subreddit

docs/examples/author/flairNewUserSubmission.json5

@@ -1,28 +1,32 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Flair New User Sub",
-      "description": "Flair submission as sketchy if user does not have vet flair",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "newflair",
-          "kind": "author",
-          // rule will trigger if Author does not have "vet" flair text
-          "exclude": [
+          "name": "Flair New User Sub",
+          "description": "Flair submission as sketchy if user does not have vet flair",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              "flairText": ["vet"]
+              "name": "newflair",
+              "kind": "author",
+              // rule will trigger if Author does not have "vet" flair text
+              "exclude": [
+                {
+                  "flairText": ["vet"]
+                }
+              ]
+            }
+          ],
+          "actions": [
+            {
+              "kind": "flair",
+              "text": "New User",
+              "css": "orange"
             }
           ]
         }
-      ],
-      "actions": [
-        {
-          "kind": "flair",
-          "text": "New User",
-          "css": "orange"
-        }
       ]
     }
   ]

docs/examples/author/flairNewUserSubmission.yaml

@@ -1,16 +1,17 @@
-checks:
-  - name: Flair New User Sub
-    description: Flair submission as sketchy if user does not have vet flair
-    # check will run on a new submission in your subreddit and look at the Author of that submission
-    kind: submission
-    rules:
-      - name: newflair
-        kind: author
-        # rule will trigger if Author does not have "vet" flair text
-        exclude:
-          - flairText:
-              - vet
-    actions:
-      - kind: flair
-        text: New User
-        css: orange
+runs:
+  - checks:
+      - name: Flair New User Sub
+        description: Flair submission as sketchy if user does not have vet flair
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: newflair
+            kind: author
+            # rule will trigger if Author does not have "vet" flair text
+            exclude:
+              - flairText:
+                  - vet
+        actions:
+          - kind: flair
+            text: New User
+            css: orange

docs/examples/author/flairVettedUserSubmission.json5

@@ -1,28 +1,32 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Flair Vetted User Submission",
-      "description": "Flair submission as Approved if user has vet flair",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "newflair",
-          "kind": "author",
-          // rule will trigger if Author has "vet" flair text
-          "include": [
+          "name": "Flair Vetted User Submission",
+          "description": "Flair submission as Approved if user has vet flair",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              "flairText": ["vet"]
+              "name": "newflair",
+              "kind": "author",
+              // rule will trigger if Author has "vet" flair text
+              "include": [
+                {
+                  "flairText": ["vet"]
+                }
+              ]
+            }
+          ],
+          "actions": [
+            {
+              "kind": "flair",
+              "text": "Vetted",
+              "css": "green"
             }
           ]
         }
-      ],
-      "actions": [
-        {
-          "kind": "flair",
-          "text": "Vetted",
-          "css": "green"
-        }
       ]
     }
   ]

docs/examples/author/flairVettedUserSubmission.yaml

@@ -1,16 +1,17 @@
-checks:
-  - name: Flair Vetted User Submission
-    description: Flair submission as Approved if user has vet flair
-    # check will run on a new submission in your subreddit and look at the Author of that submission
-    kind: submission
-    rules:
-      - name: newflair
-        kind: author
-        # rule will trigger if Author has "vet" flair text
-        include:
-          - flairText:
-              - vet
-    actions:
-      - kind: flair
-        text: Vetted
-        css: green
+runs:
+  - checks:
+      - name: Flair Vetted User Submission
+        description: Flair submission as Approved if user has vet flair
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: newflair
+            kind: author
+            # rule will trigger if Author has "vet" flair text
+            include:
+              - flairText:
+                  - vet
+        actions:
+          - kind: flair
+            text: Vetted
+            css: green

docs/examples/author/ignoreVettedUser.json5

@@ -1,73 +1,77 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "non-vetted karma/meme activity",
-      "description": "Report if Author has SP and has recent karma/meme sub activity and isn't vetted",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          // The Author Rule is best used in conjunction with other Rules --
-          // instead of having to write an AuthorFilter for every Rule where you want to skip it based on Author criteria
-          // you can write one Author Rule and make it fail on the required criteria
-          // so that the check fails and Actions don't run
-          "name": "nonvet",
-          "kind": "author",
-          "exclude": [
+          "name": "non-vetted karma/meme activity",
+          "description": "Report if Author has SP and has recent karma/meme sub activity and isn't vetted",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              "flairText": ["vet"]
-            }
-          ]
-        },
-        {
-          "name": "attr10",
-          "kind": "attribution",
-          "criteria": [
-            {
-              "threshold": "> 10%",
-              "window": "90 days"
+              // The Author Rule is best used in conjunction with other Rules --
+              // instead of having to write an AuthorFilter for every Rule where you want to skip it based on Author criteria
+              // you can write one Author Rule and make it fail on the required criteria
+              // so that the check fails and Actions don't run
+              "name": "nonvet",
+              "kind": "author",
+              "exclude": [
+                {
+                  "flairText": ["vet"]
+                }
+              ]
             },
             {
-              "threshold": "> 10%",
-              "window": 100
-            }
-          ],
-        },
-        {
-          "name": "freekarma",
-          "kind": "recentActivity",
-          "lookAt": "submissions",
-          "thresholds": [
+              "name": "attr10",
+              "kind": "attribution",
+              "criteria": [
+                {
+                  "threshold": "> 10%",
+                  "window": "90 days"
+                },
+                {
+                  "threshold": "> 10%",
+                  "window": 100
+                }
+              ],
+            },
             {
-              "threshold": ">= 1",
-              "subreddits": [
-                "DeFreeKarma",
-                "FreeKarma4U",
-              ]
-            }
-          ],
-          "window": "7 days"
-        },
-        {
-          "name": "memes",
-          "kind": "recentActivity",
-          "lookAt": "submissions",
-          "thresholds": [
+              "name": "freekarma",
+              "kind": "recentActivity",
+              "lookAt": "submissions",
+              "thresholds": [
+                {
+                  "threshold": ">= 1",
+                  "subreddits": [
+                    "DeFreeKarma",
+                    "FreeKarma4U",
+                  ]
+                }
+              ],
+              "window": "7 days"
+            },
             {
-              "threshold": ">= 3",
-              "subreddits": [
-                "dankmemes",
-              ]
+              "name": "memes",
+              "kind": "recentActivity",
+              "lookAt": "submissions",
+              "thresholds": [
+                {
+                  "threshold": ">= 3",
+                  "subreddits": [
+                    "dankmemes",
+                  ]
+                }
+              ],
+              "window": "7 days"
             }
           ],
-          "window": "7 days"
-        }
-      ],
-      // will NOT run if the Author for this Submission has the flair "vet"
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Author has posted in free karma or meme subs recently"
+          // will NOT run if the Author for this Submission has the flair "vet"
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Author has posted in free karma or meme subs recently"
+            }
+          ]
         }
       ]
     }

docs/examples/author/ignoreVettedUser.yaml

@@ -1,45 +1,46 @@
-checks:
-  - name: non-vetted karma/meme activity
-    description: >-
-      Report if Author has SP and has recent karma/meme sub activity and isn't
-      vetted
-    # check will run on a new submission in your subreddit and look at the Author of that submission
-    kind: submission
-    rules:
-      # The Author Rule is best used in conjunction with other Rules --
-      # instead of having to write an AuthorFilter for every Rule where you want to skip it based on Author criteria
-      # you can write one Author Rule and make it fail on the required criteria
-      # so that the check fails and Actions don't run
-      - name: nonvet
-        kind: author
-        exclude:
-          - flairText:
-              - vet
-      - name: attr10
-        kind: attribution
-        criteria:
-          - threshold: '> 10%'
-            window: 90 days
-          - threshold: '> 10%'
-            window: 100
-      - name: freekarma
-        kind: recentActivity
-        lookAt: submissions
-        thresholds:
-          - threshold: '>= 1'
-            subreddits:
-              - DeFreeKarma
-              - FreeKarma4U
-        window: 7 days
-      - name: memes
-        kind: recentActivity
-        lookAt: submissions
-        thresholds:
-          - threshold: '>= 3'
-            subreddits:
-              - dankmemes
-        window: 7 days
-    # will NOT run if the Author for this Submission has the flair "vet"
-    actions:
-      - kind: report
-        content: Author has posted in free karma or meme subs recently
+runs:
+  - checks:
+      - name: non-vetted karma/meme activity
+        description: >-
+          Report if Author has SP and has recent karma/meme sub activity and isn't
+          vetted
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          # The Author Rule is best used in conjunction with other Rules --
+          # instead of having to write an AuthorFilter for every Rule where you want to skip it based on Author criteria
+          # you can write one Author Rule and make it fail on the required criteria
+          # so that the check fails and Actions don't run
+          - name: nonvet
+            kind: author
+            exclude:
+              - flairText:
+                  - vet
+          - name: attr10
+            kind: attribution
+            criteria:
+              - threshold: '> 10%'
+                window: 90 days
+              - threshold: '> 10%'
+                window: 100
+          - name: freekarma
+            kind: recentActivity
+            lookAt: submissions
+            thresholds:
+              - threshold: '>= 1'
+                subreddits:
+                  - DeFreeKarma
+                  - FreeKarma4U
+            window: 7 days
+          - name: memes
+            kind: recentActivity
+            lookAt: submissions
+            thresholds:
+              - threshold: '>= 3'
+                subreddits:
+                  - dankmemes
+            window: 7 days
+        # will NOT run if the Author for this Submission has the flair "vet"
+        actions:
+          - kind: report
+            content: Author has posted in free karma or meme subs recently

docs/examples/history/lowEngagement.json5

@@ -1,29 +1,33 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Low Comment Engagement",
-      "description": "Check if Author is submitting much more than they comment",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "lowComm",
-          "kind": "history",
-          "criteria": [
+          "name": "Low Comment Engagement",
+          "description": "Check if Author is submitting much more than they comment",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              // look at last 90 days of Author's activities
-              "window": "90 days",
-              // trigger if less than 30% of their activities in this time period are comments
-              "comment": "< 30%"
-            },
+              "name": "lowComm",
+              "kind": "history",
+              "criteria": [
+                {
+                  // look at last 90 days of Author's activities
+                  "window": "90 days",
+                  // trigger if less than 30% of their activities in this time period are comments
+                  "comment": "< 30%"
+                },
+              ]
+            }
+          ],
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Low engagement: comments were {{rules.lowcomm.commentPercent}} of {{rules.lowcomm.activityTotal}} over {{rules.lowcomm.window}}"
+            }
           ]
         }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Low engagement: comments were {{rules.lowcomm.commentPercent}} of {{rules.lowcomm.activityTotal}} over {{rules.lowcomm.window}}"
-        }
       ]
     }
   ]

docs/examples/history/lowEngagement.yaml

@@ -1,21 +1,22 @@
-checks:
-  - name: Low Comment Engagement
-    description: Check if Author is submitting much more than they comment
-    # check will run on a new submission in your subreddit and look at the Author of that submission
-    kind: submission
-    rules:
-      - name: lowComm
-        kind: history
-        criteria:
-          - comment: '< 30%'
-            window:
-             # get author's last 90 days of activities or 100 activities, whichever is less
-             duration: 90 days
-             count: 100
-            # trigger if less than 30% of their activities in this time period are comments
+runs:
+  - checks:
+      - name: Low Comment Engagement
+        description: Check if Author is submitting much more than they comment
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: lowComm
+            kind: history
+            criteria:
+              - comment: '< 30%'
+                window:
+                  # get author's last 90 days of activities or 100 activities, whichever is less
+                  duration: 90 days
+                  count: 100
+                # trigger if less than 30% of their activities in this time period are comments
 
-    actions:
-      - kind: report
-        content: >-
-          Low engagement: comments were {{rules.lowcomm.commentPercent}} of
-          {{rules.lowcomm.activityTotal}} over {{rules.lowcomm.window}}
+        actions:
+          - kind: report
+            content: >-
+              Low engagement: comments were {{rules.lowcomm.commentPercent}} of
+              {{rules.lowcomm.activityTotal}} over {{rules.lowcomm.window}}

docs/examples/history/opOnlyEngagement.json5

@@ -1,29 +1,33 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Engaging Own Content Only",
-      "description": "Check if Author is mostly engaging in their own content only",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "opOnly",
-          "kind": "history",
-          "criteria": [
+          "name": "Engaging Own Content Only",
+          "description": "Check if Author is mostly engaging in their own content only",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              // look at last 90 days of Author's activities
-              "window": "90 days",
-              // trigger if more than 60% of their activities in this time period are comments as OP
-              "comment": "> 60% OP"
-            },
+              "name": "opOnly",
+              "kind": "history",
+              "criteria": [
+                {
+                  // look at last 90 days of Author's activities
+                  "window": "90 days",
+                  // trigger if more than 60% of their activities in this time period are comments as OP
+                  "comment": "> 60% OP"
+                },
+              ]
+            }
+          ],
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Selfish OP: {{rules.oponly.opPercent}} of {{rules.oponly.commentTotal}} comments over {{rules.oponly.window}} are as OP"
+            }
           ]
         }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Selfish OP: {{rules.oponly.opPercent}} of {{rules.oponly.commentTotal}} comments over {{rules.oponly.window}} are as OP"
-        }
       ]
     }
   ]

docs/examples/history/opOnlyEngagement.yaml

@@ -1,22 +1,23 @@
-checks:
-  - name: Engaging Own Content Only
-    description: Check if Author is mostly engaging in their own content only
-    # check will run on a new submission in your subreddit and look at the Author of that submission
-    kind: submission
-    rules:
-      - name: opOnly
-        kind: history
-        criteria:
-            # trigger if more than 60% of their activities in this time period are comments as OP
-          - comment: '> 60% OP'
-            window:
-              # get author's last 90 days of activities or 100 activities, whichever is less
-              duration: 90 days
-              count: 100
+runs:
+  - checks:
+      - name: Engaging Own Content Only
+        description: Check if Author is mostly engaging in their own content only
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: opOnly
+            kind: history
+            criteria:
+              # trigger if more than 60% of their activities in this time period are comments as OP
+              - comment: '> 60% OP'
+                window:
+                  # get author's last 90 days of activities or 100 activities, whichever is less
+                  duration: 90 days
+                  count: 100
 
-    actions:
-      - kind: report
-        content: >-
-          Selfish OP: {{rules.oponly.opPercent}} of
-          {{rules.oponly.commentTotal}} comments over {{rules.oponly.window}}
-          are as OP
+        actions:
+          - kind: report
+            content: >-
+              Selfish OP: {{rules.oponly.opPercent}} of
+              {{rules.oponly.commentTotal}} comments over {{rules.oponly.window}}
+              are as OP

docs/examples/onlyfansFlair/onlyfansFlair.json5

@@ -1,66 +1,70 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Flair OF submitters",
-      "description": "Flair submission as OF if user does not have Verified flair and has certain keywords in their profile",
-      "kind": "submission",
-      "authorIs": {
-        "exclude": [
-          {
-            "flairCssClass": ["verified"]
-          }
-        ]
-      },
-      "rules": [
+      "checks": [
         {
-          "name": "OnlyFans strings in description",
-          "kind": "author",
-          "include": [
+          "name": "Flair OF submitters",
+          "description": "Flair submission as OF if user does not have Verified flair and has certain keywords in their profile",
+          "kind": "submission",
+          "authorIs": {
+            "exclude": [
+              {
+                "flairCssClass": ["verified"]
+              }
+            ]
+          },
+          "rules": [
             {
-              "description": [
-                "/(cashapp|allmylinks|linktr|onlyfans\\.com)/i",
-                "/(see|check|my|view) (out|of|onlyfans|kik|skype|insta|ig|profile|links)/i",
-                "my links",
-                "$"
+              "name": "OnlyFans strings in description",
+              "kind": "author",
+              "include": [
+                {
+                  "description": [
+                    "/(cashapp|allmylinks|linktr|onlyfans\\.com)/i",
+                    "/(see|check|my|view) (out|of|onlyfans|kik|skype|insta|ig|profile|links)/i",
+                    "my links",
+                    "$"
+                  ]
+                }
               ]
             }
-          ]
-        }
-      ],
-      "actions": [
-        {
-          "name": "Set OnlyFans user flair",
-          "kind": "userflair",
-          "flair_template_id": "put-your-onlyfans-user-flair-id-here"
-        },
-        {
-          "name":"Set OF Creator SUBMISSION flair",
-          "kind": "flair",
-          "flair_template_id": "put-your-onlyfans-post-flair-id-here"
-        }
-      ]
-    },
-
-    {
-      "name": "Flair posts of OF submitters",
-      "description": "Flair submission as OnlyFans if submitter has OnlyFans userflair (override post flair set by submitter)",
-      "kind": "submission",
-      "rules": [
-        {
-          "name": "Include OF submitters",
-          "kind": "author",
-          "include": [
+          ],
+          "actions": [
             {
-              "flairCssClass": ["onlyfans"]
+              "name": "Set OnlyFans user flair",
+              "kind": "userflair",
+              "flair_template_id": "put-your-onlyfans-user-flair-id-here"
+            },
+            {
+              "name":"Set OF Creator SUBMISSION flair",
+              "kind": "flair",
+              "flair_template_id": "put-your-onlyfans-post-flair-id-here"
             }
           ]
-        }
-      ],
-      "actions": [
+        },
+
         {
-          "name":"Set OF Creator SUBMISSION flair",
-          "kind": "flair",
-          "flair_template_id": "put-your-onlyfans-post-flair-id-here"
+          "name": "Flair posts of OF submitters",
+          "description": "Flair submission as OnlyFans if submitter has OnlyFans userflair (override post flair set by submitter)",
+          "kind": "submission",
+          "rules": [
+            {
+              "name": "Include OF submitters",
+              "kind": "author",
+              "include": [
+                {
+                  "flairCssClass": ["onlyfans"]
+                }
+              ]
+            }
+          ],
+          "actions": [
+            {
+              "name":"Set OF Creator SUBMISSION flair",
+              "kind": "flair",
+              "flair_template_id": "put-your-onlyfans-post-flair-id-here"
+            }
+          ]
         }
       ]
     }

docs/examples/onlyfansFlair/onlyfansFlair.yaml

@@ -1,38 +1,39 @@
-checks:
-  - name: Flair OF submitters
-    description: Flair submission as OF if user does not have Verified flair and has
-      certain keywords in their profile
-    kind: submission
-    authorIs:
-      exclude:
-        - flairCssClass:
-            - verified
-    rules:
-      - name: OnlyFans strings in description
-        kind: author
-        include:
-          - description:
-              - '/(cashapp|allmylinks|linktr|onlyfans\.com)/i'
-              - '/(see|check|my|view) (out|of|onlyfans|kik|skype|insta|ig|profile|links)/i'
-              - my links
-              - "$"
-    actions:
-      - name: Set OnlyFans user flair
-        kind: userflair
-        flair_template_id: put-your-onlyfans-user-flair-id-here
-      - name: Set OF Creator SUBMISSION flair
-        kind: flair
-        flair_template_id: put-your-onlyfans-post-flair-id-here
-  - name: Flair posts of OF submitters
-    description: Flair submission as OnlyFans if submitter has OnlyFans userflair (override post flair set by submitter)
-    kind: submission
-    rules:
-      - name: Include OF submitters
-        kind: author
-        include:
-          - flairCssClass:
-              - onlyfans
-    actions:
-      - name: Set OF Creator SUBMISSION flair
-        kind: flair
-        flair_template_id: put-your-onlyfans-post-flair-id-here
+runs:
+  - checks:
+      - name: Flair OF submitters
+        description: Flair submission as OF if user does not have Verified flair and has
+          certain keywords in their profile
+        kind: submission
+        authorIs:
+          exclude:
+            - flairCssClass:
+                - verified
+        rules:
+          - name: OnlyFans strings in description
+            kind: author
+            include:
+              - description:
+                  - '/(cashapp|allmylinks|linktr|onlyfans\.com)/i'
+                  - '/(see|check|my|view) (out|of|onlyfans|kik|skype|insta|ig|profile|links)/i'
+                  - my links
+                  - "$"
+        actions:
+          - name: Set OnlyFans user flair
+            kind: userflair
+            flair_template_id: put-your-onlyfans-user-flair-id-here
+          - name: Set OF Creator SUBMISSION flair
+            kind: flair
+            flair_template_id: put-your-onlyfans-post-flair-id-here
+      - name: Flair posts of OF submitters
+        description: Flair submission as OnlyFans if submitter has OnlyFans userflair (override post flair set by submitter)
+        kind: submission
+        rules:
+          - name: Include OF submitters
+            kind: author
+            include:
+              - flairCssClass:
+                  - onlyfans
+        actions:
+          - name: Set OF Creator SUBMISSION flair
+            kind: flair
+            flair_template_id: put-your-onlyfans-post-flair-id-here

docs/examples/recentActivity/freeKarma.json5

@@ -1,38 +1,42 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Free Karma Alert",
-      "description": "Check if author has posted in 'freekarma' subreddits",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "freekarma",
-          "kind": "recentActivity",
-          "useSubmissionAsReference": false,
-          // when `lookAt` is not present this rule will look for submissions and comments
-          // lookAt: "submissions"
-          // lookAt: "comments"
-          "thresholds": [
+          "name": "Free Karma Alert",
+          "description": "Check if author has posted in 'freekarma' subreddits",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              // for all subreddits, if the number of activities (sub/comment) is equal to or greater than 1 then the rule is triggered
-              "threshold": ">= 1",
-              "subreddits": [
-                "DeFreeKarma",
-                "FreeKarma4U",
-                "FreeKarma4You",
-                "upvote"
-              ]
+              "name": "freekarma",
+              "kind": "recentActivity",
+              "useSubmissionAsReference": false,
+              // when `lookAt` is not present this rule will look for submissions and comments
+              // lookAt: "submissions"
+              // lookAt: "comments"
+              "thresholds": [
+                {
+                  // for all subreddits, if the number of activities (sub/comment) is equal to or greater than 1 then the rule is triggered
+                  "threshold": ">= 1",
+                  "subreddits": [
+                    "DeFreeKarma",
+                    "FreeKarma4U",
+                    "FreeKarma4You",
+                    "upvote"
+                  ]
+                }
+              ],
+              // will look at all of the Author's activities in the last 7 days
+              "window": "7 days"
             }
           ],
-          // will look at all of the Author's activities in the last 7 days
-          "window": "7 days"
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "{{rules.freekarma.totalCount}} activities in karma {{rules.freekarma.subCount}} subs over {{rules.freekarma.window}}: {{rules.freekarma.subSummary}}"
+          "actions": [
+            {
+              "kind": "report",
+              "content": "{{rules.freekarma.totalCount}} activities in karma {{rules.freekarma.subCount}} subs over {{rules.freekarma.window}}: {{rules.freekarma.subSummary}}"
+            }
+          ]
         }
       ]
     }

docs/examples/recentActivity/freeKarma.yaml

@@ -1,27 +1,28 @@
-checks:
-  - name: Free Karma Alert
-    description: Check if author has posted in 'freekarma' subreddits
-    # check will run on a new submission in your subreddit and look at the Author of that submission
-    kind: submission
-    rules:
-      - name: freekarma
-        kind: recentActivity
-        # // when lookAt is not present this rule will look for submissions and comments
-        #lookAt: comments
-        useSubmissionAsReference: false
-        thresholds:
-            # if the number of activities (sub/comment) found CUMULATIVELY in the subreddits listed is
-            # equal to or greater than 1 then the rule is triggered
-          - threshold: '>= 1'
-            subreddits:
-              - DeFreeKarma
-              - FreeKarma4U
-              - FreeKarma4You
-              - upvote
-        window: 7 days
-    actions:
-      - kind: report
-        content: >-
-          {{rules.freekarma.totalCount}} activities in karma
-          {{rules.freekarma.subCount}} subs over {{rules.freekarma.window}}:
-          {{rules.freekarma.subSummary}}
+runs:
+  - checks:
+      - name: Free Karma Alert
+        description: Check if author has posted in 'freekarma' subreddits
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: freekarma
+            kind: recentActivity
+            # // when lookAt is not present this rule will look for submissions and comments
+            #lookAt: comments
+            useSubmissionAsReference: false
+            thresholds:
+              # if the number of activities (sub/comment) found CUMULATIVELY in the subreddits listed is
+              # equal to or greater than 1 then the rule is triggered
+              - threshold: '>= 1'
+                subreddits:
+                  - DeFreeKarma
+                  - FreeKarma4U
+                  - FreeKarma4You
+                  - upvote
+            window: 7 days
+        actions:
+          - kind: report
+            content: >-
+              {{rules.freekarma.totalCount}} activities in karma
+              {{rules.freekarma.subCount}} subs over {{rules.freekarma.window}}:
+              {{rules.freekarma.subSummary}}

docs/examples/recentActivity/freeKarmaOnSubmission.json5

@@ -1,39 +1,43 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Free Karma On Submission Alert",
-      "description": "Check if author has posted this submission in 'freekarma' subreddits",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "freekarmasub",
-          "kind": "recentActivity",
-          // rule will only look at Author's submissions in these subreddits
-          "lookAt": "submissions",
-          // rule will only look at Author's submissions in these subreddits that have the same content (link) as the submission this event was made on
-          // In simpler terms -- rule will only check to see if the same link the author just posted is also posted in these subreddits
-          "useSubmissionAsReference":true,
-          "thresholds": [
+          "name": "Free Karma On Submission Alert",
+          "description": "Check if author has posted this submission in 'freekarma' subreddits",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              // for all subreddits, if the number of activities (sub/comment) is equal to or greater than 1 then the rule is triggered
-              "threshold": ">= 1",
-              "subreddits": [
-                "DeFreeKarma",
-                "FreeKarma4U",
-                "FreeKarma4You",
-                "upvote"
-              ]
+              "name": "freekarmasub",
+              "kind": "recentActivity",
+              // rule will only look at Author's submissions in these subreddits
+              "lookAt": "submissions",
+              // rule will only look at Author's submissions in these subreddits that have the same content (link) as the submission this event was made on
+              // In simpler terms -- rule will only check to see if the same link the author just posted is also posted in these subreddits
+              "useSubmissionAsReference":true,
+              "thresholds": [
+                {
+                  // for all subreddits, if the number of activities (sub/comment) is equal to or greater than 1 then the rule is triggered
+                  "threshold": ">= 1",
+                  "subreddits": [
+                    "DeFreeKarma",
+                    "FreeKarma4U",
+                    "FreeKarma4You",
+                    "upvote"
+                  ]
+                }
+              ],
+              // look at all of the Author's submissions in the last 7 days
+              "window": "7 days"
             }
           ],
-          // look at all of the Author's submissions in the last 7 days
-          "window": "7 days"
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Submission posted {{rules.freekarmasub.totalCount}} times in karma {{rules.freekarmasub.subCount}} subs over {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}"
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Submission posted {{rules.freekarmasub.totalCount}} times in karma {{rules.freekarmasub.subCount}} subs over {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}"
+            }
+          ]
         }
       ]
     }

docs/examples/recentActivity/freeKarmaOnSubmission.yaml

@@ -1,26 +1,27 @@
-checks:
-  - name: Free Karma On Submission Alert
-    description: Check if author has posted this submission in 'freekarma' subreddits
-    kind: submission
-    rules:
-      - name: freekarmasub
-        kind: recentActivity
-        # rule will only look at Author's submissions in these subreddits
-        lookAt: submissions
-        # rule will only look at Author's submissions in these subreddits that have the same content (link) as the submission this event was made on
-        # In simpler terms -- rule will only check to see if the same link the author just posted is also posted in these subreddits
-        useSubmissionAsReference: true
-        thresholds:
-          - threshold: '>= 1'
-            subreddits:
-              - DeFreeKarma
-              - FreeKarma4U
-              - FreeKarma4You
-              - upvote
-        window: 7 days
-    actions:
-      - kind: report
-        content: >-
-          Submission posted {{rules.freekarmasub.totalCount}} times in karma
-          {{rules.freekarmasub.subCount}} subs over
-          {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}
+runs:
+  - checks:
+      - name: Free Karma On Submission Alert
+        description: Check if author has posted this submission in 'freekarma' subreddits
+        kind: submission
+        rules:
+          - name: freekarmasub
+            kind: recentActivity
+            # rule will only look at Author's submissions in these subreddits
+            lookAt: submissions
+            # rule will only look at Author's submissions in these subreddits that have the same content (link) as the submission this event was made on
+            # In simpler terms -- rule will only check to see if the same link the author just posted is also posted in these subreddits
+            useSubmissionAsReference: true
+            thresholds:
+              - threshold: '>= 1'
+                subreddits:
+                  - DeFreeKarma
+                  - FreeKarma4U
+                  - FreeKarma4You
+                  - upvote
+            window: 7 days
+        actions:
+          - kind: report
+            content: >-
+              Submission posted {{rules.freekarmasub.totalCount}} times in karma
+              {{rules.freekarmasub.subCount}} subs over
+              {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}

docs/examples/regex/removeDiscordSpam.json5

@@ -1,73 +1,77 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "remove discord spam",
-      "notifyOnTrigger": true,
-      "description": "remove comments from users who are spamming discord links",
-      "kind": "comment",
-      "authorIs": {
-        "exclude": [
-          {
-            "isMod": true
-          }
-        ]
-      },
-      "itemIs": [
+      "checks": [
         {
-          "removed": false,
-          "approved": false,
-        }
-      ],
-      "condition": "OR",
-      "rules": [
-        {
-          // set to false if you want to allow comments with a discord link ONLY IF
-          // the author doesn't have a history of spamming discord links
-          // -- basically allows one-off/organic discord links
-          "enable": true,
-          "name": "linkOnlySpam",
-          "kind": "regex",
-          "criteria": [
+          "name": "remove discord spam",
+          "notifyOnTrigger": true,
+          "description": "remove comments from users who are spamming discord links",
+          "kind": "comment",
+          "authorIs": {
+            "exclude": [
+              {
+                "isMod": true
+              }
+            ]
+          },
+          "itemIs": [
             {
-              "name": "only link",
-              "regex": "/^.*(discord\\.gg\\/[\\w\\d]+)$/i",
+              "removed": false,
+              "approved": false,
             }
-          ]
-        },
-        {
-          "condition": "AND",
+          ],
+          "condition": "OR",
           "rules": [
             {
-              "name": "linkAnywhereSpam",
+              // set to false if you want to allow comments with a discord link ONLY IF
+              // the author doesn't have a history of spamming discord links
+              // -- basically allows one-off/organic discord links
+              "enable": true,
+              "name": "linkOnlySpam",
               "kind": "regex",
               "criteria": [
                 {
-                  "name": "contains link anywhere",
-                  "regex": "/^.*(discord\\.gg\\/[\\w\\d]+).*$/i",
+                  "name": "only link",
+                  "regex": "/^.*(discord\\.gg\\/[\\w\\d]+)$/i",
                 }
               ]
             },
             {
-              "name": "linkAnywhereHistoricalSpam",
-              "kind": "regex",
-              "criteria": [
+              "condition": "AND",
+              "rules": [
                 {
-                  "name": "contains links anywhere historically",
-                  "regex": "/^.*(discord\\.gg\\/[\\w\\d]+).*$/i",
-                  "totalMatchThreshold": ">= 3",
-                  "lookAt": "comments",
-                  "window": 10
+                  "name": "linkAnywhereSpam",
+                  "kind": "regex",
+                  "criteria": [
+                    {
+                      "name": "contains link anywhere",
+                      "regex": "/^.*(discord\\.gg\\/[\\w\\d]+).*$/i",
+                    }
+                  ]
+                },
+                {
+                  "name": "linkAnywhereHistoricalSpam",
+                  "kind": "regex",
+                  "criteria": [
+                    {
+                      "name": "contains links anywhere historically",
+                      "regex": "/^.*(discord\\.gg\\/[\\w\\d]+).*$/i",
+                      "totalMatchThreshold": ">= 3",
+                      "lookAt": "comments",
+                      "window": 10
+                    }
+                  ]
                 }
               ]
             }
+          ],
+          "actions": [
+            {
+              "kind": "remove"
+            }
           ]
         }
-      ],
-      "actions": [
-        {
-          "kind": "remove"
-        }
       ]
     }
-  ]
+  ],
 }

docs/examples/regex/removeDiscordSpam.yaml

@@ -1,36 +1,37 @@
-checks:
-  - name: remove discord spam
-    notifyOnTrigger: true
-    description: remove comments from users who are spamming discord links
-    kind: comment
-    authorIs:
-      exclude:
-        - isMod: true
-    itemIs:
-      - removed: false
-        approved: false
-    condition: OR
-    rules:
-      - enable: true
-        name: linkOnlySpam
-        kind: regex
-        criteria:
-          - name: only link
-            regex: '/^.*(discord\.gg\/[\w\d]+)$/i'
-      - condition: AND
+runs:
+  - checks:
+      - name: remove discord spam
+        notifyOnTrigger: true
+        description: remove comments from users who are spamming discord links
+        kind: comment
+        authorIs:
+          exclude:
+            - isMod: true
+        itemIs:
+          - removed: false
+            approved: false
+        condition: OR
         rules:
-          - name: linkAnywhereSpam
+          - enable: true
+            name: linkOnlySpam
             kind: regex
             criteria:
-              - name: contains link anywhere
-                regex: '/^.*(discord\.gg\/[\w\d]+).*$/i'
-          - name: linkAnywhereHistoricalSpam
-            kind: regex
-            criteria:
-              - name: contains links anywhere historically
-                regex: '/^.*(discord\.gg\/[\w\d]+).*$/i'
-                totalMatchThreshold: '>= 3'
-                lookAt: comments
-                window: 10
-    actions:
-      - kind: remove
+              - name: only link
+                regex: '/^.*(discord\.gg\/[\w\d]+)$/i'
+          - condition: AND
+            rules:
+              - name: linkAnywhereSpam
+                kind: regex
+                criteria:
+                  - name: contains link anywhere
+                    regex: '/^.*(discord\.gg\/[\w\d]+).*$/i'
+              - name: linkAnywhereHistoricalSpam
+                kind: regex
+                criteria:
+                  - name: contains links anywhere historically
+                    regex: '/^.*(discord\.gg\/[\w\d]+).*$/i'
+                    totalMatchThreshold: '>= 3'
+                    lookAt: comments
+                    window: 10
+        actions:
+          - kind: remove

docs/examples/repeatActivity/burstPosting.json5

@@ -1,30 +1,34 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Burstpost Spam",
-      "description": "Check if Author is crossposting in short bursts",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "burstpost",
-          "kind": "repeatActivity",
-          // will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
-          "useSubmissionAsReference": true,
-          // the number of non-repeat activities (submissions or comments) to ignore between repeat submissions
-          "gapAllowance": 3,
-          // if the Author has posted this Submission 6 times, ignoring 3 non-repeat activities between each repeat, then this rule will trigger
-          "threshold": ">= 6",
-          // look at all of the Author's submissions in the last 7 days
-          "window": "7 days"
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Author has burst-posted this link {{rules.burstpost.largestRepeat}} times over {{rules.burstpost.window}}"
+          "name": "Burstpost Spam",
+          "description": "Check if Author is crossposting in short bursts",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
+            {
+              "name": "burstpost",
+              "kind": "repeatActivity",
+              // will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
+              "useSubmissionAsReference": true,
+              // the number of non-repeat activities (submissions or comments) to ignore between repeat submissions
+              "gapAllowance": 3,
+              // if the Author has posted this Submission 6 times, ignoring 3 non-repeat activities between each repeat, then this rule will trigger
+              "threshold": ">= 6",
+              // look at all of the Author's submissions in the last 7 days
+              "window": "7 days"
+            }
+          ],
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Author has burst-posted this link {{rules.burstpost.largestRepeat}} times over {{rules.burstpost.window}}"
+            }
+          ]
         }
       ]
     }
-  ]
+  ],
 }

docs/examples/repeatActivity/burstPosting.yaml

@@ -1,23 +1,24 @@
-checks:
-  - name: Burstpost Spam
-    description: Check if Author is crossposting in short bursts
-    # check will run on a new submission in your subreddit and look at the Author of that submission
-    kind: submission
-    rules:
-      - name: burstpost
-        kind: repeatActivity
-        # will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
-        useSubmissionAsReference: true
-        # the number of non-repeat activities (submissions or comments) to ignore between repeat submissions
-        gapAllowance: 3
-        # if the Author has posted this Submission 6 times, ignoring 3 non-repeat activities between each repeat, then this rule will trigger
-        threshold: '>= 6'
-        # look at all of the Author's submissions in the last 7 days or 100 submissions
-        window:
-          duration: 7 days
-          count: 100
-    actions:
-      - kind: report
-        content: >-
-          Author has burst-posted this link {{rules.burstpost.largestRepeat}}
-          times over {{rules.burstpost.window}}
+runs:
+  - checks:
+      - name: Burstpost Spam
+        description: Check if Author is crossposting in short bursts
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: burstpost
+            kind: repeatActivity
+            # will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
+            useSubmissionAsReference: true
+            # the number of non-repeat activities (submissions or comments) to ignore between repeat submissions
+            gapAllowance: 3
+            # if the Author has posted this Submission 6 times, ignoring 3 non-repeat activities between each repeat, then this rule will trigger
+            threshold: '>= 6'
+            # look at all of the Author's submissions in the last 7 days or 100 submissions
+            window:
+              duration: 7 days
+              count: 100
+        actions:
+          - kind: report
+            content: >-
+              Author has burst-posted this link {{rules.burstpost.largestRepeat}}
+              times over {{rules.burstpost.window}}

docs/examples/repeatActivity/crosspostSpamming.json5

@@ -1,26 +1,30 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Crosspost Spam",
-      "description": "Check if Author is spamming Submissions across subreddits",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "xpostspam",
-          "kind": "repeatActivity",
-          // will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
-          "useSubmissionAsReference": true,
-          // if the Author has posted this Submission 5 times consecutively then this rule will trigger
-          "threshold": ">= 5",
-          // look at all of the Author's submissions in the last 7 days
-          "window": "7 days"
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Author has posted this link {{rules.xpostspam.largestRepeat}} times over {{rules.xpostspam.window}}"
+          "name": "Crosspost Spam",
+          "description": "Check if Author is spamming Submissions across subreddits",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
+            {
+              "name": "xpostspam",
+              "kind": "repeatActivity",
+              // will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
+              "useSubmissionAsReference": true,
+              // if the Author has posted this Submission 5 times consecutively then this rule will trigger
+              "threshold": ">= 5",
+              // look at all of the Author's submissions in the last 7 days
+              "window": "7 days"
+            }
+          ],
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Author has posted this link {{rules.xpostspam.largestRepeat}} times over {{rules.xpostspam.window}}"
+            }
+          ]
         }
       ]
     }

docs/examples/repeatActivity/crosspostSpamming.yaml

@@ -1,19 +1,20 @@
-checks:
-  - name: Crosspost Spam
-    description: Check if Author is spamming Submissions across subreddits
-    # check will run on a new submission in your subreddit and look at the Author of that submission
-    kind: submission
-    rules:
-      - name: xpostspam
-        kind: repeatActivity
-        # will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
-        useSubmissionAsReference: true
-        # if the Author has posted this Submission 5 times consecutively then this rule will trigger
-        threshold: '>= 5'
-        # look at all of the Author's submissions in the last 7 days
-        window: 7 days
-    actions:
-      - kind: report
-        content: >-
-          Author has posted this link {{rules.xpostspam.largestRepeat}} times
-          over {{rules.xpostspam.window}}
+runs:
+  - checks:
+      - name: Crosspost Spam
+        description: Check if Author is spamming Submissions across subreddits
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: xpostspam
+            kind: repeatActivity
+            # will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
+            useSubmissionAsReference: true
+            # if the Author has posted this Submission 5 times consecutively then this rule will trigger
+            threshold: '>= 5'
+            # look at all of the Author's submissions in the last 7 days
+            window: 7 days
+        actions:
+          - kind: report
+            content: >-
+              Author has posted this link {{rules.xpostspam.largestRepeat}} times
+              over {{rules.xpostspam.window}}

docs/examples/subredditReady/commentSpam.json5

@@ -1,42 +1,46 @@
 {
   "polling": ["newComm"],
-  "checks": [
+  "runs": [
     {
-      //
-      // Stop users who spam the same comment many times
-      //
-      // Remove a COMMENT if the user has crossposted it at least 4 times in recent history
-      //
-      "name": "low xp comment spam",
-      "description": "X-posted comment >=4x",
-      "kind": "comment",
-      "condition": "AND",
-      "rules": [
+      "checks": [
         {
-          "name": "xPostLow",
-          "kind": "repeatActivity",
-          "gapAllowance": 2,
-          "threshold": ">= 4",
-          "window": {
-            "count": 50,
-            "duration": "6 months"
-          }
-        },
-      ],
-      "actions": [
-        // remove this after confirming behavior is acceptable
-        {
-          "kind": "report",
-          "content": "Remove=> Posted same comment {{rules.xpostlow.largestRepeat}}x times"
-        },
-        //
-        //
-        {
-          "kind": "remove",
-          // remove the line below after confirming behavior is acceptable
-          "dryRun": true
+          //
+          // Stop users who spam the same comment many times
+          //
+          // Remove a COMMENT if the user has crossposted it at least 4 times in recent history
+          //
+          "name": "low xp comment spam",
+          "description": "X-posted comment >=4x",
+          "kind": "comment",
+          "condition": "AND",
+          "rules": [
+            {
+              "name": "xPostLow",
+              "kind": "repeatActivity",
+              "gapAllowance": 2,
+              "threshold": ">= 4",
+              "window": {
+                "count": 50,
+                "duration": "6 months"
+              }
+            },
+          ],
+          "actions": [
+            // remove this after confirming behavior is acceptable
+            {
+              "kind": "report",
+              "content": "Remove=> Posted same comment {{rules.xpostlow.largestRepeat}}x times"
+            },
+            //
+            //
+            {
+              "kind": "remove",
+              // remove the line below after confirming behavior is acceptable
+              "dryRun": true
+            }
+          ]
         }
       ]
     }
-  ]
+  ],
 }

docs/examples/subredditReady/commentSpam.yaml

@@ -1,25 +1,26 @@
 polling:
   - newComm
-checks:
-    # Stop users who spam the same comment many times
-  - name: low xp comment spam
-    description: X-posted comment >=4x
-    kind: comment
-    condition: AND
-    rules:
-      - name: xPostLow
-        kind: repeatActivity
-        # number of "non-repeat" comments allowed between "repeat comments"
-        gapAllowance: 2
-        # greater or more than 4 repeat comments triggers this rule
-        threshold: '>= 4'
-        # retrieve either last 50 comments or 6 months' of history, whichever is less
-        window:
-          count: 50
-          duration: 6 months
-    actions:
-      - kind: report
-        enable: true
-        content: 'Remove => Posted same comment {{rules.xpostlow.largestRepeat}}x times'
-      - kind: remove
-        enable: true
+runs:
+  - checks:
+      # Stop users who spam the same comment many times
+      - name: low xp comment spam
+        description: X-posted comment >=4x
+        kind: comment
+        condition: AND
+        rules:
+          - name: xPostLow
+            kind: repeatActivity
+            # number of "non-repeat" comments allowed between "repeat comments"
+            gapAllowance: 2
+            # greater or more than 4 repeat comments triggers this rule
+            threshold: '>= 4'
+            # retrieve either last 50 comments or 6 months' of history, whichever is less
+            window:
+              count: 50
+              duration: 6 months
+        actions:
+          - kind: report
+            enable: true
+            content: 'Remove => Posted same comment {{rules.xpostlow.largestRepeat}}x times'
+          - kind: remove
+            enable: true

docs/examples/subredditReady/crosspostSpam.json5

@@ -1,77 +1,81 @@
 {
   "polling": ["unmoderated"],
-  "checks": [
+  "runs": [
     {
-      //
-      // Stop users who post low-effort, crossposted spam
-      //
-      // Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
-      // less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
-      //
-      "name": "low xp spam and engagement",
-      "description": "X-posted 4x and low comment engagement",
-      "kind": "submission",
-      "itemIs": [
+      "checks": [
         {
-          "removed": false
-        }
-      ],
-      "condition": "AND",
-      "rules": [
-        {
-          "name": "xPostLow",
-          "kind": "repeatActivity",
-          "gapAllowance": 2,
-          "threshold": ">= 4",
-          "window": {
-            "count": 50,
-            "duration": "6 months"
-          }
-        },
-        {
-          "name": "lowOrOpComm",
-          "kind": "history",
-          "criteriaJoin": "OR",
-          "criteria": [
+          //
+          // Stop users who post low-effort, crossposted spam
+          //
+          // Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
+          // less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+          //
+          "name": "low xp spam and engagement",
+          "description": "X-posted 4x and low comment engagement",
+          "kind": "submission",
+          "itemIs": [
             {
+              "removed": false
+            }
+          ],
+          "condition": "AND",
+          "rules": [
+            {
+              "name": "xPostLow",
+              "kind": "repeatActivity",
+              "gapAllowance": 2,
+              "threshold": ">= 4",
               "window": {
-                "count": 100,
+                "count": 50,
                 "duration": "6 months"
-              },
-              "comment": "< 50%"
+              }
             },
             {
-              "window": {
-                "count": 100,
-                "duration": "6 months"
-              },
-              "comment": "> 40% OP"
+              "name": "lowOrOpComm",
+              "kind": "history",
+              "criteriaJoin": "OR",
+              "criteria": [
+                {
+                  "window": {
+                    "count": 100,
+                    "duration": "6 months"
+                  },
+                  "comment": "< 50%"
+                },
+                {
+                  "window": {
+                    "count": 100,
+                    "duration": "6 months"
+                  },
+                  "comment": "> 40% OP"
+                }
+              ]
+            }
+          ],
+          "actions": [
+            // remove this after confirming behavior is acceptable
+            {
+              "kind": "report",
+              "content": "Remove=>{{rules.xpostlow.largestRepeat}} X-P => {{rules.loworopcomm.thresholdSummary}}"
+            },
+            //
+            //
+            {
+              "kind": "remove",
+              // remove the line below after confirming behavior is acceptable
+              "dryRun": true
+            },
+            // optionally remove "dryRun" from below if you want to leave a comment on removal
+            // PROTIP: the comment is bland, you should make it better
+            {
+              "kind": "comment",
+              "content": "Your submission has been removed because you cross-posted it {{rules.xpostlow.largestRepeat}} times and you have very low engagement outside of making submissions",
+              "distinguish": true,
+              "dryRun": true
             }
           ]
         }
-      ],
-      "actions": [
-        // remove this after confirming behavior is acceptable
-        {
-          "kind": "report",
-          "content": "Remove=>{{rules.xpostlow.largestRepeat}} X-P => {{rules.loworopcomm.thresholdSummary}}"
-        },
-        //
-        //
-        {
-          "kind": "remove",
-          // remove the line below after confirming behavior is acceptable
-          "dryRun": true
-        },
-        // optionally remove "dryRun" from below if you want to leave a comment on removal
-        // PROTIP: the comment is bland, you should make it better
-       {
-          "kind": "comment",
-          "content": "Your submission has been removed because you cross-posted it {{rules.xpostlow.largestRepeat}} times and you have very low engagement outside of making submissions",
-          "distinguish": true,
-          "dryRun": true
-        }
       ]
     }
-  ]
+  ],
 }

docs/examples/subredditReady/crosspostSpam.yaml

@@ -1,48 +1,49 @@
 polling:
   - unmoderated
-checks:
-#   stop users who post low-effort, crossposted spam submissions
-#
-#   Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
-#   less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
-  - name: low xp spam and engagement
-    description: X-posted 4x and low comment engagement
-    kind: submission
-    itemIs:
-      - removed: false
-    condition: AND
-    rules:
-      - name: xPostLow
-        kind: repeatActivity
-        gapAllowance: 2
-        threshold: '>= 4'
-        window:
-          count: 50
-          duration: 6 months
-      - name: lowOrOpComm
-        kind: history
-        criteriaJoin: OR
-        criteria:
-          - window:
-              count: 100
+runs:
+  - checks:
+      #   stop users who post low-effort, crossposted spam submissions
+      #
+      #   Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
+      #   less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+      - name: low xp spam and engagement
+        description: X-posted 4x and low comment engagement
+        kind: submission
+        itemIs:
+          - removed: false
+        condition: AND
+        rules:
+          - name: xPostLow
+            kind: repeatActivity
+            gapAllowance: 2
+            threshold: '>= 4'
+            window:
+              count: 50
               duration: 6 months
-            comment: < 50%
-          - window:
-              count: 100
-              duration: 6 months
-            comment: '> 40% OP'
-    actions:
-      - kind: report
-        enable: true
-        content: >-
-          Remove=>{{rules.xpostlow.largestRepeat}} X-P =>
-          {{rules.loworopcomm.thresholdSummary}}
-      - kind: remove
-        enable: true
-      - kind: comment
-        enable: true
-        content: >-
-          Your submission has been removed because you cross-posted it
-          {{rules.xpostlow.largestRepeat}} times and you have very low
-          engagement outside of making submissions
-        distinguish: true
+          - name: lowOrOpComm
+            kind: history
+            criteriaJoin: OR
+            criteria:
+              - window:
+                  count: 100
+                  duration: 6 months
+                comment: < 50%
+              - window:
+                  count: 100
+                  duration: 6 months
+                comment: '> 40% OP'
+        actions:
+          - kind: report
+            enable: true
+            content: >-
+              Remove=>{{rules.xpostlow.largestRepeat}} X-P =>
+              {{rules.loworopcomm.thresholdSummary}}
+          - kind: remove
+            enable: true
+          - kind: comment
+            enable: true
+            content: >-
+              Your submission has been removed because you cross-posted it
+              {{rules.xpostlow.largestRepeat}} times and you have very low
+              engagement outside of making submissions
+            distinguish: true

docs/examples/subredditReady/discordSpam.json5

@@ -1,75 +1,79 @@
 {
   "polling": ["newComm"],
-  "checks": [
+  "runs": [
     {
-      "name": "ban discord only spammer",
-      "description": "ban a user who spams only a discord link many times historically",
-      "kind": "comment",
-      "condition": "AND",
-      "rules": [
-        "linkOnlySpam",
-        "linkAnywhereHistoricalSpam",
-      ],
-      "actions": [
+      "checks": [
         {
-          "kind": "remove"
-        },
-        {
-          "kind": "ban",
-          "content": "spamming discord links"
-        }
-      ]
-    },
-    {
-      "name": "remove discord spam",
-      "description": "remove comments from users who only link to discord or mention discord link many times historically",
-      "kind": "comment",
-      "condition": "OR",
-      "rules": [
-        {
-          "name": "linkOnlySpam",
-          "kind": "regex",
-          "criteria": [
+          "name": "ban discord only spammer",
+          "description": "ban a user who spams only a discord link many times historically",
+          "kind": "comment",
+          "condition": "AND",
+          "rules": [
+            "linkOnlySpam",
+            "linkAnywhereHistoricalSpam",
+          ],
+          "actions": [
             {
-              "name": "only link",
-              "regex": "/^.*(discord\\.gg\\/[\\w\\d]+)$/i",
+              "kind": "remove"
+            },
+            {
+              "kind": "ban",
+              "content": "spamming discord links"
             }
           ]
         },
         {
-          "condition": "AND",
+          "name": "remove discord spam",
+          "description": "remove comments from users who only link to discord or mention discord link many times historically",
+          "kind": "comment",
+          "condition": "OR",
           "rules": [
             {
-              "name": "linkAnywhereSpam",
+              "name": "linkOnlySpam",
               "kind": "regex",
               "criteria": [
                 {
-                  "name": "contains link anywhere",
-                  "regex": "/^.*(discord\\.gg\\/[\\w\\d]+).*$/i",
+                  "name": "only link",
+                  "regex": "/^.*(discord\\.gg\\/[\\w\\d]+)$/i",
                 }
               ]
             },
             {
-              "name": "linkAnywhereHistoricalSpam",
-              "kind": "regex",
-              "criteria": [
+              "condition": "AND",
+              "rules": [
                 {
-                  "name": "contains links anywhere historically",
-                  "regex": "/^.*(discord\\.gg\\/[\\w\\d]+).*$/i",
-                  "totalMatchThreshold": ">= 3",
-                  "lookAt": "comments",
-                  "window": 10
+                  "name": "linkAnywhereSpam",
+                  "kind": "regex",
+                  "criteria": [
+                    {
+                      "name": "contains link anywhere",
+                      "regex": "/^.*(discord\\.gg\\/[\\w\\d]+).*$/i",
+                    }
+                  ]
+                },
+                {
+                  "name": "linkAnywhereHistoricalSpam",
+                  "kind": "regex",
+                  "criteria": [
+                    {
+                      "name": "contains links anywhere historically",
+                      "regex": "/^.*(discord\\.gg\\/[\\w\\d]+).*$/i",
+                      "totalMatchThreshold": ">= 3",
+                      "lookAt": "comments",
+                      "window": 10
+                    }
+                  ]
                 }
               ]
             }
+          ],
+          "actions": [
+            {
+              "kind": "remove"
+            }
           ]
         }
-      ],
-      "actions": [
-        {
-          "kind": "remove"
-        }
       ]
     }
-  ]
+  ],
 }

docs/examples/subredditReady/discordSpam.yaml

@@ -1,46 +1,47 @@
 polling:
     - newComm
-checks:
-    - name: ban discord only spammer
-      description: ban a user who spams only a discord link many times historically
-      kind: comment
-      condition: AND
-      rules:
+runs:
+  - checks:
+      - name: ban discord only spammer
+        description: ban a user who spams only a discord link many times historically
+        kind: comment
+        condition: AND
+        rules:
           - linkOnlySpam
           - linkAnywhereHistoricalSpam
-      actions:
+        actions:
           - kind: remove
           - kind: ban
             content: spamming discord links
-    - name: remove discord spam
-      description: >-
+      - name: remove discord spam
+        description: >-
           remove comments from users who only link to discord or mention discord
           link many times historically
-      kind: comment
-      condition: OR
-      rules:
+        kind: comment
+        condition: OR
+        rules:
           - name: linkOnlySpam
             kind: regex
             criteria:
-                - name: only link
-                  # single quotes are required to escape special characters
-                  regex: '/^.*(discord\.gg\/[\w\d]+)$/i'
+              - name: only link
+                # single quotes are required to escape special characters
+                regex: '/^.*(discord\.gg\/[\w\d]+)$/i'
           - condition: AND
             rules:
-                - name: linkAnywhereSpam
-                  kind: regex
-                  criteria:
-                      - name: contains link anywhere
-                        # single quotes are required to escape special characters
-                        regex: '/^.*(discord\.gg\/[\w\d]+).*$/i'
-                - name: linkAnywhereHistoricalSpam
-                  kind: regex
-                  criteria:
-                      - name: contains links anywhere historically
-                        # single quotes are required to escape special characters
-                        regex: '/^.*(discord\.gg\/[\w\d]+).*$/i'
-                        totalMatchThreshold: '>= 3'
-                        lookAt: comments
-                        window: 10
-      actions:
+              - name: linkAnywhereSpam
+                kind: regex
+                criteria:
+                  - name: contains link anywhere
+                    # single quotes are required to escape special characters
+                    regex: '/^.*(discord\.gg\/[\w\d]+).*$/i'
+              - name: linkAnywhereHistoricalSpam
+                kind: regex
+                criteria:
+                  - name: contains links anywhere historically
+                    # single quotes are required to escape special characters
+                    regex: '/^.*(discord\.gg\/[\w\d]+).*$/i'
+                    totalMatchThreshold: '>= 3'
+                    lookAt: comments
+                    window: 10
+        actions:
           - kind: remove

docs/examples/subredditReady/freeKarmaOrCrosspostSpam.json5

@@ -2,135 +2,139 @@
   "polling": [
     "unmoderated"
   ],
-  "checks": [
+  "runs": [
     {
-      //
-      // Stop users who post low-effort, crossposted spam
-      //
-      // Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
-      // less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
-      //
-      "name": "remove on low xp spam and engagement",
-      "description": "X-posted 4x and low comment engagement",
-      "kind": "submission",
-      "itemIs": [
+      "checks": [
         {
-          "removed": false
-        }
-      ],
-      "condition": "AND",
-      "rules": [
-        {
-          "name": "xPostLow",
-          "kind": "repeatActivity",
-          "gapAllowance": 2,
-          "threshold": ">= 4",
-          "window": {
-            "count": 50,
-            "duration": "6 months"
-          }
-        },
-        {
-          "name": "lowOrOpComm",
-          "kind": "history",
-          "criteriaJoin": "OR",
-          "criteria": [
+          //
+          // Stop users who post low-effort, crossposted spam
+          //
+          // Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
+          // less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+          //
+          "name": "remove on low xp spam and engagement",
+          "description": "X-posted 4x and low comment engagement",
+          "kind": "submission",
+          "itemIs": [
             {
+              "removed": false
+            }
+          ],
+          "condition": "AND",
+          "rules": [
+            {
+              "name": "xPostLow",
+              "kind": "repeatActivity",
+              "gapAllowance": 2,
+              "threshold": ">= 4",
               "window": {
-                "count": 100,
+                "count": 50,
                 "duration": "6 months"
-              },
-              "comment": "< 50%"
+              }
             },
             {
-              "window": {
-                "count": 100,
-                "duration": "6 months"
-              },
-              "comment": "> 40% OP"
-            }
-          ]
-        }
-      ],
-      "actions": [
-        // remove this after confirming behavior is acceptable
-        {
-          "kind": "report",
-          "content": "Remove=>{{rules.xpostlow.largestRepeat}} X-P => {{rules.loworopcomm.thresholdSummary}}"
-        },
-        //
-        //
-        {
-          "kind": "remove",
-          // remove the line below after confirming behavior is acceptable
-          "dryRun": true
-        },
-        // optionally remove "dryRun" from below if you want to leave a comment on removal
-        // PROTIP: the comment is bland, you should make it better
-        {
-          "kind": "comment",
-          "content": "Your submission has been removed because you cross-posted it {{rules.xpostlow.largestRepeat}} times and you have very low engagement outside of making submissions",
-          "distinguish": true,
-          "dryRun": true
-        }
-      ]
-    },
-    {
-      //
-      // Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
-      //
-      "name": "freekarma removal",
-      "description": "Remove submission if user has used freekarma sub recently",
-      "kind": "submission",
-      "itemIs": [
-        {
-          "removed": false
-        }
-      ],
-      "condition": "AND",
-      "rules": [
-        {
-          "name": "freekarma",
-          "kind": "recentActivity",
-          "window": {
-            "count": 50,
-            "duration": "6 months"
-          },
-          "useSubmissionAsReference": false,
-          "thresholds": [
-            {
-              "subreddits": [
-                "FreeKarma4U",
-                "FreeKarma4You",
-                "KarmaStore",
-                "promote",
-                "shamelessplug",
-                "upvote"
+              "name": "lowOrOpComm",
+              "kind": "history",
+              "criteriaJoin": "OR",
+              "criteria": [
+                {
+                  "window": {
+                    "count": 100,
+                    "duration": "6 months"
+                  },
+                  "comment": "< 50%"
+                },
+                {
+                  "window": {
+                    "count": 100,
+                    "duration": "6 months"
+                  },
+                  "comment": "> 40% OP"
+                }
               ]
             }
+          ],
+          "actions": [
+            // remove this after confirming behavior is acceptable
+            {
+              "kind": "report",
+              "content": "Remove=>{{rules.xpostlow.largestRepeat}} X-P => {{rules.loworopcomm.thresholdSummary}}"
+            },
+            //
+            //
+            {
+              "kind": "remove",
+              // remove the line below after confirming behavior is acceptable
+              "dryRun": true
+            },
+            // optionally remove "dryRun" from below if you want to leave a comment on removal
+            // PROTIP: the comment is bland, you should make it better
+            {
+              "kind": "comment",
+              "content": "Your submission has been removed because you cross-posted it {{rules.xpostlow.largestRepeat}} times and you have very low engagement outside of making submissions",
+              "distinguish": true,
+              "dryRun": true
+            }
           ]
-        }
-      ],
-      "actions": [
-        // remove this after confirming behavior is acceptable
-        {
-          "kind": "report",
-          "content": "Remove=> {{rules.newtube.totalCount}} activities in freekarma subs"
         },
-        //
-        //
         {
-          "kind": "remove",
-          // remove the line below after confirming behavior is acceptable
-          "dryRun": true
-        },
-        // optionally remove "dryRun" from below if you want to leave a comment on removal
-        // PROTIP: the comment is bland, you should make it better
-        {
-          "kind": "comment",
-          "content": "Your submission has been removed because you have recent activity in 'freekarma' subs",
-          "distinguish": true,
-          "dryRun": true
+          //
+          // Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
+          //
+          "name": "freekarma removal",
+          "description": "Remove submission if user has used freekarma sub recently",
+          "kind": "submission",
+          "itemIs": [
+            {
+              "removed": false
+            }
+          ],
+          "condition": "AND",
+          "rules": [
+            {
+              "name": "freekarma",
+              "kind": "recentActivity",
+              "window": {
+                "count": 50,
+                "duration": "6 months"
+              },
+              "useSubmissionAsReference": false,
+              "thresholds": [
+                {
+                  "subreddits": [
+                    "FreeKarma4U",
+                    "FreeKarma4You",
+                    "KarmaStore",
+                    "promote",
+                    "shamelessplug",
+                    "upvote"
+                  ]
+                }
+              ]
+            }
+          ],
+          "actions": [
+            // remove this after confirming behavior is acceptable
+            {
+              "kind": "report",
+              "content": "Remove=> {{rules.newtube.totalCount}} activities in freekarma subs"
+            },
+            //
+            //
+            {
+              "kind": "remove",
+              // remove the line below after confirming behavior is acceptable
+              "dryRun": true
+            },
+            // optionally remove "dryRun" from below if you want to leave a comment on removal
+            // PROTIP: the comment is bland, you should make it better
+            {
+              "kind": "comment",
+              "content": "Your submission has been removed because you have recent activity in 'freekarma' subs",
+              "distinguish": true,
+              "dryRun": true
+            }
+          ]
         }
       ]
     }

docs/examples/subredditReady/freeKarmaOrCrosspostSpam.yaml

@@ -1,84 +1,85 @@
 polling:
   - unmoderated
-checks:
-    #   stop users who post low-effort, crossposted spam submissions
-    #
-    #   Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
-    #   less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
-  - name: remove on low xp spam and engagement
-    description: X-posted 4x and low comment engagement
-    kind: submission
-    itemIs:
-      - removed: false
-    condition: AND
-    rules:
-      - name: xPostLow
-        kind: repeatActivity
-        gapAllowance: 2
-        threshold: '>= 4'
-        window:
-          count: 50
-          duration: 6 months
-      - name: lowOrOpComm
-        kind: history
-        criteriaJoin: OR
-        criteria:
-          - window:
-              count: 100
+runs:
+  - checks:
+      #   stop users who post low-effort, crossposted spam submissions
+      #
+      #   Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
+      #   less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+      - name: remove on low xp spam and engagement
+        description: X-posted 4x and low comment engagement
+        kind: submission
+        itemIs:
+          - removed: false
+        condition: AND
+        rules:
+          - name: xPostLow
+            kind: repeatActivity
+            gapAllowance: 2
+            threshold: '>= 4'
+            window:
+              count: 50
               duration: 6 months
-            comment: < 50%
-          - window:
-              count: 100
+          - name: lowOrOpComm
+            kind: history
+            criteriaJoin: OR
+            criteria:
+              - window:
+                  count: 100
+                  duration: 6 months
+                comment: < 50%
+              - window:
+                  count: 100
+                  duration: 6 months
+                comment: '> 40% OP'
+        actions:
+          - kind: report
+            enable: true
+            content: >-
+              Remove=>{{rules.xpostlow.largestRepeat}} X-P =>
+              {{rules.loworopcomm.thresholdSummary}}
+          - kind: remove
+            enable: false
+          - kind: comment
+            enable: true
+            content: >-
+              Your submission has been removed because you cross-posted it
+              {{rules.xpostlow.largestRepeat}} times and you have very low
+              engagement outside of making submissions
+            distinguish: true
+            dryRun: true
+        # Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
+      - name: freekarma removal
+        description: Remove submission if user has used freekarma sub recently
+        kind: submission
+        itemIs:
+          - removed: false
+        condition: AND
+        rules:
+          - name: freekarma
+            kind: recentActivity
+            window:
+              count: 50
               duration: 6 months
-            comment: '> 40% OP'
-    actions:
-      - kind: report
-        enable: true
-        content: >-
-          Remove=>{{rules.xpostlow.largestRepeat}} X-P =>
-          {{rules.loworopcomm.thresholdSummary}}
-      - kind: remove
-        enable: false
-      - kind: comment
-        enable: true
-        content: >-
-          Your submission has been removed because you cross-posted it
-          {{rules.xpostlow.largestRepeat}} times and you have very low
-          engagement outside of making submissions
-        distinguish: true
-        dryRun: true
-    # Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
-  - name: freekarma removal
-    description: Remove submission if user has used freekarma sub recently
-    kind: submission
-    itemIs:
-      - removed: false
-    condition: AND
-    rules:
-      - name: freekarma
-        kind: recentActivity
-        window:
-          count: 50
-          duration: 6 months
-        useSubmissionAsReference: false
-        thresholds:
-          - subreddits:
-              - FreeKarma4U
-              - FreeKarma4You
-              - KarmaStore
-              - promote
-              - shamelessplug
-              - upvote
-    actions:
-      - kind: report
-        enable: true
-        content: 'Remove=> {{rules.newtube.totalCount}} activities in freekarma subs'
-      - kind: remove
-        enable: false
-      - kind: comment
-        enable: true
-        content: >-
-          Your submission has been removed because you have recent activity in
-          'freekarma' subs
-        distinguish: true
-        dryRun: true
+            useSubmissionAsReference: false
+            thresholds:
+              - subreddits:
+                  - FreeKarma4U
+                  - FreeKarma4You
+                  - KarmaStore
+                  - promote
+                  - shamelessplug
+                  - upvote
+        actions:
+          - kind: report
+            enable: true
+            content: 'Remove=> {{rules.newtube.totalCount}} activities in freekarma subs'
+          - kind: remove
+            enable: false
+          - kind: comment
+            enable: true
+            content: >-
+              Your submission has been removed because you have recent activity in
+              'freekarma' subs
+            distinguish: true
+            dryRun: true

docs/examples/subredditReady/freekarma.json5

@@ -2,63 +2,67 @@
   "polling": [
     "unmoderated"
   ],
-  "checks": [
+  "runs": [
     {
-      //
-      // Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
-      //
-      "name": "freekarma removal",
-      "description": "Remove submission if user has used freekarma sub recently",
-      "kind": "submission",
-      "itemIs": [
+      "checks": [
         {
-          "removed": false
-        }
-      ],
-      "condition": "AND",
-      "rules": [
-        {
-          "name": "freekarma",
-          "kind": "recentActivity",
-          "window": {
-            "count": 50,
-            "duration": "6 months"
-          },
-          "useSubmissionAsReference": false,
-          "thresholds": [
+          //
+          // Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
+          //
+          "name": "freekarma removal",
+          "description": "Remove submission if user has used freekarma sub recently",
+          "kind": "submission",
+          "itemIs": [
             {
-              "subreddits": [
-                "FreeKarma4U",
-                "FreeKarma4You",
-                "KarmaStore",
-                "upvote"
+              "removed": false
+            }
+          ],
+          "condition": "AND",
+          "rules": [
+            {
+              "name": "freekarma",
+              "kind": "recentActivity",
+              "window": {
+                "count": 50,
+                "duration": "6 months"
+              },
+              "useSubmissionAsReference": false,
+              "thresholds": [
+                {
+                  "subreddits": [
+                    "FreeKarma4U",
+                    "FreeKarma4You",
+                    "KarmaStore",
+                    "upvote"
+                  ]
+                }
               ]
             }
+          ],
+          "actions": [
+            // remove this after confirming behavior is acceptable
+            {
+              "kind": "report",
+              "content": "Remove=> {{rules.newtube.totalCount}} activities in freekarma subs"
+            },
+            //
+            //
+            {
+              "kind": "remove",
+              // remove the line below after confirming behavior is acceptable
+              "dryRun": true,
+            },
+            // optionally remove "dryRun" from below if you want to leave a comment on removal
+            // PROTIP: the comment is bland, you should make it better
+            {
+              "kind": "comment",
+              "content": "Your submission has been removed because you have recent activity in 'freekarma' subs",
+              "distinguish": true,
+              "dryRun": true,
+            }
           ]
         }
-      ],
-      "actions": [
-        // remove this after confirming behavior is acceptable
-        {
-          "kind": "report",
-          "content": "Remove=> {{rules.newtube.totalCount}} activities in freekarma subs"
-        },
-        //
-        //
-        {
-          "kind": "remove",
-          // remove the line below after confirming behavior is acceptable
-          "dryRun": true,
-        },
-        // optionally remove "dryRun" from below if you want to leave a comment on removal
-        // PROTIP: the comment is bland, you should make it better
-        {
-          "kind": "comment",
-          "content": "Your submission has been removed because you have recent activity in 'freekarma' subs",
-          "distinguish": true,
-          "dryRun": true,
-        }
       ]
     }
-  ]
+  ],
 }

docs/examples/subredditReady/freekarma.yaml

@@ -1,35 +1,36 @@
 polling:
   - unmoderated
-checks:
-    # Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
-  - name: freekarma removal
-    description: Remove submission if user has used freekarma sub recently
-    kind: submission
-    itemIs:
-      - removed: false
-    condition: AND
-    rules:
-      - name: freekarma
-        kind: recentActivity
-        window:
-          count: 50
-          duration: 6 months
-        useSubmissionAsReference: false
-        thresholds:
-          - subreddits:
-              - FreeKarma4U
-              - FreeKarma4You
-              - KarmaStore
-              - upvote
-    actions:
-      - kind: report
-        enable: true
-        content: 'Remove=> {{rules.newtube.totalCount}} activities in freekarma subs'
-      - kind: remove
-        enable: true
-      - kind: comment
-        enable: false
-        content: >-
-          Your submission has been removed because you have recent activity in
-          'freekarma' subs
-        distinguish: true
+runs:
+  - checks:
+      # Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
+      - name: freekarma removal
+        description: Remove submission if user has used freekarma sub recently
+        kind: submission
+        itemIs:
+          - removed: false
+        condition: AND
+        rules:
+          - name: freekarma
+            kind: recentActivity
+            window:
+              count: 50
+              duration: 6 months
+            useSubmissionAsReference: false
+            thresholds:
+              - subreddits:
+                  - FreeKarma4U
+                  - FreeKarma4You
+                  - KarmaStore
+                  - upvote
+        actions:
+          - kind: report
+            enable: true
+            content: 'Remove=> {{rules.newtube.totalCount}} activities in freekarma subs'
+          - kind: remove
+            enable: true
+          - kind: comment
+            enable: false
+            content: >-
+              Your submission has been removed because you have recent activity in
+              'freekarma' subs
+            distinguish: true

docs/examples/subredditReady/selfPromo.json5

@@ -2,48 +2,30 @@
   "polling": [
     "unmoderated"
   ],
-  "checks": [
+  "runs": [
     {
-      //
-      // Stop users who make link submissions with a self-promotional agenda (with reddit's suggested 10% rule)
-      // https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit
-      //
-      // Remove a SUBMISSION if the link comprises more than or equal to 10% of users history (100 activities or 6 months) OR
-      //
-      // if link comprises 10% of submission history (100 activities or 6 months)
-      // AND less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
-      //
-      "name": "Self-promo all AND low engagement",
-      "description": "Self-promo is >10% for all or just sub and low comment engagement",
-      "kind": "submission",
-      "condition": "OR",
-      "rules": [
+      "checks": [
         {
-          "name": "attr",
-          "kind": "attribution",
-          "criteria": [
-            {
-              "threshold": ">= 10%",
-              "window": {
-                "count": 100,
-                "duration": "6 months"
-              },
-              "domains": [
-                "AGG:SELF"
-              ]
-            }
-          ],
-        },
-        {
-          "condition": "AND",
+          //
+          // Stop users who make link submissions with a self-promotional agenda (with reddit's suggested 10% rule)
+          // https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit
+          //
+          // Remove a SUBMISSION if the link comprises more than or equal to 10% of users history (100 activities or 6 months) OR
+          //
+          // if link comprises 10% of submission history (100 activities or 6 months)
+          // AND less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+          //
+          "name": "Self-promo all AND low engagement",
+          "description": "Self-promo is >10% for all or just sub and low comment engagement",
+          "kind": "submission",
+          "condition": "OR",
           "rules": [
             {
-              "name": "attrsub",
+              "name": "attr",
               "kind": "attribution",
               "criteria": [
                 {
                   "threshold": ">= 10%",
-                  "thresholdOn": "submissions",
                   "window": {
                     "count": 100,
                     "duration": "6 months"
@@ -52,52 +34,74 @@
                     "AGG:SELF"
                   ]
                 }
-              ]
+              ],
             },
             {
-              "name": "lowOrOpComm",
-              "kind": "history",
-              "criteriaJoin": "OR",
-              "criteria": [
+              "condition": "AND",
+              "rules": [
                 {
-                  "window": {
-                    "count": 100,
-                    "duration": "6 months"
-                  },
-                  "comment": "< 50%"
+                  "name": "attrsub",
+                  "kind": "attribution",
+                  "criteria": [
+                    {
+                      "threshold": ">= 10%",
+                      "thresholdOn": "submissions",
+                      "window": {
+                        "count": 100,
+                        "duration": "6 months"
+                      },
+                      "domains": [
+                        "AGG:SELF"
+                      ]
+                    }
+                  ]
                 },
                 {
-                  "window": {
-                    "count": 100,
-                    "duration": "6 months"
-                  },
-                  "comment": "> 40% OP"
+                  "name": "lowOrOpComm",
+                  "kind": "history",
+                  "criteriaJoin": "OR",
+                  "criteria": [
+                    {
+                      "window": {
+                        "count": 100,
+                        "duration": "6 months"
+                      },
+                      "comment": "< 50%"
+                    },
+                    {
+                      "window": {
+                        "count": 100,
+                        "duration": "6 months"
+                      },
+                      "comment": "> 40% OP"
+                    }
+                  ]
                 }
               ]
             }
+          ],
+          "actions": [
+            {
+              "kind": "report",
+              "content": "{{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}} of {{rules.attr.activityTotal}}{{rules.attrsub.activityTotal}} items ({{rules.attr.window}}{{rules.attrsub.window}}){{#rules.loworopcomm.thresholdSummary}} => {{rules.loworopcomm.thresholdSummary}}{{/rules.loworopcomm.thresholdSummary}}"
+            },
+            //
+            //
+            {
+              "kind": "remove",
+              // remove the line below after confirming behavior is acceptable
+              "dryRun": true
+            },
+            // optionally remove "dryRun" from below if you want to leave a comment on removal
+            // PROTIP: the comment is bland, you should make it better
+            {
+              "kind": "comment",
+              "content": "Your submission has been removed it comprises 10% or more of your recent history ({{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}}). This is against [reddit's self promotional guidelines.](https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit)",
+              "distinguish": true,
+              "dryRun": true
+            }
           ]
         }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "{{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}} of {{rules.attr.activityTotal}}{{rules.attrsub.activityTotal}} items ({{rules.attr.window}}{{rules.attrsub.window}}){{#rules.loworopcomm.thresholdSummary}} => {{rules.loworopcomm.thresholdSummary}}{{/rules.loworopcomm.thresholdSummary}}"
-        },
-        //
-        //
-        {
-          "kind": "remove",
-          // remove the line below after confirming behavior is acceptable
-          "dryRun": true
-        },
-        // optionally remove "dryRun" from below if you want to leave a comment on removal
-        // PROTIP: the comment is bland, you should make it better
-        {
-          "kind": "comment",
-          "content": "Your submission has been removed it comprises 10% or more of your recent history ({{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}}). This is against [reddit's self promotional guidelines.](https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit)",
-          "distinguish": true,
-          "dryRun": true
-        }
       ]
     }
   ]

docs/examples/subredditReady/selfPromo.yaml

@@ -1,71 +1,72 @@
 polling:
   - unmoderated
-checks:
-    #
-    # Stop users who make link submissions with a self-promotional agenda (with reddit's suggested 10% rule)
-    # https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit
-    #
-    # Remove a SUBMISSION if the link comprises more than or equal to 10% of users history (100 activities or 6 months) OR
-    #
-    # if link comprises 10% of submission history (100 activities or 6 months)
-    # AND less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
-    #
-  - name: Self-promo all AND low engagement
-    description: Self-promo is >10% for all or just sub and low comment engagement
-    kind: submission
-    condition: OR
-    rules:
-      - name: attr
-        kind: attribution
-        criteria:
-          - threshold: '>= 10%'
-            window:
-              count: 100
-              duration: 6 months
-            domains:
-              - 'AGG:SELF'
-      - condition: AND
+runs:
+  - checks:
+      #
+      # Stop users who make link submissions with a self-promotional agenda (with reddit's suggested 10% rule)
+      # https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit
+      #
+      # Remove a SUBMISSION if the link comprises more than or equal to 10% of users history (100 activities or 6 months) OR
+      #
+      # if link comprises 10% of submission history (100 activities or 6 months)
+      # AND less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+      #
+      - name: Self-promo all AND low engagement
+        description: Self-promo is >10% for all or just sub and low comment engagement
+        kind: submission
+        condition: OR
         rules:
-          - name: attrsub
+          - name: attr
             kind: attribution
             criteria:
               - threshold: '>= 10%'
-                thresholdOn: submissions
                 window:
                   count: 100
                   duration: 6 months
                 domains:
                   - 'AGG:SELF'
-          - name: lowOrOpComm
-            kind: history
-            criteriaJoin: OR
-            criteria:
-              - window:
-                  count: 100
-                  duration: 6 months
-                comment: < 50%
-              - window:
-                  count: 100
-                  duration: 6 months
-                comment: '> 40% OP'
-    actions:
-      - kind: report
-        enable: true
-        content: >-
-          {{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}} of
-          {{rules.attr.activityTotal}}{{rules.attrsub.activityTotal}} items
-          ({{rules.attr.window}}{{rules.attrsub.window}}){{#rules.loworopcomm.thresholdSummary}}
-          =>
-          {{rules.loworopcomm.thresholdSummary}}{{/rules.loworopcomm.thresholdSummary}}
-      - kind: remove
-        enable: false
-      - kind: comment
-        enable: true
-        content: >-
-          Your submission has been removed it comprises 10% or more of your
-          recent history
-          ({{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}}). This
-          is against [reddit's self promotional
-          guidelines.](https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit)
-        distinguish: true
-        dryRun: true
+          - condition: AND
+            rules:
+              - name: attrsub
+                kind: attribution
+                criteria:
+                  - threshold: '>= 10%'
+                    thresholdOn: submissions
+                    window:
+                      count: 100
+                      duration: 6 months
+                    domains:
+                      - 'AGG:SELF'
+              - name: lowOrOpComm
+                kind: history
+                criteriaJoin: OR
+                criteria:
+                  - window:
+                      count: 100
+                      duration: 6 months
+                    comment: < 50%
+                  - window:
+                      count: 100
+                      duration: 6 months
+                    comment: '> 40% OP'
+        actions:
+          - kind: report
+            enable: true
+            content: >-
+              {{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}} of
+              {{rules.attr.activityTotal}}{{rules.attrsub.activityTotal}} items
+              ({{rules.attr.window}}{{rules.attrsub.window}}){{#rules.loworopcomm.thresholdSummary}}
+              =>
+              {{rules.loworopcomm.thresholdSummary}}{{/rules.loworopcomm.thresholdSummary}}
+          - kind: remove
+            enable: false
+          - kind: comment
+            enable: true
+            content: >-
+              Your submission has been removed it comprises 10% or more of your
+              recent history
+              ({{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}}). This
+              is against [reddit's self promotional
+              guidelines.](https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit)
+            distinguish: true
+            dryRun: true

docs/examples/userNotes/usernoteFilter.json5

@@ -1,43 +1,47 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Self Promo Activities",
-      "description": "Tag SP only if user does not have good contributor user note",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "attr10all",
-          "kind": "attribution",
-          "author": {
-            "exclude": [
-              {
-                // the key of the usernote type to look for https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
-                // rule will not run if current usernote on Author is of type 'gooduser'
-                "type": "gooduser"
-              }
-            ]
-          },
-          "criteria": [
+          "name": "Self Promo Activities",
+          "description": "Tag SP only if user does not have good contributor user note",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              "threshold": "> 10%",
-              "window": "90 days"
-            },
-            {
-              "threshold": "> 10%",
-              "window": 100
+              "name": "attr10all",
+              "kind": "attribution",
+              "author": {
+                "exclude": [
+                  {
+                    // the key of the usernote type to look for https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+                    // rule will not run if current usernote on Author is of type 'gooduser'
+                    "type": "gooduser"
+                  }
+                ]
+              },
+              "criteria": [
+                {
+                  "threshold": "> 10%",
+                  "window": "90 days"
+                },
+                {
+                  "threshold": "> 10%",
+                  "window": 100
+                }
+              ],
             }
           ],
-        }
-      ],
-      "actions": [
-        {
-          "kind": "usernote",
-          // the key of usernote type
-          // https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
-          "type": "spamwarn",
-          // content is mustache templated as usual
-          "content": "Self Promotion: {{rules.attr10all.titlesDelim}} {{rules.attr10sub.largestPercent}}%"
+          "actions": [
+            {
+              "kind": "usernote",
+              // the key of usernote type
+              // https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+              "type": "spamwarn",
+              // content is mustache templated as usual
+              "content": "Self Promotion: {{rules.attr10all.titlesDelim}} {{rules.attr10sub.largestPercent}}%"
+            }
+          ]
         }
       ]
     }

docs/examples/userNotes/usernoteFilter.yaml

@@ -1,27 +1,28 @@
-checks:
-  - name: Self Promo Activities
-    description: Tag SP only if user does not have good contributor user note
-    # check will run on a new submission in your subreddit and look at the Author of that submission
-    kind: submission
-    rules:
-      - name: attr10all
-        kind: attribution
-        author:
-          exclude:
-              # the key of the usernote type to look for https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
-              # rule will not run if current usernote on Author is of type 'gooduser'
-            - type: gooduser
-        criteria:
-          - threshold: '> 10%'
-            window: 90 days
-          - threshold: '> 10%'
-            window: 100
-    actions:
-      - kind: usernote
-        # the key of usernote type
-        # https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
-        type: spamwarn
-        # content is mustache templated
-        content: >-
-          Self Promotion: {{rules.attr10all.titlesDelim}}
-          {{rules.attr10sub.largestPercent}}%
+runs:
+  - checks:
+      - name: Self Promo Activities
+        description: Tag SP only if user does not have good contributor user note
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: attr10all
+            kind: attribution
+            author:
+              exclude:
+                # the key of the usernote type to look for https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+                # rule will not run if current usernote on Author is of type 'gooduser'
+                - type: gooduser
+            criteria:
+              - threshold: '> 10%'
+                window: 90 days
+              - threshold: '> 10%'
+                window: 100
+        actions:
+          - kind: usernote
+            # the key of usernote type
+            # https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+            type: spamwarn
+            # content is mustache templated
+            content: >-
+              Self Promotion: {{rules.attr10all.titlesDelim}}
+              {{rules.attr10sub.largestPercent}}%

docs/examples/userNotes/usernoteSP.json5

@@ -1,34 +1,38 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Self Promo Activities",
-      "description": "Check if any of Author's aggregated submission origins are >10% of entire history",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "attr10all",
-          "kind": "attribution",
-          "criteria": [
+          "name": "Self Promo Activities",
+          "description": "Check if any of Author's aggregated submission origins are >10% of entire history",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              "threshold": "> 10%",
-              "window": "90 days"
-            },
-            {
-              "threshold": "> 10%",
-              "window": 100
+              "name": "attr10all",
+              "kind": "attribution",
+              "criteria": [
+                {
+                  "threshold": "> 10%",
+                  "window": "90 days"
+                },
+                {
+                  "threshold": "> 10%",
+                  "window": 100
+                }
+              ],
             }
           ],
-        }
-      ],
-      "actions": [
-        {
-          "kind": "usernote",
-          // the key of usernote type
-          // https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
-          "type": "spamwarn",
-          // content is mustache templated as usual
-          "content": "Self Promotion: {{rules.attr10all.titlesDelim}} {{rules.attr10sub.largestPercent}}%"
+          "actions": [
+            {
+              "kind": "usernote",
+              // the key of usernote type
+              // https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+              "type": "spamwarn",
+              // content is mustache templated as usual
+              "content": "Self Promotion: {{rules.attr10all.titlesDelim}} {{rules.attr10sub.largestPercent}}%"
+            }
+          ]
         }
       ]
     }

docs/examples/userNotes/usernoteSP.yaml

@@ -1,23 +1,24 @@
-checks:
-  - name: Self Promo Activities
-    # check will run on a new submission in your subreddit and look at the Author of that submission
-    description: >-
-      Check if any of Author's aggregated submission origins are >10% of entire
-      history
-    kind: submission
-    rules:
-      - name: attr10all
-        kind: attribution
-        criteria:
-          - threshold: '> 10%'
-            window: 90 days
-          - threshold: '> 10%'
-            window: 100
-    actions:
-      - kind: usernote
-        # the key of usernote type
-        # https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
-        type: spamwarn
-        content: >-
-          Self Promotion: {{rules.attr10all.titlesDelim}}
-          {{rules.attr10sub.largestPercent}}%
+runs:
+  - checks:
+      - name: Self Promo Activities
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        description: >-
+          Check if any of Author's aggregated submission origins are >10% of entire
+          history
+        kind: submission
+        rules:
+          - name: attr10all
+            kind: attribution
+            criteria:
+              - threshold: '> 10%'
+                window: 90 days
+              - threshold: '> 10%'
+                window: 100
+        actions:
+          - kind: usernote
+            # the key of usernote type
+            # https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+            type: spamwarn
+            content: >-
+              Self Promotion: {{rules.attr10all.titlesDelim}}
+              {{rules.attr10sub.largestPercent}}%

docs/gettingStartedMod.md

@@ -81,7 +81,7 @@ The default location for this page is at `https://old.reddit.com/r/YOURSUBERDDIT
 
 The bot automatically tries to create its configuration wiki page. You can find the result of this in the log for your subreddit in the web interface.
 
-If this fails for some reason you can create the wiki page through the web interface by navigating to your subreddit's tab, opening the [built-in editor (click **View**)](/docs/screenshots/configBox.png), and following the directions in **Create configuration for...** link found there.
+If this fails for some reason you can create the wiki page through the web interface by navigating to your subreddit's tab, opening the [built-in editor (click **View**)](/docs/images/configBox.png), and following the directions in **Create configuration for...** link found there.
 
 If neither of the above approaches work, or you do not wish to use the web interface, expand the section below for directions on how to manually setup the wiki page:
 
@@ -134,7 +134,7 @@ PROTIP: Find an [example config](#using-an-example-config) to use as a starting
 In the web interface each subreddit's tab has access to the built-in editor. Use this built-in editor to automatically create, load, or save the configuration for that subreddit's wiki.
 
 * Visit the tab for the subreddit you want to edit the configuration of
-* Open the [built-in editor by click **View**](/docs/screenshots/configBox.png)
+* Open the [built-in editor by click **View**](/docs/images/configBox.png)
 * Edit your configuration
 * Follow the directions on the **Save to r/..** link found at the top of the editor to automatically save your configuration
 

docs/gettingStartedOperator.md

@@ -22,13 +22,14 @@ PROTIP: Using a container management tool like [Portainer.io CE](https://www.por
 
 ### [Dockerhub](https://hub.docker.com/r/foxxmd/context-mod)
 
-```
-foxxmd/context-mod:latest
-```
+An example of starting the container using the [minimum configuration](/docs/operatorConfiguration.md#minimum-config) with a [configuration file](/docs/operatorConfiguration.md#defining-configuration-via-file):
+
+* Bind the folder where the config is located on your host machine into the container `-v /host/path/folder:/config`
+* Tell CM where to find the config using an env `-e "OPERATOR_CONFIG=/config/myConfig.yaml"`
+* Expose the web interface using the container port `8085`
 
-Adding **environmental variables** to your `docker run` command will pass them through to the app EX:
 ```
-docker run -d -e "CLIENT_ID=myId" ... foxxmd/context-mod
+docker run -d -e "OPERATOR_CONFIG=/config/myConfig.yaml" -v /host/path/folder:/config -p 8085:8085 foxxmd/context-mod
 ```
 
 ### Locally
@@ -47,6 +48,12 @@ npm install
 tsc -p .
 ```
 
+An example of running CM using the [minimum configuration](/docs/operatorConfiguration.md#minimum-config) with a [configuration file](/docs/operatorConfiguration.md#defining-configuration-via-file):
+
+```bash
+node src/index.js run
+```
+
 ### [Heroku Quick Deploy](https://heroku.com/about)
 [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://dashboard.heroku.com/new?template=https://github.com/FoxxMD/context-mod)
 

docs/operatorConfiguration.md

@@ -41,8 +41,10 @@ configuration.
 **Note:** When reading the **schema** if the variable is available at a level of configuration other than **FILE** it will be
 noted with the same symbol as above. The value shown is the default.
 
-* To load a JSON configuration (for **FILE**) **from the command line** use the `-c` cli argument EX: `node src/index.js -c /path/to/JSON/config.json`
-* To load a JSON configuration (for **FILE**) **using an environmental variable** use `OPERATOR_CONFIG` EX: `OPERATOR_CONFIG=/path/to/JSON/config.json`
+## Defining Configuration Via File
+
+* **from the command line**  use the `-c` cli argument EX: `node src/index.js -c /path/to/JSON/config.json`
+* **using an environmental variable**  use `OPERATOR_CONFIG` EX: `OPERATOR_CONFIG=/path/to/JSON/config.json`
 
 [**See the Operator Config Schema here**](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FOperatorConfig.json)
 
@@ -121,28 +123,41 @@ Below are examples of the minimum required config to run the application using a
 Using **FILE**
 <details>
 
+CM will look for a file configuration at `PROJECT_DIR/config.yaml` by default [or you can specify your own location.](#defining-configuration-via-file)
+
 YAML
 ```yaml
+operator:
+  name: YourRedditUsername
 bots:
   - credentials:
       clientId: f4b4df1c7b2
       clientSecret: 34v5q1c56ub
-      refreshToken: 34_f1w1v4
-      accessToken: p75_1c467b2
+web:
+  credentials:
+    clientId: f4b4df1c7b2
+    clientSecret: 34v5q1c56ub
 ```
 JSON
 ```json5
 {
+  "operator": {
+    "name": "YourRedditUsername"
+  },
   "bots": [
     {
       "credentials": {
         "clientId": "f4b4df1c7b2",
-        "clientSecret": "34v5q1c56ub",
-        "refreshToken": "34_f1w1v4",
-        "accessToken": "p75_1c467b2"
+        "clientSecret": "34v5q1c56ub"
       }
     }
-  ]
+  ],
+  "web": {
+    "credentials": {
+      "clientId": "f4b4df1c7b2",
+      "clientSecret": "34v5q1c56ub"
+    }
+  }
 }
 ```
 
@@ -153,10 +168,9 @@ Using **ENV** (`.env`)
 <details>
 
 ```
+OPERATOR=YourRedditUsername
 CLIENT_ID=f4b4df1c7b2
 CLIENT_SECRET=34v5q1c56ub
-REFRESH_TOKEN=34_f1w1v4
-ACCESS_TOKEN=p75_1c467b2
 ```
 
 </details>

docs/webInterface.md

@@ -0,0 +1,30 @@
+## Editing/Updating Your Config
+
+* Open the editor for your subreddit
+    * In the web dashboard \-> r/YourSubreddit \-> Config -> **View** [(here)](/docs/images/config/config.jpg)
+* Follow the directions on the [link at the top of the window](/docs/images/config/save.png) to enable config editing using your moderator account
+    * After enabling editing just click "save" at any time to save your config
+    * After you have added/edited your config the bot will detect changes within 5 minutes or you can manually trigger it by clicking **Update**
+
+## General Config (Editor) Tips
+
+* The editor will automatically validate your [syntax (formatting)](/docs/images/config/syntax.png) and [config correctness](/docs/images/config/correctness.png) (property names, required properties, etc.)
+    * These show up as squiggly lines like in Microsoft Word and as a [list at the bottom of the editor](/docs/images/config/errors.png)
+* In your config all **Checks** and **Actions** have two properties that control how they behave:
+    * [**Enable**](/docs/images/config/enable.png) (defaults to `enable: true`) -- Determines if the check or action is run, at all
+    * **Dryrun** (defaults to `dryRun: false`) -- When `true` the check or action will run but any **Actions** that may be triggered will "pretend" to execute but not actually talk to the Reddit API.
+      * Use `dryRun` to test your config without the bot making any changes on reddit
+    * When starting out with a new config it is recommended running the bot with remove/ban actions **disabled**
+        * Use `report` actions to get reports in your modqueue from the bot that describe what it detected and what it would do about it
+        * Once the bot is behaving as desired (no false positives or weird behavior) destructive actions can be enabled or turned off of dryrun
+
+## Web Dashboard Tips
+
+* Use the [**Overview** section](/docs/images/botOperations.png) to control the bot at a high-level
+* You can **manually run** the bot on any activity (comment/submission) by pasting its permalink into the [input field below the Overview section](/docs/images/runInput.png) and hitting one of the **run buttons**
+    * **Dry run** will make the bot run on the activity but it will only **pretend** to run actions, if triggered. This is super useful for testing your config without consequences
+    * **Run** will do everything
+* All of the bot's activity is shown in real-time in the [log section](/docs/images/logs.png)
+    * This will output the results of all run checks/rules and any actions that run
+* You can view summaries of all activities that triggered a check (had actions run) by clicking on [Actioned Events](/docs/images/actionsEvents.png)
+    * This includes activities run with dry run

package.json

@@ -49,6 +49,7 @@
     "express-socket.io-session": "^1.3.5",
     "fast-deep-equal": "^3.1.3",
     "fuse.js": "^6.4.6",
+    "globrex": "^0.1.2",
     "got": "^11.8.2",
     "he": "^1.2.0",
     "http-proxy": "^1.18.1",
@@ -58,6 +59,7 @@
     "leven": "^3.1.0",
     "lodash": "^4.17.21",
     "lru-cache": "^6.0.0",
+    "migrate": "github:johsunds/node-migrate#49b0054de0a9295857aa8b8eea9a3cdeb2643913",
     "mustache": "^4.2.0",
     "node-fetch": "^2.6.1",
     "normalize-url": "^6.1.0",
@@ -68,6 +70,7 @@
     "passport-custom": "^1.1.1",
     "passport-jwt": "^4.0.0",
     "pixelmatch": "^5.2.1",
+    "pony-cause": "^1.1.1",
     "pretty-print-json": "^1.0.3",
     "safe-stable-stringify": "^1.1.1",
     "snoostorm": "^1.5.2",
@@ -94,6 +97,7 @@
     "@types/express": "^4.17.13",
     "@types/express-session": "^1.17.4",
     "@types/express-socket.io-session": "^1.3.6",
+    "@types/globrex": "^0.1.1",
     "@types/he": "^1.1.1",
     "@types/http-proxy": "^1.17.7",
     "@types/js-yaml": "^4.0.1",
@@ -114,7 +118,7 @@
     "@types/triple-beam": "^1.3.2",
     "ts-essentials": "^9.1.2",
     "ts-json-schema-generator": "^0.93.0",
-    "typescript-json-schema": "^0.50.1"
+    "typescript-json-schema": "~0.53"
   },
   "optionalDependencies": {
     "sharp": "^0.29.1"

src/Action/ApproveAction.ts

@@ -36,7 +36,7 @@ export class ApproveAction extends Action {
             }
 
             // @ts-ignore
-            if (item.approved) {
+            if (targetItem.approved) {
                 const msg = `${target === 'self' ? 'Item' : 'Comment\'s parent Submission'} is already approved`;
                 this.logger.warn(msg);
                 return {
@@ -54,6 +54,16 @@ export class ApproveAction extends Action {
                 }
                 // @ts-ignore
                 touchedEntities.push(await targetItem.approve());
+
+                if(target === 'self') {
+                    // @ts-ignore
+                    item.approved = true;
+                    await this.resources.resetCacheForItem(item);
+                } else if(await this.resources.hasActivity(targetItem)) {
+                    // @ts-ignore
+                    targetItem.approved = true;
+                    await this.resources.resetCacheForItem(targetItem);
+                }
             }
         }
 

src/Action/CommentAction.ts

@@ -52,6 +52,7 @@ export class CommentAction extends Action {
             };
         }
         const touchedEntities = [];
+        let modifiers = [];
         let reply: Comment;
         if(!dryRun) {
             // @ts-ignore
@@ -59,29 +60,29 @@ export class CommentAction extends Action {
            touchedEntities.push(reply);
         }
         if (this.lock) {
+            modifiers.push('Locked');
             if (!dryRun) {
                 // snoopwrap typing issue, thinks comments can't be locked
                 // @ts-ignore
-                await item.lock();
-                touchedEntities.push(item);
+                await reply.lock();
             }
         }
         if (this.distinguish && !dryRun) {
-            // @ts-ignore
-            await reply.distinguish({sticky: this.sticky});
-        }
-        let modifiers = [];
-        if(this.distinguish) {
             modifiers.push('Distinguished');
+            if(this.sticky) {
+                modifiers.push('Stickied');
+            }
+            if(!dryRun) {
+                // @ts-ignore
+                await reply.distinguish({sticky: this.sticky});
+            }
         }
-        if(this.sticky) {
-            modifiers.push('Stickied');
-        }
+
         const modifierStr = modifiers.length === 0 ? '' : `[${modifiers.join(' | ')}]`;
         return {
             dryRun,
             success: true,
-            result: `${modifierStr}${this.lock ? ' - Locked Author\'s Activity - ' : ''}${truncateStringToLength(100)(body)}`,
+            result: `${modifierStr}${truncateStringToLength(100)(body)}`,
             touchedEntities,
         };
     }

src/Action/LockAction.ts

@@ -26,6 +26,9 @@ export class LockAction extends Action {
             //snoowrap typing issue, thinks comments can't be locked
             // @ts-ignore
             await item.lock();
+            // @ts-ignore
+            item.locked = true;
+            await this.resources.resetCacheForItem(item);
             touchedEntities.push(item);
         }
         return {

src/Action/MessageAction.ts

@@ -12,7 +12,8 @@ import {
     REDDIT_ENTITY_REGEX_URL,
     truncateStringToLength
 } from "../util";
-import SimpleError from "../Utils/SimpleError";
+import {SimpleError} from "../Utils/Errors";
+import {ErrorWithCause} from "pony-cause";
 
 export class MessageAction extends Action {
     content: string;
@@ -65,10 +66,7 @@ export class MessageAction extends Action {
                     recipient = `/r/${entityData.name}`;
                 }
             } catch (err: any) {
-                this.logger.error(`'to' field for message was not in a valid format. See ${REDDIT_ENTITY_REGEX_URL} for valid examples`);
-                this.logger.error(err);
-                err.logged = true;
-                throw err;
+                throw new ErrorWithCause(`'to' field for message was not in a valid format. See ${REDDIT_ENTITY_REGEX_URL} for valid examples`, {cause: err});
             }
             if(recipient.includes('/r/') && this.asSubreddit) {
                 throw new SimpleError(`Cannot send a message as a subreddit to another subreddit. Requested recipient: ${recipient}`);

src/Action/RemoveAction.ts

@@ -1,30 +1,48 @@
-import {ActionJson, ActionConfig} from "./index";
+import {ActionJson, ActionConfig, ActionOptions} from "./index";
 import Action from "./index";
 import Snoowrap, {Comment, Submission} from "snoowrap";
 import {RuleResult} from "../Rule";
 import {activityIsRemoved} from "../Utils/SnoowrapUtils";
 import {ActionProcessResult} from "../Common/interfaces";
+import dayjs from "dayjs";
+import {isSubmission} from "../util";
 
 export class RemoveAction extends Action {
+    spam: boolean;
+
     getKind() {
         return 'Remove';
     }
 
+    constructor(options: RemoveOptions) {
+        super(options);
+        const {
+            spam = false,
+        } = options;
+        this.spam = spam;
+    }
+
     async process(item: Comment | Submission, ruleResults: RuleResult[], runtimeDryrun?: boolean): Promise<ActionProcessResult> {
         const dryRun = runtimeDryrun || this.dryRun;
         const touchedEntities = [];
         // issue with snoowrap typings, doesn't think prop exists on Submission
         // @ts-ignore
         if (activityIsRemoved(item)) {
-            return {
-                dryRun,
-                success: false,
-                result: 'Item is already removed',
-            }
+            this.logger.warn('It looks like this Item is already removed!');
+        }
+        if (this.spam) {
+            this.logger.verbose('Marking as spam on removal');
         }
         if (!dryRun) {
             // @ts-ignore
-            await item.remove();
+            await item.remove({spam: this.spam});
+            item.banned_at_utc = dayjs().unix();
+            item.spam = this.spam;
+            if(!isSubmission(item)) {
+                // @ts-ignore
+                item.removed = true;
+            }
+            await this.resources.resetCacheForItem(item);
             touchedEntities.push(item);
         }
 
@@ -36,13 +54,16 @@ export class RemoveAction extends Action {
     }
 }
 
-export interface RemoveActionConfig extends ActionConfig {
+export interface RemoveOptions extends RemoveActionConfig, ActionOptions {
+}
 
+export interface RemoveActionConfig extends ActionConfig {
+    spam?: boolean
 }
 
 /**
  * Remove the Activity
  * */
 export interface RemoveActionJson extends RemoveActionConfig, ActionJson {
-kind: 'remove'
+    kind: 'remove'
 }

src/Action/ReportAction.ts

@@ -35,6 +35,7 @@ export class ReportAction extends Action {
             await item.report({reason: truncatedContent});
             // due to reddit not updating this in response (maybe)?? just increment stale activity
             item.num_reports++;
+            await this.resources.resetCacheForItem(item);
             touchedEntities.push(item);
         }
 

src/Action/SubmissionAction/FlairAction.ts

@@ -33,16 +33,26 @@ export class FlairAction extends Action {
         if(this.css !== '') {
             flairParts.push(`CSS: ${this.css}`);
         }
+        if(this.flair_template_id !== '') {
+            flairParts.push(`Template: ${this.flair_template_id}`);
+        }
         const flairSummary = flairParts.length === 0 ? 'No flair (unflaired)' : flairParts.join(' | ');
         this.logger.verbose(flairSummary);
         if (item instanceof Submission) {
             if(!this.dryRun) {
                 if (this.flair_template_id) {
-                    await item.selectFlair({flair_template_id: this.flair_template_id}).then(() => {});
+                    // typings are wrong for this function, flair_template_id should be accepted
+                    // assignFlair uses /api/flair (mod endpoint)
+                    // selectFlair uses /api/selectflair (self endpoint for user to choose their own flair for submission)
+                    // @ts-ignore
+                    await item.assignFlair({flair_template_id: this.flair_template_id}).then(() => {});
+                    item.link_flair_template_id = this.flair_template_id;
                 } else {
                     await item.assignFlair({text: this.text, cssClass: this.css}).then(() => {});
+                    item.link_flair_css_class = this.css;
+                    item.link_flair_text = this.text;
                 }
-
+                await this.resources.resetCacheForItem(item);
             }
         } else {
             this.logger.warn('Cannot flair Comment');

src/Action/UserFlairAction.ts

@@ -41,7 +41,7 @@ export class UserFlairAction extends Action {
     const flairSummary = flairParts.length === 0 ? 'Unflair user' : flairParts.join(' | ');
     this.logger.verbose(flairSummary);
 
-    if (!this.dryRun) {
+    if (!dryRun) {
       if (this.flair_template_id !== undefined) {
         try {
           // @ts-ignore
@@ -50,6 +50,7 @@ export class UserFlairAction extends Action {
             flairTemplateId: this.flair_template_id,
             username: item.author.name,
           });
+          item.author_flair_template_id = this.flair_template_id
         } catch (err: any) {
           this.logger.error('Either the flair template ID is incorrect or you do not have permission to access it.');
           throw err;
@@ -57,6 +58,9 @@ export class UserFlairAction extends Action {
       } else if (this.text === undefined && this.css === undefined) {
         // @ts-ignore
         await item.subreddit.deleteUserFlair(item.author.name);
+        item.author_flair_css_class = null;
+        item.author_flair_text = null;
+        item.author_flair_template_id = null;
       } else {
         // @ts-ignore
         await item.author.assignFlair({
@@ -64,6 +68,12 @@ export class UserFlairAction extends Action {
           cssClass: this.css,
           text: this.text,
         });
+        item.author_flair_text = this.text ?? null;
+        item.author_flair_css_class = this.css ?? null;
+      }
+      await this.resources.resetCacheForItem(item);
+      if(typeof item.author !== 'string') {
+          await this.resources.resetCacheForItem(item.author);
       }
     }
 

src/Action/UserNoteAction.ts

@@ -33,8 +33,15 @@ export class UserNoteAction extends Action {
 
         if (!this.allowDuplicate) {
             const notes = await this.resources.userNotes.getUserNotes(item.author);
-            const existingNote = notes.find((x) => x.link.includes(item.id));
-            if (existingNote) {
+            let existingNote = notes.find((x) => x.link !== null && x.link.includes(item.id));
+            if(existingNote === undefined && notes.length > 0) {
+                const lastNote = notes[notes.length - 1];
+                // possibly notes don't have a reference link so check if last one has same text
+                if(lastNote.link === null && lastNote.text === renderedContent) {
+                    existingNote = lastNote;
+                }
+            }
+            if (existingNote !== undefined && existingNote.noteType === this.type) {
                 this.logger.info(`Will not add note because one already exists for this Activity (${existingNote.time.local().format()}) and allowDuplicate=false`);
                 return {
                     dryRun,

src/Action/index.ts

@@ -1,12 +1,13 @@
 import {Comment, Submission} from "snoowrap";
 import {Logger} from "winston";
 import {RuleResult} from "../Rule";
-import {checkAuthorFilter, SubredditResources} from "../Subreddit/SubredditResources";
+import {checkAuthorFilter, checkItemFilter, SubredditResources} from "../Subreddit/SubredditResources";
 import {ActionProcessResult, ActionResult, ChecksActivityState, TypedActivityStates} from "../Common/interfaces";
 import Author, {AuthorOptions} from "../Author/Author";
 import {mergeArr} from "../util";
 import LoggedError from "../Utils/LoggedError";
 import {ExtendedSnoowrap} from '../Utils/SnoowrapClients';
+import {ErrorWithCause} from "pony-cause";
 
 export abstract class Action {
     name?: string;
@@ -68,17 +69,24 @@ export abstract class Action {
             success: false,
         };
         try {
-            const itemPass = await this.resources.testItemCriteria(item, this.itemIs);
+            const [itemPass, itemFilterType, itemFilterResults] = await checkItemFilter(item, this.itemIs, this.resources, this.logger);
             if (!itemPass) {
                 this.logger.verbose(`Activity did not pass 'itemIs' test, Action not run`);
                 actRes.runReason = `Activity did not pass 'itemIs' test, Action not run`;
+                actRes.itemIs = itemFilterResults;
                 return actRes;
+            } else if(this.itemIs.length > 0) {
+                actRes.itemIs = itemFilterResults;
             }
-            const [authFilterResult, authFilterType] = await checkAuthorFilter(item, this.authorIs, this.resources, this.logger);
-            if(!authFilterResult) {
+
+            const [authPass, authFilterType, authorFilterResult] = await checkAuthorFilter(item, this.authorIs, this.resources, this.logger);
+            if(!authPass) {
                 this.logger.verbose(`${authFilterType} author criteria not matched, Action not run`);
                 actRes.runReason = `${authFilterType} author criteria not matched`;
+                actRes.authorIs = authorFilterResult;
                 return actRes;
+            } else if(authFilterType !== undefined) {
+                actRes.authorIs = authorFilterResult;
             }
 
             actRes.run = true;
@@ -86,7 +94,8 @@ export abstract class Action {
             return {...actRes, ...results};
         } catch (err: any) {
             if(!(err instanceof LoggedError)) {
-                this.logger.error(`Encountered error while running`, err);
+                const actionError = new ErrorWithCause('Action did not run successfully due to unexpected error', {cause: err});
+                this.logger.error(actionError);
             }
             actRes.success = false;
             actRes.result = err.message;

src/Bot/index.ts

@@ -6,7 +6,7 @@ import EventEmitter from "events";
 import {
     BotInstanceConfig,
     FilterCriteriaDefaults,
-    Invokee,
+    Invokee, LogInfo,
     PAUSED,
     PollOn,
     RUNNING,
@@ -15,11 +15,11 @@ import {
     USER
 } from "../Common/interfaces";
 import {
-    createRetryHandler,
-    formatNumber,
+    createRetryHandler, difference,
+    formatNumber, getExceptionMessage, getUserAgent,
     mergeArr,
     parseBool,
-    parseDuration,
+    parseDuration, parseMatchMessage, parseRedditEntity,
     parseSubredditName, RetryOptions,
     sleep,
     snooLogWrapper
@@ -30,14 +30,15 @@ import {CommentStream, ModQueueStream, SPoll, SubmissionStream, UnmoderatedStrea
 import {BotResourcesManager} from "../Subreddit/SubredditResources";
 import LoggedError from "../Utils/LoggedError";
 import pEvent from "p-event";
-import SimpleError from "../Utils/SimpleError";
-import {isRateLimitError, isStatusError} from "../Utils/Errors";
+import {SimpleError, isRateLimitError, isRequestError, isScopeError, isStatusError, CMError} from "../Utils/Errors";
+import {ErrorWithCause} from "pony-cause";
 
 
 class Bot {
 
     client!: ExtendedSnoowrap;
     logger!: Logger;
+    logs: LogInfo[] = [];
     wikiLocation: string;
     dryRun?: true | undefined;
     running: boolean = false;
@@ -78,6 +79,8 @@ class Bot {
 
     cacheManager: BotResourcesManager;
 
+    config: BotInstanceConfig;
+
     getBotName = () => {
         return this.botName;
     }
@@ -98,6 +101,7 @@ class Bot {
                 dryRun,
                 heartbeatInterval,
             },
+            userAgent,
             credentials: {
                 reddit: {
                     clientId,
@@ -129,8 +133,7 @@ class Bot {
             }
         } = config;
 
-        this.cacheManager = new BotResourcesManager(config);
-
+        this.config = config;
         this.dryRun = parseBool(dryRun) === true ? true : undefined;
         this.softLimit = softLimit;
         this.hardLimit = hardLimit;
@@ -151,6 +154,14 @@ class Bot {
             }
         }, mergeArr);
 
+        this.logger.stream().on('log', (log: LogInfo) => {
+            if(log.bot !== undefined && log.bot === this.getBotName() && log.subreddit === undefined) {
+                this.logs = [log, ...this.logs].slice(0, 301);
+            }
+        });
+
+        this.cacheManager = new BotResourcesManager(config, this.logger);
+
         let mw = maxWorkers;
         if(maxWorkers < 1) {
             this.logger.warn(`Max queue workers must be greater than or equal to 1 (Specified: ${maxWorkers})`);
@@ -166,7 +177,9 @@ class Bot {
         this.excludeSubreddits = exclude.map(parseSubredditName);
 
         let creds: any = {
-            get userAgent() { return getUserName() },
+            get userAgent() {
+                return getUserAgent(`web:contextBot:{VERSION}{FRAG}:BOT-${getBotName()}`, userAgent)
+            },
             clientId,
             clientSecret,
             refreshToken,
@@ -234,10 +247,9 @@ class Bot {
     }
 
     createSharedStreamErrorListener = (name: string) => async (err: any) => {
-        this.logger.error(`Polling error occurred on stream ${name.toUpperCase()}`, err);
         const shouldRetry = await this.sharedStreamRetryHandler(err);
         if(shouldRetry) {
-            (this.cacheManager.modStreams.get(name) as SPoll<any>).startInterval(false);
+            (this.cacheManager.modStreams.get(name) as SPoll<any>).startInterval(false, 'Within retry limits');
         } else {
             for(const m of this.subManagers) {
                 if(m.sharedStreamCallbacks.size > 0) {
@@ -255,7 +267,7 @@ class Bot {
             return;
         }
         for(const i of listing) {
-            const foundManager = this.subManagers.find(x => x.subreddit.display_name === i.subreddit.display_name && x.sharedStreamCallbacks.get(name) !== undefined);
+            const foundManager = this.subManagers.find(x => x.subreddit.display_name === i.subreddit.display_name && x.sharedStreamCallbacks.get(name) !== undefined && x.eventsState.state === RUNNING);
             if(foundManager !== undefined) {
                 foundManager.sharedStreamCallbacks.get(name)(i);
                 if(this.stagger !== undefined) {
@@ -280,22 +292,16 @@ class Bot {
             if (initial) {
                 this.logger.error('An error occurred while trying to initialize the Reddit API Client which would prevent the entire application from running.');
             }
-            if (err.name === 'StatusCodeError') {
-                const authHeader = err.response.headers['www-authenticate'];
-                if (authHeader !== undefined && authHeader.includes('insufficient_scope')) {
-                    this.logger.error('Reddit responded with a 403 insufficient_scope. Please ensure you have chosen the correct scopes when authorizing your account.');
-                } else if (err.statusCode === 401) {
-                    this.logger.error('It is likely a credential is missing or incorrect. Check clientId, clientSecret, refreshToken, and accessToken');
-                } else if(err.statusCode === 400) {
-                    this.logger.error('Credentials may have been invalidated due to prior behavior. The error message may contain more information.');
-                }
-                this.logger.error(`Error Message: ${err.message}`);
-            } else {
-                this.logger.error(err);
-            }
-            this.error = `Error occurred while testing Reddit API client: ${err.message}`;
-            err.logged = true;
-            throw err;
+            const hint = getExceptionMessage(err, {
+                401: 'Likely a credential is missing or incorrect. Check clientId, clientSecret, refreshToken, and accessToken',
+                400: 'Credentials may have been invalidated manually or by reddit due to behavior',
+            });
+            let msg = `Error occurred while testing Reddit API client${hint !== undefined ? `: ${hint}` : ''}`;
+            this.error = msg;
+            const clientError = new CMError(msg, {cause: err});
+            clientError.logged = true;
+            this.logger.error(clientError);
+            throw clientError;
         }
     }
 
@@ -347,6 +353,31 @@ class Bot {
             }
         }
 
+        const {
+            subreddits: {
+                overrides = [],
+            } = {}
+        } = this.config;
+        if(overrides.length > 0) {
+            // check for overrides that don't match subs to run and warn operator
+            const subsToRunNames = subsToRun.map(x => x.display_name.toLowerCase());
+
+            const normalizedOverrideNames = overrides.reduce((acc: string[], curr) => {
+                try {
+                    const ent = parseRedditEntity(curr.name);
+                    return acc.concat(ent.name.toLowerCase());
+                } catch (e) {
+                    this.logger.warn(new ErrorWithCause(`Could not use subreddit override because name was not valid: ${curr.name}`, {cause: e}));
+                    return acc;
+                }
+            }, []);
+            const notMatched = difference(normalizedOverrideNames, subsToRunNames);
+            if(notMatched.length > 0) {
+                this.logger.warn(`There are overrides defined for subreddits the bot is not running. Check your spelling! Overrides not matched: ${notMatched.join(', ')}`);
+            }
+        }
+
+
         // get configs for subs we want to run on and build/validate them
         for (const sub of subsToRun) {
             try {
@@ -375,7 +406,7 @@ class Bot {
                 let processed;
                 if (stream !== undefined) {
                     this.logger.info('Restarting SHARED COMMENT STREAM due to a subreddit config change');
-                    stream.end();
+                    stream.end('Replacing with a new stream with updated subreddits');
                     processed = stream.processed;
                 }
                 if (sharedCommentsSubreddits.length > 100) {
@@ -397,7 +428,7 @@ class Bot {
         } else {
             const stream = this.cacheManager.modStreams.get('newComm');
             if (stream !== undefined) {
-                stream.end();
+                stream.end('Determined no managers are listening on shared stream parsing');
             }
         }
 
@@ -408,7 +439,7 @@ class Bot {
                 let processed;
                 if (stream !== undefined) {
                     this.logger.info('Restarting SHARED SUBMISSION STREAM due to a subreddit config change');
-                    stream.end();
+                    stream.end('Replacing with a new stream with updated subreddits');
                     processed = stream.processed;
                 }
                 if (sharedSubmissionsSubreddits.length > 100) {
@@ -430,7 +461,7 @@ class Bot {
         } else {
             const stream = this.cacheManager.modStreams.get('newSub');
             if (stream !== undefined) {
-                stream.end();
+                stream.end('Determined no managers are listening on shared stream parsing');
             }
         }
 
@@ -448,7 +479,7 @@ class Bot {
             defaultUnmoderatedStream.on('listing', this.createSharedStreamListingListener('unmoderated'));
             this.cacheManager.modStreams.set('unmoderated', defaultUnmoderatedStream);
         } else if (!isUnmoderatedShared && unmoderatedstream !== undefined) {
-            unmoderatedstream.end();
+            unmoderatedstream.end('Determined no managers are listening on shared stream parsing');
         }
 
         const isModqueueShared = !this.sharedStreams.includes('modqueue') ? false : this.subManagers.some(x => x.isPollingShared('modqueue'));
@@ -465,7 +496,7 @@ class Bot {
             defaultModqueueStream.on('listing', this.createSharedStreamListingListener('modqueue'));
             this.cacheManager.modStreams.set('modqueue', defaultModqueueStream);
         } else if (isModqueueShared && modqueuestream !== undefined) {
-            modqueuestream.end();
+            modqueuestream.end('Determined no managers are listening on shared stream parsing');
         }
     }
 
@@ -473,15 +504,40 @@ class Bot {
         try {
             await manager.parseConfiguration('system', true, {suppressNotification: true, suppressChangeEvent: true});
         } catch (err: any) {
-            if (!(err instanceof LoggedError)) {
-                this.logger.error(`Config was not valid:`, {subreddit: manager.subreddit.display_name_prefixed});
-                this.logger.error(err, {subreddit: manager.subreddit.display_name_prefixed});
-                err.logged = true;
+            if(err.logged !== true) {
+                const normalizedError = new ErrorWithCause(`Bot could not start manager because config was not valid`, {cause: err});
+                // @ts-ignore
+                this.logger.error(normalizedError, {subreddit: manager.subreddit.display_name_prefixed});
+            } else {
+                this.logger.error('Bot could not start manager because config was not valid', {subreddit: manager.subreddit.display_name_prefixed});
             }
         }
     }
 
     createManager(sub: Subreddit): Manager {
+        const {
+            flowControlDefaults: {
+                maxGotoDepth: botMaxDefault
+            } = {},
+            subreddits: {
+                overrides = [],
+            } = {}
+        } = this.config;
+
+        const override = overrides.find(x => {
+            const configName = parseRedditEntity(x.name).name;
+            if(configName !== undefined) {
+                return configName.toLowerCase() === sub.display_name.toLowerCase();
+            }
+            return false;
+        });
+
+        const {
+            flowControlDefaults: {
+                maxGotoDepth: subMax = undefined,
+            } = {}
+        } = override || {};
+
         const manager = new Manager(sub, this.client, this.logger, this.cacheManager, {
             dryRun: this.dryRun,
             sharedStreams: this.sharedStreams,
@@ -489,6 +545,7 @@ class Bot {
             botName: this.botName as string,
             maxWorkers: this.maxWorkers,
             filterCriteriaDefaults: this.filterCriteriaDefaults,
+            maxGotoDepth: subMax ?? botMaxDefault
         });
         // all errors from managers will count towards bot-level retry count
         manager.on('error', async (err) => await this.panicOnRetries(err));
@@ -666,9 +723,11 @@ class Bot {
                     }
                 }
             } catch (err: any) {
-                this.logger.info('Stopping event polling to prevent activity processing queue from backing up. Will be restarted when config update succeeds.')
-                await s.stopEvents('system', {reason: 'Invalid config will cause events to pile up in queue. Will be restarted when config update succeeds (next heartbeat).'});
-                if(!(err instanceof LoggedError)) {
+                if(s.eventsState.state === RUNNING) {
+                    this.logger.info('Stopping event polling to prevent activity processing queue from backing up. Will be restarted when config update succeeds.')
+                    await s.stopEvents('system', {reason: 'Invalid config will cause events to pile up in queue. Will be restarted when config update succeeds (next heartbeat).'});
+                }
+                if(err.logged !== true) {
                     this.logger.error(err, {subreddit: s.displayLabel});
                 }
                 if(this.nextHeartbeat !== undefined) {
@@ -744,6 +803,10 @@ class Bot {
                     m.notificationManager.handle('runStateChanged', 'Hard Limit Triggered', `Hard Limit of ${this.hardLimit} hit (API Remaining: ${this.client.ratelimitRemaining}). Subreddit event polling has been paused.`, 'system', 'warn');
                 }
 
+                for(const [k,v] of this.cacheManager.modStreams) {
+                    v.end('Hard limit cutoff');
+                }
+
                 this.nannyMode = 'hard';
                 return;
             }
@@ -810,6 +873,7 @@ class Bot {
                         await m.startEvents('system', {reason: 'API Nanny has been turned off due to better API conditions'});
                     }
                 }
+                await this.runSharedStreams(true);
                 this.nannyMode = undefined;
             }
 

src/Check/index.ts

@@ -7,7 +7,7 @@ import {actionFactory} from "../Action/ActionFactory";
 import {ruleFactory} from "../Rule/RuleFactory";
 import {
     boolToString,
-    createAjvFactory,
+    createAjvFactory, determineNewResults,
     FAIL,
     mergeArr,
     PASS,
@@ -16,11 +16,11 @@ import {
     truncateStringToLength
 } from "../util";
 import {
-    ActionResult,
-    ChecksActivityState,
+    ActionResult, ActivityType, CheckResult,
+    ChecksActivityState, CheckSummary,
     CommentState,
     JoinCondition,
-    JoinOperands,
+    JoinOperands, NotificationEventPayload, PostBehavior, PostBehaviorTypes,
     SubmissionState,
     TypedActivityStates, UserResultCache
 } from "../Common/interfaces";
@@ -28,9 +28,14 @@ import * as RuleSchema from '../Schema/Rule.json';
 import * as RuleSetSchema from '../Schema/RuleSet.json';
 import * as ActionSchema from '../Schema/Action.json';
 import {ActionObjectJson, RuleJson, RuleObjectJson, ActionJson as ActionTypeJson} from "../Common/types";
-import {checkAuthorFilter, SubredditResources} from "../Subreddit/SubredditResources";
+import {checkAuthorFilter, checkItemFilter, SubredditResources} from "../Subreddit/SubredditResources";
 import {Author, AuthorCriteria, AuthorOptions} from '..';
 import {ExtendedSnoowrap} from '../Utils/SnoowrapClients';
+import {CheckProcessingError, isRateLimitError} from "../Utils/Errors";
+import {ErrorWithCause, stackWithCauses} from "pony-cause";
+import {runCheckOptions} from "../Subreddit/Manager";
+import EventEmitter from "events";
+import {itemContentPeek} from "../Utils/SnoowrapUtils";
 
 const checkLogName = truncateStringToLength(25);
 
@@ -49,9 +54,13 @@ export abstract class Check implements ICheck {
     notifyOnTrigger: boolean;
     resources: SubredditResources;
     client: ExtendedSnoowrap;
+    postTrigger: PostBehaviorTypes;
+    postFail: PostBehaviorTypes;
+    emitter: EventEmitter;
 
     constructor(options: CheckOptions) {
         const {
+            emitter,
             enable = true,
             name,
             resources,
@@ -63,6 +72,8 @@ export abstract class Check implements ICheck {
             notifyOnTrigger = false,
             subredditName,
             cacheUserResult = {},
+            postTrigger = 'nextRun',
+            postFail = 'next',
             itemIs = [],
             authorIs: {
                 include = [],
@@ -73,6 +84,7 @@ export abstract class Check implements ICheck {
         } = options;
 
         this.enabled = enable;
+        this.emitter = emitter;
 
         this.logger = options.logger.child({labels: [`CHK ${checkLogName(name)}`]}, mergeArr);
 
@@ -91,6 +103,8 @@ export abstract class Check implements ICheck {
             exclude: exclude.map(x => new Author(x)),
             include: include.map(x => new Author(x)),
         }
+        this.postTrigger = postTrigger;
+        this.postFail = postFail;
         this.cacheUserResult = {
             ...userResultCacheDefault,
             ...cacheUserResult
@@ -184,31 +198,192 @@ export abstract class Check implements ICheck {
     async setCacheResult(item: Submission | Comment, result: UserResultCache): Promise<void> {
     }
 
-    async runRules(item: Submission | Comment, existingResults: RuleResult[] = []): Promise<[boolean, RuleResult[], boolean?]> {
+    async handle(activity: (Submission | Comment), allRuleResults: RuleResult[], options: runCheckOptions = {}): Promise<CheckSummary> {
+
+        let checkSum: CheckSummary = {
+            name: this.name,
+            run: this.name,
+            actionResults: [],
+            ruleResults: [],
+            postBehavior: 'next',
+            fromCache: false,
+            triggered: false,
+            condition: this.condition
+        }
+
+        let currentResults: RuleResult[] = [];
+
+        try {
+            if (!this.enabled) {
+                checkSum.error = 'Not enabled';
+                this.logger.info(`Not enabled, skipping...`);
+                return checkSum;
+            }
+            //checksRunNames.push(check.name);
+            //checksRun++;
+            let triggered = false;
+            let runActions: ActionResult[] = [];
+            let checkRes: CheckResult;
+            let checkError: string | undefined;
+            try {
+                checkRes = await this.runRules(activity, allRuleResults);
+
+                checkSum = {
+                    ...checkSum,
+                    ...checkRes,
+                }
+                const {
+                    triggered: checkTriggered,
+                    ruleResults: checkResults,
+                    fromCache = false
+                } = checkRes;
+                //isFromCache = fromCache;
+                if (!fromCache) {
+                    await this.setCacheResult(activity, {result: checkTriggered, ruleResults: checkResults});
+                } else {
+                    checkRes.fromCache = true;
+                    //cachedCheckNames.push(check.name);
+                }
+                currentResults = checkResults;
+                //totalRulesRun += checkResults.length;
+                // allRuleResults = allRuleResults.concat(determineNewResults(allRuleResults, checkResults));
+                if (triggered && fromCache && !this.cacheUserResult.runActions) {
+                    this.logger.info('Check was triggered but cache result options specified NOT to run actions...counting as check NOT triggered');
+                    checkSum.triggered = false;
+                    triggered = false;
+                }
+            } catch (err: any) {
+                checkSum.error = `Running rules failed due to uncaught exception: ${err.message}`;
+                const chkLogError = new ErrorWithCause(`[CHK ${this.name}] Running rules failed due to uncaught exception`, {cause: err});
+                if (err.logged !== true) {
+                    this.logger.warn(chkLogError);
+                }
+                this.emitter.emit('error', chkLogError);
+            }
+
+            let behaviorT: string;
+
+            if (checkSum.triggered) {
+                try {
+                    checkSum.postBehavior = this.postTrigger;
+
+                    checkSum.actionResults = await this.runActions(activity, currentResults.filter(x => x.triggered), options.dryRun);
+                    // we only can about report and comment actions since those can produce items for newComm and modqueue
+                    const recentCandidates = checkSum.actionResults.filter(x => ['report', 'comment'].includes(x.kind.toLocaleLowerCase())).map(x => x.touchedEntities === undefined ? [] : x.touchedEntities).flat();
+                    for (const recent of recentCandidates) {
+                        await this.resources.setRecentSelf(recent as (Submission | Comment));
+                    }
+                    //actionsRun = runActions.length;
+
+                    if (this.notifyOnTrigger) {
+                        const ar = checkSum.actionResults.filter(x => x.success).map(x => x.name).join(', ');
+                        const [peek, _] = await itemContentPeek(activity);
+                        const notifPayload: NotificationEventPayload = {
+                            type: 'eventActioned',
+                            title: 'Check Triggered',
+                            body: `Check "${this.name}" was triggered on Event: \n\n ${peek} \n\n with the following actions run: ${ar}`
+                        }
+                        this.emitter.emit('notify', notifPayload)
+                    }
+                } catch (err: any) {
+                    this.emitter.emit('error', err);
+                    checkSum.error = `Running actions failed due to uncaught exception: ${err.message}`;
+                    if (err.logged !== true) {
+                        const chkLogError = new ErrorWithCause(`[CHK ${this.name}] Running actions failed due to uncaught exception`, {cause: err});
+                        this.logger.warn(chkLogError);
+                    }
+                }
+            } else {
+                checkSum.postBehavior = this.postFail;
+            }
+
+            behaviorT = checkSum.triggered ? 'Trigger' : 'Fail';
+
+            switch (checkSum.postBehavior.toLowerCase()) {
+                case 'next':
+                    this.logger.debug('Behavior => NEXT => Run next check', {leaf: `Post Check ${behaviorT}`});
+                    break;
+                case 'nextrun':
+                    this.logger.debug('Behavior => NEXT RUN => Skip remaining checks and go to next Run', {leaf: `Post Check ${behaviorT}`});
+                    break;
+                case 'stop':
+                    this.logger.debug('Behavior => STOP => Immediately stop current Run and skip all remaining runs', {leaf: `Post Check ${behaviorT}`});
+                    break;
+                default:
+                    if (checkSum.postBehavior.includes('goto:')) {
+                        const gotoContext = checkSum.postBehavior.split(':')[1];
+                        this.logger.debug(`Behavior => GOTO => ${gotoContext}`, {leaf: `Post Check ${behaviorT}`});
+                    } else {
+                        throw new Error(`Post ${behaviorT} Behavior "${checkSum.postBehavior}" was not a valid value. Must be one of => next | nextRun | stop | goto:[path]`);
+                    }
+            }
+            return checkSum;
+        } catch (err: any) {
+            if(checkSum.error === undefined) {
+                checkSum.error = stackWithCauses(err);
+            }
+            throw new CheckProcessingError(`[CHK ${this.name}] An uncaught exception occurred while processing Check`, {cause: err}, checkSum);
+        } finally {
+            this.resources.updateHistoricalStats({
+                checksTriggered: checkSum.triggered ? [checkSum.name] : [],
+                checksRun: [checkSum.name],
+                checksFromCache: checkSum.fromCache ? [checkSum.name] : [],
+                actionsRun: checkSum.actionResults.map(x => x.name),
+                rulesRun: checkSum.ruleResults.map(x => x.name),
+                rulesTriggered: checkSum.ruleResults.filter(x => x.triggered).map(x => x.name),
+                rulesCachedTotal: checkSum.ruleResults.filter(x => x.fromCache).length
+            })
+        }
+    }
+
+    async runRules(item: Submission | Comment, existingResults: RuleResult[] = []): Promise<CheckResult> {
         try {
             let allRuleResults: RuleResult[] = [];
             let allResults: (RuleResult | RuleSetResult)[] = [];
 
+            const checkResult: CheckResult = {
+                triggered: false,
+                ruleResults: [],
+            }
+
             // check cache results
             const cacheResult = await this.getCacheResult(item);
             if(cacheResult !== undefined) {
                 this.logger.verbose(`Skipping rules run because result was found in cache, Check Triggered Result: ${cacheResult}`);
-                return [cacheResult.result, cacheResult.ruleResults, true];
+                return {
+                    triggered: cacheResult.result,
+                    ruleResults: cacheResult.ruleResults,
+                    fromCache: true
+                };
             }
 
-            const itemPass = await this.resources.testItemCriteria(item, this.itemIs);
+            const [itemPass, itemFilterType, itemFilterResults] = await checkItemFilter(item, this.itemIs, this.resources, this.logger);
             if (!itemPass) {
-                this.logger.verbose(`${FAIL} => Item did not pass 'itemIs' test`);
-                return [false, allRuleResults];
+                return {
+                    triggered: false,
+                    ruleResults: allRuleResults,
+                    itemIs: itemFilterResults
+                };
+            } else if(this.itemIs.length > 0) {
+                checkResult.itemIs = itemFilterResults;
             }
-            const [authFilterResult, authFilterType] = await checkAuthorFilter(item, this.authorIs, this.resources, this.logger);
-            if(!authFilterResult) {
-                return Promise.resolve([false, allRuleResults]);
+            const [authPass, authFilterType, authorFilterResults] = await checkAuthorFilter(item, this.authorIs, this.resources, this.logger);
+            if(!authPass) {
+                return {
+                    triggered: false,
+                    ruleResults: allRuleResults,
+                    authorIs: authorFilterResults
+                };
+            } else if(authFilterType !== undefined) {
+                checkResult.authorIs = authorFilterResults;
             }
 
             if (this.rules.length === 0) {
                 this.logger.info(`${PASS} => No rules to run, check auto-passes`);
-                return [true, allRuleResults];
+                return {
+                    triggered: true,
+                    ruleResults: allRuleResults,
+                };
             }
 
             let runOne = false;
@@ -229,28 +404,41 @@ export abstract class Check implements ICheck {
                 if (passed) {
                     if (this.condition === 'OR') {
                         this.logger.info(`${PASS} => Rules: ${resultsSummary(allResults, this.condition)}`);
-                        return [true, allRuleResults];
+                        return {
+                            triggered: true,
+                            ruleResults: allRuleResults,
+                        };
                     }
                 } else if (this.condition === 'AND') {
                     this.logger.verbose(`${FAIL} => Rules: ${resultsSummary(allResults, this.condition)}`);
-                    return [false, allRuleResults];
+                    return {
+                        triggered: false,
+                        ruleResults: allRuleResults,
+                    };
                 }
             }
             if (!runOne) {
                 this.logger.verbose(`${FAIL} => All Rules skipped because of Author checks or itemIs tests`);
-                return [false, allRuleResults];
+                return {
+                    triggered: false,
+                    ruleResults: allRuleResults,
+                };
             } else if (this.condition === 'OR') {
                 // if OR and did not return already then none passed
                 this.logger.verbose(`${FAIL} => Rules: ${resultsSummary(allResults, this.condition)}`);
-                return [false, allRuleResults];
+                return {
+                    triggered: false,
+                    ruleResults: allRuleResults,
+                };
             }
             // otherwise AND and did not return already so all passed
             this.logger.info(`${PASS} => Rules: ${resultsSummary(allResults, this.condition)}`);
-            return [true, allRuleResults];
+            return {
+                triggered: true,
+                ruleResults: allRuleResults,
+            };
         } catch (e: any) {
-            e.logged = true;
-            this.logger.warn(`Running rules failed due to uncaught exception`, e);
-            throw e;
+            throw new ErrorWithCause('Running rules failed due to error', {cause: e});
         }
     }
 
@@ -279,7 +467,7 @@ export abstract class Check implements ICheck {
     }
 }
 
-export interface ICheck extends JoinCondition, ChecksActivityState {
+export interface ICheck extends JoinCondition, ChecksActivityState, PostBehavior {
     /**
      * Friendly name for this Check EX "crosspostSpamCheck"
      *
@@ -332,6 +520,7 @@ export interface CheckOptions extends ICheck {
     resources: SubredditResources;
     client: ExtendedSnoowrap;
     cacheUserResult?: UserResultCacheOptions;
+    emitter: EventEmitter
 }
 
 export interface CheckJson extends ICheck {
@@ -339,7 +528,7 @@ export interface CheckJson extends ICheck {
      * The type of event (new submission or new comment) this check should be run against
      * @examples ["submission", "comment"]
      */
-    kind: 'submission' | 'comment'
+    kind: ActivityType
     /**
      * A list of Rules to run.
      *

src/Common/ImageData.ts

@@ -3,9 +3,9 @@ import {Submission} from "snoowrap/dist/objects";
 import {URL} from "url";
 import {absPercentDifference, getSharpAsync, isValidImageURL} from "../util";
 import sizeOf from "image-size";
-import SimpleError from "../Utils/SimpleError";
 import {Sharp} from "sharp";
 import {blockhash} from "./blockhash/blockhash";
+import {SimpleError} from "../Utils/Errors";
 
 export interface ImageDataOptions {
     width?: number,

src/Common/Migrations/Cache/1644350232664-addActivityType.ts

@@ -0,0 +1,95 @@
+import {Cache} from 'cache-manager';
+import {ActionedEvent, CheckSummary, RunResult} from "../../interfaces";
+import {
+    COMMENT_URL_ID,
+    parseLinkIdentifier,
+    parseStringToRegex,
+    redisScanIterator,
+    SUBMISSION_URL_ID
+} from "../../../util";
+const commentReg = parseLinkIdentifier([COMMENT_URL_ID]);
+const submissionReg = parseLinkIdentifier([SUBMISSION_URL_ID]);
+
+const commentPeekHint = new RegExp(/by .+ in/i);
+
+export const up = async (context: any, next: any) => {
+    const client = context.client as Cache;
+    const prefix = context.prefix as string | undefined;
+
+    const subredditEventMap: Record<string, any[] | undefined> = {};
+
+    // @ts-ignore
+    if(client.store.name === 'redis') {
+        // @ts-ignore
+        for await (const key of redisScanIterator(client.store.getClient(), { MATCH: `${prefix !== undefined ? prefix : ''}actionedEvents-*` })) {
+            const nonPrefixedKey = prefix !== undefined ? key.replace(prefix, '') : key;
+            subredditEventMap[nonPrefixedKey] = await client.get(nonPrefixedKey);
+        }
+    } else if(client.store.keys !== undefined) {
+        const eventsReg = parseStringToRegex(`/${prefix !== undefined ? prefix : ''}actionedEvents-.*/i`) as RegExp;
+        for (const key of await client.store.keys()) {
+            if(eventsReg.test(key)) {
+                const nonPrefixedKey = prefix !== undefined ? key.replace(prefix, '') : key;
+                subredditEventMap[nonPrefixedKey] = await client.get(nonPrefixedKey);
+            }
+        }
+    }
+
+    for (const [k, v] of Object.entries(subredditEventMap)) {
+        const oldEvents = v;
+        if (oldEvents === null || oldEvents === undefined) {
+            continue;
+        }
+        const newEvents = (oldEvents as any[]).map(x => {
+            const {
+                activity,
+                subreddit,
+                author,
+                ...rest
+            } = x;
+
+            const {
+                peek,
+                link,
+            } = activity;
+
+            let actType;
+            let id;
+
+            try {
+                // this *should* work
+                const commentId = commentReg(`https://reddit.com${link}`);
+                if(commentId === undefined) {
+                    const submissionId = submissionReg(`https://reddit.com${link}`);
+                    actType = 'submission';
+                    id = submissionId;
+                } else {
+                    actType = 'comment';
+                    id = commentId;
+                }
+            } catch(e: any) {
+                // but if it doesn't fall back to looking for 'in' in the peek since that means "comment in submission"
+                actType = commentPeekHint.test(peek as string) ? 'comment' : 'submission';
+            }
+
+            const result: ActionedEvent = {
+                activity: {
+                    peek,
+                    link,
+                    type: actType,
+                    id,
+                    subreddit,
+                    author
+                },
+                subreddit,
+                ...rest,
+            }
+            return result;
+        });
+       await client.set(k, newEvents, {ttl: 0});
+    }
+}
+
+export const down = async (context: any, next: any) => {
+    // backwards compatible with previous structure, not needed
+}

src/Common/Migrations/Cache/1644350232664-init.ts

@@ -0,0 +1,120 @@
+import {Cache} from 'cache-manager';
+import {ActionedEvent, CheckSummary, RunResult} from "../../interfaces";
+import {parseStringToRegex, redisScanIterator} from "../../../util";
+
+export const up = async (context: any, next: any) => {
+    const client = context.client as Cache;
+    const prefix = context.prefix as string | undefined;
+
+    const subredditEventMap: Record<string, any[] | undefined> = {};
+
+    // @ts-ignore
+    if(client.store.name === 'redis') {
+        // @ts-ignore
+        for await (const key of redisScanIterator(client.store.getClient(), { MATCH: `${prefix !== undefined ? prefix : ''}actionedEvents-*` })) {
+            const nonPrefixedKey = prefix !== undefined ? key.replace(prefix, '') : key;
+            subredditEventMap[nonPrefixedKey] = await client.get(nonPrefixedKey);
+        }
+    } else if(client.store.keys !== undefined) {
+        const eventsReg = parseStringToRegex(`/${prefix !== undefined ? prefix : ''}actionedEvents-.*/i`) as RegExp;
+        for (const key of await client.store.keys()) {
+            if(eventsReg.test(key)) {
+                const nonPrefixedKey = prefix !== undefined ? key.replace(prefix, '') : key;
+                subredditEventMap[nonPrefixedKey] = await client.get(nonPrefixedKey);
+            }
+        }
+    }
+
+    for (const [k, v] of Object.entries(subredditEventMap)) {
+        const oldEvents = v;
+        if (oldEvents === null || oldEvents === undefined) {
+            continue;
+        }
+        const newEvents = (oldEvents as any[]).map(x => {
+            const {
+                ruleSummary,
+                ruleResults = [],
+                actionResults = [],
+                check,
+                ...rest
+            } = x;
+            if (check === undefined || check === null) {
+                // probably new structure, leave it alone
+                return x;
+            }
+            // otherwise wrap in dummy run
+            const result: ActionedEvent = {
+                ...rest,
+                runResults: [
+                    {
+                        name: 'Run1',
+                        triggered: true,
+                        checkResults: [
+                            {
+                                name: check,
+                                run: 'Run1',
+                                postBehavior: 'nextRun',
+                                triggered: true,
+                                condition: ruleSummary.includes('OR') ? 'OR' : 'AND',
+                                ruleResults,
+                                actionResults,
+                            }
+                        ],
+                    }
+                ]
+            }
+            return result;
+        });
+        await client.set(k, newEvents, {ttl: 0});
+    }
+}
+
+export const down = async (context: any, next: any) => {
+    const client = context.client as Cache;
+    const prefix = context.prefix as string | undefined;
+
+    const subredditEventMap: Record<string, any[] | undefined> = {};
+
+    // @ts-ignore
+    if(client.store.name === 'redis') {
+        // @ts-ignore
+        for await (const key of redisScanIterator(client.store.getClient(), { MATCH: `${prefix !== undefined ? prefix : ''}actionedEvents-*` })) {
+            const nonPrefixedKey = prefix !== undefined ? key.replace(prefix, '') : key;
+            subredditEventMap[nonPrefixedKey] = await client.get(nonPrefixedKey);
+        }
+    } else if(client.store.keys !== undefined) {
+        const eventsReg = parseStringToRegex(`/${prefix !== undefined ? prefix : ''}actionedEvents-.*/i`) as RegExp;
+        for (const key of await client.store.keys()) {
+            if(eventsReg.test(key)) {
+                const nonPrefixedKey = prefix !== undefined ? key.replace(prefix, '') : key;
+                subredditEventMap[nonPrefixedKey] = await client.get(nonPrefixedKey);
+            }
+        }
+    }
+
+    for (const [k, v] of Object.entries(subredditEventMap)) {
+        const oldEvents = v;
+        if (oldEvents === null || oldEvents === undefined) {
+            continue;
+        }
+        // don't want to lose any multi-check events so create one event per check
+        const newEvents = (oldEvents as any[]).reduce((acc, curr) => {
+            if (curr.check !== undefined) {
+                // its an old event so just return it
+                acc.push(curr);
+                return acc;
+            }
+            const {runResults = [], ...rest} = curr;
+            const singleEvents = (runResults as RunResult[]).map(y => {
+                return {
+                    ...rest,
+                    ruleResults: y.checkResults[0].ruleResults,
+                    actionResults: y.checkResults[0].actionResults,
+                    check: y.name,
+                }
+            });
+            return acc.concat(singleEvents);
+        }, []);
+        await client.set(k, newEvents, {ttl: 0});
+    }
+}

src/Common/Migrations/CacheMigrationUtils.ts

@@ -0,0 +1,69 @@
+import {Cache} from 'cache-manager';
+import {Logger} from "winston";
+import {mergeArr} from "../../util";
+import * as migrate from 'migrate';
+import path from "path";
+import {ErrorWithCause} from "pony-cause";
+
+export const cacheMigrationStorage = (client: Cache, resourceLogger: Logger) => {
+    const logger = resourceLogger.child({leaf: 'Cache Migration'}, mergeArr);
+
+    return {
+        load: async function (fn: any) {
+
+            const migrationData = await client.get('migrations');
+
+            if (migrationData === null || migrationData === undefined) {
+                logger.debug('No migration data exists (normal if cache is memory or first-run with anything else)');
+                return fn(null, {})
+            }
+            fn(null, migrationData);
+        },
+
+        save: async function (set: any, fn: any) {
+
+            await client.set('migrations', {lastRun: set.lastRun, migrations: set.migrations}, {ttl: 0});
+            fn()
+        }
+    };
+}
+
+// with the context stuff use it like this
+// migrate.load({
+//     stateStore: cacheMigrationStorage(client, logger)
+// }, (err, set) => {
+//     set.migrate('up', null, (err) => {
+//
+//     }, {client, subreddit });
+// });
+
+export const migrationDir = path.resolve(__dirname, 'Cache');
+
+export const runMigrations = async (cache: Cache, logger: Logger, prefix?: string) => {
+    const stateStore = cacheMigrationStorage(cache, logger);
+    const context = {client: cache, prefix};
+    return new Promise<void>((resolve, reject) => {
+        migrate.load({
+            migrationsDirectory: migrationDir,
+            stateStore,
+            filterFunction: (file) => {
+                return file.substring(file.length - 3) === '.js';
+            },
+        }, (err, set) => {
+            set.on('migration', function (migration, direction) {
+                logger.debug(`${direction}: ${migration.title}`, {leaf: 'Cache Migration'});
+            });
+            set.migrate('up', null, (err) => {
+                if (err) {
+                    const migError = new ErrorWithCause('Failed to complete cache migrations', {cause: err});
+                    logger.error(migError);
+                    reject(err);
+                } else {
+                    logger.debug('Migrations completed', {leaf: 'Cache Migration'});
+                    resolve();
+                }
+                // @ts-ignore
+            }, context);
+        });
+    })
+}

src/Common/defaults.ts

@@ -39,3 +39,5 @@ export const filterCriteriaDefault: FilterCriteriaDefaults = {
         ]
     }
 }
+
+export const VERSION = '0.10.12';

src/Common/interfaces.ts

@@ -13,6 +13,11 @@ import {ConfigFormat} from "./types";
 import AbstractConfigDocument, {ConfigDocumentInterface} from "./Config/AbstractConfigDocument";
 import {Document as YamlDocument} from 'yaml';
 import {JsonOperatorConfigDocument, YamlOperatorConfigDocument} from "./Config/Operator";
+import {ConsoleTransportOptions} from "winston/lib/winston/transports";
+import {DailyRotateFileTransportOptions} from "winston-daily-rotate-file";
+import {DuplexTransportOptions} from "winston-duplex/dist/DuplexTransport";
+import {CommentCheckJson, SubmissionCheckJson} from "../Check";
+import {SafeDictionary} from "ts-essentials";
 
 /**
  * An ISO 8601 Duration
@@ -833,6 +838,16 @@ export interface ManagerOptions {
      * Default behavior is to exclude all mods and automoderator from checks
      * */
     filterCriteriaDefaults?: FilterCriteriaDefaults
+
+    /**
+     * Set the default post-check behavior for all checks. If this property is specified it will override any defaults passed from the bot's config
+     *
+     * Default behavior is:
+     *
+     * * postFail => next
+     * * postTrigger => nextRun
+     * */
+    postCheckBehaviorDefaults?: PostBehavior
 }
 
 /**
@@ -946,6 +961,10 @@ export interface SubmissionState extends ActivityState {
     link_flair_text?: string | string[]
     link_flair_css_class?: string | string[]
     flairTemplate?: string | string[]
+    /**
+     * Is the submission a reddit-hosted image or video?
+     * */
+    isRedditMediaDomain?: boolean
 }
 
 // properties calculated/derived by CM -- not provided as plain values by reddit
@@ -1011,7 +1030,9 @@ export interface StrongSubredditState extends SubredditState {
     name?: RegExp
 }
 
-export type TypedActivityStates = SubmissionState[] | CommentState[];
+export type TypedActivityState = SubmissionState | CommentState;
+
+export type TypedActivityStates = TypedActivityState[];
 
 export interface DomainInfo {
     display: string,
@@ -1071,6 +1092,92 @@ export interface RegExResult {
 }
 
 type LogLevel = "error" | "warn" | "info" | "verbose" | "debug";
+
+export type LogConsoleOptions = Pick<ConsoleTransportOptions, 'silent' | 'eol' | 'stderrLevels' | 'consoleWarnLevels'> & {
+    level?: LogLevel
+}
+
+export type LogFileOptions = Omit<DailyRotateFileTransportOptions, 'stream' | 'handleRejections' | 'options' | 'handleExceptions' | 'format' | 'log' | 'logv' | 'close' | 'dirname'> & {
+    level?: LogLevel
+    /**
+     * The absolute path to a directory where rotating log files should be stored.
+     *
+     * * If not present or `null` or `false` no log files will be created
+     * * If `true` logs will be stored at `[working directory]/logs`
+     *
+     * * ENV => `LOG_DIR`
+     * * ARG => `--logDir [dir]`
+     *
+     * @examples ["/var/log/contextmod"]
+     * */
+    dirname?: string | boolean | null
+}
+
+// export type StrongFileOptions = LogFileOptions & {
+//     dirname?: string
+// }
+
+export type LogStreamOptions = Omit<DuplexTransportOptions, 'name' | 'stream' | 'handleRejections' | 'handleExceptions' | 'format' | 'log' | 'logv' | 'close'> & {
+    level?: LogLevel
+}
+
+export interface LoggingOptions  {
+    /**
+     * The minimum log level to output. The log level set will output logs at its level **and all levels above it:**
+     *
+     *  * `error`
+     *  * `warn`
+     *  * `info`
+     *  * `verbose`
+     *  * `debug`
+     *
+     *  Note: `verbose` will display *a lot* of information on the status/result of run rules/checks/actions etc. which is very useful for testing configurations. Once your bot is stable changing the level to `info` will reduce log noise.
+     *
+     *  * ENV => `LOG_LEVEL`
+     *  * ARG => `--logLevel <level>`
+     *
+     *  @default "verbose"
+     *  @examples ["verbose"]
+     * */
+    level?: LogLevel,
+    /**
+     * **DEPRECATED** - Use `file.dirname` instead
+     * The absolute path to a directory where rotating log files should be stored.
+     *
+     * * If not present or `null` or `false` no log files will be created
+     * * If `true` logs will be stored at `[working directory]/logs`
+     *
+     * * ENV => `LOG_DIR`
+     * * ARG => `--logDir [dir]`
+     *
+     * @examples ["/var/log/contextmod"]
+     * @deprecated
+     * @see logging.file.dirname
+     * */
+    path?: string | boolean | null
+
+    /**
+     * Options for Rotating File logging
+     * */
+    file?: LogFileOptions
+    /**
+     * Options for logging to api/web
+     * */
+    stream?: LogStreamOptions
+    /**
+     * Options for logging to console
+     * */
+    console?: LogConsoleOptions
+}
+
+export type StrongLoggingOptions = Required<Pick<LoggingOptions, 'stream' | 'console' | 'file'>> & {
+    level?: LogLevel
+};
+
+export type LoggerFactoryOptions = StrongLoggingOptions & {
+    additionalTransports?: any[]
+    defaultLabel?: string
+}
 /**
  * Available cache providers
  * */
@@ -1157,6 +1264,14 @@ export type NotificationProvider = 'discord';
 
 export type NotificationEventType = 'runStateChanged' | 'pollingError' | 'eventActioned' | 'configUpdated'
 
+export interface NotificationEventPayload  {
+    type: NotificationEventType,
+    title: string
+    body?: string
+    causedBy?: string
+    logLevel?: string
+}
+
 export interface NotificationProviderConfig {
     name: string
     type: NotificationProvider
@@ -1352,6 +1467,13 @@ export interface FilterCriteriaDefaults {
     authorIsBehavior?: FilterCriteriaDefaultBehavior
 }
 
+export interface SubredditOverrides {
+    name: string
+    flowControlDefaults?: {
+        maxGotoDepth?: number
+    }
+}
+
 /**
  * The configuration for an **individual reddit account** ContextMod will run as a bot.
  *
@@ -1387,6 +1509,12 @@ export interface BotInstanceJsonConfig {
      * */
     filterCriteriaDefaults?: FilterCriteriaDefaults
 
+    postCheckBehaviorDefaults?: PostBehavior
+
+    flowControlDefaults?: {
+        maxGotoDepth?: number
+    }
+
     /**
      * Settings related to bot behavior for subreddits it is managing
      * */
@@ -1447,6 +1575,8 @@ export interface BotInstanceJsonConfig {
          * @examples [300]
          * */
         heartbeatInterval?: number,
+
+        overrides?: SubredditOverrides[]
     }
 
     /**
@@ -1483,22 +1613,23 @@ export interface BotInstanceJsonConfig {
          * Useful when running many subreddits and rules are potentially cpu/memory/traffic heavy -- allows spreading out load
          * */
         stagger?: number,
-    },
+    }
+
     /**
      * Settings related to default configurations for queue behavior for subreddits
      * */
     queue?: {
-        /**
-         * Set the number of maximum concurrent workers any subreddit can use.
-         *
-         * Subreddits may define their own number of max workers in their config but the application will never allow any subreddit's max workers to be larger than the operator
-         *
-         * NOTE: Do not increase this unless you are certain you know what you are doing! The default is suitable for the majority of use cases.
-         *
-         * @default 1
-         * @examples [1]
-         * */
-        maxWorkers?: number,
+    /**
+     * Set the number of maximum concurrent workers any subreddit can use.
+     *
+     * Subreddits may define their own number of max workers in their config but the application will never allow any subreddit's max workers to be larger than the operator
+     *
+     * NOTE: Do not increase this unless you are certain you know what you are doing! The default is suitable for the majority of use cases.
+     *
+     * @default 1
+     * @examples [1]
+     * */
+    maxWorkers?: number,
     }
 
     /**
@@ -1581,38 +1712,7 @@ export interface OperatorJsonConfig {
     /**
      * Settings to configure global logging defaults
      * */
-    logging?: {
-        /**
-         * The minimum log level to output. The log level set will output logs at its level **and all levels above it:**
-         *
-         *  * `error`
-         *  * `warn`
-         *  * `info`
-         *  * `verbose`
-         *  * `debug`
-         *
-         *  Note: `verbose` will display *a lot* of information on the status/result of run rules/checks/actions etc. which is very useful for testing configurations. Once your bot is stable changing the level to `info` will reduce log noise.
-         *
-         *  * ENV => `LOG_LEVEL`
-         *  * ARG => `--logLevel <level>`
-         *
-         *  @default "verbose"
-         *  @examples ["verbose"]
-         * */
-        level?: LogLevel,
-        /**
-         * The absolute path to a directory where rotating log files should be stored.
-         *
-         * * If not present or `null` no log files will be created
-         * * If `true` logs will be stored at `[working directory]/logs`
-         *
-         * * ENV => `LOG_DIR`
-         * * ARG => `--logDir [dir]`
-         *
-         * @examples ["/var/log/contextmod"]
-         * */
-        path?: string,
-    },
+    logging?: LoggingOptions,
 
     /**
      * Settings to configure the default caching behavior globally
@@ -1628,6 +1728,17 @@ export interface OperatorJsonConfig {
 
     bots?: BotInstanceJsonConfig[]
 
+    /**
+     * Added to the User-Agent information sent to reddit
+     *
+     * This string will be added BETWEEN version and your bot name.
+     *
+     * EX: `myBranch` => `web:contextMod:v1.0.0-myBranch:BOT-/u/MyBotUser`
+     *
+     * * ENV => `USER_AGENT`
+     * */
+    userAgent?: string
+
     /**
      * Settings for the web interface
      * */
@@ -1788,6 +1899,7 @@ export interface BotInstanceConfig extends BotInstanceJsonConfig {
         dryRun?: boolean,
         wikiConfig: string,
         heartbeatInterval: number,
+        overrides?: SubredditOverrides[]
     },
     polling: {
         shared: PollOn[],
@@ -1803,6 +1915,7 @@ export interface BotInstanceConfig extends BotInstanceJsonConfig {
         softLimit: number,
         hardLimit: number,
     }
+    userAgent?: string
 }
 
 export interface OperatorConfig extends OperatorJsonConfig {
@@ -1812,10 +1925,7 @@ export interface OperatorConfig extends OperatorJsonConfig {
         display?: string,
     },
     notifications?: NotificationConfig
-    logging: {
-        level: LogLevel,
-        path?: string,
-    },
+    logging: StrongLoggingOptions,
     caching: StrongCache,
     web: {
         port: number,
@@ -1876,6 +1986,7 @@ export interface LogInfo {
     instance?: string
     labels?: string[]
     bot?: string
+    user?: string
 }
 
 export interface ActionResult extends ActionProcessResult {
@@ -1883,6 +1994,8 @@ export interface ActionResult extends ActionProcessResult {
     name: string,
     run: boolean,
     runReason?: string,
+    itemIs?: FilterResult<TypedActivityState>
+    authorIs?: FilterResult<AuthorCriteria>
 }
 
 export interface ActionProcessResult {
@@ -1892,18 +2005,49 @@ export interface ActionProcessResult {
     touchedEntities?: (Submission | Comment | RedditUser | string)[]
 }
 
-export interface ActionedEvent {
-    activity: {
-        peek: string
-        link: string
-    }
+export interface EventActivity {
+    peek: string
+    link: string
+    type: ActivityType
+    id: string
+    subreddit: string
     author: string
+}
+
+export interface ActionedEvent {
+    activity: EventActivity
+    parentSubmission?: EventActivity
     timestamp: number
-    check: string
-    ruleSummary: string,
     subreddit: string,
+    triggered: boolean,
+    runResults: RunResult[]
+}
+
+export interface CheckResult {
+    triggered: boolean
     ruleResults: RuleResult[]
+    itemIs?: FilterResult<TypedActivityState>
+    authorIs?: FilterResult<AuthorCriteria>
+    fromCache?: boolean
+}
+
+export interface CheckSummary extends CheckResult {
+    name: string
+    run: string
+    postBehavior: string
+    error?: string
     actionResults: ActionResult[]
+    condition: 'AND' | 'OR'
+}
+
+export interface RunResult {
+    name: string
+    triggered: boolean
+    reason?: string
+    error?: string
+    itemIs?: FilterResult<TypedActivityState>
+    authorIs?: FilterResult<AuthorCriteria>
+    checkResults: CheckSummary[]
 }
 
 export interface UserResultCache {
@@ -1918,22 +2062,6 @@ export interface RedditEntity {
     type: RedditEntityType
 }
 
-export interface StatusCodeError extends Error {
-    name: 'StatusCodeError',
-    statusCode: number,
-    message: string,
-    response: IncomingMessage,
-    error: Error
-}
-
-export interface RequestError extends Error {
-    name: 'RequestError',
-    statusCode: number,
-    message: string,
-    response: IncomingMessage,
-    error: Error
-}
-
 export interface HistoricalStatsDisplay extends HistoricalStats {
     checksRunTotal: number
     checksFromCacheTotal: number
@@ -2005,13 +2133,13 @@ export interface ManagerStats {
 export interface HistoricalStatUpdateData {
     eventsCheckedTotal?: number
     eventsActionedTotal?: number
-    checksRun: string[] | string
-    checksTriggered: string[] | string
-    checksFromCache: string[] | string
-    actionsRun: string[] | string
-    rulesRun: string[] | string
-    rulesCachedTotal: number
-    rulesTriggered: string[] | string
+    checksRun?: string[] | string
+    checksTriggered?: string[] | string
+    checksFromCache?: string[] | string
+    actionsRun?: string[] | string
+    rulesRun?: string[] | string
+    rulesCachedTotal?: number
+    rulesTriggered?: string[] | string
 }
 
 export type SearchFacetType = 'title' | 'url' | 'duplicates' | 'crossposts' | 'external';
@@ -2040,8 +2168,7 @@ export interface StringComparisonOptions {
 
 export interface FilterCriteriaPropertyResult<T> {
     property: keyof T
-    expected: (string | boolean | number)[]
-    found?: string | boolean | number | null
+    found?: string | boolean | number | null | FilterResult<any>
     passed?: null | boolean
     reason?: string
     behavior: FilterBehavior
@@ -2061,3 +2188,92 @@ export interface FilterResult<T> {
     join: JoinOperands
     passed: boolean
 }
+
+export interface TextTransformOptions {
+    /**
+     * A set of search-and-replace operations to perform on text values before performing a match. Transformations are performed in the order they are defined.
+     *
+     * * If `transformationsActivity` IS NOT defined then these transformations will be performed on BOTH the activity text (submission title or comment) AND the repost candidate text
+     * * If `transformationsActivity` IS defined then these transformations are only performed on repost candidate text
+     * */
+    transformations?: SearchAndReplaceRegExp[]
+
+    /**
+     * Specify a separate set of transformations for the activity text (submission title or comment)
+     *
+     * To perform no transformations when `transformations` is defined set this to an empty array (`[]`)
+     * */
+    transformationsActivity?: SearchAndReplaceRegExp[]
+}
+
+export interface TextMatchOptions {
+    /**
+     * The percentage, as a whole number, of a repost title/comment that must match the title/comment being checked in order to consider both a match
+     *
+     * Note: Setting to 0 will make every candidate considered a match -- useful if you want to match if the URL has been reposted anywhere
+     *
+     * Defaults to `85` (85%)
+     *
+     * @default 85
+     * @example [85]
+     * */
+    matchScore?: number
+
+    /**
+     * The minimum number of words in the activity being checked for which this rule will run on
+     *
+     * If the word count is below the minimum the rule fails
+     *
+     * Defaults to 2
+     *
+     * @default 2
+     * @example [2]
+     * */
+    minWordCount?: number
+
+    /**
+     * Should text matching be case sensitive?
+     *
+     * Defaults to false
+     *
+     * @default false
+     * @example [false]
+     **/
+    caseSensitive?: boolean
+}
+
+export type ActivityCheckJson = SubmissionCheckJson | CommentCheckJson;
+
+export type GotoPath = `goto:${string}`;
+/**
+ * The possible behaviors that can occur after a check has run
+ *
+ * * next => continue to next Check/Run
+ * * stop => stop CM lifecycle for this activity (immediately end)
+ * * nextRun => skip any remaining Checks in this Run and start the next Run
+ * * goto:[path] => specify a run[.check] to jump to
+ *
+ * */
+export type PostBehaviorTypes = 'next' | 'stop' | 'nextRun' | string;
+
+export interface PostBehavior {
+    /**
+     * Do this behavior if a Check is triggered
+     *
+     * @default nextRun
+     * @example ["nextRun"]
+     * */
+    postTrigger?: PostBehaviorTypes
+    /**
+     * Do this behavior if a Check is NOT triggered
+     *
+     * @default next
+     * @example ["next"]
+     * */
+    postFail?: PostBehaviorTypes
+}
+
+export type ActivityType = 'submission' | 'comment';
+
+export type ItemCritPropHelper = SafeDictionary<FilterCriteriaPropertyResult<(CommentState & SubmissionState)>, keyof (CommentState & SubmissionState)>;
+export type RequiredItemCrit = Required<(CommentState & SubmissionState)>;

src/Common/typings/support.d.ts

@@ -0,0 +1,26 @@
+declare module 'snoowrap/dist/errors' {
+
+    export interface InvalidUserError extends Error {
+
+    }
+    export interface NoCredentialsError extends Error {
+
+    }
+    export interface InvalidMethodCallError extends Error {
+
+    }
+
+    export interface RequestError extends Error {
+        statusCode: number,
+        response: http.IncomingMessage
+        error: Error
+    }
+
+    export interface StatusCodeError extends RequestError {
+        name: 'StatusCodeError',
+    }
+
+    export interface RateLimitError extends RequestError {
+        name: 'RateLimitError',
+    }
+}

src/ConfigBuilder.ts

@@ -2,7 +2,7 @@ import {Logger} from "winston";
 import {
     buildCacheOptionsFromProvider, buildCachePrefix,
     createAjvFactory, fileOrDirectoryIsWriteable,
-    mergeArr,
+    mergeArr, mergeFilters,
     normalizeName,
     overwriteMerge,
     parseBool, parseFromJsonOrYamlToObject, randomId,
@@ -35,7 +35,7 @@ import {
     RedditCredentials,
     BotCredentialsJsonConfig,
     BotCredentialsConfig,
-    FilterCriteriaDefaults, TypedActivityStates, OperatorFileConfig
+    FilterCriteriaDefaults, TypedActivityStates, OperatorFileConfig, PostBehavior
 } from "./Common/interfaces";
 import {isRuleSetJSON, RuleSetJson, RuleSetObjectJson} from "./Rule/RuleSet";
 import deepEqual from "fast-deep-equal";
@@ -55,9 +55,11 @@ import {
     OperatorConfigDocumentInterface,
     YamlOperatorConfigDocument
 } from "./Common/Config/Operator";
-import SimpleError from "./Utils/SimpleError";
 import {ConfigDocumentInterface} from "./Common/Config/AbstractConfigDocument";
 import {Document as YamlDocument} from "yaml";
+import {SimpleError} from "./Utils/Errors";
+import {ErrorWithCause} from "pony-cause";
+import {RunStructuredJson} from "./Run";
 
 export interface ConfigBuilderOptions {
     logger: Logger,
@@ -129,55 +131,66 @@ export class ConfigBuilder {
         return validConfig as JSONConfig;
     }
 
-    parseToStructured(config: JSONConfig, filterCriteriaDefaultsFromBot?: FilterCriteriaDefaults): CheckStructuredJson[] {
+    parseToStructured(config: JSONConfig, filterCriteriaDefaultsFromBot?: FilterCriteriaDefaults, postCheckBehaviorDefaultsFromBot: PostBehavior = {}): RunStructuredJson[] {
         let namedRules: Map<string, RuleObjectJson> = new Map();
         let namedActions: Map<string, ActionObjectJson> = new Map();
-        const {checks = [], filterCriteriaDefaults} = config;
-        for (const c of checks) {
-            const {rules = []} = c;
-            namedRules = extractNamedRules(rules, namedRules);
-            namedActions = extractNamedActions(c.actions, namedActions);
+        const {checks = [], runs = [], filterCriteriaDefaults, postCheckBehaviorDefaults} = config;
+
+        if(checks.length > 0 && runs.length > 0) {
+            // cannot have both checks and runs at top-level
+            throw new Error(`Subreddit configuration cannot contain both 'checks' and 'runs' at top-level.`);
         }
 
-        const filterDefs = filterCriteriaDefaults ?? filterCriteriaDefaultsFromBot;
-        const {
-            authorIsBehavior = 'merge',
-            itemIsBehavior = 'merge',
-            authorIs: authorIsDefault = {},
-            itemIs: itemIsDefault = []
-        } = filterDefs || {};
-
-        const structuredChecks: CheckStructuredJson[] = [];
-        for (const c of checks) {
-            const {rules = [], authorIs = {}, itemIs = []} = c;
-            const strongRules = insertNamedRules(rules, namedRules);
-            const strongActions = insertNamedActions(c.actions, namedActions);
-
-            let derivedAuthorIs: AuthorOptions = authorIsDefault;
-            if (authorIsBehavior === 'merge') {
-                derivedAuthorIs = merge.all([authorIs, authorIsDefault], {arrayMerge: removeFromSourceIfKeysExistsInDestination});
-            } else if (Object.keys(authorIs).length > 0) {
-                derivedAuthorIs = authorIs;
-            }
-
-            let derivedItemIs: TypedActivityStates = itemIsDefault;
-            if (itemIsBehavior === 'merge') {
-                derivedItemIs = [...itemIs, ...itemIsDefault];
-            } else if (itemIs.length > 0) {
-                derivedItemIs = itemIs;
-            }
-
-            const strongCheck = {
-                ...c,
-                authorIs: derivedAuthorIs,
-                itemIs: derivedItemIs,
-                rules: strongRules,
-                actions: strongActions
-            } as CheckStructuredJson;
-            structuredChecks.push(strongCheck);
+        const realRuns  = runs;
+        if(checks.length > 0) {
+            realRuns.push({name: 'Run1', checks: checks});
         }
 
-        return structuredChecks;
+        for(const r of realRuns) {
+            for (const c of r.checks) {
+                const {rules = []} = c;
+                namedRules = extractNamedRules(rules, namedRules);
+                namedActions = extractNamedActions(c.actions, namedActions);
+            }
+        }
+
+        const structuredRuns: RunStructuredJson[] = [];
+
+        for(const r of realRuns) {
+
+            const {filterCriteriaDefaults: filterCriteriaDefaultsFromRun, postFail, postTrigger, authorIs, itemIs } = r;
+
+            const [derivedRunAuthorIs, derivedRunItemIs] = mergeFilters(r, filterCriteriaDefaults ?? filterCriteriaDefaultsFromBot);
+
+            const structuredChecks: CheckStructuredJson[] = [];
+            for (const c of r.checks) {
+                const {rules = [], authorIs = {}, itemIs = []} = c;
+                const strongRules = insertNamedRules(rules, namedRules);
+                const strongActions = insertNamedActions(c.actions, namedActions);
+
+                const [derivedAuthorIs, derivedItemIs] = mergeFilters(c, filterCriteriaDefaultsFromRun ?? (filterCriteriaDefaults ?? filterCriteriaDefaultsFromBot));
+
+                const postCheckBehaviors = Object.assign({}, postCheckBehaviorDefaultsFromBot, removeUndefinedKeys({postFail, postTrigger}));
+
+                const strongCheck = {
+                    ...c,
+                    authorIs: derivedAuthorIs,
+                    itemIs: derivedItemIs,
+                    rules: strongRules,
+                    actions: strongActions,
+                    ...postCheckBehaviors
+                } as CheckStructuredJson;
+                structuredChecks.push(strongCheck);
+            }
+            structuredRuns.push({
+                ...r,
+                checks: structuredChecks,
+                authorIs: derivedRunAuthorIs,
+                itemIs: derivedRunItemIs
+            });
+        }
+
+        return structuredRuns;
     }
 }
 
@@ -373,7 +386,16 @@ export const parseOpConfigFromArgs = (args: any): OperatorJsonConfig => {
         },
         logging: {
             level: logLevel,
-            path: logDir === true ? `${process.cwd()}/logs` : undefined,
+            file: {
+                level: logLevel,
+                dirName: logDir,
+            },
+            stream: {
+                level: logLevel,
+            },
+            console: {
+                level: logLevel,
+            }
         },
         caching: {
             provider: caching,
@@ -457,9 +479,17 @@ export const parseOpConfigFromEnv = (): OperatorJsonConfig => {
             display: process.env.OPERATOR_DISPLAY
         },
         logging: {
-            // @ts-ignore
             level: process.env.LOG_LEVEL,
-            path: process.env.LOG_DIR === 'true' ? `${process.cwd()}/logs` : undefined,
+            file: {
+                level: process.env.LOG_LEVEL,
+                dirname: process.env.LOG_DIR,
+            },
+            stream: {
+                level: process.env.LOG_LEVEL,
+            },
+            console: {
+                level: process.env.LOG_LEVEL,
+            }
         },
         caching: {
             provider: {
@@ -501,11 +531,25 @@ export const parseOpConfigFromEnv = (): OperatorJsonConfig => {
 // json config
 // args from cli
 export const parseOperatorConfigFromSources = async (args: any): Promise<[OperatorJsonConfig, OperatorFileConfig]> => {
-    const {logLevel = process.env.LOG_LEVEL, logDir = process.env.LOG_DIR || false} = args || {};
+    const {logLevel = process.env.LOG_LEVEL ?? 'debug', logDir = process.env.LOG_DIR} = args || {};
     const envPath = process.env.OPERATOR_ENV;
+    const initLoggerOptions = {
+        level: logLevel,
+        console: {
+            level: logLevel
+        },
+        file: {
+            level: logLevel,
+            dirname: logDir,
+        },
+        stream: {
+            level: logLevel
+        }
+    }
 
     // create a pre config logger to help with debugging
-    const initLogger = getLogger({logLevel, logDir: logDir === true ? `${process.cwd()}/logs` : logDir}, 'init');
+    // default to debug if nothing is provided
+    const initLogger = getLogger(initLoggerOptions, 'init');
 
     try {
         const vars = await GetEnvVars({
@@ -556,9 +600,7 @@ export const parseOperatorConfigFromSources = async (args: any): Promise<[Operat
                 fileConfigFormat = err.extension
             }
         } else {
-            initLogger.error('Cannot continue app startup because operator config file exists but was not parseable.');
-            err.logged = true;
-            throw err;
+            throw new ErrorWithCause('Cannot continue app startup because operator config file exists but was not parseable.', {cause: err});
         }
     }
     const [format, doc, jsonErr, yamlErr] = parseFromJsonOrYamlToObject(rawConfig, {
@@ -591,7 +633,15 @@ export const parseOperatorConfigFromSources = async (args: any): Promise<[Operat
 
         try {
             configFromFile = validateJson(configDoc.toJS(), operatorSchema, initLogger) as OperatorJsonConfig;
-            const {bots = []} = configFromFile || {};
+            const {
+                bots = [],
+                logging: {
+                    path = undefined
+                } = {}
+            } = configFromFile || {};
+            if(path !== undefined) {
+                initLogger.warn(`'path' property in top-level 'logging' object is DEPRECATED and will be removed in next minor version. Use 'logging.file.dirname' instead`);
+            }
             for (const b of bots) {
                 const {
                     polling: {
@@ -628,9 +678,13 @@ export const parseOperatorConfigFromSources = async (args: any): Promise<[Operat
         defaultBotInstance.caching = configFromFile.caching;
     }
 
-    let botInstances = [];
+    let botInstances: BotInstanceJsonConfig[] = [];
     if (botInstancesFromFile.length === 0) {
-        botInstances = [defaultBotInstance];
+        // only add default bot if user supplied any credentials
+        // otherwise its most likely just default, empty settings
+        if(defaultBotInstance.credentials !== undefined) {
+            botInstances = [defaultBotInstance];
+        }
     } else {
         botInstances = botInstancesFromFile.map(x => merge.all([defaultBotInstance, x], {arrayMerge: overwriteMerge}));
     }
@@ -651,8 +705,12 @@ export const buildOperatorConfigWithDefaults = (data: OperatorJsonConfig): Opera
         logging: {
             level = 'verbose',
             path,
+            file = {},
+            console = {},
+            stream = {},
         } = {},
         caching: opCache,
+        userAgent,
         web: {
             port = 8085,
             maxLogs = 200,
@@ -726,6 +784,16 @@ export const buildOperatorConfigWithDefaults = (data: OperatorJsonConfig): Opera
 
     const defaultOperators = typeof name === 'string' ? [name] : name;
 
+    const {
+        dirname = path,
+        ...fileRest
+    } = file;
+
+     const defaultWebCredentials = {
+         redirectUri: 'http://localhost:8085/callback'
+     };
+
+
     const config: OperatorConfig = {
         mode,
         operator: {
@@ -734,9 +802,22 @@ export const buildOperatorConfigWithDefaults = (data: OperatorJsonConfig): Opera
         },
         logging: {
             level,
-            path
+            file: {
+                level: level,
+                dirname,
+                ...fileRest,
+            },
+            stream: {
+                level: level,
+                ...stream,
+            },
+            console: {
+                level: level,
+                ...console,
+            }
         },
         caching: cache,
+        userAgent,
         web: {
             port,
             caching: {
@@ -752,7 +833,7 @@ export const buildOperatorConfigWithDefaults = (data: OperatorJsonConfig): Opera
             },
             maxLogs,
             clients: clients === undefined ? [{host: 'localhost:8095', secret: apiSecret}] : clients,
-            credentials: webCredentials as RequiredWebRedditCredentials,
+            credentials: {...defaultWebCredentials, ...webCredentials} as RequiredWebRedditCredentials,
             operators: operators || defaultOperators,
         },
         api: {
@@ -776,11 +857,13 @@ export const buildBotConfig = (data: BotInstanceJsonConfig, opConfig: OperatorCo
             actionedEventsMax: opActionedEventsMax,
             actionedEventsDefault: opActionedEventsDefault = 25,
             provider: defaultProvider,
-        } = {}
+        } = {},
+        userAgent,
     } = opConfig;
     const {
         name: botName,
         filterCriteriaDefaults = filterCriteriaDefault,
+        postCheckBehaviorDefaults,
         polling: {
             sharedMod,
             shared = [],
@@ -797,8 +880,10 @@ export const buildBotConfig = (data: BotInstanceJsonConfig, opConfig: OperatorCo
             hardLimit = 50
         } = {},
         snoowrap = snoowrapOp,
+        flowControlDefaults,
         credentials = {},
         subreddits: {
+            overrides = [],
             names = [],
             exclude = [],
             wikiConfig = 'botconfig/contextbot',
@@ -907,16 +992,20 @@ export const buildBotConfig = (data: BotInstanceJsonConfig, opConfig: OperatorCo
     return {
         name: botName,
         snoowrap: snoowrap || {},
+        flowControlDefaults,
         filterCriteriaDefaults,
+        postCheckBehaviorDefaults,
         subreddits: {
             names,
             exclude,
             wikiConfig,
             heartbeatInterval,
             dryRun,
+            overrides,
         },
         credentials: botCreds,
         caching: botCache,
+        userAgent,
         polling: {
             shared: [...new Set(realShared)] as PollOn[],
             stagger,

src/JsonConfig.ts

@@ -1,5 +1,6 @@
 import {CheckJson, CommentCheckJson, SubmissionCheckJson} from "./Check";
-import {ManagerOptions} from "./Common/interfaces";
+import {ActivityCheckJson, ManagerOptions} from "./Common/interfaces";
+import {RunJson} from "./Run";
 
 export interface JSONConfig extends ManagerOptions {
     /**
@@ -12,5 +13,11 @@ export interface JSONConfig extends ManagerOptions {
      * When a check "passes", and actions are performed, then all subsequent checks are skipped.
      * @minItems 1
      * */
-    checks: Array<SubmissionCheckJson|CommentCheckJson>
+    checks?: ActivityCheckJson[]
+
+    /**
+     * A list of sets of Checks to run
+     * @minItems 1
+     * */
+    runs?: RunJson[]
 }

src/Rule/AttributionRule.ts

@@ -14,8 +14,8 @@ import {
     PASS
 } from "../util";
 import { Comment } from "snoowrap/dist/objects";
-import SimpleError from "../Utils/SimpleError";
 import as from "async";
+import {SimpleError} from "../Utils/Errors";
 
 
 export interface AttributionCriteria {
@@ -222,9 +222,11 @@ export class AttributionRule extends Rule {
 
             activities = await as.filter(activities, async (activity) => {
                 if (asSubmission(activity) && submissionState !== undefined) {
-                    return await this.resources.testItemCriteria(activity, [submissionState]);
+                    const {passed} = await this.resources.testItemCriteria(activity, submissionState, this.logger);
+                    return passed;
                 } else if (commentState !== undefined) {
-                    return await this.resources.testItemCriteria(activity, [commentState]);
+                    const {passed} = await this.resources.testItemCriteria(activity, commentState, this.logger);
+                    return passed;
                 }
                 return true;
             });