Merge branch 'develop' of https://github.com/stdlib-js/stdlib into develop

Author: kgryte

.github/workflows/run_tests_coverage.yml

@@ -147,6 +147,10 @@
 
         # Run JavaScript tests:
         - name: 'Run JavaScript tests'
+          id: extract-coverage
+          env:
+            GITHUB_REPO: ${{ github.repository }}
+            GITHUB_REF: ${{ github.ref }}
           run: |
             if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
               directories="${{ steps.changed-directories-user-input.outputs.directories }}"
@@ -156,38 +160,16 @@
             . "$GITHUB_WORKSPACE/.github/workflows/scripts/run_tests_coverage" "$directories"
           timeout-minutes: 30
 
-        # Extract coverage values and assign to output:
-        - name: 'Extract coverage values and assign to output'
-          id: extract-coverage
+        # Create final coverage report:
+        - name: 'Create final coverage report'
+          id: create-report
           run: |
-            if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
-              directories="${{ steps.changed-directories-user-input.outputs.directories }}"
-            else
-              directories="${{ steps.changed-directories.outputs.directories }}"
-            fi
-            directories=$(echo "${directories}" | tr ' ' '\n' | grep '^lib/node_modules/@stdlib') || true
-            directories=$(echo "${directories}" | tr ' ' '\n' | sed -E 's/\/(benchmark|bin|data|docs|etc|examples|include|lib|src|test)(\/.*)?$//')
-            directories=$(echo "${directories}" | uniq)
-
-            # For each package, extract coverage value from the respective coverage report:
-            coverage=''
-            for package in $directories; do
-              pkg=`echo $package | sed -E 's/^.*stdlib\///'`
-              pkg_cov=`cat reports/coverage/lcov-report/$pkg/lib/index.html | grep "fraction" | grep -oP '\d+/\d+' | printf %s "$(cat)" | jq -R -s -c 'split("\n")'`
-              pkg_url="https://github.com/${{ github.repository }}/tree/${{ github.ref }}/$package"
-              pkg_link="<a href="$pkg_url">$pkg</a>"
-              coverage="$coverage\n| $pkg_link $pkg_cov"
-            done
-
-            # Format coverage as Markdown table row:
-            table_body=`echo $coverage | sed -e 's/,/|/g; s/"/ /g; s/\[/|/g; s/\]/|/g'`
-            table_header="| Package | Statements | Branches | Functions | Lines |\n| --------- | ------------ | ---------- | ----------- | ----- |"
-            table="${table_header}${table_body}"
+            table="${{ steps.extract-coverage.outputs.table }}"
 
             if [ "${{ github.event_name }}" == "pull_request" ]; then
               compare_url="https://github.com/stdlib-js/stdlib/compare/${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}"
               compare_txt="The above coverage report was generated for the [changes in this PR]($compare_url)."
-            else if [ "${{ github.event_name }}" == "push" ]; then
+            elif [ "${{ github.event_name }}" == "push" ]; then
               compare_url="https://github.com/stdlib-js/stdlib/compare/${{ github.event.before }}...${{ github.event.after }}"
               compare_txt="The above coverage report was generated for the [changes in this push]($compare_url)."
             else
@@ -208,7 +190,7 @@
                 issue_number: context.issue.number,
                 owner: context.repo.owner,
                 repo: context.repo.repo,
-                body: '${{ steps.extract-coverage.outputs.report }}'
+                body: '${{ steps.create-report.outputs.report }}'
               })
 
         # Post report as comment to commit:
@@ -222,5 +204,43 @@
                 commit_sha: context.sha,
                 owner: context.repo.owner,
                 repo: context.repo.repo,
-                body: '${{ steps.extract-coverage.outputs.report }}'
+                body: '${{ steps.create-report.outputs.report }}'
               })
