Merge pull request #406 from linear-b/is-gitstream-user

Create isFlaggedUser plugin and new publishing materials for gitStream plugins.

docs/custom-filters.md

@@ -144,3 +144,48 @@ gitStream supports the following JavaScript dependencies:
 5. octokit rest api (@octokit/rest)
 
 No other dependencies are supported at this time. If you have recommendations for new dependencies, please open a new issue on the [gitStream GitHub repo](https://github.com/linear-b/gitstream).
+
+### How to Publish Custom Filters on the gitStream Docs
+
+Create a directory for your plugin inside one of the subdirectories in `plugins/filters`. The name of the directory must match the name of the exported JavaScript function. Then ensure you have all of the required files and JSDoc content outlined below.
+
+Required Files:
+
+* index.js - The entry point for your plugin. This should have a main function that is exported via `module.exports` that is documented according to the JSDoc requirements outlined below.
+* README.md - Use this [template](https://github.com/linear-b/gitstream/tree/main/docs/templates/filter-readme-template.md).
+* reference.md - This file must be auto-generated by `jsdoc2md`, see the instructions below.
+* plugin_name.cm - A gitStream CM example that uses the plugin.
+* LICENSE - The full text of the open source license the code is provided under.
+
+Required JSDoc tags:
+* `@module` - This must match the name of the exported JavaScript function.
+* `@description` - A 1-2 line description that wholistically describes the functionality of the plugin.
+* `@param` - There should be one `@param` tag for each argument the plugin accepts, with indicated types. Indicate which parameter is the default input parameter with the name "Input."
+* `@returns` - Provide the type and a short description.
+* `@example` - Simple examples that show how to invoke the plugin.
+* `@license` - The name of the lincense contained in the LICENSE file. 
+
+Here is an example of properly formatted JSDoc content:
+```
+/**
+ *  * @module isFlaggedUser
+ * @description Returns true if the username that is passed to this function is specified in a predefined list of users. 
+ * This is useful if you want gitStream automations to run only for specified users.
+ * @param {string} Input - The GitHub username to check.
+ * @returns {boolean} Returns true if the user is specified in the flaggedUsers list, otherwise false.
+ * @example {{ pr.author | isFlaggedUser }}
+ * @license MIT
+ */
+ ```
+
+#### How to Generate Plugin Reference Markdown
+
+You can use jsdoc2md to convert the JSDoc content of your plugin to markdown using templates we've provided. First install jsdoc2md: 
+
+```npm install -g jsdoc-to-markdown```
+
+Then, invoke the following command from inside your plugin directory:
+
+`jsdoc2md --partial ../../../docs/snippets/partials/body.hbs --partial ../../../docs/snippets/partials/sig-name.hbs --files index.js > reference.md`
+
+This should output a reference.md file that contains properly formatted markdown based on the JSDoc contents of your plugin.

docs/plugins.md

@@ -0,0 +1,10 @@
+---
+title: gitStream Plugins
+description: Implement custom gitStream filter functions with JavaScript.
+---
+
+JavaScript plugins that enable custom filter functions for gitStream. To learn how to use these examples, read our [guide on how to use gitStream plugins](/custom-filters).
+
+--8<-- "plugins/filters/isFlaggedUser/README.md"
+
+---

docs/snippets/partials/body.hbs

@@ -0,0 +1,28 @@
+{{>deprecated~}}
+{{>description~}}
+{{>summary~}}
+{{>augments~}}
+{{>implements~}}
+{{>mixes~}}
+{{>default~}}
+{{>chainable~}}
+{{>overrides~}}
+{{>returns~}}
+{{>category~}}
+{{>throws~}}
+{{>fires~}}
+{{>this~}}
+{{>access~}}
+{{>readOnly~}}
+{{>requires~}}
+{{>customTags~}}
+{{>see~}}
+{{>since~}}
+{{>version~}}
+{{>authors~}}
+{{>license~}}
+{{>copyright~}}
+{{>todo~}}
+{{>params~}}
+{{>properties~}}
+{{>examples~}}

docs/snippets/partials/sig-name.hbs

@@ -0,0 +1,13 @@
+{{#if virtual}}*{{/if}}{{#with (parentObject)}}{{#if virtual}}*{{/if~}}{{/with~}}
+{{#if name}}{{#sig~}}
+{{{@depOpen}~}}
+{{{@codeOpen}~}}
+{{#if @prefix}}{{@prefix}} {{/if~}}
+{{@parent~}}
+{{@accessSymbol}}{{#if (isEvent)}}"{{{name}}}"{{else}}{{{escape name}}}{{/if~}}
+{{#if @methodSign}}{{#if (isEvent)}} {{@methodSign}}{{else}}{{@methodSign}}{{/if}}{{/if~}}
+{{{@codeClose}~}}
+{{#if @suffix}} {{@suffix}}{{/if~}}
+{{{@depClose}~}}
+{{~/sig}}{{/if~}}
+{{#if virtual}}*{{/if}}{{#with (parentObject)}}{{#if virtual}}*{{/if~}}{{/with~}}

docs/templates/filter-readme-template.md

@@ -0,0 +1,45 @@
+---
+title: gitStream Plugin - filterName
+description: Indicate if a user is included in a specified list.
+---
+<!--
+This is a template file for a gitStream plugin README.md files
+
+In a nutshell, the custom filter pages are published under /docs/plugins, and all associated content and examples are imported via associated files inside that directory.
+
+How to use this template.
+
+1. Create a README.md file inside the plugin's directory and copy/paste the content of this file into it.
+1. Find a replace the strings below with the appropriate information
+
+
+Here are the strings to replace
+
+- docs/plugins/filters/standard/filterName/ - change this to match the directory of the plugin. This should match the function exported in the plugin's index.js
+- filterName - This should match the function exported in the plugin's index.js 
+- filter_name - This should match the name of CM example file that is included with the plugin.
+-->
+
+
+--8<-- "docs/plugins/filters/standard/filterName/reference.md"
+
+??? note "Plugin Code: filterName"
+    ```javascript
+    --8<-- "docs/plugins/filters/standard/filterName/index.js"
+    ```
+    <div class="result" markdown>
+    <span>
+    </span>
+    </div>
+
+
+??? example "gitStream CM Example: filterName"
+    ```yaml+jinja
+    --8<-- "docs/plugins/filters/standard/filterName/filter_name.cm"
+    ```
+    <div class="result" markdown>
+    <span>
+    </span>
+    </div>
+
+[Download Source Code](https://github.com/linear-b/gitstream/tree/main/docs/plugins/filters/standard/filterName)

mkdocs.yml

@@ -102,3 +102,5 @@ extra:
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/linear-b/gitstream/
+watch:
+  - plugins

plugins/filters/isFlaggedUser/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 LinearB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plugins/filters/isFlaggedUser/README.md

@@ -0,0 +1,22 @@
+--8<-- "plugins/filters/isFlaggedUser/reference.md"
+
+??? note "Plugin Code: isFlaggedUser"
+    ```javascript
+    --8<-- "plugins/filters/isFlaggedUser/index.js"
+    ```
+    <div class="result" markdown>
+    <span>
+    </span>
+    </div>
+
+
+??? example "gitStream CM Example: isFlaggedUser"
+    ```yaml+jinja
+    --8<-- "plugins/filters/isFlaggedUser/is_flagged_user.cm"
+    ```
+    <div class="result" markdown>
+    <span>
+    </span>
+    </div>
+
+[Download Source Code](https://github.com/linear-b/gitstream/tree/main/plugins/filters/isFlaggedUser)

plugins/filters/isFlaggedUser/index.js

@@ -0,0 +1,24 @@
+// Add users who you want to add to the flag list.
+const flaggedUsers = ["user1", "user2"];
+/**
+ * @description Returns true if the username that is passed to this function is specified in a predefined list of users. 
+ * This is useful if you want gitStream automations to run only for specified users.
+ * @module isFlaggedUser
+ * @param {string} Input - The GitHub username to check.
+ * @returns {boolean} Returns true if the user is specified in the flaggedUsers list, otherwise false.
+ * @example {{ pr.author | isFlaggedUser }}
+ * @license MIT
+ */
+function isFlaggedUser(username) {
+    if (containsString(flaggedUsers, username)) {
+        return true;
+    } else {
+        return false;
+    }
+};
+
+function containsString(arr, str) {
+    return arr.includes(str);
+};
+
+module.exports = isFlaggedUser;

plugins/filters/isFlaggedUser/is_flagged_user.cm

@@ -0,0 +1,13 @@
+# -*- mode: yaml -*-
+
+manifest:
+  version: 1.0
+
+automations:
+  detect_flagged_user:
+    if:
+      - {{ pr.author | isFlaggedUser }}
+    run:
+      - action: add-comment@v1
+        args:
+          comment: {{ pr.author }} is a gitStream user.

plugins/filters/isFlaggedUser/reference.md

@@ -0,0 +1,17 @@
+<a name="module_isFlaggedUser"></a>
+
+## isFlaggedUser
+Returns true if the username that is passed to this function is specified in a predefined list of users. 
+This is useful if you want gitStream automations to run only for specified users.
+
+**Returns**: <code>boolean</code> - Returns true if the user is specified in the flaggedUsers list, otherwise false.  
+**License**: MIT  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| Input | <code>string</code> | The GitHub username to check. |
+
+**Example**  
+```js
+{{ pr.author | isFlaggedUser }}
+```