Summarize unit tests

docs/automations/automation-library.md

@@ -32,6 +32,7 @@ This library of gitStream examples is meant to serve as a starting point for you
 * [Label missing project tracker](label-missing-project-tracker/README.md) - Flag PRs that are missing a reference to an associated project tracking resource.
 * [Automatic project tracking links](standard/link-issue-tracker/README.md) - Automatically post PR comments that link to the associated project tracking resource (Jira, Shortcut, Azure Boards, and more).
 * [Summarize PR contents by language](standard/summarize-language-changes/README.md) - Post a comment that breaks down code changes by the programming languages contained in the PR.
+* [Summarize unit tests](summarize-unit-tests/README.md) - Post a comment that summarizes the updates to unit tests.
 
 ## Improve PR Quality
 ### Merge Routing

docs/automations/summarize-unit-tests/README.md

@@ -0,0 +1,40 @@
+---
+title: Automation - Summarize Unit Tests
+description: Post a comment that summarizes the updates to unit tests.
+---
+
+# Summarize Unit Tests
+
+<!-- --8<-- [start:example]-->
+Post a comment that summarizes the updates to unit tests.
+
+<div class="automationImage" markdown="1">
+![Summarize Unit Tests](/automations/standard/summarize-unit-tests/summarize-unit-tests.png)
+</div>
+<div class="automationDescription" markdown="1">
+!!! info "Configuration Description"
+    There are no conditions for this action - if included as presented in the demo, it's run every time.
+
+    Automation Actions:
+
+    * Post a comment that summarizes the updates to unit tests.
+
+</div>
+<div class="automationExample" markdown="1">
+!!! example "Summarize Unit Tests"
+    ```yaml+jinja
+    --8<-- "docs/downloads/automation-library/summarize_unit_tests.cm"
+    ```
+    <div class="result" markdown>
+      <span>
+      [:octicons-download-24: Download this example as a CM file.](/downloads/automation-library/summarize_unit_tests.cm){ .md-button }
+      </span>
+    </div>
+</div>
+<!-- --8<-- [end:example]-->
+
+## Additional Resources
+
+--8<-- "docs/snippets/general.md"
+
+--8<-- "docs/snippets/automation-footer.md"

docs/downloads/automation-library/summarize_unit_tests.cm

@@ -0,0 +1,13 @@
+# -*- mode: yaml -*-
+
+manifest:
+  version: 1.0
+
+automations:
+  summarize_unit_tests: 
+    if:
+      - {{ true }}
+    run:
+      - action: add-comment@v1
+        args:
+          comment: {{ source.diff.files | summarizeUnitTests(testsDirectory="/tests", testsExtension=".test.js", fileTypes=[".js"]) }}

docs/filter-function-plugins.md

@@ -20,4 +20,6 @@ JavaScript plugins that enable custom filter functions for gitStream. To learn h
 
 --8<-- "plugins/filters/isFlaggedUser/README.md"
 
+--8<-- "plugins/filters/summarizeUnitTests/README.md"
+
 ---

plugins/filters/summarizeUnitTests/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 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/summarizeUnitTests/README.md

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

plugins/filters/summarizeUnitTests/index.js