+
+        # Checkout coverage repository:
+        - name: 'Checkout coverage repository'
+          uses: actions/checkout@v3
+          with:
+            # Code coverage repository:
+            repository: 'stdlib-js/www-test-code-coverage'
+
+            # File path to checkout to:
+            path: './www-test-code-coverage'
+
+            # Specify whether to remove untracked files before checking out the repository:
+            clean: false
+
+            # Limit clone depth to the most recent commit:
+            fetch-depth: 1
+
+            # Token for accessing the repository:
+            token: ${{ secrets.REPO_GITHUB_TOKEN }}
+
+        # Copy artifacts to the repository:
+        - name: 'Copy artifacts to the repository'
+          run: |
+              cp -R ./artifacts/* ./www-test-code-coverage
+
+        # Commit and push changes:
+        - name: 'Commit and push changes'
+          env:
+            REPO_GITHUB_TOKEN: ${{ secrets.REPO_GITHUB_TOKEN }}
+            USER_NAME: stdlib-bot
+          run: |
+            cd ./www-test-code-coverage
+            git add .
+            git config --local user.email "noreply@stdlib.io"
+            git config --local user.name "stdlib-bot"
+            git commit -m "Update artifacts"
+            git push "https://$USER_NAME:$REPO_GITHUB_TOKEN@github.com/stdlib-js/www-test-code-coverage.git" main
+

.github/workflows/scripts/run_tests_coverage

@@ -29,6 +29,8 @@
 #
 # Environment variables:
 #
+#   GITHUB_REPO    GitHub repository.
+#   GITHUB_REF     GitHub branch or tag.
 #   LOG_FILE       Log file.
 #
 
@@ -43,6 +45,12 @@ set -o pipefail
 # Get the list of changed files:
 changed="$*"
 
+# Get the GitHub repository:
+github_repo="${GITHUB_REPO}"
+
+# Get the GitHub branch or tag:
+github_ref="${GITHUB_REF}"
+
 # Get the path to a log file as the third argument to the build script:
 log_file="${LOG_FILE}"
 
@@ -104,6 +112,31 @@ print_success() {
 	echo 'Success!' >&2
 }
 
+# Calculates the percentage change in code coverage and prints a formatted string.
+#
+# $1 - previous coverage value as a decimal (e.g., 0.85 for 85% coverage)
+# $2 - new coverage value as a decimal
+compare_cov() {
+	old_cov_value="$1"
+	new_cov_value="$2"
+
+	if [ "$old_cov_value" == 0 ]; then
+		new_cov_percentage=$(awk "BEGIN {printf \"%.1f\", $new_cov_value*100}")
+		echo "\$\\\\color{green}+$new_cov_percentage\\\\%\$"
+	else
+		percentage_change=$(awk "BEGIN {printf \"%.1f\", (($new_cov_value - $old_cov_value) / $old_cov_value) * 100}")
+		color="green"
+		sign=""
+		if [ $(awk "BEGIN {if ($percentage_change > 0) print 1; else print 0}") -eq 1 ]; then
+			sign="+"
+		elif [ $(awk "BEGIN {if ($percentage_change < 0) print 1; else print 0}") -eq 1 ]; then
+			sign="-"
+			color="red"
+		fi
+		echo "\$\\\\color{$color}$sign$percentage_change\\\\%\$"
+	fi
+}
+
 # Main execution sequence.
 main() {
 	start_heartbeat "${heartbeat_interval}"
@@ -121,15 +154,62 @@ main() {
 		exit 0
 	fi
 
-	# Find all test files in package directories:
-	files=$(find ${directories} -maxdepth 2 -wholename '**/test/test*.js' | grep -v '/fixtures/' | sort -u | tr '\n' ' ') || true
+	mkdir -p artifacts
+	coverage=''
+	for package in ${directories}; do
+		make test-javascript-cov TESTS_FILTER=".*/${package}/.*"
+
+		# For each package, extract coverage values from the respective coverage report:
+		pkg=`echo $package | sed -E 's/^.*stdlib\///'`
+		pkg_cov_values=($(cat reports/coverage/lcov-report/$pkg/lib/index.html | grep "fraction" | grep -oP '\d+/\d+' | awk -F'/' '{print $1/$2}'))
+		pkg_statements_cov=${pkg_cov_values[0]}
+		pkg_branches_cov=${pkg_cov_values[1]}
+		pkg_functions_cov=${pkg_cov_values[2]}
+		pkg_lines_cov=${pkg_cov_values[3]}
+
+		pkg_cov_fractions=($(cat reports/coverage/lcov-report/$pkg/lib/index.html | grep "fraction" | grep -oP '\d+/\d+' | awk -F'/' '{if ($1<$2) print "$\\\\color{red}" $0 "$"; else print "$\\\\color{green}" $0 "$"}'))
+		pkg_statements_cov_fraction=${pkg_cov_fractions[0]}
+		pkg_branches_cov_fraction=${pkg_cov_fractions[1]}
+		pkg_functions_cov_fraction=${pkg_cov_fractions[2]}
+		pkg_lines_cov_fraction=${pkg_cov_fractions[3]}
+
+		old_cov_report=$(curl -s --fail "https://coverage.stdlib.io/${pkg}/lib/index.html" 2>/dev/null)
+		status=$?
+		if [ $status -ne 0 ]; then
+			old_statements_cov=0
+			old_branches_cov=0
+			old_functions_cov=0
+			old_lines_cov=0
+		else
+			old_cov_values=$(echo "$old_cov_report" | grep "fraction" | grep -oP '\d+/\d+' | awk -F'/' '{print $1/$2}')
+			old_statements_cov=${old_cov_values[0]}
+			old_branches_cov=${old_cov_values[1]}
+			old_functions_cov=${old_cov_values[2]}
+			old_lines_cov=${old_cov_values[3]}
+		fi
+
+		cov_change_statements=$(compare_cov "$old_statements_cov" "$pkg_statements_cov")
+		cov_change_branches=$(compare_cov "$old_branches_cov" "$pkg_branches_cov")
+		cov_change_functions=$(compare_cov "$old_functions_cov" "$pkg_functions_cov")
+		cov_change_lines=$(compare_cov "$old_lines_cov" "$pkg_lines_cov")
+
+		echo $pkg_statements_cov_fraction
+		pkg_cov="| $pkg_statements_cov_fraction (Δ $cov_change_statements) | $pkg_branches_cov_fraction (Δ $cov_change_branches) | $pkg_functions_cov_fraction (Δ $cov_change_functions) | $pkg_lines_cov_fraction (Δ $cov_change_lines) |"
+
+		pkg_url="https://github.com/${github_repo}/tree/${github_ref}/${package}"
+		pkg_link="<a href="$pkg_url">$pkg</a>"
+		coverage="$coverage\n| $pkg_link $pkg_cov"
+
+		# Copy coverage report of the package to artifacts directory:
+		mkdir -p "artifacts/${pkg}" && cp -r "reports/coverage/lcov-report/${pkg}"/* "artifacts/${pkg}/"
+	done
 
-	# Exclude files residing in test fixtures directories:
-	files=$(echo "${files}" | grep -v '/fixtures/') || true
+	# Format coverage as Markdown table row:
+	table_body=`echo $coverage | sed -e 's/,/|/g; s/"/ /g; s/\[/|/g; s/\]/|/g'`
+	table_header="| Package | Statements | Branches | Functions | Lines |\n| --------- | ------------ | ---------- | ----------- | ----- |"
+	table="${table_header}${table_body}"
 
-	if [[ -n "${files}" ]]; then
-		make test-javascript-cov-files FILES="${files}"
-	fi
+	echo "table=$table" >> $GITHUB_OUTPUT
 
 	cleanup
 	print_success

etc/eslint/rules/stdlib.js

@@ -3993,7 +3993,7 @@ rules[ 'stdlib/new-cap-regexp' ] = 'error';
 rules[ 'stdlib/no-dynamic-require' ] = 'error';
 
 /**
-* Require that comments are not empty.
+* Disallow empty comments.
 *
 * @name no-empty-comments
 * @memberof rules

lib/node_modules/@stdlib/_tools/bundle/pkg-list/lib/setdiff.js

@@ -39,7 +39,6 @@ var debug = logger( 'bundle-pkg-list:setdiff' );
 *
 * -   We assume that `A` is a list of namespaces and `B` is a list of packages. We exclude all namespaces from the output array, _except_ those that have aliases in the global alias namespace.
 *
-*
 * @private
 * @param {Array} A - first set
 * @param {Array} B - second set

lib/node_modules/@stdlib/_tools/bundle/pkg-list/lib/tree_filter.js

@@ -42,7 +42,6 @@ var debug = logger( 'bundle-pkg-list:tree-filter' );
 * -   If namespace packages with listed children were allowed, we would end up trying to override namespace properties which are read-only. So, our stance is that, if you want a namespace, you should provide a namespace only. And if you only want certain children, then provide the children, but not the namespace. Providing both signals confusion.
 * -   The one exception we allow is when a namespace has an alias in the global alias namespace, which indicates that a package is not a "traditional" namespace, possibly providing a function API to namespace packages (e.g., `@stdlib/datasets`).
 *
-*
 * @private
 * @param {StringArray} pkgs - list of packages (unique and sorted lexicographically)
 * @returns {StringArray} filtered list
@@ -55,7 +54,7 @@ var debug = logger( 'bundle-pkg-list:tree-filter' );
 * ];
 *
 * var out = filter( pkgs );
-* // returns [ '@stdlib/random/base', '@stdlib/math/base/special/erf' ]
+* // returns [ '@stdlib/math/base', '@stdlib/random/base', '@stdlib/math/base/special/erf' ]
 */
 function filter( pkgs ) {
 	var out;

lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-fenced-code-flag/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@stdlib/_tools/eslint/rules/jsdoc-fenced-code-marker",
+  "name": "@stdlib/_tools/eslint/rules/jsdoc-fenced-code-flag",
   "version": "0.0.0",
   "description": "ESLint rule to enforce fenced Markdown code blocks to have a language flag in JSDoc descriptions.",
   "license": "Apache-2.0",

lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-main-export/lib/main.js

@@ -69,6 +69,9 @@ function main( context ) {
 	// Get the part starting with `@stdlib`, shift by one to avoid leading `@`:
 	modulePath = modulePath.substr( modulePath.indexOf( '@stdlib' )+1 );
 
+	// Replace Windows path separators with POSIX path separators (if present):
+	modulePath = replace( modulePath, '\\', '/' );
+
 	activate = false;
 	ending = '/lib/index.js';
 	if ( endsWith( modulePath, ending ) && !contains( source.text, '@namespace' ) ) {
@@ -100,7 +103,15 @@ function main( context ) {
 	* @param {Object} loc - lines of code (object with `start` and `end` properties)
 	*/
 	function checkExample( tag, loc ) {
-		if ( !RE_REQUIRE.test( tag.description ) ) {
+		var match;
+
+		match = RE_REQUIRE.exec( tag.description );
+		if ( match ) {
+			// The main export should be required last, so no `require` calls should follow:
+			if ( match.index !== tag.description.lastIndexOf( 'require' ) ) {
+				report( 'Example code of main export should require itself last, i.e. contain `require( \'@'+modulePath+'\' )` as the last `require` call', loc );
+			}
+		} else {
 			report( 'Example code of main export should require itself, i.e. contain `require( \'@'+modulePath+'\' )`', loc );
 		}
 	}

lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-main-export/test/fixtures/invalid.js

@@ -48,6 +48,35 @@ test = {
 };
 invalid.push( test );
 
+test = {
+	'code': [
+		'/**',
+		'* Test if a value is an array.',
+		'*',
+		'* @module @stdlib/assert/is-array',
+		'*',
+		'* @example',
+		'* var isArray = require( \'@stdlib/assert/is-array\' );',
+		'* var filled = require( \'@stdlib/array/filled\' );',
+		'*',
+		'* var arr = filled( 0, 10 );',
+		'* var bool = isArray( arr );',
+		'* // returns true',
+		'*',
+		'* bool = isArray( {} );',
+		'* // returns false',
+		'*/'
+	].join( '\n' ),
+	'filename': '/path/to/@stdlib/assert/is-array/lib/index.js',
+	'errors': [
+		{
+			'message': 'Example code of main export should require itself last, i.e. contain `require( \'@stdlib/assert/is-array\' )` as the last `require` call',
+			'type': null
+		}
+	]
+};
+invalid.push( test );
+
 test = {
 	'code': [
 		'/**',

lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-main-export/test/fixtures/valid.js

@@ -42,6 +42,29 @@ test = {
 };
 valid.push( test );
 
+test = {
+	'code': [
+		'/**',
+		'* Test if a value is an array.',
+		'*',
+		'* @module @stdlib/assert/is-array',
+		'*',
+		'* @example',
+		'* var filled = require( \'@stdlib/array/filled\' );',
+		'* var isArray = require( \'@stdlib/assert/is-array\' );',
+		'*',
+		'* var arr = filled( 0, 10 );',
+		'* var bool = isArray( arr );',
+		'* // returns true',
+		'*',
+		'* bool = isArray( {} );',
+		'* // returns false',
+		'*/'
+	].join( '\n' ),
+	'filename': '/path/to/@stdlib/assert/is-array/lib/index.js'
+};
+valid.push( test );
+
 test = {
 	'code': [
 		'/**',

lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-space-aligned-asterisks/README.md

@@ -20,7 +20,7 @@ limitations under the License.
 
 # No Space-Aligned Asterisks
 
-> [ESLint rule][eslint-rules] to prevent prevent space-aligned asterisks for JSDoc comments.
+> [ESLint rule][eslint-rules] to disallow space-aligned asterisks for JSDoc comments.
 
 <section class="intro">
 
@@ -38,7 +38,7 @@ var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-no-space-aligned-asterisk
 
 #### rule
 
-[ESLint rule][eslint-rules] to prevent space-aligned asterisks for JSDoc comments.
+[ESLint rule][eslint-rules] to disallow space-aligned asterisks for JSDoc comments.
 
 **Bad**:
 

lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-space-aligned-asterisks/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stdlib/_tools/eslint/rules/jsdoc-no-space-aligned-asterisks",
   "version": "0.0.0",
-  "description": "ESLint rule to prevent space-aligned asterisks for JSDoc comments.",
+  "description": "ESLint rule to disallow space-aligned asterisks for JSDoc comments.",
   "license": "Apache-2.0",
   "author": {
     "name": "The Stdlib Authors",