refactor: address PR feedback

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: passed
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: na
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: na
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

Author: Planeshifter

lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-doctest/README.md

@@ -38,7 +38,7 @@ var rule = require( '@stdlib/_tools/eslint/rules/tsdoc-doctest' );
 
 #### rule
 
-[ESLint rule][eslint-rules] to ensure that return annotations in TSDoc examples match the actual output. The rule validates `@example` blocks in TSDoc comments within `.d.ts` files.
+[ESLint rule][eslint-rules] to ensure that return annotations in TSDoc examples match the actual output. Return annotations may start with `returns`, `throws`, or `=>`. `returns` follow variable declarations or assignment expressions, whereas `=>` follow expression-only forms including `console.log` calls. The rule validates `@example` blocks in TSDoc comments within `.d.ts` files by automatically resolving the corresponding implementation via the nearest `package.json` file.
 
 **Bad**:
 
@@ -129,7 +129,7 @@ var result = linter.verify( code, {
         'tsdoc-doctest': 'error'
     }
 }, {
-    'filename': 'lib/node_modules/@stdlib/math/base/special/abs/docs/types/index.d.ts'
+    'filename': '/path/to/project/lib/node_modules/@stdlib/math/base/special/abs/docs/types/index.d.ts'
 });
 /* returns
     [
@@ -155,11 +155,9 @@ var result = linter.verify( code, {
 
 ## Notes
 
--   The corresponding JavaScript package must be loadable via `require('@stdlib/<package>')`
--   The rule skips validation if the package cannot be loaded.
--   Examples are executed in a sandboxed VM context with limited globals.
--   The rule validates assignment-form examples (e.g., `var x = fn(...);` followed by an annotation). It does not validate console output or expression-only forms using `// =>`.
--   The implementation path the rule uses to load the JavaScript implementation can be overridden via the `implementationPath` rule option (default: `../../lib` relative to the declaration file).
+-   The rule automatically resolves the implementation path by traversing up the directory tree to find the nearest `package.json` file and using its `main` field.
+-   The rule skips validation if the `package.json` file cannot be found or if the resolved implementation cannot be loaded.
+-   Examples are executed in a sandboxed VM context with limited globals for security.
 
 </section>
 

lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-doctest/lib/add_package_to_scope.js

@@ -21,65 +21,83 @@
 // VARIABLES //
 
 // Regular expressions for matching TypeScript declarations:
+
+/**
+* Regular expression to match function declarations like "declare function abs( x: number ): number;" (captures function name).
+*
+* @type {RegExp}
+*/
 var RE_DECLARE_FUNCTION = /declare\s+function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*[<(]/;
+
+/**
+* Regular expression to match variable declarations like "declare var someVar: SomeType;" (captures variable name).
+*
+* @type {RegExp}
+*/
 var RE_DECLARE_VAR = /declare\s+var\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:/;
+
+/**
+* Regular expression to match class declarations like "declare class Complex64Array {" (captures class name).
+*
+* @type {RegExp}
+*/
 var RE_DECLARE_CLASS = /declare\s+class\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s/;
-var RE_DECLARE_VAR_NAMESPACE = /declare\s+var\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:\s*[A-Z][a-zA-Z0-9_$]*/;
+
+/**
+* Regular expression to match const declarations like "declare const PI: number;" (captures constant name).
+*
+* @type {RegExp}
+*/
 var RE_DECLARE_CONST = /declare\s+const\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:/;
+
+/**
+* Regular expression to match variable declarations with interface types like "declare var ctor: Int32Vector;" (captures variable name and interface name).
+*
+* @type {RegExp}
+*/
 var RE_DECLARE_VAR_INTERFACE = /declare\s+var\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:\s*([A-Z][a-zA-Z0-9_$]*)/;
 
 
 // MAIN //
 
 /**
-* Adds package export to scope based on TypeScript declarations.
+* Adds a package export to the scope based on TypeScript declarations.
 *
+* @private
 * @param {Object} scope - VM scope object to add the package export to
 * @param {*} pkg - package export value to be added to scope
 * @param {string} sourceText - TypeScript declaration source text to parse for identifier names
 */
 function addPackageToScope( scope, pkg, sourceText ) {
 	var interfaceMatch;
 	var namespaceMatch;
-	var funcMatch;
+	var pkgType;
+	var match;
 
-	if ( typeof pkg === 'function' ) {
-		// Try to match declare function pattern (handles generics with <):
-		funcMatch = sourceText.match( RE_DECLARE_FUNCTION );
-		if ( !funcMatch ) {
-			// Try to match declare var pattern:
-			funcMatch = sourceText.match( RE_DECLARE_VAR );
-		}
-		if ( !funcMatch ) {
-			// Try to match declare class pattern (for constructor functions):
-			funcMatch = sourceText.match( RE_DECLARE_CLASS );
-		}
-		if ( funcMatch ) {
-			scope[ funcMatch[1] ] = pkg;
+	pkgType = typeof pkg;
+	if ( pkgType === 'function' ) {
+		match = sourceText.match( RE_DECLARE_FUNCTION ) ||
+			sourceText.match( RE_DECLARE_VAR ) ||
+			sourceText.match( RE_DECLARE_CLASS );
+		if ( match ) {
+			scope[ match[1] ] = pkg;
 		}
-		// Also check for declare var with interface pattern (e.g., declare var ctor: Int32Vector):
 		interfaceMatch = sourceText.match( RE_DECLARE_VAR_INTERFACE );
 		if ( interfaceMatch ) {
-			// Make the function available under both the variable name and the interface name:
+			// Make the function available under both the variable and interface names:
 			scope[ interfaceMatch[1] ] = pkg; // e.g., ctor
 			scope[ interfaceMatch[2] ] = pkg; // e.g., Int32Vector
 		}
-	} else if ( typeof pkg === 'object' && pkg !== null ) {
-		// Handle namespace objects and other object interfaces:
-		namespaceMatch = sourceText.match( RE_DECLARE_VAR_NAMESPACE );
-		if ( namespaceMatch ) {
-			scope[ namespaceMatch[1] ] = pkg;
-		}
-		// Also check for const declarations (e.g., Complex64/Complex128 constants):
-		funcMatch = sourceText.match( RE_DECLARE_CONST );
-		if ( funcMatch ) {
-			scope[ funcMatch[1] ] = pkg;
-		}
 	} else {
-		// Try to match declare const pattern:
-		funcMatch = sourceText.match( RE_DECLARE_CONST );
-		if ( funcMatch ) {
-			scope[ funcMatch[1] ] = pkg;
+		if ( pkgType === 'object' && pkg !== null ) {
+			namespaceMatch = sourceText.match( RE_DECLARE_VAR_INTERFACE );
+			if ( namespaceMatch ) {
+				scope[ namespaceMatch[1] ] = pkg;
+			}
+		}
+		match = sourceText.match( RE_DECLARE_CONST );
+		if ( match ) {
+			scope[ match[1] ] = pkg;
 		}
 	}
 }

lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-doctest/lib/create_vm_scope.js

@@ -34,8 +34,8 @@ var windowShim = require( './window.js' );
 *
 * @private
 * @param {*} data - data to be logged
-* @param {...*} args - substitution values
-* @returns {*} return value
+* @param {...*} [args] - substitution values
+* @returns {*} formatted string if first argument is string, otherwise first argument
 */
 function log( data ) {
 	if ( isString( data ) ) {
@@ -50,6 +50,7 @@ function log( data ) {
 /**
 * Creates a VM execution scope with necessary globals.
 *
+* @private
 * @param {string} dir - directory path
 * @param {string} filename - file name
 * @returns {Object} VM scope object