@@ -0,0 +1,100 @@
+/*
+- @module summarizeUnitTests
+- @description Provide a summary of the unit tests contained in a PR.
+- This is useful if you want gitStream to post summary comments.
+- @param {Object} Input - Accepts the output of source.diff.files
+- @param {String} testsDirectory - The directory that contains unit tests
+- @param {String} testsExtension - The extension used by the unit test framework.
+- @param {List[String]} fileTypes - A list of file types to check for tests.
+- @returns {string} - A summary of the unit tests in markdown format
+- @example {{ source.diff.files | summarizeUnitTests(testsDirectory=testsDirectory, testsExtension=testsExtension, requiredTestExtension=".js" ) }}
+- @license MIT
+*/
+
+const commentLine = (filename, content) => `<details>
+<summary>${filename}</summary>
+
+\`\`\`
+${content}
+\`\`\`
+</details>`;
+
+const summarizeUnitTests = async (files, keywords, callback) => {
+	let affectedFilesComment = "";
+	let testFinderComment = "";
+
+	const affectedFiles = files.filter(file => 
+		file.original_file.startsWith(keywords.testsDirectory)
+		|| file.new_file.startsWith(keywords.testsDirectory)
+		|| file.original_file.endsWith(keywords.testsExtension)
+		|| file.new_file.endsWith(keywords.testsExtension)
+	);
+	if (affectedFiles.length != 0) {
+		let testFileLines = {
+			New: [],
+			Updated: [],
+			Renamed: []
+		};
+		affectedFiles.forEach(file => {
+			const line = commentLine(file.new_file, file.new_content);
+			if (file.new_file == file.original_file) testFileLines.Updated.push(line);
+			else if (!file.original_file) testFileLines.New.push(line);
+			else testFileLines.Renamed.push(line);
+		});
+
+		affectedFilesComment = `## Changes to tests
+Below are all the changes that this PR made to identifiable tests.
+
+${
+	Object
+		.entries(testFileLines)
+		.map(([type, arr]) => arr.length
+			? [`### ${type} Tests - ${arr.length}`, ...arr].join("\n\n")
+			: ""
+		)
+		.filter(section => !!section) // filter out empty sections
+		.join("\n\n\n")
+}`;
+
+	}
+
+	if (Array.isArray(keywords.fileTypes) && !!keywords.fileTypes.length && !!keywords.testsExtension) {
+		let needTestFiles = {};
+		files.forEach(file => {
+			keywords.fileTypes.forEach(ext => {
+				if (file.new_file.endsWith(ext)) {
+					needTestFiles[ext] = !needTestFiles[ext] 
+						? [file.new_file] 
+						: [...needTestFiles[ext], file.new_file];
+				}
+			});
+		});
+
+		const newFilePaths = files.map(file => file.new_file);
+		testFinderComment = [
+			`## Files modified by this PR with extension in ${JSON.stringify(keywords.fileTypes)}`,
+			...(
+				Object
+					.entries(needTestFiles)
+					.map(([ext, path]) => {
+						const testPath = path.slice(0, path.lastIndexOf(ext)) + keywords.testsExtension;
+						return newFilePaths.includes(testPath)
+							? `- ${path} -> test found at ${testPath} was modified or added by this PR`
+							: `- ${path} -> no matching test was modified by this PR`
+					})
+			)
+		].join("\n");
+	}
+
+	const comment = [affectedFilesComment, testFinderComment].filter(x => !!x).join("\n\n\n");
+	if (!comment) return callback(null, ""); // no tests have been added or modified
+	else return callback(
+		null, 
+		JSON.stringify(comment)
+	);
+};
+
+module.exports = {
+	async: true,
+	filter: summarizeUnitTests
+}

plugins/filters/summarizeUnitTests/reference.md

@@ -0,0 +1,30 @@
+<a name="module_checklist"></a>
+
+## summarizeUnitTests
+
+Generate a comment that summarizes the updates to unit tests. The comment includes:
+
+- Total number of new test files and updates to existing test files (discovered with <code>testsDirectory</code> and <code>testsExtension</code>)
+- A list of the new test files with an expandable box containing the complete code (discovered with <code>testsDirectory</code> and <code>testsExtension</code>)
+- A list of updated code files in the PR with indicators to show if there is a corresponding unit test (discovered with <code>fileTypes</code> and <code>testsExtension</code>)
+
+**Returns**: <code>string</code> - Returns a formatted GitHub comment with information about updated code and test files.  
+**License**: MIT  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| files | <code>object</code> | The files context variable. |
+| keywords | <code>object</code> | An object containing the optional keys <code>testsDirectory</code> (the filepath of the directory where the tests are stored, as a string) and/or <code>testsExtension</code> (the extension of the test files specifically, as a string) and/or <code>fileTypes</code> (an array of the file extensions as strings that are monitored for changes) |
+
+Notes:
+
+- The file extensions are compared against each changed filepath with the JavaScript function <code>String.endsWith()</code>, so how much of the extension you provide and whether you include the dot before the extension is up to you.
+- If you include the <code>fileTypes</code> array to find all the files with those extensions that need tests, you need to include <code>testsExtension</code> for the function to determine what the corresponding test file would be and see if it exists.
+
+
+**Example**  
+```js
+- action: add-comment@v1
+        args:
+        	comment: {{ "" | checklist(branch, files, pr, repo, env, source) }}
+```